ebbcharmutex.c File Reference

An introductory character driver to support the second article of my series on Linux loadable kernel module (LKM) development. This module maps to /dev/ebbchar and comes with a helper C program that can be run in Linux user space to communicate with this the LKM. This version has mutex locks to deal with synchronization problems. More...

#include <linux/init.h>
#include <linux/module.h>
#include <linux/device.h>
#include <linux/kernel.h>
#include <linux/fs.h>
#include <asm/uaccess.h>
#include <linux/mutex.h>

Include dependency graph for ebbcharmutex.c:

Macros
#define	DEVICE_NAME   "ebbchar"
	The device will appear at /dev/ebbchar using this value. More...
#define	CLASS_NAME   "ebb"
	The device class – this is a character device driver. More...

Functions
	MODULE_LICENSE ("GPL")
	The license type – this affects available functionality. More...
	MODULE_AUTHOR ("Derek Molloy")
	The author – visible when you use modinfo. More...
	MODULE_DESCRIPTION ("A simple Linux char driver for the BBB")
	The description – see modinfo. More...
	MODULE_VERSION ("0.1")
	A version number to inform users. More...
static	DEFINE_MUTEX (ebbchar_mutex)
	Macro to declare a new mutex. More...
static int	dev_open (struct inode *, struct file *)
	The prototype functions for the character driver – must come before the struct definition. More...
static int	dev_release (struct inode *inodep, struct file *filep)
	The device release function that is called whenever the device is closed/released by the userspace program. More...
static ssize_t	dev_read (struct file *filep, char *buffer, size_t len, loff_t *offset)
	This function is called whenever device is being read from user space i.e. data is being sent from the device to the user. In this case is uses the copy_to_user() function to send the buffer string to the user and captures any errors. More...
static ssize_t	dev_write (struct file *filep, const char *buffer, size_t len, loff_t *offset)
	This function is called whenever the device is being written to from user space i.e. data is sent to the device from the user. The data is copied to the message[] array in this LKM using message[x] = buffer[x]. More...
static int __init	ebbchar_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. More...
static void __exit	ebbchar_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 (ebbchar_init)
	A module must use the module_init() module_exit() macros from linux/init.h, which identify the initialization function at insertion time and the cleanup function (as listed above) More...
	module_exit (ebbchar_exit)

Variables
static int	majorNumber
	Store the device number – determined automatically. More...
static char	message [256] = {0}
	Memory for the string that is passed from userspace. More...
static short	size_of_message
	Used to remember the size of the string stored. More...
static int	numberOpens = 0
	Counts the number of times the device is opened. More...
static struct class *	ebbcharClass = NULL
	The device-driver class struct pointer. More...
static struct device *	ebbcharDevice = NULL
	The device-driver device struct pointer. More...
static struct file_operations	fops

Detailed Description

An introductory character driver to support the second article of my series on Linux loadable kernel module (LKM) development. This module maps to /dev/ebbchar and comes with a helper C program that can be run in Linux user space to communicate with this the LKM. This version has mutex locks to deal with synchronization problems.

Author

Derek Molloy

Date

7 April 2015

Version

0.1

See also

http://www.derekmolloy.ie/ for a full description and follow-up descriptions.

Macro Definition Documentation

#define CLASS_NAME   "ebb"

The device class – this is a character device driver.

#define DEVICE_NAME   "ebbchar"

The device will appear at /dev/ebbchar using this value.

Function Documentation

static DEFINE_MUTEX ( ebbchar_mutex  )

static

Macro to declare a new mutex.

static int dev_open ( struct inode *  inodep, struct file *  filep  )

static

The prototype functions for the character driver – must come before the struct definition.

The device open function that is called each time the device is opened This will only increment the numberOpens counter in this case.

Parameters

inodep	A pointer to an inode object (defined in linux/fs.h)
filep	A pointer to a file object (defined in linux/fs.h)

                                                             {

   if(!mutex_trylock(&ebbchar_mutex)){                  // Try to acquire the mutex (returns 0 on fail)
        printk(KERN_ALERT "EBBChar: Device in use by another process");
        return -EBUSY;
   }
   numberOpens++;
   printk(KERN_INFO "EBBChar: Device has been opened %d time(s)\n", numberOpens);
   return 0;
}

static ssize_t dev_read ( struct file *  filep, char *  buffer, size_t  len, loff_t *  offset  )

static

This function is called whenever device is being read from user space i.e. data is being sent from the device to the user. In this case is uses the copy_to_user() function to send the buffer string to the user and captures any errors.

Parameters

filep	A pointer to a file object (defined in linux/fs.h)
buffer	The pointer to the buffer to which this function writes the data
len	The length of the b
offset	The offset if required

                                                                                     {
   int error_count = 0;
   // copy_to_user has the format ( * to, *from, size) and returns 0 on success
   error_count = copy_to_user(buffer, message, size_of_message);

   if (error_count==0){           // success!
      printk(KERN_INFO "EBBChar: Sent %d characters to the user\n", size_of_message);
      return (size_of_message=0); // clear the position to the start and return 0
   }
   else {
      printk(KERN_INFO "EBBChar: Failed to send %d characters to the user\n", error_count);
      return -EFAULT;      // Failed -- return a bad address message (i.e. -14)
   }
}

