Documentation/crypto/async-tx-api.rst

Source file repositories/reference/linux-study-clean/Documentation/crypto/async-tx-api.rst

File Facts

System
Linux kernel
Corpus path
Documentation/crypto/async-tx-api.rst
Extension
.rst
Size
10096 bytes
Lines
271
Domain
Support Tooling And Documentation
Bucket
Documentation
Inferred role
Support Tooling And Documentation: documentation
Status
atlas-only

Why This File Exists

Repository support layer: documentation, build tooling, samples, user-space helper tools, generated initramfs support, licenses, and validation utilities.

Dependency Surface

Detected Declarations

Annotated Snippet

.. SPDX-License-Identifier: GPL-2.0

=====================================
Asynchronous Transfers/Transforms API
=====================================

.. Contents

  1. INTRODUCTION

  2 GENEALOGY

  3 USAGE
  3.1 General format of the API
  3.2 Supported operations
  3.3 Descriptor management
  3.4 When does the operation execute?
  3.5 When does the operation complete?
  3.6 Constraints
  3.7 Example

  4 DMAENGINE DRIVER DEVELOPER NOTES
  4.1 Conformance points
  4.2 "My application needs exclusive control of hardware channels"

  5 SOURCE

1. Introduction
===============

The async_tx API provides methods for describing a chain of asynchronous
bulk memory transfers/transforms with support for inter-transactional
dependencies.  It is implemented as a dmaengine client that smooths over
the details of different hardware offload engine implementations.  Code
that is written to the API can optimize for asynchronous operation and
the API will fit the chain of operations to the available offload
resources.

2.Genealogy
===========

The API was initially designed to offload the memory copy and
xor-parity-calculations of the md-raid5 driver using the offload engines
present in the Intel(R) Xscale series of I/O processors.  It also built
on the 'dmaengine' layer developed for offloading memory copies in the
network stack using Intel(R) I/OAT engines.  The following design
features surfaced as a result:

1. implicit synchronous path: users of the API do not need to know if
   the platform they are running on has offload capabilities.  The
   operation will be offloaded when an engine is available and carried out
   in software otherwise.
2. cross channel dependency chains: the API allows a chain of dependent
   operations to be submitted, like xor->copy->xor in the raid5 case.  The
   API automatically handles cases where the transition from one operation
   to another implies a hardware channel switch.
3. dmaengine extensions to support multiple clients and operation types
   beyond 'memcpy'

3. Usage
========

3.1 General format of the API
-----------------------------

::

  struct dma_async_tx_descriptor *
  async_<operation>(<op specific parameters>, struct async_submit_ctl *submit)

Annotation

Implementation Notes