1 /******************************************************************************
2  *  Filename:       lrfd.h
3  *
4  *  Description:    Defines and prototypes for LRFD.
5  *
6  *  Copyright (c) 2023 Texas Instruments Incorporated
7  *
8  *  Redistribution and use in source and binary forms, with or without
9  *  modification, are permitted provided that the following conditions are met:
10  *
11  *  1) Redistributions of source code must retain the above copyright notice,
12  *     this list of conditions and the following disclaimer.
13  *
14  *  2) Redistributions in binary form must reproduce the above copyright notice,
15  *     this list of conditions and the following disclaimer in the documentation
16  *     and/or other materials provided with the distribution.
17  *
18  *  3) Neither the name of the copyright holder nor the names of its
19  *     contributors may be used to endorse or promote products derived from this
20  *     software without specific prior written permission.
21  *
22  *  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
23  *  AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
24  *  IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
25  *  ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
26  *  LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
27  *  CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
28  *  SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
29  *  INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
30  *  CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
31  *  ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
32  *  POSSIBILITY OF SUCH DAMAGE.
33  *
34  ******************************************************************************/
35 
36 #ifndef __LRFD_H__
37 #define __LRFD_H__
38 
39 //*****************************************************************************
40 //
41 //! \addtogroup peripheral_group
42 //! @{
43 //! \addtogroup lrfd_api
44 //! @{
45 //
46 //*****************************************************************************
47 
48 //*****************************************************************************
49 //
50 // If building with a C++ compiler, make all of the definitions in this header
51 // have a C binding.
52 //
53 //*****************************************************************************
54 #ifdef __cplusplus
55 extern "C" {
56 #endif
57 
58 #include <stdint.h>
59 #include "../inc/hw_lrfddbell.h"
60 
61 // Number of LRFD clock dependency sets
62 #define LRFD_NUM_CLK_DEP   2
63 //! LRFD Clock dependency set to be used by the Power driver
64 #define LRFD_CLK_DEP_POWER 0
65 //! LRFD Clock dependency set to be used by the RCL
66 #define LRFD_CLK_DEP_RCL   1
67 
68 //*****************************************************************************
69 //
70 //! \brief Set clock dependency on a set of modules in LRFD.
71 //!
72 //! \warning This API uses internal state, and is not thread safe.
73 //!
74 //! This API supports multiple clock dependency sets. For any given LRFD module,
75 //! it will be clocked if any of the dependency sets has a dependency for that
76 //! LRFD module.
77 //! If any dependency set has a dependency on at least one LRFD module, the LRFD
78 //! module itself will be clocked, otherwise it will not be clocked.
79 //!
80 //! \param mask bitmask defining the set of LRFD modules to set clock dependency on.
81 //! - \ref LRFDDBELL_O_CLKCTL
82 //! \param dependencySetId ID for the clock dependency set to use.
83 //! - \ref LRFD_CLK_DEP_POWER
84 //! - \ref LRFD_CLK_DEP_RCL
85 //!
86 //! \sa LRFDReleaseClockDependency()
87 //!
88 //! \return None
89 //
90 //*****************************************************************************
91 extern void LRFDSetClockDependency(uint16_t mask, uint8_t dependencySetId);
92 
93 //*****************************************************************************
94 //
95 //! \brief Release clock dependency on a set of modules in LRFD.
96 //!
97 //! \warning This API uses internal state, and is not thread safe.
98 //!
99 //! This API supports multiple clock dependency sets.
100 //! See description of \ref LRFDSetClockDependency()
101 //!
102 //! \param mask bitmask defining the set of LRFD modules to release clock dependency from.
103 //! - \ref LRFDDBELL_O_CLKCTL
104 //! \param dependencySetId ID for the clock dependency set to use.
105 //! - \ref LRFD_CLK_DEP_POWER
106 //! - \ref LRFD_CLK_DEP_RCL
107 //!
108 //! \sa LRFDSetClockDependency()
109 //!
110 //! \return None
111 //
112 //*****************************************************************************
113 extern void LRFDReleaseClockDependency(uint16_t mask, uint8_t dependencySetId);
114 
115 //*****************************************************************************
116 //
117 //! \brief Apply the currently set clock dependencies.
118 //!
119 //! \warning This API uses internal state, and is not thread safe.
120 //!
121 //! \note The dependencies automatically being applied when setting and
122 //! releasing dependencies using \ref LRFDSetClockDependency() and
123 //! \ref LRFDReleaseClockDependency(). This API is mainly intended for when
124 //! the enabled clocks gets out of sync with the current dependencies.
125 //! For example, after the device wakes up from standby.
126 //!
127 //! This will update the LRFD clock control based on the currently set clock
128 //! dependencies.
129 //! If there is a clock dependency on any module in LRFD, the LRFD module itself
130 //! will be clocked, otherwise it will not be clocked.
131 //!
132 //! \return None
133 //
134 //*****************************************************************************
135 extern void LRFDApplyClockDependencies(void);
136 
137 //*****************************************************************************
138 //
139 // Mark the end of the C bindings section for C++ compilers.
140 //
141 //*****************************************************************************
142 #ifdef __cplusplus
143 }
144 #endif
145 
146 //*****************************************************************************
147 //
148 //! Close the Doxygen group.
149 //! @}
150 //! @}
151 //
152 //*****************************************************************************
153 
154 #endif // __LRFD_H__