linux-stable/Documentation
Eric Biggers 20f01f1632 blk-crypto: show crypto capabilities in sysfs
Add sysfs files that expose the inline encryption capabilities of
request queues:

	/sys/block/$disk/queue/crypto/max_dun_bits
	/sys/block/$disk/queue/crypto/modes/$mode
	/sys/block/$disk/queue/crypto/num_keyslots

Userspace can use these new files to decide what encryption settings to
use, or whether to use inline encryption at all.  This also brings the
crypto capabilities in line with the other queue properties, which are
already discoverable via the queue directory in sysfs.

Design notes:

  - Place the new files in a new subdirectory "crypto" to group them
    together and to avoid complicating the main "queue" directory.  This
    also makes it possible to replace "crypto" with a symlink later if
    we ever make the blk_crypto_profiles into real kobjects (see below).

  - It was necessary to define a new kobject that corresponds to the
    crypto subdirectory.  For now, this kobject just contains a pointer
    to the blk_crypto_profile.  Note that multiple queues (and hence
    multiple such kobjects) may refer to the same blk_crypto_profile.

    An alternative design would more closely match the current kernel
    data structures: the blk_crypto_profile could be a kobject itself,
    located directly under the host controller device's kobject, while
    /sys/block/$disk/queue/crypto would be a symlink to it.

    I decided not to do that for now because it would require a lot more
    changes, such as no longer embedding blk_crypto_profile in other
    structures, and also because I'm not sure we can rule out moving the
    crypto capabilities into 'struct queue_limits' in the future.  (Even
    if multiple queues share the same crypto engine, maybe the supported
    data unit sizes could differ due to other queue properties.)  It
    would also still be possible to switch to that design later without
    breaking userspace, by replacing the directory with a symlink.

  - Use "max_dun_bits" instead of "max_dun_bytes".  Currently, the
    kernel internally stores this value in bytes, but that's an
    implementation detail.  It probably makes more sense to talk about
    this value in bits, and choosing bits is more future-proof.

  - "modes" is a sub-subdirectory, since there may be multiple supported
    crypto modes, sysfs is supposed to have one value per file, and it
    makes sense to group all the mode files together.

  - Each mode had to be named.  The crypto API names like "xts(aes)" are
    not appropriate because they don't specify the key size.  Therefore,
    I assigned new names.  The exact names chosen are arbitrary, but
    they happen to match the names used in log messages in fs/crypto/.

  - The "num_keyslots" file is a bit different from the others in that
    it is only useful to know for performance reasons.  However, it's
    included as it can still be useful.  For example, a user might not
    want to use inline encryption if there aren't very many keyslots.

