[PATCH v5 1/5] doc: replace asym crypto code with literal includes

[Ciara Power <ciara.power@intel.com>]

The programmer's guide for cryptodev included sample code for using
Asymmetric crypto. This is now replaced with direct code from the test
application, using literal includes. It is broken into snippets as the
test application didn't have all of the required code in one function.

Signed-off-by: Ciara Power <ciara.power@intel.com>
---
 app/test/test_cryptodev_asym.c             |   7 +-
 app/test/test_cryptodev_mod_test_vectors.h |   4 +
 doc/guides/prog_guide/cryptodev_lib.rst    | 176 ++++-----------------
 3 files changed, 37 insertions(+), 150 deletions(-)

diff --git a/app/test/test_cryptodev_asym.c b/app/test/test_cryptodev_asym.c
index 9d3a5589bb..8d7290f9ed 100644
--- a/app/test/test_cryptodev_asym.c
+++ b/app/test/test_cryptodev_asym.c
@@ -855,6 +855,7 @@ testsuite_setup(void)
 	test_vector.size = 0;
 	load_test_vectors();
 
+	/* Device, op pool and session configuration for asymmetric crypto. 8< */
 	ts_params->op_mpool = rte_crypto_op_pool_create(
 			"CRYPTO_ASYM_OP_POOL",
 			RTE_CRYPTO_OP_TYPE_ASYMMETRIC,
@@ -953,7 +954,7 @@ testsuite_setup(void)
 
 	TEST_ASSERT_NOT_NULL(ts_params->session_mpool,
 			"session mempool allocation failed");
-
+	/* >8 End of device, op pool and session configuration for asymmetric crypto section. */
 	return TEST_SUCCESS;
 }
 
@@ -1637,7 +1638,7 @@ test_mod_exp(void)
 				return TEST_SKIPPED;
 		}
 
