1 /*
2  * Copyright (c) 2016 - 2025, Nordic Semiconductor ASA
3  * All rights reserved.
4  *
5  * SPDX-License-Identifier: BSD-3-Clause
6  *
7  * Redistribution and use in source and binary forms, with or without
8  * modification, are permitted provided that the following conditions are met:
9  *
10  * 1. Redistributions of source code must retain the above copyright notice, this
11  *    list of conditions and the following disclaimer.
12  *
13  * 2. Redistributions in binary form must reproduce the above copyright
14  *    notice, this list of conditions and the following disclaimer in the
15  *    documentation and/or other materials provided with the distribution.
16  *
17  * 3. Neither the name of the copyright holder nor the names of its
18  *    contributors may be used to endorse or promote products derived from this
19  *    software without specific prior written permission.
20  *
21  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
22  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
23  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
24  * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
25  * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
26  * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
27  * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
28  * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
29  * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
30  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
31  * POSSIBILITY OF SUCH DAMAGE.
32  */
33 #ifndef NRFX_RNG_H__
34 #define NRFX_RNG_H__
35 
36 #include <nrfx.h>
37 #include <hal/nrf_rng.h>
38 
39 #ifdef __cplusplus
40 extern "C" {
41 #endif
42 
43 /**
44  * @defgroup nrfx_rng RNG driver
45  * @{
46  * @ingroup nrf_rng
47  * @brief   Random Number Generator (RNG) peripheral driver.
48  */
49 
50 /** @brief Struct for RNG configuration. */
51 typedef struct
52 {
53     bool     error_correction : 1;  /**< Error correction flag. */
54     uint8_t  interrupt_priority;    /**< Interrupt priority. */
55 } nrfx_rng_config_t;
56 
57 /**
58  * @brief RNG default configuration.
59  *        Basic usage:
60  *        @code
61  *            nrfx_rng_config_t config = NRFX_RNG_DEFAULT_CONFIG;
62  *            if (nrfx_rng_init(&config, handler)
63  *            { ...
64  *        @endcode
65  *
66  * This configuration sets up randon number generator with the following options:
67  * - error correction enabled
68  */
69 #define NRFX_RNG_DEFAULT_CONFIG                                  \
70 {                                                                \
71     .error_correction   = true,                                  \
72     .interrupt_priority = NRFX_RNG_DEFAULT_CONFIG_IRQ_PRIORITY,  \
73 }
74 
75 /** @brief RNG driver event handler type. */
76 typedef void (* nrfx_rng_evt_handler_t)(uint8_t rng_data);
77 
78 /**
79  * @brief Function for initializing the nrfx_rng module.
80  *
81  * @param[in] p_config Pointer to the structure with the initial configuration.
82  * @param[in] handler  Event handler provided by the user. Must not be NULL.
83  *
84  * @retval NRFX_SUCCESS       Driver was successfully initialized.
85  * @retval NRFX_ERROR_ALREADY Driver was already initialized.
86  */
87 nrfx_err_t nrfx_rng_init(nrfx_rng_config_t const * p_config, nrfx_rng_evt_handler_t handler);
88 
89 /**
90  * @brief Function for starting the generation of random values.
91  *
92  * New data should be handled by handler passed to the @ref nrfx_rng_init() function.
93  */
94 void nrfx_rng_start(void);
95 
96 /**
97  * @brief Function for stopping the generation of random values.
98  *
99  * Function disables interrupts in peripheral and stops the generation of new random values.
100  */
101 void nrfx_rng_stop(void);
102 
103 /** @brief Function for uninitializing the nrfx_rng module. */
104 void nrfx_rng_uninit(void);
105 
106 /**
107  * @brief Function for checking if the RNG driver is initialized.
108  *
109  * @retval true  Driver is already initialized.
110  * @retval false Driver is not initialized.
111  */
112 bool nrfx_rng_init_check(void);
113 
114 /** @} */
115 
116 
117 void nrfx_rng_irq_handler(void);
118 
119 
120 #ifdef __cplusplus
121 }
122 #endif
123 
124 #endif // NRFX_RNG_H__
125