[linux-block.git] / Documentation / leds / uleds.rst

==============
Userspace LEDs
==============

The uleds driver supports userspace LEDs. This can be useful for testing
triggers and can also be used to implement virtual LEDs.


Usage
=====

When the driver is loaded, a character device is created at /dev/uleds. To
create a new LED class device, open /dev/uleds and write a uleds_user_dev
structure to it (found in kernel public header file linux/uleds.h)::

    #define LED_MAX_NAME_SIZE 64

    struct uleds_user_dev {
	char name[LED_MAX_NAME_SIZE];
    };

A new LED class device will be created with the name given. The name can be
any valid sysfs device node name, but consider using the LED class naming
convention of "devicename:color:function".

The current brightness is found by reading a single byte from the character
device. Values are unsigned: 0 to 255. Reading will block until the brightness
changes. The device node can also be polled to notify when the brightness value
changes.

The LED class device will be removed when the open file handle to /dev/uleds
is closed.

Multiple LED class devices are created by opening additional file handles to
/dev/uleds.

See tools/leds/uledmon.c for an example userspace program.
Commit	Line	Data
8dab9197	1	==============
e381322b DL	2	Userspace LEDs
	3	==============
	4
	5	The uleds driver supports userspace LEDs. This can be useful for testing
	6	triggers and can also be used to implement virtual LEDs.
	7
	8
	9	Usage
	10	=====
	11
	12	When the driver is loaded, a character device is created at /dev/uleds. To
	13	create a new LED class device, open /dev/uleds and write a uleds_user_dev
8dab9197	14	structure to it (found in kernel public header file linux/uleds.h)::
e381322b DL	15
	16	#define LED_MAX_NAME_SIZE 64
	17
	18	struct uleds_user_dev {
8dab9197	19	char name[LED_MAX_NAME_SIZE];
e381322b DL	20	};
	21
	22	A new LED class device will be created with the name given. The name can be
	23	any valid sysfs device node name, but consider using the LED class naming
	24	convention of "devicename:color:function".
	25
	26	The current brightness is found by reading a single byte from the character
	27	device. Values are unsigned: 0 to 255. Reading will block until the brightness
	28	changes. The device node can also be polled to notify when the brightness value
	29	changes.
	30
	31	The LED class device will be removed when the open file handle to /dev/uleds
	32	is closed.
	33
	34	Multiple LED class devices are created by opening additional file handles to
	35	/dev/uleds.
	36
	37	See tools/leds/uledmon.c for an example userspace program.