led.c File Reference

A kernel module for controlling a simple LED (or any signal) that is connected to a GPIO. It is threaded in order that it can flash the LED. The sysfs entry appears at /sys/ebb/led49. More...

#include <linux/init.h>
#include <linux/module.h>
#include <linux/kernel.h>
#include <linux/gpio.h>
#include <linux/kobject.h>
#include <linux/kthread.h>
#include <linux/delay.h>

Include dependency graph for led.c:

Enumerations
enum	modes { OFF, ON, FLASH }

Functions
	MODULE_LICENSE ("GPL")
	MODULE_AUTHOR ("Derek Molloy")
	MODULE_DESCRIPTION ("A simple Linux LED driver LKM for the BBB")
	MODULE_VERSION ("0.1")
	module_param (gpioLED, uint, S_IRUGO)
	Param desc. S_IRUGO can be read/not changed. More...
	MODULE_PARM_DESC (gpioLED," GPIO LED number (default=49)")
	parameter description More...
	module_param (blinkPeriod, uint, S_IRUGO)
	Param desc. S_IRUGO can be read/not changed. More...
	MODULE_PARM_DESC (blinkPeriod," LED blink period in ms (min=1, default=1000, max=10000)")
static ssize_t	mode_show (struct kobject *kobj, struct kobj_attribute *attr, char *buf)
	A callback function to display the LED mode. More...
static ssize_t	mode_store (struct kobject *kobj, struct kobj_attribute *attr, const char *buf, size_t count)
	A callback function to store the LED mode using the enum above. More...
static ssize_t	period_show (struct kobject *kobj, struct kobj_attribute *attr, char *buf)
	A callback function to display the LED period. More...
static ssize_t	period_store (struct kobject *kobj, struct kobj_attribute *attr, const char *buf, size_t count)
	A callback function to store the LED period value. More...
static int	flash (void *arg)
	The pointer to the thread task. More...
static int __init	ebbLED_init (void)
	The LKM initialization function The static keyword restricts the visibility of the function to within this C file. The __init macro means that for a built-in driver (not a LKM) the function is only used at initialization time and that it can be discarded and its memory freed up after that point. In this example this function sets up the GPIOs and the IRQ. More...
static void __exit	ebbLED_exit (void)
	The LKM cleanup function Similar to the initialization function, it is static. The __exit macro notifies that if this code is used for a built-in driver (not a LKM) that this function is not required. More...
	module_init (ebbLED_init)
	module_exit (ebbLED_exit)

Variables
static unsigned int	gpioLED = 49
	Default GPIO for the LED is 49. More...
static unsigned int	blinkPeriod = 1000
	The blink period in ms. More...
static char	ledName [7] = "ledXXX"
	Null terminated default string – just in case. More...
static bool	ledOn = 0
	Is the LED on or off? Used for flashing. More...
static enum modes	mode = FLASH
	Default mode is flashing. More...
static struct kobj_attribute	period_attr = __ATTR(blinkPeriod, 0666, period_show, period_store)
static struct kobj_attribute	mode_attr = __ATTR(mode, 0666, mode_show, mode_store)
static struct attribute *	ebb_attrs []
static struct attribute_group	attr_group
static struct kobject *	ebb_kobj
static struct task_struct *	task
	The pointer to the kobject. More...

Detailed Description

A kernel module for controlling a simple LED (or any signal) that is connected to a GPIO. It is threaded in order that it can flash the LED. The sysfs entry appears at /sys/ebb/led49.

Author

Derek Molloy

Date

19 April 2015

See also

http://www.derekmolloy.ie/

Enumeration Type Documentation

enum modes

Enumerator
OFF
ON
FLASH

{ OFF, ON, FLASH };              

Function Documentation

static void __exit ebbLED_exit ( void  )

static

