diff mbox series

[net-next,3/3] net: devlink: fix unlocked vs locked functions descriptions

Message ID 20220701095926.1191660-4-jiri@resnulli.us (mailing list archive)
State Superseded
Delegated to: Netdev Maintainers
Headers show
Series net: devlink: devl_* cosmetic fixes | expand

Checks

Context Check Description
netdev/tree_selection success Clearly marked for net-next
netdev/fixes_present success Fixes tag not required for -next series
netdev/subject_prefix success Link
netdev/cover_letter success Series has a cover letter
netdev/patch_count success Link
netdev/header_inline success No static functions without inline keyword in header files
netdev/build_32bit fail Errors and warnings before: 2 this patch: 3
netdev/cc_maintainers warning 1 maintainers not CCed: jiri@nvidia.com
netdev/build_clang fail Errors and warnings before: 6 this patch: 7
netdev/module_param success Was 0 now: 0
netdev/verify_signedoff success Signed-off-by tag matches author and committer
netdev/check_selftest success No net selftest shell script
netdev/verify_fixes success No Fixes tag
netdev/build_allmodconfig_warn fail Errors and warnings before: 2 this patch: 3
netdev/checkpatch success total: 0 errors, 0 warnings, 0 checks, 72 lines checked
netdev/kdoc fail Errors and warnings before: 0 this patch: 1
netdev/source_inline success Was 0 now: 0

Commit Message

Jiri Pirko July 1, 2022, 9:59 a.m. UTC 
From: Jiri Pirko <jiri@nvidia.com>

To be unified with the rest of the code, the unlocked version (devl_*)
of function should have the same description in documentation as the
locked one. Add the missing documentation. Also, add "Context"
annotation for the locked versions where it is missing.

Signed-off-by: Jiri Pirko <jiri@nvidia.com>
---
 net/core/devlink.c | 36 ++++++++++++++++++++++++++++++++++++
 1 file changed, 36 insertions(+)

Comments

Jakub Kicinski July 1, 2022, 4:30 p.m. UTC | #1 
On Fri,  1 Jul 2022 11:59:26 +0200 Jiri Pirko wrote:

> + *	Register devlink port with provided port index. User can use
> + *	any indexing, even hw-related one. devlink_port structure
> + *	is convenient to be embedded inside user driver private structure.
> + *	Note that the caller should take care of zeroing the devlink_port
> + *	structure.

Should we also mention that the port type has to be set later?
I guess that may be beyond the scope.

> + */

> +/**
> + *	devlink_port_unregister - Unregister devlink port

devl_

> + *
> + *	@devlink_port: devlink port
> + */

I wonder if we should use this as an opportunity to start following 
the more modern kdoc format:

No tab indentation, and () after the function's name.

At least for the new kdoc we add.

>  void devl_port_unregister(struct devlink_port *devlink_port)
>  {
>  	lockdep_assert_held(&devlink_port->devlink->lock);
Jiri Pirko July 1, 2022, 4:35 p.m. UTC | #2 
Fri, Jul 01, 2022 at 06:30:37PM CEST, kuba@kernel.org wrote:
>On Fri,  1 Jul 2022 11:59:26 +0200 Jiri Pirko wrote:
>
>> + *	Register devlink port with provided port index. User can use
>> + *	any indexing, even hw-related one. devlink_port structure
>> + *	is convenient to be embedded inside user driver private structure.
>> + *	Note that the caller should take care of zeroing the devlink_port
>> + *	structure.
>
>Should we also mention that the port type has to be set later?
>I guess that may be beyond the scope.

Let's do that in a separate patch. This is just to keep consistency
between devlink_ and devl_

>
>> + */
>
>> +/**
>> + *	devlink_port_unregister - Unregister devlink port
>
>devl_

Right.


>
>> + *
>> + *	@devlink_port: devlink port
>> + */
>
>I wonder if we should use this as an opportunity to start following 
>the more modern kdoc format:
>
>No tab indentation, and () after the function's name.
>
>At least for the new kdoc we add.

Okay. Makes sense.


>
>>  void devl_port_unregister(struct devlink_port *devlink_port)
>>  {
>>  	lockdep_assert_held(&devlink_port->devlink->lock);
>
diff mbox series

Patch

diff --git a/net/core/devlink.c b/net/core/devlink.c
index a7477addbd59..cdb33125cd1e 100644
--- a/net/core/devlink.c
+++ b/net/core/devlink.c
@@ -9877,6 +9877,19 @@  static void devlink_port_type_warn_cancel(struct devlink_port *devlink_port)
 	cancel_delayed_work_sync(&devlink_port->type_warn_dw);
 }
 
+/**
+ *	devl_port_register - Register devlink port
+ *
+ *	@devlink: devlink
+ *	@devlink_port: devlink port
+ *	@port_index: driver-specific numerical identifier of the port
+ *
+ *	Register devlink port with provided port index. User can use
+ *	any indexing, even hw-related one. devlink_port structure
+ *	is convenient to be embedded inside user driver private structure.
+ *	Note that the caller should take care of zeroing the devlink_port
+ *	structure.
+ */
 int devl_port_register(struct devlink *devlink,
 		       struct devlink_port *devlink_port,
 		       unsigned int port_index)
@@ -9915,6 +9928,8 @@  EXPORT_SYMBOL_GPL(devl_port_register);
  *	is convenient to be embedded inside user driver private structure.
  *	Note that the caller should take care of zeroing the devlink_port
  *	structure.
+ *
+ *	Context: Takes and release devlink->lock <mutex>.
  */
 int devlink_port_register(struct devlink *devlink,
 			  struct devlink_port *devlink_port,
@@ -9929,6 +9944,11 @@  int devlink_port_register(struct devlink *devlink,
 }
 EXPORT_SYMBOL_GPL(devlink_port_register);
 
+/**
+ *	devlink_port_unregister - Unregister devlink port
+ *
+ *	@devlink_port: devlink port
+ */
 void devl_port_unregister(struct devlink_port *devlink_port)
 {
 	lockdep_assert_held(&devlink_port->devlink->lock);
@@ -9946,6 +9966,8 @@  EXPORT_SYMBOL_GPL(devl_port_unregister);
  *	devlink_port_unregister - Unregister devlink port
  *
  *	@devlink_port: devlink port
+ *
+ *	Context: Takes and release devlink->lock <mutex>.
  */
 void devlink_port_unregister(struct devlink_port *devlink_port)
 {
@@ -10206,6 +10228,15 @@  int devl_rate_leaf_create(struct devlink_port *devlink_port, void *priv)
 }
 EXPORT_SYMBOL_GPL(devl_rate_leaf_create);
 
+/**
+ * devlink_rate_leaf_create - create devlink rate leaf
+ * @devlink_port: devlink port object to create rate object on
+ * @priv: driver private data
+ *
+ * Create devlink rate object of type leaf on provided @devlink_port.
+ *
+ * Context: Takes and release devlink->lock <mutex>.
+ */
 int
 devlink_rate_leaf_create(struct devlink_port *devlink_port, void *priv)
 {
@@ -10220,6 +10251,11 @@  devlink_rate_leaf_create(struct devlink_port *devlink_port, void *priv)
 }
 EXPORT_SYMBOL_GPL(devlink_rate_leaf_create);
 
+/**
+ * devl_rate_leaf_destroy - destroy devlink rate leaf
+ *
+ * @devlink_port: devlink port linked to the rate object
+ */
 void devl_rate_leaf_destroy(struct devlink_port *devlink_port)
 {
 	struct devlink_rate *devlink_rate = devlink_port->devlink_rate;