1 /**
2  * @file
3  * @brief Pulse Train data types, definitions and function prototypes.
4  */
5 
6 /******************************************************************************
7  *
8  * Copyright (C) 2022-2023 Maxim Integrated Products, Inc. (now owned by
9  * Analog Devices, Inc.),
10  * Copyright (C) 2023-2024 Analog Devices, Inc.
11  *
12  * Licensed under the Apache License, Version 2.0 (the "License");
13  * you may not use this file except in compliance with the License.
14  * You may obtain a copy of the License at
15  *
16  *     http://www.apache.org/licenses/LICENSE-2.0
17  *
18  * Unless required by applicable law or agreed to in writing, software
19  * distributed under the License is distributed on an "AS IS" BASIS,
20  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
21  * See the License for the specific language governing permissions and
22  * limitations under the License.
23  *
24  ******************************************************************************/
25 
26 /* Define to prevent redundant inclusion */
27 #ifndef LIBRARIES_PERIPHDRIVERS_INCLUDE_MAX32662_PT_H_
28 #define LIBRARIES_PERIPHDRIVERS_INCLUDE_MAX32662_PT_H_
29 
30 /* **** Includes **** */
31 
32 #include <stdio.h>
33 #include "pt.h"
34 #include "gcr_regs.h"
35 #include "pt_regs.h"
36 #include "ptg_regs.h"
37 #include "mxc_device.h"
38 #include "mxc_errors.h"
39 #include "mxc_assert.h"
40 #include "mxc_sys.h"
41 #include "mcr_regs.h"
42 
43 #ifdef __cplusplus
44 extern "C" {
45 #endif
46 
47 /**
48  * @defgroup pulsetrain Pulse Train Engine
49  * @ingroup periphlibs
50  * @brief This is the high level API for the pulse train engine.
51  * @{
52  */
53 
54 /**
55  * Structure type for pulse train mode configuration.
56  * @note       Do not use for square wave
57  */
58 typedef struct {
59     unsigned channel; /**< PT Channel to use */
60     uint32_t bps; /**< pulse train bit rate */
61     uint32_t pattern; /**< Output pattern to shift out, starts at LSB */
62     uint8_t
63         ptLength; /**< Number of bits in pulse train, 0 = 32bits, 1 = non valid , 2 = 2 bits, ... */
64     uint16_t loop; /**< Number of times to repeat the train, 0 = continuous */
65     uint16_t
66         loopDelay; /**< Delay between loops specified in bits Example: loopDelay = 4,  delays time  = time it takes to shift out 4 bits */
67 } mxc_pt_cfg_t;
68 /**
69  * Enumeration type for the system clock scale types
70  */
71 typedef enum {
72     MXC_PT_CLK_DIV1,
73     MXC_PT_CLK_DIV2,
74     MXC_PT_CLK_DIV4,
75     MXC_PT_CLK_DIV8,
76     MXC_PT_CLK_DIV16,
77     MXC_PT_CLK_DIV32,
78     MXC_PT_CLK_DIV64,
79     MXC_PT_CLK_DIV128,
80 } mxc_clk_scale_t;
81 
82 /**
83  * @brief      This function initializes the pulse trains to a known stopped
84  *             state and sets the global PT clock scale.
85  * @param      clk_scale  Scale the system clock for the global PT clock.
86  */
87 void MXC_PT_Init(mxc_clk_scale_t clk_scale);
88 
89 /**
90  * @brief      Shutdown the pulse train channel/channels.
91  * @details    Shutdown pulse train and if all pluse trains are shut down then turn off pulse train clock.
92  * @note       Shutdown pulse train channel/channels and delete config.
93  *
94  * @param      pts    Pulse train channel to operate on.
95  */
96 void MXC_PT_Shutdown(uint32_t pts);
97 
98 /**
99  * @brief      Configures the pulse train in the specified mode.
100  * @details    The parameters in the config structure must be set before calling
101  *             this function. This function should be used for configuring pulse
102  *             train mode only.
103  * @note       The pulse train cannot be running when this function is called.
104  *
105  * @param      cfg     Pointer to pulse train configuration.
106  *
107  * @return     #E_NO_ERROR if everything is successful, @ref MXC_Error_Codes
108  *             "error" if unsuccessful.
109  */
110 int MXC_PT_Config(mxc_pt_cfg_t *cfg);
111 
112 /**
113  * @brief      Configures the pulse train in the square wave mode.
114  * @details    This function should be used for configuring square wave mode only.
115  * @note       The pulse train cannot be running when this function is called
116  *
117  * @param      channel Pulse train channel to operate on
118  * @param      freq    square wave output frequency in Hz
119  *
120  * @returns #E_NO_ERROR if everything is successful, \ref MXC_Error_Codes "error" if unsuccessful.
121  */
122 int MXC_PT_SqrWaveConfig(unsigned channel, uint32_t freq);
123 
124 /**
125  * @brief      Starts the pulse trains specified.
126  *
127  * @param      pts   Pulse train pts to operate on.
128  */
129 void MXC_PT_Start(unsigned pts);
130 
131 /**
132  * @brief      Stops pulse trains.
133  *
134  * @param      pts Pulse train pts to stop.
135  */
136 void MXC_PT_Stop(unsigned pts);
137 
138 /**
139  * @brief      Determines if the pulse trains selected are running
140  *
141  * @param      pts   Set the bits of pulse trains to check Bit0-\>pt0,
142  *                   Bit1-\>pt1... etc.
143  *
144  * @return     0            All pulse trains are off.
145  * @return     \>0          At least one pulse train is on.
146  */
147 uint32_t MXC_PT_IsActive(uint32_t pts);
148 
149 /**
150  * @brief      Sets the pattern of the pulse train
151  *
152  * @param      pts     Pulse train pts to operate on.
153  * @param      pattern Output pattern.
154  *
155  */
156 void MXC_PT_SetPattern(unsigned pts, uint32_t pattern);
157 
158 /**
159  * @brief      Enable Stop interrupts for the pulse trains selected.
160  *
161  * @note       This is just an explicit version of MXC_PT_EnableInt()
162  *
163  * @param      pts   Bit mask of which pulse trains to enable. Set the bit
164  *                   position of each pulse train to enable it. Bit0-\>pt0,
165  *                   Bit1-\>pt1... etc, 1 will enable the interrupt, 0 to leave
166  *                   a PT channel in its current state.
167  */
168 void MXC_PT_EnableStopInt(uint32_t pts);
169 
170 /**
171  * @brief      Disable Stop interrupts for the pulse trains selected.
172  *
173  * @note       This is an explicit version of MXC_PT_DisableInt()
174  *
175  * @param      pts   Bit mask of what pulse trains to disable. Set the bit
176  *                   position of each pulse train to disable it. Bit0-\>pt0,
177  *                   Bit1-\>pt1... etc, 1 will disable the interrupt, 0 to leave
178  *                   a PT channel in its current state.
179  */
180 void MXC_PT_DisableStopInt(uint32_t pts);
181 
182 /**
183  * @brief      Gets the pulse trains's Stop interrupt flags.
184  *
185  * @note       This is an explicit version of MXC_PT_GetStopFlags()
186  *
187  * @return     The Pulse Train Interrupt Flags, \ref MXC_PT_STOP_INTFL_Register Register
188  *             for details.
189  */
190 uint32_t MXC_PT_GetStopFlags(void);
191 
192 /**
193  * @brief      Clears the pulse train's Stop interrupt flag.
194  *
195  * @note       This is an explicit version of MXC_PT_ClearStopFlags()
196  *
197  * @param      flags  bits to clear, see \ref MXC_PT_STOP_INTFL_Register Register for details.
198  */
199 void MXC_PT_ClearStopFlags(uint32_t flags);
200 
201 #if defined(__GNUC__)
202 /**
203  * @brief      Enable Stop interrupts for the pulse trains selected.
204  *
205  * @note       This function is deprecated. Use MXC_PT_EnableStopInt instead to
206  *             differentiate between the STOP and READY interrupts.
207  *
208  * @param      pts   Bit mask of which pulse trains to enable. Set the bit
209  *                   position of each pulse train to enable it. Bit0-\>pt0,
210  *                   Bit1-\>pt1... etc, 1 will enable the interrupt, 0 to leave
211  *                   a PT channel in its current state.
212  */
213 inline
214     __attribute__((deprecated("Use MXC_PT_EnableStopInt instead.  See pt.h for more details."))) void
MXC_PT_EnableInt(uint32_t pts)215     MXC_PT_EnableInt(uint32_t pts)
216 {
217     MXC_PT_EnableStopInt(pts);
218 }
219 
220 /**
221  * @brief      Disable Stop interrupts for the pulse trains selected.
222  *
223  * @note       This function is deprecated. Use MXC_PT_DisableStopInt instead to
224  *             differentiate between the STOP and READY interrupts.
225  *
226  * @param      pts   Bit mask of what pulse trains to disable. Set the bit
227  *                   position of each pulse train to disable it. Bit0-\>pt0,
228  *                   Bit1-\>pt1... etc, 1 will disable the interrupt, 0 to leave
229  *                   a PT channel in its current state.
230  */
231 inline __attribute__((
232     deprecated("Use MXC_PT_DisableStopInt instead.  See pt.h for more details."))) void
MXC_PT_DisableInt(uint32_t pts)233 MXC_PT_DisableInt(uint32_t pts)
234 {
235     MXC_PT_DisableStopInt(pts);
236 }
237 
238 /**
239  * @brief      Gets the pulse trains's Stop interrupt flags.
240  *
241  * @note       This function is deprecated. Use MXC_PT_GetStopFlags instead to
242  *             differentiate between the STOP and READY interrupts.
243  *
244  * @return     The Pulse Train Interrupt Flags, \ref MXC_PT_STOP_INTFL_Register Register
245  *             for details.
246  */
247 inline __attribute__((deprecated("Use MXC_PT_GetStopFlags instead.  See pt.h for more details.")))
248 uint32_t
MXC_PT_GetFlags(void)249 MXC_PT_GetFlags(void)
250 {
251     return MXC_PT_GetStopFlags();
252 }
253 
254 /**
255  * @brief      Clears the pulse train's Stop interrupt flag.
256  *
257  * @note       This function is deprecated. Use MXC_PT_ClearStopFlags instead to
258  *             differentiate between the STOP and READY interrupts.
259  *
260  * @param      flags  bits to clear, see \ref MXC_PT_STOP_INTFL_Register Register for details.
261  */
262 inline __attribute__((
263     deprecated("Use MXC_PT_ClearStopFlags instead.  See pt.h for more details."))) void
MXC_PT_ClearFlags(uint32_t flags)264 MXC_PT_ClearFlags(uint32_t flags)
265 {
266     MXC_PT_ClearStopFlags(flags);
267 }
268 #endif
269 
270 /**
271  * @brief      Setup and enables a pulse train to restart after another pulse
272  *             train has exited its loop. Each pulse train can have up to two
273  *             restart triggers.
274  *
275  * @param      start         Pulse train channel to start.
276  * @param      stop          Pulse train channel to stop.
277  * @param      restartIndex  selects which restart trigger to set (0 or 1).
278  */
279 void MXC_PT_EnableRestart(unsigned start, unsigned stop, uint8_t restartIndex);
280 
281 /**
282  * @brief      Disable the restart for the specified pulse train
283  *
284  * @param      channel       Pulse train channel
285  * @param      restartIndex  selects which restart trigger to disable (0 or 1)
286  */
287 void MXC_PT_DisableRestart(unsigned channel, uint8_t restartIndex);
288 
289 /**
290  * @brief      Resynchronize individual pulse trains together. Resync will stop
291  *             those resync_pts; others will be still running
292  *
293  * @param      pts   Pulse train modules that need to be re-synced by bit
294  *                        number. Bit0-\>pt0, Bit1-\>pt1... etc.
295  */
296 void MXC_PT_Resync(uint32_t pts);
297 
298 /**
299  * @brief      Enable Ready interrupts for the pulse trains selected.
300  *
301  * @param      pts   Bit mask of which pulse trains to enable. Set the bit
302  *                   position of each pulse train to enable it. Bit0-\>pt0,
303  *                   Bit1-\>pt1... etc, 1 will enable the interrupt, 0 to leave
304  *                   a PT channel in its current state.
305  */
306 void MXC_PT_EnableReadyInt(uint32_t pts);
307 
308 /**
309  * @brief      Disable Ready interrupts for the pulse trains selected.
310  *
311  * @param      pts   Bit mask of what pulse trains to disable. Set the bit
312  *                   position of each pulse train to disable it. Bit0-\>pt0,
313  *                   Bit1-\>pt1... etc, 1 will disable the interrupt, 0 to leave
314  *                   a PT channel in its current state.
315  */
316 void MXC_PT_DisableReadyInt(uint32_t pts);
317 
318 /**
319  * @brief      Gets the pulse trains's Ready interrupt flags.
320  *
321  * @return     The Pulse Train Interrupt Flags, \ref MXC_PT_READY_INTFL_Register Register
322  *             for details.
323  */
324 uint32_t MXC_PT_GetReadyFlags(void);
325 
326 /**
327  * @brief      Clears the pulse train's Ready interrupt flag.
328  *
329  * @param      flags  bits to clear, see \ref MXC_PT_READY_INTFL_Register Register for details.
330  */
331 void MXC_PT_ClearReadyFlags(uint32_t flags);
332 
333 /**@} end of group pulsetrains*/
334 
335 #ifdef __cplusplus
336 }
337 #endif
338 
339 #endif // LIBRARIES_PERIPHDRIVERS_INCLUDE_MAX32662_PT_H_
340