Commit cd00bc2c authored by James Seo's avatar James Seo Committed by Greg Kroah-Hartman
Browse files

driver core: device.h: add some missing kerneldocs 



struct device_attribute, struct dev_ext_attribute, dev_name(), and the
DEVICE_ATTR() macros lack kerneldocs, preventing them from appearing in
the driver core documentation and from being cross-referenced elsewhere.

Add the missing kerneldocs (except for DEVICE_ATTR_IGNORE_LOCKDEP(),
which is only meaningful on debug builds with CONFIG_DEBUG_LOCK_ALLOC
defined, and is aliased to DEVICE_ATTR() otherwise).

Tested-by: default avatarRandy Dunlap <rdunlap@infradead.org>
Acked-by: default avatarRandy Dunlap <rdunlap@infradead.org>
Signed-off-by: default avatarJames Seo <james@equiv.tech>
Link: https://lore.kernel.org/r/20230509024702.1977991-1-james@equiv.tech


Signed-off-by: default avatarGreg Kroah-Hartman <gregkh@linuxfoundation.org>
parent 30480b98

include/linux/device.h

+110 −1
Original line number Diff line number Diff line
@@ -96,7 +96,12 @@ struct device_type { 
	const struct dev_pm_ops *pm;

};



/* interface for exporting device attributes */

/**

 * struct device_attribute - Interface for exporting device attributes.

 * @attr: sysfs attribute definition.

 * @show: Show handler.

 * @store: Store handler.

 */

struct device_attribute {

	struct attribute	attr;

	ssize_t (*show)(struct device *dev, struct device_attribute *attr,
@@ -105,6 +110,11 @@ struct device_attribute { 
			 const char *buf, size_t count);

};



/**

 * struct dev_ext_attribute - Exported device attribute with extra context.

 * @attr: Exported device attribute.

 * @var: Pointer to context.

 */

struct dev_ext_attribute {

	struct device_attribute attr;

