1 //*****************************************************************************
2 //
3 //! @file am_hal_entropy.h
4 //!
5 //! @brief Functions for Generating True Random Numbers.
6 //!
7 //! @addtogroup entropy3p Entropy - Random Number Generation Functions
8 //! @ingroup apollo3p_hal
9 //! @{
10 //
11 //*****************************************************************************
12 
13 //*****************************************************************************
14 //
15 // Copyright (c) 2023, Ambiq Micro, Inc.
16 // All rights reserved.
17 //
18 // Redistribution and use in source and binary forms, with or without
19 // modification, are permitted provided that the following conditions are met:
20 //
21 // 1. Redistributions of source code must retain the above copyright notice,
22 // this list of conditions and the following disclaimer.
23 //
24 // 2. Redistributions in binary form must reproduce the above copyright
25 // notice, this list of conditions and the following disclaimer in the
26 // documentation and/or other materials provided with the distribution.
27 //
28 // 3. Neither the name of the copyright holder nor the names of its
29 // contributors may be used to endorse or promote products derived from this
30 // software without specific prior written permission.
31 //
32 // THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
33 // AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
34 // IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
35 // ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
36 // LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
37 // CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
38 // SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
39 // INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
40 // CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
41 // ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
42 // POSSIBILITY OF SUCH DAMAGE.
43 //
44 // This is part of revision release_sdk_3_1_1-10cda4b5e0 of the AmbiqSuite Development Package.
45 //
46 //*****************************************************************************
47 #ifndef AM_HAL_ENTROPY_H
48 #define AM_HAL_ENTROPY_H
49 
50 #include "stdint.h"
51 #include "stdbool.h"
52 
53 #ifdef __cplusplus
54 extern "C"
55 {
56 #endif
57 
58 //******************************************************************************
59 //
60 //! ENTROPY configuration
61 //
62 //! Use these macros to set the timer number and timer segment to be used for the
63 //! ENTROPY.
64 //
65 //******************************************************************************
66 #define AM_HAL_ENTROPY_CTIMER                  0
67 #define AM_HAL_ENTROPY_CTIMER_SEGMENT          A
68 
69 //******************************************************************************
70 //
71 //! Helper macros for ENTROPY.
72 //
73 //******************************************************************************
74 #define AM_HAL_ENTROPY_CTIMER_SEG2(X) AM_HAL_CTIMER_TIMER ## X
75 #define AM_HAL_ENTROPY_CTIMER_SEG1(X) AM_HAL_ENTROPY_CTIMER_SEG2(X)
76 #define AM_HAL_ENTROPY_CTIMER_TIMERX AM_HAL_ENTROPY_CTIMER_SEG1(AM_HAL_ENTROPY_CTIMER_SEGMENT)
77 
78 #define AM_HAL_ENTROPY_CTIMER_INT2(SEG, NUM) AM_HAL_CTIMER_INT_TIMER ## SEG ## NUM
79 #define AM_HAL_ENTROPY_CTIMER_INT1(SEG, NUM) AM_HAL_ENTROPY_CTIMER_INT2(SEG, NUM)
80 #define AM_HAL_ENTROPY_CTIMER_INT \
81     AM_HAL_ENTROPY_CTIMER_INT1(AM_HAL_ENTROPY_CTIMER_SEGMENT, AM_HAL_ENTROPY_CTIMER)
82 
83 //******************************************************************************
84 //
85 //! Types.
86 //
87 //******************************************************************************
88 typedef void (*am_hal_entropy_callback_t)(void *context);
89 
90 //******************************************************************************
91 //
92 //! External Globals.
93 //
94 //******************************************************************************
95 extern uint32_t am_hal_entropy_timing_error_count;
96 
97 //******************************************************************************
98 //
99 //! Prototypes.
100 //
101 //******************************************************************************
102 //*****************************************************************************
103 //! @brief Initialize the ENTROPY
104 //!
105 //*****************************************************************************
106 extern void am_hal_entropy_init(void);
107 
108 //*****************************************************************************
109 //
110 //! @brief Start the entropy timers
111 //
112 //*****************************************************************************
113 extern void am_hal_entropy_enable(void);
114 
115 //*****************************************************************************
116 //
117 //! @brief Stop the entropy timers
118 //
119 //*****************************************************************************
120 extern void am_hal_entropy_disable(void);
121 
122 //******************************************************************************
123 //
124 //! @brief Place the next N values from the entropy collector into the output
125 //!        location.
126 //!
127 //! @param pui8Output  - where to put the data
128 //! @param ui32Length  - how much data you want
129 //! @param pfnCallback - function to call when the data is ready
130 //! @param pvContext   - will be passed to the callback. can be used for anything
131 //! @return uint32_t   - status
132 //
133 //*****************************************************************************
134 extern uint32_t am_hal_entropy_get_values(uint8_t *pui8Output, uint32_t ui32Length,
135                                           am_hal_entropy_callback_t pfnCallback,
136                                           void *pvContext);
137 
138 
139 #ifdef __cplusplus
140 }
141 #endif
142 
143 #endif // AM_HAL_ENTROPY_H
144 
145 //*****************************************************************************
146 //
147 // End Doxygen group.
148 //! @}
149 //
150 //*****************************************************************************
151