-	/* generate crypto op data structure */
+	/* Create op, create session, and process packets. 8< */
 	op = rte_crypto_op_alloc(op_mpool, RTE_CRYPTO_OP_TYPE_ASYMMETRIC);
 	if (!op) {
 		RTE_LOG(ERR, USER1,
@@ -1696,7 +1697,7 @@ test_mod_exp(void)
 		status = TEST_FAILED;
 		goto error_exit;
 	}
-
+	/* >8 End of create op, create session, and process packets section. */
 	ret = verify_modexp(mod_exp, result_op);
 	if (ret) {
 		RTE_LOG(ERR, USER1,
diff --git a/app/test/test_cryptodev_mod_test_vectors.h b/app/test/test_cryptodev_mod_test_vectors.h
index c66f4b18bc..807ca7a47e 100644
--- a/app/test/test_cryptodev_mod_test_vectors.h
+++ b/app/test/test_cryptodev_mod_test_vectors.h
@@ -979,6 +979,7 @@ uint8_t base[] = {
 	0xA8, 0xEB, 0x7E, 0x78, 0xA0, 0x50
 };
 
+/* MODEX data. 8< */
 uint8_t mod_p[] = {
 	0x00, 0xb3, 0xa1, 0xaf, 0xb7, 0x13, 0x08, 0x00,
 	0x0a, 0x35, 0xdc, 0x2b, 0x20, 0x8d, 0xa1, 0xb5,
@@ -1000,6 +1001,7 @@ uint8_t mod_p[] = {
 };
 
 uint8_t mod_e[] = {0x01, 0x00, 0x01};
+/* >8 End of MODEX data. */
 
 /* Precomputed modular exponentiation for verification */
 uint8_t mod_exp[] = {
@@ -1041,6 +1043,7 @@ uint8_t mod_inv[] = {
 	0x9a, 0x66, 0x9a, 0x3a, 0xc1, 0xb8, 0x4b, 0xc3
 };
 
+/* MODEX vector. 8< */
 struct rte_crypto_asym_xform modex_xform = {
 	.next = NULL,
 	.xform_type = RTE_CRYPTO_ASYM_XFORM_MODEX,
@@ -1055,6 +1058,7 @@ struct rte_crypto_asym_xform modex_xform = {
 		}
 	}
 };
+/* >8 End of MODEX vector. */
 
 struct rte_crypto_asym_xform modinv_xform = {
 	.next = NULL,
diff --git a/doc/guides/prog_guide/cryptodev_lib.rst b/doc/guides/prog_guide/cryptodev_lib.rst
index 8766bc34a9..9f33f7a177 100644
--- a/doc/guides/prog_guide/cryptodev_lib.rst
+++ b/doc/guides/prog_guide/cryptodev_lib.rst
@@ -1119,162 +1119,44 @@ Asymmetric crypto Sample code
 There's a unit test application test_cryptodev_asym.c inside unit test framework that
 show how to setup and process asymmetric operations using cryptodev library.
 
-The following sample code shows the basic steps to compute modular exponentiation
-using 1024-bit modulus length using openssl PMD available in DPDK (performing other
-crypto operations is similar except change to respective op and xform setup).
+The following code samples are taken from the test application mentioned above,
+and show basic steps to compute modular exponentiation using an openssl PMD
+available in DPDK (performing other crypto operations is similar except change
+to respective op and xform setup).
 
-.. code-block:: c
+.. note::
+   The following code snippets are taken from multiple functions, so variable
+   names may differ slightly between sections.
 
-    /*
-     * Simple example to compute modular exponentiation with 1024-bit key
-     *
-     */
-    #define MAX_ASYM_SESSIONS	10
-    #define NUM_ASYM_BUFS	10
-
-    struct rte_mempool *crypto_op_pool, *asym_session_pool;
-    unsigned int asym_session_size;
-    int ret;
+Configure the virtual device, queue pairs, crypto op pool and session mempool.
 
-    /* Initialize EAL. */
-    ret = rte_eal_init(argc, argv);
-    if (ret < 0)
-        rte_exit(EXIT_FAILURE, "Invalid EAL arguments\n");
+.. literalinclude:: ../../../app/test/test_cryptodev_asym.c
+   :language: c
+   :start-after: Device, op pool and session configuration for asymmetric crypto. 8<
+   :end-before: >8 End of device, op pool and session configuration for asymmetric crypto section.
+   :dedent: 1
 
-    uint8_t socket_id = rte_socket_id();
-
-    /* Create crypto operation pool. */
-    crypto_op_pool = rte_crypto_op_pool_create(
-                                    "crypto_op_pool",
-                                    RTE_CRYPTO_OP_TYPE_ASYMMETRIC,
-                                    NUM_ASYM_BUFS, 0, 0,
-                                    socket_id);
-    if (crypto_op_pool == NULL)
-        rte_exit(EXIT_FAILURE, "Cannot create crypto op pool\n");
-
-    /* Create the virtual crypto device. */
-    char args[128];
-    const char *crypto_name = "crypto_openssl";
-    snprintf(args, sizeof(args), "socket_id=%d", socket_id);
-    ret = rte_vdev_init(crypto_name, args);
-    if (ret != 0)
-        rte_exit(EXIT_FAILURE, "Cannot create virtual device");
+Create MODEX data vectors.
 
-    uint8_t cdev_id = rte_cryptodev_get_dev_id(crypto_name);
+.. literalinclude:: ../../../app/test/test_cryptodev_mod_test_vectors.h
+   :language: c
+   :start-after: MODEX data. 8<
+   :end-before: >8 End of MODEX data.
 
-    /* Get private asym session data size. */
-    asym_session_size = rte_cryptodev_get_asym_private_session_size(cdev_id);
+Setup crypto xform to do modular exponentiation using data vectors.
 
-    /*
-     * Create session mempool, with two objects per session,
-     * one for the session header and another one for the
-     * private asym session data for the crypto device.
-     */
-    asym_session_pool = rte_mempool_create("asym_session_pool",
-                                    MAX_ASYM_SESSIONS * 2,
-                                    asym_session_size,
-                                    0,
-                                    0, NULL, NULL, NULL,
-                                    NULL, socket_id,
-                                    0);
+.. literalinclude:: ../../../app/test/test_cryptodev_mod_test_vectors.h
+   :language: c
+   :start-after: MODEX vector. 8<
+   :end-before: >8 End of MODEX vector.
 
-    /* Configure the crypto device. */
-    struct rte_cryptodev_config conf = {
-        .nb_queue_pairs = 1,
-        .socket_id = socket_id
-    };
-    struct rte_cryptodev_qp_conf qp_conf = {
-        .nb_descriptors = 2048
-    };
+Generate crypto op, create and attach a session, then process packets.
 
-    if (rte_cryptodev_configure(cdev_id, &conf) < 0)
-        rte_exit(EXIT_FAILURE, "Failed to configure cryptodev %u", cdev_id);
-
-    if (rte_cryptodev_queue_pair_setup(cdev_id, 0, &qp_conf,
-                            socket_id, asym_session_pool) < 0)
-        rte_exit(EXIT_FAILURE, "Failed to setup queue pair\n");
-
-    if (rte_cryptodev_start(cdev_id) < 0)
-        rte_exit(EXIT_FAILURE, "Failed to start device\n");
-
-    /* Setup crypto xform to do modular exponentiation with 1024 bit
-	 * length modulus
-	 */
-    struct rte_crypto_asym_xform modex_xform = {
-		.next = NULL,
-		.xform_type = RTE_CRYPTO_ASYM_XFORM_MODEX,
-		.modex = {
-			.modulus = {
-				.data =
-				(uint8_t *)
-				("\xb3\xa1\xaf\xb7\x13\x08\x00\x0a\x35\xdc\x2b\x20\x8d"
-				"\xa1\xb5\xce\x47\x8a\xc3\x80\xf4\x7d\x4a\xa2\x62\xfd\x61\x7f"
-				"\xb5\xa8\xde\x0a\x17\x97\xa0\xbf\xdf\x56\x5a\x3d\x51\x56\x4f"
-				"\x70\x70\x3f\x63\x6a\x44\x5b\xad\x84\x0d\x3f\x27\x6e\x3b\x34"
-				"\x91\x60\x14\xb9\xaa\x72\xfd\xa3\x64\xd2\x03\xa7\x53\x87\x9e"
-				"\x88\x0b\xc1\x14\x93\x1a\x62\xff\xb1\x5d\x74\xcd\x59\x63\x18"
-				"\x11\x3d\x4f\xba\x75\xd4\x33\x4e\x23\x6b\x7b\x57\x44\xe1\xd3"
-				"\x03\x13\xa6\xf0\x8b\x60\xb0\x9e\xee\x75\x08\x9d\x71\x63\x13"
-				"\xcb\xa6\x81\x92\x14\x03\x22\x2d\xde\x55"),
-				.length = 128
-			},
-			.exponent = {
-				.data = (uint8_t *)("\x01\x00\x01"),
-				.length = 3
-			}
-		}
-    };
-    /* Create asym crypto session and initialize it for the crypto device. */
-    struct rte_cryptodev_asym_session *asym_session;
-    asym_session = rte_cryptodev_asym_session_create(asym_session_pool);
-    if (asym_session == NULL)
-        rte_exit(EXIT_FAILURE, "Session could not be created\n");
-
-    if (rte_cryptodev_asym_session_init(cdev_id, asym_session,
-                    &modex_xform, asym_session_pool) < 0)
-        rte_exit(EXIT_FAILURE, "Session could not be initialized "
-                    "for the crypto device\n");
-
-    /* Get a burst of crypto operations. */
-    struct rte_crypto_op *crypto_ops[1];
-    if (rte_crypto_op_bulk_alloc(crypto_op_pool,
-                            RTE_CRYPTO_OP_TYPE_ASYMMETRIC,
-                            crypto_ops, 1) == 0)
-        rte_exit(EXIT_FAILURE, "Not enough crypto operations available\n");
-
-    /* Set up the crypto operations. */
-    struct rte_crypto_asym_op *asym_op = crypto_ops[0]->asym;
-
-	/* calculate mod exp of value 0xf8 */
-    static unsigned char base[] = {0xF8};
-    asym_op->modex.base.data = base;
-    asym_op->modex.base.length = sizeof(base);
-	asym_op->modex.base.iova = base;
-
-    /* Attach the asym crypto session to the operation */
-    rte_crypto_op_attach_asym_session(op, asym_session);
-
-    /* Enqueue the crypto operations in the crypto device. */
-    uint16_t num_enqueued_ops = rte_cryptodev_enqueue_burst(cdev_id, 0,
-                                            crypto_ops, 1);
-
-    /*
-     * Dequeue the crypto operations until all the operations
-     * are processed in the crypto device.
-     */
-    uint16_t num_dequeued_ops, total_num_dequeued_ops = 0;
-    do {
-        struct rte_crypto_op *dequeued_ops[1];
-        num_dequeued_ops = rte_cryptodev_dequeue_burst(cdev_id, 0,
-                                        dequeued_ops, 1);
-        total_num_dequeued_ops += num_dequeued_ops;
-
-        /* Check if operation was processed successfully */
-        if (dequeued_ops[0]->status != RTE_CRYPTO_OP_STATUS_SUCCESS)
-                rte_exit(EXIT_FAILURE,
-                        "Some operations were not processed correctly");
-
-    } while (total_num_dequeued_ops < num_enqueued_ops);
+.. literalinclude:: ../../../app/test/test_cryptodev_asym.c
+   :language: c
+   :start-after: Create op, create session, and process packets. 8<
+   :end-before: >8 End of create op, create session, and process packets section.
+   :dedent: 1
 
 
 Asymmetric Crypto Device API
-- 
2.25.1