	void *var;
@@ -123,30 +133,124 @@ ssize_t device_show_bool(struct device *dev, struct device_attribute *attr, 
ssize_t device_store_bool(struct device *dev, struct device_attribute *attr,

			 const char *buf, size_t count);



/**

 * DEVICE_ATTR - Define a device attribute.

 * @_name: Attribute name.

 * @_mode: File mode.

 * @_show: Show handler. Optional, but mandatory if attribute is readable.

 * @_store: Store handler. Optional, but mandatory if attribute is writable.

 *

 * Convenience macro for defining a struct device_attribute.

 *

 * For example, ``DEVICE_ATTR(foo, 0644, foo_show, foo_store);`` expands to:

 *

 * .. code-block:: c

 *

 *	struct device_attribute dev_attr_foo = {

 *		.attr	= { .name = "foo", .mode = 0644 },

 *		.show	= foo_show,

 *		.store	= foo_store,

 *	};

 */

#define DEVICE_ATTR(_name, _mode, _show, _store) \

	struct device_attribute dev_attr_##_name = __ATTR(_name, _mode, _show, _store)



/**

 * DEVICE_ATTR_PREALLOC - Define a preallocated device attribute.

 * @_name: Attribute name.

 * @_mode: File mode.

 * @_show: Show handler. Optional, but mandatory if attribute is readable.

 * @_store: Store handler. Optional, but mandatory if attribute is writable.

 *

 * Like DEVICE_ATTR(), but ``SYSFS_PREALLOC`` is set on @_mode.

 */

#define DEVICE_ATTR_PREALLOC(_name, _mode, _show, _store) \

	struct device_attribute dev_attr_##_name = \

		__ATTR_PREALLOC(_name, _mode, _show, _store)



/**

 * DEVICE_ATTR_RW - Define a read-write device attribute.

 * @_name: Attribute name.

 *

 * Like DEVICE_ATTR(), but @_mode is 0644, @_show is <_name>_show,

 * and @_store is <_name>_store.

 */

#define DEVICE_ATTR_RW(_name) \

	struct device_attribute dev_attr_##_name = __ATTR_RW(_name)



/**

 * DEVICE_ATTR_ADMIN_RW - Define an admin-only read-write device attribute.

 * @_name: Attribute name.

 *

 * Like DEVICE_ATTR_RW(), but @_mode is 0600.

 */

#define DEVICE_ATTR_ADMIN_RW(_name) \

	struct device_attribute dev_attr_##_name = __ATTR_RW_MODE(_name, 0600)



/**

 * DEVICE_ATTR_RO - Define a readable device attribute.

 * @_name: Attribute name.

 *

 * Like DEVICE_ATTR(), but @_mode is 0444 and @_show is <_name>_show.

 */

#define DEVICE_ATTR_RO(_name) \

	struct device_attribute dev_attr_##_name = __ATTR_RO(_name)



/**

 * DEVICE_ATTR_ADMIN_RO - Define an admin-only readable device attribute.

 * @_name: Attribute name.

 *

 * Like DEVICE_ATTR_RO(), but @_mode is 0400.

 */

#define DEVICE_ATTR_ADMIN_RO(_name) \

	struct device_attribute dev_attr_##_name = __ATTR_RO_MODE(_name, 0400)



/**

 * DEVICE_ATTR_WO - Define an admin-only writable device attribute.

 * @_name: Attribute name.

 *

 * Like DEVICE_ATTR(), but @_mode is 0200 and @_store is <_name>_store.

 */

#define DEVICE_ATTR_WO(_name) \

	struct device_attribute dev_attr_##_name = __ATTR_WO(_name)



/**

 * DEVICE_ULONG_ATTR - Define a device attribute backed by an unsigned long.

 * @_name: Attribute name.

 * @_mode: File mode.

 * @_var: Identifier of unsigned long.

 *

 * Like DEVICE_ATTR(), but @_show and @_store are automatically provided

 * such that reads and writes to the attribute from userspace affect @_var.

 */

#define DEVICE_ULONG_ATTR(_name, _mode, _var) \

	struct dev_ext_attribute dev_attr_##_name = \

		{ __ATTR(_name, _mode, device_show_ulong, device_store_ulong), &(_var) }



/**

 * DEVICE_INT_ATTR - Define a device attribute backed by an int.

 * @_name: Attribute name.

 * @_mode: File mode.

 * @_var: Identifier of int.

 *

 * Like DEVICE_ULONG_ATTR(), but @_var is an int.

 */

#define DEVICE_INT_ATTR(_name, _mode, _var) \

	struct dev_ext_attribute dev_attr_##_name = \

		{ __ATTR(_name, _mode, device_show_int, device_store_int), &(_var) }



/**

 * DEVICE_BOOL_ATTR - Define a device attribute backed by a bool.

 * @_name: Attribute name.

 * @_mode: File mode.

 * @_var: Identifier of bool.

 *

 * Like DEVICE_ULONG_ATTR(), but @_var is a bool.

 */

#define DEVICE_BOOL_ATTR(_name, _mode, _var) \

	struct dev_ext_attribute dev_attr_##_name = \

		{ __ATTR(_name, _mode, device_show_bool, device_store_bool), &(_var) }



#define DEVICE_ATTR_IGNORE_LOCKDEP(_name, _mode, _show, _store) \

	struct device_attribute dev_attr_##_name =		\

		__ATTR_IGNORE_LOCKDEP(_name, _mode, _show, _store)
@@ -711,6 +815,11 @@ static inline bool device_iommu_mapped(struct device *dev) 
/* Get the wakeup routines, which depend on struct device */

#include <linux/pm_wakeup.h>



/**

 * dev_name - Return a device's name.

 * @dev: Device with name to get.

 * Return: The kobject name of the device, or its initial name if unavailable.

 */

static inline const char *dev_name(const struct device *dev)

{

	/* Use the init name until the kobject becomes available */