Skip to content

Commit dd23abe

Browse files
facchinmfacchinm
committed
h33: add qspi includes
Former-commit-id: 3781453
1 parent 50ce5d0 commit dd23abe

File tree

3 files changed

+530
-0
lines changed

3 files changed

+530
-0
lines changed

‎variants/PORTENTA_H33/includes/ra/fsp/inc/api/r_spi_flash_api.h

+353
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,353 @@
1+
/***********************************************************************************************************************
2+
* Copyright [2020-2022] Renesas Electronics Corporation and/or its affiliates. All Rights Reserved.
3+
*
4+
* This software and documentation are supplied by Renesas Electronics America Inc. and may only be used with products
5+
* of Renesas Electronics Corp. and its affiliates ("Renesas"). No other uses are authorized. Renesas products are
6+
* sold pursuant to Renesas terms and conditions of sale. Purchasers are solely responsible for the selection and use
7+
* of Renesas products and Renesas assumes no liability. No license, express or implied, to any intellectual property
8+
* right is granted by Renesas. This software is protected under all applicable laws, including copyright laws. Renesas
9+
* reserves the right to change or discontinue this software and/or this documentation. THE SOFTWARE AND DOCUMENTATION
10+
* IS DELIVERED TO YOU "AS IS," AND RENESAS MAKES NO REPRESENTATIONS OR WARRANTIES, AND TO THE FULLEST EXTENT
11+
* PERMISSIBLE UNDER APPLICABLE LAW, DISCLAIMS ALL WARRANTIES, WHETHER EXPLICITLY OR IMPLICITLY, INCLUDING WARRANTIES
12+
* OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT, WITH RESPECT TO THE SOFTWARE OR
13+
* DOCUMENTATION. RENESAS SHALL HAVE NO LIABILITY ARISING OUT OF ANY SECURITY VULNERABILITY OR BREACH. TO THE MAXIMUM
14+
* EXTENT PERMITTED BY LAW, IN NO EVENT WILL RENESAS BE LIABLE TO YOU IN CONNECTION WITH THE SOFTWARE OR DOCUMENTATION
15+
* (OR ANY PERSON OR ENTITY CLAIMING RIGHTS DERIVED FROM YOU) FOR ANY LOSS, DAMAGES, OR CLAIMS WHATSOEVER, INCLUDING,
16+
* WITHOUT LIMITATION, ANY DIRECT, CONSEQUENTIAL, SPECIAL, INDIRECT, PUNITIVE, OR INCIDENTAL DAMAGES; ANY LOST PROFITS,
17+
* OTHER ECONOMIC DAMAGE, PROPERTY DAMAGE, OR PERSONAL INJURY; AND EVEN IF RENESAS HAS BEEN ADVISED OF THE POSSIBILITY
18+
* OF SUCH LOSS, DAMAGES, CLAIMS OR COSTS.
19+
**********************************************************************************************************************/
20+
21+
/*******************************************************************************************************************//**
22+
* @ingroup RENESAS_INTERFACES
23+
* @defgroup SPI_FLASH_API SPI Flash Interface
24+
* @brief Interface for accessing external SPI flash devices.
25+
*
26+
* @section SPI_FLASH_API_SUMMARY Summary
27+
* The SPI flash API provides an interface that configures, writes, and erases sectors in SPI flash devices.
28+
*
29+
* Implemented by:
30+
* - @ref OSPI
31+
* - @ref QSPI
32+
* @{
33+
**********************************************************************************************************************/
34+
35+
#ifndef R_SPI_FLASH_API_H
36+
#define R_SPI_FLASH_API_H
37+
38+
/***********************************************************************************************************************
39+
* Includes
40+
**********************************************************************************************************************/
41+
42+
/* Register definitions, common services and error codes. */
43+
#include "bsp_api.h"
44+
45+
/* Common macro for FSP header files. There is also a corresponding FSP_FOOTER macro at the end of this file. */
46+
FSP_HEADER
47+
48+
/**********************************************************************************************************************
49+
* Macro definitions
50+
**********************************************************************************************************************/
51+
52+
#define SPI_FLASH_ERASE_SIZE_CHIP_ERASE (UINT32_MAX)
53+
54+
/**********************************************************************************************************************
55+
* Typedef definitions
56+
**********************************************************************************************************************/
57+
58+
/** Read mode. */
59+
typedef enum e_spi_flash_read_mode
60+
{
61+
SPI_FLASH_READ_MODE_STANDARD = 0, ///< Standard Read Mode (no dummy cycles)
62+
SPI_FLASH_READ_MODE_FAST_READ = 1, ///< Fast Read Mode (dummy cycles between address and data)
63+
SPI_FLASH_READ_MODE_FAST_READ_DUAL_OUTPUT = 2, ///< Fast Read Dual Output Mode (data on 2 lines)
64+
SPI_FLASH_READ_MODE_FAST_READ_DUAL_IO = 3, ///< Fast Read Dual I/O Mode (address and data on 2 lines)
65+
SPI_FLASH_READ_MODE_FAST_READ_QUAD_OUTPUT = 4, ///< Fast Read Quad Output Mode (data on 4 lines)
66+
SPI_FLASH_READ_MODE_FAST_READ_QUAD_IO = 5, ///< Fast Read Quad I/O Mode (address and data on 4 lines)
67+
} spi_flash_read_mode_t;
68+
69+
/** SPI protocol. */
70+
typedef enum e_spi_flash_protocol
71+
{
72+
SPI_FLASH_PROTOCOL_EXTENDED_SPI = 0, ///< Extended SPI mode (commands on 1 line)
73+
74+
/** QPI mode (commands on 4 lines). Note that the application must ensure the device is in QPI mode. */
75+
SPI_FLASH_PROTOCOL_QPI = 2,
76+
77+
/** SOPI mode (command and data on 8 lines). Note that the application must ensure the device is in SOPI mode. */
78+
SPI_FLASH_PROTOCOL_SOPI = 3,
79+
80+
/** DOPI mode (command and data on 8 lines, dual data rate). Note that the application must ensure the device is in DOPI mode. */
81+
SPI_FLASH_PROTOCOL_DOPI = 4,
82+
} spi_flash_protocol_t;
83+
84+
/** Number of bytes in the address. */
85+
typedef enum e_spi_flash_address_bytes
86+
{
87+
SPI_FLASH_ADDRESS_BYTES_3 = 2, ///< 3 address bytes
88+
89+
/** 4 address bytes with standard commands. If this option is selected, the application must issue the EN4B
90+
* command using @ref spi_flash_api_t::directWrite() if required by the device. */
91+
SPI_FLASH_ADDRESS_BYTES_4 = 3,
92+
93+
/** 4 address bytes using standard 4-byte command set. */
94+
SPI_FLASH_ADDRESS_BYTES_4_4BYTE_READ_CODE = 0x13,
95+
} spi_flash_address_bytes_t;
96+
97+
/** Number of data lines used. */
98+
typedef enum e_spi_flash_data_lines
99+
{
100+
SPI_FLASH_DATA_LINES_1 = 0, ///< 1 data line
101+
SPI_FLASH_DATA_LINES_2 = 1, ///< 2 data lines
102+
SPI_FLASH_DATA_LINES_4 = 2, ///< 4 data lines
103+
} spi_flash_data_lines_t;
104+
105+
/** Number of dummy cycles for fast read operations. */
106+
typedef enum e_spi_flash_dummy_clocks
107+
{
108+
/** Default is 6 clocks for Fast Read Quad I/O, 4 clocks for Fast Read Dual I/O, and 8 clocks for other
109+
* fast read instructions including Fast Read Quad Output, Fast Read Dual Output, and Fast Read. */
110+
SPI_FLASH_DUMMY_CLOCKS_DEFAULT,
111+
SPI_FLASH_DUMMY_CLOCKS_3, ///< 3 dummy clocks
112+
SPI_FLASH_DUMMY_CLOCKS_4, ///< 4 dummy clocks
113+
SPI_FLASH_DUMMY_CLOCKS_5, ///< 5 dummy clocks
114+
SPI_FLASH_DUMMY_CLOCKS_6, ///< 6 dummy clocks
115+
SPI_FLASH_DUMMY_CLOCKS_7, ///< 7 dummy clocks
116+
SPI_FLASH_DUMMY_CLOCKS_8, ///< 8 dummy clocks
117+
SPI_FLASH_DUMMY_CLOCKS_9, ///< 9 dummy clocks
118+
SPI_FLASH_DUMMY_CLOCKS_10, ///< 10 dummy clocks
119+
SPI_FLASH_DUMMY_CLOCKS_11, ///< 11 dummy clocks
120+
SPI_FLASH_DUMMY_CLOCKS_12, ///< 12 dummy clocks
121+
SPI_FLASH_DUMMY_CLOCKS_13, ///< 13 dummy clocks
122+
SPI_FLASH_DUMMY_CLOCKS_14, ///< 14 dummy clocks
123+
SPI_FLASH_DUMMY_CLOCKS_15, ///< 15 dummy clocks
124+
SPI_FLASH_DUMMY_CLOCKS_16, ///< 16 dummy clocks
125+
SPI_FLASH_DUMMY_CLOCKS_17, ///< 17 dummy clocks
126+
} spi_flash_dummy_clocks_t;
127+
128+
/** Direct Read and Write direction */
129+
typedef enum e_spi_flash_direct_transfer_dir_option
130+
{
131+
SPI_FLASH_DIRECT_TRANSFER_DIR_READ = 0x0,
132+
SPI_FLASH_DIRECT_TRANSFER_DIR_WRITE = 0x1
133+
} spi_flash_direct_transfer_dir_t;
134+
135+
/** Structure to define an erase command and associated erase size. */
136+
typedef struct st_spi_flash_erase_command
137+
{
138+
uint16_t command; ///< Erase command
139+
uint32_t size; ///< Size of erase for associated command, set to SPI_FLASH_ERASE_SIZE_CHIP_ERASE for chip erase
140+
} spi_flash_erase_command_t;
141+
142+
/** Structure to define a direct transfer. */
143+
typedef struct st_spi_flash_direct_transfer
144+
{
145+
uint32_t address; ///< Starting address
146+
uint32_t data; ///< Data
147+
uint16_t command; ///< Transfer command
148+
uint8_t dummy_cycles; ///< Number of dummy cycles
149+
uint8_t command_length; ///< Command length
150+
uint8_t address_length; ///< Address lengrh
151+
uint8_t data_length; ///< Data length
152+
} spi_flash_direct_transfer_t;
153+
154+
/** User configuration structure used by the open function */
155+
typedef struct st_spi_flash_cfg
156+
{
157+
spi_flash_protocol_t spi_protocol; ///< Initial SPI protocol. SPI protocol can be changed in @ref spi_flash_api_t::spiProtocolSet.
158+
spi_flash_read_mode_t read_mode; ///< Read mode
159+
spi_flash_address_bytes_t address_bytes; ///< Number of bytes used to represent the address
160+
spi_flash_dummy_clocks_t dummy_clocks; ///< Number of dummy clocks to use for fast read operations
161+
162+
/** Number of lines used to send address for page program command. This should either be 1 or match the number of lines used in
163+
* the selected read mode. */
164+
spi_flash_data_lines_t page_program_address_lines;
165+
uint8_t write_status_bit; ///< Which bit determines write status
166+
uint8_t write_enable_bit; ///< Which bit determines write status
167+
uint32_t page_size_bytes; ///< Page size in bytes (maximum number of bytes for page program). Used to specify single continuous write size (bytes) in case of OSPI RAM.
168+
uint8_t page_program_command; ///< Page program command
169+
uint8_t write_enable_command; ///< Command to enable write or erase, typically 0x06
170+
uint8_t status_command; ///< Command to read the write status
171+
uint8_t read_command; ///< Read command - OSPI SPI mode only
172+
uint8_t xip_enter_command; ///< Command to enter XIP mode
173+
uint8_t xip_exit_command; ///< Command to exit XIP mode
174+
uint8_t erase_command_list_length; ///< Length of erase command list
175+
spi_flash_erase_command_t const * p_erase_command_list; ///< List of all erase commands and associated sizes
176+
void const * p_extend; ///< Pointer to implementation specific extended configurations
177+
} spi_flash_cfg_t;
178+
179+
/** SPI flash control block. Allocate an instance specific control block to pass into the SPI flash API calls.
180+
* @par Implemented as
181+
* - qspi_instance_ctrl_t
182+
* - ospi_instance_ctrl_t
183+
*/
184+
typedef void spi_flash_ctrl_t;
185+
186+
/** Status. */
187+
typedef struct st_spi_flash_status
188+
{
189+
/** Whether or not a write is in progress. This is determined by reading the @ref spi_flash_cfg_t::write_status_bit
190+
* from the @ref spi_flash_cfg_t::status_command. */
191+
bool write_in_progress;
192+
} spi_flash_status_t;
193+
194+
/** SPI flash implementations follow this API. */
195+
typedef struct st_spi_flash_api
196+
{
197+
/** Open the SPI flash driver module.
198+
* @par Implemented as
199+
* - @ref R_OSPI_Open()
200+
* - @ref R_QSPI_Open()
201+
*
202+
* @param[in] p_ctrl Pointer to a driver handle
203+
* @param[in] p_cfg Pointer to a configuration structure
204+
**/
205+
fsp_err_t (* open)(spi_flash_ctrl_t * p_ctrl, spi_flash_cfg_t const * const p_cfg);
206+
207+
/** Write raw data to the SPI flash.
208+
* @par Implemented as
209+
* - @ref R_OSPI_DirectWrite()
210+
* - @ref R_QSPI_DirectWrite()
211+
*
212+
* @param[in] p_ctrl Pointer to a driver handle
213+
* @param[in] p_src Pointer to raw data to write, must include any required command/address
214+
* @param[in] bytes Number of bytes to write
215+
* @param[in] read_after_write If true, the slave select remains asserted and the peripheral does not return
216+
* to direct communications mode. If false, the slave select is deasserted and
217+
* memory mapped access is possible after this function returns if the device
218+
* is not busy.
219+
**/
220+
fsp_err_t (* directWrite)(spi_flash_ctrl_t * p_ctrl, uint8_t const * const p_src, uint32_t const bytes,
221+
bool const read_after_write);
222+
223+
/** Read raw data from the SPI flash. Must follow a call to @ref spi_flash_api_t::directWrite.
224+
* @par Implemented as
225+
* - @ref R_OSPI_DirectRead()
226+
* - @ref R_QSPI_DirectRead()
227+
*
228+
* @param[in] p_ctrl Pointer to a driver handle
229+
* @param[out] p_dest Pointer to read raw data into
230+
* @param[in] bytes Number of bytes to read
231+
**/
232+
fsp_err_t (* directRead)(spi_flash_ctrl_t * p_ctrl, uint8_t * const p_dest, uint32_t const bytes);
233+
234+
/** Direct Read/Write raw data to the SPI flash.
235+
* @par Implemented as
236+
* - @ref R_OSPI_DirectTransfer()
237+
* - @ref R_QSPI_DirectTransfer()
238+
*
239+
* @param[in] p_ctrl Pointer to a driver handle
240+
* @param[in] p_data Pointer to command, address and data values and lengths
241+
* @param[in] direction Direct Read/Write
242+
**/
243+
fsp_err_t (* directTransfer)(spi_flash_ctrl_t * p_ctrl, spi_flash_direct_transfer_t * const p_transfer,
244+
spi_flash_direct_transfer_dir_t direction);
245+
246+
/** Change the SPI protocol in the driver. The application must change the SPI protocol on the device.
247+
* @par Implemented as
248+
* - @ref R_OSPI_SpiProtocolSet()
249+
* - @ref R_QSPI_SpiProtocolSet()
250+
*
251+
* @param[in] p_ctrl Pointer to a driver handle
252+
* @param[in] spi_protocol Desired SPI protocol
253+
**/
254+
fsp_err_t (* spiProtocolSet)(spi_flash_ctrl_t * p_ctrl, spi_flash_protocol_t spi_protocol);
255+
256+
/** Program a page of data to the flash.
257+
* @par Implemented as
258+
* - @ref R_OSPI_Write()
259+
* - @ref R_QSPI_Write()
260+
*
261+
* @param[in] p_ctrl Pointer to a driver handle
262+
* @param[in] p_src The memory address of the data to write to the flash device
263+
* @param[in] p_dest The location in the flash device address space to write the data to
264+
* @param[in] byte_count The number of bytes to write
265+
**/
266+
fsp_err_t (* write)(spi_flash_ctrl_t * p_ctrl, uint8_t const * const p_src, uint8_t * const p_dest,
267+
uint32_t byte_count);
268+
269+
/** Erase a certain number of bytes of the flash.
270+
* @par Implemented as
271+
* - @ref R_OSPI_Erase()
272+
* - @ref R_QSPI_Erase()
273+
*
274+
* @param[in] p_ctrl Pointer to a driver handle
275+
* @param[in] p_device_address The location in the flash device address space to start the erase from
276+
* @param[in] byte_count The number of bytes to erase. Set to SPI_FLASH_ERASE_SIZE_CHIP_ERASE to erase entire
277+
* chip.
278+
**/
279+
fsp_err_t (* erase)(spi_flash_ctrl_t * p_ctrl, uint8_t * const p_device_address, uint32_t byte_count);
280+
281+
/** Get the write or erase status of the flash.
282+
* @par Implemented as
283+
* - @ref R_OSPI_StatusGet()
284+
* - @ref R_QSPI_StatusGet()
285+
*
286+
* @param[in] p_ctrl Pointer to a driver handle
287+
* @param[out] p_status Current status of the SPI flash device stored here.
288+
**/
289+
fsp_err_t (* statusGet)(spi_flash_ctrl_t * p_ctrl, spi_flash_status_t * const p_status);
290+
291+
/** Enter XIP mode.
292+
* @par Implemented as
293+
* - @ref R_OSPI_XipEnter()
294+
* - @ref R_QSPI_XipEnter()
295+
*
296+
* @param[in] p_ctrl Pointer to a driver handle
297+
**/
298+
fsp_err_t (* xipEnter)(spi_flash_ctrl_t * p_ctrl);
299+
300+
/** Exit XIP mode.
301+
* @par Implemented as
302+
* - @ref R_OSPI_XipExit()
303+
* - @ref R_QSPI_XipExit()
304+
*
305+
* @param[in] p_ctrl Pointer to a driver handle
306+
**/
307+
fsp_err_t (* xipExit)(spi_flash_ctrl_t * p_ctrl);
308+
309+
/** Select the bank to access. See implementation for details.
310+
* @par Implemented as
311+
* - @ref R_OSPI_BankSet()
312+
* - @ref R_QSPI_BankSet()
313+
*
314+
* @param[in] p_ctrl Pointer to a driver handle
315+
* @param[in] bank The bank number
316+
**/
317+
fsp_err_t (* bankSet)(spi_flash_ctrl_t * p_ctrl, uint32_t bank);
318+
319+
/** AutoCalibrate the SPI flash driver module. Expected to be used when auto-calibrating OSPI RAM device.
320+
* @par Implemented as
321+
* - @ref R_OSPI_AutoCalibrate()
322+
* - @ref R_QSPI_AutoCalibrate()
323+
*
324+
* @param[in] p_ctrl Pointer to a driver handle
325+
**/
326+
fsp_err_t (* autoCalibrate)(spi_flash_ctrl_t * p_ctrl);
327+
328+
/** Close the SPI flash driver module.
329+
* @par Implemented as
330+
* - @ref R_OSPI_Close()
331+
* - @ref R_QSPI_Close()
332+
*
333+
* @param[in] p_ctrl Pointer to a driver handle
334+
**/
335+
fsp_err_t (* close)(spi_flash_ctrl_t * p_ctrl);
336+
} spi_flash_api_t;
337+
338+
/** This structure encompasses everything that is needed to use an instance of this interface. */
339+
typedef struct st_spi_flash_instance
340+
{
341+
spi_flash_ctrl_t * p_ctrl; ///< Pointer to the control structure for this instance
342+
spi_flash_cfg_t const * p_cfg; ///< Pointer to the configuration structure for this instance
343+
spi_flash_api_t const * p_api; ///< Pointer to the API structure for this instance
344+
} spi_flash_instance_t;
345+
346+
/* Common macro for FSP header files. There is also a corresponding FSP_HEADER macro at the top of this file. */
347+
FSP_FOOTER
348+
349+
#endif
350+
351+
/*******************************************************************************************************************//**
352+
* @} (end addtogroup SPI_FLASH_API)
353+
**********************************************************************************************************************/

0 commit comments

Comments
 (0)