RFC: configfs attribute description

RFC: configfs attribute description

[Lucas De Marchi]

Hi,

In the drm/xe drivers we recently started to use configfs for a few
things that would be added as module parameters in the past. Configfs
seems a much better fit for us in these cases.

One thing we are missing from module parameters is the description.
I can point people to https://docs.kernel.org/gpu/xe/xe_configfs.html,
but having a short description somewhere of each config at runtime would
be good. I thought of 2 alternatives and would like to know your opinion
or if there's a different way you envision for this.

1) Add description to a module info. This would allow to show "all
configfs attributes this module implements":

configfs.h:
#define CONFIGFS_ATTR_DESC(_name, _desc) \
	MODULE_INFO(configfs_attr_ ## _name, _desc)

xe_configfs.c:
#define XE_CONFIGFS_ATTR(_name, _desc) \
	CONFIGFS_ATTR(, survivability_mode); \
	CONFIGFS_ATTR_DESC(survivability_mode, \
			   "Bind device in a survivability mode useful to unbrick it")

Or provide a single macro in configfs itself. This would "standardize"
module info to contain configfs_attr_xxxxx to describe each entry a
module implements. Main benefit here is that I can take a module and run

2) Add description in the fs tree itself, similarly to how perf adds a
.unit: 2 attributes are created, with the second being RO:

ls /sys/kernel/config/xe/0000:03:00.0/
...
survivability_mode
survivability_mode.description
...

This could be done all inside xe itself, but I think it would be better
if there's a common way across the kernel for that, hence my RFC here.

thanks
Lucas De Marchi

Re: RFC: configfs attribute description

[Andreas Hindborg]

"Lucas De Marchi" <lucas.demarchi@intel.com> writes:

> Hi,
>
> In the drm/xe drivers we recently started to use configfs for a few
> things that would be added as module parameters in the past. Configfs
> seems a much better fit for us in these cases.
>
> One thing we are missing from module parameters is the description.
> I can point people to https://docs.kernel.org/gpu/xe/xe_configfs.html,
> but having a short description somewhere of each config at runtime would
> be good. I thought of 2 alternatives and would like to know your opinion
> or if there's a different way you envision for this.
>
> 1) Add description to a module info. This would allow to show "all
> configfs attributes this module implements":
>
> configfs.h:
> #define CONFIGFS_ATTR_DESC(_name, _desc) \
> 	MODULE_INFO(configfs_attr_ ## _name, _desc)
>
> xe_configfs.c:
> #define XE_CONFIGFS_ATTR(_name, _desc) \
> 	CONFIGFS_ATTR(, survivability_mode); \
> 	CONFIGFS_ATTR_DESC(survivability_mode, \
> 			   "Bind device in a survivability mode useful to unbrick it")
>
> Or provide a single macro in configfs itself. This would "standardize"
> module info to contain configfs_attr_xxxxx to describe each entry a
> module implements. Main benefit here is that I can take a module and run
>
> 2) Add description in the fs tree itself, similarly to how perf adds a
> .unit: 2 attributes are created, with the second being RO:
>
> ls /sys/kernel/config/xe/0000:03:00.0/
> ...
> survivability_mode
> survivability_mode.description
> ...
>
> This could be done all inside xe itself, but I think it would be better
> if there's a common way across the kernel for that, hence my RFC here.

I'm not against adding this if you want to code it. But is it really
that useful? I always find myself reaching for kernel docs for module
parameters anyway.

I would suggest providing this info in user space tooling (if you use
scripts or a binary to interact with your driver through configfs). Or
you can add the info to the kernel man pages or, as you suggest
yourself, the kernel documentation.

I am curious what others think of this.


Best regards,
Andreas Hindborg

Re: RFC: configfs attribute description

[Breno Leitao]

On Wed, Aug 13, 2025 at 08:06:05PM +0200, Andreas Hindborg wrote:
> "Lucas De Marchi" <lucas.demarchi@intel.com> writes:
> 
> > Hi,
> >
> > In the drm/xe drivers we recently started to use configfs for a few
> > things that would be added as module parameters in the past. Configfs
> > seems a much better fit for us in these cases.
> >
> > One thing we are missing from module parameters is the description.
> > I can point people to https://docs.kernel.org/gpu/xe/xe_configfs.html,
> > but having a short description somewhere of each config at runtime would
> > be good. I thought of 2 alternatives and would like to know your opinion
> > or if there's a different way you envision for this.
> >
> > 1) Add description to a module info. This would allow to show "all
> > configfs attributes this module implements":
> >
> > configfs.h:
> > #define CONFIGFS_ATTR_DESC(_name, _desc) \
> > 	MODULE_INFO(configfs_attr_ ## _name, _desc)
> >
> > xe_configfs.c:
> > #define XE_CONFIGFS_ATTR(_name, _desc) \
> > 	CONFIGFS_ATTR(, survivability_mode); \
> > 	CONFIGFS_ATTR_DESC(survivability_mode, \
> > 			   "Bind device in a survivability mode useful to unbrick it")
> >
> > Or provide a single macro in configfs itself. This would "standardize"
> > module info to contain configfs_attr_xxxxx to describe each entry a
> > module implements. Main benefit here is that I can take a module and run
> >
> > 2) Add description in the fs tree itself, similarly to how perf adds a
> > .unit: 2 attributes are created, with the second being RO:

What is this perf .unit exactly? Is it what we see when listing the
perf events?

From a broader kernel perspective, debugfs and sysfs don't have such
a feature, but, module params do, and they are useful sometimes.

But, in general, the kernel documentation is detached from the
binary.