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 /** QSPI Bus width
43  *
44  * Some parts of commands provide variable bus width
45  */
46 typedef enum qspi_bus_width {
47  QSPI_CFG_BUS_SINGLE,
48  QSPI_CFG_BUS_DUAL,
49  QSPI_CFG_BUS_QUAD,
51 
52 /** Address size in bits
53  */
54 typedef enum qspi_address_size {
55  QSPI_CFG_ADDR_SIZE_8,
56  QSPI_CFG_ADDR_SIZE_16,
57  QSPI_CFG_ADDR_SIZE_24,
58  QSPI_CFG_ADDR_SIZE_32,
60 
61 /** Alternative size in bits
62  */
63 typedef enum qspi_alt_size {
64  QSPI_CFG_ALT_SIZE_8,
65  QSPI_CFG_ALT_SIZE_16,
66  QSPI_CFG_ALT_SIZE_24,
67  QSPI_CFG_ALT_SIZE_32,
69 
70 /** QSPI command
71  *
72  * Defines a frame format. It consists of instruction, address, alternative, dummy count and data
73  */
74 typedef struct qspi_command {
75  struct {
76  qspi_bus_width_t bus_width; /**< Bus width for the instruction >*/
77  uint8_t value; /**< Instruction value >*/
78  bool disabled; /**< Instruction phase skipped if disabled is set to true >*/
79  } instruction;
80  struct {
81  qspi_bus_width_t bus_width; /**< Bus width for the address >*/
82  qspi_address_size_t size; /**< Address size >*/
83  uint32_t value; /**< Address value >*/
84  bool disabled; /**< Address phase skipped if disabled is set to true >*/
85  } address;
86  struct {
87  qspi_bus_width_t bus_width; /**< Bus width for alternative >*/
88  qspi_alt_size_t size; /**< Alternative size >*/
89  uint32_t value; /**< Alternative value >*/
90  bool disabled; /**< Alternative phase skipped if disabled is set to true >*/
91  } alt;
92  uint8_t dummy_count; /**< Dummy cycles count >*/
93  struct {
94  qspi_bus_width_t bus_width; /**< Bus width for data >*/
95  } data;
97 
98 /** QSPI return status
99  */
100 typedef enum qspi_status {
101  QSPI_STATUS_ERROR = -1, /**< Generic error >*/
102  QSPI_STATUS_INVALID_PARAMETER = -2, /**< The parameter is invalid >*/
103  QSPI_STATUS_OK = 0, /**< Function executed sucessfully >*/
104 } qspi_status_t;
105 
106 /** Initialize QSPI peripheral.
107  *
108  * 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
109  *
110  * @param obj QSPI object
111  * @param io0 Data pin 0
112  * @param io1 Data pin 1
113  * @param io2 Data pin 2
114  * @param io3 Data pin 3
115  * @param sclk The clock pin
116  * @param ssel The chip select pin
117  * @param hz The bus frequency
118  * @param mode Clock polarity and phase mode (0 - 3)
119  * @return QSPI_STATUS_OK if initialisation successfully executed
120  QSPI_STATUS_INVALID_PARAMETER if invalid parameter found
121  QSPI_STATUS_ERROR otherwise
122  */
123 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);
124 
125 /** Deinitilize QSPI peripheral
126  *
127  * It should release pins that are associated with the QSPI object, and disable clocks for QSPI peripheral module that was associated with the object
128  *
129  * @param obj QSPI object
130  * @return QSPI_STATUS_OK if deinitialisation successfully executed
131  QSPI_STATUS_INVALID_PARAMETER if invalid parameter found
132  QSPI_STATUS_ERROR otherwise
133  */
135 
136 /** Set the QSPI baud rate
137  *
138  * Actual frequency may differ from the desired frequency due to available dividers and the bus clock
139  * Configures the QSPI peripheral's baud rate
140  * @param obj The SPI object to configure
141  * @param hz The baud rate in Hz
142  * @return QSPI_STATUS_OK if frequency was set
143  QSPI_STATUS_INVALID_PARAMETER if invalid parameter found
144  QSPI_STATUS_ERROR otherwise
145  */
146 qspi_status_t qspi_frequency(qspi_t *obj, int hz);
147 
148 /** Send a command and block of data
149  *
150  * @param obj QSPI object
151  * @param command QSPI command
152  * @param data TX buffer
153  * @param[in,out] length in - TX buffer length in bytes, out - number of bytes written
154  * @return QSPI_STATUS_OK if the data has been succesfully sent
155  QSPI_STATUS_INVALID_PARAMETER if invalid parameter found
156  QSPI_STATUS_ERROR otherwise
157  */
158 qspi_status_t qspi_write(qspi_t *obj, const qspi_command_t *command, const void *data, size_t *length);
159 
160 /** Send a command (and optionally data) and get the response. Can be used to send/receive device specific commands
161  *
162  * @param obj QSPI object
163  * @param command QSPI command
164  * @param tx_data TX buffer
165  * @param tx_size TX buffer length in bytes
166  * @param rx_data RX buffer
167  * @param rx_size RX buffer length in bytes
168  * @return QSPI_STATUS_OK if the data has been succesfully sent
169  QSPI_STATUS_INVALID_PARAMETER if invalid parameter found
170  QSPI_STATUS_ERROR otherwise
171  */
172 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);
173 
174 /** Receive a command and block of data
175  *
176  * @param obj QSPI object
177  * @param command QSPI command
178  * @param data RX buffer
179  * @param[in,out] length in - RX buffer length in bytes, out - number of bytes read
180  * @return QSPI_STATUS_OK if data has been succesfully received
181  QSPI_STATUS_INVALID_PARAMETER if invalid parameter found
182  QSPI_STATUS_ERROR otherwise
183  */
184 qspi_status_t qspi_read(qspi_t *obj, const qspi_command_t *command, void *data, size_t *length);
185 
186 /** Get the pins that support QSPI SCLK
187  *
188  * Return a PinMap array of pins that support QSPI SCLK in
189  * master mode. The array is terminated with {NC, NC, 0}.
190  *
191  * @return PinMap array
192  */
193 const PinMap *qspi_master_sclk_pinmap(void);
194 
195 /** Get the pins that support QSPI SSEL
196  *
197  * Return a PinMap array of pins that support QSPI SSEL in
198  * master mode. The array is terminated with {NC, NC, 0}.
199  *
200  * @return PinMap array
201  */
202 const PinMap *qspi_master_ssel_pinmap(void);
203 
204 /** Get the pins that support QSPI DATA0
205  *
206  * Return a PinMap array of pins that support QSPI DATA0 in
207  * master mode. The array is terminated with {NC, NC, 0}.
208  *
209  * @return PinMap array
210  */
211 const PinMap *qspi_master_data0_pinmap(void);
212 
213 /** Get the pins that support QSPI DATA1
214  *
215  * Return a PinMap array of pins that support QSPI DATA1 in
216  * master mode. The array is terminated with {NC, NC, 0}.
217  *
218  * @return PinMap array
219  */
220 const PinMap *qspi_master_data1_pinmap(void);
221 
222 /** Get the pins that support QSPI DATA2
223  *
224  * Return a PinMap array of pins that support QSPI DATA2 in
225  * master mode. The array is terminated with {NC, NC, 0}.
226  *
227  * @return PinMap array
228  */
229 const PinMap *qspi_master_data2_pinmap(void);
230 
231 /** Get the pins that support QSPI DATA3
232  *
233  * Return a PinMap array of pins that support QSPI DATA3 in
234  * master mode. The array is terminated with {NC, NC, 0}.
235  *
236  * @return PinMap array
237  */
238 const PinMap *qspi_master_data3_pinmap(void);
239 
240 /**@}*/
241 
242 #ifdef __cplusplus
243 }
244 #endif
245 
246 #endif
247 
248 #endif
249 
250 /** @}*/
qspi_status_t qspi_frequency(qspi_t *obj, int hz)
Set the QSPI baud rate.
QSPI command.
Definition: qspi_api.h:74
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:92
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:83
Generic error >
Definition: qspi_api.h:101
enum qspi_alt_size qspi_alt_size_t
Alternative size in bits.
const PinMap * qspi_master_data1_pinmap(void)
Get the pins that support QSPI DATA1.
The parameter is invalid >
Definition: qspi_api.h:102
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:78
qspi_status
QSPI return status.
Definition: qspi_api.h:100
qspi_bus_width_t bus_width
Bus width for the instruction >
Definition: qspi_api.h:76
qspi_alt_size_t size
Alternative size >
Definition: qspi_api.h:88
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_alt_size
Alternative size in bits.
Definition: qspi_api.h:63
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:30
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.
qspi_address_size_t size
Address size >
Definition: qspi_api.h:82
enum qspi_bus_width qspi_bus_width_t
QSPI Bus width.
qspi_address_size
Address size in bits.
Definition: qspi_api.h:54
qspi_bus_width
QSPI Bus width.
Definition: qspi_api.h:46
uint8_t value
Instruction value >
Definition: qspi_api.h:77
Function executed sucessfully >
Definition: qspi_api.h:103
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.