1 /*************************************************************************** 2 * Copyright (c) 2024 Microsoft Corporation 3 * 4 * This program and the accompanying materials are made available under the 5 * terms of the MIT License which is available at 6 * https://opensource.org/licenses/MIT. 7 * 8 * SPDX-License-Identifier: MIT 9 **************************************************************************/ 10 11 12 /**************************************************************************/ 13 /**************************************************************************/ 14 /** */ 15 /** LevelX Component */ 16 /** */ 17 /** Application Interface (API) */ 18 /** */ 19 /**************************************************************************/ 20 /**************************************************************************/ 21 22 23 /**************************************************************************/ 24 /* */ 25 /* APPLICATION INTERFACE DEFINITION RELEASE */ 26 /* */ 27 /* lx_api.h PORTABLE C */ 28 /* 6.4.1 */ 29 /* AUTHOR */ 30 /* */ 31 /* William E. Lamie, Microsoft Corporation */ 32 /* */ 33 /* DESCRIPTION */ 34 /* */ 35 /* This file defines the basic Application Interface (API) to the */ 36 /* high-performance LevelX. All service prototypes and data structure */ 37 /* definitions are defined in this file. */ 38 /* */ 39 /* RELEASE HISTORY */ 40 /* */ 41 /* DATE NAME DESCRIPTION */ 42 /* */ 43 /* 05-19-2020 William E. Lamie Initial Version 6.0 */ 44 /* 09-30-2020 William E. Lamie Modified comment(s), and */ 45 /* updated product constants, */ 46 /* resulting in version 6.1 */ 47 /* 11-09-2020 William E. Lamie Modified comment(s), and */ 48 /* added support for lx_user.h */ 49 /* so user can specify values, */ 50 /* resulting in version 6.1.2 */ 51 /* 12-31-2020 William E. Lamie Modified comment(s), and */ 52 /* updated product constants, */ 53 /* resulting in version 6.1.3 */ 54 /* 06-02-2021 Bhupendra Naphade Modified comment(s), */ 55 /* added standalone support, */ 56 /* resulting in version 6.1.7 */ 57 /* 08-02-2021 William E. Lamie Modified comment(s), and */ 58 /* updated product constants, */ 59 /* resulting in version 6.1.8 */ 60 /* 10-15-2021 Bhupendra Naphade Modified comment(s), */ 61 /* updated configuration for */ 62 /* nand flash */ 63 /* resulting in version 6.1.9 */ 64 /* 01-31-2022 Bhupendra Naphade Modified comment(s), */ 65 /* updated include order for */ 66 /* standalone mode, */ 67 /* resulting in version 6.1.10 */ 68 /* 04-25-2022 William E. Lamie Modified comment(s), and */ 69 /* updated product constants, */ 70 /* resulting in version 6.1.11 */ 71 /* 07-29-2022 William E. Lamie Modified comment(s), and */ 72 /* updated product constants, */ 73 /* resulting in version 6.1.12 */ 74 /* 10-31-2022 Xiuwen Cai Modified comment(s), and */ 75 /* updated product constants, */ 76 /* resulting in version 6.2.0 */ 77 /* 03-08-2023 Xiuwen Cai Modified comment(s), */ 78 /* modified NAND logic, */ 79 /* added new driver interface */ 80 /* and user extension, */ 81 /* resulting in version 6.2.1 */ 82 /* 10-31-2023 Xiuwen Cai Modified comment(s), */ 83 /* made LX_NOR_SECTOR_SIZE */ 84 /* configurable, added mapping */ 85 /* bitmap and obsolete count */ 86 /* cache for NOR flash, */ 87 /* resulting in version 6.3.0 */ 88 /* 12-31-2023 Xiuwen Cai Modified comment(s), */ 89 /* added configuration checks, */ 90 /* resulting in version 6.4.0 */ 91 /* 03-01-2024 Tiejun Zhou Modified comment(s), */ 92 /* update version number, */ 93 /* resulting in version 6.4.1 */ 94 /* */ 95 /**************************************************************************/ 96 97 #ifndef LX_API_H 98 #define LX_API_H 99 100 101 /* Determine if a C++ compiler is being used. If so, ensure that standard 102 C is used to process the API information. */ 103 104 #ifdef __cplusplus 105 106 /* Yes, C++ compiler is present. Use standard C. */ 107 extern "C" { 108 109 #endif 110 111 /* Determine if the optional LevelX user define file should be used. */ 112 113 #ifdef LX_INCLUDE_USER_DEFINE_FILE 114 115 116 /* Yes, include the user defines in lx_user.h. The defines in this file may 117 alternately be defined on the command line. */ 118 119 #include "lx_user.h" 120 #endif 121 122 /* Include the ThreadX api file. */ 123 124 #ifndef LX_STANDALONE_ENABLE 125 #include "tx_api.h" 126 #endif 127 128 129 #ifdef LX_STANDALONE_ENABLE 130 131 /* Define compiler library include files. */ 132 133 #include <stdint.h> 134 #include <stdlib.h> 135 #include <string.h> 136 137 #ifndef VOID 138 #define VOID void 139 typedef char CHAR; 140 typedef char BOOL; 141 typedef unsigned char UCHAR; 142 typedef int INT; 143 typedef unsigned int UINT; 144 typedef long LONG; 145 typedef unsigned long ULONG; 146 typedef short SHORT; 147 typedef unsigned short USHORT; 148 #endif 149 150 #ifndef ULONG64_DEFINED 151 #define ULONG64_DEFINED 152 typedef unsigned long long ULONG64; 153 #endif 154 155 /* Define basic alignment type used in block and byte pool operations. This data type must 156 be at least 32-bits in size and also be large enough to hold a pointer type. */ 157 158 #ifndef ALIGN_TYPE_DEFINED 159 #define ALIGN_TYPE_DEFINED 160 #define ALIGN_TYPE ULONG 161 #endif 162 163 /* Define the LX_MEMSET macro to the standard library function, if not already defined. */ 164 #ifndef LX_MEMSET 165 #define LX_MEMSET(a,b,c) memset((a),(b),(c)) 166 #endif 167 168 #ifndef LX_MEMCPY 169 #define LX_MEMCPY(a,b,c) memcpy((a),(b),(c)) 170 #endif 171 172 /* Disable usage of ThreadX mutex in standalone mode */ 173 #ifdef LX_THREAD_SAFE_ENABLE 174 #undef LX_THREAD_SAFE_ENABLE 175 #endif 176 177 #define LX_INTERRUPT_SAVE_AREA 178 #define LX_DISABLE 179 #define LX_RESTORE 180 181 #else 182 183 #define LX_MEMSET TX_MEMSET 184 #ifndef LX_MEMCPY 185 #include <string.h> 186 #define LX_MEMCPY(a,b,c) memcpy((a),(b),(c)) 187 #endif 188 189 #define LX_INTERRUPT_SAVE_AREA TX_INTERRUPT_SAVE_AREA 190 #define LX_DISABLE TX_DISABLE 191 #define LX_RESTORE TX_RESTORE 192 193 #endif 194 195 196 /* Disable warning of parameter not used. */ 197 #ifndef LX_PARAMETER_NOT_USED 198 #define LX_PARAMETER_NOT_USED(p) ((void)(p)) 199 #endif /* LX_PARAMETER_NOT_USED */ 200 201 202 /* Define basic constants for the LevelX Stack. */ 203 #define AZURE_RTOS_LEVELX 204 #define LEVELX_MAJOR_VERSION 6 205 #define LEVELX_MINOR_VERSION 4 206 #define LEVELX_PATCH_VERSION 1 207 208 209 /* Define general LevelX Constants. */ 210 211 #define LX_FALSE 0 212 #define LX_TRUE 1 213 #define LX_NULL 0 214 #define LX_BLOCK_ERASE_COUNT_MASK 0x7FFFFFFF 215 #define LX_BLOCK_ERASE_COUNT_MAX 0x7FFFFFFF 216 #define LX_BLOCK_ERASED 0x80000000 217 #define LX_BLOCK_ERASE_STARTED 0 218 #define LX_ALL_ONES 0xFFFFFFFF 219 220 221 /* Define error codes. */ 222 223 #define LX_SUCCESS 0 224 #define LX_ERROR 1 225 #define LX_NO_SECTORS 2 226 #define LX_SECTOR_NOT_FOUND 3 227 #define LX_NO_PAGES 4 228 #define LX_INVALID_WRITE 5 229 #define LX_NAND_ERROR_CORRECTED 6 230 #define LX_NAND_ERROR_NOT_CORRECTED 7 231 #define LX_NO_MEMORY 8 232 #define LX_DISABLED 9 233 #define LX_BAD_BLOCK 10 234 #define LX_NO_BLOCKS 11 235 #define LX_NOT_SUPPORTED 12 236 #define LX_SYSTEM_INVALID_FORMAT 90 237 #define LX_SYSTEM_INVALID_BLOCK 91 238 #define LX_SYSTEM_ALLOCATION_FAILED 92 239 #define LX_SYSTEM_MUTEX_CREATE_FAILED 93 240 #define LX_SYSTEM_INVALID_SECTOR_MAP 94 241 242 243 /* Define NOR flash constants. */ 244 245 #define LX_NOR_FLASH_OPENED ((ULONG) 0x4E4F524F) 246 #define LX_NOR_FLASH_CLOSED ((ULONG) 0x4E4F5244) 247 #ifndef LX_NOR_SECTOR_SIZE 248 #define LX_NOR_SECTOR_SIZE (512/sizeof(ULONG)) 249 #endif 250 #define LX_NOR_FLASH_MIN_LOGICAL_SECTOR_OFFSET 1 251 #define LX_NOR_FLASH_MAX_LOGICAL_SECTOR_OFFSET 2 252 #ifndef LX_NOR_FLASH_MAX_ERASE_COUNT_DELTA 253 #define LX_NOR_FLASH_MAX_ERASE_COUNT_DELTA 4 254 #endif 255 #define LX_NOR_SECTOR_MAPPING_CACHE_DEPTH 4 256 #ifndef LX_NOR_SECTOR_MAPPING_CACHE_SIZE 257 #define LX_NOR_SECTOR_MAPPING_CACHE_SIZE 16 /* Minimum value of 8, all sizes must be a power of 2. */ 258 #endif 259 #ifndef LX_NOR_EXTENDED_CACHE_SIZE 260 #define LX_NOR_EXTENDED_CACHE_SIZE 8 /* Maximum number of extended cache sectors. */ 261 #endif 262 #ifdef LX_NOR_ENABLE_OBSOLETE_COUNT_CACHE 263 #ifndef LX_NOR_OBSOLETE_COUNT_CACHE_TYPE 264 #define LX_NOR_OBSOLETE_COUNT_CACHE_TYPE UCHAR 265 #endif 266 #endif 267 268 269 /* Define the mask for the hash index into the sector mapping cache table. The sector mapping cache is divided 270 into 4 entry pieces that are indexed by the formula: 271 272 index = (sector & LX_NOR_SECTOR_MAPPING_CACHE_HASH_MASK) * LX_NOR_SECTOR_MAPPING_CACHE_DEPTH 273 274 The LX_NOR_SECTOR_MAPPING_CACHE_DEPTH define must not be changed unless the related source code is also changed. */ 275 276 #define LX_NOR_SECTOR_MAPPING_CACHE_HASH_MASK ((LX_NOR_SECTOR_MAPPING_CACHE_SIZE/LX_NOR_SECTOR_MAPPING_CACHE_DEPTH)-1) 277 #define LX_NOR_SECTOR_MAPPING_CACHE_ENTRY_MASK 0x7FFFFFFF 278 #define LX_NOR_SECTOR_MAPPING_CACHE_ENTRY_VALID 0x80000000 279 280 #define LX_NOR_PHYSICAL_SECTOR_VALID 0x80000000 281 #define LX_NOR_PHYSICAL_SECTOR_SUPERCEDED 0x40000000 282 #define LX_NOR_PHYSICAL_SECTOR_MAPPING_NOT_VALID 0x20000000 283 #define LX_NOR_LOGICAL_SECTOR_MASK 0x1FFFFFFF 284 #define LX_NOR_PHYSICAL_SECTOR_FREE 0xFFFFFFFF 285 286 287 /* Check extended cache configurations. */ 288 #ifdef LX_NOR_DISABLE_EXTENDED_CACHE 289 290 #ifdef LX_NOR_ENABLE_MAPPING_BITMAP 291 #error "To enable mapping bitmap, you need to undefine LX_NOR_DISABLE_EXTENDED_CACHE." 292 #endif 293 294 #ifdef LX_NOR_ENABLE_OBSOLETE_COUNT_CACHE 295 #error "To enable obsolete count cache, you need to undefine LX_NOR_DISABLE_EXTENDED_CACHE." 296 #endif 297 298 #endif 299 300 /* Define NAND flash constants. */ 301 302 #define LX_NAND_GOOD_BLOCK 0xFF 303 #define LX_NAND_BAD_BLOCK 0x00 304 #define LX_NAND_FLASH_OPENED ((ULONG) 0x4E4F524F) 305 #define LX_NAND_FLASH_CLOSED ((ULONG) 0x4E4F5244) 306 #ifndef LX_NAND_FLASH_MAX_ERASE_COUNT_DELTA 307 #define LX_NAND_FLASH_MAX_ERASE_COUNT_DELTA 64 308 #endif 309 310 /* Define the NAND sector mapping cache. */ 311 312 #define LX_NAND_SECTOR_MAPPING_CACHE_DEPTH 4 /* Not required if LX_NAND_FLASH_DIRECT_MAPPING_CACHE is defined. */ 313 #ifndef LX_NAND_SECTOR_MAPPING_CACHE_SIZE 314 #define LX_NAND_SECTOR_MAPPING_CACHE_SIZE 128 /* Minimum value of 8, all sizes must be a power of 2, unless direct 315 mapping is defined, in which there is no power of 2 requirement. */ 316 #endif 317 #ifndef LX_NAND_ERASE_COUNT_WRITE_SIZE 318 #define LX_NAND_ERASE_COUNT_WRITE_SIZE (nand_flash -> lx_nand_flash_pages_per_block + 1) 319 #endif 320 321 #ifndef LX_NAND_FLASH_MAPPING_LIST_UPDATE_DISABLE 322 #define LX_NAND_FLASH_MAPPING_LIST_UPDATE_DISABLE 323 #endif 324 325 #ifndef LX_NAND_FLASH_MAX_METADATA_BLOCKS 326 #define LX_NAND_FLASH_MAX_METADATA_BLOCKS 4 327 #endif 328 329 #ifndef LX_UTILITY_SHORT_SET 330 #define LX_UTILITY_SHORT_SET(address, value) *((USHORT*)(address)) = (USHORT)(value) 331 #endif 332 333 #ifndef LX_UTILITY_LONG_SET 334 #define LX_UTILITY_LONG_SET(address, value) *((ULONG*)(address)) = (ULONG)(value) 335 #endif 336 337 #ifndef LX_UTILITY_SHORT_GET 338 #define LX_UTILITY_SHORT_GET(address) (*((USHORT*)(address))) 339 #endif 340 341 #ifndef LX_UTILITY_LONG_GET 342 #define LX_UTILITY_LONG_GET(address) (*((ULONG*)(address))) 343 #endif 344 345 /* Define the mask for the hash index into the NAND sector mapping cache table. The sector mapping cache is divided 346 into 4 entry pieces that are indexed by the formula: 347 348 index = (sector & LX_NAND_SECTOR_MAPPING_CACHE_HASH_MASK) * LX_NAND_SECTOR_MAPPING_CACHE_DEPTH 349 350 The LX_NAND_SECTOR_MAPPING_CACHE_DEPTH define must not be changed unless the related source code is also changed. */ 351 352 #define LX_NAND_SECTOR_MAPPING_CACHE_HASH_MASK ((LX_NAND_SECTOR_MAPPING_CACHE_SIZE/LX_NAND_SECTOR_MAPPING_CACHE_DEPTH)-1) 353 #define LX_NAND_SECTOR_MAPPING_CACHE_ENTRY_MASK 0x7FFFFFFF 354 #define LX_NAND_SECTOR_MAPPING_CACHE_ENTRY_VALID 0x80000000 355 356 #define LX_NAND_BLOCK_VALID 0x80000000 357 #define LX_NAND_BLOCK_EMPTY 0x40000000 358 #define LX_NAND_BLOCK_FULL 0x20000000 359 #define LX_NAND_PAGE_VALID 0x80000000 360 #define LX_NAND_PAGE_SUPERCEDED 0x40000000 361 #define LX_NAND_PAGE_MAPPING_NOT_VALID 0x20000000 362 #define LX_NAND_LOGICAL_SECTOR_MASK 0x1FFFFFFF 363 #define LX_NAND_PAGE_FREE 0xFFFFFFFF 364 #define LX_NAND_PAGE_LIST_VALID 0xF0F0F0F0 365 366 #define LX_NAND_PAGE_TYPE_DEVICE_INFO 0x10000000u 367 #define LX_NAND_PAGE_TYPE_ERASE_COUNT_TABLE 0x20000000u 368 #define LX_NAND_PAGE_TYPE_BLOCK_MAPPING_TABLE 0x30000000u 369 #define LX_NAND_PAGE_TYPE_USER_DATA 0x40000000u 370 #define LX_NAND_PAGE_TYPE_USER_DATA_RELEASED 0x50000000u 371 #define LX_NAND_PAGE_TYPE_READ_COUNT_TABLE 0x60000000u 372 #define LX_NAND_PAGE_TYPE_PAGE_MAPPING_TABLE 0x70000000u 373 #define LX_NAND_PAGE_TYPE_BLOCK_STATUS_TABLE 0x80000000u 374 #define LX_NAND_PAGE_TYPE_BLOCK_LINK 0x90000000u 375 #define LX_NAND_PAGE_TYPE_USER_DATA_MASK 0x0FFFFFFFu 376 #define LX_NAND_PAGE_TYPE_PAGE_NUMBER_MASK 0x000000FFu 377 378 #define LX_NAND_PAGE_TYPE_FREE_PAGE 0xFFFFFF00u 379 380 #define LX_NAND_BLOCK_STATUS_FULL 0x4000u 381 #define LX_NAND_BLOCK_STATUS_NON_SEQUENTIAL 0x2000u 382 #define LX_NAND_BLOCK_STATUS_MAPPING_PRESENT 0x1000u 383 #define LX_NAND_BLOCK_STATUS_PAGE_NUMBER_MASK 0x0FFFu 384 #define LX_NAND_BLOCK_STATUS_FREE 0xFFFFu 385 #define LX_NAND_BLOCK_STATUS_BAD 0xFF00u 386 #define LX_NAND_BLOCK_STATUS_ALLOCATED 0x8000u 387 388 #define LX_NAND_BLOCK_LINK_MAIN_METADATA_OFFSET 0 389 #define LX_NAND_BLOCK_LINK_BACKUP_METADATA_OFFSET 4 390 391 #define LX_NAND_MAX_BLOCK_COUNT 32768 392 #define LX_NAND_MAX_PAGE_PER_BLOCK 4096 393 394 395 396 #define LX_NAND_BLOCK_UNMAPPED 0xFFFF 397 398 #define LX_NAND_DEVICE_INFO_SIGNATURE1 0x76654C20 399 #define LX_NAND_DEVICE_INFO_SIGNATURE2 0x20586C65 400 401 #define LX_NAND_DEVICE_INFO_METADATA_TYPE_MAIN 0x01 402 #define LX_NAND_DEVICE_INFO_METADATA_TYPE_SECONDARY 0x02 403 404 405 406 407 /* Define the NAND device information structure. This will be set in the spare area. */ 408 409 typedef struct LX_NAND_DEVICE_INFO_STRUCT 410 { 411 ULONG lx_nand_device_info_signature1; 412 ULONG lx_nand_device_info_signature2; 413 ULONG lx_nand_device_info_major_version; 414 ULONG lx_nand_device_info_minor_version; 415 ULONG lx_nand_device_info_patch_version; 416 ULONG lx_nand_device_info_metadata_block_number; 417 ULONG lx_nand_device_info_backup_metadata_block_number; 418 ULONG lx_nand_device_info_base_erase_count; 419 } LX_NAND_DEVICE_INFO; 420 421 422 /* Determine if the flash control block has an extension defined. If not, 423 define the extension to whitespace. */ 424 425 #ifndef LX_NAND_FLASH_USER_EXTENSION 426 #define LX_NAND_FLASH_USER_EXTENSION 427 #endif 428 429 /* Define the NAND flash control block structure. */ 430 431 typedef struct LX_NAND_FLASH_STRUCT 432 { 433 ULONG lx_nand_flash_state; 434 ULONG lx_nand_flash_total_blocks; 435 ULONG lx_nand_flash_pages_per_block; 436 ULONG lx_nand_flash_bytes_per_page; 437 ULONG lx_nand_flash_words_per_block; 438 ULONG lx_nand_flash_words_per_page; 439 ULONG lx_nand_flash_total_pages; 440 441 ULONG lx_nand_flash_bad_blocks; 442 ULONG lx_nand_flash_base_erase_count; 443 444 ULONG lx_nand_flash_page_corrections; 445 ULONG lx_nand_flash_last_block_correction; 446 ULONG lx_nand_flash_last_page_correction; 447 448 USHORT *lx_nand_flash_block_mapping_table; 449 ULONG lx_nand_flash_block_mapping_table_size; 450 USHORT *lx_nand_flash_block_status_table; 451 ULONG lx_nand_flash_block_status_table_size; 452 UCHAR *lx_nand_flash_erase_count_table; 453 ULONG lx_nand_flash_erase_count_table_size; 454 USHORT *lx_nand_flash_block_list; 455 ULONG lx_nand_flash_block_list_size; 456 ULONG lx_nand_flash_free_block_list_tail; 457 ULONG lx_nand_flash_mapped_block_list_head; 458 459 ULONG lx_nand_flash_metadata_block_number; 460 ULONG lx_nand_flash_metadata_block_number_current; 461 ULONG lx_nand_flash_metadata_block_number_next; 462 ULONG lx_nand_flash_metadata_block_current_page; 463 ULONG lx_nand_flash_metadata_block_count; 464 USHORT lx_nand_flash_metadata_block[LX_NAND_FLASH_MAX_METADATA_BLOCKS]; 465 466 ULONG lx_nand_flash_backup_metadata_block_number; 467 ULONG lx_nand_flash_backup_metadata_block_number_current; 468 ULONG lx_nand_flash_backup_metadata_block_number_next; 469 ULONG lx_nand_flash_backup_metadata_block_current_page; 470 USHORT lx_nand_flash_backup_metadata_block[LX_NAND_FLASH_MAX_METADATA_BLOCKS]; 471 472 ULONG lx_nand_flash_spare_data1_offset; 473 ULONG lx_nand_flash_spare_data1_length; 474 ULONG lx_nand_flash_spare_data2_offset; 475 ULONG lx_nand_flash_spare_data2_length; 476 ULONG lx_nand_flash_spare_total_length; 477 478 ULONG lx_nand_flash_diagnostic_system_errors; 479 ULONG lx_nand_flash_diagnostic_system_error; 480 ULONG lx_nand_flash_diagnostic_sector_write_requests; 481 ULONG lx_nand_flash_diagnostic_sector_read_requests; 482 ULONG lx_nand_flash_diagnostic_sector_release_requests; 483 ULONG lx_nand_flash_diagnostic_page_allocates; 484 ULONG lx_nand_flash_diagnostic_page_allocate_errors; 485 486 ULONG lx_nand_flash_diagnostic_block_reclaim_attempts; 487 ULONG lx_nand_flash_diagnostic_block_erases; 488 ULONG lx_nand_flash_diagnostic_block_status_gets; 489 ULONG lx_nand_flash_diagnostic_block_status_sets; 490 ULONG lx_nand_flash_diagnostic_page_extra_bytes_sets; 491 ULONG lx_nand_flash_diagnostic_page_writes; 492 ULONG lx_nand_flash_diagnostic_page_extra_bytes_gets; 493 ULONG lx_nand_flash_diagnostic_page_reads; 494 ULONG lx_nand_flash_diagnostic_moved_pages; 495 ULONG lx_nand_flash_diagnostic_block_erased_verifies; 496 ULONG lx_nand_flash_diagnostic_page_erased_verifies; 497 498 #ifdef LX_NAND_ENABLE_CONTROL_BLOCK_FOR_DRIVER_INTERFACE 499 UINT (*lx_nand_flash_driver_read)(struct LX_NAND_FLASH_STRUCT *nand_flash, ULONG block, ULONG page, ULONG *destination, ULONG words); 500 UINT (*lx_nand_flash_driver_write)(struct LX_NAND_FLASH_STRUCT *nand_flash, ULONG block, ULONG page, ULONG *source, ULONG words); 501 UINT (*lx_nand_flash_driver_block_erase)(struct LX_NAND_FLASH_STRUCT *nand_flash, ULONG block, ULONG erase_count); 502 UINT (*lx_nand_flash_driver_block_erased_verify)(struct LX_NAND_FLASH_STRUCT *nand_flash, ULONG block); 503 UINT (*lx_nand_flash_driver_page_erased_verify)(struct LX_NAND_FLASH_STRUCT *nand_flash, ULONG block, ULONG page); 504 UINT (*lx_nand_flash_driver_block_status_get)(struct LX_NAND_FLASH_STRUCT *nand_flash, ULONG block, UCHAR *bad_block_flag); 505 UINT (*lx_nand_flash_driver_block_status_set)(struct LX_NAND_FLASH_STRUCT *nand_flash, ULONG block, UCHAR bad_block_flag); 506 UINT (*lx_nand_flash_driver_extra_bytes_get)(struct LX_NAND_FLASH_STRUCT *nand_flash, ULONG block, ULONG page, UCHAR *destination, UINT size); 507 UINT (*lx_nand_flash_driver_extra_bytes_set)(struct LX_NAND_FLASH_STRUCT *nand_flash, ULONG block, ULONG page, UCHAR *source, UINT size); 508 UINT (*lx_nand_flash_driver_system_error)(struct LX_NAND_FLASH_STRUCT *nand_flash, UINT error_code, ULONG block, ULONG page); 509 510 UINT (*lx_nand_flash_driver_pages_read)(struct LX_NAND_FLASH_STRUCT *nand_flash, ULONG block, ULONG page, UCHAR* main_buffer, UCHAR* spare_buffer, ULONG pages); 511 UINT (*lx_nand_flash_driver_pages_write)(struct LX_NAND_FLASH_STRUCT *nand_flash, ULONG block, ULONG page, UCHAR* main_buffer, UCHAR* spare_buffer, ULONG pages); 512 UINT (*lx_nand_flash_driver_pages_copy)(struct LX_NAND_FLASH_STRUCT *nand_flash, ULONG source_block, ULONG source_page, ULONG destination_block, ULONG destination_page, ULONG pages, UCHAR* data_buffer); 513 #else 514 UINT (*lx_nand_flash_driver_read)(ULONG block, ULONG page, ULONG *destination, ULONG words); 515 UINT (*lx_nand_flash_driver_write)(ULONG block, ULONG page, ULONG *source, ULONG words); 516 UINT (*lx_nand_flash_driver_block_erase)(ULONG block, ULONG erase_count); 517 UINT (*lx_nand_flash_driver_block_erased_verify)(ULONG block); 518 UINT (*lx_nand_flash_driver_page_erased_verify)(ULONG block, ULONG page); 519 UINT (*lx_nand_flash_driver_block_status_get)(ULONG block, UCHAR *bad_block_flag); 520 UINT (*lx_nand_flash_driver_block_status_set)(ULONG block, UCHAR bad_block_flag); 521 UINT (*lx_nand_flash_driver_extra_bytes_get)(ULONG block, ULONG page, UCHAR *destination, UINT size); 522 UINT (*lx_nand_flash_driver_extra_bytes_set)(ULONG block, ULONG page, UCHAR *source, UINT size); 523 UINT (*lx_nand_flash_driver_system_error)(UINT error_code, ULONG block, ULONG page); 524 525 UINT (*lx_nand_flash_driver_pages_read)(ULONG block, ULONG page, UCHAR* main_buffer, UCHAR* spare_buffer, ULONG pages); 526 UINT (*lx_nand_flash_driver_pages_write)(ULONG block, ULONG page, UCHAR* main_buffer, UCHAR* spare_buffer, ULONG pages); 527 UINT (*lx_nand_flash_driver_pages_copy)(ULONG source_block, ULONG source_page, ULONG destination_block, ULONG destination_page, ULONG pages, UCHAR* data_buffer); 528 #endif 529 UCHAR *lx_nand_flash_page_buffer; 530 UINT lx_nand_flash_page_buffer_size; 531 532 #ifdef LX_THREAD_SAFE_ENABLE 533 534 /* When this conditional is used, the LevelX code utilizes a ThreadX mutex for thread 535 safe operation. Generally, this is not required since FileX ensures thread safe operation at 536 a higher layer. */ 537 TX_MUTEX lx_nand_flash_mutex; 538 #endif 539 540 /* Define the NAND flash control block open next/previous pointers. */ 541 struct LX_NAND_FLASH_STRUCT *lx_nand_flash_open_next, 542 *lx_nand_flash_open_previous; 543 544 /* Define the user extension in the flash control block. This 545 is typically defined in lx_user.h. */ 546 LX_NAND_FLASH_USER_EXTENSION 547 548 } LX_NAND_FLASH; 549 550 551 552 /* Define the NOR flash sector cache entry structure. */ 553 554 typedef struct LX_NOR_SECTOR_MAPPING_CACHE_ENTRY_STRUCT 555 { 556 ULONG lx_nor_sector_mapping_cache_logical_sector; 557 ULONG *lx_nor_sector_mapping_cache_physical_sector_map_entry; 558 ULONG *lx_nor_sector_mapping_cache_physical_sector_address; 559 } LX_NOR_SECTOR_MAPPING_CACHE_ENTRY; 560 561 562 /* Define the NOR flash extended cache entry structure. */ 563 564 typedef struct LX_NOR_FLASH_EXTENDED_CACHE_ENTRY_STRUCT 565 { 566 ULONG *lx_nor_flash_extended_cache_entry_sector_address; 567 ULONG *lx_nor_flash_extended_cache_entry_sector_memory; 568 ULONG lx_nor_flash_extended_cache_entry_access_count; 569 } LX_NOR_FLASH_EXTENDED_CACHE_ENTRY; 570 571 572 /* Determine if the flash control block has an extension defined. If not, 573 define the extension to whitespace. */ 574 575 #ifndef LX_NOR_FLASH_USER_EXTENSION 576 #define LX_NOR_FLASH_USER_EXTENSION 577 #endif 578 579 /* Define the NOR flash control block structure. */ 580 581 typedef struct LX_NOR_FLASH_STRUCT 582 { 583 ULONG lx_nor_flash_state; 584 ULONG lx_nor_flash_total_blocks; 585 ULONG lx_nor_flash_words_per_block; 586 ULONG lx_nor_flash_total_physical_sectors; 587 ULONG lx_nor_flash_physical_sectors_per_block; 588 589 ULONG *lx_nor_flash_base_address; 590 ULONG lx_nor_flash_block_free_bit_map_offset; 591 ULONG lx_nor_flash_block_bit_map_words; 592 ULONG lx_nor_flash_block_bit_map_mask; 593 ULONG lx_nor_flash_block_physical_sector_mapping_offset; 594 ULONG lx_nor_flash_block_physical_sector_offset; 595 596 ULONG lx_nor_flash_free_physical_sectors; 597 ULONG lx_nor_flash_mapped_physical_sectors; 598 ULONG lx_nor_flash_obsolete_physical_sectors; 599 ULONG lx_nor_flash_minimum_erase_count; 600 ULONG lx_nor_flash_minimum_erased_blocks; 601 ULONG lx_nor_flash_maximum_erase_count; 602 603 ULONG lx_nor_flash_free_block_search; 604 ULONG lx_nor_flash_found_block_search; 605 ULONG lx_nor_flash_found_sector_search; 606 607 ULONG lx_nor_flash_write_requests; 608 ULONG lx_nor_flash_read_requests; 609 ULONG lx_nor_flash_sector_mapping_cache_hits; 610 ULONG lx_nor_flash_sector_mapping_cache_misses; 611 ULONG lx_nor_flash_physical_block_allocates; 612 ULONG lx_nor_flash_physical_block_allocate_errors; 613 ULONG lx_nor_flash_diagnostic_system_errors; 614 ULONG lx_nor_flash_diagnostic_system_error; 615 ULONG lx_nor_flash_diagnostic_initial_format; 616 ULONG lx_nor_flash_diagnostic_erased_block; 617 ULONG lx_nor_flash_diagnostic_re_erase_block; 618 ULONG lx_nor_flash_diagnostic_sector_being_obsoleted; 619 ULONG lx_nor_flash_diagnostic_sector_obsoleted; 620 ULONG lx_nor_flash_diagnostic_mapping_invalidated; 621 ULONG lx_nor_flash_diagnostic_mapping_write_interrupted; 622 ULONG lx_nor_flash_diagnostic_sector_not_free; 623 ULONG lx_nor_flash_diagnostic_sector_data_not_free; 624 625 #ifdef LX_NOR_ENABLE_CONTROL_BLOCK_FOR_DRIVER_INTERFACE 626 UINT (*lx_nor_flash_driver_read)(struct LX_NOR_FLASH_STRUCT *nor_flash, ULONG *flash_address, ULONG *destination, ULONG words); 627 UINT (*lx_nor_flash_driver_write)(struct LX_NOR_FLASH_STRUCT *nor_flash, ULONG *flash_address, ULONG *source, ULONG words); 628 UINT (*lx_nor_flash_driver_block_erase)(struct LX_NOR_FLASH_STRUCT *nor_flash, ULONG block, ULONG erase_count); 629 UINT (*lx_nor_flash_driver_block_erased_verify)(struct LX_NOR_FLASH_STRUCT *nor_flash, ULONG block); 630 UINT (*lx_nor_flash_driver_system_error)(struct LX_NOR_FLASH_STRUCT *nor_flash, UINT error_code); 631 #else 632 UINT (*lx_nor_flash_driver_read)(ULONG *flash_address, ULONG *destination, ULONG words); 633 UINT (*lx_nor_flash_driver_write)(ULONG *flash_address, ULONG *source, ULONG words); 634 UINT (*lx_nor_flash_driver_block_erase)(ULONG block, ULONG erase_count); 635 UINT (*lx_nor_flash_driver_block_erased_verify)(ULONG block); 636 UINT (*lx_nor_flash_driver_system_error)(UINT error_code); 637 #endif 638 639 ULONG *lx_nor_flash_sector_buffer; 640 UINT lx_nor_flash_sector_mapping_cache_enabled; 641 LX_NOR_SECTOR_MAPPING_CACHE_ENTRY 642 lx_nor_flash_sector_mapping_cache[LX_NOR_SECTOR_MAPPING_CACHE_SIZE]; 643 644 #ifndef LX_NOR_DISABLE_EXTENDED_CACHE 645 646 UINT lx_nor_flash_extended_cache_entries; 647 LX_NOR_FLASH_EXTENDED_CACHE_ENTRY 648 lx_nor_flash_extended_cache[LX_NOR_EXTENDED_CACHE_SIZE]; 649 ULONG lx_nor_flash_extended_cache_hits; 650 ULONG lx_nor_flash_extended_cache_misses; 651 #ifdef LX_NOR_ENABLE_MAPPING_BITMAP 652 ULONG *lx_nor_flash_extended_cache_mapping_bitmap; 653 ULONG lx_nor_flash_extended_cache_mapping_bitmap_max_logical_sector; 654 #endif 655 #ifdef LX_NOR_ENABLE_OBSOLETE_COUNT_CACHE 656 LX_NOR_OBSOLETE_COUNT_CACHE_TYPE 657 *lx_nor_flash_extended_cache_obsolete_count; 658 ULONG lx_nor_flash_extended_cache_obsolete_count_max_block; 659 #endif 660 #endif 661 662 #ifdef LX_THREAD_SAFE_ENABLE 663 664 /* When this conditional is used, the LevelX code utilizes a ThreadX mutex for thread 665 safe operation. Generally, this is not required since FileX ensures thread safe operation at 666 a higher layer. */ 667 TX_MUTEX lx_nor_flash_mutex; 668 #endif 669 670 /* Define the NOR flash control block open next/previous pointers. */ 671 struct LX_NOR_FLASH_STRUCT *lx_nor_flash_open_next, 672 *lx_nor_flash_open_previous; 673 674 /* Define the user extension in the flash control block. This 675 is typically defined in lx_user.h. */ 676 LX_NOR_FLASH_USER_EXTENSION 677 678 } LX_NOR_FLASH; 679 680 681 /* Each physical NOR block has the following structure at the beginning of the block: 682 683 Offset Meaning 684 685 0 Erase count 686 4 Minimum logical sector number - only when the block is full 687 8 Maximum logical sector number - only when the block is full 688 12 Free physical sector bit map, where a value of 1 indicates a 689 free physical sector. The bit map is evenly divisible by 4 690 . Array of physical sector mapping information (4 bytes per entry, 691 one entry for each physical sector in block). Each entry looks 692 like the following: 693 694 Bit(s) Meaning 695 696 0-29 Logical sector mapped if not 0x3FFFFFFF 697 30 If 0, entry is being superceded 698 31 If 1, entry is valid 699 700 Array of physical sectors, with each of size LX_NOR_SECTOR_SIZE 701 */ 702 703 704 typedef struct LX_NOR_FLASH_BLOCK_HEADER_STRUCT 705 { 706 ULONG lx_nor_flash_block_erase_count; /* Bit 31: 1 -> not used, 0 -> used */ 707 ULONG lx_nor_flash_block_min_logical_sector; /* On full block, minimum valid sector */ 708 ULONG lx_nor_flash_block_max_logical_sector; /* On full block, maximum valid sector */ 709 } LX_NOR_FLASH_BLOCK_HEADER; 710 711 712 /* Define external structure references. */ 713 714 extern LX_NAND_FLASH *_lx_nand_flash_opened_ptr; 715 extern ULONG _lx_nand_flash_opened_count; 716 extern LX_NOR_FLASH *_lx_nor_flash_opened_ptr; 717 extern ULONG _lx_nor_flash_opened_count; 718 719 720 /* Map internal functions. */ 721 722 #ifndef LX_SOURCE_CODE 723 #define lx_nand_flash_close _lx_nand_flash_close 724 #define lx_nand_flash_defragment _lx_nand_flash_defragment 725 #define lx_nand_flash_partial_defragment _lx_nand_flash_partial_defragment 726 #define lx_nand_flash_extended_cache_enable _lx_nand_flash_extended_cache_enable 727 #define lx_nand_flash_format _lx_nand_flash_format 728 #define lx_nand_flash_initialize _lx_nand_flash_initialize 729 #define lx_nand_flash_open _lx_nand_flash_open 730 #define lx_nand_flash_page_ecc_check _lx_nand_flash_page_ecc_check 731 #define lx_nand_flash_page_ecc_compute _lx_nand_flash_page_ecc_compute 732 #define lx_nand_flash_sector_read _lx_nand_flash_sector_read 733 #define lx_nand_flash_sector_release _lx_nand_flash_sector_release 734 #define lx_nand_flash_sector_write _lx_nand_flash_sector_write 735 #define lx_nand_flash_sectors_read _lx_nand_flash_sectors_read 736 #define lx_nand_flash_sectors_release _lx_nand_flash_sectors_release 737 #define lx_nand_flash_sectors_write _lx_nand_flash_sectors_write 738 #define lx_nand_flash_256byte_ecc_check _lx_nand_flash_256byte_ecc_check 739 #define lx_nand_flash_256byte_ecc_compute _lx_nand_flash_256byte_ecc_compute 740 741 #define lx_nor_flash_close _lx_nor_flash_close 742 #define lx_nor_flash_defragment _lx_nor_flash_defragment 743 #define lx_nor_flash_partial_defragment _lx_nor_flash_partial_defragment 744 #define lx_nor_flash_extended_cache_enable _lx_nor_flash_extended_cache_enable 745 #define lx_nor_flash_initialize _lx_nor_flash_initialize 746 #define lx_nor_flash_open _lx_nor_flash_open 747 #define lx_nor_flash_sector_read _lx_nor_flash_sector_read 748 #define lx_nor_flash_sector_release _lx_nor_flash_sector_release 749 #define lx_nor_flash_sector_write _lx_nor_flash_sector_write 750 #endif 751 752 753 /* External LevelX API prototypes. */ 754 755 UINT _lx_nand_flash_close(LX_NAND_FLASH *nand_flash); 756 UINT _lx_nand_flash_defragment(LX_NAND_FLASH *nand_flash); 757 UINT _lx_nand_flash_initialize(void); 758 UINT _lx_nand_flash_extended_cache_enable(LX_NAND_FLASH *nand_flash, VOID *memory, ULONG size); 759 UINT _lx_nand_flash_format(LX_NAND_FLASH* nand_flash, CHAR* name, 760 UINT(*nand_driver_initialize)(LX_NAND_FLASH*), 761 ULONG* memory_ptr, UINT memory_size); 762 UINT _lx_nand_flash_open(LX_NAND_FLASH *nand_flash, CHAR *name, UINT (*nand_driver_initialize)(LX_NAND_FLASH *), ULONG* memory_ptr, UINT memory_size); 763 UINT _lx_nand_flash_page_ecc_check(LX_NAND_FLASH *nand_flash, UCHAR *page_buffer, UCHAR *ecc_buffer); 764 UINT _lx_nand_flash_page_ecc_compute(LX_NAND_FLASH *nand_flash, UCHAR *page_buffer, UCHAR *ecc_buffer); 765 UINT _lx_nand_flash_partial_defragment(LX_NAND_FLASH *nand_flash, UINT max_blocks); 766 UINT _lx_nand_flash_sector_read(LX_NAND_FLASH *nand_flash, ULONG logical_sector, VOID *buffer); 767 UINT _lx_nand_flash_sector_release(LX_NAND_FLASH *nand_flash, ULONG logical_sector); 768 UINT _lx_nand_flash_sector_write(LX_NAND_FLASH *nand_flash, ULONG logical_sector, VOID *buffer); 769 UINT _lx_nand_flash_sectors_read(LX_NAND_FLASH* nand_flash, ULONG logical_sector, VOID* buffer, ULONG sector_count); 770 UINT _lx_nand_flash_sectors_release(LX_NAND_FLASH* nand_flash, ULONG logical_sector, ULONG sector_count); 771 UINT _lx_nand_flash_sectors_write(LX_NAND_FLASH* nand_flash, ULONG logical_sector, VOID* buffer, ULONG sector_count); 772 773 UINT _lx_nor_flash_close(LX_NOR_FLASH *nor_flash); 774 UINT _lx_nor_flash_defragment(LX_NOR_FLASH *nor_flash); 775 UINT _lx_nor_flash_extended_cache_enable(LX_NOR_FLASH *nor_flash, VOID *memory, ULONG size); 776 UINT _lx_nor_flash_initialize(void); 777 UINT _lx_nor_flash_open(LX_NOR_FLASH *nor_flash, CHAR *name, UINT (*nor_driver_initialize)(LX_NOR_FLASH *)); 778 UINT _lx_nor_flash_partial_defragment(LX_NOR_FLASH *nor_flash, UINT max_blocks); 779 UINT _lx_nor_flash_sector_read(LX_NOR_FLASH *nor_flash, ULONG logical_sector, VOID *buffer); 780 UINT _lx_nor_flash_sector_release(LX_NOR_FLASH *nor_flash, ULONG logical_sector); 781 UINT _lx_nor_flash_sector_write(LX_NOR_FLASH *nor_flash, ULONG logical_sector, VOID *buffer); 782 783 784 /* Internal LevelX prototypes. */ 785 786 UINT _lx_nand_flash_driver_block_erase(LX_NAND_FLASH *nand_flash, ULONG block, ULONG erase_count); 787 UINT _lx_nand_flash_driver_block_erased_verify(LX_NAND_FLASH *nand_flash, ULONG block); 788 UINT _lx_nand_flash_driver_page_erased_verify(LX_NAND_FLASH *nand_flash, ULONG block, ULONG page); 789 UINT _lx_nand_flash_driver_block_status_get(LX_NAND_FLASH *nand_flash, ULONG block, UCHAR *bad_block_flag); 790 UINT _lx_nand_flash_driver_block_status_set(LX_NAND_FLASH *nand_flash, ULONG block, UCHAR bad_block_flag); 791 792 VOID _lx_nand_flash_internal_error(LX_NAND_FLASH *nand_flash, ULONG error_code); 793 UINT _lx_nand_flash_block_find(LX_NAND_FLASH *nand_flash, ULONG logical_sector, ULONG *block, USHORT *block_status); 794 UINT _lx_nand_flash_block_allocate(LX_NAND_FLASH *nand_flash, ULONG *block); 795 UINT _lx_nand_flash_block_data_move(LX_NAND_FLASH* nand_flash, ULONG new_block); 796 UINT _lx_nand_flash_block_status_set(LX_NAND_FLASH *nand_flash, ULONG block, ULONG block_status); 797 UINT _lx_nand_flash_erase_count_set(LX_NAND_FLASH* nand_flash, ULONG block, UCHAR erase_count); 798 UINT _lx_nand_flash_block_mapping_set(LX_NAND_FLASH* nand_flash, ULONG logical_sector, ULONG block); 799 UINT _lx_nand_flash_data_page_copy(LX_NAND_FLASH* nand_flash, ULONG logical_sector, ULONG source_block, USHORT src_block_status, 800 ULONG destination_block, USHORT* dest_block_status_ptr, ULONG sectors); 801 UINT _lx_nand_flash_free_block_list_add(LX_NAND_FLASH* nand_flash, ULONG block); 802 UINT _lx_nand_flash_mapped_block_list_add(LX_NAND_FLASH* nand_flash, ULONG block_mapping_index); 803 UINT _lx_nand_flash_mapped_block_list_get(LX_NAND_FLASH* nand_flash, ULONG *block_mapping_index); 804 UINT _lx_nand_flash_mapped_block_list_remove(LX_NAND_FLASH* nand_flash, ULONG block_mapping_index); 805 UINT _lx_nand_flash_memory_initialize(LX_NAND_FLASH* nand_flash, ULONG* memory_ptr, UINT memory_size); 806 UINT _lx_nand_flash_metadata_allocate(LX_NAND_FLASH* nand_flash); 807 UINT _lx_nand_flash_metadata_build(LX_NAND_FLASH* nand_flash); 808 UINT _lx_nand_flash_metadata_write(LX_NAND_FLASH *nand_flash, UCHAR* main_buffer, ULONG spare_value); 809 VOID _lx_nand_flash_system_error(LX_NAND_FLASH *nand_flash, UINT error_code, ULONG block, ULONG page); 810 UINT _lx_nand_flash_256byte_ecc_check(UCHAR *page_buffer, UCHAR *ecc_buffer); 811 UINT _lx_nand_flash_256byte_ecc_compute(UCHAR *page_buffer, UCHAR *ecc_buffer); 812 813 UINT _lx_nor_flash_block_reclaim(LX_NOR_FLASH *nor_flash); 814 UINT _lx_nor_flash_driver_block_erase(LX_NOR_FLASH *nor_flash, ULONG block, ULONG erase_count); 815 UINT _lx_nor_flash_driver_read(LX_NOR_FLASH *nor_flash, ULONG *flash_address, ULONG *destination, ULONG words); 816 UINT _lx_nor_flash_driver_write(LX_NOR_FLASH *nor_flash, ULONG *flash_address, ULONG *source, ULONG words); 817 VOID _lx_nor_flash_internal_error(LX_NOR_FLASH *nor_flash, ULONG error_code); 818 UINT _lx_nor_flash_logical_sector_find(LX_NOR_FLASH *nor_flash, ULONG logical_sector, ULONG superceded_check, ULONG **physical_sector_map_entry, ULONG **physical_sector_address); 819 UINT _lx_nor_flash_next_block_to_erase_find(LX_NOR_FLASH *nor_flash, ULONG *return_erase_block, ULONG *return_erase_count, ULONG *return_mapped_sectors, ULONG *return_obsolete_sectors); 820 UINT _lx_nor_flash_physical_sector_allocate(LX_NOR_FLASH *nor_flash, ULONG logical_sector, ULONG **physical_sector_map_entry, ULONG **physical_sector_address); 821 VOID _lx_nor_flash_sector_mapping_cache_invalidate(LX_NOR_FLASH *nor_flash, ULONG logical_sector); 822 VOID _lx_nor_flash_system_error(LX_NOR_FLASH *nor_flash, UINT error_code); 823 824 825 #ifdef __cplusplus 826 } 827 #endif 828 829 #endif 830 831
