From 60a866685006bae0c3db20e4bae31887eb452ff1 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Tue, 26 Jun 2018 06:49:08 -0300 Subject: gpio.h: fix location of gpio legacy documentation The location of this doc file was moved. Change its reference accordingly. Fixes: 7ee2c13080c9 ("Documentation: gpio: Move legacy documentation to driver-api") Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- include/linux/gpio.h | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'include/linux') diff --git a/include/linux/gpio.h b/include/linux/gpio.h index 91ed23468530..39745b8bdd65 100644 --- a/include/linux/gpio.h +++ b/include/linux/gpio.h @@ -14,7 +14,7 @@ #include -/* see Documentation/gpio/gpio-legacy.txt */ +/* see Documentation/driver-api/gpio/legacy.rst */ /* make these flag values available regardless of GPIO kconfig options */ #define GPIOF_DIR_OUT (0 << 0) -- cgit v1.2.3 From 0e3fd810c4f41dbd63fb7caddc11684959176727 Mon Sep 17 00:00:00 2001 From: Arnd Bergmann Date: Tue, 10 Jul 2018 16:46:41 +0200 Subject: Documentation: document ktime_get_*() APIs As Dave Chinner points out, we don't have a proper documentation for the ktime_get() family of interfaces, making it rather unclear which of the over 30 (!) interfaces one should actually use in a driver or elsewhere in the kernel. I wrote up an explanation from how I personally see the interfaces, documenting what each of the functions do and hopefully making it a bit clearer which should be used where. This is the first time I tried writing .rst format documentation, so in addition to any mistakes in the content, I probably also introduce nonstandard formatting ;-) I first tried to add an extra section to Documentation/timers/timekeeping.txt, but this is currently not included in the generated API, and it seems useful to have the API docs as part of what gets generated in https://www.kernel.org/doc/html/latest/core-api/index.html#core-utilities instead, so I started a new file there. I also considered adding the documentation inline in the include/linux/timekeeping.h header, but couldn't figure out how to do that in a way that would result both in helpful inline comments as well as readable html output, so I settled for the latter, with a small note pointing to it from the header. Cc: Dave Chinner Cc: John Stultz Cc: Thomas Gleixner Cc: Stephen Boyd Tested-by: Randy Dunlap Reviewed-by: Randy Dunlap Reviewed-by: Linus Walleij Signed-off-by: Arnd Bergmann Signed-off-by: Jonathan Corbet --- include/linux/timekeeping.h | 15 +++++++++++++++ 1 file changed, 15 insertions(+) (limited to 'include/linux') diff --git a/include/linux/timekeeping.h b/include/linux/timekeeping.h index 86bc2026efce..947b1b8d2d01 100644 --- a/include/linux/timekeeping.h +++ b/include/linux/timekeeping.h @@ -20,6 +20,21 @@ extern int do_settimeofday64(const struct timespec64 *ts); extern int do_sys_settimeofday64(const struct timespec64 *tv, const struct timezone *tz); +/* + * ktime_get() family: read the current time in a multitude of ways, + * + * The default time reference is CLOCK_MONOTONIC, starting at + * boot time but not counting the time spent in suspend. + * For other references, use the functions with "real", "clocktai", + * "boottime" and "raw" suffixes. + * + * To get the time in a different format, use the ones wit + * "ns", "ts64" and "seconds" suffix. + * + * See Documentation/core-api/timekeeping.rst for more details. + */ + + /* * timespec64 based interfaces */ -- cgit v1.2.3 From a83c0ea79d8b5705d09a39c73224332f9170a903 Mon Sep 17 00:00:00 2001 From: Mike Rapoport Date: Sat, 30 Jun 2018 17:54:59 +0300 Subject: docs/mm: bootmem: add kernel-doc description of 'struct bootmem_data' Signed-off-by: Mike Rapoport Signed-off-by: Jonathan Corbet --- include/linux/bootmem.h | 17 ++++++++++++++--- 1 file changed, 14 insertions(+), 3 deletions(-) (limited to 'include/linux') diff --git a/include/linux/bootmem.h b/include/linux/bootmem.h index 7942a96b1a9d..42515195d7d8 100644 --- a/include/linux/bootmem.h +++ b/include/linux/bootmem.h @@ -27,9 +27,20 @@ extern unsigned long max_pfn; extern unsigned long long max_possible_pfn; #ifndef CONFIG_NO_BOOTMEM -/* - * node_bootmem_map is a map pointer - the bits represent all physical - * memory pages (including holes) on the node. +/** + * struct bootmem_data - per-node information used by the bootmem allocator + * @node_min_pfn: the starting physical address of the node's memory + * @node_low_pfn: the end physical address of the directly addressable memory + * @node_bootmem_map: is a bitmap pointer - the bits represent all physical + * memory pages (including holes) on the node. + * @last_end_off: the offset within the page of the end of the last allocation; + * if 0, the page used is full + * @hint_idx: the PFN of the page used with the last allocation; + * together with using this with the @last_end_offset field, + * a test can be made to see if allocations can be merged + * with the page used for the last allocation rather than + * using up a full new page. + * @list: list entry in the linked list ordered by the memory addresses */ typedef struct bootmem_data { unsigned long node_min_pfn; -- cgit v1.2.3 From e1720fee27246dfb84f7c433e35367170a2d4436 Mon Sep 17 00:00:00 2001 From: Mike Rapoport Date: Sat, 30 Jun 2018 17:55:01 +0300 Subject: mm/memblock: add a name for memblock flags enumeration Since kernel-doc does not like anonymous enums the name is required for adding documentation. While on it, I've also updated all the function declarations to use 'enum memblock_flags' instead of unsigned long. Signed-off-by: Mike Rapoport Signed-off-by: Jonathan Corbet --- include/linux/memblock.h | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) (limited to 'include/linux') diff --git a/include/linux/memblock.h b/include/linux/memblock.h index ca59883c8364..8b8fbceffd4d 100644 --- a/include/linux/memblock.h +++ b/include/linux/memblock.h @@ -21,7 +21,7 @@ #define INIT_PHYSMEM_REGIONS 4 /* Definition of memblock flags. */ -enum { +enum memblock_flags { MEMBLOCK_NONE = 0x0, /* No special request */ MEMBLOCK_HOTPLUG = 0x1, /* hotpluggable region */ MEMBLOCK_MIRROR = 0x2, /* mirrored region */ @@ -31,7 +31,7 @@ enum { struct memblock_region { phys_addr_t base; phys_addr_t size; - unsigned long flags; + enum memblock_flags flags; #ifdef CONFIG_HAVE_MEMBLOCK_NODE_MAP int nid; #endif @@ -72,7 +72,7 @@ void memblock_discard(void); phys_addr_t memblock_find_in_range_node(phys_addr_t size, phys_addr_t align, phys_addr_t start, phys_addr_t end, - int nid, ulong flags); + int nid, enum memblock_flags flags); phys_addr_t memblock_find_in_range(phys_addr_t start, phys_addr_t end, phys_addr_t size, phys_addr_t align); void memblock_allow_resize(void); @@ -89,19 +89,19 @@ int memblock_clear_hotplug(phys_addr_t base, phys_addr_t size); int memblock_mark_mirror(phys_addr_t base, phys_addr_t size); int memblock_mark_nomap(phys_addr_t base, phys_addr_t size); int memblock_clear_nomap(phys_addr_t base, phys_addr_t size); -ulong choose_memblock_flags(void); +enum memblock_flags choose_memblock_flags(void); /* Low level functions */ int memblock_add_range(struct memblock_type *type, phys_addr_t base, phys_addr_t size, - int nid, unsigned long flags); + int nid, enum memblock_flags flags); -void __next_mem_range(u64 *idx, int nid, ulong flags, +void __next_mem_range(u64 *idx, int nid, enum memblock_flags flags, struct memblock_type *type_a, struct memblock_type *type_b, phys_addr_t *out_start, phys_addr_t *out_end, int *out_nid); -void __next_mem_range_rev(u64 *idx, int nid, ulong flags, +void __next_mem_range_rev(u64 *idx, int nid, enum memblock_flags flags, struct memblock_type *type_a, struct memblock_type *type_b, phys_addr_t *out_start, phys_addr_t *out_end, int *out_nid); @@ -253,13 +253,13 @@ void __next_mem_pfn_range(int *idx, int nid, unsigned long *out_start_pfn, NUMA_NO_NODE, MEMBLOCK_NONE, p_start, p_end, NULL) static inline void memblock_set_region_flags(struct memblock_region *r, - unsigned long flags) + enum memblock_flags flags) { r->flags |= flags; } static inline void memblock_clear_region_flags(struct memblock_region *r, - unsigned long flags) + enum memblock_flags flags) { r->flags &= ~flags; } @@ -317,10 +317,10 @@ static inline bool memblock_bottom_up(void) phys_addr_t __init memblock_alloc_range(phys_addr_t size, phys_addr_t align, phys_addr_t start, phys_addr_t end, - ulong flags); + enum memblock_flags flags); phys_addr_t memblock_alloc_base_nid(phys_addr_t size, phys_addr_t align, phys_addr_t max_addr, - int nid, ulong flags); + int nid, enum memblock_flags flags); phys_addr_t memblock_alloc_base(phys_addr_t size, phys_addr_t align, phys_addr_t max_addr); phys_addr_t __memblock_alloc_base(phys_addr_t size, phys_addr_t align, -- cgit v1.2.3 From 47cec4432ab06c4ba90c241b142a016f878ac6da Mon Sep 17 00:00:00 2001 From: Mike Rapoport Date: Sat, 30 Jun 2018 17:55:02 +0300 Subject: docs/mm: memblock: update kernel-doc comments * make memblock_discard description kernel-doc compatible * add brief description for memblock_setclr_flag and describe its parameters * fixup return value descriptions Signed-off-by: Mike Rapoport Signed-off-by: Jonathan Corbet --- include/linux/memblock.h | 17 ++++++++++++----- 1 file changed, 12 insertions(+), 5 deletions(-) (limited to 'include/linux') diff --git a/include/linux/memblock.h b/include/linux/memblock.h index 8b8fbceffd4d..63704c64583a 100644 --- a/include/linux/memblock.h +++ b/include/linux/memblock.h @@ -239,7 +239,6 @@ void __next_mem_pfn_range(int *idx, int nid, unsigned long *out_start_pfn, /** * for_each_resv_unavail_range - iterate through reserved and unavailable memory * @i: u64 used as loop variable - * @flags: pick from blocks based on memory attributes * @p_start: ptr to phys_addr_t for start address of the range, can be %NULL * @p_end: ptr to phys_addr_t for end address of the range, can be %NULL * @@ -367,8 +366,10 @@ phys_addr_t memblock_get_current_limit(void); */ /** - * memblock_region_memory_base_pfn - Return the lowest pfn intersecting with the memory region + * memblock_region_memory_base_pfn - get the lowest pfn of the memory region * @reg: memblock_region structure + * + * Return: the lowest pfn intersecting with the memory region */ static inline unsigned long memblock_region_memory_base_pfn(const struct memblock_region *reg) { @@ -376,8 +377,10 @@ static inline unsigned long memblock_region_memory_base_pfn(const struct membloc } /** - * memblock_region_memory_end_pfn - Return the end_pfn this region + * memblock_region_memory_end_pfn - get the end pfn of the memory region * @reg: memblock_region structure + * + * Return: the end_pfn of the reserved region */ static inline unsigned long memblock_region_memory_end_pfn(const struct memblock_region *reg) { @@ -385,8 +388,10 @@ static inline unsigned long memblock_region_memory_end_pfn(const struct memblock } /** - * memblock_region_reserved_base_pfn - Return the lowest pfn intersecting with the reserved region + * memblock_region_reserved_base_pfn - get the lowest pfn of the reserved region * @reg: memblock_region structure + * + * Return: the lowest pfn intersecting with the reserved region */ static inline unsigned long memblock_region_reserved_base_pfn(const struct memblock_region *reg) { @@ -394,8 +399,10 @@ static inline unsigned long memblock_region_reserved_base_pfn(const struct membl } /** - * memblock_region_reserved_end_pfn - Return the end_pfn this region + * memblock_region_reserved_end_pfn - get the end pfn of the reserved region * @reg: memblock_region structure + * + * Return: the end_pfn of the reserved region */ static inline unsigned long memblock_region_reserved_end_pfn(const struct memblock_region *reg) { -- cgit v1.2.3 From 9a0de1bfe191220cb0437865261ab2f95cbb13ef Mon Sep 17 00:00:00 2001 From: Mike Rapoport Date: Sat, 30 Jun 2018 17:55:04 +0300 Subject: docs/mm: memblock: add kernel-doc description for memblock types Signed-off-by: Mike Rapoport Signed-off-by: Jonathan Corbet --- include/linux/memblock.h | 37 +++++++++++++++++++++++++++++++++---- 1 file changed, 33 insertions(+), 4 deletions(-) (limited to 'include/linux') diff --git a/include/linux/memblock.h b/include/linux/memblock.h index 63704c64583a..516920549378 100644 --- a/include/linux/memblock.h +++ b/include/linux/memblock.h @@ -20,7 +20,13 @@ #define INIT_MEMBLOCK_REGIONS 128 #define INIT_PHYSMEM_REGIONS 4 -/* Definition of memblock flags. */ +/** + * enum memblock_flags - definition of memory region attributes + * @MEMBLOCK_NONE: no special request + * @MEMBLOCK_HOTPLUG: hotpluggable region + * @MEMBLOCK_MIRROR: mirrored region + * @MEMBLOCK_NOMAP: don't add to kernel direct mapping + */ enum memblock_flags { MEMBLOCK_NONE = 0x0, /* No special request */ MEMBLOCK_HOTPLUG = 0x1, /* hotpluggable region */ @@ -28,6 +34,13 @@ enum memblock_flags { MEMBLOCK_NOMAP = 0x4, /* don't add to kernel direct mapping */ }; +/** + * struct memblock_region - represents a memory region + * @base: physical address of the region + * @size: size of the region + * @flags: memory region attributes + * @nid: NUMA node id + */ struct memblock_region { phys_addr_t base; phys_addr_t size; @@ -37,14 +50,30 @@ struct memblock_region { #endif }; +/** + * struct memblock_type - collection of memory regions of certain type + * @cnt: number of regions + * @max: size of the allocated array + * @total_size: size of all regions + * @regions: array of regions + * @name: the memory type symbolic name + */ struct memblock_type { - unsigned long cnt; /* number of regions */ - unsigned long max; /* size of the allocated array */ - phys_addr_t total_size; /* size of all regions */ + unsigned long cnt; + unsigned long max; + phys_addr_t total_size; struct memblock_region *regions; char *name; }; +/** + * struct memblock - memblock allocator metadata + * @bottom_up: is bottom up direction? + * @current_limit: physical address of the current allocation limit + * @memory: usabe memory regions + * @reserved: reserved memory regions + * @physmem: all physical memory + */ struct memblock { bool bottom_up; /* is bottom up direction? */ phys_addr_t current_limit; -- cgit v1.2.3