Simple char driver. for Linux. my_first.c: headers. my_first.c: file structure. Calcolatori Elettronici e Sistemi Operativi.

Transcription

1 Calcolatori Elettronici e Sistemi Operativi Simple char driver Simple char driver for Linux Code organization my_first.c driver code: Headers Macro definitions Device structure definition Globals and module parameters Procmem interface (functions and structure) Chardev interface (functions and structure) Module initialization and cleanup Module authorship and license Makefile Building instructions my_first.c: file structure my_first.c: headers Headers Macro definitions Device structure definition Globals and module parameters Procmem interface (funcs and struct) #include <linux/module.h> #include <linux/moduleparam.h> #include <linux/init.h> #include <linux/kernel.h> #include <linux/fs.h> #include <linux/errno.h> #include <linux/slab.h> #include <linux/types.h> #include <asm/uaccess.h> #include <linux/fcntl.h> #include <linux/proc_fs.h> #include <linux/seq_file.h> #include <linux/cdev.h> Chardev interface (functions and structure) Module initialization and cleanup Module authorship and license

2 my_first.c: macro definitions my_first.c: device structure definition #define MY_FIRST_NR_DEVS 1 #define MY_FIRST_DEFAULT_SIZE (10*1024) #define IOCTL_DEV_ID 0x8A device id #define IOCTL_RESET _IO(IOCTL_DEV_ID, 0) #define IOCTL_GETSIZE _IOR(IOCTL_DEV_ID, 1, int) #define IOCTL_SETSIZE _IOW(IOCTL_DEV_ID, 2, int) build identifiers for ioctl requests struct myfirst_descr struct cdev cdev; char device structure struct mutex mutex; synchronization unsigned long size; size of vector data unsigned long ndata; actual bytes in data char *data; ; _IO(IOCTL_DEV_ID, 0) _IOR(IOCTL_DEV_ID, 1, int) _IOW(IOCTL_DEV_ID, 2, int) request id: 0 - no data passed request id: 1 - data from driver to user space (read) request id: 2 - data from user space to driver (write) size data cdev dir dir 0: none 1: write 2: read size size: size of data to read/write type type: driver id function nr. nr: id of the ioctl request ioctl request format ops struct myfirst_descr my_first.c: globals and module parameters parameters int nr_devs = MY_FIRST_NR_DEVS; int dev_size = MY_FIRST_DEFAULT_SIZE; module_param (nr_devs, int, S_IRUGO); module_param (dev_size, int, S_IRUGO); globals struct myfirst_descr *devices; int major; int first_minor; int first_dev; int registered_devs; S_IRUGO : read permission for all dev 0 dev 1 dev 2 dev 3 dev 4 devices size data cdev ops struct myfirst_descr Module init: - require a major number - allocate the needed memory for all registered devices - register char devices int init my_first_init_module(void) Only one module load at a time For an already loaded module, init function is not called (loading is aborted) Init function is allowed to be not reentrant Reentrant code: protect global (and local ) variable access protect calls to non reentrant functions do not modify code