The LKM cleanup function Similar to the initialization function, it is static. The __exit macro notifies that if this code is used for a built-in driver (not a LKM) that this function is not required.

                                    {
   kthread_stop(task);                      // Stop the LED flashing thread
   kobject_put(ebb_kobj);                   // clean up -- remove the kobject sysfs entry
   gpio_set_value(gpioLED, 0);              // Turn the LED off, indicates device was unloaded
   gpio_unexport(gpioLED);                  // Unexport the Button GPIO
   gpio_free(gpioLED);                      // Free the LED GPIO
   printk(KERN_INFO "EBB LED: Goodbye from the EBB LED LKM!\n");
}

static int __init ebbLED_init ( void  )

static

The LKM initialization function The static keyword restricts the visibility of the function to within this C file. The __init macro means that for a built-in driver (not a LKM) the function is only used at initialization time and that it can be discarded and its memory freed up after that point. In this example this function sets up the GPIOs and the IRQ.

Returns

returns 0 if successful

                                   {
   int result = 0;

   printk(KERN_INFO "EBB LED: Initializing the EBB LED LKM\n");
   sprintf(ledName, "led%d", gpioLED);      // Create the gpio115 name for /sys/ebb/led49

   ebb_kobj = kobject_create_and_add("ebb", kernel_kobj->parent); // kernel_kobj points to /sys/kernel
   if(!ebb_kobj){
      printk(KERN_ALERT "EBB LED: failed to create kobject\n");
      return -ENOMEM;
   }
   // add the attributes to /sys/ebb/ -- for example, /sys/ebb/led49/ledOn
   result = sysfs_create_group(ebb_kobj, &attr_group);
   if(result) {
      printk(KERN_ALERT "EBB LED: failed to create sysfs group\n");
      kobject_put(ebb_kobj);                // clean up -- remove the kobject sysfs entry
      return result;
   }
   ledOn = true;
   gpio_request(gpioLED, "sysfs");          // gpioLED is 49 by default, request it
   gpio_direction_output(gpioLED, ledOn);   // Set the gpio to be in output mode and turn on
   gpio_export(gpioLED, false);  // causes gpio49 to appear in /sys/class/gpio
                                 // the second argument prevents the direction from being changed

   task = kthread_run(flash, NULL, "LED_flash_thread");  // Start the LED flashing thread
   if(IS_ERR(task)){                                     // Kthread name is LED_flash_thread
      printk(KERN_ALERT "EBB LED: failed to create the task\n");
      return PTR_ERR(task);
   }
   return result;
}

static int flash ( void *  arg )

static

The pointer to the thread task.

The LED Flasher main kthread loop

Parameters

arg	A void pointer used in order to pass data to the thread

Returns

returns 0 if successful

                           {
   printk(KERN_INFO "EBB LED: Thread has started running \n");
   while(!kthread_should_stop()){           // Returns true when kthread_stop() is called
      set_current_state(TASK_RUNNING);
      if (mode==FLASH) ledOn = !ledOn;      // Invert the LED state
      else if (mode==ON) ledOn = true;
      else ledOn = false;
      gpio_set_value(gpioLED, ledOn);       // Use the LED state to light/turn off the LED
      set_current_state(TASK_INTERRUPTIBLE);
      msleep(blinkPeriod/2);                // millisecond sleep for half of the period
   }
   printk(KERN_INFO "EBB LED: Thread has run to completion \n");
   return 0;
}

static ssize_t mode_show ( struct kobject *  kobj, struct kobj_attribute *  attr, char *  buf  )

static

A callback function to display the LED mode.

Parameters

kobj	represents a kernel object device that appears in the sysfs filesystem
attr	the pointer to the kobj_attribute struct
buf	the buffer to which to write the number of presses

Returns

return the number of characters of the mode string successfully displayed

                                                                                      {
   switch(mode){
      case OFF:   return sprintf(buf, "off\n");       // Display the state -- simplistic approach
      case ON:    return sprintf(buf, "on\n");
      case FLASH: return sprintf(buf, "flash\n");
      default:    return sprintf(buf, "LKM Error\n"); // Cannot get here
   }
}

