From 946b8f6fb02642cc925455132261671398094152 Mon Sep 17 00:00:00 2001
From: John Baldwin <jhb@FreeBSD.org>
Date: Thu, 16 Jul 2020 21:30:46 +0000
Subject: Add crypto_initreq() and crypto_destroyreq().

These routines are similar to crypto_getreq() and crypto_freereq() but
operate on caller-supplied storage instead of allocating crypto
requests from a UMA zone.

Reviewed by:	markj
Sponsored by:	Netflix
Differential Revision:	https://reviews.freebsd.org/D25691
---
 share/man/man9/Makefile         |  4 +++-
 share/man/man9/crypto_request.9 | 35 ++++++++++++++++++++++++++++++-----
 2 files changed, 33 insertions(+), 6 deletions(-)

(limited to 'share')

diff --git a/share/man/man9/Makefile b/share/man/man9/Makefile
index f5a91afe7ab1..96a7c819eb18 100644
--- a/share/man/man9/Makefile
+++ b/share/man/man9/Makefile
@@ -927,9 +927,11 @@ MLINKS+=crypto_driver.9 crypto_copyback.9 \
 	crypto_driver.9 CRYPTODEV_PROCESS.9 \
 	crypto_driver.9 hmac_init_ipad.9 \
 	crypto_driver.9 hmac_init_opad.9
-MLINKS+=crypto_request.9 crypto_dispatch.9 \
+MLINKS+=crypto_request.9 crypto_destroyreq.9 \
+	crypto_request.9 crypto_dispatch.9 \
 	crypto_request.9 crypto_freereq.9 \
 	crypto_request.9 crypto_getreq.9 \
+	crypto_request.9 crypto_initreq.9 \
 	crypto_request.9 crypto_use_buf.9 \
 	crypto_request.9 crypto_use_mbuf.9 \
 	crypto_request.9 crypto_use_output_buf.9 \
diff --git a/share/man/man9/crypto_request.9 b/share/man/man9/crypto_request.9
index 1a46a5a9962d..69b2a82d7ab1 100644
--- a/share/man/man9/crypto_request.9
+++ b/share/man/man9/crypto_request.9
@@ -30,7 +30,7 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd June 22, 2020
+.Dd July 16, 2020
 .Dt CRYPTO_REQUEST 9
 .Os
 .Sh NAME
@@ -41,10 +41,14 @@
 .Ft int
 .Fn crypto_dispatch "struct cryptop *crp"
 .Ft void
+.Fn crypto_destroyreq "struct cryptop *crp"
+.Ft void
 .Fn crypto_freereq "struct cryptop *crp"
 .Ft "struct cryptop *"
 .Fn crypto_getreq "crypto_session_t cses" "int how"
 .Ft void
+.Fn crypto_initreq "crypto_session_t cses" "int how"
+.Ft void
 .Fn crypto_use_buf "struct cryptop *crp" "void *buf" "int len"
 .Ft void
 .Fn crypto_use_mbuf "struct cryptop *crp" "struct mbuf *m"
@@ -62,10 +66,27 @@ an instance of
 .Vt struct cryptop
 and is associated with an active session.
 .Pp
-New requests are allocated by
-.Fn crypto_getreq .
+Requests can either be allocated dynamically or use caller-supplied
+storage.
+Dynamically allocated requests should be allocated by
+.Fn crypto_getreq
+and freed by
+.Fn crypto_freereq
+once the request has completed.
+Requests using caller-supplied storage should be initialized by
+.Fn crypto_initreq
+at the start of each operation and destroyed by
+.Fn crypto_destroyreq
+once the request has completed.
+.Pp
+For both
+.Fn crypto_getreq
+and
+.Fn crypto_initreq ,
 .Fa cses
 is a reference to an active session.
+For
+.Fn crypto_getreq ,
 .Fa how
 is passed to
 .Xr malloc 9
@@ -73,7 +94,9 @@ and should be set to either
 .Dv M_NOWAIT
 or
 .Dv M_WAITOK .
-The caller should then set fields in the returned structure to describe
+.Pp
+Once a request has been initialized,
+the caller should set fields in the structure to describe
 request-specific parameters.
 Unused fields should be left as-is.
 .Pp
@@ -92,7 +115,9 @@ Note that a request's callback function may be invoked before
 returns.
 .Pp
 Once a request has signaled completion by invoking its callback function,
-it should be feed via
+it should be freed via
+.Fn crypto_destroyreq
+or
 .Fn crypto_freereq .
 .Pp
 Cryptographic operations include several fields to describe the request.
-- 
cgit v1.2.3