1 /******************************************************************************
2  *  Copyright (c) 2022-2023 Texas Instruments Incorporated. All rights reserved.
3  *
4  *  Redistribution and use in source and binary forms, with or without
5  *  modification, are permitted provided that the following conditions are met:
6  *
7  *  1) Redistributions of source code must retain the above copyright notice,
8  *     this list of conditions and the following disclaimer.
9  *
10  *  2) Redistributions in binary form must reproduce the above copyright notice,
11  *     this list of conditions and the following disclaimer in the documentation
12  *     and/or other materials provided with the distribution.
13  *
14  *  3) Neither the name of the copyright holder nor the names of its contributors
15  *     may be used to endorse or promote products derived from this software
16  *     without specific prior written permission.
17  *
18  *  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
19  *  AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
20  *  IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
21  *  ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
22  *  LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
23  *  CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
24  *  SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
25  *  INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
26  *  CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
27  *  ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
28  *  POSSIBILITY OF SUCH DAMAGE.
29  ******************************************************************************
30  *  \file       copylist.h
31  *
32  *  \brief      Copy list format used to apply FCFG, CCFG, and standby wakeup
33  *              configurations.
34  *
35  ******************************************************************************/
36 
37 #ifndef __COPYLIST_H__
38 #define __COPYLIST_H__
39 
40 #include <stdint.h>
41 
42 #include "hapi.h"
43 
44 #include "../inc/hw_types.h"
45 
46 //*****************************************************************************
47 //
48 //! \brief Copy list macro to end a copy list
49 //!
50 //! Processing of the copy list with CopyList_apply() will stop upon
51 //! encountering this entry.
52 //!
53 //! Command      |31:28|27:20    |19:2                  |1:0|LW|Description
54 //! -------------|-----|---------|----------------------|---|--|----------------
55 //! EOL          |0000 |0000_0000|0000_0000_0000_0000_00|00 |0 |End-of-list
56 //!
57 //! \sa CopyList_apply()
58 //
59 //*****************************************************************************
60 #define CopyList_EOL 0U
61 
62 //*****************************************************************************
63 //
64 //! \brief Copy list macro to do nothing.
65 //!
66 //! Command      |31:28|27:20    |19:2                  |1:0|LW|Description
67 //! -------------|-----|---------|----------------------|---|--|----------------
68 //! NOP = WAIT(0)|0001 |0000_0000|0000_0000_0000_0000_00|00 |0 |No operation
69 //!
70 //! \sa CopyList_apply()
71 //
72 //*****************************************************************************
73 #define CopyList_NOP CopyList_WAIT(0U)
74 
75 //*****************************************************************************
76 //
77 //! \brief Copy list macro for waiting \c n iterations of a do-nothing loop
78 //!
79 //! Command      |31:28|27:20    |19:2                  |1:0|LW|Description
80 //! -------------|-----|---------|----------------------|---|--|----------------
81 //! WAIT(N)      |0001 |0000_0000|nnnn_nnnn_nnnn_nnnn_nn|00 |0 |Wait N/12 us
82 //!
83 //! \param[in] n Number of iterations to wait. Must be in range [1, 2^18 - 1].
84 //!
85 //! \sa CopyList_apply()
86 //
87 //*****************************************************************************
88 #define CopyList_WAIT(n) (0x10000000U | (((uint32_t)n << 2U) & 0xFFFFCU))
89 
90 //*****************************************************************************
91 //
92 //! \brief Copy list macro for copying a single literal to a specified address
93 //!
94 //! This macro copies a 32-bit literal to a specified \c address. This command
95 //! expects the next word in the copy list to be the literal it is supposed to
96 //! copy.
97 //!
98 //! Command      |31:28|27:20    |19:2                  |1:0|LW|Description
99 //! -------------|-----|---------|----------------------|---|--|----------------
100 //! CPY(A,1)     |aaaa |aaaa_aaaa|aaaa_aaaa_aaaa_aaaa_aa|01 |1 |Copy single literal word to full address A
101 //!
102 //! \param[in] address Address to copy the following literal to. The address
103 //!                    must be word-aligned.
104 //!
105 //! \sa CopyList_apply()
106 //
107 //*****************************************************************************
108 #define CopyList_COPY(address) ((uint32_t)address | 0x1U)
109 
110 //*****************************************************************************
111 //
112 //! \brief Copy list macro for copying multiple literals to a specified address
113 //!
114 //! This macro copies \c n 32-bit literal to a specified \c address. This
115 //! command expects the next \c n words in the copy list to be the literal it is
116 //! supposed to copy.
117 //!
118 //! Command      |31:28|27:20    |19:2                  |1:0|LW|Description
119 //! -------------|-----|---------|----------------------|---|--|----------------
120 //! CPY(A*,N)    |aaaa |nnnn_nnnn|aaaa_aaaa_aaaa_aaaa_aa|00 |N |Copy N literal words to address A*
121 //!
122 //! The devices' address space is arranged such that bits 20:27 are not actually
123 //! needed to specify any valid address.
124 //!
125 //! \param[in] address Address to copy the following literals to. The address
126 //!                    must be word-aligned.
127 //!
128 //! \param[in] n Number of words to copy. Must be in range [1, 255]
129 //!
130 //! \sa CopyList_apply()
131 //
132 //*****************************************************************************
133 #define CopyList_COPY_MULTI(address, n) (((uint32_t)address & 0xF00FFFFCU) | (((uint32_t)n << 20U) & 0xFF00000U))
134 
135 //*****************************************************************************
136 //
137 //! \brief Copy list macro for continuing copy list processing at a new address
138 //!
139 //! This macro continues processing the copy list at \c address.
140 //!
141 //! Command      |31:28|27:20    |19:2                  |1:0|LW|Description
142 //! -------------|-----|---------|----------------------|---|--|----------------
143 //! JMP(A)       |aaaa |aaaa_aaaa|aaaa_aaaa_aaaa_aaaa_aa|10 |0 |Jump to new list at full address A
144 //!
145 //! \param[in] address Address to continue processing the copy list at. The
146 //!                    address must be word-aligned.
147 //!
148 //! \sa CopyList_apply()
149 //
150 //*****************************************************************************
151 #define CopyList_JUMP(address) ((uint32_t)address | 0x2U)
152 
153 //*****************************************************************************
154 //
155 //! \brief Copy list macro to recurse to a new list
156 //!
157 //! Recurse into new list at \c address by invoking CopyList_apply(). Once this
158 //! list ends it will return back here and continue parsing this list.
159 //!
160 //! Command      |31:28|27:20    |19:2                  |1:0|LW|Description
161 //! -------------|-----|---------|----------------------|---|--|----------------
162 //! CALL(A)      |aaaa |aaaa_aaaa|aaaa_aaaa_aaaa_aaaa_aa|11 |0 |Recurse to list at full address A
163 //!
164 //! \param[in] address Address to continue processing the copy list at. The
165 //!                    address must be word-aligned.
166 //!
167 //! \sa CopyList_apply()
168 //
169 //*****************************************************************************
170 #define CopyList_CALL(address) ((uint32_t)address | 0x3U)
171 
172 //*****************************************************************************
173 //
174 //! \brief Process copy list
175 //! Processes a copy list in a flexible CopyList format. Used by trims
176 //! in FCFG, for user-defined initialization in CCFG and may be used by
177 //! peripheral drivers to do HW reinitialization during wakeup from standby.
178 //! The copy list is processed as a sequence of 32b command words, followed by
179 //! zero or more literal words (LW):
180 //!
181 //! Command      |31:28|27:20    |19:2                  |1:0|LW|Description
182 //! -------------|-----|---------|----------------------|---|--|----------------
183 //! EOL          |0000 |0000_0000|0000_0000_0000_0000_00|00 |0 |End-of-list
184 //! WAIT(N)      |0001 |0000_0000|nnnn_nnnn_nnnn_nnnn_nn|00 |0 |Wait N/12 us
185 //! NOP = WAIT(0)|0001 |0000_0000|0000_0000_0000_0000_00|00 |0 |No operation
186 //! CPY(A*,N)    |aaaa |nnnn_nnnn|aaaa_aaaa_aaaa_aaaa_aa|00 |N |Copy N literal words to address A*
187 //! CPY(A,1)     |aaaa |aaaa_aaaa|aaaa_aaaa_aaaa_aaaa_aa|01 |1 |Copy single literal word to full address A
188 //! JMP(A)       |aaaa |aaaa_aaaa|aaaa_aaaa_aaaa_aaaa_aa|10 |0 |Jump to new list at full address A
189 //! CALL(A)      |aaaa |aaaa_aaaa|aaaa_aaaa_aaaa_aaaa_aa|11 |0 |Recurse to list at full address A
190 //!
191 //! A* is a reduced address space that covers all SRAM and peripheral space.
192 //! Bits 27:20 of this address will be assumed to be all zero. Full addresses
193 //! must have 32b alignment
194 //!
195 //! \param[in] list Pointer to the copy list
196 //
197 //*****************************************************************************
CopyList_apply(const uint32_t * list)198 __STATIC_INLINE void CopyList_apply(const uint32_t *list)
199 {
200     HapiApplyCopyList(list);
201 }
202 
203 #endif //__COPYLIST_H__
204