static ssize_t mode_store ( struct kobject *  kobj, struct kobj_attribute *  attr, const char *  buf, size_t  count  )

static

A callback function to store the LED mode using the enum above.

                                                                                                           {
   // the count-1 is important as otherwise the \n is used in the comparison
   if (strncmp(buf,"on",count-1)==0) { mode = ON; }   // strncmp() compare with fixed number chars
   else if (strncmp(buf,"off",count-1)==0) { mode = OFF; }
   else if (strncmp(buf,"flash",count-1)==0) { mode = FLASH; }
   return count;
}

MODULE_AUTHOR

(

"Derek Molloy"

)

MODULE_DESCRIPTION

(

"A simple Linux LED driver LKM for the BBB"

)

module_exit

(

ebbLED_exit

)

module_init

(

ebbLED_init

)

This next calls are mandatory – they identify the initialization function and the cleanup function (as above).

MODULE_LICENSE

(

"GPL"

)

module_param	(	gpioLED	,
		uint	,
		S_IRUGO
	)

Param desc. S_IRUGO can be read/not changed.

module_param	(	blinkPeriod	,
		uint	,
		S_IRUGO
	)

Param desc. S_IRUGO can be read/not changed.

MODULE_PARM_DESC	(	gpioLED	,
		" GPIO LED number (default=49)"
	)

parameter description

MODULE_PARM_DESC	(	blinkPeriod	,
		" LED blink period in ms (min=1, default=1000, max=10000)"
	)

MODULE_VERSION

(

"0.1"

)

static ssize_t period_show ( struct kobject *  kobj, struct kobj_attribute *  attr, char *  buf  )

static

A callback function to display the LED period.

                                                                                        {
   return sprintf(buf, "%d\n", blinkPeriod);
}

static ssize_t period_store ( struct kobject *  kobj, struct kobj_attribute *  attr, const char *  buf, size_t  count  )

static

A callback function to store the LED period value.

                                                                                                             {
   unsigned int period;                     // Using a variable to validate the data sent
   sscanf(buf, "%du", &period);             // Read in the period as an unsigned int
   if ((period>1)&&(period<=10000)){        // Must be 2ms or greater, 10secs or less
      blinkPeriod = period;                 // Within range, assign to blinkPeriod variable
   }
   return period;
}

Variable Documentation

struct attribute_group attr_group

static

Initial value:

= {
   .name  = ledName,                        
   .attrs = ebb_attrs,                      
}

The attribute group uses the attribute array and a name, which is exposed on sysfs – in this case it is gpio49, which is automatically defined in the ebbLED_init() function below using the custom kernel parameter that can be passed when the module is loaded.

unsigned int blinkPeriod = 1000

static

The blink period in ms.

struct attribute* ebb_attrs[]

static

Initial value:

= {
   &period_attr.attr,                       
   &mode_attr.attr,                         
   NULL,
}

The ebb_attrs[] is an array of attributes that is used to create the attribute group below. The attr property of the kobj_attribute is used to extract the attribute struct

struct kobject* ebb_kobj

static

unsigned int gpioLED = 49

static

Default GPIO for the LED is 49.

char ledName[7] = "ledXXX"

static

Null terminated default string – just in case.

bool ledOn = 0

static

Is the LED on or off? Used for flashing.

enum modes mode = FLASH

static

Default mode is flashing.

struct kobj_attribute mode_attr = __ATTR(mode, 0666, mode_show, mode_store)

static

struct kobj_attribute period_attr = __ATTR(blinkPeriod, 0666, period_show, period_store)

static

Use these helper macros to define the name and access levels of the kobj_attributes The kobj_attribute has an attribute attr (name and mode), show and store function pointers The period variable is associated with the blinkPeriod variable and it is to be exposed with mode 0666 using the period_show and period_store functions above

struct task_struct* task

static

The pointer to the kobject.