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