1 /**
2  * @file    spixr.h
3  * @brief   Registers, Bit Masks and Bit Positions for the SPI RAM XIP Data module.
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_MAX32570_SPIXR_H_
28 #define LIBRARIES_PERIPHDRIVERS_INCLUDE_MAX32570_SPIXR_H_
29 
30 /* **** Includes **** */
31 #include "spixr_regs.h"
32 #include "mxc_sys.h"
33 
34 #ifdef __cplusplus
35 extern "C" {
36 #endif
37 
38 /**
39  * @defgroup spixr SPI External RAM (SPIXR)
40  * @ingroup periphlibs
41  * @{
42  */
43 
44 /* **** Definitions **** */
45 /**
46  * @brief       Structure type for configuring a SPIXR port.
47  */
48 
49 /// @brief Data Width, # of data I/O used to rcv data
50 
51 /**
52  * @brief       Data Width, # of data I/O used to rcv data
53  */
54 typedef enum {
55     MXC_SPIXR_SINGLE_SDIO = 0,
56     MXC_SPIXR_DUAL_SDIO,
57     MXC_SPIXR_QUAD_SDIO,
58     MXC_SPIXR_INVALID,
59 } mxc_spixr_width_t;
60 
61 /**
62  * @brief       SPIXF mode.
63  * @note        modes 1 and 2 are not supported
64  */
65 typedef enum {
66     MXC_SPIXR_MODE_0,
67     MXC_SPIXR_MODE_1,
68     MXC_SPIXR_MODE_2,
69     MXC_SPIXR_MODE_3,
70 } mxc_spixr_mode_t;
71 
72 /**
73  * @brief       Configuration parameters of SPIXR
74  */
75 typedef struct {
76     uint32_t
77         numbits; ///< Number of Bits per character. In slave mode 9-bit character length is not supported.
78     mxc_spixr_width_t data_width; ///< SPI Data width
79 
80     uint32_t ssel_act_1; ///< Slave Select Action delay 1
81     uint32_t ssel_act_2; ///< Slave Select Action delay 2
82     uint32_t ssel_inact; ///< Slave Select Inactive delay
83 
84     uint32_t baud_freq; ///< Desired frequency
85 } mxc_spixr_cfg_t;
86 
87 /* **** Function Prototypes **** */
88 
89 /**
90  * @brief       Unloads bytes from the FIFO
91  *
92  * @param       buf   The buffer to read the data into
93  * @param       len     The number of bytes to read
94  *
95  * @return      The number of bytes actually read
96  */
97 int MXC_SPIXR_ReadRXFIFO(uint8_t *buf, int len);
98 
99 /**
100  * @brief       Loads bytes into the FIFO
101  *
102  * @param       buf   The buffer containing data to write
103  * @param       len     The number of bytes to write
104  *
105  * @return      The number of bytes actually written
106  */
107 int MXC_SPIXR_WriteTXFIFO(uint8_t *buf, int len);
108 
109 /**
110  * @brief       Select which SS pin is used in SPIXR
111  *
112  * @param       ssIdx   The index of the SS pin to use
113  */
114 void MXC_SPIXR_SetSS(int ssIdx);
115 
116 /**
117  * @brief       Returns the SS line selected
118  *
119  * @return      The index of the SS pin to use
120  */
121 int MXC_SPIXR_GetSS(void);
122 
123 /**
124  * @brief       Control the deassertion of the SS line
125  *
126  * @param       stayActive  Keep the SS line asserted between
127  *                          sequential transmissions
128  */
129 void MXC_SPIXR_SetSSCtrl(int stayActive);
130 
131 /**
132  * @brief       Get the setting that controls deassertion of the SS line
133  *
134  * @return      1 to keep the SS line asserted between sequential transmissions
135  */
136 int MXC_SPIXR_GetSSCtrl(void);
137 
138 /**
139  * @brief       Enable the SPIXR peripheral
140  *
141  */
142 void MXC_SPIXR_Enable(void);
143 
144 /**
145  * @brief       Disable the SPIXR peripheral
146  * @note        Disabling the peripheral keeps all registers and FIFO data
147  *
148  */
149 void MXC_SPIXR_Disable(void);
150 
151 /**
152  * @brief       Get if SPIXR is enabled
153  *
154  * @return      1 = enabled, 0 = disabled
155  */
156 int MXC_SPIXR_IsEnabled(void);
157 
158 /**
159  * @brief       Enable the TXFIFO
160  *
161  */
162 void MXC_SPIXR_TXFIFOEnable(void);
163 
164 /**
165  * @brief       Disable the TXFIFO
166  *
167  */
168 void MXC_SPIXR_TXFIFODisable(void);
169 
170 /**
171  * @brief       Get if TXFIFO is enabled
172  *
173  * @return      1 = enabled, 0 = disabled
174  */
175 int MXC_SPIXR_TXFIFOIsEnabled(void);
176 
177 /**
178  * @brief       Enable the TXFIFO DMA
179  *
180  */
181 void MXC_SPIXR_DmaTXFIFOEnable(void);
182 
183 /**
184  * @brief       Disable the TXFIFO DMA
185  *
186  */
187 void MXC_SPIXR_DmaTXFIFODisable(void);
188 
189 /**
190  * @brief       Get if TXFIFO DMA is enabled
191  *
192  * @return      1 = enabled, 0 = disabled
193  */
194 int MXC_SPIXR_DmaTXFIFOIsEnabled(void);
195 
196 /**
197  * @brief       Enable the RXFIFO
198  *
199  */
200 void MXC_SPIXR_RXFIFOEnable(void);
201 
202 /**
203  * @brief       Disable the RXFIFO
204  *
205  */
206 void MXC_SPIXR_RXFIFODisable(void);
207 
208 /**
209  * @brief       Get if RXFIFO is enabled
210  *
211  * @return      1 = enabled, 0 = disabled
212  */
213 int MXC_SPIXR_RXFIFOIsEnabled(void);
214 
215 /**
216  * @brief       Enable the RXFIFO DMA
217  *
218  */
219 void MXC_SPIXR_DmaRXFIFOEnable(void);
220 
221 /**
222  * @brief       Disable the RXFIFO DMA
223  *
224  */
225 void MXC_SPIXR_DmaRXFIFODisable(void);
226 
227 /**
228  * @brief       Get if RXFIFO DMA is enabled
229  *
230  * @return      1 = enabled, 0 = disabled
231  */
232 int MXC_SPIXR_DmaRXFIFOIsEnabled(void);
233 
234 /**
235  * @brief       Enable three wire mode
236  *
237  */
238 void MXC_SPIXR_ThreeWireModeEnable(void);
239 
240 /**
241  * @brief       Disable three wire mode
242  *
243  */
244 void MXC_SPIXR_ThreeWireModeDisable(void);
245 
246 /**
247  * @brief       Get if three wire mode is enabled
248  *
249  * @return      1 = enabled, 0 = disabled
250  */
251 int MXC_SPIXR_ThreeWireModeIsEnabled(void);
252 
253 /**
254  * @brief       Get the number of bytes currently in the TX FIFO
255  *
256  * @return      The number of bytes currently in the TX FIFO
257  */
258 int MXC_SPIXR_GetTXFIFOCount(void);
259 
260 /**
261  * @brief       Get the number of bytes currently in the RX FIFO
262  *
263  * @return      The number of bytes currently in the RX FIFO
264  */
265 int MXC_SPIXR_GetRXFIFOCount(void);
266 
267 /**
268  * @brief       Clear TX FIFO
269  *
270  */
271 void MXC_SPIXR_TXFIFOClear(void);
272 
273 /**
274  * @brief       Clear RX FIFO
275  *
276  */
277 void MXC_SPIXR_RXFIFOClear(void);
278 
279 /**
280  * @brief       Set the SPI Width used
281  *
282  * @param       width   The width to be used
283  */
284 int MXC_SPIXR_SetWidth(mxc_spixr_width_t width);
285 
286 /**
287  * @brief       Set the SPI Mode used
288  *
289  * @param       mode   The mode to be used
290  */
291 int MXC_SPIXR_SetSPIMode(mxc_spixr_mode_t mode);
292 
293 /**
294  * @brief       Set the active state of the SS line
295  *
296  * @param       activeLow   Make the slave select line active low
297  */
298 int MXC_SPIXR_SetSSPolarity(int activeLow);
299 
300 /**
301  * @brief       Set the SS Timing Parameters
302  * @note        All timing is in units of system clocks
303  *
304  * @param       ssIActDelay Delay between end of transaction and start of next
305  * @param       postActive  Time after last SCLK  that SS remains active
306  * @param       preActive   Time after SS becomes active until first SCLK
307  *
308  */
309 void MXC_SPIXR_SetSSTiming(unsigned int ssIActDelay, unsigned int postActive,
310                            unsigned int preActive);
311 
312 /**
313  * @brief       Set the SPI Frequency
314  *
315  * @param       hz  The requested SCLK frequency
316  *
317  * @return      The actual speed set in Hz
318  */
319 int MXC_SPIXR_SetFrequency(int hz);
320 
321 /**
322  * @brief       Get the SPI Frequency
323  *
324  * @return      The current speed in Hz
325  */
326 int MXC_SPIXR_GetFrequency(void);
327 
328 /**
329  * @brief       Get the active interrupt flags
330  * @note        See \ref mxc_spixr_regs_t for a detailed list of flags
331  *
332  * @return      The SPIXR interrupt flags
333  */
334 int MXC_SPIXR_GetIntFlags(void);
335 
336 /**
337  * @brief       Enable SPIXR interrupts
338  *
339  * @param       flags   The flags to enable
340  */
341 void MXC_SPIXR_EnableInt(int flags);
342 
343 /**
344  * @brief       Disable SPIXR interrupts
345  *
346  * @param       flags   The flags to disable
347  */
348 void MXC_SPIXR_DisableInt(int flags);
349 
350 /**
351  * @brief       Get the active wake up flags
352  * @note        See \ref mxc_spixr_regs_t for a detailed list of flags
353  *
354  * @return      The SPIXR wake up flags
355  */
356 int MXC_SPIXR_GetWakeUpFlags(void);
357 
358 /**
359  * @brief       Enable Wake up for SPIXR
360  *
361  * @param       flags   The flags to disable
362  */
363 void MXC_SPIXR_EnableWakeUp(int flags);
364 
365 /**
366  * @brief       Enable Wake up for SPIXR
367  *
368  * @param       flags   The flags to disable
369  */
370 void MXC_SPIXR_DisableWakeUp(int flags);
371 
372 /**
373  * @brief       Enable the external memory mode
374  */
375 void MXC_SPIXR_ExMemEnable(void);
376 
377 /**
378  * @brief       Disable the SPI RAM XIP Data module.
379  */
380 void MXC_SPIXR_ExMemDisable(void);
381 
382 /**
383  * @brief       Put 255 characters worth of clocks between address
384  *              and read phase of external memory transactions
385  *
386  * @param       delay255 add the delay
387  */
388 void MXC_SPIXR_ExMemUseDummy(int delay255);
389 
390 /**
391  * @brief       Set the write command used for external memory mode
392  *
393  * @param       command The command to be used
394  */
395 void MXC_SPIXR_ExMemSetWriteCommand(uint8_t command);
396 
397 /**
398  * @brief       Get the write command used for external memory mode
399  *
400  * @return      the command to be used
401  */
402 uint8_t MXC_SPIXR_ExMemGetWriteCommand(void);
403 
404 /**
405  * @brief       Set the read command used for external memory mode
406  *
407  * @param       command The command to be used
408  */
409 void MXC_SPIXR_ExMemSetReadCommand(uint8_t command);
410 
411 /**
412  * @brief       Get the read command used for external memory mode
413  *
414  * @return      the command to be used
415  */
416 uint8_t MXC_SPIXR_ExMemGetReadCommand(void);
417 
418 /**
419  * @brief       SPI active status.
420  *
421  * In Master mode, set when transaction starts, cleared when last bit of last
422  * character is acted upon and Slave Select de-assertion would occur.
423  * @return      0 if inactive, 1 if active
424  */
425 int MXC_SPIXR_Busy(void);
426 
427 /**
428  * @brief       Initialize the SPI RAM XIP Data module.
429  *
430  * @param       cfg   The configuration
431  *
432  * @return      #E_NO_ERROR if the SPIXR is initialized successfully, @ref
433  *              MXC_Error_Codes "error" if unsuccessful.
434  */
435 int MXC_SPIXR_Init(mxc_spixr_cfg_t *cfg);
436 
437 /**
438  * @brief       Shut Down the SPI RAM XIP Data Module
439  *
440  * @return      #E_NO_ERROR if the SPIXR is shutdown successfully,
441  *              @ref MXC_Error_Codes "error" if unsuccessful.
442  */
443 int MXC_SPIXR_Shutdown(void);
444 
445 /**
446  * @brief       Send a SPI formatted instruction to external RAM
447  * @param       cmd         Array of instructions to send
448  * @param       length      number of bytes to send
449  * @param       tx_num_char number of bytes to send
450  */
451 void MXC_SPIXR_SendCommand(uint8_t *cmd, uint32_t length, uint32_t tx_num_char);
452 
453 #ifdef __cplusplus
454 }
455 #endif
456 
457 /**@} end of group spixr*/
458 
459 #endif // LIBRARIES_PERIPHDRIVERS_INCLUDE_MAX32570_SPIXR_H_
460