diff options
Diffstat (limited to 'Documentation/block')
| -rw-r--r-- | Documentation/block/biovecs.rst | 8 | ||||
| -rw-r--r-- | Documentation/block/blk-mq.rst | 2 | ||||
| -rw-r--r-- | Documentation/block/data-integrity.rst | 2 | ||||
| -rw-r--r-- | Documentation/block/error-injection.rst | 59 | ||||
| -rw-r--r-- | Documentation/block/index.rst | 1 | ||||
| -rw-r--r-- | Documentation/block/inline-encryption.rst | 43 | ||||
| -rw-r--r-- | Documentation/block/ublk.rst | 14 |
7 files changed, 90 insertions, 39 deletions
diff --git a/Documentation/block/biovecs.rst b/Documentation/block/biovecs.rst index 11126ed6f40f..49da2147b7d8 100644 --- a/Documentation/block/biovecs.rst +++ b/Documentation/block/biovecs.rst @@ -16,16 +16,16 @@ bv_len by the number of bytes completed in that biovec. In the new scheme of things, everything that must be mutated in order to partially complete a bio is segregated into struct bvec_iter: bi_sector, bi_size and bi_idx have been moved there; and instead of modifying bv_offset -and bv_len, struct bvec_iter has bi_bvec_done, which represents the number of +and bv_len, struct bvec_iter has bi_offset, which represents the number of bytes completed in the current bvec. There are a bunch of new helper macros for hiding the gory details - in particular, presenting the illusion of partially completed biovecs so that -normal code doesn't have to deal with bi_bvec_done. +normal code doesn't have to deal with bi_offset. * Driver code should no longer refer to biovecs directly; we now have bio_iovec() and bio_iter_iovec() macros that return literal struct biovecs, - constructed from the raw biovecs but taking into account bi_bvec_done and + constructed from the raw biovecs but taking into account bi_offset and bi_size. bio_for_each_segment() has been updated to take a bvec_iter argument @@ -101,7 +101,7 @@ Other implications: I.e. instead of using bio_iovec_idx() (or bio->bi_iovec[bio->bi_idx]), you now use bio_iter_iovec(), which takes a bvec_iter and returns a literal struct bio_vec - constructed on the fly from the raw biovec but - taking into account bi_bvec_done (and bi_size). + taking into account bi_offset (and bi_size). * bi_vcnt can't be trusted or relied upon by driver code - i.e. anything that doesn't actually own the bio. The reason is twofold: firstly, it's not diff --git a/Documentation/block/blk-mq.rst b/Documentation/block/blk-mq.rst index fc06761b6ea9..2798761efe0d 100644 --- a/Documentation/block/blk-mq.rst +++ b/Documentation/block/blk-mq.rst @@ -139,7 +139,7 @@ completed. Further reading --------------- -- `Linux Block IO: Introducing Multi-queue SSD Access on Multi-core Systems <http://kernel.dk/blk-mq.pdf>`_ +- `Linux Block IO: Introducing Multi-queue SSD Access on Multi-core Systems <https://www.kernel.dk/blk-mq.pdf>`_ - `NOOP scheduler <https://en.wikipedia.org/wiki/Noop_scheduler>`_ diff --git a/Documentation/block/data-integrity.rst b/Documentation/block/data-integrity.rst index 99905e880a0e..b7b10c8abbcc 100644 --- a/Documentation/block/data-integrity.rst +++ b/Documentation/block/data-integrity.rst @@ -154,7 +154,7 @@ bio_free() will automatically free the bip. ---------------- Block devices can set up the integrity information in the integrity -sub-struture of the queue_limits structure. +sub-structure of the queue_limits structure. Layered block devices will need to pick a profile that's appropriate for all subdevices. queue_limits_stack_integrity() can help with that. DM diff --git a/Documentation/block/error-injection.rst b/Documentation/block/error-injection.rst new file mode 100644 index 000000000000..81f31af82e65 --- /dev/null +++ b/Documentation/block/error-injection.rst @@ -0,0 +1,59 @@ +.. SPDX-License-Identifier: GPL-2.0 + +============================ +Configurable Error Injection +============================ + +Overview +-------- + +Configurable error injection allows injecting specific block layer status codes +for sector ranges of a block device. Errors can be injected unconditionally, or +with a given probability. + +To use configurable error injection, CONFIG_BLK_ERROR_INJECTION must be enabled. + +The only interface is the error_injection debugfs file, which is created for +each registered gendisk. Writes to this file are used to create or delete rules +and reads return a list of the current error injection sites. + +Options +------- + +The following options specify the operations: + +=================== ======================================================= +add add a new rule +removeall remove all existing rules +=================== ======================================================= + +The following options specify the details of the rule for the add operation: + +=================== ======================================================= +op=<string> block layer operation this rule applies to. This uses + the XYZ for each REQ_OP_XYZ operation, e.g. READ, WRITE + or DISCARD. Mandatory. +status=<string> Status to return. This uses XYZ for each BLK_STS_XYZ + code, e.g. IOERR or MEDIUM. Mandatory. +start=<number> First block layer sector the rule applies to. + Optional, defaults to 0. +nr_sectors=<number> Number of sectors this rule applies. + Optional, defaults to the remainder of the device. +chance=<number> Only return a failure with a likelihood of 1/chance. + Optional, defaults to 1 (always). +=================== ======================================================= + +Example +------- + +Return BLK_STS_IOERR for one in 10 reads of sector 0 of /dev/nvme0n1: + + $ echo 'add,op=READ,start=0,status=IOERR,chance=10' > /sys/kernel/debug/block/nvme0n1/error_injection + +Return BLK_STS_MEDIUM for every write to /dev/nvme0n1: + + $ echo 'add,op=WRITE,start=0,status=MEDIUM' > /sys/kernel/debug/block/nvme0n1/error_injection + +Remove all rules for /dev/nvme0n1: + + $ echo 'removeall' > /sys/kernel/debug/block/nvme0n1/error_injection diff --git a/Documentation/block/index.rst b/Documentation/block/index.rst index 9fea696f9daa..bfa1bbd31ddf 100644 --- a/Documentation/block/index.rst +++ b/Documentation/block/index.rst @@ -22,3 +22,4 @@ Block switching-sched writeback_cache_control ublk + error-injection diff --git a/Documentation/block/inline-encryption.rst b/Documentation/block/inline-encryption.rst index cae23949a626..0df964507f76 100644 --- a/Documentation/block/inline-encryption.rst +++ b/Documentation/block/inline-encryption.rst @@ -37,12 +37,12 @@ initialization vector for each sector, and can be tested for correctness. Objective ========= -We want to support inline encryption in the kernel. To make testing easier, we -also want support for falling back to the kernel crypto API when actual inline -encryption hardware is absent. We also want inline encryption to work with -layered devices like device-mapper and loopback (i.e. we want to be able to use -the inline encryption hardware of the underlying devices if present, or else -fall back to crypto API en/decryption). +We want to support inline encryption hardware in the kernel. The API for using +such hardware should also support a fallback to the CPU, so that users only need +to use a single API and more of the code can be tested without actual hardware. +We also want inline encryption to work with layered devices like device-mapper +and loopback (i.e. we want to be able to use the inline encryption hardware of +the underlying devices if present, or else fall back to the CPU). Constraints and notes ===================== @@ -185,20 +185,12 @@ blk-crypto-fallback is optional and is controlled by the API presented to users of the block layer ========================================= -``blk_crypto_config_supported()`` allows users to check ahead of time whether -inline encryption with particular crypto settings will work on a particular -block_device -- either via hardware or via blk-crypto-fallback. This function -takes in a ``struct blk_crypto_config`` which is like blk_crypto_key, but omits -the actual bytes of the key and instead just contains the algorithm, data unit -size, etc. This function can be useful if blk-crypto-fallback is disabled. - ``blk_crypto_init_key()`` allows users to initialize a blk_crypto_key. Users must call ``blk_crypto_start_using_key()`` before actually starting to use -a blk_crypto_key on a block_device (even if ``blk_crypto_config_supported()`` -was called earlier). This is needed to initialize blk-crypto-fallback if it -will be needed. This must not be called from the data path, as this may have to -allocate resources, which may deadlock in that case. +a blk_crypto_key on a block_device. This is needed to initialize +blk-crypto-fallback if it will be needed. This must not be called from the data +path, as this may have to allocate resources, which may deadlock in that case. Next, to attach an encryption context to a bio, users should call ``bio_crypt_set_ctx()``. This function allocates a bio_crypt_ctx and attaches @@ -220,16 +212,15 @@ any kernel data structures it may be linked into. In summary, for users of the block layer, the lifecycle of a blk_crypto_key is as follows: -1. ``blk_crypto_config_supported()`` (optional) -2. ``blk_crypto_init_key()`` -3. ``blk_crypto_start_using_key()`` -4. ``bio_crypt_set_ctx()`` (potentially many times) -5. ``blk_crypto_evict_key()`` (after all I/O has completed) -6. Zeroize the blk_crypto_key (this has no dedicated function) +1. ``blk_crypto_init_key()`` +2. ``blk_crypto_start_using_key()`` +3. ``bio_crypt_set_ctx()`` (potentially many times) +4. ``blk_crypto_evict_key()`` (after all I/O has completed) +5. Zeroize the blk_crypto_key (this has no dedicated function) If a blk_crypto_key is being used on multiple block_devices, then -``blk_crypto_config_supported()`` (if used), ``blk_crypto_start_using_key()``, -and ``blk_crypto_evict_key()`` must be called on each block_device. +``blk_crypto_start_using_key()`` and ``blk_crypto_evict_key()`` must be called +on each block_device. API presented to device drivers =============================== @@ -304,7 +295,7 @@ hardware implementations might not implement both features together correctly, and disallow the combination for now. Whenever a device supports integrity, the kernel will pretend that the device does not support hardware inline encryption (by setting the blk_crypto_profile in the request_queue of the device to NULL). -When the crypto API fallback is enabled, this means that all bios with and +When the crypto API fallback is enabled, this means that all bios with an encryption context will use the fallback, and IO will complete as usual. When the fallback is disabled, a bio with an encryption context will be failed. diff --git a/Documentation/block/ublk.rst b/Documentation/block/ublk.rst index 0413dcd9ef69..28300fee22bf 100644 --- a/Documentation/block/ublk.rst +++ b/Documentation/block/ublk.rst @@ -382,17 +382,17 @@ Zero copy --------- ublk zero copy relies on io_uring's fixed kernel buffer, which provides -two APIs: `io_buffer_register_bvec()` and `io_buffer_unregister_bvec`. +two APIs: `io_buffer_register_request()` and `io_buffer_unregister`. ublk adds IO command of `UBLK_IO_REGISTER_IO_BUF` to call -`io_buffer_register_bvec()` for ublk server to register client request +`io_buffer_register_request()` for ublk server to register client request buffer into io_uring buffer table, then ublk server can submit io_uring IOs with the registered buffer index. IO command of `UBLK_IO_UNREGISTER_IO_BUF` -calls `io_buffer_unregister_bvec()` to unregister the buffer, which is -guaranteed to be live between calling `io_buffer_register_bvec()` and -`io_buffer_unregister_bvec()`. Any io_uring operation which supports this -kind of kernel buffer will grab one reference of the buffer until the -operation is completed. +calls `io_buffer_unregister()` to unregister the buffer, which is guaranteed +to be live between calling `io_buffer_register_request()` and +`io_buffer_unregister()`. Any io_uring operation which supports this kind of +kernel buffer will grab one reference of the buffer until the operation is +completed. ublk server implementing zero copy or user copy has to be CAP_SYS_ADMIN and be trusted, because it is ublk server's responsibility to make sure IO buffer |