3 int init my_first_init_module(void) int init my_first_init_module(void) int result, i; dev_t dev = 0; int err, devno; require a major number result = alloc_chrdev_region(&dev, first_minor, nr_devs, "my_first"); if (result < 0) printk(kern_warning "my_first: can't get major\n"); err = result; goto fail_alloc_chrdev_region; return 0; OK return 0; OK rollback return err; FAIL unregister_chrdev_region (first_dev, nr_devs); fail_alloc_chrdev_region: return err; FAIL release major number int init my_first_init_module(void) int result, i; dev_t dev = 0; int err, devno; require a major number result = alloc_chrdev_region(&dev, first_minor, nr_devs, "my_first"); if (result < 0) printk(kern_warning "my_first: can't get major\n"); err = result; goto fail_alloc_chrdev_region; first_dev = dev; major = MAJOR(dev); allocate memory registered_devs = nr_devs; for (i = 0; i < nr_devs; i++) devices[i].data = kmalloc(dev_size, GFP_KERNEL); if (!devices[i].data) registered_devs = i; memset (devices[i].data, 0, dev_size); devices[i].size = dev_size; devices[i].ndata = 0; mutex_init(&devices[i].mutex); cdev_init(&devices[i].cdev, &my_first_funcs); devices[i].cdev.owner = THIS_MODULE; allocate memory for i-th device stop at the first failure initialize structure prepare device registration devices = kmalloc(nr_devs * sizeof(struct myfirst_descr), GFP_KERNEL); if (!devices) err = -ENOMEM; goto fail_alloc; memset(devices, 0, nr_devs * sizeof(struct myfirst_descr)); devno = MKDEV(major, first_minor + i); err = cdev_add(&devices[i].cdev, devno, 1); device is live now device registration

4 if (err) registration failed kfree(devices[i].data); registered_devs = i; printk(kern_notice "Error %d adding my_first%d", err, i); if (registered_devs == 0) err = -ENOMEM; goto fail_alloc_buffers; proc_create_data("driver/my_first", name 0, mode (0:default) NULL, parent dir &proc_fops, NULL client data ); return 0; OK fail_alloc_buffers: kfree(devices); fail_alloc: unregister_chrdev_region(first_dev, nr_devs); fail_alloc_chrdev_region: return err; FAIL Error management Just after device registration devices device 0 device 1 device 2 device 3 device 4 Array allocated by driver (maj,min) data cdev ops struct myfirst_descr file_operations llseek read write Cleanup: - free the registered major number - free memory - unregister cleanup function is not called if initial registering failed void exit my_first_cleanup_module(void) int i; remove_proc_entry("driver/my_first", NULL); for (i = 0; i < registered_devs; i++) cdev_del(&devices[i].cdev); kfree(devices[i].data); kfree(devices); unregister_chrdev_region(first_dev, nr_devs); free memory unregister device release major number module_init(my_first_init_module); module_exit(my_first_cleanup_module); Set initialization and cleanup functions

