Char Drivers

1. Char Drivers Ted Baker  Andy Wang COP 5641 / CIS 4930

2. Goal • Write a complete char device driver • scull • Simple Character Utility for Loading Localities • Not hardware dependent • Just acts on some memory allocated from the kernel

3. The Design of scull • Implements various devices • scull0 to scull3 • Four device drivers, each consisting of a memory area • Global • Data contained within the device is shared by all the file descriptors that opened it • Persistent • If the device is closed and reopened, data isn’t lost

4. The Design of scull • scullpipe0 to scullpipe3 • Four FIFO devices • Act like pipes • Show how blocking and nonblocking read and write can be implemented • Without resorting to interrupts • scullpriv • Private to each virtual console

5. The Design of scull • scullsingle • Similar to scull0 • Allows only one process to use the driver at a time • sculluid • Can be opened multiple times by one user at a time • Returns “Device Busy” if another user is locking the device

6. The Design of scull • scullwuid • Blocks open if another user is locking the device

7. Major and Minor Numbers • Char devices are accessed through names in the file system • Special files/nodes in /dev >cd /dev >ls –l crw------- 1 root root 5, 1 Apr 12 16:50 console brw-rw---- 1 awang floppy 2, 0 Apr 12 16:50 fd0 brw-rw---- 1 awang floppy 2, 84 Apr 12 16:50 fd0u1040

8. Major and Minor Numbers • Char devices are accessed through names in the file system • Special files/nodes in /dev >cd /dev >ls –l crw------- 1 root root 5, 1 Apr 12 16:50 console brw-rw---- 1 awang floppy 2, 0 Apr 12 16:50 fd0 brw-rw---- 1 awang floppy 2, 84 Apr 12 16:50 fd0u1040 Major numbers Block drivers are identified by a “b” Char drivers are identified by a “c” Minor numbers

9. Major and Minor Numbers • Major number identifies the driver associated with the device • /dev/fd0 and /dev/fd0u1040 are managed by driver 2 >cd /dev >ls –l crw------- 1 root root 5, 1 Apr 12 16:50 console brw-rw---- 1 awang floppy 2, 0 Apr 12 16:50 fd0 brw-rw---- 1 awang floppy 2, 84 Apr 12 16:50 fd0u1040 • Minor number indicates which device is being referred to

10. Representation of Device Numbers • dev_t type, defined in <linux/kdev_t.h> • 12 bits for the major number • Use MAJOR(dev_t dev) to obtain the major number • 20 bits for the minor number • Use MINOR(dev_t dev) to obtain the minor number • Use MKDEV(int major, int minor) to turn them into a dev_t

11. Allocation and Deallocation • To obtain one or more device numbers, use int register_chrdev_region(dev_t first, unsigned int count, char *name); • first • Beginning device number • Minor device number is often 0 • count • Requested number of contiguous device numbers • name • Name of the device

12. Allocation and Deallocation • To obtain one or more device numbers, use int register_chrdev_region(dev_t first, unsigned int count, char *name); • Returns 0 on success, error code on failure

13. Allocation and Deallocation • Kernel can allocate a major number on the fly int alloc_chrdev_region(dev_t *dev, unsigned int firstminor, unsigned int count, char *name); • dev • Output-only parameter that holds the first number on success • firstminor • Requested first minor number • Often 0

14. Allocation and Deallocation • To free your device numbers, use int unregister_chrdev_region(dev_t first, unsigned int count);

15. Dynamic Allocation • Some major device numbers are statically assigned • See Documentation/devices.txt • To avoid conflicts, use dynamically allocation

16. scull_load Shell Script #!/bin/sh module=“scull” device=“scull” mode=“664” # invoke insmod with all arguments we got and use a pathname, # as newer modutils don’t look in . by default /sbin/insmod ./$module.ko $* || exit 1 # remove stale nodes rm –f /dev/${device}[0-3] major=$(awk “\$2==\”$module\” {print \$1}” /proc/devices) Arguments to scull_load Textbook typos

17. scull_load Shell Script mknod /dev/${device}0 c $major 0 mknod /dev/${device}1 c $major 1 mknod /dev/${device}2 c $major 2 mknod /dev/${device}3 c $major 3 # give appropriate group/permissions, and change the group. # Not all distributions have staff, some have “wheel” instead. group=“staff” grep –q ‘^staff:’ /etc/group || group=“wheel” chgrp $group /dev/${device}[0-3] chmod $mode /dev/${device}[0-3]

18. struct file One struct file per open() Overview of Data Structures struct scull_dev cdev_add() struct file_operations scull_fops struct cdev struct i_node data data

19. Some Important Data Structures • file_operations • file • inode • Defined in <linux/fs.h>

