Mistake on this page?
Report an issue in GitHub or email us
qspi_api.h
1 
2 /** \addtogroup hal */
3 /** @{*/
4 /* mbed Microcontroller Library
5  * Copyright (c) 2017 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_QSPI_API_H
21 #define MBED_QSPI_API_H
22 
23 #include "device.h"
24 #include "pinmap.h"
25 #include <stdbool.h>
26 
27 #if DEVICE_QSPI
28 
29 #ifdef __cplusplus
30 extern "C" {
31 #endif
32 
33 /**
34  * \defgroup hal_qspi QSPI HAL
35  * @{
36  */
37 
38 /** QSPI HAL object
39  */
40 typedef struct qspi_s qspi_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 sclk_pin;
53  int sclk_function;
54  PinName ssel_pin;
55  int ssel_function;
57 
58 /** QSPI Bus width
59  *
60  * Some parts of commands provide variable bus width
61  */
62 typedef enum qspi_bus_width {
63  QSPI_CFG_BUS_SINGLE,
64  QSPI_CFG_BUS_DUAL,
65  QSPI_CFG_BUS_QUAD,
67 
68 /** Address size in bits
69  */
70 typedef enum qspi_address_size {
71  QSPI_CFG_ADDR_SIZE_8,
72  QSPI_CFG_ADDR_SIZE_16,
73  QSPI_CFG_ADDR_SIZE_24,
74  QSPI_CFG_ADDR_SIZE_32,
76 
77 /** Alternative size in bits
78  */
79 typedef uint8_t qspi_alt_size_t;
80 
81 // The following defines are provided for backwards compatibilty. New code should explicitly
82 // specify the required number of alt bits.
83 #define QSPI_CFG_ALT_SIZE_8 8u
84 #define QSPI_CFG_ALT_SIZE_16 16u
85 #define QSPI_CFG_ALT_SIZE_24 24u
86 #define QSPI_CFG_ALT_SIZE_32 32u
87 
88 /** QSPI command
89  *
90  * Defines a frame format. It consists of instruction, address, alternative, dummy count and data
91  */
92 typedef struct qspi_command {
93  struct {
94  qspi_bus_width_t bus_width; /**< Bus width for the instruction >*/
95  uint8_t value; /**< Instruction value >*/
96  bool disabled; /**< Instruction phase skipped if disabled is set to true >*/
97  } instruction;
98  struct {
99  qspi_bus_width_t bus_width; /**< Bus width for the address >*/
100  qspi_address_size_t size; /**< Address size >*/
101  uint32_t value; /**< Address value >*/
102  bool disabled; /**< Address phase skipped if disabled is set to true >*/
103  } address;
104  struct {
105  qspi_bus_width_t bus_width; /**< Bus width for alternative >*/
106  qspi_alt_size_t size; /**< Alternative size >*/
107  uint32_t value; /**< Alternative value >*/
108  bool disabled; /**< Alternative phase skipped if disabled is set to true >*/
109  } alt;
110  uint8_t dummy_count; /**< Dummy cycles count >*/
111  struct {
112  qspi_bus_width_t bus_width; /**< Bus width for data >*/
113  } data;
115 
116 /** QSPI return status
117  */
118 typedef enum qspi_status {
119  QSPI_STATUS_ERROR = -1, /**< Generic error >*/
120  QSPI_STATUS_INVALID_PARAMETER = -2, /**< The parameter is invalid >*/
121  QSPI_STATUS_OK = 0, /**< Function executed sucessfully >*/
122 } qspi_status_t;
123 
124 /** Initialize QSPI peripheral.
125  *
126  * It should initialize QSPI pins (io0-io3, sclk and ssel), set frequency, clock polarity and phase mode. The clock for the peripheral should be enabled
127  *
128  * @param obj QSPI object
129  * @param io0 Data pin 0
130  * @param io1 Data pin 1
131  * @param io2 Data pin 2
132  * @param io3 Data pin 3
133  * @param sclk The clock pin
134  * @param ssel The chip select pin
135  * @param hz The bus frequency
136  * @param mode Clock polarity and phase mode (0 - 3)
137  * @return QSPI_STATUS_OK if initialisation successfully executed
138  QSPI_STATUS_INVALID_PARAMETER if invalid parameter found
139  QSPI_STATUS_ERROR otherwise
140  */
141 qspi_status_t qspi_init(qspi_t *obj, PinName io0, PinName io1, PinName io2, PinName io3, PinName sclk, PinName ssel, uint32_t hz, uint8_t mode);
142 
143 /** Initialize QSPI peripheral.
144  *
145  * It should initialize QSPI pins (io0-io3, sclk and ssel), set frequency, clock polarity and phase mode. The clock for the peripheral should be enabled
146  *
147  * @param obj QSPI object
148  * @param pinmap pointer to structure which holds static pinmap
149  * @param hz The bus frequency
150  * @param mode Clock polarity and phase mode (0 - 3)
151  * @return QSPI_STATUS_OK if initialisation successfully executed
152  QSPI_STATUS_INVALID_PARAMETER if invalid parameter found
153  QSPI_STATUS_ERROR otherwise
154  */
155 qspi_status_t qspi_init_direct(qspi_t *obj, const qspi_pinmap_t *pinmap, uint32_t hz, uint8_t mode);
156 
157 /** Deinitilize QSPI peripheral
158  *
159  * It should release pins that are associated with the QSPI object, and disable clocks for QSPI peripheral module that was associated with the object
160  *
161  * @param obj QSPI object
162  * @return QSPI_STATUS_OK if deinitialisation successfully executed
163  QSPI_STATUS_INVALID_PARAMETER if invalid parameter found
164  QSPI_STATUS_ERROR otherwise
165  */
167 
168 /** Set the QSPI baud rate
169  *
170  * Actual frequency may differ from the desired frequency due to available dividers and the bus clock
171  * Configures the QSPI peripheral's baud rate
172  * @param obj The SPI object to configure
173  * @param hz The baud rate in Hz
174  * @return QSPI_STATUS_OK if frequency was set
175  QSPI_STATUS_INVALID_PARAMETER if invalid parameter found
176  QSPI_STATUS_ERROR otherwise
177  */
178 qspi_status_t qspi_frequency(qspi_t *obj, int hz);
179 
180 /** Send a command and block of data
181  *
182  * @param obj QSPI object
183  * @param command QSPI command
184  * @param data TX buffer
185  * @param[in,out] length in - TX buffer length in bytes, out - number of bytes written
186  * @return QSPI_STATUS_OK if the data has been succesfully sent
187  QSPI_STATUS_INVALID_PARAMETER if invalid parameter found
188  QSPI_STATUS_ERROR otherwise
189  */
190 qspi_status_t qspi_write(qspi_t *obj, const qspi_command_t *command, const void *data, size_t *length);
191 
192 /** Send a command (and optionally data) and get the response. Can be used to send/receive device specific commands
193  *
194  * @param obj QSPI object
195  * @param command QSPI command
196  * @param tx_data TX buffer
197  * @param tx_size TX buffer length in bytes
198  * @param rx_data RX buffer
199  * @param rx_size RX buffer length in bytes
200  * @return QSPI_STATUS_OK if the data has been succesfully sent
201  QSPI_STATUS_INVALID_PARAMETER if invalid parameter found
202  QSPI_STATUS_ERROR otherwise
203  */
204 qspi_status_t qspi_command_transfer(qspi_t *obj, const qspi_command_t *command, const void *tx_data, size_t tx_size, void *rx_data, size_t rx_size);
205 
206 /** Receive a command and block of data
207  *
208  * @param obj QSPI object
209  * @param command QSPI command
210  * @param data RX buffer
211  * @param[in,out] length in - RX buffer length in bytes, out - number of bytes read
212  * @return QSPI_STATUS_OK if data has been succesfully received
213  QSPI_STATUS_INVALID_PARAMETER if invalid parameter found
214  QSPI_STATUS_ERROR otherwise
215  */
216 qspi_status_t qspi_read(qspi_t *obj, const qspi_command_t *command, void *data, size_t *length);
217 
218 /** Get the pins that support QSPI SCLK
219  *
220  * Return a PinMap array of pins that support QSPI SCLK in
221  * master mode. The array is terminated with {NC, NC, 0}.
222  *
223  * @return PinMap array
224  */
225 const PinMap *qspi_master_sclk_pinmap(void);
226 
227 /** Get the pins that support QSPI SSEL
228  *
229  * Return a PinMap array of pins that support QSPI SSEL in
230  * master mode. The array is terminated with {NC, NC, 0}.
231  *
232  * @return PinMap array
233  */
234 const PinMap *qspi_master_ssel_pinmap(void);
235 
236 /** Get the pins that support QSPI DATA0
237  *
238  * Return a PinMap array of pins that support QSPI DATA0 in
239  * master mode. The array is terminated with {NC, NC, 0}.
240  *
241  * @return PinMap array
242  */
243 const PinMap *qspi_master_data0_pinmap(void);
244 
245 /** Get the pins that support QSPI DATA1
246  *
247  * Return a PinMap array of pins that support QSPI DATA1 in
248  * master mode. The array is terminated with {NC, NC, 0}.
249  *
250  * @return PinMap array
251  */
252 const PinMap *qspi_master_data1_pinmap(void);
253 
254 /** Get the pins that support QSPI DATA2
255  *
256  * Return a PinMap array of pins that support QSPI DATA2 in
257  * master mode. The array is terminated with {NC, NC, 0}.
258  *
259  * @return PinMap array
260  */
261 const PinMap *qspi_master_data2_pinmap(void);
262 
263 /** Get the pins that support QSPI DATA3
264  *
265  * Return a PinMap array of pins that support QSPI DATA3 in
266  * master mode. The array is terminated with {NC, NC, 0}.
267  *
268  * @return PinMap array
269  */
270 const PinMap *qspi_master_data3_pinmap(void);
271 
272 /**@}*/
273 
274 #ifdef __cplusplus
275 }
276 #endif
277 
278 #endif
279 
280 #endif
281 
282 /** @}*/
qspi_status_t qspi_frequency(qspi_t *obj, int hz)
Set the QSPI baud rate.
QSPI command.
Definition: qspi_api.h:92
qspi_status_t qspi_init_direct(qspi_t *obj, const qspi_pinmap_t *pinmap, uint32_t hz, uint8_t mode)
Initialize QSPI peripheral.
const PinMap * qspi_master_data0_pinmap(void)
Get the pins that support QSPI DATA0.
struct qspi_command qspi_command_t
QSPI command.
uint8_t dummy_count
Dummy cycles count >
Definition: qspi_api.h:110
struct qspi_s qspi_t
QSPI HAL object.
Definition: qspi_api.h:40
const PinMap * qspi_master_ssel_pinmap(void)
Get the pins that support QSPI SSEL.
qspi_status_t qspi_read(qspi_t *obj, const qspi_command_t *command, void *data, size_t *length)
Receive a command and block of data.
uint32_t value
Address value >
Definition: qspi_api.h:101
Generic error >
Definition: qspi_api.h:119
const PinMap * qspi_master_data1_pinmap(void)
Get the pins that support QSPI DATA1.
The parameter is invalid >
Definition: qspi_api.h:120
qspi_status_t qspi_write(qspi_t *obj, const qspi_command_t *command, const void *data, size_t *length)
Send a command and block of data.
bool disabled
Instruction phase skipped if disabled is set to true >
Definition: qspi_api.h:96
qspi_status
QSPI return status.
Definition: qspi_api.h:118
qspi_bus_width_t bus_width
Bus width for the instruction >
Definition: qspi_api.h:94
qspi_alt_size_t size
Alternative size >
Definition: qspi_api.h:106
qspi_status_t qspi_command_transfer(qspi_t *obj, const qspi_command_t *command, const void *tx_data, size_t tx_size, void *rx_data, size_t rx_size)
Send a command (and optionally data) and get the response.
enum qspi_address_size qspi_address_size_t
Address size in bits.
qspi_status_t qspi_init(qspi_t *obj, PinName io0, PinName io1, PinName io2, PinName io3, PinName sclk, PinName ssel, uint32_t hz, uint8_t mode)
Initialize QSPI peripheral.
Definition: pinmap.h:31
const PinMap * qspi_master_data2_pinmap(void)
Get the pins that support QSPI DATA2.
const PinMap * qspi_master_sclk_pinmap(void)
Get the pins that support QSPI SCLK.
uint8_t qspi_alt_size_t
Alternative size in bits.
Definition: qspi_api.h:79
qspi_address_size_t size
Address size >
Definition: qspi_api.h:100
enum qspi_bus_width qspi_bus_width_t
QSPI Bus width.
qspi_address_size
Address size in bits.
Definition: qspi_api.h:70
qspi_bus_width
QSPI Bus width.
Definition: qspi_api.h:62
uint8_t value
Instruction value >
Definition: qspi_api.h:95
Function executed sucessfully >
Definition: qspi_api.h:121
enum qspi_status qspi_status_t
QSPI return status.
const PinMap * qspi_master_data3_pinmap(void)
Get the pins that support QSPI DATA3.
qspi_status_t qspi_free(qspi_t *obj)
Deinitilize QSPI peripheral.
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.