mbed library sources. Supersedes mbed-src.

Dependents:   Nucleo_Hello_Encoder BLE_iBeaconScan AM1805_DEMO DISCO-F429ZI_ExportTemplate1 ... more

Embed: (wiki syntax)

« Back to documentation index

Show/hide line numbers qspi_api.h Source File

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