NetBurner 3.1
qspiShared.h
1 /*NB_REVISION*/
2 
3 /*NB_COPYRIGHT*/
4 
5 #ifndef _QSPI_SHARED_H_
6 #define _QSPI_SHARED_H_
7 
8 /*
9  *****************************************************************************
10  *
11  * Queued Serial Peripheral Interface (QSPI)
12  *
13  * Interface consists of data output (QSPI_DOUT), data input (QSPI_DIN),
14  * serial clock (QSPI_CLK) & optionally peripheral chip selects
15  * (QSPI_CS[3:0]).
16  *
17  * SPI parameters are used to match the master (processor) with the slave
18  * device. Chip select can be used to multiplex devices.
19  *
20  * The specific hardware initialization for MFCXXXX and MODXXXX are
21  * microprocessor and module specific and need to be correctly
22  * implemented in the module specific library for each SPI device, for
23  * example Nburn\MOD5270\system\wifi70_bsp.cpp.
24  *
25  * More than one SPI device requires careful coordination of hardware use
26  * and synchronization of use.
27  *
28  *****************************************************************************
29  */
30 
31 /*
32  *****************************************************************************
33  *
34  * Definitions
35  *
36  *****************************************************************************
37  */
38 /* Chip selects
39  * Can connect to QSPI module as supported by the processor.
40  */
41 #define QSPI_CHIP_SELECT_0 (0x1)
42 #define QSPI_CHIP_SELECT_1 (0x2)
43 #define QSPI_CHIP_SELECT_2 (0x4)
44 #define QSPI_CHIP_SELECT_3 (0x8)
45 
46 /* Sets of settings available */
47 #define QSPI_SETTINGS_MAXIMUM (4)
48 
49 /* Block size in bytes */
50 #define QSPI_BLOCK_SIZE_IN_BYTES (16)
51 
52 /*
53  *****************************************************************************
54  *
55  * Enumerations
56  *
57  *****************************************************************************
58  */
59 /*
60  * Transfer size in bits, must match settings for qmr.bits
61  */
62 typedef enum _SpiTransferSize
63 {
64  TransferSize_16_bits = 0x0,
65  TransferSize_8_bits = 0x8
66 
67 } SpiTransferSize;
68 
69 /*
70  *****************************************************************************
71  *
72  * Runtime Library Routines
73  *
74  *****************************************************************************
75  */
76 
77 /*
78  *****************************************************************************
79  *
80  * Initialize shared QSPI driver.
81  *
82  * Parameters:
83  * isDriveStrengthHigh - Output drive strength TRUE high, FALSE low
84  * isDoutHighImpedance - DOUT high impedance between transactions
85  * TRUE high impedance, FALSE driven
86  * isClockInactiveHigh - Clock inactive state
87  * TRUE high, FALSE low
88  * isDataChangeOnLeading - Clock phase
89  * TRUE Data changed on leading edge,
90  * captured on the following edge.
91  * FALSE Data captured on leading edge,
92  * changed on the following edge.
93  * isChipSelectActiveLow - Chips select phase
94  * TRUE Active low, inactive high
95  * TRUE Active high, inactive low
96  * moduleChipSelects - Chip selects to integrate with QSPI module.
97  *
98  * Return:
99  * None
100  *
101  * Notes:
102  * Must be called at least once before any use of the SPI bus.
103  *
104  *****************************************************************************
105  */
106 extern void QspiInitialize(BOOL isDriveStrengthHigh,
107  BOOL isHighImpedance,
108  BOOL isClockInactiveHigh,
109  BOOL isDataChangeOnLeading,
110  BOOL isChipSelectActiveLow,
111  uint8_t moduleChipSelects);
112 
113 /*
114  *****************************************************************************
115  *
116  * Allocate SPI bus
117  *
118  * Parameters:
119  * spiSetting - Settings handle
120  * timeout - Timeout in ticks
121  *
122  * Return:
123  * OS_NO_ERR OK, else probably timed out.
124  *
125  * Notes:
126  * Must release when idle to support sharing. Will suspend task until
127  * granted.
128  *
129  *****************************************************************************
130  */
131 extern uint8_t QspiAllocate(int spiSetting, uint16_t timeout);
132 
133 /*
134  *****************************************************************************
135  *
136  * Releases SPI bus
137  *
138  * Parameters:
139  * None
140  *
141  * Return:
142  * None
143  *
144  * Notes:
145  * Will support granting it to any waiting tasks.
146  *
147  *****************************************************************************
148  */
149 extern void QspiRelease(void);
150 
151 /*
152  *****************************************************************************
153  *
154  * Creates bus parameters profile used for transfers.
155  *
156  * Parameters:
157  * baudRateInMhz - Baud rate in Mhz
158  * qspiTransferSize - Bits transfered for each entry in queue
159  * Currently 8 and 16 bits
160  * delayFromCstoClockValid - Delay from assertion of the chip selects to
161  * valid clock transition
162  * delayBetweenTransfers - Delay after the serial transfer
163  * chipSelects - Chips select mask
164  * idleValue - Value while driving idle bus
165  *
166  * Return:
167  * >=0 handle assigned to these settings.
168  * <0 Problems with settings.
169  *
170  * Notes:
171  * Baud rate has minimum and maximum rates depending on the module.
172  *
173  *****************************************************************************
174  */
175 extern int QspiCreateSetting(int baudRateInMhz,
176  SpiTransferSize qspiTransferSize,
177  uint16_t delayFromCstoClockValid,
178  uint16_t delayBetweenTransfers,
179  uint8_t chipSelects,
180  uint16_t idleValue);
181 
182 /*
183  *****************************************************************************
184  *
185  * Sets bus parameters used for transfers.
186  *
187  * Parameters:
188  * spiSetting - Settings handle
189  * baudRateInMhz - Baud rate in Mhz
190  *
191  * Return:
192  * None
193  *
194  * Notes:
195  * Can be done any time, only used after SpiSet
196  *
197  *****************************************************************************
198  */
199 extern void QspiChangeBaudRate(int spiSettings, int baudRateInMhz);
200 
201 /*
202  *****************************************************************************
203  *
204  * Gets current baud rate in Mhz for the current active setting.
205  *
206  * Parameters:
207  * None
208  *
209  * Return:
210  * Actual baud rate in Mhz
211  *
212  * Notes:
213  * Can be done any time, only used after SpiSet
214  *
215  *****************************************************************************
216  */
217 extern unsigned long QspiGetBaudRate(void);
218 
219 /*
220  *****************************************************************************
221  *
222  * Change bus setup.
223  *
224  * Parameters:
225  * spiSetting - Settings handle
226  *
227  * Return:
228  * None
229  *
230  * Notes:
231  * None
232  *
233  *****************************************************************************
234  */
235 extern void QspiChangeSetting(int spiSetting);
236 
237 /*
238  *****************************************************************************
239  *
240  * Send, receive or exchange bytes (8 bits) with slave
241  *
242  * Parameters:
243  * transmitBufferPtr - Buffer of bytes to send, NULL for receiving
244  * receiveBufferPtr - Buffer to receive data, NULL for sending
245  * byteCount - Count of bytes to send or receive
246  * finishedSemPtr - Optional semaphore to set when completed
247  *
248  * Return:
249  * None
250  *
251  * Notes:
252  * None
253  *
254  *****************************************************************************
255  */
256 extern void QspiExchangeBytes(uint8_t *transmitBufferPtr, uint8_t *receiveBufferPtr, uint32_t byteCount, OS_SEM *finishedSemPtr);
257 
258 /*
259  *****************************************************************************
260  *
261  * Send, receive or exchange data word with slave (9-16 bits)
262  *
263  * Parameters:
264  * transmitBufferPtr - Buffer of words to send, NULL for receiving
265  * receiveBufferPtr - Buffer to receive data, NULL for sending
266  * byteCount - Count of bytes to send or receive
267  * finishedSemPtr - Optional semaphore to set when completed
268  *
269  * Return:
270  * None
271  *
272  * Notes:
273  * None
274  *
275  *****************************************************************************
276  */
277 extern void QspiExchangeWords(uint16_t *transmitBufferPtr, uint16_t *receiveBufferPtr, uint32_t byteCount, OS_SEM *finishedSemPtr);
278 
279 /*
280  *****************************************************************************
281  *
282  * Setup chip select(s) as user not module controlled
283  *
284  * Parameters:
285  * chipSelects - Chips select mask
286  *
287  * Return:
288  * None
289  *
290  * Notes:
291  * Polarity set by isChipSelectActiveLow parameter of QspiInitialize.
292  *
293  *****************************************************************************
294  */
295 extern void QspiUserChipSelects(uint8_t chipSelects);
296 
297 /*
298  *****************************************************************************
299  *
300  * Select SPI device(s) by asserting chip select(s)
301  *
302  * Parameters:
303  * chipSelects - Chips select mask
304  *
305  * Return:
306  * None
307  *
308  * Notes:
309  * None
310  *
311  *****************************************************************************
312  */
313 extern void QspiSelectDevice(uint8_t chipSelects);
314 
315 /*
316  *****************************************************************************
317  *
318  * Release SPI device(s) by deasserting chip select(s)
319  *
320  * Parameters:
321  * chipSelects - Chips select mask
322  *
323  * Return:
324  * None
325  *
326  * Notes:
327  * None
328  *
329  *****************************************************************************
330  */
331 extern void QspiReleaseDevice(uint8_t chipSelects);
332 
333 /*
334  *****************************************************************************
335  *
336  * SDIO in the SPI Mode Functions (Driver use only)
337  *
338  *****************************************************************************
339  */
340 /*
341  *****************************************************************************
342  *
343  * Send command, process acknowledgement and send or receive data
344  *
345  * Parameters:
346  * commandBufferPtr - Buffer containing SDIO command (6 bytes)
347  * r5ResponsePtr - Buffer containing two bytes for SPI response
348  * sendData - TRUE send data else receive data
349  * dataBufferPtr - Buffer of bytes to send or recieve data
350  * byteCount - Count of bytes to send or receive
351  * responseTimeout - Response delay in ticks
352  *
353  * Return:
354  * TRUE - success, FALSE response timeout
355  *
356  * Notes:
357  * SDIO using the SPI mode.
358  *
359  *****************************************************************************
360  */
361 extern BOOL QspiSdioDataExchange(uint8_t *commandBufferPtr,
362  uint8_t *r5ResponsePtr,
363  BOOL sendData,
364  uint8_t *dataBufferPtr,
365  uint32_t byteCount,
366  uint32_t responseTimeout);
367 
368 #endif /* #ifndef _QSPI_SHARED_H_ */
Semaphores are used to control access to shared resource critical section, or to communicate between ...
Definition: nbrtos.h:318