Address bug https://bugs.linaro.org/show_bug.cgi?id=2557 by replacing the
use_entropy parameter with a more comprehensive enum that specifies the
kind of random data requested.
Signed-off-by: Bill Fischofer <bill.fischo...@linaro.org>
---
Changes in v4:
- Normalize random API signatures with other ODP APIs
- Add new odp_random_seeded_data() API for repeatable random data generation
- Add additional tests for new odp_random_seeded_data() API
- Break out crypto section of User Guide to its own sub-document
- Add User Guide docuemntation for ODP random data API.
Changes in v3:
- Address commments by Petri
- Rename ODP_RAND_NORMAL to ODP_RANDOM_BASIC to avoid confusion with the
mathematical term "normal"
include/odp/api/spec/random.h | 31 ++++++++++++++++++++++++++-----
1 file changed, 26 insertions(+), 5 deletions(-)
diff --git a/include/odp/api/spec/random.h b/include/odp/api/spec/random.h
index 00fa15b..62f2376 100644
--- a/include/odp/api/spec/random.h
+++ b/include/odp/api/spec/random.h
@@ -24,18 +24,39 @@ extern "C" {
*/
/**
+ * Random kind selector
+ */
+typedef enum {
+ /** Basic random, presumably pseudo-random generated by SW */
+ ODP_RANDOM_BASIC,
+ /** Cryptographic quality random */
+ ODP_RANDOM_CRYPTO,
+ /** True random, generated from a HW entropy source */
+ ODP_RANDOM_TRUE,
+} odp_random_kind_t;
+
+/**
* Generate random byte data
*
- * @param[out] buf Output buffer
- * @param size Size of output buffer
- * @param use_entropy Use entropy
+ * The intent in supporting different kinds of random data is to allow
+ * tradeoffs between performance and the quality of random data needed. The
+ * assumption is that basic random is cheap while true random is relatively
+ * expensive in terms of time to generate, with cryptographic random being
+ * something in between. Implementations that support highly efficient true
+ * random are free to use this for all requested kinds. So it is always
+ * permissible to "upgrade" a random data request, but never to "downgrade"
+ * such requests.
*
- * @todo Define the implication of the use_entropy parameter
+ * @param[out] buf Output buffer
+ * @param len Length of output buffer in bytes
+ * @param kind Specifies the type of random data required. Request
+ * is expected to fail if the implementation is unable to
+ * provide the requested type.
*
* @return Number of bytes written
* @retval <0 on failure
*/
-int32_t odp_random_data(uint8_t *buf, int32_t size, odp_bool_t use_entropy);
+int odp_random_data(uint8_t *buf, uint32_t len, odp_random_kind_t kind);
/**
* @}
--
2.7.4
