The Cavium OCTEON executive and PCI code has 61 comments that begin
with '/**' but are missing the required kernel-doc name line (function
or union), so they are silently dropped from the generated
documentation. Add the missing name line to each, and add the missing
':' after "Returns" so the return documentation is parsed correctly.

Two file-header comments that are not kernel-doc are downgraded from
'/**' to '/*'.

No functional change.

Verified with 'scripts/kernel-doc -none', which reports zero warnings
for all touched files after this change.

Signed-off-by: hanzhijian <hanzhijian1991@gmail.com>
---
 .../executive/cvmx-boot-vector.c              |   4 +-
 .../executive/cvmx-helper-errata.c            |   8 +-
 .../executive/cvmx-helper-jtag.c              |  37 ++--
 .../executive/cvmx-helper-loop.c              |  16 +-
 .../cavium-octeon/executive/cvmx-helper-npi.c |  16 +-
 .../executive/cvmx-helper-sgmii.c             |  61 +++----
 .../cavium-octeon/executive/cvmx-helper-spi.c |  36 ++--
 .../executive/cvmx-helper-util.c              |  42 +++--
 .../cavium-octeon/executive/cvmx-helper.c     | 161 ++++++++++--------
 .../executive/cvmx-interrupt-rsl.c            |   7 +-
 .../cavium-octeon/executive/octeon-model.c    |  19 +--
 arch/mips/cavium-octeon/octeon-crypto.c       |  19 ++-
 arch/mips/pci/pci-octeon.c                    |  28 +--
 13 files changed, 239 insertions(+), 215 deletions(-)

diff --git a/arch/mips/cavium-octeon/executive/cvmx-boot-vector.c b/arch/mips/cavium-octeon/executive/cvmx-boot-vector.c
index 76446db66..b259c350e 100644
--- a/arch/mips/cavium-octeon/executive/cvmx-boot-vector.c
+++ b/arch/mips/cavium-octeon/executive/cvmx-boot-vector.c
@@ -153,8 +153,8 @@ static void cvmx_boot_vector_init(void *mem)
 }
 
 /**
- * Get a pointer to the per-core table of reset vector pointers
- *
+ * cvmx_boot_vector_get() - Get a pointer to the per-core table of reset
+ *	vector pointers
  */
 struct cvmx_boot_vector_element *cvmx_boot_vector_get(void)
 {
diff --git a/arch/mips/cavium-octeon/executive/cvmx-helper-errata.c b/arch/mips/cavium-octeon/executive/cvmx-helper-errata.c
index 4b26fedec..697b6e760 100644
--- a/arch/mips/cavium-octeon/executive/cvmx-helper-errata.c
+++ b/arch/mips/cavium-octeon/executive/cvmx-helper-errata.c
@@ -25,7 +25,7 @@
  * Contact Cavium Networks for more information
  ***********************license end**************************************/
 
-/**
+/*
  *
  * Fixes and workaround for Octeon chip errata. This file
  * contains functions called by cvmx-helper to workaround known
@@ -40,9 +40,9 @@
 #include <asm/octeon/cvmx-helper-jtag.h>
 
 /**
- * Due to errata G-720, the 2nd order CDR circuit on CN52XX pass
- * 1 doesn't work properly. The following code disables 2nd order
- * CDR for the specified QLM.
+ * __cvmx_helper_errata_qlm_disable_2nd_order_cdr() - Due to errata G-720, the
+ *	2nd order CDR circuit on CN52XX pass 1 doesn't work properly. The following
+ *	code disables 2nd order CDR for the specified QLM.
  *
  * @qlm:    QLM to disable 2nd order CDR for.
  */
diff --git a/arch/mips/cavium-octeon/executive/cvmx-helper-jtag.c b/arch/mips/cavium-octeon/executive/cvmx-helper-jtag.c
index 1fceb7fd2..4f1180b93 100644
--- a/arch/mips/cavium-octeon/executive/cvmx-helper-jtag.c
+++ b/arch/mips/cavium-octeon/executive/cvmx-helper-jtag.c
@@ -26,7 +26,7 @@
  * Contact Cavium Networks for more information
  ***********************license end**************************************/
 
-/**
+/*
  *
  * Helper utilities for qlm_jtag.
  *
@@ -37,11 +37,11 @@
 
 
 /**
- * Initialize the internal QLM JTAG logic to allow programming
- * of the JTAG chain by the cvmx_helper_qlm_jtag_*() functions.
- * These functions should only be used at the direction of Cavium
- * Networks. Programming incorrect values into the JTAG chain
- * can cause chip damage.
+ * cvmx_helper_qlm_jtag_init() - Initialize the internal QLM JTAG logic to
+ *	allow programming of the JTAG chain by the cvmx_helper_qlm_jtag_*()
+ *	functions. These functions should only be used at the direction of Cavium
+ *	Networks. Programming incorrect values into the JTAG chain can cause chip
+ *	damage.
  */
 void cvmx_helper_qlm_jtag_init(void)
 {
@@ -71,17 +71,17 @@ void cvmx_helper_qlm_jtag_init(void)
 }
 
 /**
- * Write up to 32bits into the QLM jtag chain. Bits are shifted
- * into the MSB and out the LSB, so you should shift in the low
- * order bits followed by the high order bits. The JTAG chain is
- * 4 * 268 bits long, or 1072.
+ * cvmx_helper_qlm_jtag_shift() - Write up to 32bits into the QLM jtag chain.
+ *	Bits are shifted into the MSB and out the LSB, so you should shift in the
+ *	low order bits followed by the high order bits. The JTAG chain is 4 * 268
+ *	bits long, or 1072.
  *
  * @qlm:    QLM to shift value into
  * @bits:   Number of bits to shift in (1-32).
  * @data:   Data to shift in. Bit 0 enters the chain first, followed by
  *		 bit 1, etc.
  *
- * Returns The low order bits of the JTAG chain that shifted out of the
+ * Returns: The low order bits of the JTAG chain that shifted out of the
  *	   circle.
  */
 uint32_t cvmx_helper_qlm_jtag_shift(int qlm, int bits, uint32_t data)
@@ -101,11 +101,10 @@ uint32_t cvmx_helper_qlm_jtag_shift(int qlm, int bits, uint32_t data)
 }
 
 /**
- * Shift long sequences of zeros into the QLM JTAG chain. It is
- * common to need to shift more than 32 bits of zeros into the
- * chain. This function is a convenience wrapper around
- * cvmx_helper_qlm_jtag_shift() to shift more than 32 bits of
- * zeros at a time.
+ * cvmx_helper_qlm_jtag_shift_zeros() - Shift long sequences of zeros into the
+ *	QLM JTAG chain. It is common to need to shift more than 32 bits of zeros
+ *	into the chain. This function is a convenience wrapper around
+ *	cvmx_helper_qlm_jtag_shift() to shift more than 32 bits of zeros at a time.
  *
  * @qlm:    QLM to shift zeros into
  * @bits:
@@ -122,9 +121,9 @@ void cvmx_helper_qlm_jtag_shift_zeros(int qlm, int bits)
 }
 
 /**
- * Program the QLM JTAG chain into all lanes of the QLM. You must
- * have already shifted in 268*4, or 1072 bits into the JTAG
- * chain. Updating invalid values can possibly cause chip damage.
+ * cvmx_helper_qlm_jtag_update() - Program the QLM JTAG chain into all lanes
+ *	of the QLM. You must have already shifted in 268*4, or 1072 bits into the
+ *	JTAG chain. Updating invalid values can possibly cause chip damage.
  *
  * @qlm:    QLM to program
  */
