contiki/cpu/cc26xx-cc13xx/dev/soc-trng.h
2016-06-15 10:32:03 +01:00

136 lines
5.9 KiB
C

/*
* Copyright (c) 2016, University of Bristol - http://www.bristol.ac.uk
* All rights reserved.
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions
* are met:
* 1. Redistributions of source code must retain the above copyright
* notice, this list of conditions and the following disclaimer.
* 2. Redistributions in binary form must reproduce the above copyright
* notice, this list of conditions and the following disclaimer in the
* documentation and/or other materials provided with the distribution.
* 3. Neither the name of the copyright holder nor the names of its
* contributors may be used to endorse or promote products derived
* from this software without specific prior written permission.
*
* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
* ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
* LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
* FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
* COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
* INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
* (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
* SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
* HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 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 POSSIBILITY OF SUCH DAMAGE.
*/
/*---------------------------------------------------------------------------*/
/**
* \addtogroup cc26xx
* @{
*
* \defgroup cc26xx-trng CC13xx/CC26xx Random Number Generator
*
* Driver for the CC13xx/CC26xx Random Number Generator
*
* @{
*
* \file
*
* Header file for the CC13xx/CC26xx TRNG driver
*/
/*---------------------------------------------------------------------------*/
#ifndef SOC_TRNG_H_
#define SOC_TRNG_H_
/*---------------------------------------------------------------------------*/
#include <stdint.h>
/*---------------------------------------------------------------------------*/
#define SOC_TRNG_RAND_ASYNC_REQUEST_ERROR 0 /**< Async request rejected */
#define SOC_TRNG_RAND_ASYNC_REQUEST_OK 1 /**< Async request accepted */
/*---------------------------------------------------------------------------*/
#define SOC_TRNG_REFILL_CYCLES_MIN 0x00000100
#define SOC_TRNG_REFILL_CYCLES_MAX 0x00000000
/*---------------------------------------------------------------------------*/
/**
* \brief Pointer to a callback to be provided as an argument to
* soc_trng_rand_asynchronous()
*/
typedef void (*soc_trng_callback_t)(uint64_t rand);
/*---------------------------------------------------------------------------*/
/**
* \name TRNG functions
* @{
*/
/**
* \brief Returns a minimum entropy random number
* \return The random number
*
* This function is synchronous. This function will make sure the PERIPH PD is
* powered and the TRNG is clocked. The function will then configure the TRNG
* to generate a random number of minimum entropy. These numbers are not
* suitable for cryptographic usage, but their generation is very fast.
*
* If a high-entropy random number is currently being generated, this function
* will return a cached random number. The cache is of configurable size and
* can hold a maximum SOC_TRNG_CONF_CACHE_LEN numbers. If the cache gets
* emptied while high-entropy generation is in progress (e.g. because a
* function requested many random numbers in a row), this function will return
* 0. Care must therefore be taken when the return value is 0, which can also
* be a valid random number.
*
* This function can be safely called from within an interrupt context.
*/
uint64_t soc_trng_rand_synchronous();
/**
* \brief Initialise the CC13xx/CC26xx TRNG driver
*/
void soc_trng_init(void);
/**
* \brief Request a 64-bit, configurable-entropy random number
* \param samples Controls the entropy generated for the random number
* \param cb A callback function to be called when the generation is complete
* \retval SOC_TRNG_RAND_ASYNC_REQUEST_ERROR There was an error adding request.
* \retval SOC_TRNG_RAND_ASYNC_REQUEST_OK Request successfully registered
*
* This function is asynchronous, it will start generation of a random number
* and will return. The caller must provide a callback that will be called when
* the generation is complete. This callback must either use the random number
* immediately or store it, since it will not be possible to retrieve it again
* later form the soc-trng module.
*
* Only one generation can be active at any given point in time. If this
* function gets called when a generation is already in progress, it will
* return SOC_TRNG_RAND_ASYNC_REQUEST_ERROR.
*
* The function will configure the TRNG to generate entropy by sampling the
* FROs for a number clock cycles controlled by the samples argument. The 8 LS
* bits of this argument will be truncated by CC13xxware/CC26xxware and the
* resulting number of clock cycles will be (samples >> 8) * 2^8. Increasing
* the value of this argument increases entropy, but it also increases latency.
* Maximum entropy can be generated by passing SOC_TRNG_REFILL_CYCLES_MAX, but
* this will take approximately 350ms. Consult the chip's technical reference
* manual for advice on what would constitute sufficient entropy for random
* numbers meant to be used for crypto.
*
* While this function is executing, calls to soc_trng_rand_synchronous() will
* return cached random numbers.
*
* This function is not re-entrant and must not be called from an interrupt
* context.
*/
uint8_t soc_trng_rand_asynchronous(uint32_t samples, soc_trng_callback_t cb);
/** @} */
/*---------------------------------------------------------------------------*/
#endif /* SOC_TRNG_H_ */
/*---------------------------------------------------------------------------*/
/**
* @}
* @}
*/