Contiki-NG
soc-trng.h
Go to the documentation of this file.
1 /*
2  * Copyright (c) 2016, University of Bristol - http://www.bristol.ac.uk
3  * All rights reserved.
4  *
5  * Redistribution and use in source and binary forms, with or without
6  * modification, are permitted provided that the following conditions
7  * are met:
8  * 1. Redistributions of source code must retain the above copyright
9  * notice, this list of conditions and the following disclaimer.
10  * 2. Redistributions in binary form must reproduce the above copyright
11  * notice, this list of conditions and the following disclaimer in the
12  * documentation and/or other materials provided with the distribution.
13  * 3. Neither the name of the copyright holder nor the names of its
14  * contributors may be used to endorse or promote products derived
15  * from this software without specific prior written permission.
16  *
17  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
18  * ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
19  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
20  * FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
21  * COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
22  * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
23  * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
24  * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
25  * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
26  * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
27  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
28  * OF THE POSSIBILITY OF SUCH DAMAGE.
29  */
30 /*---------------------------------------------------------------------------*/
31 /**
32  * \addtogroup cc26xx
33  * @{
34  *
35  * \defgroup cc26xx-trng CC13xx/CC26xx Random Number Generator
36  *
37  * Driver for the CC13xx/CC26xx Random Number Generator
38  *
39  * @{
40  *
41  * \file
42  *
43  * Header file for the CC13xx/CC26xx TRNG driver
44  */
45 /*---------------------------------------------------------------------------*/
46 #ifndef SOC_TRNG_H_
47 #define SOC_TRNG_H_
48 /*---------------------------------------------------------------------------*/
49 #include <stdint.h>
50 /*---------------------------------------------------------------------------*/
51 #define SOC_TRNG_RAND_ASYNC_REQUEST_ERROR 0 /**< Async request rejected */
52 #define SOC_TRNG_RAND_ASYNC_REQUEST_OK 1 /**< Async request accepted */
53 /*---------------------------------------------------------------------------*/
54 #define SOC_TRNG_REFILL_CYCLES_MIN 0x00000100
55 #define SOC_TRNG_REFILL_CYCLES_MAX 0x00000000
56 /*---------------------------------------------------------------------------*/
57 /**
58  * \brief Pointer to a callback to be provided as an argument to
59  * soc_trng_rand_asynchronous()
60  */
61 typedef void (*soc_trng_callback_t)(uint64_t rand);
62 /*---------------------------------------------------------------------------*/
63 /**
64  * \name TRNG functions
65  * @{
66  */
67 
68 /**
69  * \brief Returns a minimum entropy random number
70  * \return The random number
71  *
72  * This function is synchronous. This function will make sure the PERIPH PD is
73  * powered and the TRNG is clocked. The function will then configure the TRNG
74  * to generate a random number of minimum entropy. These numbers are not
75  * suitable for cryptographic usage, but their generation is very fast.
76  *
77  * If a high-entropy random number is currently being generated, this function
78  * will return a cached random number. The cache is of configurable size and
79  * can hold a maximum SOC_TRNG_CONF_CACHE_LEN numbers. If the cache gets
80  * emptied while high-entropy generation is in progress (e.g. because a
81  * function requested many random numbers in a row), this function will return
82  * 0. Care must therefore be taken when the return value is 0, which can also
83  * be a valid random number.
84  *
85  * This function can be safely called from within an interrupt context.
86  */
87 uint64_t soc_trng_rand_synchronous();
88 
89 /**
90  * \brief Initialise the CC13xx/CC26xx TRNG driver
91  */
92 void soc_trng_init(void);
93 
94 /**
95  * \brief Request a 64-bit, configurable-entropy random number
96  * \param samples Controls the entropy generated for the random number
97  * \param cb A callback function to be called when the generation is complete
98  * \retval SOC_TRNG_RAND_ASYNC_REQUEST_ERROR There was an error adding request.
99  * \retval SOC_TRNG_RAND_ASYNC_REQUEST_OK Request successfully registered
100  *
101  * This function is asynchronous, it will start generation of a random number
102  * and will return. The caller must provide a callback that will be called when
103  * the generation is complete. This callback must either use the random number
104  * immediately or store it, since it will not be possible to retrieve it again
105  * later form the soc-trng module.
106  *
107  * Only one generation can be active at any given point in time. If this
108  * function gets called when a generation is already in progress, it will
109  * return SOC_TRNG_RAND_ASYNC_REQUEST_ERROR.
110  *
111  * The function will configure the TRNG to generate entropy by sampling the
112  * FROs for a number clock cycles controlled by the samples argument. The 8 LS
113  * bits of this argument will be truncated by CC13xxware/CC26xxware and the
114  * resulting number of clock cycles will be (samples >> 8) * 2^8. Increasing
115  * the value of this argument increases entropy, but it also increases latency.
116  * Maximum entropy can be generated by passing SOC_TRNG_REFILL_CYCLES_MAX, but
117  * this will take approximately 350ms. Consult the chip's technical reference
118  * manual for advice on what would constitute sufficient entropy for random
119  * numbers meant to be used for crypto.
120  *
121  * While this function is executing, calls to soc_trng_rand_synchronous() will
122  * return cached random numbers.
123  *
124  * This function is not re-entrant and must not be called from an interrupt
125  * context.
126  */
127 uint8_t soc_trng_rand_asynchronous(uint32_t samples, soc_trng_callback_t cb);
128 /** @} */
129 /*---------------------------------------------------------------------------*/
130 #endif /* SOC_TRNG_H_ */
131 /*---------------------------------------------------------------------------*/
132 /**
133  * @}
134  * @}
135  */
void soc_trng_init()
Initialise the CC13xx/CC26xx TRNG driver.
Definition: soc-trng.c:298
uint64_t soc_trng_rand_synchronous()
Returns a minimum entropy random number.
Definition: soc-trng.c:145
uint8_t soc_trng_rand_asynchronous(uint32_t samples, soc_trng_callback_t cb)
Request a 64-bit, configurable-entropy random number.
Definition: soc-trng.c:191
void(* soc_trng_callback_t)(uint64_t rand)
Pointer to a callback to be provided as an argument to soc_trng_rand_asynchronous() ...
Definition: soc-trng.h:61