==================== Block Device Drivers ==================== Lab objectives ============== * acquiring knowledge about the behavior of the I/O subsystem on Linux * hands-on activities in structures and functions of block devices * acquiring basic skills for utilizing the API for block devices, by solving exercises Overview ======== Block devices are characterized by random access to data organized in fixed-size blocks. Examples of such devices are hard drives, CD-ROM drives, RAM disks, etc. The speed of block devices is generally much higher than the speed of character devices, and their performance is also important. This is why the Linux kernel handles differently these 2 types of devices (it uses a specialized API). Working with block devices is therefore more complicated than working with character devices. Character devices have a single current position, while block devices must be able to move to any position in the device to provide random access to data. To simplify work with block devices, the Linux kernel provides an entire subsystem called the block I/O (or block layer) subsystem. From the kernel perspective, the smallest logical unit of addressing is the block. Although the physical device can be addressed at sector level, the kernel performs all disk operations using blocks. Since the smallest unit of physical addressing is the sector, the size of the block must be a multiple of the size of the sector. Additionally, the block size must be a power of 2 and can not exceed the size of a page. The size of the block may vary depending on the file system used, the most common values being 512 bytes, 1 kilobytes and 4 kilobytes. Register a block I/O device =========================== To register a block I/O device, function :c:func:`register_blkdev` is used. To deregister a block I/O device, function :c:func:`unregister_blkdev` is used. Starting with version 4.9 of the Linux kernel, the call to :c:func:`register_blkdev` is optional. The only operations performed by this function are the dynamic allocation of a major (if the major argument is 0 when calling the function) and creating an entry in :file:`/proc/devices`. In future kernel versions it may be removed; however, most drivers still call it. Usually, the call to the register function is performed in the module initialization function, and the call to the deregister function is performed in the module exit function. A typical scenario is presented below: .. code-block:: c #include #define MY_BLOCK_MAJOR 240 #define MY_BLKDEV_NAME "mybdev" static int my_block_init(void) { int status; status = register_blkdev(MY_BLOCK_MAJOR, MY_BLKDEV_NAME); if (status < 0) { printk(KERN_ERR "unable to register mybdev block device\n"); return -EBUSY; } //... } static void my_block_exit(void) { //... unregister_blkdev(MY_BLOCK_MAJOR, MY_BLKDEV_NAME); } Register a disk =============== Although the :c:func:`register_blkdev` function obtains a major, it does not provide a device (disk) to the system. For creating and using block devices (disks), a specialized interface defined in :file:`linux/genhd.h` is used. The useful functions defined in :file:`linux/genhd.h` are to register /allocate a disk, add it to the system, and de-register /unmount the disk. The :c:func:`alloc_disk` function is used to allocate a disk, and the :c:func:`del_gendisk` function is used to deallocate it. Adding the disk to the system is done using the :c:func:`add_disk` function. The :c:func:`alloc_disk` and :c:func:`add_disk` functions are typically used in the module initialization function, and the :c:func:`del_gendisk` function in the module exit function. .. code-block:: c #include #include #define MY_BLOCK_MINORS 1 static struct my_block_dev { struct gendisk *gd; //... } dev; static int create_block_device(struct my_block_dev *dev) { dev->gd = alloc_disk(MY_BLOCK_MINORS); //... add_disk(dev->gd); } static int my_block_init(void) { //... create_block_device(&dev); } static void delete_block_device(struct my_block_dev *dev) { if (dev->gd) del_gendisk(dev->gd); //... } static void my_block_exit(void) { delete_block_device(&dev); //... } As with character devices, it is recommended to use :c:type:`my_block_dev` structure to store important elements describing the block device. Note that immediately after calling the :c:func:`add_disk` function (actually even during the call), the disk is active and its methods can be called at any time. As a result, this function should not be called before the driver is fully initialized and ready to respond to requests for the registered disk. It can be noticed that the basic structure in working with block devices (disks) is the :c:type:`struct gendisk` structure. After a call to :c:func:`del_gendisk`, the :c:type:`struct gendisk` structure may continue to exist (and the device operations may still be called) if there are still users (an open operation was called on the device but the associated release operation has not been called). One solution is to keep the number of users of the device and call the :c:func:`del_gendisk` function only when there are no users left of the device. :c:type:`struct gendisk` structure ================================== The :c:type:`struct gendisk` structure stores information about a disk. As stated above, such a structure is obtained from the :c:func:`alloc_disk` call and its fields must be filled before it is sent to the :c:func:`add_disk` function. The :c:type:`struct gendisk` structure has the following important fields: * :c:member:`major`, :c:member:`first_minor`, :c:member:`minor`, describing the identifiers used by the disk; a disk must have at least one minor; if the disk allows the partitioning operation, a minor must be allocated for each possible partition * :c:member:`disk_name`, which represents the disk name as it appears in :file:`/proc/partitions` and in sysfs (:file:`/sys/block`) * :c:member:`fops`, representing operations associated with the disk * :c:member:`queue`, which represents the queue of requests * :c:member:`capacity`, which is disk capacity in 512 byte sectors; it is initialized using the :c:func:`set_capacity` function * :c:member:`private_data`, which is a pointer to private data An example of filling a :c:type:`struct gendisk` structure is presented below: .. code-block:: c #include #include #include #define NR_SECTORS 1024 #define KERNEL_SECTOR_SIZE 512 static struct my_block_dev { //... spinlock_t lock; /* For mutual exclusion */ struct request_queue *queue; /* The device request queue */ struct gendisk *gd; /* The gendisk structure */ //... } dev; static int create_block_device(struct my_block_dev *dev) { ... /* Initialize the gendisk structure */ dev->gd = alloc_disk(MY_BLOCK_MINORS); if (!dev->gd) { printk (KERN_NOTICE "alloc_disk failure\n"); return -ENOMEM; } dev->gd->major = MY_BLOCK_MAJOR; dev->gd->first_minor = 0; dev->gd->fops = &my_block_ops; dev->gd->queue = dev->queue; dev->gd->private_data = dev; snprintf (dev->gd->disk_name, 32, "myblock"); set_capacity(dev->gd, NR_SECTORS); add_disk(dev->gd); return 0; } static int my_block_init(void) { int status; //... status = create_block_device(&dev); if (status < 0) return status; //... } static void delete_block_device(struct my_block_dev *dev) { if (dev->gd) { del_gendisk(dev->gd); } //... } static void my_block_exit(void) { delete_block_device(&dev); //... } As stated before, the kernel considers a disk as a vector of 512 byte sectors. In reality, the devices may have a different size of the sector. To work with these devices, the kernel needs to be informed about the real size of a sector, and for all operations the necessary conversions must be made. To inform the kernel about the device sector size, a parameter of the request queue must be set just after the request queue is allocated, using the :c:func:`blk_queue_logical_block_size` function. All requests generated by the kernel will be multiple of this sector size and will be aligned accordingly. However, communication between the device and the driver will still be performed in sectors of 512 bytes in size, so conversion should be done each time (an example of such conversion is when calling the :c:func:`set_capacity` function in the code above). :c:type:`struct block_device_operations` structure ================================================== Just as for a character device, operations in :c:type:`struct file_operations` should be completed, so for a block device, the operations in :c:type:`struct block_device_operations` should be completed. The association of operations is done through the :c:member:`fops` field in the :c:type:`struct gendisk` structure. Some of the fields of the :c:type:`struct block_device_operations` structure are presented below: .. code-block:: c struct block_device_operations { int (*open) (struct block_device *, fmode_t); int (*release) (struct gendisk *, fmode_t); int (*locked_ioctl) (struct block_device *, fmode_t, unsigned, unsigned long); int (*ioctl) (struct block_device *, fmode_t, unsigned, unsigned long); int (*compat_ioctl) (struct block_device *, fmode_t, unsigned, unsigned long); int (*direct_access) (struct block_device *, sector_t, void **, unsigned long *); int (*media_changed) (struct gendisk *); int (*revalidate_disk) (struct gendisk *); int (*getgeo)(struct block_device *, struct hd_geometry *); blk_qc_t (*submit_bio) (struct bio *bio); struct module *owner; } :c:func:`open` and :c:func:`release` operations are called directly from user space by utilities that may perform the following tasks: partitioning, file system creation, file system verification. In a :c:func:`mount` operation, the :c:func:`open` function is called directly from the kernel space, the file descriptor being stored by the kernel. A driver for a block device can not differentiate between :c:func:`open` calls performed from user space and kernel space. An example of how to use these two functions is given below: .. code-block:: c #include #include static struct my_block_dev { //... struct gendisk * gd; //... } dev; static int my_block_open(struct block_device *bdev, fmode_t mode) { //... return 0; } static int my_block_release(struct gendisk *gd, fmode_t mode) { //... return 0; } struct block_device_operations my_block_ops = { .owner = THIS_MODULE, .open = my_block_open, .release = my_block_release }; static int create_block_device(struct my_block_dev *dev) { //.... dev->gd->fops = &my_block_ops; dev->gd->private_data = dev; //... } Please notice that there are no read or write operations. These operations are performed by the :c:func:`request` function associated with the request queue of the disk. Request Queues - Multi-Queue Block Layer ======================================== Drivers for block devices use queues to store the block I/O requests that will be processed. A request queue is represented by the :c:type:`struct request_queue` structure. The request queue is made up of a double-linked list of requests and their associated control information. The requests are added to the queue by higher-level kernel code (for example, file systems). The block device driver associates each queue with a handling function, which will be called for each request in the queue (the :c:type:`struct request` structure). In earlier version of the Linux kernel, each device driver had associated one or more request queues (:c:type:`struct request_queue`), where any client could add requests, while also being able to reorder them. The problem with this approach is that it requires a per-queue lock, making it inefficient in distributed systems. The `Multi-Queue Block Queing Mechanism `_ solves this issue by splitting the device driver queue in two parts: 1. Software staging queues 2. Hardware dispatch queues Software staging queues ----------------------- The staging queues hold requests from the clients before sending them to the block device driver. To prevent the waiting for a per-queue lock, a staging queue is allocated for each CPU or node. A software queue is associated to only one hardware queue. While in this queue, the requests can be merged or reordered, according to an I/O Scheduler, in order to maximize performance. This means that only the requests coming from the same CPU or node can be optimized. Staging queues are usually not used by the block device drivers, but only internally by the I/O subsystem to optimize requests before sending them to the device drivers. Hardware dispatch queues ------------------------ The hardware queues (:c:type:`struct blk_mq_hw_ctx`) are used to send the requests from the staging queues to the block device driver. Once in this queue, the requests can't be merged or reordered. Depending on the underlying hardware, a block device driver can create multiple hardware queues in order to improve parallelism and maximize performance. Tag sets -------- A block device driver can accept a request before the previous one is completed. As a consequence, the upper layers need a way to know when a request is completed. For this, a "tag" is added to each request upon submission and sent back using a completion notification after the request is completed. The tags are part of a tag set (:c:type:`struct blk_mq_tag_set`), which is unique to a device. The tag set structure is allocated and initialized before the request queues and also stores some of the queues properties. .. code-block:: c struct blk_mq_tag_set { ... const struct blk_mq_ops *ops; unsigned int nr_hw_queues; unsigned int queue_depth; unsigned int cmd_size; int numa_node; void *driver_data; struct blk_mq_tags **tags; struct list_head tag_list; ... }; Some of the fields in :c:type:`struct blk_mq_tag_set` are: * ``ops`` - Queue operations, most notably the request handling function. * ``nr_hw_queues`` - The number of hardware queues allocated for the device * ``queue_depth`` - Hardware queues size * ``cmd_size`` - Number of extra bytes allocated at the end of the device, to be used by the block device driver, if needed. * ``numa_node`` - In NUMA systems, the index of the node the storage device is connected to. * ``driver_data`` - Data private to the driver, if needed. * ``tags`` - Pointer to an array of ``nr_hw_queues`` tag sets. * ``tag_list`` - List of request queues using this tag set. Create and delete a request queue --------------------------------- Request queues are created using the :c:func:`blk_mq_init_queue` function and are deleted using :c:func:`blk_cleanup_queue`. The first function creates both the hardware and the software queues and initializes their structures. Queue properties, including the number of hardware queues, their capacity and request handling function are configured using the :c:type:`blk_mq_tag_set` structure, as described above. An example of using these functions is as follows: .. code-block:: c #include #include #include static struct my_block_dev { //... struct blk_mq_tag_set tag_set; struct request_queue *queue; //... } dev; static blk_status_t my_block_request(struct blk_mq_hw_ctx *hctx, const struct blk_mq_queue_data *bd) //... static struct blk_mq_ops my_queue_ops = { .queue_rq = my_block_request, }; static int create_block_device(struct my_block_dev *dev) { /* Initialize tag set. */ dev->tag_set.ops = &my_queue_ops; dev->tag_set.nr_hw_queues = 1; dev->tag_set.queue_depth = 128; dev->tag_set.numa_node = NUMA_NO_NODE; dev->tag_set.cmd_size = 0; dev->tag_set.flags = BLK_MQ_F_SHOULD_MERGE; err = blk_mq_alloc_tag_set(&dev->tag_set); if (err) { goto out_err; } /* Allocate queue. */ dev->queue = blk_mq_init_queue(&dev->tag_set); if (IS_ERR(dev->queue)) { goto out_blk_init; } blk_queue_logical_block_size(dev->queue, KERNEL_SECTOR_SIZE); /* Assign private data to queue structure. */ dev->queue->queuedata = dev; //... out_blk_init: blk_mq_free_tag_set(&dev->tag_set); out_err: return -ENOMEM; } static int my_block_init(void) { int status; //... status = create_block_device(&dev); if (status < 0) return status; //... } static void delete_block_device(struct block_dev *dev) { //... blk_cleanup_queue(dev->queue); blk_mq_free_tag_set(&dev->tag_set); } static void my_block_exit(void) { delete_block_device(&dev); //... } After initializing the tag set structure, the tag lists are allocated using the :c:func:`blk_mq_alloc_tag_set` function. The pointer to the function which will process the requests (:c:func:`my_block_request`) is filled in the ``my_queue_ops`` structure and then the pointer to this structure is added to the tag set. The queue is created using the :c:func:`blk_mq_init_queue` function, based on the information added in the tag set. As part of the request queue initialization, you can configure the :c:member:`queuedata` field, which is equivalent to the :c:member:`private_data` field in other structures. Useful functions for processing request queues ---------------------------------------------- The ``queue_rq`` function from :c:type:`struct blk_mq_ops` is used to handle requests for working with the block device. This function is the equivalent of read and write functions encountered on character devices. The function receives the requests for the device as arguments and can use various functions for processing them. The functions used to process the requests in the handler are described below: * :c:func:`blk_mq_start_request` - must be called before starting processing a request; * :c:func:`blk_mq_requeue_request` - to re-send the request in the queue; * :c:func:`blk_mq_end_request` - to end request processing and notify the upper layers. Requests for block devices ========================== A request for a block device is described by :c:type:`struct request` structure. The fields of :c:type:`struct request` structure include: * :c:member:`cmd_flags`: a series of flags including direction (reading or writing); to find out the direction, the macrodefinition :c:macro:`rq_data_dir` is used, which returns 0 for a read request and 1 for a write request on the device; * :c:member:`__sector`: the first sector of the transfer request; if the device sector has a different size, the appropriate conversion should be done. To access this field, use the :c:macro:`blk_rq_pos` macro; * :c:member:`__data_len`: the total number of bytes to be transferred; to access this field the :c:macro:`blk_rq_bytes` macro is used; * generally, data from the current :c:type:`struct bio` will be transferred; the data size is obtained using the :c:macro:`blk_rq_cur_bytes` macro; * :c:member:`bio`, a dynamic list of :c:type:`struct bio` structures that is a set of buffers associated to the request; this field is accessed by macrodefinition :c:macro:`rq_for_each_segment` if there are multiple buffers, or by :c:macro:`bio_data` macrodefinition in case there is only one associated buffer; We will discuss more about the :c:type:`struct bio` structure and its associated operations in the :ref:`bio_structure` section. Create a request ---------------- Read /write requests are created by code layers superior to the kernel I/O subsystem. Typically, the subsystem that creates requests for block devices is the file management subsystem. The I/O subsystem acts as an interface between the file management subsystem and the block device driver. The main operations under the responsibility of the I/O subsystem are adding requests to the queue of the specific block device and sorting and merging requests according to performance considerations. Process a request ----------------- The central part of a block device driver is the request handling function (``queue_rq``). In previous examples, the function that fulfilled this role was :c:func:`my_block_request`. As stated in the `Create and delete a request queue`_ section, this function is associated to the driver when creating the tag set structure. This function is called when the kernel considers that the driver should process I/O requests. The function must start processing the requests from the queue, but it is not mandatory to finish them, as requests may be finished by other parts of the driver. The request function runs in an atomic context and must follow the rules for atomic code (it does not need to call functions that can cause sleep, etc.). Calling the function that processes the requests is asynchronous relative to the actions of any userspace process and no assumptions about the process in which the respective function is running should be made. Also, it should not be assumed that the buffer provided by a request is from kernel space or user space, any operation that accesses the userspace being erroneous. One of the simplest request handling function is presented below: .. code-block:: c static blk_status_t my_block_request(struct blk_mq_hw_ctx *hctx, const struct blk_mq_queue_data *bd) { struct request *rq = bd->rq; struct my_block_dev *dev = q->queuedata; blk_mq_start_request(rq); if (blk_rq_is_passthrough(rq)) { printk (KERN_NOTICE "Skip non-fs request\n"); blk_mq_end_request(rq, BLK_STS_IOERR); goto out; } /* do work */ ... blk_mq_end_request(rq, BLK_STS_OK); out: return BLK_STS_OK; } The :c:func:`my_block_request` function performs the following operations: * Get a pointer to the request structure from the ``bd`` argument and start its processing using the :c:func:`blk_mq_start_request` function. * A block device can receive calls which do not transfer data blocks (e.g. low level operations on the disk, instructions referring to special ways of accessing the device). Most drivers do not know how to handle these requests and return an error. * To return an error, :c:func:`blk_mq_end_request` function is called, ``BLK_STS_IOERR`` being the second argument. * The request is processed according to the needs of the associated device. * The request ends. In this case, :c:func:`blk_mq_end_request` function is called in order to complete the request. .. bio_structure: :c:type:`struct bio` structure ============================== Each :c:type:`struct request` structure is an I/O block request, but may come from combining more independent requests from a higher level. The sectors to be transferred for a request can be scattered into the main memory but they always correspond to a set of consecutive sectors on the device. The request is represented as a series of segments, each corresponding to a buffer in memory. The kernel can combine requests that refer to adjacent sectors but will not combine write requests with read requests into a single :c:type:`struct request` structure. A :c:type:`struct request` structure is implemented as a linked list of :c:type:`struct bio` structures together with information that allows the driver to retain its current position while processing the request. The :c:type:`struct bio` structure is a low-level description of a portion of a block I/O request. .. code-block:: c struct bio { //... struct gendisk *bi_disk; unsigned int bi_opf; /* bottom bits req flags, top bits REQ_OP. Use accessors. */ //... struct bio_vec *bi_io_vec; /* the actual vec list */ //... struct bvec_iter bi_iter; /... void *bi_private; //... }; In turn, the :c:type:`struct bio` structure contains a :c:member:`bi_io_vec` vector of :c:type:`struct bio_vec` structures. It consists of the individual pages in the physical memory to be transferred, the offset within the page and the size of the buffer. To iterate through a :c:type:`struct bio` structure, we need to iterate through the vector of :c:type:`struct bio_vec` and transfer the data from every physical page. To simplify vector iteration, the :c:type:`struct bvec_iter` structure is used. This structure maintains information about how many buffers and sectors were consumed during the iteration. The request type is encoded in the :c:member:`bi_opf` field; to determine it, use the :c:func:`bio_data_dir` function. Create a :c:type:`struct bio` structure --------------------------------------- Two functions can be used to create a :c:type:`struct bio` structure: * :c:func:`bio_alloc`: allocates space for a new structure; the structure must be initialized; * :c:func:`bio_clone`: makes a copy of an existing :c:type:`struct bio` structure; the newly obtained structure is initialized with the values of the cloned structure fields; the buffers are shared with the :c:type:`struct bio` structure that has been cloned so that access to the buffers has to be done carefully to avoid access to the same memory area from the two clones; Both functions return a new :c:type:`struct bio` structure. Submit a :c:type:`struct bio` structure --------------------------------------- Usually, a :c:type:`struct bio` structure is created by the higher levels of the kernel (usually the file system). A structure thus created is then transmitted to the I/O subsystem that gathers more :c:type:`struct bio` structures into a request. For submitting a :c:type:`struct bio` structure to the associated I/O device driver, the :c:func:`submit_bio` function is used. The function receives as argument an initialized :c:type:`struct bio` structure that will be added to a request from the request queue of an I/O device. From that queue, it can be processed by the I/O device driver using a specialized function. .. _bio_completion: Wait for the completion of a :c:type:`struct bio` structure ----------------------------------------------------------- Submitting a :c:type:`struct bio` structure to a driver has the effect of adding it to a request from the request queue from where it will be further processed. Thus, when the :c:func:`submit_bio` function returns, it is not guaranteed that the processing of the structure has finished. If you want to wait for the processing of the request to be finished, use the :c:func:`submit_bio_wait` function. To be notified when the processing of a :c:type:`struct bio` structure ends (when we do not use :c:func:`submit_bio_wait` function), the :c:member:`bi_end_io` field of the structure should be used. This field specifies the function that will be called at the end of the :c:type:`struct bio` structure processing. You can use the :c:member:`bi_private` field of the structure to pass information to the function. Initialize a :c:type:`struct bio` structure ------------------------------------------- Once a :c:type:`struct bio` structure has been allocated and before being transmitted, it must be initialized. Initializing the structure involves filling in its important fields. As mentioned above, the :c:member:`bi_end_io` field is used to specify the function called when the processing of the structure is finished. The :c:member:`bi_private` field is used to store useful data that can be accessed in the function pointed by :c:member:`bi_end_io`. The :c:member:`bi_opf` field specifies the type of operation. .. code-block:: c struct bio *bio = bio_alloc(GFP_NOIO, 1); //... bio->bi_disk = bdev->bd_disk; bio->bi_iter.bi_sector = sector; bio->bi_opf = REQ_OP_READ; bio_add_page(bio, page, size, offset); //... In the code snippet above we specified the block device to which we sent the following: :c:type:`struct bio` structure, startup sector, operation (:c:data:`REQ_OP_READ` or :c:data:`REQ_OP_WRITE`) and content. The content of a :c:type:`struct bio` structure is a buffer described by: a physical page, the offset in the page and the size of the bufer. A page can be assigned using the :c:func:`alloc_page` call. .. note:: The :c:data:`size` field of the :c:func:`bio_add_page` call must be a multiple of the device sector size. .. _bio_content: How to use the content of a :c:type:`struct bio` structure ---------------------------------------------------------- To use the content of a :c:type:`struct bio` structure, the structure's support pages must be mapped to the kernel address space from where they can be accessed. For mapping /unmapping, use the :c:macro:`kmap_atomic` and the :c:macro:`kunmap_atomic` macros. A typical example of use is: .. code-block:: c static void my_block_transfer(struct my_block_dev *dev, size_t start, size_t len, char *buffer, int dir); static int my_xfer_bio(struct my_block_dev *dev, struct bio *bio) { struct bio_vec bvec; struct bvec_iter i; int dir = bio_data_dir(bio); /* Do each segment independently. */ bio_for_each_segment(bvec, bio, i) { sector_t sector = i.bi_sector; char *buffer = kmap_atomic(bvec.bv_page); unsigned long offset = bvec.bv_offset; size_t len = bvec.bv_len; /* process mapped buffer */ my_block_transfer(dev, sector, len, buffer + offset, dir); kunmap_atomic(buffer); } return 0; } As it can be seen from the example above, iterating through a :c:type:`struct bio` requires iterating through all of its segments. A segment (:c:type:`struct bio_vec`) is defined by the physical address page, the offset in the page and its size. To simplify the processing of a :c:type:`struct bio`, use the :c:macro:`bio_for_each_segment` macrodefinition. It will iterate through all segments, and will also update global information stored in an iterator (:c:type:`struct bvec_iter`) such as the current sector as well as other internal information (segment vector index, number of bytes left to be processed, etc.) . You can store information in the mapped buffer, or extract information. In case request queues are used and you needed to process the requests at :c:type:`struct bio` level, use the :c:macro:`rq_for_each_segment` macrodefinition instead of the :c:macro:`bio_for_each_segment` macrodefinition. This macrodefinition iterates through each segment of each :c:type:`struct bio` structure of a :c:type:`struct request` structure and updates a :c:type:`struct req_iterator` structure. The :c:type:`struct req_iterator` contains the current :c:type:`struct bio` structure and the iterator that traverses its segments. A typical example of use is: .. code-block:: c struct bio_vec bvec; struct req_iterator iter; rq_for_each_segment(bvec, req, iter) { sector_t sector = iter.iter.bi_sector; char *buffer = kmap_atomic(bvec.bv_page); unsigned long offset = bvec.bv_offset; size_t len = bvec.bv_len; int dir = bio_data_dir(iter.bio); my_block_transfer(dev, sector, len, buffer + offset, dir); kunmap_atomic(buffer); } Free a :c:type:`struct bio` structure ------------------------------------- Once a kernel subsystem uses a :c:type:`struct bio` structure, it will have to release the reference to it. This is done by calling :c:func:`bio_put` function. Set up a request queue at :c:type:`struct bio` level ---------------------------------------------------- We have previously seen how we can specify a function to be used to process requests sent to the driver. The function receives as argument the requests and carries out processing at :c:type:`struct request` level. If, for flexibility reasons, we need to specify a function that carries out processing at :c:type:`struct bio` structure level, we no longer use request queues and we will need to fill the ``submit_bio`` field in the :c:type:`struct block_device_operations` associated to the driver. Below is a typical example of initializing a function that carries out processing at :c:type:`struct bio` structure level: .. code-block:: c // the declaration of the function that carries out processing // :c:type:`struct bio` structures static blk_qc_t my_submit_bio(struct bio *bio); struct block_device_operations my_block_ops = { .owner = THIS_MODULE, .submit_bio = my_submit_bio ... }; Further reading =============== * `Linux Device Drivers 3rd Edition, Chapter 16. Block Drivers `_ * Linux Kernel Development, Second Edition – Chapter 13. The Block I/O Layer * `A simple block driver `_ * `The gendisk interface `_ * `The bio structure `_ * `Request queues `_ * `Documentation/block/request.txt - Struct request documentation `_ * `Documentation/block/biodoc.txt - Notes on the Generic Block Layer `_ * `drivers/block/brd/c - RAM backed block disk driver `_ * `I/O Schedulers `_ Exercises ========= .. include:: ../labs/exercises-summary.hrst .. |LAB_NAME| replace:: block_device_drivers 0. Intro -------- Using |LXR|_ find the definitions of the following symbols in the Linux kernel: * :c:type:`struct bio` * :c:type:`struct bio_vec` * :c:macro:`bio_for_each_segment` * :c:type:`struct gendisk` * :c:type:`struct block_device_operations` * :c:type:`struct request` 1. Block device --------------- Create a kernel module that allows you to register or deregister a block device. Start from the files in the :file:`1-2-3-6-ram-disk/kernel` directory in the lab skeleton. Follow the comments marked with **TODO 1** in the laboratory skeleton. Use the existing macrodefinitions (:c:macro:`MY_BLOCK_MAJOR`, :c:macro:`MY_BLKDEV_NAME`). Check the value returned by the register function, and in case of error, return the error code. Compile the module, copy it to the virtual machine and insert it into the kernel. Verify that your device was successfully created inside the :file:`/proc/devices`. You will see a device with major 240. Unload the kernel module and check that the device was unregistered. .. hint:: Review the `Register a block I/O device`_ section. Change the :c:macro:`MY_BLOCK_MAJOR` value to 7. Compile the module, copy it to the virtual machine, and insert it into the kernel. Notice that the insertion fails because there is already another driver/device registered in the kernel with the major 7. Restore the 240 value for the :c:macro:`MY_BLOCK_MAJOR` macro. 2. Disk registration -------------------- Modify the previous module to add a disk associated with the driver. Analyze the macrodefinitions, :c:type:`my_block_dev` structure and existing functions from the :file:`ram-disk.c` file. Follow the comments marked with **TODO 2**. Use the :c:func:`create_block_device` and the :c:func:`delete_block_device` functions. .. hint:: Review the `Register a disk`_ and `Process a request`_ sections. Fill in the :c:func:`my_block_request` function to process the request without actually processing your request: display the "request received" message and the following information: start sector, total size, data size from the current :c:type:`struct bio` structure, direction. To validate a request type, use the :c:func:`blk_rq_is_passthrough` (the function returns 0 in the case in which we are interested, i.e. when the request is generated by the file system). .. hint:: To find the needed info, review the `Requests for block devices`_ section. Use the :c:func:`blk_mq_end_request` function to finish processing the request. Insert the module into the kernel and inspect the messages printed by the module. When a device is added, a request is sent to the device. Check the presence of :file:`/dev/myblock` and if it doesn't exist, create the device using the command: .. code-block:: shell mknod /dev/myblock b 240 0 To generate writing requests, use the command: .. code-block:: shell echo "abc"> /dev/myblock Notice that a write request is preceded by a read request. The request is done to read the block from the disk and "update" its content with the data provided by the user, without overwriting the rest. After reading and updating, writing takes place. 3. RAM disk ----------- Modify the previous module to create a RAM disk: requests to the device will result in reads/writes in a memory area. The memory area :c:data:`dev->data` is already allocated in the source code of the module using :c:func:`vmalloc` and deallocated using :c:func:`vfree`. .. note:: Review the `Process a request`_ section. Follow the comments marked with **TODO 3** to complete the :c:func:`my_block_transfer` function to write/read the request information in/from the memory area. The function will be called for each request within the queue processing function: :c:func:`my_block_request`. To write/read to/from the memory area, use :c:func:`memcpy`. To determine the write/read information, use the fields of the :c:type:`struct request` structure. .. hint:: To find out the size of the request data, use the :c:macro:`blk_rq_cur_bytes` macro. Do not use the :c:macro:`blk_rq_bytes` macro. .. hint:: To find out the buffer associated to the request, use :c:data:`bio_data`(:c:data:`rq->bio`). .. hint:: A description of useful macros is in the `Requests for block devices`_ section. .. hint:: You can find useful information in the `block device driver example `_ from `Linux Device Driver `_. For testing, use the test file :file:`user/ram-disk-test.c`. The test program is compiled automatically at ``make build``, copied to the virtual machine at ``make copy`` and can be run on the QEMU virtual machine using the command: .. code-block:: shell ./ram-disk-test There is no need to insert the module into the kernel, it will be inserted by the ``ram-disk-test`` command. Some tests may fail because of lack of synchronization between the transmitted data (flush). 4. Read data from the disk -------------------------- The purpose of this exercise is to read data from the :c:macro:`PHYSICAL_DISK_NAME` disk (:file:`/dev/vdb`) directly from the kernel. .. attention:: Before solving the exercise, we need to make sure the disk is added to the virtual machine. Check the variable ``QEMU_OPTS`` from :file:`qemu/Makefile`. There should already be two extra disks added using ``-drive ...``. If there are not, generate a file that we will use as the disk image using the command: :command:`dd if=/dev/zero of=qemu/mydisk.img bs=1024 count=1` and add the following option: :command:`-drive file=qemu/mydisk.img,if=virtio,format=raw` to :file:`qemu/Makefile` (in the :c:data:`QEMU_OPTS` variable, after the root disk). Follow the comments marked with **TODO 4** in the directory :file:`4-5-relay/` and implement :c:func:`open_disk` and :c:func:`close_disk`. Use the :c:func:`blkdev_get_by_path` and :c:func:`blkdev_put` functions. The device must be opened in read-write mode exclusively (:c:macro:`FMODE_READ` | :c:macro:`FMODE_WRITE` | :c:macro:`FMODE_EXCL`), and as holder you must use the current module (:c:macro:`THIS_MODULE`). Implement the :c:func:`send_test_bio` function. You will have to create a new :c:type:`struct bio` structure and fill it, submit it and wait for it. Read the first sector of the disk. To wait, call the :c:func:`submit_bio_wait` function. .. hint:: The first sector of the disk is the sector with the index 0. This value must be used to initialize the field :c:member:`bi_iter.bi_sector` of the :c:type:`struct bio`. For the read operation, use the :c:macro:`REQ_OP_READ` macro to initialize the :c:member:`bi_opf` field of the :c:type:`struct bio`. After finishing the operation, display the first 3 bytes of data read by :c:type:`struct bio` structure. Use the format ``"% 02x"`` for :c:func:`printk` to display the data and the :c:macro:`kmap_atomic` and :c:macro:`kunmap_atomic` macros respectively. .. hint:: As an argument for the :c:func:`kmap_atomic` function, just use the page which is allocated above in the code, in the :c:data:`page` variable. .. hint:: Review the sections :ref:`bio_content` and :ref:`bio_completion`. For testing, use the :file:`test-relay-disk` script, which is copied on the virtual machine when running :command:`make copy`. If it is not copied, make sure it is executable: .. code-block:: shell chmod +x test-relay-disk There is no need to load the module into the kernel, it will be loaded by :command:`test-relay-disk`. Use the command below to run the script: .. code-block:: shell ./test-relay-disk The script writes "abc" at the beginning of the disk indicated by :c:macro:`PHYSICAL_DISK_NAME`. After running, the module will display 61 62 63 (the corresponding hexadecimal values of letters "a", "b" and "c"). 5. Write data to the disk ------------------------- Follow the comments marked with **TODO 5** to write a message (:c:macro:`BIO_WRITE_MESSAGE`) on the disk. The :c:func:`send_test_bio` function receives as argument the operation type (read or write). Call in the :c:func:`relay_init` function the function for reading and in the :c:func:`relay_exit` function the function for writing. We recommend using the :c:macro:`REQ_OP_READ` and the :c:macro:`REQ_OP_WRITE` macros. Inside the :c:func:`send_test_bio` function, if the operation is write, fill in the buffer associated to the :c:type:`struct bio` structure with the message :c:macro:`BIO_WRITE_MESSAGE`. Use the :c:macro:`kmap_atomic` and the :c:macro:`kunmap_atomic` macros to work with the buffer associated to the :c:type:`struct bio` structure. .. hint:: You need to update the type of the operation associated to the :c:type:`struct bio` structure by setting the :c:member:`bi_opf` field accordingly. For testing, run the :file:`test-relay-disk` script using the command: .. code-block:: shell ./test-relay-disk The script will display the ``"read from /dev/sdb: 64 65 66"`` message at the standard output. 6. Processing requests from the request queue at :c:type:`struct bio` level --------------------------------------------------------------------------- In the implementation from Exercise 3, we have only processed a :c:type:`struct bio_vec` of the current :c:type:`struct bio` from the request. We want to process all :c:type:`struct bio_vec` structures from all :c:type:`struct bio` structures. For this, we will iterate through all :c:type:`struct bio` requests and through all :c:type:`struct bio_vec` structures (also called segments) of each :c:type:`struct bio`. Add, within the ramdisk implementation (:file:`1-2-3-6-ram-disk/` directory), support for processing the requests from the request queue at :c:type:`struct bio` level. Follow the comments marked with **TODO 6**. Set the :c:macro:`USE_BIO_TRANSFER` macro to 1. Implement the :c:func:`my_xfer_request` function. Use the :c:macro:`rq_for_each_segment` macro to iterate through the :c:type:`bio_vec` structures of each :c:type:`struct bio` from the request. .. hint:: Review the indications and the code snippets from the :ref:`bio_content` section. .. hint:: Use the :c:type:`struct bio` segment iterator to get the current sector (:c:member:`iter.iter.bi_sector`). .. hint:: Use the request iterator to get the reference to the current :c:type:`struct bio` (:c:member:`iter.bio`). .. hint:: Use the :c:macro:`bio_data_dir` macro to find the reading or writing direction for a :c:type:`struct bio`. Use the :c:macro:`kmap_atomic` or the :c:macro:`kunmap_atomic` macros to map the pages of each :c:type:`struct bio` structure and access its associated buffers. For the actual transfer, call the :c:func:`my_block_transfer` function implemented in the previous exercise. For testing, use the :file:`ram-disk-test.c` test file: .. code-block:: shell ./ram-disk-test There is no need to insert the module into the kernel, it will be inserted by the :command:`ram-disk-test` executable. Some tests may crash because of lack of synchronization between the transmitted data (flush).