2eeaa4394d2fb5bdf757961ca819d3b0029b2d07
1 /*
2 * Copyright (c) 2016-2020, Texas Instruments Incorporated
3 * All rights reserved.
4 *
5 * Redistribution and use in source and binary forms, with or without
6 * modification, are permitted provided that the following conditions
7 * are met:
8 *
9 * * Redistributions of source code must retain the above copyright
10 * notice, this list of conditions and the following disclaimer.
11 *
12 * * Redistributions in binary form must reproduce the above copyright
13 * notice, this list of conditions and the following disclaimer in the
14 * documentation and/or other materials provided with the distribution.
15 *
16 * * Neither the name of Texas Instruments Incorporated nor the names of
17 * its contributors may be used to endorse or promote products derived
18 * from this software without specific prior written permission.
19 *
20 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
21 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
22 * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
23 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
24 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
25 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
26 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
27 * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
28 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
29 * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
30 * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
31 */
33 #ifndef BOARD_FLASH_H_
34 #define BOARD_FLASH_H_
36 #ifdef __cplusplus
37 extern "C" {
38 #endif
40 #include <stdbool.h>
41 #include <ti/csl/tistdtypes.h>
43 #if defined(BOARD_NOR_FLASH_IN)
44 #include <ti/board/src/flash/nor/nor.h>
45 #elif defined (BOARD_NAND_FLASH_IN)
46 #include <ti/board/src/flash/nand/nand.h>
47 #else
48 #endif
50 /**
51 *
52 * \ingroup BOARD_LIB_MODULE
53 *
54 * \defgroup BOARD_LIB_FLASH Board Flash Library
55 *
56 * Provides access to different flash devices.
57 *
58 * @{
59 *
60 */
61 /* @} */
63 /**
64 * \ingroup BOARD_LIB_FLASH
65 * @defgroup BOARD_LIB_FLASH_TYPES Data Types
66 */
67 /*@{*/
69 /**
70 * @brief This type defines the opaque handle returned to a flash device that is opened.
71 * The handle must be used in all subsequent operations.
72 *
73 */
74 typedef uintptr_t Board_flashHandle;
76 /**
77 * Error codes used by Board flash functions. Negative values are errors,
78 * while positive values indicate success.
79 */
80 typedef int32_t Board_flash_STATUS; /** Board Flash API return type */
82 #define BOARD_FLASH_EINVALID -3 /**< Error code for invalid parameters */
83 #define BOARD_FLASH_EUNSUPPORTED -2 /**< Error code for unsupported feature */
84 #define BOARD_FLASH_EFAIL -1 /**< General failure code */
85 #define BOARD_FLASH_EOK 0 /**< General success code */
87 /**
88 * @brief Device Identifiers. These are used in the Open call to allow access to a specific
89 * memory device.
90 *
91 */
92 #define BOARD_FLASH_ID_MT29F1G08ABCHC 0x2CA1 /**< 128MB NAND Flash */
93 #define BOARD_FLASH_ID_NAND512R3A2D 0x2036 /**< 64MB NAND Flash */
94 #define BOARD_FLASH_ID_MT29F4G08ABADA 0x2CDC /**< 512MB NAND Flash */
95 #define BOARD_FLASH_ID_MT29F16G08ADBCAH4C 0x2CA5 /**< 16Gb,1.8v,x8 */
96 #define BOARD_FLASH_ID_MT29F2G16ABAFA 0x2CCA /**< 2Gb, x16, 3.3V */
97 #define BOARD_FLASH_ID_NORN25Q128 0xBB18 /**< 16MB NOR Flash */
98 #define BOARD_FLASH_ID_NORN25Q128A13ESF40F 0xBA18 /**< 16MB, 3.3v NOR Flash */
99 #define BOARD_FLASH_ID_W25X32VSFIG 0x4016 /**< w25x32 SPI Flash Device ID */
100 #define BOARD_FLASH_ID_NORN25Q032A 0xBB16 /**< 4MB NOR Flash */
101 #define BOARD_FLASH_ID_EEPROM50 0x50 /**< EEPROM @ slave address 0x50 */
102 #define BOARD_FLASH_ID_EEPROM51 0x51 /**< EEPROM @ slave address 0x51 */
103 #define BOARD_FLASH_ID_EMMC 0xFF00 /**< eMMC device Id */
104 #define BOARD_FLASH_ID_SD 0xFF01 /**< Micro SD device Id */
105 #define BOARD_FLASH_ID_QSPIFLASH_S25FL512S 0x0220 /**< QSPI flash device Id - S25FL512S*/
106 #define BOARD_FLASH_ID_QSPIFLASH_S25FL256S 0x0219 /**< QSPI flash device Id - S25FL256S */
107 #define BOARD_FLASH_ID_S25FL512S (0x0220U) /**< Spansion 64MB NOR flash */
108 #define BOARD_FLASH_ID_S25FL256S (0x0219U) /**< Spansion 32MB NOR flash */
109 #define BOARD_FLASH_ID_MT29W160EB (0x2249U) /**< Micron 2MB NOR flash */
110 #define BOARD_FLASH_ID_MT29F4G08ABAEAWP (0xDC90U) /**< Micron 512MB NAND flash */
111 #if defined(SIM_BUILD)
112 #define BOARD_FLASH_ID_MT35XU512ABA1G12 (0x5B1AU) /**< J7 VLAB SIM flash ID */
113 #define BOARD_FLASH_ID_MT35XU256ABA1G12 (0x5B1AU) /**< AM64x VLAB SIM flash ID */
114 #else
115 #define BOARD_FLASH_ID_MT35XU512ABA1G12 (0x5B1AU) /**< Micro 512Mb NOR flash device Id */
116 #define BOARD_FLASH_ID_MT35XU256ABA1G12 (0x5B19U) /**< Micro 256Mb NOR flash device Id */
117 #endif
118 #define BOARD_FLASH_ID_MT25QU512ABB (0xBB20) /**< 64MB NOR Flash */
119 #define BOARD_FLASH_ID_S71KS512S (0x007EU) /**< 512 Mb cypress Hyperflash device Id */
120 #define BOARD_FLASH_ID_S28HS512T (0x5B1AU) /**< 512 Mb Cypress OSPI NOR flash */
121 #define BOARD_FLASH_ID_MX25V1635F (0x2315U) /** Macronix 16Mbit NOR Flash **/
122 #define BOARD_FLASH_ID_GD25B16CSAG (0x4015U) /** Giga device 16Mbit NOR Flash **/
123 #define BOARD_FLASH_ID_GD25B64CW2G (0x4017U) /** Giga device 16Mbit NOR Flash **/
124 #define BOARD_FLASH_ID_W25Q80VSFIG (0x4014U) /** Winbond flash model on QT **/
126 /**
127 * @brief Board specific Flash Device Identifiers.
128 *
129 */
130 #if defined(evmK2H) || defined(evmK2K) || defined(evmK2E) || defined(evmK2L) || defined(evmK2G) || defined(evmC6678) || defined(evmC6657) || defined(iceK2G)
131 #if defined(evmK2G) || defined(iceK2G)
132 #define BOARD_FLASH_DEV_ID BOARD_FLASH_ID_NORN25Q128A13ESF40F
133 #else
134 #define BOARD_FLASH_DEV_ID BOARD_FLASH_ID_NORN25Q128
135 #endif
136 #endif
138 #if defined(evmOMAPL137)
139 #define BOARD_FLASH_DEV_ID BOARD_FLASH_ID_W25X32VSFIG
140 #endif
143 /**
144 * @brief Indicates the type of NOR flash peripheral
145 *
146 */
147 typedef enum {
148 BOARD_FLASH_NOR_SPI = 0,
149 /**<NOR SPI peripheral interface */
150 BOARD_FLASH_NOR_QSPI,
151 /**<NOR QSPI peripheral interface */
152 BOARD_FLASH_NOR_GPMC,
153 /**<NOR GPMC peripheral interface */
154 BOARD_FLASH_NOR_OSPI,
155 /**<NOR GPMC peripheral interface */
156 BOARD_FLASH_NOR_HPF,
157 /**<NOR HyperBus peripheral interface */
158 BOARD_FLASH_NOR_INTF_MAX
159 /**<End of NOR peripheral interface */
160 } Board_flashNorPeriType;
162 /**
163 * @brief Indicates the type of NAND flash peripheral
164 *
165 */
166 typedef enum {
167 BOARD_FLASH_NAND_GPMC = 0,
168 /**<NAND GPMC peripheral interface */
169 BOARD_FLASH_NAND_EMIF16,
170 /**<NAND EMIF16 peripheral interface */
171 BOARD_FLASH_NAND_INTF_MAX
172 /**<End of NAND peripheral interface */
173 } Board_flashNandPeriType;
175 /**
176 * @brief Indicates the type of device
177 *
178 */
179 typedef enum {
180 BOARD_FLASH_NAND,
181 /**<NAND Flash*/
182 BOARD_FLASH_NOR,
183 /**<NOR Flash*/
184 BOARD_FLASH_EEPROM,
185 /**<EEPROM */
186 BOARD_FLASH_SD,
187 /**<SD Card*/
188 BOARD_FLASH_EMMC,
189 /**<eMMC Card*/
190 BOARD_FLASH_QSPI_FLASH,
191 /**<QSPI flash */
192 BOARD_FLASH_MAX
193 /**<End of devices*/
194 } Board_flashType;
196 /**
197 * @brief Options to set qspi flash read/write access mode
198 */
199 typedef enum {
200 BOARD_FLASH_QSPI_IO_MODE_SINGLE,
201 /**< QSPI flash read/write access on single I/O line */
202 BOARD_FLASH_QSPI_IO_MODE_DUAL,
203 /**< QSPI flash read/write access on two I/O lines */
204 BOARD_FLASH_QSPI_IO_MODE_QUAD
205 /**< QSPI flash read/write access on four I/O lines */
206 } Board_flashQspiIoMode;
208 /**
209 * @brief This structure contains information about the flash device on the board
210 *
211 * The bblist points to an array of bytes where each position represents a
212 * block on the device. If the block is good it is marked as 0xFF. If the block
213 * is bad, it is marked as 0x00. For devices that do not support a bad block list this
214 * value will be NULL. The number of blocks in the bblist is determined by the block_count field.
215 */
216 typedef struct
217 {
218 uint32_t flashHandle;
219 /**<Handle to the flash interface as returned by flash init function */
220 int32_t manufacturer_id;
221 /**<manufacturer ID*/
222 int32_t device_id;
223 /**<Manufacturers device ID*/
224 Board_flashType type;
225 /**<Type of device */
226 int32_t width;
227 /**<Width in bits*/
228 int32_t block_count;
229 /**<Total blocks. First block starts at 0. */
230 int32_t page_count;
231 /**<Page count per block*/
232 int32_t page_size;
233 /**<Number of bytes in a page */
234 int32_t spare_size;
235 /**<Spare area size in bytes*/
236 int32_t bboffset;
237 /**<Offset into spare area to check for a bad block */
238 uint32_t column;
239 /**<Column for a NAND device */
240 uint8_t *bblist;
241 /** <Bad Block list or NULL if device does not support one */
242 uint32_t sector_size;
243 /**<Number of bytes in a sector */
244 bool blkErase_flag;
245 /**<Flag to be set false for Sector Erase and true for Block Erase */
246 } Board_FlashInfo;
248 /**
249 * @brief Maximum Board flash instance number that can be opened.
250 */
251 #define MAX_BOARD_FLASH_INSTANCE_NUM 8
253 /* @} */
255 /**
256 * \ingroup BOARD_LIB_FLASH
257 * @defgroup BOARD_LIB_FLASH_API Application Interfaces
258 */
259 /*@{*/
260 /**************************************************************************
261 ** API function Prototypes
262 **************************************************************************/
264 /**
265 * @brief Opens a flash device for use
266 *
267 * @param[in] deviceId Flash device ID to open
268 * @param[in] portNum Peripheral port number attached to the flash device
269 * @param[in] params configuration parameters for the peripheral interface
270 *
271 * @retval NULL or Board_flashHandle.
272 *
273 * @remark
274 * On success a handle is returned in which should be used in
275 * all subsequent calls. As of now, the devices are not virtualized and only
276 * one open may exist at a time for a particular device.
277 *
278 */
279 Board_flashHandle Board_flashOpen(uint32_t deviceId,
280 uint32_t portNum,
281 void *params);
283 /**
284 * @brief Closes the device
285 *
286 * @param[in] handle Handle to the device as returned in the open call.
287 *
288 * @retval BOARD_FLASH_EOK on Success
289 *
290 */
291 Board_flash_STATUS Board_flashClose (Board_flashHandle handle);
293 /**
294 * @brief Reads a page from the device
295 *
296 * @param[in] handle Flash device handle from the open
297 * @param[in] offset Offset to start the read from
298 * @param[in] buf Pointer to a buffer to read the data into
299 * @param[in] len Amount of data to read
300 * @param[in] params Pointer to read configuration parameters
301 * for QSPI NOR, *params is used to set
302 * the Board_flashQspiIoMode
303 *
304 *
305 * @retval BOARD_FLASH_EOK on Success
306 *
307 * @remark The buffer size should be page_size + spare_size
308 * The application should not write into the spare area
309 *
310 */
311 Board_flash_STATUS Board_flashRead(Board_flashHandle handle,
312 uint32_t offset,
313 uint8_t *buf,
314 uint32_t len,
315 void *params);
317 /**
318 * @brief Write the data to the device
319 *
320 * @param[in] handle Handle to the device as returned by open
321 * @param[in] offset Offset to start writing the data at.
322 * @param[in] buf Pointer to data to write
323 * @param[in] len Length of the data pointed to by buf
324 * @param[in] params Pointer to write configuration parameters
325 * for QSPI NOR, *params is used to set
326 * the Board_flashQspiIoMode
327 *
328 * @retval BOARD_FLASH_EOK on Success
329 *
330 */
331 Board_flash_STATUS Board_flashWrite(Board_flashHandle handle,
332 uint32_t offset,
333 uint8_t *buf,
334 uint32_t len,
335 void *params);
337 /**
338 * @brief Convert the block and page number to offset
339 *
340 * @param[in] handle Handle to the device as returned by open
341 * @param[in] offset Offset to start writing the data at.
342 * @param[in] block Block number
343 * @param[in] page Page number
344 *
345 * @retval BOARD_FLASH_EOK on Success
346 *
347 *
348 */
349 Board_flash_STATUS Board_flashBlkPageToOffset(Board_flashHandle handle,
350 uint32_t *offset,
351 uint32_t block,
352 uint32_t page);
355 /**
356 * @brief Convert the offset to block and page number
357 *
358 * @param[in] handle Handle to the device as returned by open
359 *
360 * @param[in] offset Offset to start writing the data at.
361 *
362 * @param[in] block Pointer to the block number
363 *
364 * @param[in] page Pointer to the Page number
365 *
366 * @retval BOARD_FLASH_EOK on Success
367 *
368 *
369 */
370 Board_flash_STATUS Board_flashOffsetToBlkPage(Board_flashHandle handle,
371 uint32_t offset,
372 uint32_t *block,
373 uint32_t *page);
375 /**
376 * @brief Convert the offset to sector and page number
377 *
378 * @param[in] handle Handle to the device as returned by open
379 *
380 * @param[in] offset Offset to start writing the data at.
381 *
382 * @param[in] sector Pointer to the sector number
383 *
384 * @param[in] page Pointer to the Page number
385 *
386 * @param[in] hybridSector_flag Flag to enable Hybrid Sector Erase
387 *
388 * @retval BOARD_FLASH_EOK on Success
389 *
390 *
391 */
392 Board_flash_STATUS Board_flashOffsetToSectorPage(Board_flashHandle handle,
393 uint32_t offset,
394 uint32_t *sector,
395 uint32_t *page,
396 bool hybridSector_flag);
398 /**
399 * @brief erase a block on the flash block
400 *
401 * @param[in] handle Flash device handle from the open
402 *
403 * @param[in] block_number Block ID to erase
404 *
405 * @retval BOARD_FLASH_EOK on Success
406 *
407 */
408 Board_flash_STATUS Board_flashEraseBlk(Board_flashHandle handle,
409 uint32_t block_number);
412 #ifdef __cplusplus
413 }
414 #endif
416 #endif
418 /* @} */