Kenji Arai / mbed-os_TYBLE16

mbed-os5 only for TYBLE16

Dependents:   TYBLE16_simple_data_logger TYBLE16_MP3_Air

hal/qspi_api.h@1:9db0e321a9f4, 2019-12-31 (annotated)

Committer:
kenjiArai
Date:
Tue Dec 31 06:02:27 2019 +0000
Revision:
1:9db0e321a9f4
Parent:
0:5b88d5760320 
updated based on mbed-os5.15.0

Who changed what in which revision?

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