static int dev_release ( struct inode *  inodep, struct file *  filep  )

static

The device release function that is called whenever the device is closed/released by the userspace program.

Parameters

inodep	A pointer to an inode object (defined in linux/fs.h)
filep	A pointer to a file object (defined in linux/fs.h)

                                                                {
   mutex_unlock(&ebbchar_mutex);                      // release the mutex (i.e., lock goes up)
   printk(KERN_INFO "EBBChar: Device successfully closed\n");
   return 0;
}

static ssize_t dev_write ( struct file *  filep, const char *  buffer, size_t  len, loff_t *  offset  )

static

This function is called whenever the device is being written to from user space i.e. data is sent to the device from the user. The data is copied to the message[] array in this LKM using message[x] = buffer[x].

Parameters

filep	A pointer to a file object
buffer	The buffer to that contains the string to write to the device
len	The length of the array of data that is being passed in the const char buffer
offset	The offset if required

                                                                                            {

   sprintf(message, "%s(%d letters)", buffer, len);   // appending received string with its length
   size_of_message = strlen(message);                 // store the length of the stored message
   printk(KERN_INFO "EBBChar: Received %d characters from the user\n", len);
   return len;
}

static void __exit ebbchar_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.

                                     {
   mutex_destroy(&ebbchar_mutex);                       // destroy the dynamically-allocated mutex
   device_destroy(ebbcharClass, MKDEV(majorNumber, 0)); // remove the device
   class_unregister(ebbcharClass);                      // unregister the device class
   class_destroy(ebbcharClass);                         // remove the device class
   unregister_chrdev(majorNumber, DEVICE_NAME);         // unregister the major number
   printk(KERN_INFO "EBBChar: Goodbye from the LKM!\n");
}

static int __init ebbchar_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.

Returns

returns 0 if successful

                                    {
   printk(KERN_INFO "EBBChar: Initializing the EBBChar LKM\n");

   // Try to dynamically allocate a major number for the device -- more difficult but worth it
   majorNumber = register_chrdev(0, DEVICE_NAME, &fops);
   if (majorNumber<0){
      printk(KERN_ALERT "EBBChar failed to register a major number\n");
      return majorNumber;
   }
   printk(KERN_INFO "EBBChar: registered correctly with major number %d\n", majorNumber);

   // Register the device class
   ebbcharClass = class_create(THIS_MODULE, CLASS_NAME);
   if (IS_ERR(ebbcharClass)){           // Check for error and clean up if there is
      unregister_chrdev(majorNumber, DEVICE_NAME);
      printk(KERN_ALERT "Failed to register device class\n");
      return PTR_ERR(ebbcharClass);     // Correct way to return an error on a pointer
   }
   printk(KERN_INFO "EBBChar: device class registered correctly\n");

   // Register the device driver
   ebbcharDevice = device_create(ebbcharClass, NULL, MKDEV(majorNumber, 0), NULL, DEVICE_NAME);
   if (IS_ERR(ebbcharDevice)){          // Clean up if there is an error
      class_destroy(ebbcharClass);      // Repeated code but the alternative is goto statements
      unregister_chrdev(majorNumber, DEVICE_NAME);
      printk(KERN_ALERT "Failed to create the device\n");
      return PTR_ERR(ebbcharDevice);
   }
   printk(KERN_INFO "EBBChar: device class created correctly\n"); // Made it! device was initialized
   mutex_init(&ebbchar_mutex);          // Initialize the mutex dynamically
   return 0;
}

MODULE_AUTHOR

(

"Derek Molloy"

)

The author – visible when you use modinfo.

MODULE_DESCRIPTION

(

"A simple Linux char driver for the BBB"

)

The description – see modinfo.

module_exit

(

ebbchar_exit

)

module_init

(

ebbchar_init

)

A module must use the module_init() module_exit() macros from linux/init.h, which identify the initialization function at insertion time and the cleanup function (as listed above)

MODULE_LICENSE

(

"GPL"

)

The license type – this affects available functionality.

MODULE_VERSION

(

"0.1"

)

A version number to inform users.

Variable Documentation

struct class* ebbcharClass = NULL

static

The device-driver class struct pointer.

struct device* ebbcharDevice = NULL

static

The device-driver device struct pointer.

struct file_operations fops

static

Initial value:

=
{
   .open = dev_open,
   .read = dev_read,
   .write = dev_write,
   .release = dev_release,
}

Devices are represented as file structure in the kernel. The file_operations structure from /linux/fs.h lists the callback functions that you wish to associated with your file operations using a C99 syntax structure. char devices usually implement open, read, write and release calls

int majorNumber

static

Store the device number – determined automatically.

char message[256] = {0}

static

Memory for the string that is passed from userspace.

int numberOpens = 0

static

Counts the number of times the device is opened.

short size_of_message

static

Used to remember the size of the string stored.