Orange Pi5 kernel

^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  1) =====
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  2) dm-io
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  3) =====
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  4) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  5) Dm-io provides synchronous and asynchronous I/O services. There are three
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  6) types of I/O services available, and each type has a sync and an async
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  7) version.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  8) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  9) The user must set up an io_region structure to describe the desired location
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 10) of the I/O. Each io_region indicates a block-device along with the starting
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 11) sector and size of the region::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 12) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 13)    struct io_region {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 14)       struct block_device *bdev;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 15)       sector_t sector;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 16)       sector_t count;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 17)    };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 18) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 19) Dm-io can read from one io_region or write to one or more io_regions. Writes
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 20) to multiple regions are specified by an array of io_region structures.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 21) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 22) The first I/O service type takes a list of memory pages as the data buffer for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 23) the I/O, along with an offset into the first page::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 24) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 25)    struct page_list {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 26)       struct page_list *next;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 27)       struct page *page;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 28)    };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 29) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 30)    int dm_io_sync(unsigned int num_regions, struct io_region *where, int rw,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 31)                   struct page_list *pl, unsigned int offset,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 32)                   unsigned long *error_bits);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 33)    int dm_io_async(unsigned int num_regions, struct io_region *where, int rw,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 34)                    struct page_list *pl, unsigned int offset,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 35)                    io_notify_fn fn, void *context);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 36) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 37) The second I/O service type takes an array of bio vectors as the data buffer
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 38) for the I/O. This service can be handy if the caller has a pre-assembled bio,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 39) but wants to direct different portions of the bio to different devices::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 40) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 41)    int dm_io_sync_bvec(unsigned int num_regions, struct io_region *where,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 42)                        int rw, struct bio_vec *bvec,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 43)                        unsigned long *error_bits);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 44)    int dm_io_async_bvec(unsigned int num_regions, struct io_region *where,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 45)                         int rw, struct bio_vec *bvec,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 46)                         io_notify_fn fn, void *context);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 47) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 48) The third I/O service type takes a pointer to a vmalloc'd memory buffer as the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 49) data buffer for the I/O. This service can be handy if the caller needs to do
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 50) I/O to a large region but doesn't want to allocate a large number of individual
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 51) memory pages::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 52) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 53)    int dm_io_sync_vm(unsigned int num_regions, struct io_region *where, int rw,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 54)                      void *data, unsigned long *error_bits);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 55)    int dm_io_async_vm(unsigned int num_regions, struct io_region *where, int rw,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 56)                       void *data, io_notify_fn fn, void *context);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 57) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 58) Callers of the asynchronous I/O services must include the name of a completion
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 59) callback routine and a pointer to some context data for the I/O::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 60) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 61)    typedef void (*io_notify_fn)(unsigned long error, void *context);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 62) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 63) The "error" parameter in this callback, as well as the `*error` parameter in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 64) all of the synchronous versions, is a bitset (instead of a simple error value).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 65) In the case of an write-I/O to multiple regions, this bitset allows dm-io to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 66) indicate success or failure on each individual region.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 67) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 68) Before using any of the dm-io services, the user should call dm_io_get()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 69) and specify the number of pages they expect to perform I/O on concurrently.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 70) Dm-io will attempt to resize its mempool to make sure enough pages are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 71) always available in order to avoid unnecessary waiting while performing I/O.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 72) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 73) When the user is finished using the dm-io services, they should call
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 74) dm_io_put() and specify the same number of pages that were given on the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 75) dm_io_get() call.