diff --git a/arch/mips/cavium-octeon/executive/cvmx-helper-loop.c b/arch/mips/cavium-octeon/executive/cvmx-helper-loop.c
index bfbd46115..5050d01d3 100644
--- a/arch/mips/cavium-octeon/executive/cvmx-helper-loop.c
+++ b/arch/mips/cavium-octeon/executive/cvmx-helper-loop.c
@@ -37,13 +37,13 @@
 #include <asm/octeon/cvmx-pip-defs.h>
 
 /**
- * Probe a LOOP interface and determine the number of ports
- * connected to it. The LOOP interface should still be down
- * after this call.
+ * __cvmx_helper_loop_probe() - Probe a LOOP interface and determine the
+ *	number of ports connected to it. The LOOP interface should still be down
+ *	after this call.
  *
  * @interface: Interface to probe
  *
- * Returns Number of ports on the interface. Zero to disable.
+ * Returns: Number of ports on the interface. Zero to disable.
  */
 int __cvmx_helper_loop_probe(int interface)
 {
@@ -70,13 +70,13 @@ int __cvmx_helper_loop_probe(int interface)
 }
 
 /**
- * Bringup and enable a LOOP interface. After this call packet
- * I/O should be fully functional. This is called with IPD
- * enabled but PKO disabled.
+ * __cvmx_helper_loop_enable() - Bringup and enable a LOOP interface. After
+ *	this call packet I/O should be fully functional. This is called with IPD
+ *	enabled but PKO disabled.
  *
  * @interface: Interface to bring up
  *
- * Returns Zero on success, negative on failure
+ * Returns: Zero on success, negative on failure
  */
 int __cvmx_helper_loop_enable(int interface)
 {
diff --git a/arch/mips/cavium-octeon/executive/cvmx-helper-npi.c b/arch/mips/cavium-octeon/executive/cvmx-helper-npi.c
index cb210d2ef..2b8cd7569 100644
--- a/arch/mips/cavium-octeon/executive/cvmx-helper-npi.c
+++ b/arch/mips/cavium-octeon/executive/cvmx-helper-npi.c
@@ -38,13 +38,13 @@
 #include <asm/octeon/cvmx-pip-defs.h>
 
 /**
- * Probe a NPI interface and determine the number of ports
- * connected to it. The NPI interface should still be down
- * after this call.
+ * __cvmx_helper_npi_probe() - Probe a NPI interface and determine the number
+ *	of ports connected to it. The NPI interface should still be down after this
+ *	call.
  *
  * @interface: Interface to probe
  *
- * Returns Number of ports on the interface. Zero to disable.
+ * Returns: Number of ports on the interface. Zero to disable.
  */
 int __cvmx_helper_npi_probe(int interface)
 {
@@ -64,13 +64,13 @@ int __cvmx_helper_npi_probe(int interface)
 }
 
 /**
- * Bringup and enable a NPI interface. After this call packet
- * I/O should be fully functional. This is called with IPD
- * enabled but PKO disabled.
+ * __cvmx_helper_npi_enable() - Bringup and enable a NPI interface. After this
+ *	call packet I/O should be fully functional. This is called with IPD enabled
+ *	but PKO disabled.
  *
  * @interface: Interface to bring up
  *
- * Returns Zero on success, negative on failure
+ * Returns: Zero on success, negative on failure
  */
 int __cvmx_helper_npi_enable(int interface)
 {
diff --git a/arch/mips/cavium-octeon/executive/cvmx-helper-sgmii.c b/arch/mips/cavium-octeon/executive/cvmx-helper-sgmii.c
index e07d8f15e..91a3773a4 100644
--- a/arch/mips/cavium-octeon/executive/cvmx-helper-sgmii.c
+++ b/arch/mips/cavium-octeon/executive/cvmx-helper-sgmii.c
@@ -42,12 +42,13 @@
 #include <asm/octeon/cvmx-pcsxx-defs.h>
 
 /**
- * Perform initialization required only once for an SGMII port.
+ * __cvmx_helper_sgmii_hardware_init_one_time() - Perform initialization
+ *	required only once for an SGMII port.
  *
  * @interface: Interface to init
  * @index:     Index of prot on the interface
  *
- * Returns Zero on success, negative on failure
+ * Returns: Zero on success, negative on failure
  */
 static int __cvmx_helper_sgmii_hardware_init_one_time(int interface, int index)
 {
@@ -126,13 +127,13 @@ static int __cvmx_helper_sgmii_hardware_init_one_time(int interface, int index)
 }
 
 /**
- * Initialize the SERTES link for the first time or after a loss
- * of link.
+ * __cvmx_helper_sgmii_hardware_init_link() - Initialize the SERTES link for
+ *	the first time or after a loss of link.
  *
  * @interface: Interface to init
  * @index:     Index of prot on the interface
  *
- * Returns Zero on success, negative on failure
+ * Returns: Zero on success, negative on failure
  */
 static int __cvmx_helper_sgmii_hardware_init_link(int interface, int index)
 {
@@ -189,14 +190,14 @@ static int __cvmx_helper_sgmii_hardware_init_link(int interface, int index)
 }
 
 /**
- * Configure an SGMII link to the specified speed after the SERTES
- * link is up.
+ * __cvmx_helper_sgmii_hardware_init_link_speed() - Configure an SGMII link to
+ *	the specified speed after the SERTES link is up.
  *
  * @interface: Interface to init
  * @index:     Index of prot on the interface
  * @link_info: Link state to configure
  *
- * Returns Zero on success, negative on failure
+ * Returns: Zero on success, negative on failure
  */
 static int __cvmx_helper_sgmii_hardware_init_link_speed(int interface,
 							int index,
@@ -295,14 +296,14 @@ static int __cvmx_helper_sgmii_hardware_init_link_speed(int interface,
 }
 
 /**
- * Bring up the SGMII interface to be ready for packet I/O but
- * leave I/O disabled using the GMX override. This function
- * follows the bringup documented in 10.6.3 of the manual.
+ * __cvmx_helper_sgmii_hardware_init() - Bring up the SGMII interface to be
+ *	ready for packet I/O but leave I/O disabled using the GMX override. This
+ *	function follows the bringup documented in 10.6.3 of the manual.
  *
  * @interface: Interface to bringup
  * @num_ports: Number of ports on the interface
  *
- * Returns Zero on success, negative on failure
+ * Returns: Zero on success, negative on failure
  */
 static int __cvmx_helper_sgmii_hardware_init(int interface, int num_ports)
 {
@@ -331,13 +332,13 @@ int __cvmx_helper_sgmii_enumerate(int interface)
 	return 4;
 }
 /**
- * Probe a SGMII interface and determine the number of ports
- * connected to it. The SGMII interface should still be down after
- * this call.
+ * __cvmx_helper_sgmii_probe() - Probe a SGMII interface and determine the
+ *	number of ports connected to it. The SGMII interface should still be down
+ *	after this call.
  *
  * @interface: Interface to probe
  *
- * Returns Number of ports on the interface. Zero to disable.
+ * Returns: Number of ports on the interface. Zero to disable.
  */
 int __cvmx_helper_sgmii_probe(int interface)
 {
@@ -355,13 +356,13 @@ int __cvmx_helper_sgmii_probe(int interface)
 }
 
 /**
- * Bringup and enable a SGMII interface. After this call packet
- * I/O should be fully functional. This is called with IPD
- * enabled but PKO disabled.
+ * __cvmx_helper_sgmii_enable() - Bringup and enable a SGMII interface. After
+ *	this call packet I/O should be fully functional. This is called with IPD
+ *	enabled but PKO disabled.
  *
  * @interface: Interface to bring up
  *
- * Returns Zero on success, negative on failure
+ * Returns: Zero on success, negative on failure
  */
 int __cvmx_helper_sgmii_enable(int interface)
 {
@@ -385,14 +386,14 @@ int __cvmx_helper_sgmii_enable(int interface)
 }
 
 /**
- * Return the link state of an IPD/PKO port as returned by
- * auto negotiation. The result of this function may not match
- * Octeon's link config if auto negotiation has changed since
- * the last call to cvmx_helper_link_set().
+ * __cvmx_helper_sgmii_link_get() - Return the link state of an IPD/PKO port
+ *	as returned by auto negotiation. The result of this function may not match
+ *	Octeon's link config if auto negotiation has changed since the last call to
+ *	cvmx_helper_link_set().
  *
  * @ipd_port: IPD/PKO port to query
  *
- * Returns Link state
+ * Returns: Link state
  */
 union cvmx_helper_link_info __cvmx_helper_sgmii_link_get(int ipd_port)
 {
@@ -494,15 +495,15 @@ union cvmx_helper_link_info __cvmx_helper_sgmii_link_get(int ipd_port)
 }
 
 /**
- * Configure an IPD/PKO port for the specified link state. This
- * function does not influence auto negotiation at the PHY level.
- * The passed link state must always match the link state returned
- * by cvmx_helper_link_get().
+ * __cvmx_helper_sgmii_link_set() - Configure an IPD/PKO port for the
+ *	specified link state. This function does not influence auto negotiation at
+ *	the PHY level. The passed link state must always match the link state
+ *	returned by cvmx_helper_link_get().
  *
  * @ipd_port:  IPD/PKO port to configure
  * @link_info: The new link state
  *
- * Returns Zero on success, negative on failure
+ * Returns: Zero on success, negative on failure
  */
 int __cvmx_helper_sgmii_link_set(int ipd_port,
 				 union cvmx_helper_link_info link_info)
diff --git a/arch/mips/cavium-octeon/executive/cvmx-helper-spi.c b/arch/mips/cavium-octeon/executive/cvmx-helper-spi.c
index 525914e9b..6df2f54c8 100644
--- a/arch/mips/cavium-octeon/executive/cvmx-helper-spi.c
+++ b/arch/mips/cavium-octeon/executive/cvmx-helper-spi.c
@@ -60,13 +60,13 @@ int __cvmx_helper_spi_enumerate(int interface)
 }
 
 /**
- * Probe a SPI interface and determine the number of ports
- * connected to it. The SPI interface should still be down after
- * this call.
+ * __cvmx_helper_spi_probe() - Probe a SPI interface and determine the number
+ *	of ports connected to it. The SPI interface should still be down after this
+ *	call.
  *
  * @interface: Interface to probe
  *
- * Returns Number of ports on the interface. Zero to disable.
+ * Returns: Number of ports on the interface. Zero to disable.
  */
 int __cvmx_helper_spi_probe(int interface)
 {
@@ -93,13 +93,13 @@ int __cvmx_helper_spi_probe(int interface)
 }
 
 /**
- * Bringup and enable a SPI interface. After this call packet I/O
- * should be fully functional. This is called with IPD enabled but
- * PKO disabled.
+ * __cvmx_helper_spi_enable() - Bringup and enable a SPI interface. After this
+ *	call packet I/O should be fully functional. This is called with IPD enabled
+ *	but PKO disabled.
  *
  * @interface: Interface to bring up
  *
- * Returns Zero on success, negative on failure
+ * Returns: Zero on success, negative on failure
  */
 int __cvmx_helper_spi_enable(int interface)
 {
@@ -131,14 +131,14 @@ int __cvmx_helper_spi_enable(int interface)
 }
 
 /**
- * Return the link state of an IPD/PKO port as returned by
- * auto negotiation. The result of this function may not match
- * Octeon's link config if auto negotiation has changed since
- * the last call to cvmx_helper_link_set().
+ * __cvmx_helper_spi_link_get() - Return the link state of an IPD/PKO port as
+ *	returned by auto negotiation. The result of this function may not match
+ *	Octeon's link config if auto negotiation has changed since the last call to
+ *	cvmx_helper_link_set().
  *
  * @ipd_port: IPD/PKO port to query
  *
- * Returns Link state
+ * Returns: Link state
  */
 union cvmx_helper_link_info __cvmx_helper_spi_link_get(int ipd_port)
 {
@@ -183,15 +183,15 @@ union cvmx_helper_link_info __cvmx_helper_spi_link_get(int ipd_port)
 }
 
 /**
- * Configure an IPD/PKO port for the specified link state. This
- * function does not influence auto negotiation at the PHY level.
- * The passed link state must always match the link state returned
- * by cvmx_helper_link_get().
+ * __cvmx_helper_spi_link_set() - Configure an IPD/PKO port for the specified
+ *	link state. This function does not influence auto negotiation at the PHY
+ *	level. The passed link state must always match the link state returned by
+ *	cvmx_helper_link_get().
  *
  * @ipd_port:  IPD/PKO port to configure
  * @link_info: The new link state
  *
- * Returns Zero on success, negative on failure
+ * Returns: Zero on success, negative on failure
  */
 int __cvmx_helper_spi_link_set(int ipd_port, union cvmx_helper_link_info link_info)
 {
diff --git a/arch/mips/cavium-octeon/executive/cvmx-helper-util.c b/arch/mips/cavium-octeon/executive/cvmx-helper-util.c
index abaf91f6a..be83b948e 100644
--- a/arch/mips/cavium-octeon/executive/cvmx-helper-util.c
+++ b/arch/mips/cavium-octeon/executive/cvmx-helper-util.c
@@ -46,11 +46,12 @@
 #include <asm/octeon/cvmx-ipd-defs.h>
 
 /**
- * Convert a interface mode into a human readable string
+ * cvmx_helper_interface_mode_to_string() - Convert a interface mode into a
+ *	human readable string
  *
  * @mode:   Mode to convert
  *
- * Returns String
+ * Returns: String
  */
 const char *cvmx_helper_interface_mode_to_string(enum cvmx_helper_interface_mode
 						 mode)
@@ -81,7 +82,8 @@ const char *cvmx_helper_interface_mode_to_string(enum cvmx_helper_interface_mode
 }
 
 /**
- * Setup Random Early Drop on a specific input queue
+ * cvmx_helper_setup_red_queue() - Setup Random Early Drop on a specific input
+ *	queue
  *
  * @queue:  Input queue to setup RED on (0-7)
  * @pass_thresh:
@@ -90,7 +92,8 @@ const char *cvmx_helper_interface_mode_to_string(enum cvmx_helper_interface_mode
  * @drop_thresh:
  *		 All incoming packets will be dropped when there are less
  *		 than this many free packet buffers in FPA 0.
- * Returns Zero on success. Negative on failure
+ *
+ * Returns: Zero on success. Negative on failure
  */
 static int cvmx_helper_setup_red_queue(int queue, int pass_thresh,
 				       int drop_thresh)
@@ -118,7 +121,8 @@ static int cvmx_helper_setup_red_queue(int queue, int pass_thresh,
 }
 
 /**
- * Setup Random Early Drop to automatically begin dropping packets.
+ * cvmx_helper_setup_red() - Setup Random Early Drop to automatically begin
+ *	dropping packets.
  *
  * @pass_thresh:
  *		 Packets will begin slowly dropping when there are less than
@@ -126,7 +130,8 @@ static int cvmx_helper_setup_red_queue(int queue, int pass_thresh,
  * @drop_thresh:
  *		 All incoming packets will be dropped when there are less
  *		 than this many free packet buffers in FPA 0.
- * Returns Zero on success. Negative on failure
+ *
+ * Returns: Zero on success. Negative on failure
  */
 int cvmx_helper_setup_red(int pass_thresh, int drop_thresh)
 {
@@ -168,14 +173,14 @@ int cvmx_helper_setup_red(int pass_thresh, int drop_thresh)
 EXPORT_SYMBOL_GPL(cvmx_helper_setup_red);
 
 /**
- * Setup the common GMX settings that determine the number of
- * ports. These setting apply to almost all configurations of all
- * chips.
+ * __cvmx_helper_setup_gmx() - Setup the common GMX settings that determine
+ *	the number of ports. These setting apply to almost all configurations of
+ *	all chips.
  *
  * @interface: Interface to configure
  * @num_ports: Number of ports on the interface
  *
- * Returns Zero on success, negative on failure
+ * Returns: Zero on success, negative on failure
  */
 int __cvmx_helper_setup_gmx(int interface, int num_ports)
 {
@@ -277,13 +282,13 @@ int __cvmx_helper_setup_gmx(int interface, int num_ports)
 }
 
 /**
- * Returns the IPD/PKO port number for a port on the given
- * interface.
+ * cvmx_helper_get_ipd_port() - Returns the IPD/PKO port number for a port on
+ *	the given interface.
  *
  * @interface: Interface to use
  * @port:      Port on the interface
  *
- * Returns IPD/PKO port number
+ * Returns: IPD/PKO port number
  */
 int cvmx_helper_get_ipd_port(int interface, int port)
 {
@@ -306,11 +311,12 @@ int cvmx_helper_get_ipd_port(int interface, int port)
 EXPORT_SYMBOL_GPL(cvmx_helper_get_ipd_port);
 
 /**
- * Returns the interface number for an IPD/PKO port number.
+ * cvmx_helper_get_interface_num() - Returns the interface number for an
+ *	IPD/PKO port number.
  *
  * @ipd_port: IPD/PKO port number
  *
- * Returns Interface number
+ * Returns: Interface number
  */
 int cvmx_helper_get_interface_num(int ipd_port)
 {
@@ -335,12 +341,12 @@ int cvmx_helper_get_interface_num(int ipd_port)
 EXPORT_SYMBOL_GPL(cvmx_helper_get_interface_num);
 
 /**
- * Returns the interface index number for an IPD/PKO port
- * number.
+ * cvmx_helper_get_interface_index_num() - Returns the interface index number
+ *	for an IPD/PKO port number.
  *
  * @ipd_port: IPD/PKO port number
  *
- * Returns Interface index number
+ * Returns: Interface index number
  */
 int cvmx_helper_get_interface_index_num(int ipd_port)
 {
diff --git a/arch/mips/cavium-octeon/executive/cvmx-helper.c b/arch/mips/cavium-octeon/executive/cvmx-helper.c
index 1985cd668..adcf60ae2 100644
--- a/arch/mips/cavium-octeon/executive/cvmx-helper.c
+++ b/arch/mips/cavium-octeon/executive/cvmx-helper.c
@@ -50,12 +50,12 @@
 static int interface_port_count[9];
 
 /**
- * Return the number of interfaces the chip has. Each interface
- * may have multiple ports. Most chips support two interfaces,
- * but the CNX0XX and CNX1XX are exceptions. These only support
- * one interface.
+ * cvmx_helper_get_number_of_interfaces() - Return the number of interfaces
+ *	the chip has. Each interface may have multiple ports. Most chips support
+ *	two interfaces, but the CNX0XX and CNX1XX are exceptions. These only
+ *	support one interface.
  *
- * Returns Number of interfaces on chip
+ * Returns: Number of interfaces on chip
  */
 int cvmx_helper_get_number_of_interfaces(void)
 {
@@ -77,13 +77,13 @@ int cvmx_helper_get_number_of_interfaces(void)
 EXPORT_SYMBOL_GPL(cvmx_helper_get_number_of_interfaces);
 
 /**
- * Return the number of ports on an interface. Depending on the
- * chip and configuration, this can be 1-16. A value of 0
- * specifies that the interface doesn't exist or isn't usable.
+ * cvmx_helper_ports_on_interface() - Return the number of ports on an
+ *	interface. Depending on the chip and configuration, this can be 1-16. A
+ *	value of 0 specifies that the interface doesn't exist or isn't usable.
  *
  * @interface: Interface to get the port count for
  *
- * Returns Number of ports on interface. Can be Zero.
+ * Returns: Number of ports on interface. Can be Zero.
  */
 int cvmx_helper_ports_on_interface(int interface)
 {
@@ -92,8 +92,10 @@ int cvmx_helper_ports_on_interface(int interface)
 EXPORT_SYMBOL_GPL(cvmx_helper_ports_on_interface);
 
 /**
+ * __cvmx_get_mode_cn68xx() - Return interface mode for CN68xx.
  * @INTERNAL
- * Return interface mode for CN68xx.
+ *
+ * @interface: interface to get the mode for
  */
 static enum cvmx_helper_interface_mode __cvmx_get_mode_cn68xx(int interface)
 {
@@ -144,8 +146,10 @@ static enum cvmx_helper_interface_mode __cvmx_get_mode_cn68xx(int interface)
 }
 
 /**
+ * __cvmx_get_mode_octeon2() - Return interface mode for an Octeon II
  * @INTERNAL
- * Return interface mode for an Octeon II
+ *
+ * @interface: interface to get the mode for
  */
 static enum cvmx_helper_interface_mode __cvmx_get_mode_octeon2(int interface)
 {
@@ -244,8 +248,10 @@ static enum cvmx_helper_interface_mode __cvmx_get_mode_octeon2(int interface)
 }
 
 /**
+ * __cvmx_get_mode_cn7xxx() - Return interface mode for CN7XXX.
  * @INTERNAL
- * Return interface mode for CN7XXX.
+ *
+ * @interface: interface to get the mode for
  */
 static enum cvmx_helper_interface_mode __cvmx_get_mode_cn7xxx(int interface)
 {
@@ -280,13 +286,13 @@ static enum cvmx_helper_interface_mode __cvmx_get_mode_cn7xxx(int interface)
 }
 
 /**
- * Get the operating mode of an interface. Depending on the Octeon
- * chip and configuration, this function returns an enumeration
- * of the type of packet I/O supported by an interface.
+ * cvmx_helper_interface_get_mode() - Get the operating mode of an interface.
+ *	Depending on the Octeon chip and configuration, this function returns an
+ *	enumeration of the type of packet I/O supported by an interface.
  *
  * @interface: Interface to probe
  *
- * Returns Mode of the interface. Unknown or unsupported interfaces return
+ * Returns: Mode of the interface. Unknown or unsupported interfaces return
  *	   DISABLED.
  */
 enum cvmx_helper_interface_mode cvmx_helper_interface_get_mode(int interface)
@@ -362,15 +368,15 @@ enum cvmx_helper_interface_mode cvmx_helper_interface_get_mode(int interface)
 EXPORT_SYMBOL_GPL(cvmx_helper_interface_get_mode);
 
 /**
- * Configure the IPD/PIP tagging and QoS options for a specific
- * port. This function determines the POW work queue entry
- * contents for a port. The setup performed here is controlled by
- * the defines in executive-config.h.
+ * __cvmx_helper_port_setup_ipd() - Configure the IPD/PIP tagging and QoS
+ *	options for a specific port. This function determines the POW work queue
+ *	entry contents for a port. The setup performed here is controlled by the
+ *	defines in executive-config.h.
  *
  * @ipd_port: Port to configure. This follows the IPD numbering, not the
  *		   per interface numbering
  *
- * Returns Zero on success, negative on failure
+ * Returns: Zero on success, negative on failure
  */
 static int __cvmx_helper_port_setup_ipd(int ipd_port)
 {
@@ -411,13 +417,13 @@ static int __cvmx_helper_port_setup_ipd(int ipd_port)
 }
 
 /**
- * This function sets the interface_port_count[interface] correctly,
- * without modifying any hardware configuration.  Hardware setup of
- * the ports will be performed later.
+ * cvmx_helper_interface_enumerate() - This function sets the
+ *	interface_port_count[interface] correctly, without modifying any hardware
+ *	configuration. Hardware setup of the ports will be performed later.
  *
  * @interface: Interface to probe
  *
- * Returns Zero on success, negative on failure
+ * Returns: Zero on success, negative on failure
  */
 int cvmx_helper_interface_enumerate(int interface)
 {
@@ -485,15 +491,15 @@ int cvmx_helper_interface_enumerate(int interface)
 }
 
 /**
- * This function probes an interface to determine the actual
- * number of hardware ports connected to it. It doesn't setup the
- * ports or enable them. The main goal here is to set the global
- * interface_port_count[interface] correctly. Hardware setup of the
- * ports will be performed later.
+ * cvmx_helper_interface_probe() - This function probes an interface to
+ *	determine the actual number of hardware ports connected to it. It doesn't
+ *	setup the ports or enable them. The main goal here is to set the global
+ *	interface_port_count[interface] correctly. Hardware setup of the ports will
+ *	be performed later.
  *
  * @interface: Interface to probe
  *
- * Returns Zero on success, negative on failure
+ * Returns: Zero on success, negative on failure
  */
 int cvmx_helper_interface_probe(int interface)
 {
@@ -553,14 +559,14 @@ int cvmx_helper_interface_probe(int interface)
 }
 
 /**
- * Setup the IPD/PIP for the ports on an interface. Packet
- * classification and tagging are set for every port on the
- * interface. The number of ports on the interface must already
- * have been probed.
+ * __cvmx_helper_interface_setup_ipd() - Setup the IPD/PIP for the ports on an
+ *	interface. Packet classification and tagging are set for every port on the
+ *	interface. The number of ports on the interface must already have been
+ *	probed.
  *
  * @interface: Interface to setup IPD/PIP for
  *
- * Returns Zero on success, negative on failure
+ * Returns: Zero on success, negative on failure
  */
 static int __cvmx_helper_interface_setup_ipd(int interface)
 {
@@ -575,10 +581,11 @@ static int __cvmx_helper_interface_setup_ipd(int interface)
 }
 
 /**
- * Setup global setting for IPD/PIP not related to a specific
- * interface or port. This must be called before IPD is enabled.
+ * __cvmx_helper_global_setup_ipd() - Setup global setting for IPD/PIP not
+ *	related to a specific interface or port. This must be called before IPD is
+ *	enabled.
  *
- * Returns Zero on success, negative on failure.
+ * Returns: Zero on success, negative on failure.
  */
 static int __cvmx_helper_global_setup_ipd(void)
 {
@@ -597,13 +604,14 @@ static int __cvmx_helper_global_setup_ipd(void)
 }
 
 /**
- * Setup the PKO for the ports on an interface. The number of
- * queues per port and the priority of each PKO output queue
- * is set here. PKO must be disabled when this function is called.
+ * __cvmx_helper_interface_setup_pko() - Setup the PKO for the ports on an
+ *	interface. The number of queues per port and the priority of each PKO
+ *	output queue is set here. PKO must be disabled when this function is
+ *	called.
  *
  * @interface: Interface to setup PKO for
  *
- * Returns Zero on success, negative on failure
+ * Returns: Zero on success, negative on failure
  */
 static int __cvmx_helper_interface_setup_pko(int interface)
 {
@@ -641,10 +649,10 @@ static int __cvmx_helper_interface_setup_pko(int interface)
 }
 
 /**
- * Setup global setting for PKO not related to a specific
- * interface or port. This must be called before PKO is enabled.
+ * __cvmx_helper_global_setup_pko() - Setup global setting for PKO not related
+ *	to a specific interface or port. This must be called before PKO is enabled.
  *
- * Returns Zero on success, negative on failure.
+ * Returns: Zero on success, negative on failure.
  */
 static int __cvmx_helper_global_setup_pko(void)
 {
@@ -676,9 +684,10 @@ static int __cvmx_helper_global_setup_pko(void)
 }
 
 /**
- * Setup global backpressure setting.
+ * __cvmx_helper_global_setup_backpressure() - Setup global backpressure
+ *	setting.
  *
- * Returns Zero on success, negative on failure
+ * Returns: Zero on success, negative on failure
  */
 static int __cvmx_helper_global_setup_backpressure(void)
 {
@@ -710,15 +719,15 @@ static int __cvmx_helper_global_setup_backpressure(void)
 }
 
 /**
- * Enable packet input/output from the hardware. This function is
- * called after all internal setup is complete and IPD is enabled.
- * After this function completes, packets will be accepted from the
- * hardware ports. PKO should still be disabled to make sure packets
- * aren't sent out partially setup hardware.
+ * __cvmx_helper_packet_hardware_enable() - Enable packet input/output from
+ *	the hardware. This function is called after all internal setup is complete
+ *	and IPD is enabled. After this function completes, packets will be accepted
+ *	from the hardware ports. PKO should still be disabled to make sure packets
+ *	aren't sent out partially setup hardware.
  *
  * @interface: Interface to enable
  *
- * Returns Zero on success, negative on failure
+ * Returns: Zero on success, negative on failure
  */
 static int __cvmx_helper_packet_hardware_enable(int interface)
 {
@@ -772,9 +781,10 @@ static int __cvmx_helper_packet_hardware_enable(int interface)
 }
 
 /**
- * Function to adjust internal IPD pointer alignments
+ * __cvmx_helper_errata_fix_ipd_ptr_alignment() - Function to adjust internal
+ *	IPD pointer alignments
  *
- * Returns 0 on success
+ * Returns: 0 on success
  *	   !0 on failure
  */
 static int __cvmx_helper_errata_fix_ipd_ptr_alignment(void)
@@ -966,10 +976,11 @@ static int __cvmx_helper_errata_fix_ipd_ptr_alignment(void)
 }
 
 /**
- * Called after all internal packet IO paths are setup. This
- * function enables IPD/PIP and begins packet input and output.
+ * cvmx_helper_ipd_and_packet_input_enable() - Called after all internal
+ *	packet IO paths are setup. This function enables IPD/PIP and begins packet
+ *	input and output.
  *
- * Returns Zero on success, negative on failure
+ * Returns: Zero on success, negative on failure
  */
 int cvmx_helper_ipd_and_packet_input_enable(void)
 {
@@ -1002,13 +1013,13 @@ int cvmx_helper_ipd_and_packet_input_enable(void)
 EXPORT_SYMBOL_GPL(cvmx_helper_ipd_and_packet_input_enable);
 
 /**
- * Initialize the PIP, IPD, and PKO hardware to support
- * simple priority based queues for the ethernet ports. Each
- * port is configured with a number of priority queues based
- * on CVMX_PKO_QUEUES_PER_PORT_* where each queue is lower
- * priority than the previous.
+ * cvmx_helper_initialize_packet_io_global() - Initialize the PIP, IPD, and
+ *	PKO hardware to support simple priority based queues for the ethernet
+ *	ports. Each port is configured with a number of priority queues based on
+ *	CVMX_PKO_QUEUES_PER_PORT_* where each queue is lower priority than the
+ *	previous.
  *
- * Returns Zero on success, non-zero on failure
+ * Returns: Zero on success, non-zero on failure
  */
 int cvmx_helper_initialize_packet_io_global(void)
 {
@@ -1062,14 +1073,14 @@ int cvmx_helper_initialize_packet_io_global(void)
 EXPORT_SYMBOL_GPL(cvmx_helper_initialize_packet_io_global);
 
 /**
- * Return the link state of an IPD/PKO port as returned by
- * auto negotiation. The result of this function may not match
- * Octeon's link config if auto negotiation has changed since
- * the last call to cvmx_helper_link_set().
+ * cvmx_helper_link_get() - Return the link state of an IPD/PKO port as
+ *	returned by auto negotiation. The result of this function may not match
+ *	Octeon's link config if auto negotiation has changed since the last call to
+ *	cvmx_helper_link_set().
  *
  * @ipd_port: IPD/PKO port to query
  *
- * Returns Link state
+ * Returns: Link state
  */
 union cvmx_helper_link_info cvmx_helper_link_get(int ipd_port)
 {
@@ -1122,15 +1133,15 @@ union cvmx_helper_link_info cvmx_helper_link_get(int ipd_port)
 EXPORT_SYMBOL_GPL(cvmx_helper_link_get);
 
 /**
- * Configure an IPD/PKO port for the specified link state. This
- * function does not influence auto negotiation at the PHY level.
- * The passed link state must always match the link state returned
- * by cvmx_helper_link_get().
+ * cvmx_helper_link_set() - Configure an IPD/PKO port for the specified link
+ *	state. This function does not influence auto negotiation at the PHY level.
+ *	The passed link state must always match the link state returned by
+ *	cvmx_helper_link_get().
  *
  * @ipd_port:  IPD/PKO port to configure
  * @link_info: The new link state
  *
- * Returns Zero on success, negative on failure
+ * Returns: Zero on success, negative on failure
  */
 int cvmx_helper_link_set(int ipd_port, union cvmx_helper_link_info link_info)
 {
diff --git a/arch/mips/cavium-octeon/executive/cvmx-interrupt-rsl.c b/arch/mips/cavium-octeon/executive/cvmx-interrupt-rsl.c
index d23f46736..6729355e4 100644
--- a/arch/mips/cavium-octeon/executive/cvmx-interrupt-rsl.c
+++ b/arch/mips/cavium-octeon/executive/cvmx-interrupt-rsl.c
@@ -42,8 +42,8 @@
 void __cvmx_interrupt_gmxx_rxx_int_en_enable(int index, int block);
 
 /**
- * Enable ASX error interrupts that exist on CN3XXX, CN50XX, and
- * CN58XX.
+ * __cvmx_interrupt_asxx_enable() - Enable ASX error interrupts that exist on
+ *	CN3XXX, CN50XX, and CN58XX.
  *
  * @block:  Interface to enable 0-1
  */
@@ -69,7 +69,8 @@ void __cvmx_interrupt_asxx_enable(int block)
 	cvmx_write_csr(CVMX_ASXX_INT_EN(block), csr.u64);
 }
 /**
- * Enable GMX error reporting for the supplied interface
+ * __cvmx_interrupt_gmxx_enable() - Enable GMX error reporting for the
+ *	supplied interface
  *
  * @interface: Interface to enable
  */
diff --git a/arch/mips/cavium-octeon/executive/octeon-model.c b/arch/mips/cavium-octeon/executive/octeon-model.c
index 98996cc08..e46717b13 100644
--- a/arch/mips/cavium-octeon/executive/octeon-model.c
+++ b/arch/mips/cavium-octeon/executive/octeon-model.c
@@ -32,10 +32,11 @@ enum octeon_feature_bits __octeon_feature_bits __read_mostly;
 EXPORT_SYMBOL_GPL(__octeon_feature_bits);
 
 /**
- * Read a byte of fuse data
+ * cvmx_fuse_read_byte() - Read a byte of fuse data
+ *
  * @byte_addr:	 address to read
  *
- * Returns fuse value: 0 or 1
+ * Returns: fuse value: 0 or 1
  */
 static uint8_t __init cvmx_fuse_read_byte(int byte_addr)
 {
@@ -493,17 +494,15 @@ static const char *__init octeon_model_get_string_buffer(uint32_t chip_id,
 }
 
 /**
- * Given the chip processor ID from COP0, this function returns a
- * string representing the chip model number. The string is of the
- * form CNXXXXpX.X-FREQ-SUFFIX.
- * - XXXX = The chip model number
- * - X.X = Chip pass number
- * - FREQ = Current frequency in Mhz
- * - SUFFIX = NSP, EXP, SCP, SSP, or CP
+ * octeon_model_get_string() - Given the chip processor ID from COP0, this
+ *	function returns a string representing the chip model number. The string is
+ *	of the form CNXXXXpX.X-FREQ-SUFFIX. - XXXX = The chip model number - X.X =
+ *	Chip pass number - FREQ = Current frequency in Mhz - SUFFIX = NSP, EXP,
+ *	SCP, SSP, or CP
  *
  * @chip_id: Chip ID
  *
- * Returns Model string
+ * Returns: Model string
  */
 const char *__init octeon_model_get_string(uint32_t chip_id)
 {
diff --git a/arch/mips/cavium-octeon/octeon-crypto.c b/arch/mips/cavium-octeon/octeon-crypto.c
index 0ff855939..173a8a904 100644
--- a/arch/mips/cavium-octeon/octeon-crypto.c
+++ b/arch/mips/cavium-octeon/octeon-crypto.c
@@ -13,11 +13,12 @@
 #include <linux/sched/task_stack.h>
 
 /**
- * Enable access to Octeon's COP2 crypto hardware for kernel use. Wrap any
- * crypto operations in calls to octeon_crypto_enable/disable in order to make
- * sure the state of COP2 isn't corrupted if userspace is also performing
- * hardware crypto operations. Allocate the state parameter on the stack.
- * Returns with preemption disabled.
+ * octeon_crypto_enable() - Enable access to Octeon's COP2 crypto hardware for
+ *	kernel use. Wrap any crypto operations in calls to
+ *	octeon_crypto_enable/disable in order to make sure the state of COP2 isn't
+ *	corrupted if userspace is also performing hardware crypto operations.
+ *	Allocate the state parameter on the stack. Returns with preemption
+ *	disabled.
  *
  * @state: Pointer to state structure to store current COP2 state in.
  *
@@ -45,12 +46,12 @@ unsigned long octeon_crypto_enable(struct octeon_cop2_state *state)
 EXPORT_SYMBOL_GPL(octeon_crypto_enable);
 
 /**
- * Disable access to Octeon's COP2 crypto hardware in the kernel. This must be
- * called after an octeon_crypto_enable() before any context switch or return to
- * userspace.
+ * octeon_crypto_disable() - Disable access to Octeon's COP2 crypto hardware
+ *	in the kernel. This must be called after an octeon_crypto_enable() before
+ *	any context switch or return to userspace.
  *
  * @state:	Pointer to COP2 state to restore
- * @flags:	Return value from octeon_crypto_enable()
+ * @crypto_flags: Return value from octeon_crypto_enable()
  */
 void octeon_crypto_disable(struct octeon_cop2_state *state,
 			   unsigned long crypto_flags)
diff --git a/arch/mips/pci/pci-octeon.c b/arch/mips/pci/pci-octeon.c
index 36d12cea3..4bf770f3f 100644
--- a/arch/mips/pci/pci-octeon.c
+++ b/arch/mips/pci/pci-octeon.c
@@ -37,7 +37,11 @@
 u64 octeon_bar1_pci_phys;
 
 /**
- * This is the bit decoding used for the Octeon PCI controller addresses
+ * union octeon_pci_address - This is the bit decoding used for the Octeon PCI
+ *	controller addresses
+ *
+ * @u64: the address as a single 64-bit value
+ * @s: the address split into bit fields
  */
 union octeon_pci_address {
 	uint64_t u64;
@@ -61,7 +65,7 @@ int (*octeon_pcibios_map_irq)(const struct pci_dev *dev, u8 slot, u8 pin);
 enum octeon_dma_bar_type octeon_dma_bar_type = OCTEON_DMA_BAR_TYPE_INVALID;
 
 /**
- * Map a PCI device to the appropriate interrupt line
+ * pcibios_map_irq() - Map a PCI device to the appropriate interrupt line
  *
  * @dev:    The Linux PCI device structure for the device to map
  * @slot:   The slot number for this device on __BUS 0__. Linux
@@ -69,7 +73,8 @@ enum octeon_dma_bar_type octeon_dma_bar_type = OCTEON_DMA_BAR_TYPE_INVALID;
  *		 slot on Bus 0 where this device eventually hooks to.
  * @pin:    The PCI interrupt pin read from the device, then swizzled
  *		 as it goes through each bridge.
- * Returns Interrupt number for the device
+ *
+ * Returns: Interrupt number for the device
  */
 int pcibios_map_irq(const struct pci_dev *dev, u8 slot, u8 pin)
 {
@@ -168,13 +173,12 @@ int pcibios_plat_dev_init(struct pci_dev *dev)
 }
 
 /**
- * Return the mapping of PCI device number to IRQ line. Each
- * character in the return string represents the interrupt
- * line for the device at that position. Device 1 maps to the
- * first character, etc. The characters A-D are used for PCI
- * interrupts.
+ * octeon_get_pci_interrupts() - Return the mapping of PCI device number to
+ *	IRQ line. Each character in the return string represents the interrupt line
+ *	for the device at that position. Device 1 maps to the first character, etc.
+ *	The characters A-D are used for PCI interrupts.
  *
- * Returns PCI interrupt mapping
+ * Returns: PCI interrupt mapping
  */
 const char *octeon_get_pci_interrupts(void)
 {
@@ -221,7 +225,8 @@ const char *octeon_get_pci_interrupts(void)
 }
 
 /**
- * Map a PCI device to the appropriate interrupt line
+ * octeon_pci_pcibios_map_irq() - Map a PCI device to the appropriate
+ *	interrupt line
  *
  * @dev:    The Linux PCI device structure for the device to map
  * @slot:   The slot number for this device on __BUS 0__. Linux
@@ -229,7 +234,8 @@ const char *octeon_get_pci_interrupts(void)
  *		 slot on Bus 0 where this device eventually hooks to.
  * @pin:    The PCI interrupt pin read from the device, then swizzled
  *		 as it goes through each bridge.
- * Returns Interrupt number for the device
+ *
+ * Returns: Interrupt number for the device
  */
 int __init octeon_pci_pcibios_map_irq(const struct pci_dev *dev,
 				      u8 slot, u8 pin)
-- 
2.43.0