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 February 8, 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 | |||||||||