From 7b4ff1adb57ad96d8f12a05d8c661a3d8c4d2be1 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Thu, 11 May 2017 10:17:45 -0300 Subject: mutex, futex: adjust kernel-doc markups to generate ReST There are a few issues on some kernel-doc markups that was causing troubles with kernel-doc output on ReST format: ./kernel/futex.c:492: WARNING: Inline emphasis start-string without end-string. ./kernel/futex.c:1264: WARNING: Block quote ends without a blank line; unexpected unindent. ./kernel/futex.c:1721: WARNING: Block quote ends without a blank line; unexpected unindent. ./kernel/futex.c:2338: WARNING: Block quote ends without a blank line; unexpected unindent. ./kernel/futex.c:2426: WARNING: Block quote ends without a blank line; unexpected unindent. ./kernel/futex.c:2899: WARNING: Block quote ends without a blank line; unexpected unindent. ./kernel/futex.c:2972: WARNING: Block quote ends without a blank line; unexpected unindent. Fix them. No functional changes. Acked-by: Darren Hart (VMware) Signed-off-by: Mauro Carvalho Chehab --- include/linux/mutex.h | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'include/linux') diff --git a/include/linux/mutex.h b/include/linux/mutex.h index 1127fe31645d..ffcba1f337da 100644 --- a/include/linux/mutex.h +++ b/include/linux/mutex.h @@ -214,9 +214,9 @@ enum mutex_trylock_recursive_enum { * raisins, and once those are gone this will be removed. * * Returns: - * MUTEX_TRYLOCK_FAILED - trylock failed, - * MUTEX_TRYLOCK_SUCCESS - lock acquired, - * MUTEX_TRYLOCK_RECURSIVE - we already owned the lock. + * - MUTEX_TRYLOCK_FAILED - trylock failed, + * - MUTEX_TRYLOCK_SUCCESS - lock acquired, + * - MUTEX_TRYLOCK_RECURSIVE - we already owned the lock. */ static inline /* __deprecated */ __must_check enum mutex_trylock_recursive_enum mutex_trylock_recursive(struct mutex *lock) -- cgit v1.2.3 From 771b00a84be46d10e3f74af2d86d226302c907c5 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Fri, 12 May 2017 09:19:29 -0300 Subject: net: skbuff.h: properly escape a macro name on kernel-doc The "%" escape code of kernel-doc only handle letters. It doesn't handle special chars. So, use the ``literal`` notation. That fixes this warning: ./include/linux/skbuff.h:2695: WARNING: Inline literal start-string without end-string. No functional changes. Signed-off-by: Mauro Carvalho Chehab --- include/linux/skbuff.h | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'include/linux') diff --git a/include/linux/skbuff.h b/include/linux/skbuff.h index a098d95b3d84..25b1659c832a 100644 --- a/include/linux/skbuff.h +++ b/include/linux/skbuff.h @@ -2691,7 +2691,7 @@ bool skb_page_frag_refill(unsigned int sz, struct page_frag *pfrag, gfp_t prio); * @offset: the offset within the fragment (starting at the * fragment's own offset) * @size: the number of bytes to map - * @dir: the direction of the mapping (%PCI_DMA_*) + * @dir: the direction of the mapping (``PCI_DMA_*``) * * Maps the page associated with @frag to @device. */ -- cgit v1.2.3 From d651983dde41a854e25664d98cbfc999d55785a8 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Fri, 12 May 2017 09:35:46 -0300 Subject: net: fix some identation issues at kernel-doc markups Sphinx is very pedantic with regards to identation and escape sequences: ./include/net/sock.h:1967: ERROR: Unexpected indentation. ./include/net/sock.h:1969: ERROR: Unexpected indentation. ./include/net/sock.h:1970: WARNING: Block quote ends without a blank line; unexpected unindent. ./include/net/sock.h:1971: WARNING: Block quote ends without a blank line; unexpected unindent. ./include/net/sock.h:2268: WARNING: Inline emphasis start-string without end-string. ./net/core/sock.c:2686: ERROR: Unexpected indentation. ./net/core/sock.c:2687: WARNING: Block quote ends without a blank line; unexpected unindent. ./net/core/datagram.c:182: WARNING: Inline emphasis start-string without end-string. ./include/linux/netdevice.h:1444: ERROR: Unexpected indentation. ./drivers/net/phy/phy.c:381: ERROR: Unexpected indentation. ./drivers/net/phy/phy.c:382: WARNING: Block quote ends without a blank line; unexpected unindent. - Fix spacing where needed; - Properly escape constants; - Use a literal block for a race description. No functional changes. Signed-off-by: Mauro Carvalho Chehab --- include/linux/netdevice.h | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) (limited to 'include/linux') diff --git a/include/linux/netdevice.h b/include/linux/netdevice.h index 9c23bd2efb56..56d54b6fac45 100644 --- a/include/linux/netdevice.h +++ b/include/linux/netdevice.h @@ -1433,13 +1433,14 @@ enum netdev_priv_flags { /** * struct net_device - The DEVICE structure. - * Actually, this whole structure is a big mistake. It mixes I/O - * data with strictly "high-level" data, and it has to know about - * almost every data structure used in the INET module. + * + * Actually, this whole structure is a big mistake. It mixes I/O + * data with strictly "high-level" data, and it has to know about + * almost every data structure used in the INET module. * * @name: This is the first field of the "visible" part of this structure * (i.e. as seen by users in the "Space.c" file). It is the name - * of the interface. + * of the interface. * * @name_hlist: Device name hash chain, please keep it close to name[] * @ifalias: SNMP alias -- cgit v1.2.3 From b6f6c29454d236e85f2912cb0f9366825ca1b0be Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Sat, 13 May 2017 07:40:36 -0300 Subject: mtd: adjust kernel-docs to avoid Sphinx/kerneldoc warnings ./drivers/mtd/nand/nand_bbt.c:1: warning: no structured comments found ./include/linux/mtd/nand.h:785: ERROR: Unexpected indentation. ./drivers/mtd/nand/nand_base.c:449: WARNING: Definition list ends without a blank line; unexpected unindent. ./drivers/mtd/nand/nand_base.c:1161: ERROR: Unexpected indentation. ./drivers/mtd/nand/nand_base.c:1162: WARNING: Block quote ends without a blank line; unexpected unindent. Signed-off-by: Mauro Carvalho Chehab --- include/linux/mtd/nand.h | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'include/linux') diff --git a/include/linux/mtd/nand.h b/include/linux/mtd/nand.h index 9591e0fbe5bd..3d5b20379ba3 100644 --- a/include/linux/mtd/nand.h +++ b/include/linux/mtd/nand.h @@ -779,7 +779,7 @@ nand_get_sdr_timings(const struct nand_data_interface *conf) * Minimum amount of bit errors per @ecc_step_ds guaranteed * to be correctable. If unknown, set to zero. * @ecc_step_ds: [INTERN] ECC step required by the @ecc_strength_ds, - * also from the datasheet. It is the recommended ECC step + * also from the datasheet. It is the recommended ECC step * size, if known; if unknown, set to zero. * @onfi_timing_mode_default: [INTERN] default ONFI timing mode. This field is * set to the actually used ONFI mode if the chip is -- cgit v1.2.3 From 19285f3c4669c8b0cea8fb6c452c83db9e6386be Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Sun, 14 May 2017 11:52:56 -0300 Subject: ata: update references for libata documentation The libata documentation is now using ReST. Update references to it to point to the new place. Signed-off-by: Mauro Carvalho Chehab --- include/linux/ata.h | 2 +- include/linux/libata.h | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) (limited to 'include/linux') diff --git a/include/linux/ata.h b/include/linux/ata.h index ad7d9ee89ff0..73fe18edfdaf 100644 --- a/include/linux/ata.h +++ b/include/linux/ata.h @@ -20,7 +20,7 @@ * * * libata documentation is available via 'make {ps|pdf}docs', - * as Documentation/DocBook/libata.* + * as Documentation/driver-api/libata.rst * * Hardware documentation available from http://www.t13.org/ * diff --git a/include/linux/libata.h b/include/linux/libata.h index c9a69fc8821e..9e6633235ad7 100644 --- a/include/linux/libata.h +++ b/include/linux/libata.h @@ -19,7 +19,7 @@ * * * libata documentation is available via 'make {ps|pdf}docs', - * as Documentation/DocBook/libata.* + * as Documentation/driver-api/libata.rst * */ -- cgit v1.2.3 From e1b4fc7add72f565d9c35066d85108346e01d3e9 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Sun, 14 May 2017 12:04:55 -0300 Subject: fs: update location of filesystems documentation The filesystem documentation was moved from DocBook to Documentation/filesystems/. Update it at the sources. Signed-off-by: Mauro Carvalho Chehab --- include/linux/debugfs.h | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'include/linux') diff --git a/include/linux/debugfs.h b/include/linux/debugfs.h index 9174b0d28582..aa86e6d8c1aa 100644 --- a/include/linux/debugfs.h +++ b/include/linux/debugfs.h @@ -9,7 +9,7 @@ * 2 as published by the Free Software Foundation. * * debugfs is for people to use instead of /proc or /sys. - * See Documentation/DocBook/filesystems for more details. + * See Documentation/filesystems/ for more details. */ #ifndef _DEBUGFS_H_ -- cgit v1.2.3 From af777cd1b83e95138e7285fde87c795ef0ae7c4d Mon Sep 17 00:00:00 2001 From: Kees Cook Date: Sat, 13 May 2017 04:51:40 -0700 Subject: doc: ReSTify credentials.txt This updates the credentials API documentation to ReST markup and moves it under the security subsection of kernel API documentation. Cc: David Howells Signed-off-by: Kees Cook Signed-off-by: Jonathan Corbet --- include/linux/cred.h | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'include/linux') diff --git a/include/linux/cred.h b/include/linux/cred.h index b03e7d049a64..c728d515e5e2 100644 --- a/include/linux/cred.h +++ b/include/linux/cred.h @@ -1,4 +1,4 @@ -/* Credentials management - see Documentation/security/credentials.txt +/* Credentials management - see Documentation/security/credentials.rst * * Copyright (C) 2008 Red Hat, Inc. All Rights Reserved. * Written by David Howells (dhowells@redhat.com) -- cgit v1.2.3 From f00f85a8b2e0ac344f8dbaa3441b31bc283ce400 Mon Sep 17 00:00:00 2001 From: Kees Cook Date: Sat, 13 May 2017 04:51:42 -0700 Subject: doc: security: minor cleanups to build kernel-doc These fixes were needed to parse lsm_hooks.h kernel-doc. More work is needed, but this is the first step. Acked-by: James Morris Acked-by: Casey Schaufler Signed-off-by: Kees Cook Signed-off-by: Jonathan Corbet --- include/linux/lsm_hooks.h | 25 ++++++++++++------------- 1 file changed, 12 insertions(+), 13 deletions(-) (limited to 'include/linux') diff --git a/include/linux/lsm_hooks.h b/include/linux/lsm_hooks.h index 080f34e66017..a1eeaf603d2f 100644 --- a/include/linux/lsm_hooks.h +++ b/include/linux/lsm_hooks.h @@ -29,6 +29,8 @@ #include /** + * union security_list_options - Linux Security Module hook function list + * * Security hooks for program execution operations. * * @bprm_set_creds: @@ -193,8 +195,8 @@ * @value will be set to the allocated attribute value. * @len will be set to the length of the value. * Returns 0 if @name and @value have been successfully set, - * -EOPNOTSUPP if no security attribute is needed, or - * -ENOMEM on memory allocation failure. + * -EOPNOTSUPP if no security attribute is needed, or + * -ENOMEM on memory allocation failure. * @inode_create: * Check permission to create a regular file. * @dir contains inode structure of the parent of the new file. @@ -510,8 +512,7 @@ * process @tsk. Note that this hook is sometimes called from interrupt. * Note that the fown_struct, @fown, is never outside the context of a * struct file, so the file structure (and associated security information) - * can always be obtained: - * container_of(fown, struct file, f_owner) + * can always be obtained: container_of(fown, struct file, f_owner) * @tsk contains the structure of task receiving signal. * @fown contains the file owner information. * @sig is the signal that will be sent. When 0, kernel sends SIGIO. @@ -521,7 +522,7 @@ * to receive an open file descriptor via socket IPC. * @file contains the file structure being received. * Return 0 if permission is granted. - * @file_open + * @file_open: * Save open-time permission checking state for later use upon * file_permission, and recheck access if anything has changed * since inode_permission. @@ -1143,7 +1144,7 @@ * @sma contains the semaphore structure. May be NULL. * @cmd contains the operation to be performed. * Return 0 if permission is granted. - * @sem_semop + * @sem_semop: * Check permissions before performing operations on members of the * semaphore set @sma. If the @alter flag is nonzero, the semaphore set * may be modified. @@ -1153,20 +1154,20 @@ * @alter contains the flag indicating whether changes are to be made. * Return 0 if permission is granted. * - * @binder_set_context_mgr + * @binder_set_context_mgr: * Check whether @mgr is allowed to be the binder context manager. * @mgr contains the task_struct for the task being registered. * Return 0 if permission is granted. - * @binder_transaction + * @binder_transaction: * Check whether @from is allowed to invoke a binder transaction call * to @to. * @from contains the task_struct for the sending task. * @to contains the task_struct for the receiving task. - * @binder_transfer_binder + * @binder_transfer_binder: * Check whether @from is allowed to transfer a binder reference to @to. * @from contains the task_struct for the sending task. * @to contains the task_struct for the receiving task. - * @binder_transfer_file + * @binder_transfer_file: * Check whether @from is allowed to transfer @file to @to. * @from contains the task_struct for the sending task. * @file contains the struct file being transferred. @@ -1214,7 +1215,7 @@ * @cred contains the credentials to use. * @ns contains the user namespace we want the capability in * @cap contains the capability . - * @audit: Whether to write an audit message or not + * @audit contains whether to write an audit message or not * Return 0 if the capability is granted for @tsk. * @syslog: * Check permission before accessing the kernel message ring or changing @@ -1336,9 +1337,7 @@ * @inode we wish to get the security context of. * @ctx is a pointer in which to place the allocated security context. * @ctxlen points to the place to put the length of @ctx. - * This is the main security structure. */ - union security_list_options { int (*binder_set_context_mgr)(struct task_struct *mgr); int (*binder_transaction)(struct task_struct *from, -- cgit v1.2.3 From b68101a1e8f0263dbc7b8375d2a7c57c6216fb76 Mon Sep 17 00:00:00 2001 From: Kees Cook Date: Sat, 13 May 2017 04:51:50 -0700 Subject: doc: ReSTify keys.txt This creates a new section in the security development index for kernel keys, and adjusts for ReST markup. Cc: David Howells Signed-off-by: Kees Cook Signed-off-by: Jonathan Corbet --- include/linux/key.h | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'include/linux') diff --git a/include/linux/key.h b/include/linux/key.h index 0c9b93b0d1f7..24dfe6c1f8cb 100644 --- a/include/linux/key.h +++ b/include/linux/key.h @@ -9,7 +9,7 @@ * 2 of the License, or (at your option) any later version. * * - * See Documentation/security/keys.txt for information on keys/keyrings. + * See Documentation/security/keys/core.rst for information on keys/keyrings. */ #ifndef _LINUX_KEY_H -- cgit v1.2.3