Changeset View
Changeset View
Standalone View
Standalone View
share/man/man9/crypto_request.9
Show All 24 Lines | |||||||||
.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) | .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) | ||||||||
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE | .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE | ||||||||
.\" POSSIBILITY OF SUCH DAMAGE. | .\" POSSIBILITY OF SUCH DAMAGE. | ||||||||
.\" | .\" | ||||||||
.\" * Other names and brands may be claimed as the property of others. | .\" * Other names and brands may be claimed as the property of others. | ||||||||
.\" | .\" | ||||||||
.\" $FreeBSD$ | .\" $FreeBSD$ | ||||||||
.\" | .\" | ||||||||
.Dd August 12, 2020 | .Dd January 30, 2021 | ||||||||
.Dt CRYPTO_REQUEST 9 | .Dt CRYPTO_REQUEST 9 | ||||||||
.Os | .Os | ||||||||
.Sh NAME | .Sh NAME | ||||||||
.Nm crypto_request | .Nm crypto_request | ||||||||
.Nd symmetric cryptographic operations | .Nd symmetric cryptographic operations | ||||||||
.Sh SYNOPSIS | .Sh SYNOPSIS | ||||||||
.In opencrypto/cryptodev.h | .In opencrypto/cryptodev.h | ||||||||
.Ft int | .Ft int | ||||||||
.Fn crypto_dispatch "struct cryptop *crp" | .Fn crypto_dispatch "struct cryptop *crp" | ||||||||
.Ft int | |||||||||
.Fn crypto_dispatch_async "struct cryptop *crp" "int flags" | |||||||||
.Ft void | .Ft void | ||||||||
.Fn crypto_dispatch_batch "struct cryptopq *crpq" "int flags" | |||||||||
.Ft void | |||||||||
.Fn crypto_destroyreq "struct cryptop *crp" | .Fn crypto_destroyreq "struct cryptop *crp" | ||||||||
.Ft void | .Ft void | ||||||||
.Fn crypto_freereq "struct cryptop *crp" | .Fn crypto_freereq "struct cryptop *crp" | ||||||||
.Ft "struct cryptop *" | .Ft "struct cryptop *" | ||||||||
.Fn crypto_getreq "crypto_session_t cses" "int how" | .Fn crypto_getreq "crypto_session_t cses" "int how" | ||||||||
.Ft void | .Ft void | ||||||||
.Fn crypto_initreq "crypto_session_t cses" "int how" | .Fn crypto_initreq "crypto_session_t cses" "int how" | ||||||||
.Ft void | .Ft void | ||||||||
▲ Show 20 Lines • Show All 47 Lines • ▼ Show 20 Lines | |||||||||
or | or | ||||||||
.Dv M_WAITOK . | .Dv M_WAITOK . | ||||||||
.Pp | .Pp | ||||||||
Once a request has been initialized, | Once a request has been initialized, | ||||||||
the caller should set fields in the structure to describe | the caller should set fields in the structure to describe | ||||||||
request-specific parameters. | request-specific parameters. | ||||||||
Unused fields should be left as-is. | Unused fields should be left as-is. | ||||||||
.Pp | .Pp | ||||||||
.Fn crypto_dispatch | The | ||||||||
passes a crypto request to the driver attached to the request's session. | .Fn crypto_dispatch , | ||||||||
If there are errors in the request's fields, this function may return | .Fn crypto_dispatch_async , | ||||||||
an error to the caller. | and | ||||||||
.Fn crypto_dispatch_batch | |||||||||
functions pass one or more crypto requests to the driver attached to the | |||||||||
request's session. | |||||||||
If there are errors in the request's fields, these functions may return an | |||||||||
jhbUnsubmitted Not Done Inline Actions
jhb: | |||||||||
error to the caller. | |||||||||
If errors are encountered while servicing the request, they will instead | If errors are encountered while servicing the request, they will instead | ||||||||
be reported to the request's callback function | be reported to the request's callback function | ||||||||
.Pq Fa crp_callback | .Pq Fa crp_callback | ||||||||
via | via | ||||||||
.Fa crp_etype . | .Fa crp_etype . | ||||||||
.Pp | .Pp | ||||||||
Note that a request's callback function may be invoked before | Note that a request's callback function may be invoked before | ||||||||
.Fn crypto_dispatch | .Fn crypto_dispatch | ||||||||
▲ Show 20 Lines • Show All 217 Lines • ▼ Show 20 Lines | |||||||||
should be left as zero. | should be left as zero. | ||||||||
.Pp | .Pp | ||||||||
Requests that store part, but not all, of the IV in the data buffer should | Requests that store part, but not all, of the IV in the data buffer should | ||||||||
store the partial IV in the data buffer and pass the full IV separately in | store the partial IV in the data buffer and pass the full IV separately in | ||||||||
.Fa crp_iv . | .Fa crp_iv . | ||||||||
.Ss Request and Callback Scheduling | .Ss Request and Callback Scheduling | ||||||||
The crypto framework provides multiple methods of scheduling the dispatch | The crypto framework provides multiple methods of scheduling the dispatch | ||||||||
of requests to drivers along with the processing of driver callbacks. | of requests to drivers along with the processing of driver callbacks. | ||||||||
Requests use flags in | The | ||||||||
.Fa crp_flags | .Fn crypto_dispatch , | ||||||||
to select the desired scheduling methods. | .Fn crypto_dispatch_async , | ||||||||
and | |||||||||
.Fn crypto_dispatch_batch | |||||||||
functions can be used to request different dispatch scheduling policies. | |||||||||
.Pp | .Pp | ||||||||
.Fn crypto_dispatch | .Fn crypto_dispatch | ||||||||
can pass the request to the session's driver via three different methods: | synchronously passes the request to the driver. | ||||||||
.Bl -enum | The driver itself may process the request synchronously or asynchronously | ||||||||
.It | depending on whether the driver is implemented by software or hardware. | ||||||||
The request is queued to a taskqueue backed by a pool of worker threads. | .Pp | ||||||||
.Fn crypto_dispatch_async | |||||||||
dispatches the request asynchronously. | |||||||||
If the driver is inherently synchronous, the request is queued to a taskqueue | |||||||||
backed by a pool of worker threads. | |||||||||
This can increase througput by allowing requests from a single producer to be | |||||||||
processed in parallel. | |||||||||
By default the pool is sized to provide one thread for each CPU. | By default the pool is sized to provide one thread for each CPU. | ||||||||
Worker threads dequeue requests and pass them to the driver | Worker threads dequeue requests and pass them to the driver asynchronously. | ||||||||
asynchronously. | .Fn crypto_dispatch_async | ||||||||
.It | additionally takes a | ||||||||
The request is passed to the driver synchronously in the context of the | .Va flags | ||||||||
thread invoking | parameter. | ||||||||
The | |||||||||
.Dv CRYPTO_ASYNC_ORDERED | |||||||||
flag indicates that completion callbacks for requests must be called in the | |||||||||
same order as requests were dispatched. | |||||||||
If the driver is asynchronous, the behavior of | |||||||||
.Fn crypto_dispatch_async | |||||||||
is identical to that of | |||||||||
.Fn crypto_dispatch . | .Fn crypto_dispatch . | ||||||||
.It | |||||||||
The request is queued to a queue of pending requests. | |||||||||
A single worker thread dequeues requests and passes them to the driver | |||||||||
asynchronously. | |||||||||
.El | |||||||||
.Pp | .Pp | ||||||||
To select the first method (taskqueue backed by multiple threads), | .Fn crypto_dispatch_batch | ||||||||
requests should set | allows the caller to collect a batch of requests and submit them to the driver | ||||||||
.Dv CRYPTO_F_ASYNC . | at the same time. | ||||||||
To always use the third method (queue to single worker thread), | This allows hardware drivers to optimize the scheduling of request processing | ||||||||
requests should set | and batch completion interrupts. | ||||||||
.Dv CRYPTO_F_BATCH . | A batch is submitted to the driver by invoking the driver's process method on | ||||||||
If both flags are set, | each request, specifying | ||||||||
.Dv CRYPTO_F_ASYNC | |||||||||
takes precedence. | |||||||||
If neither flag is set, | |||||||||
.Fn crypto_dispatch | |||||||||
will first attempt the second method (invoke driver synchronously). | |||||||||
If the driver is blocked, | |||||||||
the request will be queued using the third method. | |||||||||
One caveat is that the first method is only used for requests using software | |||||||||
drivers which use host CPUs to process requests. | |||||||||
Requests whose session is associated with a hardware driver will ignore | |||||||||
.Dv CRYPTO_F_ASYNC | |||||||||
and only use | |||||||||
.Dv CRYPTO_F_BATCH | |||||||||
to determine how requests should be scheduled. | |||||||||
.Pp | |||||||||
In addition to bypassing synchronous dispatch in | |||||||||
.Fn crypto_dispatch , | |||||||||
.Dv CRYPTO_F_BATCH | |||||||||
requests additional changes aimed at optimizing batches of requests to | |||||||||
the same driver. | |||||||||
When the worker thread processes a request with | |||||||||
.Dv CRYPTO_F_BATCH , | |||||||||
it will search the pending request queue for any other requests for the same | |||||||||
driver, | |||||||||
including requests from different sessions. | |||||||||
If any other requests are present, | |||||||||
.Dv CRYPTO_HINT_MORE | .Dv CRYPTO_HINT_MORE | ||||||||
is passed to the driver's process method. | with each request except for the last. | ||||||||
Drivers may use this to batch completion interrupts. | The | ||||||||
.Fa flags | |||||||||
parameter to | |||||||||
.Fn crypto_dispatch_batch | |||||||||
is currently ignored. | |||||||||
.Pp | .Pp | ||||||||
Callback function scheduling is simpler than request scheduling. | Callback function scheduling is simpler than request scheduling. | ||||||||
Callbacks can either be invoked synchronously from | Callbacks can either be invoked synchronously from | ||||||||
.Fn crypto_done , | .Fn crypto_done , | ||||||||
or they can be queued to a pool of worker threads. | or they can be queued to a pool of worker threads. | ||||||||
This pool of worker threads is also sized to provide one worker thread | This pool of worker threads is also sized to provide one worker thread | ||||||||
for each CPU by default. | for each CPU by default. | ||||||||
Note that a callback function invoked synchronously from | Note that a callback function invoked synchronously from | ||||||||
▲ Show 20 Lines • Show All 120 Lines • Show Last 20 Lines |