Keil Studio Cloud
Mistake on this page?
Report an issue in GitHub or email us
ospi_api.h
1 
2 /** \addtogroup hal */
3 /** @{*/
4 /* mbed Microcontroller Library
5  * Copyright (c) 2020 ARM Limited
6  * SPDX-License-Identifier: Apache-2.0
7  *
8  * Licensed under the Apache License, Version 2.0 (the "License");
9  * you may not use this file except in compliance with the License.
10  * You may obtain a copy of the License at
11  *
12  * http://www.apache.org/licenses/LICENSE-2.0
13  *
14  * Unless required by applicable law or agreed to in writing, software
15  * distributed under the License is distributed on an "AS IS" BASIS,
16  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
17  * See the License for the specific language governing permissions and
18  * limitations under the License.
19  */
20 #ifndef MBED_OSPI_API_H
21 #define MBED_OSPI_API_H
22 
23 #include "device.h"
24 #include "pinmap.h"
25 #include <stdbool.h>
26 
27 #if DEVICE_OSPI
28 
29 #ifdef __cplusplus
30 extern "C" {
31 #endif
32 
33 /**
34  * \defgroup hal_ospi OSPI HAL
35  * @{
36  */
37 
38 /** OSPI HAL object
39  */
40 typedef struct ospi_s ospi_t;
41 
42 typedef struct {
43  int peripheral;
44  PinName data0_pin;
45  int data0_function;
46  PinName data1_pin;
47  int data1_function;
48  PinName data2_pin;
49  int data2_function;
50  PinName data3_pin;
51  int data3_function;
52  PinName data4_pin;
53  int data4_function;
54  PinName data5_pin;
55  int data5_function;
56  PinName data6_pin;
57  int data6_function;
58  PinName data7_pin;
59  int data7_function;
60  PinName sclk_pin;
61  int sclk_function;
62  PinName ssel_pin;
63  int ssel_function;
64  PinName dqs_pin;
65  int dqs_function;
66 
67 } ospi_pinmap_t;
68 
69 /** OSPI Bus width
70  *
71  * Some parts of commands provide variable bus width
72  */
73 typedef enum ospi_bus_width {
74  OSPI_CFG_BUS_SINGLE,
75  OSPI_CFG_BUS_DUAL,
76  OSPI_CFG_BUS_QUAD,
77  OSPI_CFG_BUS_OCTA,
78  OSPI_CFG_BUS_OCTA_DTR,
79 } ospi_bus_width_t;
80 
81 /** Instruction size in bits
82  */
83 typedef enum ospi_inst_size {
84  OSPI_CFG_INST_SIZE_8, /* 1 byte for SPI mode */
85  OSPI_CFG_INST_SIZE_16, /* 2 byte for OPI mode */
86 } ospi_inst_size_t;
87 
88 /** Address size in bits
89  */
90 typedef enum ospi_address_size {
91  OSPI_CFG_ADDR_SIZE_8,
92  OSPI_CFG_ADDR_SIZE_16,
93  OSPI_CFG_ADDR_SIZE_24,
94  OSPI_CFG_ADDR_SIZE_32,
95 } ospi_address_size_t;
96 
97 /** Alternative size in bits
98  */
99 typedef uint8_t ospi_alt_size_t;
100 
101 // The following defines are provided for backwards compatibilty. New code should explicitly
102 // specify the required number of alt bits.
103 #define OSPI_CFG_ALT_SIZE_8 8u
104 #define OSPI_CFG_ALT_SIZE_16 16u
105 #define OSPI_CFG_ALT_SIZE_24 24u
106 #define OSPI_CFG_ALT_SIZE_32 32u
107 
108 /** OSPI command
109  *
110  * Defines a frame format. It consists of instruction, address, alternative, dummy count and data
111  */
112 typedef struct ospi_command {
113  struct {
114  ospi_bus_width_t bus_width; /**< Bus width for the instruction >*/
115  ospi_inst_size_t size; /**< Inst size >*/
116  uint32_t value; /**< Instruction value >*/
117  bool disabled; /**< Instruction phase skipped if disabled is set to true >*/
118  } instruction;
119  struct {
120  ospi_bus_width_t bus_width; /**< Bus width for the address >*/
121  ospi_address_size_t size; /**< Address size >*/
122  uint32_t value; /**< Address value >*/
123  bool disabled; /**< Address phase skipped if disabled is set to true >*/
124  } address;
125  struct {
126  ospi_bus_width_t bus_width; /**< Bus width for alternative >*/
127  ospi_alt_size_t size; /**< Alternative size >*/
128  uint32_t value; /**< Alternative value >*/
129  bool disabled; /**< Alternative phase skipped if disabled is set to true >*/
130  } alt;
131  uint8_t dummy_count; /**< Dummy cycles count >*/
132  struct {
133  ospi_bus_width_t bus_width; /**< Bus width for data >*/
134  } data;
135 } ospi_command_t;
136 
137 /** OSPI return status
138  */
139 typedef enum ospi_status {
140  OSPI_STATUS_ERROR = -1, /**< Generic error >*/
141  OSPI_STATUS_INVALID_PARAMETER = -2, /**< The parameter is invalid >*/
142  OSPI_STATUS_OK = 0, /**< Function executed sucessfully >*/
143 } ospi_status_t;
144 
145 /** Initialize OSPI peripheral.
146  *
147  * It should initialize OSPI pins (io0-io7, sclk, ssel and dqs), set frequency, clock polarity and phase mode. The clock for the peripheral should be enabled
148  *
149  * @param obj OSPI object
150  * @param io0 Data pin 0
151  * @param io1 Data pin 1
152  * @param io2 Data pin 2
153  * @param io3 Data pin 3
154  * @param io4 Data pin 4
155  * @param io5 Data pin 5
156  * @param io6 Data pin 6
157  * @param io7 Data pin 7
158  * @param sclk The clock pin
159  * @param ssel The chip select pin
160  * @param dqs The chip dqs pin
161  * @param hz The bus frequency
162  * @param mode Clock polarity and phase mode (0 - 3)
163  * @return OSPI_STATUS_OK if initialisation successfully executed
164  OSPI_STATUS_INVALID_PARAMETER if invalid parameter found
165  OSPI_STATUS_ERROR otherwise
166  */
167 ospi_status_t ospi_init(ospi_t *obj, PinName io0, PinName io1, PinName io2, PinName io3, PinName io4, PinName io5, PinName io6, PinName io7,
168  PinName sclk, PinName ssel, PinName dqs, uint32_t hz, uint8_t mode);
169 
170 /** Initialize OSPI peripheral.
171  *
172  * It should initialize OSPI pins (io0-io7, sclk, ssel and dqs), set frequency, clock polarity and phase mode. The clock for the peripheral should be enabled
173  *
174  * @param obj OSPI object
175  * @param pinmap pointer to structure which holds static pinmap
176  * @param hz The bus frequency
177  * @param mode Clock polarity and phase mode (0 - 3)
178  * @return OSPI_STATUS_OK if initialisation successfully executed
179  OSPI_STATUS_INVALID_PARAMETER if invalid parameter found
180  OSPI_STATUS_ERROR otherwise
181  */
182 ospi_status_t ospi_init_direct(ospi_t *obj, const ospi_pinmap_t *pinmap, uint32_t hz, uint8_t mode);
183 
184 /** Deinitialize OSPI peripheral
185  *
186  * It should release pins that are associated with the OSPI object, and disable clocks for OSPI peripheral module that was associated with the object
187  *
188  * @param obj OSPI object
189  * @return OSPI_STATUS_OK if deinitialisation successfully executed
190  OSPI_STATUS_INVALID_PARAMETER if invalid parameter found
191  OSPI_STATUS_ERROR otherwise
192  */
193 ospi_status_t ospi_free(ospi_t *obj);
194 
195 /** Set the OSPI baud rate
196  *
197  * Actual frequency may differ from the desired frequency due to available dividers and the bus clock
198  * Configures the OSPI peripheral's baud rate
199  * @param obj The SPI object to configure
200  * @param hz The baud rate in Hz
201  * @return OSPI_STATUS_OK if frequency was set
202  OSPI_STATUS_INVALID_PARAMETER if invalid parameter found
203  OSPI_STATUS_ERROR otherwise
204  */
205 ospi_status_t ospi_frequency(ospi_t *obj, int hz);
206 
207 /** Send a command and block of data
208  *
209  * @param obj OSPI object
210  * @param command OSPI command
211  * @param data TX buffer
212  * @param[in,out] length in - TX buffer length in bytes, out - number of bytes written
213  * @return OSPI_STATUS_OK if the data has been succesfully sent
214  OSPI_STATUS_INVALID_PARAMETER if invalid parameter found
215  OSPI_STATUS_ERROR otherwise
216  */
217 ospi_status_t ospi_write(ospi_t *obj, const ospi_command_t *command, const void *data, size_t *length);
218 
219 /** Send a command (and optionally data) and get the response. Can be used to send/receive device specific commands
220  *
221  * @param obj OSPI object
222  * @param command OSPI command
223  * @param tx_data TX buffer
224  * @param tx_size TX buffer length in bytes
225  * @param rx_data RX buffer
226  * @param rx_size RX buffer length in bytes
227  * @return OSPI_STATUS_OK if the data has been succesfully sent
228  OSPI_STATUS_INVALID_PARAMETER if invalid parameter found
229  OSPI_STATUS_ERROR otherwise
230  */
231 ospi_status_t ospi_command_transfer(ospi_t *obj, const ospi_command_t *command, const void *tx_data, size_t tx_size, void *rx_data, size_t rx_size);
232 
233 /** Receive a command and block of data
234  *
235  * @param obj OSPI object
236  * @param command OSPI command
237  * @param data RX buffer
238  * @param[in,out] length in - RX buffer length in bytes, out - number of bytes read
239  * @return OSPI_STATUS_OK if data has been succesfully received
240  OSPI_STATUS_INVALID_PARAMETER if invalid parameter found
241  OSPI_STATUS_ERROR otherwise
242  */
243 ospi_status_t ospi_read(ospi_t *obj, const ospi_command_t *command, void *data, size_t *length);
244 
245 /** Get the pins that support OSPI SCLK
246  *
247  * Return a PinMap array of pins that support OSPI SCLK in
248  * master mode. The array is terminated with {NC, NC, 0}.
249  *
250  * @return PinMap array
251  */
252 const PinMap *ospi_master_sclk_pinmap(void);
253 
254 /** Get the pins that support OSPI SSEL
255  *
256  * Return a PinMap array of pins that support OSPI SSEL in
257  * master mode. The array is terminated with {NC, NC, 0}.
258  *
259  * @return PinMap array
260  */
261 const PinMap *ospi_master_ssel_pinmap(void);
262 
263 /** Get the pins that support OSPI DQS
264  *
265  * Return a PinMap array of pins that support OSPI DQS in
266  * master mode. The array is terminated with {NC, NC, 0}.
267  *
268  * @return PinMap array
269  */
270 const PinMap *ospi_master_dqs_pinmap(void);
271 
272 /** Get the pins that support OSPI DATA0
273  *
274  * Return a PinMap array of pins that support OSPI DATA0 in
275  * master mode. The array is terminated with {NC, NC, 0}.
276  *
277  * @return PinMap array
278  */
279 const PinMap *ospi_master_data0_pinmap(void);
280 
281 /** Get the pins that support OSPI DATA1
282  *
283  * Return a PinMap array of pins that support OSPI DATA1 in
284  * master mode. The array is terminated with {NC, NC, 0}.
285  *
286  * @return PinMap array
287  */
288 const PinMap *ospi_master_data1_pinmap(void);
289 
290 /** Get the pins that support OSPI DATA2
291  *
292  * Return a PinMap array of pins that support OSPI DATA2 in
293  * master mode. The array is terminated with {NC, NC, 0}.
294  *
295  * @return PinMap array
296  */
297 const PinMap *ospi_master_data2_pinmap(void);
298 
299 /** Get the pins that support OSPI DATA3
300  *
301  * Return a PinMap array of pins that support OSPI DATA3 in
302  * master mode. The array is terminated with {NC, NC, 0}.
303  *
304  * @return PinMap array
305  */
306 const PinMap *ospi_master_data3_pinmap(void);
307 
308 /** Get the pins that support OSPI DATA4
309  *
310  * Return a PinMap array of pins that support OSPI DATA4 in
311  * master mode. The array is terminated with {NC, NC, 0}.
312  *
313  * @return PinMap array
314  */
315 const PinMap *ospi_master_data4_pinmap(void);
316 
317 /** Get the pins that support OSPI DATA5
318  *
319  * Return a PinMap array of pins that support OSPI DATA5 in
320  * master mode. The array is terminated with {NC, NC, 0}.
321  *
322  * @return PinMap array
323  */
324 const PinMap *ospi_master_data5_pinmap(void);
325 
326 /** Get the pins that support OSPI DATA6
327  *
328  * Return a PinMap array of pins that support OSPI DATA6 in
329  * master mode. The array is terminated with {NC, NC, 0}.
330  *
331  * @return PinMap array
332  */
333 const PinMap *ospi_master_data6_pinmap(void);
334 
335 /** Get the pins that support OSPI DATA7
336  *
337  * Return a PinMap array of pins that support OSPI DATA7 in
338  * master mode. The array is terminated with {NC, NC, 0}.
339  *
340  * @return PinMap array
341  */
342 const PinMap *ospi_master_data7_pinmap(void);
343 
344 /**@}*/
345 
346 #ifdef __cplusplus
347 }
348 #endif
349 
350 #endif
351 
352 #endif
353 
354 /** @}*/
PinMap
Definition: pinmap.h:31
Important Information for this Arm website

This site uses cookies to store information on your computer. By continuing to use our site, you consent to our cookies. If you are not happy with the use of these cookies, please review our Cookie Policy to learn how they can be disabled. By disabling cookies, some features of the site will not work.