20. File Operations struct file_operations { struct module *owner; /* pointer to the module that owns the structure prevents the module from being unloaded while in use */ loff_t (*llseek) (struct file *, loff_t, int); /* change the current position in a file; returns a 64-bit offset, or a negative value on errors */ ssize_t (*read) (struct file *, char __user *, size_t, loff_t *); /* returns the number of bytes read, or a negative value on errors */ ssize_t (*aio_read) (struct kiocb *, const struct iovec *, unsigned long, loff_t); /* might return before a read completes */

21. File Operations ssize_t (*write) (struct file *, const char __user *, size_t, loff_t *); /* returns the number bytes written, or a negative value on error */ ssize_t (*aio_write) (struct kiocb *, const struct __iovec *, unsigned long, loff_t); int (*readdir) (struct file *, void *, filldir_t); /* this function pointer should be NULL for devices */ unsigned int (*poll) (struct file *, struct poll_table_struct *); /* query whether a read or write would block */ int (*ioctl) (struct inode *, struct file *, unsigned int, unsigned long); /* provides a way to issue device-specific commands (e.g., formatting) */

22. File Operations int (*mmap) (struct file *, struct vm_area_struct *); /* map a device memory to a process’s address */ int (*open) (struct inode *, struct file *); /* first operation performed on the device file; if not defined, opening always succeeds, but driver is not notified */ int (*flush) (struct file *, fl_owner_t); /* invoked when a process closes its copy of a file descriptor for a device; not to be confused with fsync */ int (*release) (struct inode *, struct file *); /* invoked when the file structure is being released */ int (*fsync) (struct file *, struct dentry *, int); /* flush pending data for a file */ int (*aio_fsync) (struct kiocb *, int); /* asynchronous version of fsync */ int (*fasync) (int, struct file *, int); /* notifies the device of a change in its FASYNC flag */

23. File Operations int (*lock) (struct file *, int, struct file_lock *); /* file locking for regular files, almost never implemented by device drivers */ ssize_t (*splice_read) (struct file *, loff_t *, struct pipe_inode_info *, size_t, unsigned int); ssize_t (*splice_write) (struct pipe_inode_info *, file *, loff_t *, size_t, unsigned int); /* implement gather/scatter read and write operations */ ssize_t (*sendfile) (struct file *, loff_t *, size_t, read_actor_t, void *); /* moves the data from one file descriptor to another usually not used by device drivers */ ssize_t (*sendpage) (struct file *, struct page *, int, size_t, loff_t *, int); /* called by kernel to send data, one page at a time usually not used by device drivers */

24. File Operations unsigned long (*get_unmapped_area) (struct file *, unsigned long, unsigned long, unsigned long, unsigned long); /* finds a location in the process’s memory to map in a memory segment on the underlying device; used to enforce alignment requirements; most drivers do not use this function */ int (*check_flags) (int); /* allows a module to check flags passed to an fcntl call */ int (*dir_notify) (struct file *, unsigned long); /* invoked when an application uses fcntl to request directory change notifications; usually not used by device drivers */ };

25. scull device driver • Implements only the most important methods struct file_operations scull_fops = { .owner = THIS_MODULE, .llseek = scull_llseek, .read = scull_read, .write = scull_write, .ioctl = scull_ioctl, .open = scull_open, .release = scull_release, };

26. The File Structure • struct file • Nothing to do with the FILE pointers • Defined in the C Library • Represents an open file • A pointer to file is often called filp

27. The File Structure • Some important fields • mode_t f_mode; • Identifies the file as either readable or writable • loff_t f_pos; • Current reading/writing position (64-bits) • unsigned int f_flags; • File flags, such as O_RDONLY, O_NONBLOCK, O_SYNC

28. The File Structure • Some important fields • struct file_operations *f_op; • Operations associated with the file • Dynamically replaceable pointer • Equivalent of method overriding in OO programming • void *private data; • Can be used to store additional data structures • Needs to be freed during the release method

29. The File Structure • Some important fields • struct dentry *f_dentry; • Directory entry associated with the file • Used to access the inode data structure • filp->f_dentry->d_inode

30. The i-node Structure • There can be numerous file structures (multiple open descriptors) for a single file • Only one inode structure per file

31. The i-node Structure • Some important fields • dev_t i_rdev; • Contains device number • For portability, use the following macros • unsigned int iminor(struct inode *inode); • unsigned int imajor(struct inode *inode); • struct cdev *i_cdev; • Contains a pointer to the data structure that refers to a char device file

32. Char Device Registration • Need to allocate struct cdev to represent char devices #include <linux/cdev.h> /* first way */ struct cdev *my_cdev = cdev_alloc(); my_cdev->ops = &my_fops; /* second way, for embedded cdev structure, call this function */ void cdev_init(struct cdev *cdev, struct file_operations *fops);

33. Char Device Registration • Either way • Need to initializefile_operations and setownertoTHIS_MODULE • Inform the kernel by calling int cdev_add(struct cdev *dev, dev_t num, unsigned int count); • num: first device number • count: number of device numbers • Remove a char device, call this function void cdev_del(struct cdev *dev);

34. scull’s Memory Usage struct scull_qset { void **data; struct scull_qset *next; }; SCULL_QUANTUM = 1KB Quantum set, SCULL_QSET = 1K quanta

