From b2e33536c010513e07e92ca914fcc11108d5eef5 Mon Sep 17 00:00:00 2001 From: sayli karnik Date: Thu, 30 Mar 2017 02:01:16 +0530 Subject: Documentation: Add flexible-arrays.rst to the documentation tree Add flexible-arrays.rst to Documentation/core-api. Add kernel-doc comments to allow referencing. Signed-off-by: sayli karnik Signed-off-by: Jonathan Corbet --- include/linux/flex_array.h | 67 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 67 insertions(+) (limited to 'include') diff --git a/include/linux/flex_array.h b/include/linux/flex_array.h index b6efb0c64408..11366b3ff0b4 100644 --- a/include/linux/flex_array.h +++ b/include/linux/flex_array.h @@ -61,16 +61,83 @@ struct flex_array { FLEX_ARRAY_ELEMENTS_PER_PART(__element_size)); \ } +/** + * flex_array_alloc() - Creates a flexible array. + * @element_size: individual object size. + * @total: maximum number of objects which can be stored. + * @flags: GFP flags + * + * Return: Returns an object of structure flex_array. + */ struct flex_array *flex_array_alloc(int element_size, unsigned int total, gfp_t flags); + +/** + * flex_array_prealloc() - Ensures that memory for the elements indexed in the + * range defined by start and nr_elements has been allocated. + * @fa: array to allocate memory to. + * @start: start address + * @nr_elements: number of elements to be allocated. + * @flags: GFP flags + * + */ int flex_array_prealloc(struct flex_array *fa, unsigned int start, unsigned int nr_elements, gfp_t flags); + +/** + * flex_array_free() - Removes all elements of a flexible array. + * @fa: array to be freed. + */ void flex_array_free(struct flex_array *fa); + +/** + * flex_array_free_parts() - Removes all elements of a flexible array, but + * leaves the array itself in place. + * @fa: array to be emptied. + */ void flex_array_free_parts(struct flex_array *fa); + +/** + * flex_array_put() - Stores data into a flexible array. + * @fa: array where element is to be stored. + * @element_nr: position to copy, must be less than the maximum specified when + * the array was created. + * @src: data source to be copied into the array. + * @flags: GFP flags + * + * Return: Returns zero on success, a negative error code otherwise. + */ int flex_array_put(struct flex_array *fa, unsigned int element_nr, void *src, gfp_t flags); + +/** + * flex_array_clear() - Clears an individual element in the array, sets the + * given element to FLEX_ARRAY_FREE. + * @element_nr: element position to clear. + * @fa: array to which element to be cleared belongs. + * + * Return: Returns zero on success, -EINVAL otherwise. + */ int flex_array_clear(struct flex_array *fa, unsigned int element_nr); + +/** + * flex_array_get() - Retrieves data into a flexible array. + * + * @element_nr: Element position to retrieve data from. + * @fa: array from which data is to be retrieved. + * + * Return: Returns a pointer to the data element, or NULL if that + * particular element has never been allocated. + */ void *flex_array_get(struct flex_array *fa, unsigned int element_nr); + +/** + * flex_array_shrink() - Reduces the allocated size of an array. + * @fa: array to shrink. + * + * Return: Returns number of pages of memory actually freed. + * + */ int flex_array_shrink(struct flex_array *fa); #define flex_array_put_ptr(fa, nr, src, gfp) \ -- cgit v1.2.3-71-gd317 From 0e056eb5530da802c07f080d6bbd43c50e799efd Mon Sep 17 00:00:00 2001 From: "mchehab@s-opensource.com" Date: Thu, 30 Mar 2017 17:11:36 -0300 Subject: kernel-api.rst: fix a series of errors when parsing C files ./lib/string.c:134: WARNING: Inline emphasis start-string without end-string. ./mm/filemap.c:522: WARNING: Inline interpreted text or phrase reference start-string without end-string. ./mm/filemap.c:1283: ERROR: Unexpected indentation. ./mm/filemap.c:3003: WARNING: Inline interpreted text or phrase reference start-string without end-string. ./mm/vmalloc.c:1544: WARNING: Inline emphasis start-string without end-string. ./mm/page_alloc.c:4245: ERROR: Unexpected indentation. ./ipc/util.c:676: ERROR: Unexpected indentation. ./drivers/pci/irq.c:35: WARNING: Block quote ends without a blank line; unexpected unindent. ./security/security.c:109: ERROR: Unexpected indentation. ./security/security.c:110: WARNING: Definition list ends without a blank line; unexpected unindent. ./block/genhd.c:275: WARNING: Inline strong start-string without end-string. ./block/genhd.c:283: WARNING: Inline strong start-string without end-string. ./include/linux/clk.h:134: WARNING: Inline emphasis start-string without end-string. ./include/linux/clk.h:134: WARNING: Inline emphasis start-string without end-string. ./ipc/util.c:477: ERROR: Unknown target name: "s". Signed-off-by: Mauro Carvalho Chehab Acked-by: Bjorn Helgaas Signed-off-by: Jonathan Corbet --- block/genhd.c | 7 ++++--- drivers/pci/irq.c | 2 +- include/linux/clk.h | 4 ++-- ipc/util.c | 12 +++++++----- lib/string.c | 2 +- mm/filemap.c | 18 ++++++++++-------- mm/page_alloc.c | 3 ++- mm/vmalloc.c | 2 +- security/security.c | 12 ++++++++---- 9 files changed, 36 insertions(+), 26 deletions(-) (limited to 'include') diff --git a/block/genhd.c b/block/genhd.c index b26a5ea115d0..a53bfd19a0ec 100644 --- a/block/genhd.c +++ b/block/genhd.c @@ -271,16 +271,17 @@ void blkdev_show(struct seq_file *seqf, off_t offset) /** * register_blkdev - register a new block device * - * @major: the requested major device number [1..255]. If @major=0, try to + * @major: the requested major device number [1..255]. If @major = 0, try to * allocate any unused major number. * @name: the name of the new block device as a zero terminated string * * The @name must be unique within the system. * - * The return value depends on the @major input parameter. + * The return value depends on the @major input parameter: + * * - if a major device number was requested in range [1..255] then the * function returns zero on success, or a negative error code - * - if any unused major number was requested with @major=0 parameter + * - if any unused major number was requested with @major = 0 parameter * then the return value is the allocated major number in range * [1..255] or a negative error code otherwise */ diff --git a/drivers/pci/irq.c b/drivers/pci/irq.c index 6684f153ab57..f9f2a0324ecc 100644 --- a/drivers/pci/irq.c +++ b/drivers/pci/irq.c @@ -31,7 +31,7 @@ static void pci_note_irq_problem(struct pci_dev *pdev, const char *reason) * driver). * * Returns: - * a suggestion for fixing it (although the driver is not required to + * a suggestion for fixing it (although the driver is not required to * act on this). */ enum pci_lost_interrupt_reason pci_lost_interrupt(struct pci_dev *pdev) diff --git a/include/linux/clk.h b/include/linux/clk.h index e9d36b3e49de..024cd07870d0 100644 --- a/include/linux/clk.h +++ b/include/linux/clk.h @@ -132,8 +132,8 @@ int clk_get_phase(struct clk *clk); * @q: clk compared against p * * Returns true if the two struct clk pointers both point to the same hardware - * clock node. Put differently, returns true if struct clk *p and struct clk *q - * share the same struct clk_core object. + * clock node. Put differently, returns true if @p and @q + * share the same &struct clk_core object. * * Returns false otherwise. Note that two NULL clks are treated as matching. */ diff --git a/ipc/util.c b/ipc/util.c index 798cad18dd87..3459a16a9df9 100644 --- a/ipc/util.c +++ b/ipc/util.c @@ -474,7 +474,7 @@ void ipc_rcu_free(struct rcu_head *head) * Check user, group, other permissions for access * to ipc resources. return 0 if allowed * - * @flag will most probably be 0 or S_...UGO from + * @flag will most probably be 0 or ``S_...UGO`` from */ int ipcperms(struct ipc_namespace *ns, struct kern_ipc_perm *ipcp, short flag) { @@ -672,10 +672,12 @@ int ipc_update_perm(struct ipc64_perm *in, struct kern_ipc_perm *out) * * This function does some common audit and permissions check for some IPC_XXX * cmd and is called from semctl_down, shmctl_down and msgctl_down. - * It must be called without any lock held and - * - retrieves the ipc with the given id in the given table. - * - performs some audit and permission check, depending on the given cmd - * - returns a pointer to the ipc object or otherwise, the corresponding error. + * It must be called without any lock held and: + * + * - retrieves the ipc with the given id in the given table. + * - performs some audit and permission check, depending on the given cmd + * - returns a pointer to the ipc object or otherwise, the corresponding + * error. * * Call holding the both the rwsem and the rcu read lock. */ diff --git a/lib/string.c b/lib/string.c index ed83562a53ae..b5c9a1168d3a 100644 --- a/lib/string.c +++ b/lib/string.c @@ -131,7 +131,7 @@ EXPORT_SYMBOL(strncpy); * @src: Where to copy the string from * @size: size of destination buffer * - * Compatible with *BSD: the result is always a valid + * Compatible with ``*BSD``: the result is always a valid * NUL-terminated string that fits in the buffer (unless, * of course, the buffer size is zero). It does not pad * out the result like strncpy() does. diff --git a/mm/filemap.c b/mm/filemap.c index 1694623a6289..c5808b7a5fb1 100644 --- a/mm/filemap.c +++ b/mm/filemap.c @@ -519,7 +519,7 @@ EXPORT_SYMBOL(filemap_write_and_wait); * * Write out and wait upon file offsets lstart->lend, inclusive. * - * Note that `lend' is inclusive (describes the last byte to be written) so + * Note that @lend is inclusive (describes the last byte to be written) so * that this function can be used to write to the very end-of-file (end = -1). */ int filemap_write_and_wait_range(struct address_space *mapping, @@ -1277,12 +1277,14 @@ EXPORT_SYMBOL(find_lock_entry); * * PCG flags modify how the page is returned. * - * FGP_ACCESSED: the page will be marked accessed - * FGP_LOCK: Page is return locked - * FGP_CREAT: If page is not present then a new page is allocated using - * @gfp_mask and added to the page cache and the VM's LRU - * list. The page is returned locked and with an increased - * refcount. Otherwise, %NULL is returned. + * @fgp_flags can be: + * + * - FGP_ACCESSED: the page will be marked accessed + * - FGP_LOCK: Page is return locked + * - FGP_CREAT: If page is not present then a new page is allocated using + * @gfp_mask and added to the page cache and the VM's LRU + * list. The page is returned locked and with an increased + * refcount. Otherwise, NULL is returned. * * If FGP_LOCK or FGP_CREAT are specified then the function may sleep even * if the GFP flags specified for FGP_CREAT are atomic. @@ -3001,7 +3003,7 @@ EXPORT_SYMBOL(generic_file_write_iter); * @gfp_mask: memory allocation flags (and I/O mode) * * The address_space is to try to release any data against the page - * (presumably at page->private). If the release was successful, return `1'. + * (presumably at page->private). If the release was successful, return '1'. * Otherwise return zero. * * This may also be called if PG_fscache is set on a page, indicating that the diff --git a/mm/page_alloc.c b/mm/page_alloc.c index eaa64d2ffdc5..c1b68edaf106 100644 --- a/mm/page_alloc.c +++ b/mm/page_alloc.c @@ -4242,7 +4242,8 @@ EXPORT_SYMBOL(free_pages_exact); * nr_free_zone_pages() counts the number of counts pages which are beyond the * high watermark within all zones at or below a given zone index. For each * zone, the number of pages is calculated as: - * managed_pages - high_pages + * + * nr_free_zone_pages = managed_pages - high_pages */ static unsigned long nr_free_zone_pages(int offset) { diff --git a/mm/vmalloc.c b/mm/vmalloc.c index b4024d688f38..c24db06f15c4 100644 --- a/mm/vmalloc.c +++ b/mm/vmalloc.c @@ -1540,7 +1540,7 @@ void vfree_atomic(const void *addr) * have CONFIG_ARCH_HAVE_NMI_SAFE_CMPXCHG, but making the calling * conventions for vfree() arch-depenedent would be a really bad idea) * - * NOTE: assumes that the object at *addr has a size >= sizeof(llist_node) + * NOTE: assumes that the object at @addr has a size >= sizeof(llist_node) */ void vfree(const void *addr) { diff --git a/security/security.c b/security/security.c index d0e07f269b2d..23555c5504f6 100644 --- a/security/security.c +++ b/security/security.c @@ -103,10 +103,14 @@ static int lsm_append(char *new, char **result) * to avoid security registration races. This method may also be used * to check if your LSM is currently loaded during kernel initialization. * - * Return true if: - * -The passed LSM is the one chosen by user at boot time, - * -or the passed LSM is configured as the default and the user did not - * choose an alternate LSM at boot time. + * Returns: + * + * true if: + * + * - The passed LSM is the one chosen by user at boot time, + * - or the passed LSM is configured as the default and the user did not + * choose an alternate LSM at boot time. + * * Otherwise, return false. */ int __init security_module_enable(const char *module) -- cgit v1.2.3-71-gd317 From e0c34e900611a58c93adf463d096c5843eb1967a Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Wed, 5 Apr 2017 10:23:12 -0300 Subject: usb: get rid of some ReST doc build errors We need an space before a numbered list to avoid those warnings: ./drivers/usb/core/message.c:478: ERROR: Unexpected indentation. ./drivers/usb/core/message.c:479: WARNING: Block quote ends without a blank line; unexpected unindent. ./include/linux/usb/composite.h:455: ERROR: Unexpected indentation. ./include/linux/usb/composite.h:456: WARNING: Block quote ends without a blank line; unexpected unindent. Signed-off-by: Mauro Carvalho Chehab Acked-by: Greg Kroah-Hartman Signed-off-by: Jonathan Corbet --- drivers/usb/core/message.c | 1 + include/linux/usb/composite.h | 1 + 2 files changed, 2 insertions(+) (limited to 'include') diff --git a/drivers/usb/core/message.c b/drivers/usb/core/message.c index 2184ef40a82a..4c38ea41ae96 100644 --- a/drivers/usb/core/message.c +++ b/drivers/usb/core/message.c @@ -474,6 +474,7 @@ EXPORT_SYMBOL_GPL(usb_sg_init); * significantly improve USB throughput. * * There are three kinds of completion for this function. + * * (1) success, where io->status is zero. The number of io->bytes * transferred is as requested. * (2) error, where io->status is a negative errno value. The number diff --git a/include/linux/usb/composite.h b/include/linux/usb/composite.h index 4616a49a1c2e..30a063e98c19 100644 --- a/include/linux/usb/composite.h +++ b/include/linux/usb/composite.h @@ -451,6 +451,7 @@ static inline struct usb_composite_driver *to_cdriver( * sure doing that won't hurt too much. * * One notion for how to handle Wireless USB devices involves: + * * (a) a second gadget here, discovery mechanism TBD, but likely * needing separate "register/unregister WUSB gadget" calls; * (b) updates to usb_gadget to include flags "is it wireless", -- cgit v1.2.3-71-gd317 From 3e208a00cffd1358cecf79074e50b093212043c1 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Wed, 5 Apr 2017 10:23:13 -0300 Subject: usb: composite.h: fix two warnings when building docs By definition, we use /* private: */ tag when we won't be documenting a parameter. However, those two parameters are documented: ./include/linux/usb/composite.h:510: warning: Excess struct/union/enum/typedef member 'setup_pending' description in 'usb_composite_dev' ./include/linux/usb/composite.h:510: warning: Excess struct/union/enum/typedef member 'os_desc_pending' description in 'usb_composite_dev' So, we need to use /* public: */ to avoid a warning. Signed-off-by: Mauro Carvalho Chehab Acked-by: Greg Kroah-Hartman Signed-off-by: Jonathan Corbet --- include/linux/usb/composite.h | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) (limited to 'include') diff --git a/include/linux/usb/composite.h b/include/linux/usb/composite.h index 30a063e98c19..f665d2ceac20 100644 --- a/include/linux/usb/composite.h +++ b/include/linux/usb/composite.h @@ -504,8 +504,9 @@ struct usb_composite_dev { /* protects deactivations and delayed_status counts*/ spinlock_t lock; - unsigned setup_pending:1; - unsigned os_desc_pending:1; + /* public: */ + unsigned int setup_pending:1; + unsigned int os_desc_pending:1; }; extern int usb_string_id(struct usb_composite_dev *c); -- cgit v1.2.3-71-gd317 From 0cb300623e3bb460fd9853bbde2fd1973e3bbcd8 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Wed, 5 Apr 2017 10:23:14 -0300 Subject: usb: gadget.h: be consistent at kernel doc macros There's one value that use spaces instead of tabs to ident. That causes the following warning: ./include/linux/usb/gadget.h:193: ERROR: Unexpected indentation. Signed-off-by: Mauro Carvalho Chehab Acked-by: Greg Kroah-Hartman Signed-off-by: Jonathan Corbet --- include/linux/usb/gadget.h | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'include') diff --git a/include/linux/usb/gadget.h b/include/linux/usb/gadget.h index e4516e9ded0f..fbc22a39e7bc 100644 --- a/include/linux/usb/gadget.h +++ b/include/linux/usb/gadget.h @@ -188,7 +188,7 @@ struct usb_ep_caps { * @caps:The structure describing types and directions supported by endoint. * @maxpacket:The maximum packet size used on this endpoint. The initial * value can sometimes be reduced (hardware allowing), according to - * the endpoint descriptor used to configure the endpoint. + * the endpoint descriptor used to configure the endpoint. * @maxpacket_limit:The maximum packet size value which can be handled by this * endpoint. It's set once by UDC driver when endpoint is initialized, and * should not be changed. Should not be confused with maxpacket. -- cgit v1.2.3-71-gd317