1 /*
2  * Copyright (c) 2001-2019, Arm Limited and Contributors. All rights reserved.
3  *
4  * SPDX-License-Identifier: BSD-3-Clause
5  */
6 
7 #ifndef LLF_RND_TRNG_H
8 #define LLF_RND_TRNG_H
9 
10 
11 #include "dx_rng.h"
12 #include "cc_pal_mem.h"
13 #include "cc_general_defs.h"
14 #include "dx_crys_kernel.h"
15 #include "cc_regs.h"
16 #include "dx_host.h"
17 #include "cc_plat.h"
18 #include "cc_rnd_common.h"
19 #include "llf_rnd.h"
20 
21 #define LLF_RND_NUM_OF_ROSCS    4
22 
23 #ifdef __cplusplus
24 extern "C"
25 {
26 #endif
27 
28 
29 /************************ Defines ******************************/
30 
31 /******************** Public Functions *************************/
32 
33 /****************************************************************************************/
34 /**
35  * @brief The function starts the TRNG with given parameters and ROSCs lengths
36  *
37  *      NOTE: It is assumed, that before calling this function, the previously
38  *            started TRNG processes were compleated and Interrupts cleared.
39  *
40  *      Algorithm:
41  *      1. If is continued mode, the function does:
42  *              checks actual parameters, loaded in TRNG registers,
43  *              vs. user given parameters; if any not matchs - returns Error.
44  *         Else /do restart/:
45  *          sets ROSCs to start: for "SWEE" - all allowed, for "FE" -
46  *          fastest from allowed; gets the user given parameters and sets
47  *          them in the HW, starts the TRNG clocks and sets TRNG parameters
48  *          into HW registers.
49  *      2. Initializes the RND DMA according to ROSCs required to start,
50  *         initializes the TRNG Interrupt. Enables RNG source.
51  *      3. Exits.
52  *
53  * @param[in/out] rndContext_ptr - The pointer to the internal State buffer of DRNG.
54  * @param[in/out] trngParams_ptr - The pointer to structure, containing TRNG parameters.
55  * @isContinued[in] isRestart - The variable indicates is a restart required or not.
56  * @roscsToStart[in] roscsToStart_ptr - The variable, defining which ROSCs to
57  *                      start according to bits set: b'0...b'3. When
58  *                      isRestart=TRUE, then:
59  *                      for "swee" - starts all allowed ROSCs, for
60  *                      "fe" - starts fastest ROSC from allowed.
61  *                      Note: if isRestart = 1, then
62  *
63  *
64  * @return CCError_t - no return value
65  */
66 CCError_t LLF_RND_StartTrngHW(
67                    CCRndState_t  *rndState_ptr,
68                    CCRndParams_t *trngParams_ptr,
69                    CCBool_t           isRestart,
70                    uint32_t         *roscsToStart_ptr);
71 
72 /*******************************************************************************/
73 /**
74  * @brief The LLF_RND_GetTrngSource reads random source of needed size from TRNG.
75  *
76  *        The function is used in Self, Instantiation and Reseeding functions.
77  *
78  * @param[in/out] rndContext_ptr - The pointer to the internal State buffer of DRNG.
79  * @param[in/out] trngParams_ptr - The pointer to structure, containing TRNG parameters.
80  * @isContinued[in] isContinued - The variable indicates is the required process should
81  *                  continue a  previous one or restart TRNG.
82  * @entropySize_ptr[in/out] - The pointer to size of entropy in bits: input - required,
83  *                            output - actual size.
84  * @sourceOut_ptr_ptr[out] - The pointer to to pointer to the entropy source buffer.
85  *                   The buffer contains one empty word for using by CC level
86  *                   and then buffer for output the rng source.
87  * @param[out] - sourceOutSize_ptr - The pointer to the size in bytes of entropy source
88  *                      in - required size, output - actual size.
89  * @param[in/out] - rndWorkBuff_ptr - The pointer to the temp buffer for allocation of
90  *                     estimator buffers.
91  * @param[in] - isFipsSupported - indication if FIPS is supported.
92  *
93  *
94  * @return CCError_t - On success CC_OK is returned, on failure a
95  *                        value MODULE_* as defined in ...
96  */
97 CCError_t LLF_RND_GetTrngSource(
98                  CCRndState_t  *rndState_ptr,      /*in/out*/
99                  CCRndParams_t  *trngParams_ptr,   /*in/out*/
100                  CCBool_t            isContinued,    /*in*/
101                  uint32_t         *entropySize_ptr,  /*in/out*/
102                  uint32_t         **sourceOut_ptr_ptr, /*out*/
103                  uint32_t         *sourceOutSize_ptr,/*in/out*/
104                  uint32_t         *rndWorkBuff_ptr,      /*in*/
105                  bool              isFipsSupported);      /*in*/
106 
107 /*******************************************************************************/
108 /**
109  * @brief The LLF_RND_RunTrngStartupTest runs the startup tests required for TRNG.
110  *
111  * @param[in/out] rndContext_ptr - The pointer to the internal State buffer of DRNG.
112  * @param[out] trngParams_ptr - The pointer to structure, containing TRNG parameters.
113  * @param[in/out] - rndWorkBuff_ptr - The pointer to the temp buffer for allocation of
114  *                     estimator buffers.
115  *
116  * @return CCError_t - On success CC_OK is returned, on failure a
117  *                        value MODULE_* as defined in ...
118  */
119 CCError_t LLF_RND_RunTrngStartupTest(
120                       CCRndState_t *rndState_ptr,   /*in/out*/
121                                       CCRndParams_t *trngParams_ptr,   /*out*/
122                       uint32_t          *rndWorkBuff_ptr);  /*in*/
123 
124 
125 #ifdef __cplusplus
126 }
127 #endif
128 
129 #endif  // LLF_RND_TRNG_H
130