Skip to contentSkip to conversation

driver: clean up comment formatting and spacing

PATCH Applied Bo Sun 3 participants 8 messages Jul 11, 2025 – Aug 5, 2025 Device tree

lore
Share & tools
lore

Bo Sun

author
#0 lore raw

PATCH 1/3 driver: clean up comment formatting and spacing

- Fixed a missing closing parenthesis in the comment for DEVICE_ID_SINGLE
- Cleaned up indentation and alignment of multi-line comments in struct device
- Removed redundant spaces in function pointer declarations

No functional changes.

---
 include/device.h | 18 ++++++++++--------
 include/driver.h |  8 ++++----
 2 files changed, 14 insertions(+), 12 deletions(-)
include/device.h +10 -8
index bc3a348e2e..97fa040365 100644
@@ -37,7 +37,7 @@ struct device {
 	/*! This member is used to store device's unique name as
 	 *  obtained by calling dev_id(). Internal field, do not
 	 *  access it directly.
-	  */
+	 */
 	char *unique_name;
 	/*! The id is used to uniquely identify a device in the system. The id
 	 * will show up under /dev/ as the device's name. Usually this is
@@ -58,14 +58,16 @@ struct device {
 		void *priv;
 		void *driver_data;
 	};
-	void *type_data;     /*! In case this device is a specific device, this pointer
-			      * points to the type specific device, i.e. eth_device
-			      */
+	/*! In case this device is a specific device, this pointer
+	 * points to the type specific device, i.e. eth_device
+	 */
+	void *type_data;
+
 	struct driver *driver; /*! The driver for this device */
 
 	struct list_head list;     /* The list of all devices */
-	struct list_head bus_list; /* our bus            */
-	struct list_head children; /* our children            */
+	struct list_head bus_list; /* our bus */
+	struct list_head children; /* our children */
 	struct list_head sibling;
 	struct list_head active;   /* The list of all devices which have a driver */
 
@@ -102,8 +104,8 @@ struct device {
 	 * For devices which take longer to probe this is called
 	 * when the driver should actually detect client devices
 	 */
-	int     (*detect) (struct device *);
-	void	(*rescan) (struct device *);
+	int (*detect)(struct device *);
+	void (*rescan)(struct device *);
 
 	/*
 	 * if a driver probe is deferred, this stores the last error
include/driver.h +4 -4
index dd50a7aa3c..510a32186d 100644
@@ -36,13 +36,13 @@ struct driver {
 	const char *name;
 
 	struct list_head list;
-	struct list_head bus_list; /* our bus            */
+	struct list_head bus_list; /* our bus */
 
 	/*! Called if an instance of a device is found */
-	int     (*probe) (struct device *);
+	int (*probe)(struct device *);
 
 	/*! Called if an instance of a device is gone. */
-	void     (*remove)(struct device *);
+	void (*remove)(struct device *);
 
 	struct bus_type *bus;
 
@@ -61,7 +61,7 @@ struct driver {
 
 /* dynamically assign the next free id */
 #define DEVICE_ID_DYNAMIC	-2
-/* do not use an id (only one device available */
+/* do not use an id (only one device available) */
 #define DEVICE_ID_SINGLE	-1
 
 /* Register devices and drivers.
author
#1 lore raw

PATCH 2/3 miitool: clarify help text for default behavior and -s option

The -s option description was misleading about default behavior. Clarify that miitool without options shows all PHYs, and -s requires a device argument.

---
 commands/miitool.c | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)
commands/miitool.c +3 -1
index 0121fdc542..0c70b51ad3 100644
@@ -344,9 +344,11 @@ BAREBOX_CMD_HELP_TEXT("Media Independent Interface (MII) unit as well as allowin
 BAREBOX_CMD_HELP_TEXT("register dummy PHY devices for raw MDIO access. Most fast ethernet")
 BAREBOX_CMD_HELP_TEXT("adapters use an MII to autonegotiate link speed and duplex setting.")
 BAREBOX_CMD_HELP_TEXT("")
+BAREBOX_CMD_HELP_TEXT("When run without options, shows status of all PHYs.")
+BAREBOX_CMD_HELP_TEXT("")
 BAREBOX_CMD_HELP_TEXT("Options:")
 BAREBOX_CMD_HELP_OPT("-v", "increase verbosity")
-BAREBOX_CMD_HELP_OPT("-s <devpath/devname>", "show PHY status (not providing PHY prints status of all)")
+BAREBOX_CMD_HELP_OPT("-s <devpath/devname>", "show PHY status for specified device")
 BAREBOX_CMD_HELP_OPT("-r <busno>:<adr>", "register a PHY")
 BAREBOX_CMD_HELP_END
 
Reviewed-by on v1 2/3
#2 lore raw

Re: [PATCH 2/3] miitool: clarify help text for default behavior and -s option

Quoted 5 lines · Bo Sun

The -s option description was misleading about default behavior. Clarify that miitool without options shows all PHYs, and -s requires a device argument.

Quoted 23 lines
---
 commands/miitool.c | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)
commands/miitool.c +3 -1
index 0121fdc542..0c70b51ad3 100644
@@ -344,9 +344,11 @@ BAREBOX_CMD_HELP_TEXT("Media Independent Interface (MII) unit as well as allowin
 BAREBOX_CMD_HELP_TEXT("register dummy PHY devices for raw MDIO access. Most fast ethernet")
 BAREBOX_CMD_HELP_TEXT("adapters use an MII to autonegotiate link speed and duplex setting.")
 BAREBOX_CMD_HELP_TEXT("")
+BAREBOX_CMD_HELP_TEXT("When run without options, shows status of all PHYs.")
+BAREBOX_CMD_HELP_TEXT("")
 BAREBOX_CMD_HELP_TEXT("Options:")
 BAREBOX_CMD_HELP_OPT("-v", "increase verbosity")
-BAREBOX_CMD_HELP_OPT("-s <devpath/devname>", "show PHY status (not providing PHY prints status of all)")
+BAREBOX_CMD_HELP_OPT("-s <devpath/devname>", "show PHY status for specified device")
 BAREBOX_CMD_HELP_OPT("-r <busno>:<adr>", "register a PHY")
 BAREBOX_CMD_HELP_END
 
Signature · 4 lines
Pengutronix e.K.                  |                             |
Steuerwalder Str. 21              | http://www.pengutronix.de/  |
31137 Hildesheim, Germany         | Phone: +49-5121-206917-0    |
Amtsgericht Hildesheim, HRA 2686  | Fax:   +49-5121-206917-5555 |
author
#3 lore raw

PATCH 3/3 of: base: fix of_match_node function documentation

In reply to Bo Sun

Fix grammar error, correct structure name, and add missing return value description.

---
 drivers/of/base.c | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)
drivers/of/base.c +3 -1
index 1439e55a0a..903adb3670 100644
@@ -778,11 +778,13 @@ struct device_node *of_find_node_with_property(struct device_node *from,
 EXPORT_SYMBOL(of_find_node_with_property);
 
 /**
- * of_match_node - Tell if an device_node has a matching of_match structure
+ * of_match_node - Tell if a device_node has a matching of_device_id structure
  *      @matches:       array of of device match structures to search in
  *      @node:          the of device structure to match against
  *
  *      Low level utility function used by device matching.
+ *
+ *      Return: pointer to the best matching of_device_id structure, or NULL
  */
 const struct of_device_id *of_match_node(const struct of_device_id *matches,
 					 const struct device_node *node)
Reviewed-by on v1 3/3
#4 lore raw

Re: [PATCH 3/3] of: base: fix of_match_node function documentation

Quoted 4 lines · Bo Sun

Fix grammar error, correct structure name, and add missing return value description.

Thanks,
Ahmad

Quoted 25 lines
---
 drivers/of/base.c | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)
drivers/of/base.c +3 -1
index 1439e55a0a..903adb3670 100644
@@ -778,11 +778,13 @@ struct device_node *of_find_node_with_property(struct device_node *from,
 EXPORT_SYMBOL(of_find_node_with_property);
 
 /**
- * of_match_node - Tell if an device_node has a matching of_match structure
+ * of_match_node - Tell if a device_node has a matching of_device_id structure
  *      @matches:       array of of device match structures to search in
  *      @node:          the of device structure to match against
  *
  *      Low level utility function used by device matching.
+ *
+ *      Return: pointer to the best matching of_device_id structure, or NULL
  */
 const struct of_device_id *of_match_node(const struct of_device_id *matches,
 					 const struct device_node *node)
Signature · 4 lines
Pengutronix e.K.                  |                             |
Steuerwalder Str. 21              | http://www.pengutronix.de/  |
31137 Hildesheim, Germany         | Phone: +49-5121-206917-0    |
Amtsgericht Hildesheim, HRA 2686  | Fax:   +49-5121-206917-5555 |
Reviewed-by on v1 1/3
#5 lore raw
In reply to Bo Sun

Hello Bo,

Quoted 7 lines · Bo Sun

- Fixed a missing closing parenthesis in the comment for DEVICE_ID_SINGLE
- Cleaned up indentation and alignment of multi-line comments in struct device
- Removed redundant spaces in function pointer declarations

No functional changes.

Quoted 10 lines
---
 include/device.h | 18 ++++++++++--------
 include/driver.h |  8 ++++----
 2 files changed, 14 insertions(+), 12 deletions(-)
include/device.h +0 -0
index bc3a348e2e..97fa040365 100644

include/device.h struct device { · line 40

Quoted 5 lines
include/device.h +1 -1
@@ -37,7 +37,7 @@ struct device {
 	/*! This member is used to store device's unique name as
 	 *  obtained by calling dev_id(). Internal field, do not
 	 *  access it directly.
-	  */
+	 */

Would you like to use the occasion to switch this over to kerneldoc style? Kerneldoc is much more common in newer barebox code and would allow us using the same infrastructure in future.

Cheers,
Ahmad

Quoted 68 lines
include/device.h +9 -7
 	char *unique_name;
 	/*! The id is used to uniquely identify a device in the system. The id
 	 * will show up under /dev/ as the device's name. Usually this is
@@ -58,14 +58,16 @@ struct device {
 		void *priv;
 		void *driver_data;
 	};
-	void *type_data;     /*! In case this device is a specific device, this pointer
-			      * points to the type specific device, i.e. eth_device
-			      */
+	/*! In case this device is a specific device, this pointer
+	 * points to the type specific device, i.e. eth_device
+	 */
+	void *type_data;
+
 	struct driver *driver; /*! The driver for this device */
 
 	struct list_head list;     /* The list of all devices */
-	struct list_head bus_list; /* our bus            */
-	struct list_head children; /* our children            */
+	struct list_head bus_list; /* our bus */
+	struct list_head children; /* our children */
 	struct list_head sibling;
 	struct list_head active;   /* The list of all devices which have a driver */
 
@@ -102,8 +104,8 @@ struct device {
 	 * For devices which take longer to probe this is called
 	 * when the driver should actually detect client devices
 	 */
-	int     (*detect) (struct device *);
-	void	(*rescan) (struct device *);
+	int (*detect)(struct device *);
+	void (*rescan)(struct device *);
 
 	/*
 	 * if a driver probe is deferred, this stores the last error
include/driver.h +4 -4
index dd50a7aa3c..510a32186d 100644
@@ -36,13 +36,13 @@ struct driver {
 	const char *name;
 
 	struct list_head list;
-	struct list_head bus_list; /* our bus            */
+	struct list_head bus_list; /* our bus */
 
 	/*! Called if an instance of a device is found */
-	int     (*probe) (struct device *);
+	int (*probe)(struct device *);
 
 	/*! Called if an instance of a device is gone. */
-	void     (*remove)(struct device *);
+	void (*remove)(struct device *);
 
 	struct bus_type *bus;
 
@@ -61,7 +61,7 @@ struct driver {
 
 /* dynamically assign the next free id */
 #define DEVICE_ID_DYNAMIC	-2
-/* do not use an id (only one device available */
+/* do not use an id (only one device available) */
 #define DEVICE_ID_SINGLE	-1
 
 /* Register devices and drivers.
Signature · 4 lines
Pengutronix e.K.                  |                             |
Steuerwalder Str. 21              | http://www.pengutronix.de/  |
31137 Hildesheim, Germany         | Phone: +49-5121-206917-0    |
Amtsgericht Hildesheim, HRA 2686  | Fax:   +49-5121-206917-5555 |
author
#6 lore raw
Quoted 20 lines · Ahmad Fatoum

Hello Bo,

Quoted 9 lines · Bo Sun

- Fixed a missing closing parenthesis in the comment for DEVICE_ID_SINGLE
- Cleaned up indentation and alignment of multi-line comments in struct device
- Removed redundant spaces in function pointer declarations

No functional changes.

Quoted 5 lines
---
 include/device.h | 18 ++++++++++--------
 include/driver.h |  8 ++++----
 2 files changed, 14 insertions(+), 12 deletions(-)
Quoted 14 lines

include/device.h struct device { · line 40

Quoted 10 lines
include/device.h +1 -1
index bc3a348e2e..97fa040365 100644
@@ -37,7 +37,7 @@ struct device {
 	/*! This member is used to store device's unique name as
 	 *  obtained by calling dev_id(). Internal field, do not
 	 *  access it directly.
-	  */
+	 */

Would you like to use the occasion to switch this over to kerneldoc style? Kerneldoc is much more common in newer barebox code and would allow us using the same infrastructure in future.

Sure, will do.

Thanks,
Bo

Quoted 75 lines

Cheers,
Ahmad

Quoted 71 lines
include/device.h +0 -0
 	char *unique_name;
 	/*! The id is used to uniquely identify a device in the system. The 

id

include/device.h +0 -1
 	 * will show up under /dev/ as the device's name. Usually this is
@@ -58,14 +58,16 @@ struct device {
 		void *priv;
 		void *driver_data;
 	};
-	void *type_data;     /*! In case this device is a specific device, 

this pointer

include/device.h +7 -4
-			      * points to the type specific device, i.e. eth_device
-			      */
+	/*! In case this device is a specific device, this pointer
+	 * points to the type specific device, i.e. eth_device
+	 */
+	void *type_data;
+
 	struct driver *driver; /*! The driver for this device */
 
 	struct list_head list;     /* The list of all devices */
-	struct list_head bus_list; /* our bus            */
-	struct list_head children; /* our children            */
+	struct list_head bus_list; /* our bus */
+	struct list_head children; /* our children */
 	struct list_head sibling;
 	struct list_head active;   /* The list of all devices which have a 

driver */

include/device.h +2 -2
@@ -102,8 +104,8 @@ struct device {
 	 * For devices which take longer to probe this is called
 	 * when the driver should actually detect client devices
 	 */
-	int     (*detect) (struct device *);
-	void	(*rescan) (struct device *);
+	int (*detect)(struct device *);
+	void (*rescan)(struct device *);
 
 	/*
 	 * if a driver probe is deferred, this stores the last error
include/driver.h +4 -4
index dd50a7aa3c..510a32186d 100644
@@ -36,13 +36,13 @@ struct driver {
 	const char *name;
 
 	struct list_head list;
-	struct list_head bus_list; /* our bus            */
+	struct list_head bus_list; /* our bus */
 
 	/*! Called if an instance of a device is found */
-	int     (*probe) (struct device *);
+	int (*probe)(struct device *);
 
 	/*! Called if an instance of a device is gone. */
-	void     (*remove)(struct device *);
+	void (*remove)(struct device *);
 
 	struct bus_type *bus;
 
@@ -61,7 +61,7 @@ struct driver {
 
 /* dynamically assign the next free id */
 #define DEVICE_ID_DYNAMIC	-2
-/* do not use an id (only one device available */
+/* do not use an id (only one device available) */
 #define DEVICE_ID_SINGLE	-1
 
 /* Register devices and drivers.
Applied
#7 lore raw
In reply to Bo Sun
Quoted 8 lines · Bo Sun

- Fixed a missing closing parenthesis in the comment for DEVICE_ID_SINGLE
- Cleaned up indentation and alignment of multi-line comments in struct device
- Removed redundant spaces in function pointer declarations

No functional changes.

[...]

Applied, thanks!

[1/3] driver: clean up comment formatting and spacing
https://git.pengutronix.de/cgit/barebox/commit/?id=1c9f3ddcd7fc (link may not be stable)
[2/3] miitool: clarify help text for default behavior and -s option
https://git.pengutronix.de/cgit/barebox/commit/?id=f9af57826140 (link may not be stable)
[3/3] of: base: fix of_match_node function documentation
https://git.pengutronix.de/cgit/barebox/commit/?id=e67cb2525544 (link may not be stable)

Best regards,

Signature · 1 line
Sascha Hauer <[email protected]>