The Importance of the container_of Macro in a Linux Character Device Driver

In this article, we explain the importance of the container_of macro in a linux character device driver.

The container_of macro is used especially used with linux device drivers with multiple character devices.

Typically, we use the container_of macro is access the device private data of each character device.

So how does this all work?

Let's say that we create a structure in C that represents the device private data for each character device.

Let's say below is the structure for the device private data that each character device will use.


struct pcdev_private_data {         char *buffer;         unsigned size;         const char *serial_number;         int perm;         struct cdev cdev; };

So let's say that for each character device that we create, we want these private data values included. This includes the buffer address, the size of the data, the serial number, the permission data, and the cdev structure of the device.

You see that one of the member elements of this pcdev_private_data structure is cdev.

cdev is a member element of the the pcdev_private_data structure, which serves as the container for the cdev member element. The pcdev_private_data is the container for this member element.

The container_of comes in good use for us because through the inode structure, we can get the cdev structure of a character device.

We can then use the container_of macro to get the container of the element, which then a allows us to access all the other member elements, such as the buffer address, the size of the data, serial mnumber, the permissions, etc.

The container_of macro allows us to get the address of the containing structure by taking an address of one of its member elements. As the name implies, the container_of macro gives the container address of the member element.

The container_of macro takes in 3 arguments, which are the pointer, the type of the container, and the name of the member the pointer refers to.

This is shown below.


container_of(pointer, the type of the container, the name of the member element)

The open file operation method will contain the container_of macro statement, because this is the file operation which is first run when a character device is used. A user has to first open it.

The code in our open file operation method is shown below.


int pcd_open(struct inode *inode, struct file *filp) {         int ret;         struct pcdev_private_data *pcdev_data;         pcdev_data= container_of(inode->i_cdev,struct pcdev_private_data,cdev);         filp->private_data = pcdev_data;         ret = check_permission(pcdev_data->perm,filp->f_mode);         (!ret)?pr_info("open was successful\n"):pr_info("open was unsucessful\n");         return ret; } 

So let's go through this code in the open file operation.

So you see that the open file operation takes in 2 parameters, the inode structure and the file structure.

The inode structure is important because each character device has a unique cdev structure; so that allow s us to single out each character device in a linux device driver where we create multiple character devices.

The inode structure has a property named i_cdev, which represents the pointer of the cdev structure for the particular character device which was opened.

This is the first parameter of the container_of macro; thus, for this parameter, we specify, inode->i_cdev

Next, we specify the type of the container structure. In our case, this would be, struct pcdev_private_data

Lastly, you specify the name of the member element of the containing structure that the first parameter points to. In this case, it would be, cdev.

Notice that before have this container_of statement, we create an instance of the private data structure with the line, struct pcdev_private_data *pcdev_data;

We then set this instance to the container_of statement.

So what we've done here is now we have all the private data of the character device within this variable.

This is how the container_of macro works.

We can create a structure and put a unique identifying member element within this structure, which is usually the cdev structure of a device, and we can access all the properties of this structure through the container_of macro. This is commonly done with device private data in a linux device driver. The device private data is essential in a linux device driver, because it gives us unique, needed information about each character device.

For example, let's look at the full program for a linux device driver with multiple character devices.