Reviewed-by: Hannes Reinecke <hare@suse.de>
Signed-off-by: Eric Biggers <ebiggers@google.com>
Link: https://lore.kernel.org/r/20220124215938.2769-4-ebiggers@kernel.org
Signed-off-by: Jens Axboe <axboe@kernel.dk>
2022-02-28 06:40:23 -07:00
..
ABI blk-crypto: show crypto capabilities in sysfs 2022-02-28 06:40:23 -07:00
accounting - A bunch of fixes: forced idle time accounting, utilization values 2022-01-23 17:35:27 +02:00
admin-guide gpio: sim: add doc file to index file 2022-01-24 09:21:28 +01:00
arc docs: ARC: Improve readability 2021-12-10 14:28:01 -07:00
arm Documentation: arm: marvell: Extend Avanta list 2022-01-27 11:22:34 -07:00
arm64 arm64: cpufeature: List early Cortex-A510 parts as having broken dbm 2022-01-28 16:15:46 +00:00
block block: remove biodoc.rst 2022-02-15 07:47:52 -07:00
bpf bpf, docs: Fully document the JMP mode modifiers 2022-01-05 13:11:26 -08:00
cdrom
core-api Convert xfs/iomap to use folios 2022-01-12 12:51:41 -08:00
cpu-freq cpufreq: docs: Update core.rst 2021-12-01 20:02:11 +01:00
crypto
dev-tools This isn't a hugely busy cycle for documentation, but a few significant 2022-01-11 10:00:04 -08:00
devicetree - Drop an unused private data field in the AIC driver 2022-01-30 15:12:02 +02:00
doc-guide docs: discourage use of list tables 2022-01-07 09:33:13 -07:00
driver-api Three small documentation fixes. 2022-01-22 09:02:57 +02:00
fault-injection
fb
features ARM: 9158/1: leave it to core code to manage thread_info::cpu 2021-12-17 11:34:31 +00:00
filesystems The highlight is the new mount "device" string syntax implemented 2022-01-20 13:46:20 +02:00
firmware-guide Device properties framework updates for 5.17-rc1 2022-01-10 20:48:19 -08:00
firmware_class
fpga
gpu Merge tag 'amd-drm-next-5.17-2021-12-16' of https://gitlab.freedesktop.org/agd5f/linux into drm-next 2021-12-23 11:55:28 +10:00
hid
hwmon hwmon/pmbus: (ir38064) Add support for IR38060, IR38164 IR38263 2021-12-26 15:02:07 -08:00
i2c Docs: Fixes link to I2C specification 2021-12-31 14:39:28 +01:00
ia64
ide
iio
infiniband
input
isdn
kbuild doc: kbuild: fix default in imply table 2022-01-08 18:28:21 +09:00
kernel-hacking docs: fix typo in Documentation/kernel-hacking/locking.rst 2022-01-27 11:22:33 -07:00
leds
litmus-tests
livepatch Documentation: livepatch: Add livepatch API page 2021-12-23 11:35:53 +01:00
locking Documentation/locking/locktypes: Update migrate_disable() bits. 2021-11-30 15:40:31 +01:00
m68k
maintainer
mhi
mips
misc-devices
netlabel
networking This isn't a hugely busy cycle for documentation, but a few significant 2022-01-11 10:00:04 -08:00
nios2
nvdimm
openrisc
parisc
PCI
pcmcia
power Merge branches 'pm-opp', 'pm-devfreq' and 'powercap' 2022-01-10 18:00:31 +01:00
powerpc
process Kbuild updates for v5.17 2022-01-19 11:15:19 +02:00
RCU Merge branches 'doc.2021.11.30c', 'exp.2021.12.07a', 'fastnohz.2021.11.30c', 'fixes.2021.11.30c', 'nocb.2021.12.09a', 'nolibc.2021.11.30c', 'tasks.2021.12.09a', 'torture.2021.12.07a' and 'torturescript.2021.11.30c' into HEAD 2021-12-09 11:38:09 -08:00
riscv riscv: Move KASAN mapping next to the kernel mapping 2022-01-19 17:54:04 -08:00
s390
scheduler docs/scheduler: fix typo and warning in sched-bwc 2021-12-06 12:15:49 -07:00
scsi
security docs: update self-protection __ro_after_init status 2021-12-10 14:02:06 -07:00
sh
sound ALSA: hda/realtek: Add new alc285-hp-amp-init model 2021-12-14 10:44:26 +01:00
sparc
sphinx docs: automarkup.py: Fix invalid HTML link output and broken URI fragments 2022-01-07 09:32:58 -07:00
sphinx-static docs: add support for RTD dark mode 2021-12-10 14:05:55 -07:00
spi spi: pxa2xx: Get rid of unused enable_loopback member 2021-11-29 12:20:00 +00:00
staging Three small documentation fixes. 2022-01-22 09:02:57 +02:00
target
timers rcu: Remove the RCU_FAST_NO_HZ Kconfig option 2021-11-30 17:24:47 -08:00
tools docs: Hook the RTLA documents into the kernel docs build 2022-01-27 11:20:39 -07:00
trace Three small documentation fixes. 2022-01-22 09:02:57 +02:00
translations driver core changes for 5.17-rc1 2022-01-12 11:11:34 -08:00
tty Documentation: add TTY chapter 2021-11-26 16:27:43 +01:00
usb docs: ABI: fixed req_number desc in UAC1 2021-12-30 12:10:44 +01:00
userspace-api Merge branch 'acpi-pfrut' 2022-01-17 18:25:57 +01:00
virt Two larger x86 series: 2022-01-28 19:00:26 +02:00
vm docs/vm: Fix typo in *harden* 2022-01-27 11:22:34 -07:00
w1
watchdog
x86 x86/sgx: Fix minor documentation issues 2021-11-17 06:36:09 -08:00
xtensa
.gitignore
arch.rst docs: Add documentation for ARC processors 2021-11-29 14:53:11 -07:00
asm-annotations.rst
atomic_bitops.txt
atomic_t.txt
Changes
CodingStyle
conf.py docs: add support for RTD dark mode 2021-12-10 14:05:55 -07:00
COPYING-logo
docutils.conf
dontdiff
index.rst docs: Hook the RTLA documents into the kernel docs build 2022-01-27 11:20:39 -07:00
Kconfig
logo.gif
Makefile docs: address some text issues with css/theme support 2021-12-16 15:54:12 -07:00
memory-barriers.txt asm-generic: introduce io_stop_wc() and add implementation for ARM64 2021-12-22 10:44:53 +00:00
SubmittingPatches
watch_queue.rst