35. Device Registration in scull • scull represents each device with struct scull_dev struct scull_dev { struct scull_qset *data; /* pointer to first quantum set */ int quantum; /* the current quantum size */ int qset; /* the current array size */ unsigned long size; /* amount of data stored here */ unsigned int access_key; /* used by sculluid & scullpriv */ struct semaphore sem; /* mutual exclusion semaphore */ struct cdev cdev; /* char device structure */ };

36. Char Device Initialization Steps • Register device driver name and numbers • Allocation of the struct scull_devobjects • Initialization of scull cdev objects • Calls cdev_init to initialize the struct cdev component • Sets cdev.owner to this module • Sets cdev.ops to scull_fops • Calls cdev_add to complete registration

37. Char Device Cleanup Steps • Clean up internal data structures • cdev_delscull devices • Deallocate scull devices • Unregister device numbers

38. Device Registration in scull • To add struct scull_dev to the kernel static void scull_setup_cdev(struct scull_dev *dev, int index) { int err, devno = MKDEV(scull_major, scull_minor + index); cdev_init(&dev->cdev, &scull_fops); dev->cdev.owner = THIS_MODULE; dev->cdev.ops = &scull_fops; /* redundant? */ err = cdev_add(&dev->cdev, devno, 1); if (err) { printk(KERN_NOTICE “Error %d adding scull%d”, err, index); } }

39. The open Method • In most drivers, open should • Check for device-specific errors • Initialize the device (if opened for the first time) • Update the f_op pointer, as needed • Allocate and fill data structure in filp->private_data

40. The open Method int scull_open(struct inode *inode, struct file *file) { struct scull_dev *dev; /* device info */ /* #include <linux/kernel.h> container_of(pointer, container_type, container_field returns the starting address of struct scull_dev */ dev = container_of(inode->i_cdev, struct scull_dev, cdev); filp->private_data = dev; /* now trim to 0 the length of the device if open was write-only */ if ((filp->f_flags & O_ACCMODE) == O_WRONLY) { scull_trim(dev); /* ignore errors */ } return 0; /* success */ }

41. The release Method • Deallocate filp->private_data • Shut down the device on last close • One release call per open • Potentially multiple close calls per open due to fork/dup • scull has no hardware to shut down int scull_release(struct inode *inode, struct file *filp) { return 0; }

42. scull’s Memory Usage • Dynamically allocated • #include <linux/slab.h> • void *kmalloc(size_t size, int flags); • Allocate size bytes of memory • For now, always use GFP_KERNEL • Return a pointer to the allocated memory, or NULL if the allocation fails • void kfree(void *ptr);

43. scull’s Memory Usage struct scull_qset { void **data; struct scull_qset *next; }; SCULL_QUANTUM = 1KB Quantum set, SCULL_QSET = 1K quanta

44. scull’s Memory Usage int scull_trim(struct scull_dev *dev) { struct scull_qset *next, *dptr; int qset = dev->qset; /* dev is not NULL */ int i; for (dptr = dev->data; dptr; dptr = next) { if (dptr->data) { for (i = 0; i < qset; i++) kfree(dptr->data[i]); kfree(dptr->data); dptr->data = NULL; } next = dptr->next; kfree(dptr); } dev->size = 0; dev->data = NULL; dev->quantum = scull_quantum; dev->qset = scull_qset; return 0; }

45. Race Condition Protection • Different processes may try to execute operations on the same scull device concurrently • There would be trouble if both were able to access the data of the same device at once • scull avoids this using per-device semaphore • All operations that touch the device’s data need to lock the semaphore

46. Race Condition Protection • Some semaphore usage rules • No double locking • No double unlocking • Always lock at start of critical section • Don’t release until end of critical section • Don’t forget to release before exiting • return, break, or goto • If you need to hold two locks at once, lock them in a well-known order, unlock them in the reverse order (e.g., lock1, lock2, unlock2, unlock1)

47. Semaphore Usage Examples • Initialization • init_MUTEX(&scull_devices[i].sem); • Critial section if (down_interruptible(&dev->sem)) return –ERESTARTSYS; scull_trim(dev); /* ignore errors */ up(&dev->sem); Can be interrupted by signals (e.g. Ctrl-C)

48. Semaphore vs. Spinlock • Semaphores may block • Calling process is blocked until the lock is released • Spinlock may spin (loop) • Calling processor spins until the lock is released • Never call “down” unless it is OK for the current thread to block • Do not call “down” while holding a spinlock • Do not call “down” within an interrupt handler

49. read and write ssize_t (*read) (struct file *filp, char __user *buff, size_t count, loff_t *offp); ssize_t (*write) (struct file *filp, const char __user *buff, size_t count, loff_t *offp); • filp: file pointer • buff: a user-space pointer • May not be valid in kernel mode • Might be swapped out • Could be malicious • count: size of requested transfer • offp: file position pointer

50. read and write • To safely access user-space buffer • Use kernel-provided functions • #include <asm/uaccess.h> • unsigned long copy_to_user(void __user *to, const void *from, unsigned long count); • unsigned long copy_from_user(void *to, const void __user *from, unsigned long count); • Check whether the user-space pointer is valid • Return the amount of memory still to be copied