#include<linux/module.h> #include<linux/fs.h> #include<linux/cdev.h> #include<linux/device.h> #include<linux/kdev_t.h> #include<linux/uaccess.h> #undef pr_fmt #define pr_fmt(fmt) "%s :" fmt,__func__ #define DEV1_MEM_SIZE 1024 #define DEV2_MEM_SIZE 512 #define DEV3_MEM_SIZE 1024 #define DEV4_MEM_SIZE 512 #define NO_OF_DEVICES 4 #define RDONLY 0x01 #define WRONLY 0x10 #define RDWR   0x11 char device_buffer_dev1[DEV1_MEM_SIZE]; char device_buffer_dev2[DEV2_MEM_SIZE]; char device_buffer_dev3[DEV3_MEM_SIZE]; char device_buffer_dev4[DEV4_MEM_SIZE]; /* Device private data structure */ struct pcdev_private_data {         char *buffer;         unsigned size;         const char *serial_number;         int perm;         struct cdev cdev; }; /* Driver private data structure */ struct pcdrv_private_data {         int total_devices;         dev_t device_number; /* holds device number */         struct class *class_pcd;         struct device *device_pcd;         struct pcdev_private_data pcdev_data[NO_OF_DEVICES]; }; struct pcdrv_private_data pcdrv_data = {         .total_devices= NO_OF_DEVICES,         .pcdev_data = {                 [0] = {                         .buffer= device_buffer_dev1,                         .size= DEV1_MEM_SIZE,   .serial_number= "PCDEV1XYZ123",                         .perm= RDONLY                 },                 [1] = {                         .buffer= device_buffer_dev2,                         .size= DEV2_MEM_SIZE,                         .serial_number= "PCDEV2XYZ123",                         .perm= WRONLY                 },                 [2] = {                         .buffer= device_buffer_dev3,                         .size= DEV3_MEM_SIZE,                         .serial_number= "PCDEV3XYZ123",                         .perm= RDWR                 },                 [3] = {                         .buffer= device_buffer_dev4,                         .size= DEV4_MEM_SIZE,                         .serial_number= "PCDEV4XYZ123",                         .perm= RDWR                 }         } }; //File operation methods loff_t pcd_lseek(struct file *filp, loff_t offset, int whence) {         struct pcdev_private_data *pcdev_data = (struct pcdev_private_data*)filp->private_data;         int max_size= pcdev_data->size;         loff_t temp;         pr_info("lseek requested \n");         pr_info("Current file position= %lld\n",filp->f_pos);         switch(whence)         {                 case SEEK_SET:                         if((offset > max_size) || (offset <0))                                 return -EINVAL;                         filp->f_pos = offset;                         break;                 case SEEK_CUR:                         temp= filp->f_pos + offset;                         if((temp > max_size) || (temp <0))                                 return -EINVAL;                         filp->f_pos = temp;                         break;                 case SEEK_END:                         temp= max_size + offset;                         if((temp > max_size) || (temp < 0))                                 return -EINVAL;                         filp->f_pos = temp;                         break;                 default:                         return -EINVAL;         }         pr_info("New file position: %lld\n",filp->f_pos);         return filp->f_pos; } ssize_t pcd_read(struct file *filp, char __user *buff, size_t count, loff_t *f_pos) {         struct pcdev_private_data *pcdev_data = (struct pcdev_private_data*)filp->private_data;  int max_size= pcdev_data->size;         pr_info("read requested for %zu bytes \n", count);         pr_info("Current file position = %lld\n", *f_pos);         /* Adjust the count */         if((*f_pos + count) > max_size)                 count= max_size - *f_pos;         /*copy to user */         if(copy_to_user(buff,pcdev_data->buffer+(*f_pos),count)) {                 return -EFAULT;         }         /* update the current file position */         *f_pos += count;         pr_info("Number of bytes successfully read= %zu\n", count);         pr_info("Updated file position= %lld\n", *f_pos);         /* Return the number of bytes which have been successfully read */         return count; } ssize_t pcd_write(struct file *filp, const char __user *buff, size_t count, loff_t *f_pos) {         struct pcdev_private_data *pcdev_data = (struct pcdev_private_data*)filp->private_data;         int max_size= pcdev_data->size;         pr_info("Write requested for %zu bytes \n", count);         pr_info("Current file position = %lld\n", *f_pos);         /* Adjust the count */         if((*f_pos + count) > max_size)                 count= max_size - *f_pos;         if(!count)                 return -ENOMEM;         /*copy from  user */         if(copy_from_user(pcdev_data->buffer+(*f_pos),buff,count)) {                 return -EFAULT;         }         /* update the current file position */         *f_pos += count;  pr_info("Number of bytes successfully written= %zu\n", count);         pr_info("Updated file position= %lld\n", *f_pos);         /* Return the number of bytes which have been successfully written*/         return count; } int check_permission(int dev_perm, int acc_mode) {         if(dev_perm == RDWR)                 return 0;         //ensures readonly access         if ((dev_perm == RDONLY) && ((acc_mode & FMODE_READ) && !(acc_mode & FMODE_WRITE)))                 return 0;         //ensures writeonly access         if ((dev_perm == WRONLY) && ((acc_mode & FMODE_WRITE) && !(acc_mode & FMODE_READ)))                 return 0;         return -EPERM; } int pcd_open(struct inode *inode, struct file *filp) {         int ret;         int minor_n;         struct pcdev_private_data *pcdev_data;         minor_n= MINOR(inode->i_rdev);         pr_info("minor access = %d\n",minor_n);         pcdev_data= container_of(inode->i_cdev,struct pcdev_private_data,cdev);         filp->private_data = pcdev_data;         ret = check_permission(pcdev_data->perm,filp->f_mode);         (!ret)?pr_info("open was successful\n"):pr_info("open was unsucessful\n");         return ret; } int pcd_release(struct inode *inode, struct file *filp) {         pr_info("Close was successful\n");         return 0; } //file operations of the driver struct file_operations pcd_fops = {         .open= pcd_open,         .write= pcd_write,         .read= pcd_read,         .llseek= pcd_lseek,         .release= pcd_release,         .owner= THIS_MODULE }; static int __init pcd_driver_init(void) {         int ret;         int i;         //Dynamically allocate a device number         ret= alloc_chrdev_region(&pcdrv_data.device_number, 0,NO_OF_DEVICES,"pcdevs");         if(ret < 0) {                 pr_err("Alloc chdrdev failed\n");                 goto out;         }         /*Create device class under /sys/class */         pcdrv_data.class_pcd= class_create(THIS_MODULE,"pcd_class");         if(IS_ERR(pcdrv_data.class_pcd)){                 pr_err("Class creation failed\n");                 ret= PTR_ERR(pcdrv_data.class_pcd);                 goto unreg_chrdev;         }         for(i=0;i<NO_OF_DEVICES;i++){                 pr_info("Device number <major>:<minor>= %d:%d\n", MAJOR(pcdrv_data.device_number+i),MINOR(pcdrv_data.device_number+i));                 //Initialize the cdev structure with fops                 cdev_init(&pcdrv_data.pcdev_data[i].cdev,&pcd_fops);                 pcdrv_data.pcdev_data[i].cdev.owner= THIS_MODULE;                 //Register a device (cdev structure) with VFS                 ret= cdev_add(&pcdrv_data.pcdev_data[i].cdev,pcdrv_data.device_number+i,1);                 if(ret < 0){                         pr_err("Cdev add failed\n");                         goto cdev_del;                 }                 //Populate the sysfs with device information                 pcdrv_data.device_pcd= device_create(pcdrv_data.class_pcd, NULL,pcdrv_data.device_number+i, NULL,"pcdev-%d",i+1);                 if(IS_ERR(pcdrv_data.device_pcd)){                         pr_err("Device create failed\n");                         ret= PTR_ERR(pcdrv_data.device_pcd);                         goto class_del;                 }         }                 pr_info("Module init was successful\n");                 return 0; cdev_del: class_del:         for(;i>=0;i--){                 device_destroy(pcdrv_data.class_pcd,pcdrv_data.device_number+i);                 cdev_del(&pcdrv_data.pcdev_data[i].cdev);         }         class_destroy(pcdrv_data.class_pcd); unreg_chrdev:         unregister_chrdev_region(pcdrv_data.device_number, NO_OF_DEVICES); out:         pr_info("Module insertion failed\n");         return ret; } static void __exit pcd_driver_cleanup(void) {         int i;         for(i=0;i<NO_OF_DEVICES;i++){                 device_destroy(pcdrv_data.class_pcd,pcdrv_data.device_number+i);                 cdev_del(&pcdrv_data.pcdev_data[i].cdev);         }         class_destroy(pcdrv_data.class_pcd);         unregister_chrdev_region(pcdrv_data.device_number,NO_OF_DEVICES);         pr_info("module unloaded\n"); } module_init(pcd_driver_init); module_exit(pcd_driver_cleanup); MODULE_LICENSE("GPL"); MODULE_AUTHOR("David Hylton"); MODULE_DESCRIPTION("A pseudo character driver for multiple character devices");                            

