qspi_api.h

00001 
00002 /** \addtogroup hal */
00003 /** @{*/
00004 /* mbed Microcontroller Library
00005  * Copyright (c) 2017 ARM Limited
00006  *
00007  * Licensed under the Apache License, Version 2.0 (the "License");
00008  * you may not use this file except in compliance with the License.
00009  * You may obtain a copy of the License at
00010  *
00011  *     http://www.apache.org/licenses/LICENSE-2.0
00012  *
00013  * Unless required by applicable law or agreed to in writing, software
00014  * distributed under the License is distributed on an "AS IS" BASIS,
00015  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00016  * See the License for the specific language governing permissions and
00017  * limitations under the License.
00018  */
00019 #ifndef MBED_QSPI_API_H
00020 #define MBED_QSPI_API_H
00021 
00022 #include "device.h"
00023 #include <stdbool.h>
00024 
00025 #if DEVICE_QSPI
00026 
00027 #ifdef __cplusplus
00028 extern "C" {
00029 #endif
00030 
00031 /**
00032  * \defgroup hal_qspi QSPI HAL
00033  * @{
00034  */
00035 
00036 /** QSPI HAL object
00037  */
00038 typedef struct qspi_s qspi_t;
00039 
00040 /** QSPI Bus width
00041  *
00042  * Some parts of commands provide variable bus width
00043  */
00044 typedef enum qspi_bus_width {
00045     QSPI_CFG_BUS_SINGLE,
00046     QSPI_CFG_BUS_DUAL,
00047     QSPI_CFG_BUS_QUAD,
00048 } qspi_bus_width_t;
00049 
00050 /** Address size in bits
00051  */
00052 typedef enum qspi_address_size {
00053     QSPI_CFG_ADDR_SIZE_8,
00054     QSPI_CFG_ADDR_SIZE_16,
00055     QSPI_CFG_ADDR_SIZE_24,
00056     QSPI_CFG_ADDR_SIZE_32,
00057 } qspi_address_size_t;
00058 
00059 /** Alternative size in bits
00060  */
00061 typedef enum qspi_alt_size {
00062     QSPI_CFG_ALT_SIZE_8,
00063     QSPI_CFG_ALT_SIZE_16,
00064     QSPI_CFG_ALT_SIZE_24,
00065     QSPI_CFG_ALT_SIZE_32,
00066 } qspi_alt_size_t;
00067 
00068 /** QSPI command
00069  *
00070  * Defines a frame format. It consists of instruction, address, alternative, dummy count and data
00071  */
00072 typedef struct qspi_command {
00073     struct {
00074         qspi_bus_width_t bus_width; /**< Bus width for the instruction >*/
00075         uint8_t value;  /**< Instruction value >*/
00076         bool disabled; /**< Instruction phase skipped if disabled is set to true >*/
00077     } instruction;
00078     struct {
00079         qspi_bus_width_t bus_width; /**< Bus width for the address >*/
00080         qspi_address_size_t size; /**< Address size >*/
00081         uint32_t value; /**< Address value >*/
00082         bool disabled; /**< Address phase skipped if disabled is set to true >*/
00083     }  address;
00084     struct {
00085         qspi_bus_width_t bus_width; /**< Bus width for alternative  >*/
00086         qspi_alt_size_t size; /**< Alternative size >*/
00087         uint32_t value; /**< Alternative value >*/
00088         bool disabled; /**< Alternative phase skipped if disabled is set to true >*/
00089     } alt;
00090     uint8_t dummy_count; /**< Dummy cycles count >*/
00091     struct {
00092         qspi_bus_width_t bus_width; /**< Bus width for data >*/
00093     } data;
00094 } qspi_command_t;
00095 
00096 /** QSPI return status
00097  */
00098 typedef enum qspi_status {
00099     QSPI_STATUS_ERROR = -1, /**< Generic error >*/
00100     QSPI_STATUS_INVALID_PARAMETER = -2, /**< The parameter is invalid >*/
00101     QSPI_STATUS_OK    =  0, /**< Function executed sucessfully  >*/
00102 } qspi_status_t;
00103 
00104 /** Initialize QSPI peripheral.
00105  *
00106  * 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
00107  *
00108  * @param obj QSPI object
00109  * @param io0 Data pin 0
00110  * @param io1 Data pin 1
00111  * @param io2 Data pin 2
00112  * @param io3 Data pin 3
00113  * @param sclk The clock pin
00114  * @param ssel The chip select pin
00115  * @param hz The bus frequency
00116  * @param mode Clock polarity and phase mode (0 - 3)
00117  * @return QSPI_STATUS_OK if initialisation successfully executed
00118            QSPI_STATUS_INVALID_PARAMETER if invalid parameter found
00119            QSPI_STATUS_ERROR otherwise
00120  */
00121 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);
00122 
00123 /** Deinitilize QSPI peripheral
00124  *
00125  * It should release pins that are associated with the QSPI object, and disable clocks for QSPI peripheral module that was associated with the object
00126  *
00127  * @param obj QSPI object
00128  * @return QSPI_STATUS_OK if deinitialisation successfully executed
00129            QSPI_STATUS_INVALID_PARAMETER if invalid parameter found
00130            QSPI_STATUS_ERROR otherwise
00131  */
00132 qspi_status_t qspi_free(qspi_t *obj);
00133 
00134 /** Set the QSPI baud rate
00135  *
00136  * Actual frequency may differ from the desired frequency due to available dividers and the bus clock
00137  * Configures the QSPI peripheral's baud rate
00138  * @param obj The SPI object to configure
00139  * @param hz  The baud rate in Hz
00140  * @return QSPI_STATUS_OK if frequency was set
00141            QSPI_STATUS_INVALID_PARAMETER if invalid parameter found
00142            QSPI_STATUS_ERROR otherwise
00143  */
00144 qspi_status_t qspi_frequency(qspi_t *obj, int hz);
00145 
00146 /** Send a command and block of data
00147  *
00148  * @param obj QSPI object
00149  * @param command QSPI command
00150  * @param data TX buffer
00151  * @param[in,out] length in - TX buffer length in bytes, out - number of bytes written
00152  * @return QSPI_STATUS_OK if the data has been succesfully sent
00153            QSPI_STATUS_INVALID_PARAMETER if invalid parameter found
00154            QSPI_STATUS_ERROR otherwise
00155  */
00156 qspi_status_t qspi_write(qspi_t *obj, const qspi_command_t *command, const void *data, size_t *length);
00157 
00158 /** Send a command (and optionally data) and get the response. Can be used to send/receive device specific commands
00159  *
00160  * @param obj QSPI object
00161  * @param command QSPI command
00162  * @param tx_data TX buffer
00163  * @param tx_size TX buffer length in bytes
00164  * @param rx_data RX buffer
00165  * @param rx_size RX buffer length in bytes
00166  * @return QSPI_STATUS_OK if the data has been succesfully sent
00167            QSPI_STATUS_INVALID_PARAMETER if invalid parameter found
00168            QSPI_STATUS_ERROR otherwise
00169  */
00170 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);
00171 
00172 /** Receive a command and block of data
00173  *
00174  * @param obj QSPI object
00175  * @param command QSPI command
00176  * @param data RX buffer
00177  * @param[in,out] length in - RX buffer length in bytes, out - number of bytes read
00178  * @return QSPI_STATUS_OK if data has been succesfully received
00179            QSPI_STATUS_INVALID_PARAMETER if invalid parameter found
00180            QSPI_STATUS_ERROR otherwise
00181  */
00182 qspi_status_t qspi_read(qspi_t *obj, const qspi_command_t *command, void *data, size_t *length);
00183 
00184 /**@}*/
00185 
00186 #ifdef __cplusplus
00187 }
00188 #endif
00189 
00190 #endif
00191 
00192 #endif
00193 
00194 /** @}*/