[PATCH] MIPS: OCTEON: fix kernel-doc comments
hanzhijian <[email protected]>
| Newsgroups | org.kernel.vger.linux-mips,org.kernel.vger.linux-kernel |
|---|---|
| Message-ID | <[email protected]> |
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 <[email protected]> --- .../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