You don't have to go through all of this code.

But in the program above, we created a linux device driver with 4 character devices.

These 4 character devices have different features. They have different sizes. For example, character device 1 is 1024, character device 2 is 512, character device 3 is 1024, and character device 4 is 512 (bytes).

Being that this size data is placed within the private data of the device, we can retrieve all of this data and can know the data size for each character device.

Another type of private data that each device has are their own serial numbers. Character device 1 has a serial number of PCDEV1XYZ123, character device 2 has a serial number of PCDEV2XYZ123, character device 3 has a serial number of PCDEV3XYZ123, and character device 4 has a serial number of PCDEV4XYZ123.

Another type of private data that each device has are their own permissions, meaning the character device can be readonly, writeonly, or read/write. In our example, character device 1 is readonly, character device 2 is writeonly, character device 3 is read/write, and character device 4 is read/write.

All of this data can be obtained by creating an instance of the private data structure and access the elements of this structure through the container_of macro.

Again, the open file operation is the best place to put this container_of macro code, because it is the first file operation that is always run when accessing a character device. Once we are able to get this data, we save it to the file structure.

Since all file operation methods have the file structure as a parameter and the file structure stays open throughout a program once it is initially opened, we can access this device private data in any other file operation such as the read or write file operation.

So this illustrates the importance of the container_of macro in a linux character device driver and how it allows us to access device private data for each individual device.

Related Resources