Merge tag 'docs/v5.10-1' of git://git.kernel.org/pub/scm/linux/kernel/git/mchehab/linux-media

.. SPDX-License-Identifier: GPL-2.0

.. include:: <isonum.txt>

.. |struct cpufreq_policy| replace:: :c:type:`struct cpufreq_policy <cpufreq_policy>`

.. |intel_pstate| replace:: :doc:`intel_pstate <intel_pstate>`

=======================

all of those CPUs simultaneously.

Sets of CPUs sharing hardware P-state control interfaces are represented by

``CPUFreq`` as |struct cpufreq_policy| objects.  For consistency,

|struct cpufreq_policy| is also used when there is only one CPU in the given

``CPUFreq`` as struct cpufreq_policy objects.  For consistency,

struct cpufreq_policy is also used when there is only one CPU in the given

set.

The ``CPUFreq`` core maintains a pointer to a |struct cpufreq_policy| object for

The ``CPUFreq`` core maintains a pointer to a struct cpufreq_policy object for

every CPU in the system, including CPUs that are currently offline.  If multiple

CPUs share the same hardware P-state control interface, all of the pointers

corresponding to them point to the same |struct cpufreq_policy| object.

corresponding to them point to the same struct cpufreq_policy object.

``CPUFreq`` uses |struct cpufreq_policy| as its basic data type and the design

``CPUFreq`` uses struct cpufreq_policy as its basic data type and the design

of its user space interface is based on the policy concept.

Only a block device driver cares about these configurations. A block device

driver uses ``register_pstore_blk`` to register to pstore/blk.

.. kernel-doc:: fs/pstore/blk.c

   :identifiers: register_pstore_blk

A non-block device driver uses ``register_pstore_device`` with

``struct pstore_device_info`` to register to pstore/blk.

.. kernel-doc:: fs/pstore/blk.c

   :identifiers: register_pstore_device

.. kernel-doc:: include/linux/pstore_blk.h

   :identifiers: pstore_device_info

   :export:

Compression and header

----------------------

   :internal:

.. kernel-doc:: fs/pstore/blk.c

   :export:

   :internal:

.. kernel-doc:: include/linux/pstore_blk.h

   :internal:

~~~~~~~~~~~~~~~~~~~~~~~

The block IO subsystem adds requests  in the software staging queues

(represented by struct :c:type:`blk_mq_ctx`) in case that they weren't sent

(represented by struct blk_mq_ctx) in case that they weren't sent

directly to the driver. A request is one or more BIOs. They arrived at the

block layer through the data structure struct :c:type:`bio`. The block layer

will then build a new structure from it, the struct :c:type:`request` that will

block layer through the data structure struct bio. The block layer

will then build a new structure from it, the struct request that will

be used to communicate with the device driver. Each queue has its own lock and

the number of queues is defined by a per-CPU or per-node basis.

Hardware dispatch queues

~~~~~~~~~~~~~~~~~~~~~~~~

The hardware queue (represented by struct :c:type:`blk_mq_hw_ctx`) is a struct

The hardware queue (represented by struct blk_mq_hw_ctx) is a struct

used by device drivers to map the device submission queues (or device DMA ring

buffer), and are the last step of the block layer submission code before the

low level device driver taking ownership of the request. To run this queue, the

dispatch to the hardware.

If it's not possible to send the requests directly to hardware, they will be

added to a linked list (:c:type:`hctx->dispatch`) of requests. Then,

added to a linked list (``hctx->dispatch``) of requests. Then,

next time the block layer runs a queue, it will send the requests laying at the

:c:type:`dispatch` list first, to ensure a fairness dispatch with those

``dispatch`` list first, to ensure a fairness dispatch with those

requests that were ready to be sent first. The number of hardware queues

depends on the number of hardware contexts supported by the hardware and its

device driver, but it will not be more than the number of cores of the system.

Design

======

We add a :c:type:`struct bio_crypt_ctx` to :c:type:`struct bio` that can

We add a struct bio_crypt_ctx to struct bio that can

represent an encryption context, because we need to be able to pass this

encryption context from the upper layers (like the fs layer) to the

device driver to act upon.

=================================================================

We add a pointer to a ``bi_crypt_context`` and ``keyslot`` to

:c:type:`struct request`. These will be referred to as the ``crypto fields``

struct request. These will be referred to as the ``crypto fields``

for the request. This ``keyslot`` is the keyslot into which the

``bi_crypt_context`` has been programmed in the KSM of the ``request_queue``

that this request is being sent to.

If a ``request queue``'s inline encryption hardware claimed to support the

encryption context specified with a bio, then it will not be handled by the

``blk-crypto-fallback``. We will eventually reach a point in blk-mq when a

:c:type:`struct request` needs to be allocated for that bio. At that point,

struct request needs to be allocated for that bio. At that point,

blk-mq tries to program the encryption context into the ``request_queue``'s

keyslot_manager, and obtain a keyslot, which it stores in its newly added

``keyslot`` field. This keyslot is released when the request is completed.

The device driver also needs to tell the KSM how to actually manipulate the

IE hardware in the device to do things like programming the crypto key into

the IE hardware into a particular keyslot. All this is achieved through the

:c:type:`struct blk_ksm_ll_ops` field in the KSM that the device driver

struct blk_ksm_ll_ops field in the KSM that the device driver

must fill up after initing the ``blk_keyslot_manager``.

The KSM also handles runtime power management for the device when applicable

#

if major >= 3:

    sys.stderr.write('''WARNING: The kernel documentation build process

	does not work correctly with Sphinx v3.0 and above.  Expect errors

	in the generated output.

        support for Sphinx v3.0 and above is brand new. Be prepared for

        possible issues in the generated output.

        ''')

    if minor > 0 or patch >= 2:

        # Sphinx c function parser is more pedantic with regards to type

        # checking. Due to that, having macros at c:function cause problems.

        # Those needed to be scaped by using c_id_attributes[] array

        c_id_attributes = [

            # GCC Compiler types not parsed by Sphinx:

            "__restrict__",

            # include/linux/compiler_types.h:

            "__iomem",

            "__kernel",

            "noinstr",

            "notrace",

            "__percpu",

            "__rcu",

            "__user",

            # include/linux/compiler_attributes.h:

            "__alias",

            "__aligned",

            "__aligned_largest",

            "__always_inline",

            "__assume_aligned",

            "__cold",

            "__attribute_const__",

            "__copy",

            "__pure",

            "__designated_init",

            "__visible",

            "__printf",

            "__scanf",

            "__gnu_inline",

            "__malloc",

            "__mode",

            "__no_caller_saved_registers",

            "__noclone",

            "__nonstring",

            "__noreturn",

            "__packed",

            "__pure",

            "__section",

            "__always_unused",

            "__maybe_unused",

            "__used",

            "__weak",

            "noinline",

            # include/linux/memblock.h:

            "__init_memblock",

            "__meminit",

            # include/linux/init.h:

            "__init",

            "__ref",

            # include/linux/linkage.h:

            "asmlinkage",

        ]

else:

    extensions.append('cdomain')