qspi_api.h

00001 
00002 /** \addtogroup hal */
00003 /** @{*/
00004 /* mbed Microcontroller Library
00005  * Copyright (c) 2017 ARM Limited
00006  * SPDX-License-Identifier: Apache-2.0
00007  *
00008  * Licensed under the Apache License, Version 2.0 (the "License");
00009  * you may not use this file except in compliance with the License.
00010  * You may obtain a copy of the License at
00011  *
00012  *     http://www.apache.org/licenses/LICENSE-2.0
00013  *
00014  * Unless required by applicable law or agreed to in writing, software
00015  * distributed under the License is distributed on an "AS IS" BASIS,
00016  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00017  * See the License for the specific language governing permissions and
00018  * limitations under the License.
00019  */
00020 #ifndef MBED_QSPI_API_H
00021 #define MBED_QSPI_API_H
00022 
00023 #include "device.h"
00024 #include "pinmap.h"
00025 #include <stdbool.h>
00026 
00027 #if DEVICE_QSPI
00028 
00029 #ifdef __cplusplus
00030 extern "C" {
00031 #endif
00032 
00033 /**
00034  * \defgroup hal_qspi QSPI HAL
00035  * @{
00036  */
00037 
00038 /** QSPI HAL object
00039  */
00040 typedef struct qspi_s qspi_t;
00041 
00042 typedef struct {
00043     int peripheral;
00044     PinName data0_pin;
00045     int data0_function;
00046     PinName data1_pin;
00047     int data1_function;
00048     PinName data2_pin;
00049     int data2_function;
00050     PinName data3_pin;
00051     int data3_function;
00052     PinName sclk_pin;
00053     int sclk_function;
00054     PinName ssel_pin;
00055     int ssel_function;
00056 } qspi_pinmap_t;
00057 
00058 /** QSPI Bus width
00059  *
00060  * Some parts of commands provide variable bus width
00061  */
00062 typedef enum qspi_bus_width {
00063     QSPI_CFG_BUS_SINGLE,
00064     QSPI_CFG_BUS_DUAL,
00065     QSPI_CFG_BUS_QUAD,
00066 } qspi_bus_width_t;
00067 
00068 /** Address size in bits
00069  */
00070 typedef enum qspi_address_size {
00071     QSPI_CFG_ADDR_SIZE_8,
00072     QSPI_CFG_ADDR_SIZE_16,
00073     QSPI_CFG_ADDR_SIZE_24,
00074     QSPI_CFG_ADDR_SIZE_32,
00075 } qspi_address_size_t;
00076 
00077 /** Alternative size in bits
00078  */
00079 typedef uint8_t qspi_alt_size_t;
00080 
00081 // The following defines are provided for backwards compatibilty. New code should explicitly
00082 // specify the required number of alt bits.
00083 #define QSPI_CFG_ALT_SIZE_8 8u
00084 #define QSPI_CFG_ALT_SIZE_16 16u
00085 #define QSPI_CFG_ALT_SIZE_24 24u
00086 #define QSPI_CFG_ALT_SIZE_32 32u
00087 
00088 /** QSPI command
00089  *
00090  * Defines a frame format. It consists of instruction, address, alternative, dummy count and data
00091  */
00092 typedef struct qspi_command {
00093     struct {
00094         qspi_bus_width_t bus_width; /**< Bus width for the instruction >*/
00095         uint8_t value;  /**< Instruction value >*/
00096         bool disabled; /**< Instruction phase skipped if disabled is set to true >*/
00097     } instruction;
00098     struct {
00099         qspi_bus_width_t bus_width; /**< Bus width for the address >*/
00100         qspi_address_size_t size; /**< Address size >*/
00101         uint32_t value; /**< Address value >*/
00102         bool disabled; /**< Address phase skipped if disabled is set to true >*/
00103     }  address;
00104     struct {
00105         qspi_bus_width_t bus_width; /**< Bus width for alternative  >*/
00106         qspi_alt_size_t size; /**< Alternative size >*/
00107         uint32_t value; /**< Alternative value >*/
00108         bool disabled; /**< Alternative phase skipped if disabled is set to true >*/
00109     } alt;
00110     uint8_t dummy_count; /**< Dummy cycles count >*/
00111     struct {
00112         qspi_bus_width_t bus_width; /**< Bus width for data >*/
00113     } data;
00114 } qspi_command_t;
00115 
00116 /** QSPI return status
00117  */
00118 typedef enum qspi_status {
00119     QSPI_STATUS_ERROR = -1, /**< Generic error >*/
00120     QSPI_STATUS_INVALID_PARAMETER = -2, /**< The parameter is invalid >*/
00121     QSPI_STATUS_OK    =  0, /**< Function executed sucessfully  >*/
00122 } qspi_status_t;
00123 
00124 /** Initialize QSPI peripheral.
00125  *
00126  * 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
00127  *
00128  * @param obj QSPI object
00129  * @param io0 Data pin 0
00130  * @param io1 Data pin 1
00131  * @param io2 Data pin 2
00132  * @param io3 Data pin 3
00133  * @param sclk The clock pin
00134  * @param ssel The chip select pin
00135  * @param hz The bus frequency
00136  * @param mode Clock polarity and phase mode (0 - 3)
00137  * @return QSPI_STATUS_OK if initialisation successfully executed
00138            QSPI_STATUS_INVALID_PARAMETER if invalid parameter found
00139            QSPI_STATUS_ERROR otherwise
00140  */
00141 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);
00142 
00143 /** Initialize QSPI peripheral.
00144  *
00145  * 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
00146  *
00147  * @param obj QSPI object
00148  * @param pinmap pointer to structure which holds static pinmap
00149  * @param hz The bus frequency
00150  * @param mode Clock polarity and phase mode (0 - 3)
00151  * @return QSPI_STATUS_OK if initialisation successfully executed
00152            QSPI_STATUS_INVALID_PARAMETER if invalid parameter found
00153            QSPI_STATUS_ERROR otherwise
00154  */
00155 qspi_status_t qspi_init_direct(qspi_t *obj, const qspi_pinmap_t *pinmap, uint32_t hz, uint8_t mode);
00156 
00157 /** Deinitilize QSPI peripheral
00158  *
00159  * It should release pins that are associated with the QSPI object, and disable clocks for QSPI peripheral module that was associated with the object
00160  *
00161  * @param obj QSPI object
00162  * @return QSPI_STATUS_OK if deinitialisation successfully executed
00163            QSPI_STATUS_INVALID_PARAMETER if invalid parameter found
00164            QSPI_STATUS_ERROR otherwise
00165  */
00166 qspi_status_t qspi_free(qspi_t *obj);
00167 
00168 /** Set the QSPI baud rate
00169  *
00170  * Actual frequency may differ from the desired frequency due to available dividers and the bus clock
00171  * Configures the QSPI peripheral's baud rate
00172  * @param obj The SPI object to configure
00173  * @param hz  The baud rate in Hz
00174  * @return QSPI_STATUS_OK if frequency was set
00175            QSPI_STATUS_INVALID_PARAMETER if invalid parameter found
00176            QSPI_STATUS_ERROR otherwise
00177  */
00178 qspi_status_t qspi_frequency(qspi_t *obj, int hz);
00179 
00180 /** Send a command and block of data
00181  *
00182  * @param obj QSPI object
00183  * @param command QSPI command
00184  * @param data TX buffer
00185  * @param[in,out] length in - TX buffer length in bytes, out - number of bytes written
00186  * @return QSPI_STATUS_OK if the data has been succesfully sent
00187            QSPI_STATUS_INVALID_PARAMETER if invalid parameter found
00188            QSPI_STATUS_ERROR otherwise
00189  */
00190 qspi_status_t qspi_write(qspi_t *obj, const qspi_command_t *command, const void *data, size_t *length);
00191 
00192 /** Send a command (and optionally data) and get the response. Can be used to send/receive device specific commands
00193  *
00194  * @param obj QSPI object
00195  * @param command QSPI command
00196  * @param tx_data TX buffer
00197  * @param tx_size TX buffer length in bytes
00198  * @param rx_data RX buffer
00199  * @param rx_size RX buffer length in bytes
00200  * @return QSPI_STATUS_OK if the data has been succesfully sent
00201            QSPI_STATUS_INVALID_PARAMETER if invalid parameter found
00202            QSPI_STATUS_ERROR otherwise
00203  */
00204 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);
00205 
00206 /** Receive a command and block of data
00207  *
00208  * @param obj QSPI object
00209  * @param command QSPI command
00210  * @param data RX buffer
00211  * @param[in,out] length in - RX buffer length in bytes, out - number of bytes read
00212  * @return QSPI_STATUS_OK if data has been succesfully received
00213            QSPI_STATUS_INVALID_PARAMETER if invalid parameter found
00214            QSPI_STATUS_ERROR otherwise
00215  */
00216 qspi_status_t qspi_read(qspi_t *obj, const qspi_command_t *command, void *data, size_t *length);
00217 
00218 /** Get the pins that support QSPI SCLK
00219  *
00220  * Return a PinMap array of pins that support QSPI SCLK in
00221  * master mode. The array is terminated with {NC, NC, 0}.
00222  *
00223  * @return PinMap array
00224  */
00225 const PinMap *qspi_master_sclk_pinmap(void);
00226 
00227 /** Get the pins that support QSPI SSEL
00228  *
00229  * Return a PinMap array of pins that support QSPI SSEL in
00230  * master mode. The array is terminated with {NC, NC, 0}.
00231  *
00232  * @return PinMap array
00233  */
00234 const PinMap *qspi_master_ssel_pinmap(void);
00235 
00236 /** Get the pins that support QSPI DATA0
00237  *
00238  * Return a PinMap array of pins that support QSPI DATA0 in
00239  * master mode. The array is terminated with {NC, NC, 0}.
00240  *
00241  * @return PinMap array
00242  */
00243 const PinMap *qspi_master_data0_pinmap(void);
00244 
00245 /** Get the pins that support QSPI DATA1
00246  *
00247  * Return a PinMap array of pins that support QSPI DATA1 in
00248  * master mode. The array is terminated with {NC, NC, 0}.
00249  *
00250  * @return PinMap array
00251  */
00252 const PinMap *qspi_master_data1_pinmap(void);
00253 
00254 /** Get the pins that support QSPI DATA2
00255  *
00256  * Return a PinMap array of pins that support QSPI DATA2 in
00257  * master mode. The array is terminated with {NC, NC, 0}.
00258  *
00259  * @return PinMap array
00260  */
00261 const PinMap *qspi_master_data2_pinmap(void);
00262 
00263 /** Get the pins that support QSPI DATA3
00264  *
00265  * Return a PinMap array of pins that support QSPI DATA3 in
00266  * master mode. The array is terminated with {NC, NC, 0}.
00267  *
00268  * @return PinMap array
00269  */
00270 const PinMap *qspi_master_data3_pinmap(void);
00271 
00272 /**@}*/
00273 
00274 #ifdef __cplusplus
00275 }
00276 #endif
00277 
00278 #endif
00279 
00280 #endif
00281 
00282 /** @}*/