5 ssize_t my_first_read(struct file *file, ssize_t my_first_write(struct file *file, loff_t my_first_llseek(struct file *file, long my_first_ioctl(struct file *file, int my_first_open(struct inode *inode, int my_first_release(struct inode *inode, functions to implement #define ioctl unlocked_ioctl struct file_operations my_first_funcs =.owner = THIS_MODULE,.open = my_first_open,.release = my_first_release,.read = my_first_read,.write = my_first_write,.llseek = my_first_llseek,.ioctl = my_first_ioctl, ; #define ioctl unlocked_ioctl struct file_operations my_first_funcs =.owner = THIS_MODULE,.open = my_first_open,.release = my_first_release,.read = my_first_read, ; function pointers Kernel calls open Device opened struct myfirst_descr struct myfirst_descr struct inode i_cdev struct file (maj,min) data cdev ops file_operations llseek read write struct inode i_cdev struct file (maj,min) data cdev ops file_operations llseek read write private_data private_data f_op f_op Arguments (from kernel) struct file argument will be used by next function calls (read, write, etc.) Arguments (from kernel) struct file argument will be used by next function calls (read, write, etc.)

6 Device open: - check for device-specific errors (such as hardware problems) - initialize the device on first open - update the f_op pointer, if necessary - allocate and fill data structure to be put in private_data int my_first_open(struct inode *inode, struct file *file) struct myfirst_descr *dev; dev = container_of(inode->i_cdev, struct myfirst_descr, cdev); file->private_data = dev; return 0; pointer container type container field Device close: - free data allocated in private_data - shut down the hw device on last close int my_first_release(struct inode *inode, struct file *file) return 0; Read: - put data into the user space referred by buffer - update offset ssize_t my_first_read(struct file *file, char user *buffer, size_t count, loff_t *offset) ssize_t ret; if (mutex_lock_interruptible(&d->mutex)) return -ERESTARTSYS; mutex_unlock(&d->mutex); return ret; info on device Do not overlap with other interface functions Fill the user buffer with data in d->data release exclusive access user space pointer (don't defer) enforce exclusive access to device if (*offset < d->ndata) if (*offset + count > d->ndata) count = d->ndata - *offset; if (copy_to_user(buffer, d->data+*offset, count)) ret = -EFAULT; else *offset += count; ret = count; else ret = 0; mutex_unlock(&d->mutex); return ret; update offset pointer return size of data actually read release exclusive access copy (safe) from kernel space to user space Write: - read data from the user space referred by buffer - update offset ssize_t my_first_write(struct file *file, const char user *buffer, size_t count, loff_t *offset) ssize_t ret; if (mutex_lock_interruptible(&d->mutex)) return -ERESTARTSYS; mutex_unlock(&d->mutex); return ret; info on device Do not overlap with other interface functions Fill the buffer d->data with data in user buffer release exclusive access user space pointer (don't defer) enforce exclusive access to device

7 if (*offset < d->size) if (*offset + count > d->size) count = d->size - *offset; if (copy_from_user(d->data+*offset, buffer, count)) ret = -EFAULT; else *offset += count; d->ndata = *offset; ret = count; else ret = 0; mutex_unlock(&d->mutex); return ret; update offset pointer return size of data actually written release exclusive access copy (safe) from user space to kernel space llseek: - update file->f_pos loff_t my_first_llseek(struct file *file, loff_t offset, int origin) loff_t newpos; if (mutex_lock_interruptible(&d->mutex)) return -ERESTARTSYS; switch (origin) case 0: SEEK_SET newpos = offset; case 1: SEEK_CUR newpos = file->f_pos + offset; case 2: SEEK_END newpos = d->ndata + offset; default : invalid newpos = -EINVAL; if (newpos < 0) newpos = -EINVAL; else file->f_pos = newpos; mutex_unlock(&d->mutex); return newpos; ioctl() long my_first_ioctl(struct file *file, unsigned int cmd, unsigned long arg) int err = 0, retval = 0; verify device id if (_IOC_TYPE(cmd)!= IOCTL_DEV_ID) return -ENOTTY; Macros to decode the ioctl request: _IOC_TYPE(req) _IOC_NR(req) _IOC_DIR(req) _IOC_SIZE(req) extract the driver id extract the request number extract data direction (read, write, or none) extract the data size of req.

8 ioctl() long my_first_ioctl(struct file *file, unsigned int cmd, unsigned long arg) int err = 0, retval = 0; verify device id if (_IOC_TYPE(cmd)!= IOCTL_DEV_ID) return -ENOTTY; if (mutex_lock_interruptible(&d->mutex)) return -ERESTARTSYS; user argument accessibility if (_IOC_DIR(cmd) & _IOC_READ) err =!access_ok(verify_write, (void user *)arg, _IOC_SIZE(cmd)); request is a read (data from kernel to user): check if the user buffer is writable ioctl() long my_first_ioctl(struct file *file, unsigned int cmd, unsigned long arg) int err = 0, retval = 0; verify device id if (_IOC_TYPE(cmd)!= IOCTL_DEV_ID) return -ENOTTY; if (mutex_lock_interruptible(&d->mutex)) return -ERESTARTSYS; user argument accessibility if (_IOC_DIR(cmd) & _IOC_READ) err =!access_ok(verify_write, (void user *)arg, _IOC_SIZE(cmd)); else if (_IOC_DIR(cmd) & _IOC_WRITE) err =!access_ok(verify_read, (void user *)arg, _IOC_SIZE(cmd)); request is a write (data from user to kernel): check if the user buffer is readable my_first.c: procmem interface if (err) retval = -EFAULT; else switch (cmd) case IOCTL_RESET: d->ndata = 0; case IOCTL_GETSIZE: retval = put_user(d->ndata, (int user *)arg); case IOCTL_SETSIZE: allow changes only to superuser if (!capable(cap_sys_admin)) retval = -EPERM; else retval = get_user(d->ndata, (int user *)arg); default : retval = -ENOTTY; mutex_unlock (&d->mutex); return retval; put_user: work on scalar put_user: unsafe, work on scalar get_user: work on scalar get_user: unsafe, work on scalar int read_procmem(struct file *file, int open_procmem(struct inode *inode, int release_procmem(struct inode *inode, const struct file_operations proc_fops =.open = open_procmem,.release = release_procmem,.read = read_procmem,.llseek = default_llseek, ; function pointers functions to implement

9 my_first.c: procmem interface my_first.c: procmem interface int open_procmem(struct inode *inode, struct file *file) return 0; int release_procmem(struct inode *inode, struct file *file) return 0; const struct file_operations proc_fops =.open = open_procmem,.release = release_procmem,.read = read_procmem,.llseek = default_llseek, ; int read_procmem(struct file *file, char user *buffer, size_t count, loff_t *offset) const char *h = "Hello!\n"; const int len = strlen(h); int datalen; datalen = len - *offset + 1; if (datalen > count) datalen = count; if (copy_to_user(buffer, h + *offset, datalen)) return -EFAULT; *offset += datalen; return datalen; my_first.c: module authorship and license my_first.c: exported symbols (example) MODULE_AUTHOR("Calcolatori Elettronici e Sistemi Operativi (uniud)"); MODULE_DESCRIPTION("Example"); MODULE_VERSION("1.0"); MODULE_LICENSE("Dual BSD/GPL"); int my_first_symbol_1(void)return 1; int my_first_symbol_2(void)return 2; EXPORT_SYMBOL (my_first_symbol_1); EXPORT_SYMBOL_GPL (my_first_symbol_2); Export symbols (for other modules)

10 Makefile Simple char driver # If KERNELRELEASE is defined, we've been invoked from the # kernel build system and can use its language. ifneq ($(KERNELRELEASE),) obj-m := my_first.o # Otherwise we were called directly from the command # line; invoke the kernel build system. else KERNELDIR?= /lib/modules/$(shell uname -r)/build PWD := $(shell pwd) default: $(MAKE) -C $(KERNELDIR) M=$(PWD) modules clean: -@rm my_first.ko *.o.*.o.cmd.*.ko.cmd *.mod.c modules.order Module.symvers -@rm -r.tmp_versions endif Tabulations (mandatory) Tabulation (mandatory) Makefile # insmod./my_first.ko # lsmod # cat /proc/devices grep my_first # mknod mydev c # ls /sys/module/my_first/parameters/ # cat /sys/module/my_first/parameters/dev_size # cat /sys/module/my_first/parameters/nr_devs # cat /proc/kallsyms grep my_first # echo Test string > mydev # cat mydev # rmmod my_first Test Build with: # insmod./my_first.ko nr_devs=2 # cat /proc/devices grep my_first # mknod mydev2 c # rmmod my_first make KERNELDIR=<path of kernel sources> ARCH=<target arch> CROSS_COMPILE=<prefix of cross compiler> Try to use both devices Use the major number from this command on the next one Exercise Write a char driver (mymem) to access kernel memory Read: return data in memory Memory range accessed: ARM: 0xC xC MIPS: 0x x Examples: ARM Read at file offset 0x100: return data starting at address 0xC MIPS Read at file offset 0x200: return data starting at address 0x Write: not implemented (return 0) Seek: valid if the new position is in the allowed range Test: Verify that commands: dd if=mymem of=file1 bs=1 count=128 skip= dd if=/dev/mem of=file2 bs=1 count=128 skip= Produce the same output (i.e., file1 and file2 are identical) (mymem is the device associated to this driver)