9512.net
甜梦文库
当前位置:首页 >> >>

1 Intel Flash File System Core Introduction...............................................


Intel? Flash File System Core Reference Guide
Version 1
October 2004

304436-001

This Intel? Flash File System Core Reference Guide, version 6 as well as the software described in it is furnished under license and may only be used or copied in accordance with the terms of the license. The information in this manual is furnished for informational use only, is subject to change without notice, and should not be construed as a commitment by Intel Corporation. Intel Corporation assumes no responsibility or liability for any errors or inaccuracies that may appear in this document or any software that may be provided in association with this document. Except as permitted by such license, no part of this document may be reproduced, stored in a retrieval system, or transmitted in any form or by any means without the express written consent of Intel Corporation. Contact your local Intel sales office or your distributor to obtain the latest specifications and before placing your product order. Copies of documents which have an ordering number and are referenced in this document, or other Intel literature may be obtained by calling 1-800548-4725 or by visiting Intel's website at http://www.intel.com. Copyright ? Intel Corporation, 2004. *Other names and brands may be claimed as the property of others

2

Intel? Flash File System Core Reference Guide

Contents

Contents
1 Intel? Flash File System Core Introduction.................................................................................9 1.1 1.2 1.3 2 2.1 2.2 2.3 Where Do I Start? .................................................................................................................9 Document Purpose and Scope .............................................................................................9 Terminology ........................................................................................................................10 Architecture Model..............................................................................................................11 Theory of Operation ............................................................................................................12 System Overview ................................................................................................................13 2.3.1 Real-Time Operating System (RTOS) Wrapper Interface .....................................13 2.3.2 Flash File System Core Components ....................................................................13 2.3.2.1 File System Layer ..................................................................................13 2.3.2.2 Data Objects Layer ................................................................................13 2.3.2.3 The Basic Allocation Layer ....................................................................13 2.3.2.4 Reclaim Module .....................................................................................14 2.3.2.5 Flash Interface Layer .............................................................................14 2.3.3 Low-Level Layer ....................................................................................................14 Data Flow............................................................................................................................14 Power Loss Recovery (PLR) ..............................................................................................17 2.5.1 PLR Status Definitions ...........................................................................................17 2.5.2 Initialization for PLR ...............................................................................................18 2.5.2.1 PLR Testing Strategy.............................................................................19 Architecture Benefits...........................................................................................................19 2.6.1 Performance ..........................................................................................................19 2.6.2 Transactions ..........................................................................................................19 2.6.3 Portability and Operating System Support.............................................................19 Functionality........................................................................................................................22 Other Component Dependency/Inter-Relationship .............................................................22 Requirements and Constraints ...........................................................................................22 FS_CheckFileExists............................................................................................................24 FS_CheckFileOpen ............................................................................................................25 FS_CloseFileDir..................................................................................................................27 FS_Commit.........................................................................................................................28 FS_CommitCancel..............................................................................................................29 FS_DeleteFileDir ................................................................................................................30 FS_FindComplete ...............................................................................................................31 FS_FindFileDir ....................................................................................................................32 FS_GetFileDirInfo ...............................................................................................................34 FS_GetVolumeInfo .............................................................................................................35 FS_Init ................................................................................................................................36 FS_IOCTL...........................................................................................................................37 FS_MoveFileDir ..................................................................................................................38 FS_OpenFileDir ..................................................................................................................39

Architecture .................................................................................................................................11

2.4 2.5

2.6

3

File System Layer ........................................................................................................................21 3.1 3.2 3.3

4

File System API Reference .........................................................................................................23 4.1 4.2 4.3 4.4 4.5 4.6 4.7 4.8 4.9 4.10 4.11 4.12 4.13 4.14

Intel? Flash File System Core Reference Guide

3

Contents

4.15 4.16 4.17 4.18 4.19 4.20 4.21 5

FS_ReadFileDir .................................................................................................................. 42 FS_SetFileDirInfo ............................................................................................................... 44 FS_SetFileOffset ................................................................................................................ 46 FS_SetFileSize ................................................................................................................... 48 FS_Shutdown ..................................................................................................................... 50 FS_WriteFile ....................................................................................................................... 51 Error Codes ........................................................................................................................ 53

Data Objects Layer ...................................................................................................................... 57 5.1 5.2 5.3 Functionality........................................................................................................................ 58 Other Component Dependency/Inter-Relationship............................................................. 58 Requirements and Constraints ........................................................................................... 58 DO_AllocateDataObject...................................................................................................... 61 DO_CalculateReserveSpace.............................................................................................. 62 DO_CheckAvailableSpaceForObjects................................................................................ 63 DO_DeleteDataObject ........................................................................................................ 64 DO_FindNextObject............................................................................................................ 65 DO_GetObjectInfo .............................................................................................................. 66 DO_GetDataObjectSize...................................................................................................... 67 DO_GetSeqTableInfo ......................................................................................................... 68 DO_GetVolumeInfo ............................................................................................................ 69 DO_Init................................................................................................................................ 70 DO_InvalidateDataObject ................................................................................................... 71 DO_InvalidateNewData ...................................................................................................... 72 DO_IsSizeMatched............................................................................................................. 73 DO_ModifyDataObject........................................................................................................ 74 DO_PLRDataRecovery....................................................................................................... 75 DO_PLRInvalidateNewData ............................................................................................... 76 DO_PLRTruncateDataObject ............................................................................................. 77 DO_PLRTruncateRecovery ................................................................................................ 78 DO_ReadDataObject.......................................................................................................... 79 DO_Shutdown .................................................................................................................... 80 DO_TruncateDataObject .................................................................................................... 81 DO_ValidateDataObject ..................................................................................................... 82 DO_ValidateNewData......................................................................................................... 83 DO_WriteDataObject .......................................................................................................... 84 Using the Write-Related Data Objects API ......................................................................... 86 6.25.1 Creating Dynamic Information (Static Information)................................................ 86 6.25.2 Creating a Directory............................................................................................... 86 6.25.3 Adding One Entry to a Directory With a Free Entry ............................................... 86 6.25.4 Adding One Entry to a Directory With No Free Entry ............................................ 86 6.25.5 Writing File Data .................................................................................................... 86 6.25.6 Compile Time Options ........................................................................................... 86 Error Codes ........................................................................................................................ 87 Functionality........................................................................................................................ 90 7.1.1 Application Program Interface (BA_API) ............................................................... 92 7.1.2 Logical Volume (BA_LV)........................................................................................ 92

6

Data Objects API Reference ....................................................................................................... 59 6.1 6.2 6.3 6.4 6.5 6.6 6.7 6.8 6.9 6.10 6.11 6.12 6.13 6.14 6.15 6.16 6.17 6.18 6.19 6.20 6.21 6.22 6.23 6.24 6.25

6.26 7 7.1

Basic Allocation Layer ................................................................................................................ 89

4

Intel? Flash File System Core Reference Guide

Contents

7.2 7.3 8 8.1 8.2 8.3 8.4 8.5 8.6 8.7 8.8 8.9 8.10 8.11 8.12 8.13 8.14 8.15 8.16 9 9.1 9.2

Logical Block (BA_LB) ...........................................................................................92 Physical Block (BA_PB).........................................................................................94 7.1.4.1 PB_VolumeInfo ......................................................................................95 7.1.4.2 PB_PhysicalBlockInfo ............................................................................96 7.1.4.3 PB_LogicalBlockInfo ..............................................................................97 7.1.4.4 PB_ReclaimBlockInfo ............................................................................98 7.1.4.5 PB_BlockInfo .........................................................................................99 7.1.5 typedef enum PB_Status ..................................................................................... 100 7.1.6 Logical Unit (BA_LU) ........................................................................................... 101 7.1.7 Flash Interface (BA_FI)........................................................................................102 7.1.8 EDAC (BA_EDAC)............................................................................................... 102 Basic Allocation Layer Interface ....................................................................................... 103 Other Component Dependency/Inter-Relationship ........................................................... 103 BA_AllocateUnit................................................................................................................ 107 BA_CopyUnitData.............................................................................................................108 BA_FindNextUnit ..............................................................................................................109 BA_GetUnitsAvailable ...................................................................................................... 110 BA_GetUnitInfo ................................................................................................................. 111 BA_GetUnitsInvalid........................................................................................................... 112 BA_GetUnitsTotal .............................................................................................................113 BA_Init .............................................................................................................................. 114 BA_InvalidateUnit .............................................................................................................115 BA_ModifyUnitData .......................................................................................................... 116 BA_ReadUnitData ............................................................................................................ 117 BA_ReplaceUnitData ........................................................................................................ 118 BA_Shutdown ................................................................................................................... 120 BA_ValidateUnit................................................................................................................ 121 BA_WriteUnitData.............................................................................................................122 Error Codes ...................................................................................................................... 123 Reclaim Module Functionality ........................................................................................... 126 9.1.1 RIP Write .............................................................................................................127 Reclaim Process ............................................................................................................... 128 9.2.1 RC_StateIdle (Reclaim State 0)........................................................................... 128 9.2.2 RC_StateSelecting (Reclaim State 1)..................................................................128 9.2.3 RC_StateRelocating (Reclaim State 2)................................................................ 128 9.2.4 RC_StateErasing (Reclaim State 3) .................................................................... 129 9.2.5 RC_StateUpdating (Reclaim State 4) ..................................................................130 External Resources Required ........................................................................................... 130 Other Component Dependency/Inter-Relationship ........................................................... 130 Requirements and Constraints .........................................................................................131 RC_GetReclaimState ....................................................................................................... 134 RC_Init.............................................................................................................................. 135 RC_PowerLossRecovery.................................................................................................. 136 RC_ReclaimBackground .................................................................................................. 137 RC_ReclaimBlock .............................................................................................................138

7.1.3 7.1.4

Basic Allocation API Reference ............................................................................................... 105

Reclaim Module .........................................................................................................................125

9.3 9.4 9.5 10 10.1 10.2 10.3 10.4 10.5

Reclaim Module API Reference ................................................................................................ 133

Intel? Flash File System Core Reference Guide

5

Contents

10.6 10.7 10.8 10.9 10.10 11 11.1 11.2 11.3 12 12.1 12.2 12.3 12.4 12.5 12.6 13 13.1 13.2 13.3 13.4 13.5 13.6 14 14.1 14.2 14.3 14.4

RC_ReclaimInProgress .................................................................................................... 139 RC_ReclaimVolume ......................................................................................................... 140 RC_Shutdown................................................................................................................... 141 RC_SimulatePowerLoss................................................................................................... 142 Error Codes ...................................................................................................................... 143 Functionality...................................................................................................................... 146 Other Component Dependency/Inter-Relationship........................................................... 146 Requirements and Constraints ......................................................................................... 146 FLASH_Erase................................................................................................................... 148 FLASH_Init ....................................................................................................................... 149 FLASH_Read.................................................................................................................... 150 FLASH_Shutdown ............................................................................................................ 151 FLASH_Write.................................................................................................................... 152 Error Codes ...................................................................................................................... 153 Functionality...................................................................................................................... 156 External Resources Required........................................................................................... 156 Externally Visible Attributes .............................................................................................. 156 External Interfaces............................................................................................................ 156 Other Component Dependency/Inter-Relationship........................................................... 157 Requirements and Constraints ......................................................................................... 157 Low-Level Layer Overview ............................................................................................... 159 FlashArray and FlashDevice Structures ........................................................................... 160 FlashArray and FlashDevice Initialization......................................................................... 163 FlashArray API Functions ................................................................................................. 165 14.4.1 Erase ................................................................................................................... 166 14.4.2 Lock ..................................................................................................................... 171 14.4.3 Lockdown............................................................................................................. 176 14.4.4 Read .................................................................................................................... 181 14.4.5 ReadLockStatus .................................................................................................. 186 14.4.6 ReadProtReg ....................................................................................................... 191 14.4.7 Unlock.................................................................................................................. 195 14.4.8 Write .................................................................................................................... 200 14.4.9 WriteProtReg ....................................................................................................... 205 FlashDevice API Functions............................................................................................... 209 14.5.1 Erase ................................................................................................................... 210 14.5.2 Lock ..................................................................................................................... 218 14.5.3 Lockdown............................................................................................................. 221 14.5.4 Read .................................................................................................................... 224 14.5.5 ReadLockStatus .................................................................................................. 227 14.5.6 ReadProtReg (Not Supported) ............................................................................ 230 14.5.7 Unlock.................................................................................................................. 231 14.5.8 Write .................................................................................................................... 234 14.5.9 WriteProtReg (Not Supported)............................................................................. 246

Flash Interface Layer................................................................................................................. 145

Flash Interface API Reference .................................................................................................. 147

Low-Level Layer ........................................................................................................................ 155

Low-Level API Reference.......................................................................................................... 159

14.5

6

Intel? Flash File System Core Reference Guide

Contents

14.6 15

Error Codes ...................................................................................................................... 247

API Structures, Defines, and Enumerations ........................................................................... 249 15.1 Basic Allocation ................................................................................................................ 249 15.1.1 BA_InitInfo ........................................................................................................... 249 15.1.2 BA_UnitLocation .................................................................................................. 250 15.1.3 BA_UnitStatus typedef enum............................................................................... 251 15.1.4 BA_UnitType typedef enum ................................................................................. 251 File System ....................................................................................................................... 253 15.2.1 FFS_Entry............................................................................................................ 253 15.2.2 FFS_Format......................................................................................................... 254 15.2.3 FFS_Options........................................................................................................ 254 15.2.4 FFS_VolumeInfo .................................................................................................. 255 15.2.5 FS_Class typedef enum ...................................................................................... 256 15.2.6 FS_FileDirInfo ...................................................................................................... 257 15.2.7 FS_OpenFileInfo.................................................................................................. 258 15.2.8 FS_FindMode #Defines ....................................................................................... 261 15.2.9 FS_OpenMode #Defines ..................................................................................... 261 15.2.10 FS_AccessMode #Defines .................................................................................. 262 15.2.11 FS_IOCMD #Defines ........................................................................................... 262 15.2.12 FS_RamBufferMode #Defines .............................................................................262 15.2.13 FS_SearchHandle #Defines ................................................................................ 263 15.2.14 FS_SeekMode #Defines ...................................................................................... 263 15.2.15 FS_ShareMode #Defines .................................................................................... 263 15.2.16 FS_TransOpStatus #Defines ............................................................................... 264 FLASH Interface ............................................................................................................... 265 15.3.1 FLASH_INFO....................................................................................................... 265 Reclaim ............................................................................................................................. 266 15.4.1 RC_State typedef enum ...................................................................................... 266 Low-Level .........................................................................................................................267 15.5.1 struct FlashArray and struct FlashDevice ............................................................ 267 15.5.2 struct Erase Region ............................................................................................. 270 15.5.3 struct FlashPartition ............................................................................................. 271 15.5.4 typedef enum PartitionState ................................................................................ 271 15.5.5 typedef enum RwwType ...................................................................................... 272 15.5.6 struct FlashLayout ............................................................................................... 272

15.2

15.3 15.4 15.5

§§

Intel? Flash File System Core Reference Guide

7

Contents

8

Intel? Flash File System Core Reference Guide

Intel? Flash File System Core Introduction

Intel? Flash File System Core Introduction
1.1 Where Do I Start?

1

This Intel? Flash File System Core Reference Guide is organized so that specific information can easily be found. This manual has been organized into the following conceptual areas:

? Introductory
— Chapter 1, “Intel? Flash File System Core Introduction” includes an overview of the major sections of this document and a list of acronyms and terms used.

? Architecture Overview
— Chapter 2, “Architecture” provides an overview of the Flash File System Core components.

? Architecture and API references provide detailed conceptual and API information for each of
the Flash File System Core components: — Chapter 3, “File System Layer” and Chapter 4, “File System API Reference” — Chapter 5, “Data Objects Layer” and Chapter 6, “Data Objects API Reference” — Chapter 7, “Basic Allocation Layer” and Chapter 8, “Basic Allocation API Reference” — Chapter 9, “Reclaim Module” and Chapter 10, “Reclaim Module API Reference” — Chapter 11, “Flash Interface Layer” and Chapter 12, “Flash Interface API Reference” — Chapter 13, “Low-Level Layer” and Chapter 14, “Low-Level API Reference”

? API Structures provides details about structures and defines referenced in the individual
function descriptions in the preceding API chapters: — Chapter 15, “API Structures, Defines, and Enumerations”

1.2

Document Purpose and Scope
The Intel? Flash File System Core Reference Guide outlines the structure and major components that make up the Flash File System Core. It identifies all interfaces between the major system components and includes information on each function to simplify application development to the Flash File System Core.

Intel? Flash File System Core Reference Guide

9

Intel? Flash File System Core Introduction

1.3
Table 1.

Terminology
Acronyms and Terms
Acronym/Term API dentry dcache EDAC FDI File GLIBC inode Application Programmer Interface An inode that is maintained in a cache by the VFS. The VFS maintained cache of dentries. Error Detection And Correction Flash Data Integrator Objects that can be read from or written to. They can also be mapped into main system memory. The GNU C library. A basic object within a file system. It can represent a regular file, a directory, or a symbolic link. Info is similar to man (Linux man pages) and typically gives the same information; however, there are cases where info will allow you to follow links to different related pages. Linux group id. The core functionality of the Linux operating system. Linux user id. An application used by Linux to display on-line manual pages. Portable Operating System Interface Operating System Personal Data Assistant Power Loss Recovery Persistent Storage Manager Reclaim in Progress Real Time Operating System A resource synchronization object. The Linux Virtual File System Switch. Description

info Linux GID Linux Kernel Linux UID man POSIX OS PDA PLR PSM RIP RTOS semaphore VFS

§§

10

Intel? Flash File System Core Reference Guide

Architecture

Architecture
2.1 Architecture Model

2

Communication within the Intel?Flash File System Core (called hereafter the Flash File System Core) is primarily unidirectional--upper layers call lower layers and lower layers do not call upper layers. Callback functions, however, allow lower layers to call upper layers. Peer layers can call each other. For example, the Basic Allocation Layer and the Reclaim Module can call each other. "a translation layer is needed between the file system layer and the file system API of the OS in question." (it is corrent in 2.4) As illustrated in Figure 1, “Intel? Flash File System Core Components” on page 12, the following components are part of or used by the Flash File System Core:

? Operating System components:
— OS File System API — OS External Libraries — OS Specific Layer

? Translation layers between the core product and the operating system:
— RTOS Wrapper Interface — Translation Layer — OS Resources Translation Layer

? Flash File System Core components
— File System Layer — Data Object Layer — Basic Allocation Layer — Reclaim Module — Flash Interface Layer

Intel? Flash File System Core Reference Guide

11

Architecture

Figure 1. Intel? Flash File System Core Components

OS File System API

Real-time Operating System (RTOS) Wrapper Interface OS Resources Translation Layer

RAM FIFO Buffer

File System Layer

Data Objects Layer Flash File System Core Basic Allocation Layer Reclaim Module

Flash Interface Layer

OS Specific Layer

Translation Layer

Low-Level

Flash Hardware

2.2

Theory of Operation
The Flash File System Core uses a single, concise interface that is POSIX-aware. The Operating System Layer uses the File System Layer to implement all file and directory operations per the POSIX standard. Variances are documented and called out. The Flash File System Core can determine whether to use open file structures. Certain operating systems have already implemented the tracking of these objects. The Flash File System Core components uses a layered approach, providing a consistent interface, independent of hardware and operating system cbanges.Details of this layered approach are given in Section 2.3 through Section 2.3.3.

12

Intel? Flash File System Core Reference Guide

OS External Libraries

Architecture

2.3

System Overview
Figure 1, “Intel? Flash File System Core Components” on page 12, illustrates the components that are part of or used by the Flash File System Core.

2.3.1

Real-Time Operating System (RTOS) Wrapper Interface
The Real-Time Operating System (RTOS) Wrapper Interface is an external API that provides the user interface. It gives a handle to RTOS users, allowing applications to use the file manager product. This interface is sometimes defined by the operating system. For example, Microsoft Windows CE* and Linux* defines its own API prototype.

2.3.2

Flash File System Core Components
For some operating systems, a translation layer may be required to interface to the operating system file system API. These layers are:

? The File System Layer manages file-level operations and calls into either the Data Objects
Layer for data objects or application objects layer for code objects.

? The Basic Allocation Layer and Reclaim Module components manage block-level
operations.

? The Flash Interface Layer is the device-independent layer, and the Flash Low-Level Layer
deals with the specific device characteristics. In some operating systems, an OS Specific Layer (such as an OEM adaptation layer) exists between the Flash Interface Layer and the Flash Low-Level Layer, and a corresponding Translation Layer may be required.

2.3.2.1

File System Layer
The File System Layer provides the generic interface into the file system itself. This layer understands the POSIX conventions.

2.3.2.2

Data Objects Layer
The Data Object Layer provides a common structural organization for different types of data, such as static information, dynamic information, directory page, and file data. The Data Object Layer also provides a unified way to manipulate data, links together separate logical units across multiple blocks to form integrated data, and accesses the appropriate logical units irrespective of the data type.

2.3.2.3

The Basic Allocation Layer
The Basic Allocation Layer breaks up a physical erase block into units of equal size and keeps track of individual units and their immediate status, such as allocating, valid, and invalid. It allocates units on requests from the Data Objects Layer and is responsible for PLR on a single unit. It is unaware of whether a given unit is a sequence table, static file information, and dynamic file information, It keeps track of the free and dirty space in every erase block in the managed space.

Intel? Flash File System Core Reference Guide

13

Architecture

2.3.2.4

Reclaim Module
The Reclaim Module is used to clean up the media and reclaim free space from the dirty space that was generated during system operation. It copies all valid data from a block that is to be reclaimed (source block) to a destination block, and then erases the source block. At this point, the space for the dirty or invalid data becomes available free space. The reclaim operation is completely powerloss recoverable. The Reclaim Module calls functions in the Basic Allocation Layer to maintain the block information structure in each block.

2.3.2.5

Flash Interface Layer
The Flash Interface Layer is responsible for interacting with the platform-specific Low-Level Layer driver. It is responsible for issuing read, write, and erase commands to flash. The Flash Interface Layer also translates the file system volumes into flash arrays.

2.3.3

Low-Level Layer
The Low-Level Layer is designed to be a flash driver, which is directly responsible for manipulating flash. All flash accesses must to go through the Low-Level Layer to ensure system integrity. Depending on the platform being used, this module’s behavior may or may not be defined.

2.4

Data Flow
Figure 2 and Figure 3 illustrate write and read data flow respectively.

14

Intel? Flash File System Core Reference Guide

Architecture

Figure 2. Data Write Flow
File Write (offset, size); Data

OS Wrapper Layer Return
Permission Management Error Code Conversion

OS Wrapper API

Call

File System Layer
File System Layer Write Function Locate Static Information Locate File Data Root Write File Data

Return

Yes

All Data Finished?

No

Update Dynamic Information

Update Static Information

Call

Data Object Layer
Data Object Layer Write Function Check for Space for New Data Write Sequence Tables / Entries Yes

Return
Yes All Data Finished? No

Locate the Fragment matched with Write Offset from Root Down

Write Fragments

File Data Root Changed?

No

Call

Basic Allocation Layer
Basic Allocation Layer Write Function Find Space for New Data

Return

Mark PLR Status

Write Data

Call

Flash Interface Layer
Flash Interface Layer Write Function Translate to Low-Level Write Commands

Return

Write Data

Call

Low-Level Layer
Low-Level Layer Write Function Send WSM Command

Return
Wait for Write Completion and Do Interrupt Polling

Write Data

Intel? Flash File System Core Reference Guide

15

Architecture

Figure 3. Data Read Flow

File Read (offset, size);

Data

OS Wrapper Layer Return
Permission Management Error Code Conversion

OS Wrapper API

Call

File System Layer
File System Layer Read Function Locate Static Information Locate File Data Root

Return

Read File Data

Call

Data Object Layer
Data Object Layer Read Function Read Sequence Table Entries

Return
Yes

Read Fragments

All Data Finished? No

Call

Basic Allocation Layer
Basic Allocation Layer Read Function

Return

Read Data

Call

Flash Interface Layer
Flash Interface Layer Read Function Translate to Low-Level Read Commands

Return

Read Data

Call

Low-Level Layer
Low-Level Layer Read Function

Return

Send Read Command

Get Data

16

Intel? Flash File System Core Reference Guide

Architecture

2.5
2.5.1

Power Loss Recovery (PLR)
PLR Status Definitions
To support EDAC, the unit header of the logical unit only holds the PLR status information, allowing the least number of bit twiddling operations. To obtain best write performance, the number of unit header PLR states is limited to three. The PLR states of unit header are:

? header_allocating: The logical unit is occupied and the data is not finished yet. ? header_valid: The logical unit is valid. ? header_invalid: The logical unit is invalid.
The number of sequence table entry PLR states is limited to five (three for main entry and two for replacement). The PLR states of sequence table entry are:

? ? ? ? ?

entry_allocating: The entry information is being written and has not finished yet. entry_valid: The entry information is finished and can properly point to a sub-level unit. entry_invalid: The entry is invalid. replace_allocating; The replacement information is being written and has not finished yet. replace_valid: The replacement information is finished and can properly point to a replace entry.

The sequence table entry PLR states are applicable for the location entry in the file system static info and directory page. To support transacted operations, the transaction information is recorded in the flash to indicate the progress of each transaction. The three PLR states for the transaction information are:

? transaction_start: The transaction writes are started, the new data is being created. ? commit_begin: The new data are finished but the old data (replaced data) is not invalidated. ? commit_end: The transaction write is finished.
Due to minimized PLR states in the unit header, some special information writes are needed to handle the data size change, truncate operation and file delete.

Intel? Flash File System Core Reference Guide

17

Architecture

Figure 4. Typical Write Steps for PLR Flow

Example
1
V V V

Write Flow

PLR Operations

Start
replace 2 fragments and append 2 fragments

2
V

V A V

Step 1: Create new data
Create 4 new fragments, and 2 new seq tables, write corresponding seq entries for new units, keep new units at allocating If power loss happens, Invalidate all the allocating units and seq entries which point to the allocating units

A

A A A A

E A

EMPTY FRAGMENT ALLOCATING FRAGMENT VALID FRAGMENT INVALID FRAGMENT

3
V

V A V

V

Step 2: Write special info
by checking the status of the special info, we can decide if new data are ready, at this point, all the old data are valid while all the new data are allocating

I

E A V I

EMPTY SEQ TABLE ALLOCATING SEQ TABLE VALID SEQ TABLE INVALID SEQ TABLE

A

A A A

SPECIAL INFO

A

4
V

I A I

A

A A A

Step 3: Invalidate old data

SPECIAL INFO

A

5
V

I V I

If power loss happens, invalidate all the valid units which have valid replacement, validate all the allocating units

V

V V V

Step 4: Validate new data

SPECIAL INFO

V

End

2.5.2

Initialization for PLR
During initialization, all the directory/file trees need to be scanned for PLR issues.

18

Intel? Flash File System Core Reference Guide

Architecture

During system shutdown, a structure records whether it is a clean shutdown or a power loss shutdown. This information can speed up the initialization. a flag is recorded in the flash to indicate whether it is a clean shutdown or power loss shutdown. This can speed up the initialization.

2.5.2.1

PLR Testing Strategy
The PLR algorithms is tested by simulating power loss and verifying that recovery occurs correctly at every step. Structures are maintained internally to provide this deterministic test functionality. To ensure completeness, two methods of power loss recovery testing is performed:

? A power loss is simulated, and the write/erase operation never takes place. A special error
code is returned to signify that a power loss has occurred and initialization is performed to verify that recovery correctly takes place.

? Write/erase operations are interrupted in an attempt to put the flash into one of the intermediate
ISF states (0x10 and 0x01). This verifies that the PLR algorithm can correctly recover from an intermediate state.

2.6

Architecture Benefits
The architecture for the Flash File System Core provide these benefits:

? Performance Enhancements ? Transaction Flexibility ? Portability and Operating System Support

2.6.1

Performance
The Open files global structure was added to provide better sequential read and write performance. Reclaim performance is enhanced if units are moved from the block to be reclaimed (source block) to the destination block “in place”; there is no compression of headers and data. The bit array of free units is also a performance enhancement, since the whole block does not need to be searched to find an empty header and data unit each time a new unit is allocated.

2.6.2

Transactions
The Flash File System Core has the ability to commit or rollback a set of operations on a file. For example, a set of write operations at different offsets within a file is considered one single transaction, and either all or none of the operations are done. This is also why some of the power loss recovery (PLR) steps were changed and special information in the dynamic file information structure for each file were added.

2.6.3

Portability and Operating System Support
The Flash File System Core has a single core file system and supports translation layers for different operating systems, supporting the efficiency and rigidity of the POSIX interface. The Flash File System Core supports real-time operating systems (RTOS).

§§
Intel? Flash File System Core Reference Guide 19

Architecture

20

Intel? Flash File System Core Reference Guide

File System Layer

File System Layer

3

The File System Layer, shown in Figure 5, “Flash File System Components” on page 21, provides the generic interface into the Flash File System Core. This layer understands the POSIX conventions. Figure 5. Flash File System Components

OS File System API

Real-time Operating System (RTOS) Wrapper Interface OS Resources Translation Layer

RAM FIFO Buffer

File System Layer

Data Objects Layer Flash File System Core Basic Allocation Layer Reclaim Module

Flash Interface Layer

OS Specific Layer

Translation Layer

Low-Level

Flash Hardware

Intel? Flash File System Core Reference Guide

OS External Libraries

21

File System Layer

3.1

Functionality
The File System Layer provides:

? A set of interfaces for individual operating system layers to communicate with the Flash File
System core.

? An interface for the individual operating system layers to communicate with the Flash File
System Core for specialized commands.

? ? ? ? ? ? ? ? ? ? ? ? ?

A storage for information on open handles used by the OS for file and directory management. An interface for searching. An interface for renaming or moving a file or directory. An implementation of transactions allowing multiple operations per file handle until a commit is issued. File system information to the OS Layer that is needed for partition management. Optional management of the file accesses in a file cache for increased access speeds. A method for retrieving volume statistics information. A method of setting and retrieving information about a file or directory. Support for multiple volumes via geometry information as inputs. Support for multiple simultaneous thread accesses into the API layer. PLR of file constructs that are in mid-transition/creation. A method of storing and accessing metadata for the given file construct. A parameter check except for permissions, mode, attribute.

3.2

Other Component Dependency/Inter-Relationship
The File System Layer has the following dependencies and inter-relationships with other components:

? The File System Layer functions are called by the OS Wrapper Layer. When receiving these
calls, the File System Layer assumes that the OS Wrapper Layer has: — determined if a transaction is required — performed permission checks that the OS requires before performing these transactions.

? The File System Layer requires the Data Objects Layer to be available for management of the
individual file construct management.

3.3

Requirements and Constraints
Requirements of the File System Layer are determined by the POSIX specification and the functionality listed in Section 3.1, “Functionality” on page 22. This File System Layer is constrained by locking and protection mechanisms required to control shared memory and objects.

§§

22

Intel? Flash File System Core Reference Guide

File System API Reference

File System API Reference

4

The File System Layer provides the generic interface into the file system. This layer understands the POSIX conventions. Important: The RTOS Wrapper Interface is the primary interface to the Flash File System. As ports are made to other operating systems, the RTOS Wrapper Interface may be changed to provide for those OS needs. There may be a port of the RTOS Wrapper Interface for a specific OS; therefore, please check with an Intel representative. This File System Layer is a Flash File System internal interface that may change and is provided only to enhance developer understanding of the Flash File System functionality. This chapter lists and details each function, alphabetically. For quick reference, the File System functions are listed Table 2, “File System Functions, Listed Alphabetically” on page 23. Error codes are listed in Section 4.21, “Error Codes” on page 53. The structures and defines used by the File System Layer functions are described in Chapter 15, “API Structures, Defines, and Enumerations.” Table 2. File System Functions, Listed Alphabetically
Task Validates a specified file name and ensures the file/directory exists. Checks whether a new open on a file is allowed or a file is opened with a given mode. Closes an open file. Commits a transaction operation. Cancels a transaction operation. Deletes a single file/directory from the media. Recycles an FS_SearchHandle. Searches for a specified file/directory or a set of files. Gets information about a file/directory. Gets the file system space usage information. Initializes the file system. A custom set of APIs for non-POSIX functionality. Moves a file/directory from one location to another. Creates a directory, creates and opens a file, or opens an existing file. Reads data from an open file, starting at the current file offset. Sets file/directory attributes. Moves the file offset for the specified file handle to a new location. Changes the size of a specified file. Shuts down the file system. Writes data from an external buffer to a specified file. Page 24 25 27 28 29 30 31 32 34 35 36 37 38 39 42 44 46 48 50 51

Function Name FS_CheckFileExists FS_CheckFileOpen FS_CloseFileDir FS_Commit FS_CommitCancel FS_DeleteFileDir FS_FindComplete FS_FindFileDir FS_GetFileDirInfo FS_GetVolumeInfo FS_Init FS_IOCTL FS_MoveFileDir FS_OpenFileDir FS_ReadFileDir FS_SetFileDirInfo FS_SetFileOffset FS_SetFileSize FS_Shutdown FS_WriteFile

Intel? Flash File System Core Reference Guide

23

File System API Reference

4.1

FS_CheckFileExists
Validates a specified file name and ensures the file/directory exists Syntax
FFS_Status FS_CheckFileExists ( *full_path, parent_static_info_loc_ptr, static_info_loc_ptr ); mOS_char BA_UnitLocationPtr BA_UnitLocationPtr

Parameters
Parameter *full_path parent_static_info_loc_ptr Description (IN) The full null terminated path and filename to validate. (OUT) Returns the static info location of the parent directory. This is the directory that matches the second to last token in the full_path. If NULL, the location is not returned. (See Section 15.1.2, “BA_UnitLocation” on page 250.) (OUT) Returns the static info location for the file or directory that matches the last token in the filename. If NULL, the location is not returned. (See Section 15.1.2, “BA_UnitLocation” on page 250.)

static_info_loc_ptr

Error Codes/Return Values
FFS_StatusSuccess FFS_StatusNotInitialized FFS_StatusInvalidPath FFS_StatusFileNotFound FFS_StatusPathNotFound FFS_StatusInvalidFilename FFS_StatusInvalidTarget FFS_StatusOutOfMemory FFS_StatusInvalidParameter Success Failure Failure Failure Failure Failure Failure Failure Failure

Description
The FS_CheckFileExists function validates a file name (illegal chars, or name) and walks the file path to ensure that the specified file or directory exists. It returns the static info location of the filename (last token in the full_path) and its parent directory static info location.

24

Intel? Flash File System Core Reference Guide

File System API Reference

4.2

FS_CheckFileOpen
Checks whether a new open on a file is allowed or a file is opened with a given mode Syntax
FFS_Status FS_CheckFileOpen ( BA_UnitLocationPtr FS_FileHandle FS_ShareMode UINT8 static_info_loc_ptr, file_handle, share_mode, validate_new );

Parameters
Parameter static_info_loc_ptr Description (IN) Points to the location of the file's static info that is checked to determine if the file is open. This location is used only if file_handle is NULL. (See Section 15.1.2, “BA_UnitLocation” on page 250.) (IN) The open file handle of the file to be checked to determine if it is open. This value is used prior to the static_info_loc_ptr, if it is not NULL. (See Section 15.2.7, “FS_OpenFileInfo” on page 258. (IN) The requested mode; the function checks whether a file is opened with this given mode. If a file handle is used, this value is treated as the action--if the mode is “ShareWrite” then it means write access. The share_mode parameter of type FS_ShareMode defines all allowable modes in which a file can be shared when using the FS_OpenFileDir function. See Section 15.2.15, “FS_ShareMode #Defines” on page 263. validate_new (IN) TRUE: Validates for a new open operation. FALSE: Validates the operation on an existing file.

file_handle

share_moder

Error Codes/Return Values
FFS_StatusSuccess FFS_StatusInvalidParameter FFS_StatusSemLockFailed FFS_StatusSemReleaseFailed FFS_StatusSharingViolation FFS_StatusAccessDenied FFS_StatusFileNotOpen Success Failure Failure Failure Failure Failure Failure

Intel? Flash File System Core Reference Guide

25

File System API Reference

Description
The FS_CheckFileOpen function checks whether a new open on a file is allowed or whether a file is opened with the given mode. The FS_CheckFileOpen function scans each entry in the open file list. If the validate new is set to true, this function checks the share mode for the new open. (See Section 15.1.2, “BA_UnitLocation” on page 250 and Section 15.2.7, “FS_OpenFileInfo” on page 258.) If the validate new is set to false, and if the file handle is given, this function checks the access mode of the file handle to see whether the given share mode is allowed. The given share mode indicates the operation to be done on the file: Read or Write operation. If the validate new is set to false, and if the file handle is not given, this function checks the access mode to see whether the given share mode is allowed. The given share mode is the share mode of the new open file handle. (This case is also for the new open).

26

Intel? Flash File System Core Reference Guide

File System API Reference

4.3

FS_CloseFileDir
Closes an open file Syntax
FFS_Status FS_CloseFileDir ( FS_FileHandlePtr file_handle_ptr );

Parameters
Parameter file_handle_ptr Description (IN) The handle of the open file to close. If the handle has write access to the file, all buffered data for the file is flushed before this function returns. This function returns with an error if this input is NULL. (See Section 15.2.7, “FS_OpenFileInfo” on page 258.)

Error Codes/Return Values
FFS_StatusSuccess FFS_StatusNotInitialized FFS_StatusInvalidHandlePointer FFS_StatusSemLockFailed FFS_StatusSemReleaseFailed FFS_StatusFileNotOpen FFS_ErrorSystem FFS_StatusEntryNotFound FFS_StatusEntryCorrupt FFS_StatusInvalidTarget FFS_StatusInvalidStaticInfoChildClass FFS_StatusInvalidHandle Success Failure Failure Failure Failure Failure Failure Failure Failure Failure Failure Failure

Description
The FS_CloseFileDir function closes an open file. This function does not return until the operation completes.

Intel? Flash File System Core Reference Guide

27

File System API Reference

4.4

FS_Commit
Commits a transaction operation Syntax
FFS_Status FS_Commit ( FS_FileHandle file_handle );

Parameters
Parameter file_handle Description (IN) The handle of the open file whose transaction operation is to be committed. If the file handle is not opened for transaction, an error is returned. (See Section 15.2.7, “FS_OpenFileInfo” on page 258.)

Error Codes/Return Values
FFS_StatusSuccess FFS_StatusNotInitialized FFS_StatusInvalidHandle Success Failure Failure

Description
This function commits a transaction operation. It validates all the new data that has been written to the file during the transaction operation, invalidates all the data that has been replaced, and finishes the truncate operation, if needed.

28

Intel? Flash File System Core Reference Guide

File System API Reference

4.5

FS_CommitCancel
Cancels a transaction operation Syntax
FFS_Status FS_CommitCancel ( FS_FileHandle file_handle );

Parameters
Parameter file_handle Description (IN) The handle of the open file whose transaction operation is to be cancelled. If the file handle is not opened for transaction, an error is returned. (See Section 15.2.7, “FS_OpenFileInfo” on page 258.)

Error Codes/Return Values
FFS_StatusSuccess FFS_StatusNotInitialized FFS_StatusInvalidHandle Success Failure Failure

Description
This function cancels a transaction operation. It validates all new data that has been written to the file during the transaction operation, invalidates all the data that has been replaced, and finishes the truncate operation, if needed.

Intel? Flash File System Core Reference Guide

29

File System API Reference

4.6

FS_DeleteFileDir
Deletes a single file/directory from the media Syntax
FFS_Status FS_DeleteFileDir ( *full_path, static_info_type ); mOS_char UINT8

Parameters
Parameter *full_path static_info_type Description (IN) This is the full path of the filename for the file or directory to be deleted. (IN) This tells whether this function is called to delete a file or a directory.

Error Codes/Return Values
FFS_StatusSuccess FFS_StatusNotInitialized FFS_StatusInvalidPath FFS_StatusInvalidTarget FFS_StatusFileStillOpen FFS_StatusDirectoryNotEmpty FFS_StatusSemLockFailed FFS_StatusSemReleaseFailed FFS_StatusFileNotFound FFS_StatusPathNotFound FFS_StatusInvalidFilename FFS_StatusOutOfMemory FFS_StatusInvalidParameter FFS_StatusFullFileNotReturned FFS_StatusEntryNotFound FFS_ErrorSystem Success Failure Failure Failure Failure Failure Failure Failure Failure Failure Failure Failure Failure Failure Failure Failure

Description
The FS_DeleteFileDir function deletes a single file or directory from the media. If the file or directory has any child objects associated with it (dynamic info, primary data, or auxiliary data), the data will be deleted. This function returns with an error if there are any open file handles to the file specified, or if there are any files or subdirectories in the directory specified. If there are any open search handles for the directory to be deleted, this function first deletes the open search handles, and then deletes the directory. This function does not return until the operation completes.

30

Intel? Flash File System Core Reference Guide

File System API Reference

4.7

FS_FindComplete
Recycles an FS_SearchHandle Syntax
FFS_Status FS_FindComplete ( search_handle_ptr ); FS_SearchHandlePtr

Parameters
Parameter search_handle_ptr Description (IN) Pointer to the open search handle to recycle. This function returns an error if this parameter is NULL. See Section 15.2.13, “FS_SearchHandle #Defines” on page 263.

Error Codes/Return Values
FFS_StatusSuccess FFS_StatusNotInitialized FFS_StatusInvalidHandlePointer FFS_StatusSemLockFailed FFS_StatusSemReleaseFailed FFS_StatusInvalidHandle Success Failure Failure Failure Failure Failure

Description
The FS_FindComplete function recycles an FS_SearchHandle. This function MUST be called once a search handle provided by FS_FindFileDir is no longer needed. Failure to do so results in a memory leak and may prevent other operations from completing successfully. This function is usually called after the last matching file in a directory has been found. This function does not return until the operation completes.

Intel? Flash File System Core Reference Guide

31

File System API Reference

4.8

FS_FindFileDir
Searches for a specified file/directory or a set of files Syntax
FFS_Status FS_FindFileDir ( *search_pattern, search_handle_ptr, file_info_ptr, find_mode ); mOS_char FS_SearchHandlePtr FS_FileDirInfoPtr FS_FindMode

Parameters
Parameter *search_pattern Description (IN) Specifies a pattern to match when searching for files or directories. The pattern is supplied in the form of an ordinary filename, with wildcards being optional. To search in directories other than the root, the full path must precede the filename. Note that only the filename can contain wildcards -- the path must be unique. When the find_mode is FS_FindMatched, no wildcards are allowed in the filename. This input can be set to NULL when FS_FindNext or FS_FindPrev modes are being used. The input must be present for all other modes. (IN/OUT) Points to an FS_SearchHandle. A search handle is passed into this function when using the FS_FindNext or FS_FindPrev modes, to indicate which search should be resumed. A handle is always passed back (except when using the FS_FindMatched mode) to allow searches to be continued. This input is ignored (and can be set to NULL) when using the FS_FindMatched mode. The FS_SearchHandle references open searches to allow an application to continue a wildcard-based search in progress. See Section 15.2.13, “FS_SearchHandle #Defines” on page 263. file_info_ptr (OUT) Points to an FS_OpenFileInfo structure, which is filled in (by this function) with information about the file or directory that was found. This function fails with an error if this input is NULL. (See Section 15.2.6, “FS_FileDirInfo” on page 257.) (IN) Determines the behavior of this function. It is one of the following values: ? FS_FindFirst: Searches for the first file in the given directory that matches the search pattern specified, starting at the beginning of the directory and working toward the end. ? FS_FindNext: Searches for the next file in the given directory that matches the search pattern specified in the search handle given. The FS_SearchHandle passed allows the file system to determine which search in progress is to be resumed. The "next" file is the first one that matches the search pattern supplied, starting immediately after the last matched file found, working forward to the end of the directory. ? FS_FindPrev: Searches for the previous file in the given directory that matches the search pattern specified in the search handle given. The FS_SearchHandle passed in allows the file system to determine which search in progress is to be resumed. The "previous" file is the first one that matches the search pattern, starting immediately prior to the last matched file found, working backward to the beginning of the directory. ? FS_FindMatched: Searches for a file in the given directory with the exact name specified. The search pattern can not contain wildcards when using this mode. No search handle is output, and any handles input are ignored. The FS_FindMode defines all allowable modes for searching for data parameters, when using the FS_FindFileDir function. See Section 15.2.8, “FS_FindMode #Defines” on page 261

search_handle_ptr

find_mode

32

Intel? Flash File System Core Reference Guide

File System API Reference

Error Codes/Return Values
FFS_StatusSuccess FFS_StatusNotInitialized FFS_StatusInvalidParameter FFS_StatusInvalidHandlePointer FFS_StatusInvalidFilename FFS_StatusPathNotFound FFS_StatusFileNotFound FFS_StatusSemLockFailed FFS_StatusSemReleaseFailed FFS_StatusInvalidHandle FFS_StatusInvalidPath FFS_StatusInvalidTarget FFS_StatusOutOfMemory FFS_StatusFullFileNotReturned FFS_StatusEntryNotFound Success Failure Failure Failure Failure Failure Failure Failure Failure Failure Failure Failure Failure Failure Failure

Description
The FS_FindFileDir function performs a search for a specific file or directory, or set of files, that match the search pattern supplied. This function does not affect a file or directory's time/date stamps. This function does not return until the operation completes.(See Section 15.2.6, “FS_FileDirInfo” on page 257.) Note: This function finds all objects within a directory, regardless of whether they are files or directories. Files can be differentiated from directories by checking the "file offset" field of the FS_FileDirInfo structure that is filled in when this function returns. Directories always report an offset of 0xFFFFFFFF, while files report an offset of 0.

Intel? Flash File System Core Reference Guide

33

File System API Reference

4.9

FS_GetFileDirInfo
Gets information about a file/directory Syntax
FFS_Status FS_GetFileDirInfo ( *full_path, file_handle, file_info_ptr ); mOS_char FS_FileHandle FS_FileDirInfoPtr

Parameters
Parameter *full_path file_handle Description (IN) The full path of the filename for the file or directory whose information is to be read. (IN) The open file handle of the file or directory whose information is to be read. If this parameter is not NULL, it will get file offset from the open file handle. Either full_path or file_handle should be given for this function. This parameter will be used prior to full_path if it is not NULL. (See Section 15.2.7, “FS_OpenFileInfo” on page 258.) (OUT) The file information that is read from flash for the specified file or directory. This is a pointer to the FS_OpenFileDirInfo structure. If this parameter is NULL, this function returns an error. (See Section 15.2.6, “FS_FileDirInfo” on page 257.)

file_info_ptr

Error Codes/Return Values
FFS_StatusSuccess FFS_StatusNotInitialized FFS_StatusInvalidHandle FFS_StatusInvalidParameter FFS_StatusFileNotFound FFS_StatusInvalidFilename FFS_StatusFileNotOpen FFS_StatusSemLockFailed FFS_StatusSemReleaseFailed FFS_StatusInvalidPath FFS_StatusPathNotFound FFS_StatusInvalidTarget FFS_StatusOutOfMemory FFS_StatusFullFileNotReturned FFS_StatusEntryNotFound Success Failure Failure Failure Failure Failure Failure Failure Failure Failure Failure Failure Failure Failure Failure

Description
The FS_GetFileDirInfo function gets information about a file or directory, such as its size, time/ date stamps, attributes, and filename. In addition, the current file offset is returned if an open file handle is used to identify which file's information is desired. This function does not affect a file or directory's time/date stamps. This function does not return until the operation completes.

34

Intel? Flash File System Core Reference Guide

File System API Reference

4.10

FS_GetVolumeInfo
Gets the file system space usage information Syntax
FFS_Status FS_GetVolumeInfo ( FFS_VolumeInfoPtr info_ptr );

Parameters
Parameter info_ptr Description (OUT) Pointer to the space usage information that has been retrieved. This function returns an error if this parameter is NULL. (See Section 15.2.4, “FFS_VolumeInfo” on page 255.)

Error Codes/Return Values
FFS_StatusSuccess FFS_StatusNotInitialized FFS_StatusInvalidParameter Success Failure Failure

Description
The FS_ GetVolumeInfo function gets the File System space usage information.

Intel? Flash File System Core Reference Guide

35

File System API Reference

4.11

FS_Init
Initializes the file system Syntax
FFS_Status FS_Init ( volume_info_ptr, format_info_ptr, options_ptr ); VOID_PTR FFS_FormatPtr FFS_OptionsPtr

Parameters
Parameter volume_info_ptr format_info_ptr options_ptr Description (IN) Pointer to an FFS_VolumeInfo structure. (See Section 15.2.4, “FFS_VolumeInfo” on page 255.) (IN) Pointer to an FFS_Format structure. (See Section 15.2.2, “FFS_Format” on page 254.) (IN) Pointer to an FFS_Options structure. (See Section 15.2.3, “FFS_Options” on page 254.)

Error Codes/Return Values
FFS_StatusSuccess FFS_StatusInvalidParameter FFS_StatusFileNotFound FFS_StatusPathNotFound FFS_StatusInvalidFilename FFS_StatusInvalidTarget FFS_StatusOutOfMemory FFS_StatusInvalidParameter Success Failure Failure Failure Failure Failure Failure Failure

Description
The FS_Init function initializes the Flash File System.

36

Intel? Flash File System Core Reference Guide

File System API Reference

4.12

FS_IOCTL
Provides a custom set of functions for non-POSIX functionality Syntax
FFS_Status FS_IOCTL ( pInBufptr , nInBufSize, pOutBufptr, nOutBufSize, pBytesReturned, sub_cmd ); UINT8_PTR UINT32 UINT8_PTR UINT32 UINT32_PTR FS_IOCMD

Parameters
Parameter pInBufptr nInBufSize pOutBufptr nOutBufSize pBytesReturned sub_cmd Description (IN) Pointer to a buffer that contains the data required to perform the operation. (IN) Size, in bytes, of the buffer pointed to by pInBuf. (OUT) Pointer to a buffer that receives the operations output data. (OUT) Size, in bytes, of the buffer pointed to by pOutBuf (OUT) Size, in bytes, of the data stored into the buffer pointed to by pOutBuf (IN) Command to be performed. This input must be one of the following FS_IOCMD_RECL_ENABLE: To enable the user to trigger a foreground reclaim. pInBuffer = (UINT32) volume_name, nInBufSize = sizeof(UINT32), pOutBufptr = NULL, nOutBufSize = N/A, pBytesReturned = N/A, sub_cmd = FS_IOCMD_RECL_ENABLE FS_IOCMD_RECL_STATUS: To query the cache status. pInBuffer = volume name, nInBufSize = volume name size, pOutBufptr = RIP, nOutBufSize = 1, pBytesReturned = 1, sub_cmd = FS_IOCMD_RECL_STATUS

Error Codes/Return Values
FFS_StatusSuccess FFS_StatusNotInitialized FFS_StatusInvalidParameter Success Failure Failure

Description
A custom set of functions for implementing non-POSIX functionality.

Intel? Flash File System Core Reference Guide

37

File System API Reference

4.13

FS_MoveFileDir
Moves a file or directory from one location to another Syntax
FFS_Status FS_MoveFileDir ( *old_full_path, *new_full_path ); mOS_char mOS_char

Parameters
Parameter *old_full_path *new_full_path Description (IN) Full path of the old filename for the file or directory to be moved. This function returns an error if this input is NULL. (IN) Full path of the new filename for the file or directory to move. This function returns an error is this input is NULL.

Error Codes/Return Values
FFS_StatusSuccess FFS_StatusNotInitialized FFS_StatusInvalidPath FFS_StatusFileAlreadyExists FFS_StatusMediaFull FFS_ErrorSystem FFS_StatusInvalidTarget FFS_StatusFileNotFound FFS_StatusPathNotFound FFS_StatusInvalidFilename FFS_StatusOutOfMemory FFS_StatusInvalidParameter FFS_StatusEntryNotFound FFS_StatusSemLockFailed FFS_StatusSemReleaseFailed Success Failure Failure Failure Failure Failure Failure Failure Failure Failure Failure Failure Failure Failure Failure

Description
The FS_MoveFileDir function moves a file or directory from one location to another. This function can also rename files. This function updates the open search list and open file list with the new location of the file or directory. This function does not return until the operation completes. Note: The OS layer must verify that the file to be moved is not open. If the target of the move is a subdirectory, the OS layer must verify that there are no open files or searches in progress within the target subdirectory (or its subtree). Otherwise, the File System layer cannot guarantee the data in flash is not corrupt.

38

Intel? Flash File System Core Reference Guide

File System API Reference

4.14

FS_OpenFileDir
Creates a directory, or creates and opens a file, or opens existing file Syntax
FFS_Status FS_OpenFileDir ( *full_path, file_handle_ptr, attributes, open_mode, share_mode, ram_buffer_mode, trans_flag, static_info_type ); mOS_char FS_FileHandlePtr UINT32 FS_OpenMode FS_ShareMode FS_RamBufferMode UINT8 UINT8

Parameters
Parameter *full_path file_handle_ptr Description (IN) The fullpath of the filename for the file or directory. This function fails with an error if this input is NULL. (OUT) Pointer to an open file handle (FS_FileHandle) that is owned by the calling function. Upon exit from this function, the variable pointed to by this input is assigned a unique file handle. This handle is used in subsequent calls to File System functions to reference the file that was opened or created. This function returns with an error if this input is NULL. (See Section 15.2.7, “FS_OpenFileInfo” on page 258.) (IN) File or directory attributes to be set. No effort is made to interpret these. (IN) Specifies whether the file is to be opened or created, and what kind of access will be granted by the resulting file handle. This input must be one of the following FS_OpenMode constants (See Section 15.2.8, “FS_FindMode #Defines” on page 261): ? FS_CreateNew: Attempts to create a new file with the given name in the specified path. Returns with an error if the file already exists. If successful, the file is opened for read/write access. ? FS_CreateAlways: Creates the file with the given name in the specified path. If a file with the same name already exists, it is deleted and replaced by the new file. If successful, the file is opened for read/write access. ? FS_OpenRead: Attempts to open an existing file for read-only access. Returns with an error if the file does not exist. Any attempts to write to a file opened in this mode will fail with an error. ? FS_OpenWrite: Attempts to open an existing file for read/write access. Returns with an error if the file does not exist. ? FS_OpenAlways: Attempts to open an existing file for read/write access. If the file does not exist, it is created. share_mode (IN) File sharing mode, FS_ShareMode. This parameter is ignored when the static_info_type is for a directory. The share_mode parameter of type FS_ShareMode defines all allowable modes in which a file can be shared when using the FS_OpenFileDir function. See Section 15.2.15, “FS_ShareMode #Defines” on page 263.

attributes open_mode

Intel? Flash File System Core Reference Guide

39

File System API Reference

Parameter ram_bufer_mode trans_flag (IN) RAM buffer mode for the file.

Description

(IN) Flag to indicate whether this file is opened for transaction. This flag is ignored when the static_info_type is for a directory. TRUE: for transaction. FALSE: not for transaction. (IN) Specifies whether this function is called for a file or directory.

static_info_type

Error Code/Return Value
FFS_StatusSuccess FFS_StatusNotInitialized FFS_StatusInvalidPath FFS_StatusInvalidHandlePointer FFS_StatusTooManyOpenFiles FFS_StatusInvalidFilename FFS_StatusInvalidParameter FFS_StatusInvalidTarget FFS_StatusFileAlreadyExists FFS_StatusSharingViolation FFS_StatusNoErrorFileExists FFS_StatusFileNotFound FFS_StatusPathNotFound FFS_StatusOutOfMemory FFS_ErrorSystem FFS_StatusMediaFull FFS_StatusEntryNotFound FFS_StatusFullFileNotReturned FFS_StatusSemLockFailed FFS_StatusSemReleaseFailed FFS_StatusEntryCorrupt FFS_StatusInvalidStaticInfoChildClass FFS_StatusInvalidTransInfoCount FFS_StatusInvalidSizeInfoCount Failure Failure Failure Failure Failure Failure Failure Failure Failure Failure Failure Failure Failure Failure Failure Failure Failure Failure Failure Failure Failure Failure Failure

Other codes bubbled up from the OS function and from the Data Objects Layer.

Description
If the FS_OpenFileDir function is called for a directory, it creates a directory. If called for a file, it creates a file if open_mode is FS_CreateNew. It also opens the file if the file exists. If the file does not exist, it will create and them open it. (See Section 15.2.7, “FS_OpenFileInfo” on page 258.) A file can be opened multiple times by different applications or by the same application. Multiple open file handles to the same file are controlled by the share_mode the file is opened with. If multiple handles to the same file exist, it is the responsibility of the handle owner to synchronize file access.

40

Intel? Flash File System Core Reference Guide

File System API Reference

When opening files, the file offset (file pointer) is set to the end of the file when opened for writing, and to the beginning of the file when opened for reading. When creating files, the offset is always zero, since the file contains no data. This function does not return until the operation completes. Currently, this function is only used to 1) create or open a file or 2) create a directory.

Intel? Flash File System Core Reference Guide

41

File System API Reference

4.15

FS_ReadFileDir
Reads data from an open file, starting at the current file offset Syntax
FFS_Status FS_ReadFileDir ( VOID_PTR data_buffer_ptr, FS_FileHandle file_handle, UINT32_PTR FS_Class data_size_ptr, child_class );

Parameters
Parameter data_buffer_ptr file_handle Description (OUT) Pointer to the data buffer in RAM that receives the data that is read. This function returns with an error is this parameter is NULL. (IN/OUT) The handle of the open file to read from. This function returns with an error if this parameter is NULL. The FileOffset field of the open file handle is updated if any data is read. (See Section 15.2.7, “FS_OpenFileInfo” on page 258.) (IN/OUT) Pointer to the a variable containing the number of bytes that should be read from the file. On entry, the value pointed to by this parameter should not be greater than the actual size of the buffer pointed to by data_buffer_ptr, or the output buffer may be overrun. But this should be controlled by the calling function. On return, the value pointed to by this parameter is set to the total number of bytes actually read. This number may be different from the number requested if the EOF is encountered or an error occurs. This function returns with an error if this parameter is NULL. child_class (IN) Specifies either of the following type of object to read: FS_ClassFilePrimaryData FS_ClassFileAuxData Other class values cause an error to be returned. See Section 15.2.5, “FS_Class typedef enum” on page 256.

data_size_ptr

Error Code/Return Value
FFS_StatusSuccess FFS_StatusNotInitialized FFS_StatusInvalidHandle FFS_StatusInvalidParameter FFS_StatusInvalidStaticInfoChildClass FFS_StatusEndOfFile FFS_StatusAccessDenied FFS_StatusFileNotOpen FFS_StatusSemLockFailed FFS_StatusSemReleaseFailed FFS_StatusEntryNotFound Failure Failure Failure Failure Failure Failure Failure Failure Failure Failure

42

Intel? Flash File System Core Reference Guide

File System API Reference

Description
Reads data from an open file, starting at the current file offset. If end-of-file is reached before the specified number of bytes are read, an error is returned. This function does not return until all data has been read.

Intel? Flash File System Core Reference Guide

43

File System API Reference

4.16

FS_SetFileDirInfo
Sets file/directory attributes Syntax
FFS_Status FS_SetFileDirInfo ( * full_path, file_handle, attributes_ptr, creation_time_ptr, last_access_time_ptr, update_modify_time ); mOS_char FS_FileHandle UINT32_PTR FFS_FileDirTimePtr FFS_FileDirTimePtr UINT8

Parameters
Parameter *full_path file_handle Description (IN) The full path of the filename for the file or directory to set information. (IN) The open file handle for the file to set information. If this parameter is not NULL, it is used prior to full_path. Either this parameter or full_path should be given for this function. (See Section 15.2.7, “FS_OpenFileInfo” on page 258.) (IN) Pointer to the attribute that will be set for the file or directory. If this pointer is not NULL, this function updates the attributes for the file or directory. (IN) Pointer to the creation time that will be set for the file or directory. If this pointer is not NULL, this function updates the creation time for the file or directory. (IN) Pointer to the last access time that will be set for the file or directory. If this pointer is not NULL, this function updates the last access time for the file or directory. (IN) The flag to indicate whether the last modify time needs to be updated together with the last access time. This flag is checked only when last_access_time_ptr is not NULL. TRUE: Update needed. FALSE: Update NOT needed.

attributes_ptr creation_time_ptr

last_access_time_ptr

update_modify_time

Error Codes/Return Values
FFS_StatusSuccess FFS_StatusNotInitialized FFS_StatusInvalidHandle FFS_StatusFileNotFound FFS_StatusInvalidFilename FFS_ErrorSystem FFS_StatusInvalidTarget FFS_StatusSemLockFailed FFS_StatusSemReleaseFailed FFS_StatusFileNotOpen Success Failure Failure Failure Failure Failure Failure Failure Failure Failure

44

Intel? Flash File System Core Reference Guide

File System API Reference

FFS_StatusInvalidPath FFS_StatusPathNotFound FFS_StatusOutOfMemory FFS_StatusInvalidParameter FFS_StatusEntryNotFound FFS_StatusEntryCorrupt FFS_StatusInvalidStaticInfoChildClass

Failure Failure Failure Failure Failure Failure Failure

Description
The FS_SetFileDirInfo function sets a file or directory's attributes and time/date stamps. This function returns with an error if used on a file that is currently open. This function does not return until the operation completes.

Intel? Flash File System Core Reference Guide

45

File System API Reference

4.17

FS_SetFileOffset
Moves the file offset for the specified file handle to a new location Syntax
FFS_Status FS_SetFileOffset ( file_handle, offset, seek_mode, child_class ); FS_FileHandle SINT32 FS_SeekMode FS_Class

Parameters
Parameter file_handle Description (IN) The handle of the open file whose offset is to be set. This function returns with an error if this input is NULL. (See Section 15.2.7, “FS_OpenFileInfo” on page 258.) (IN) The new offset to seek to. How this value is interpreted is governed by the seek_mode input. Note that this value is a signed integer, so both forward (positive) and backward (negative) seeks are allowed. If given offset value is evaluates to an offset that is before the physical start of the file (less than zero), an error is returned. However, it is valid to seek beyond the end-of-file (EOF). Read operations performed after seeking beyond the EOF behave exactly the same as if the offset were at the EOF—no data is returned. Write operations performed beyond the EOF occur at that location—the file is extended to the current offset (past the EOF), and then the new data is appended to the file. If there is not enough free memory to extend the file to the current offset, an error is returned and the original file size is maintained. For extended files, the data between the old EOF and the newly written data is undefined. seek_mode (IN) Controls how the value in offset is used. This value must be one of the following constants: ? FS_SeekFromBeginning: Causes the file pointer to be placed at offset bytes from the beginning of the file. As such, only positive offsets are valid when using this mode. This mode is used most commonly to seek to the beginning of the file or to an absolute offset. ? FS_SeekFromCurrent: Causes the file pointer to be placed at offset bytes from the current pointer location. This mode is used most commonly for random access operations within a file. ? FS_SeekFromEnd: Causes the file pointer to be placed at offset bytes from the end of the file. child_class (IN) Specifies either of the following type of objects to read the data from: ? FS_ClassFilePrimaryData ? FS_ClassFileAuxData Other class values will cause an error to be returned. See Section 15.2.5, “FS_Class typedef enum” on page 256.

offset

46

Intel? Flash File System Core Reference Guide

File System API Reference

Error Codes/Return Values
FFS_StatusSuccess FFS_StatusNotInitialized FFS_StatusInvalidHandle FFS_StatusInvalidStaticInfoChildClass FFS_StatusInvalidOffset FFS_StatusInvalidParameter FFS_StatusFileNotOpen FFS_StatusSemLockFailed FFS_StatusSemReleaseFailed Success Failure Failure Failure Failure Failure Failure Failure Failure

Description
The FS_SetFileOffset function moves the file offset for the given file handle to a new location. The file offset is where all reads and writes to a file originate. This is a per-handle value; changing the file offset of one handle does not affect the offset accessed by another handle. If an error occurs while trying to seek to the new offset, the original offset will be restored. This function does not affect a file or directory's time/date stamps and does not generate a change notification event. This function does not return until the operation completes. Note: The file offset 0xFFFFFFFF is reserved for system use and is not a valid offset to seek to. This is irrelevant to normal file system usage since more than 4GB of flash is required to necessitate use of offset 0xFFFFFFFF.

Intel? Flash File System Core Reference Guide

47

File System API Reference

4.18

FS_SetFileSize
Changes the size of a specified file Syntax
FFS_Status FS_SetFileSize ( file_handle, new_file_size_ptr, child_class); FS_FileHandle UINT32_PTR FS_Class

Parameters
Parameter file_handle Description (IN) The handle of the open file whose size is to be changed. The file must have been opened with write access for this function to succeed. This function returns with an error if this input is NULL. (See Section 15.2.7, “FS_OpenFileInfo” on page 258.) (OUT) Upon return from this function, the variable pointed to will be set to the actual size the file was changed to. This number may be different from the size requested if the media becomes full or an error occurs. This input can be set to NULL if this information is not needed. (IN) Specifies either of the following type of objects to write the data to: FS_ClassFilePrimaryData FS_ClassFileAuxData. Other class values will cause an error to be returned. See Section 15.2.5, “FS_Class typedef enum” on page 256.

new_file_size_ptr

child_class

Error Codes/Return Values
FFS_StatusSuccess FFS_StatusNotInitialized FFS_StatusInvalidHandle FFS_StatusInvalidStaticInfoChildClass FFS_ErrorSystem FFS_StatusMediaFull FFS_StatusAccessDenied FFS_StatusFileNotOpen FFS_StatusSemLockFailed FFS_StatusSemReleaseFailed FFS_StatusEntryCorrupt FFS_StatusInvalidTarget FFS_StatusEntryNotFound FFS_StatusInvalidTransInfoCount FFS_StatusInvalidSizeInfoCount FFS_StatusInvalidParameter Success Failure Failure Failure Failure Failure Failure Failure Failure Failure Failure Failure Failure Failure Failure Failure

48

Intel? Flash File System Core Reference Guide

File System API Reference

Description
The FS_SetFileSize function changes the size of the file associated with the given file handle. This function can be used either to truncate or extend a file.(See Section 15.2.7, “FS_OpenFileInfo” on page 258.) Note: Because the file size is changed to match the current file offset, the FS_SetFileOffset function (Section 4.17, on page 4-46) should be called to set the offset before calling this function. This function does not return until the operation completes.

Intel? Flash File System Core Reference Guide

49

File System API Reference

4.19

FS_Shutdown
Shuts down the file system Syntax
FFS_Status FS_Shutdown ( void );

Parameters
None

Error Codes/Return Values
FFS_StatusSuccess FFS_StatusNotInitialized FFS_StatusSemLockFailed FFS_StatusSemReleaseFailed FFS_ErrorSystem FFS_StatusEntryNotFound FFS_StatusEntryCorrupt FFS_StatusInvalidTarget FFS_StatusInvalidStaticInfoChildClass FFS_StatusSemDestroyFailed Success Failure Failure Failure Failure Failure Failure Failure Failure Failure

Description
The FS_Shutdown function shuts down the file system, ensuring it is safe to terminate.

50

Intel? Flash File System Core Reference Guide

File System API Reference

4.20

FS_WriteFile
Writes data from an external buffer to an open file Syntax
FFS_Status FS_WriteFile ( FS_FileHandle file_handle, VOID_PTR data_ptr, UINT32_PTR FS_Class data_size_ptr, child_class );

Parameters
Parameter file_handle Description (IN) The handle of the open file to write to. The file must have been opened with write access for this function to succeed. This function returns with an error if this input is NULL. (See Section 15.2.7, “FS_OpenFileInfo” on page 258.) (IN) Points to the data buffer in RAM that contains the data that is to be written. This buffer MUST NOT be disturbed until the background write operation completes. The calling application can either 1) call the FS_FlushFileBuffers function to force the write to occur immediately, or 2) it can supply a callback function pointer (see below) to inform it when the background write completes. This function returns with an error if this input is NULL. data_size_ptr (IN/OUT) On input, points to a variable containing the number of bytes that should be written to the file. The value given in this input must not be greater than the actual size of the buffer pointed to by data_ptr, or memory outside the input buffer may be accessed. On output, points to the total number of bytes that can actually be written based on the amount of free space in flash. This number will be different from the number requested only if there is not enough free space remaining on the media to store the requested number of bytes. This function returns with an error if this input is NULL. child_class (IN) Specifies either of the following type of objects to write the data to: ? FS_ClassFilePrimaryData ? FS_ClassFileAuxData Other class values will cause an error to be returned. See Section 15.2.5, “FS_Class typedef enum” on page 256.

data_ptr

Error Codes/Return Values
FFS_StatusSuccess FFS_StatusNotInitialized FFS_StatusInvalidHandle FFS_StatusInvalidParameter FFS_StatusInvalidStaticInfoChildClass FFS_StatusMediaFull FFS_StatusAccessDenied Success Failure Failure Failure Failure Failure Failure

Intel? Flash File System Core Reference Guide

51

File System API Reference

FFS_StatusFileNotOpen FFS_StatusSemLockFailed FFS_StatusSemReleaseFailed FFS_ErrorSystem FFS_StatusEntryCorrupt FFS_StatusInvalidTarget FFS_StatusEntryNotFound FFS_StatusInvalidTransInfoCount FFS_StatusInvalidSizeInfoCount

Failure Failure Failure Failure Failure Failure Failure Failure Failure

Description
The FS_WriteFile function writes data from an external buffer to an open file, starting at the current file offset. This function waits until the write is complete before returning.

52

Intel? Flash File System Core Reference Guide

File System API Reference

4.21
Table 3.

Error Codes
Table 3 describes the Flash File System error codes. File System Error Codes
Error Code FFS_StatusSuccess FFS_StatusNotFound FFS_StatusInvalidParameter FFS_StatusOutOfMemory FFS_StatusMutexFailure FFS_StatusSemaphoreFailure FFS_StatusThreadFailure FFS_StatusReclaimInProgress FFS_ErrorNone FFS_ErrorSystem FFS_ErrorNoMoreMemory FFS_ErrorInsufficientAvailableSpace FFS_ParentReclaimNeeded FFS_StatusInvalidMediaFormat FFS_StatusReclaimNeeded FFS_StatusMediaFull FFS_StatusBlockInfoCorrupt FFS_StatusGlobalInfoCorrupt FFS_StatusRootInfoCorrupt FFS_StatusInvalidLogicalUnit DO_ErrorInvalidDataPtr DO_ErrorInvalidSizePtr DO_ErrorInvalidObjectLocationPtr DO_ErrorInvalidCallbackInfoPtr DO_ErrorInvalidCallbackFunctionPtr DO_ErrorInvalidBytesWrittenPtr DO_ErrorInvalidVolumeInfoPtr DO_ErrorInvalidObjectLocation DO_ErrorInvalidOffset DO_ErrorInvalidSize DO_ErrorInvalidPLRStatusType DO_ErrorObjectExists DO_ErrorInsufficientAvailableSpace #if 0 Value 0x0000 0x0001 0x0002 0x0003 0x0006 0x0007 0x0008 0x0009 0x0000 0x0004 0x0003 0xBA02 0x0005 0xBA00 0xBA01 0xBA02 0xBA03 0xBA04 0xBA05 0xBA06 0xD000 0xD001 0xD002 0xD003 0xD004 0xD005 0xD006 0xD007 0xD008 0xD009 0xD00A 0xD00B 0xD00C

Intel? Flash File System Core Reference Guide

53

File System API Reference

Table 3.

File System Error Codes
Error Code SEQ_ErrorInvalidOffset SEQ_ErrorInvalidObjectLocationPtr SEQ_ErrorInvalidEntryPtr SEQ_ErrorInvalidTableLevelPtr SEQ_ErrorInvalidIndexPtr SEQ_ErrorInvalidAllocationInfoPtr SEQ_ErrorInvalidSeqTableIndex SEQ_ErrorInvalidSize SEQ_ErrorInvalidFragSize SEQ_ErrorInvalidTableLevel SEQ_StatusEmptyTable SEQ_ParentUpdateNeeded #endif FS_ErrorAccessDenied FS_ErrorDirectoryNotEmpty FS_ErrorEndOfFile FS_ErrorEntryCorrupt FS_ErrorFileAlreadyExists FS_ErrorFileNotFound FS_ErrorFileNotOpen FS_ErrorFileStillOpen FS_ErrorFullFileNotReturned FS_ErrorPathNotFound FS_ErrorInvalidDataPointer FS_ErrorInvalidFilename FS_ErrorInvalidHandle FS_ErrorInvalidHandlePointer FS_ErrorInvalidLocationPointer FS_ErrorInvalidMode FS_ErrorInvalidObjectSize FS_ErrorInvalidOffset FS_ErrorInvalidParameter FS_ErrorInvalidPath FS_ErrorInvalidSizeInfoCount FS_ErrorInvalidStaticInfoChildClass FS_ErrorInvalidStaticInfoType FS_ErrorInvalidTarget 0xF000 0xF001 0xF002 0xF003 0xF004 0xF005 0xF006 0xF007 0xF008 0xF009 0xF00A 0xF00B 0xF00C 0xF00D 0xF00E 0xF00F 0xF010 0xF011 0xF012 0xF013 0xF014 0xF015 0xF016 0xF017 Value 0xD00D 0xD00E 0xD00F 0xD010 0xD011 0xD012 0xD013 0xD014 0xD015 0xD016 0xD017 0xD018

54

Intel? Flash File System Core Reference Guide

File System API Reference

Table 3.

File System Error Codes
Error Code FS_ErrorInvalidTransInfoCount FS_ErrorMutexCreateFailed FS_ErrorMutexDestroyFailed FS_ErrorMutexLockFailed FS_ErrorMutexReleaseFailed FS_ErrorNoErrorFileExists FS_ErrorNotFound FS_ErrorNotInitialized FS_ErrorSharingViolation FS_ErrorTooManyOpenFiles FFS_StatusUnknown Value 0xF018 0xF019 0xF01A 0xF01B 0xF01C 0xF01D 0xF01E 0xF01F 0xF020 0xF021 0xFFFF

§§

Intel? Flash File System Core Reference Guide

55

File System API Reference

56

Intel? Flash File System Core Reference Guide

Data Objects Layer

Data Objects Layer

5

The Data Object Layer, shown in Figure 6, “Flash File System Components” on page 57, provides a common structural organization for different types of data, such as static information, dynamic information, directory page, and file data. The Data Object Layer also provides a unified way to:

? Manipulate data, ? Link separate logical units across multiple blocks to form integrated data, ? Access the appropriate logical units irrespective of the data type.
Figure 6. Flash File System Components

OS File System API

Real-time Operating System (RTOS) Wrapper Interface OS Resources Translation Layer

RAM FIFO Buffer

File System Layer

Data Objects Layer Flash File System Core Basic Allocation Layer Reclaim Module

Flash Interface Layer

OS Specific Layer

Translation Layer

Low-Level

Flash Hardware

Intel? Flash File System Core Reference Guide

OS External Libraries

57

Data Objects Layer

5.1

Functionality
The Data Object Layer provides the following functionality:

? Provides a set of uniform interfaces for Flash File System components to access any type of
data.

? Determines whether to store data as single instance or fragmented data. ? Creates/manipulates appropriate sequence table levels and entries to link multiple logical units
for fragmented data.

? Manages sequence table replacement chains when any logical unit of a fragment is replaced. ? Translates the read/write commands within data to read/write commands within multiple
logical units.

? Provides power loss recovery (PLR) steps at the data object level, guarantees partial data
writes success for the Append command, and guarantees either rollback to old data or having all new data for the Replace command.

? Supports transacted operations on a file. If an operation on a data object is part of a transaction,
then the Data Objects Layer performs the appropriate PLR steps while writing the data.

? During initialization, is responsible for detecting any power loss issues at the data object level
and provides functionality to perform appropriate recovery operations. It also calls down into basic allocation initialization function to perform lower level initialization.

5.2

Other Component Dependency/Inter-Relationship
The Data Objects Layer has the following dependencies and inter-relationships with other components:

? Interfaces with File System Interface Layer and provides a set of functions it calls to perform
data access.

? Interfaces with the Basic Allocation Layer, by sending the logical units access command to
perform the lower layer data writes and reads

? Requires a callback helper function to the File System Interface Layer to provide updates to
the primary data pointer in static info.

5.3

Requirements and Constraints
Data Object Layer allocation ensures power loss recovery (PLR) at the data object level. This guarantees the success of partial data writes for the Append command. For any replacement command, this also provides for either rolling back to old data or having all new data.

§§

58

Intel? Flash File System Core Reference Guide

Data Objects API Reference

Data Objects API Reference

6

The Data Object Layer provides a common structure organization for different types of data, such as static information, dynamic information, directory page, and file data. The Data Object Layer also provides a unified way to:

? Manipulate data ? Link separate logical units across multiple blocks to form integrated data ? Access the appropriate logical units irrespective of the data type.
Important: The RTOS Wrapper Interface is the primary interface to the Flash File System. As ports are made to other operating systems, the RTOS Wrapper Interface may be changed to provide for those OS needs. There may be a port of the RTOS Wrapper Interface for a specific OS; therefore, first check with an Intel representative. This Data Objects Layer is a Flash File System internal interface that may change and is provided only to enhance developer understanding of Flash File System functionality. This chapter lists and detailss each function, alphabetically. For quick reference, the Data Object Layer functions are listed in Table 4, “Data Objects Functions, Listed Alphabetically” on page 59. Error codes are listed in Section 6.26, “Error Codes” on page 87. The structures and defines used by the Data Object Layer functions are described in Chapter 15, “API Structures, Defines, and Enumerations.” Table 4. Data Objects Functions, Listed Alphabetically (Sheet 1 of 2)
Function Task Description Allocates an empty data object with size of one granularity. Calculates the amount of memory to reserve prior to actually writing anything to flash. Checks that allocation of the object is possible. Deletes an existing data object. Searches the partition beginning with the unit specified to locate and return a logical unit matching the criteria specified. Gets total byte size of an existing data object. Gets information, status, and type of root of the data object. Gets file system storage info, such as available space Initializes all internal data structures and lower levels and performs all data object PLR. Invalidates specified data objects. Invalidates new data, at hdr_allocating status, of a specified data object. Checks if size of last fragment and object level match data. Modifies an existing data object, starting at the given offset. Page 61 62 63 64 65 67 66 69 70 71 72 73 74

Function Name DO_AllocateDataObject DO_CalculateReserveSpace DO_CheckAvailableSpaceForObjects DO_DeleteDataObject DO_FindNextObject DO_GetDataObjectSize DO_GetObjectInfo DO_GetVolumeInfo DO_Init DO_InvalidateDataObject DO_InvalidateNewData DO_IsSizeMatched DO_ModifyDataObject

Intel? Flash File System Core Reference Guide

59

Data Objects API Reference

Table 4.

Data Objects Functions, Listed Alphabetically (Sheet 2 of 2)
Function Task Description Data recovery: Scans whole data object for PLR. Invalidates new data, at hdr_allocating status, of specific data object for power loss recovery. Truncates for power loss recovery. Truncates recovery: Allows caller to continue the truncate, which resulted in object level decrease. Reads data from existing data object starting at given offset. Shuts down data object layer. Reduces size of existing data object to the new size, which should not be zero (0) or larger than the existing size. Validates specified data objects. Validates new data. Writes data from given buffer to data object, starting at the given offset, or reserves space according to ‘size’ and ‘offset’. Page 75 76 77 78 79 80 81 82 83 84

Function Name DO_PLRDataRecovery DO_PLRInvalidateNewData DO_PLRTruncateDataObject DO_PLRTruncateRecovery DO_ReadDataObject DO_Shutdown DO_TruncateDataObject DO_ValidateDataObject DO_ValidateNewData DO_WriteDataObject

60

Intel? Flash File System Core Reference Guide

Data Objects API Reference

6.1

DO_AllocateDataObject
Allocates an empty data object with size of one unit granularity Syntax
FFS_Status DO_AllocateDataObject ( dst_unit_loc_ptr, src_unit_loc_ptr, dst_unit_type ); BA_UnitLocationPtr BA_UnitLocationPtr BA_UnitType

Parameters
Parameter dst_unit_loc_ptr Description (OUT) Pointer to a BA_UnitLocation structure. If no errors occur, the target structure is filled in before this function returns. The initial contents of the target structure are ignored. (See Section 15.1.2, “BA_UnitLocation” on page 250.) (IN) Pointer to a BA_UnitLocation structure. NULL indicates a new logical unit allocation. Otherwise, this points to the location of an original unit to be overwritten, truncated, or appended to. (See Section 15.1.2, “BA_UnitLocation” on page 250.) (IN) Specifies the type of logical unit to be allocated. (See(Section 15.1.4, “BA_UnitType typedef enum” on page 251.)

src_unit_loc_ptr

dst_unit_type

Error Codes/Return Values
FFS_StatusSuccess FFS_StatusInvalidParameter Success Failure (No change has been made.)

Description
The DO_AllocateDataObject function allocates an empty data object with size of one unit granularity. It is used together with the DO_ModifyDataObject function (Section 6.14, on page 6-74) and the DO_ValidateDataObject function (Section 6.24, on page 6-84) to create/ overwrite dynamic info or static info.

Intel? Flash File System Core Reference Guide

61

Data Objects API Reference

6.2

DO_CalculateReserveSpace
Calculates the amount of memory to reserve before writing to flash Syntax
FFS_Status DO_CalculateReserveSpace ( reserve_size_ptr, current_size, size_from_offset, offset, data_static_flag ); UINT32_PTR UINT32 UINT32 UINT32 UINT8

Parameters
Parameter reserve_size_ptr current_size Description (OUT) The number of units to be reserved. (IN) The size, in bytes, of the data buffer to be written. If the data_ptr is NULL this is amount of data to be blanked with 0xFFs. This size should also be the same size specified when reserving the memory. (IN) The offset, in bytes, of where to start writing the data. This offset must be within the existing size of the object. (IN) Existing data size in bytes. (IN) The flag indicates whether the data is static or dynamic. TRUE indicates that the data was only written once and never modified, meaning it can be written MLC. FALSE indicates that the data is dynamic or modifyable.

size_from_offset offset data_static_flag

Error Codes/Return Values
FFS_StatusSuccess FFS_StatusInvalidParameter Success Failure (No change has been made.)

Description
The DO_CalculateReserveSpace function calculates the amount of memory to reserve before actually writing anything to flash.

62

Intel? Flash File System Core Reference Guide

Data Objects API Reference

6.3

DO_CheckAvailableSpaceForObjects
Checks for allocation space Syntax
FFS_Status UINT32 DO_CheckAvailableSpaceForObjects ( object_count );

Parameters
Parameter object_count (IN) Number of units needed. Description

Error Codes/Return Values
FFS_StatusSuccess FFS_StatusMediaFull Success Failure (No change has been made.)

Description
The DO_CheckAvailableSpaceForObjects function checks if sufficient space exists for the allocation.

Intel? Flash File System Core Reference Guide

63

Data Objects API Reference

6.4

DO_DeleteDataObject
Removes the selected object and its overhead, freeing it for reclaim Syntax
FFS_Status DO_DeleteDataObject ( object, seq_table_level ); BA_UnitLocation UINT8

Parameters
Parameter object Description (IN) This value is used to locate the object that is to be deleted.This value can be determined using the FindNextObject function or the AllocateObject function. This information is also stored in the BA_UnitLocation value. (See Section 15.1.2, “BA_UnitLocation” on page 250.) (IN) Sequence table level.

seq_table_level

Error Codes/Return Values
FFS_StatusSuccess FFS_ErrorSystem FFS_StatusInvalidParameter Success Failure (No change has been made.) Failure (No change has been made.)

Description
The DO_DeleteDataObject function removes the selected object and the overhead associated with it, allowing it to be reclaimed and used for other data objects.

64

Intel? Flash File System Core Reference Guide

Data Objects API Reference

6.5

DO_FindNextObject
Finds the next data object with the specified type Syntax
FFS_Status DO_FindNextObject ( begin_object_ptr, next_object_ptr, object_type, object_status ); BA_UnitLocationPtr BA_UnitLocationPtr BA_UnitType BA_UnitStatus

Parameters
Parameter begin_object_ptr Description (IN) The location of the object at which to begin/continue the search. A value of NULL initiates a search all units from the beginning of the volume. (See Section 15.1.2, “BA_UnitLocation” on page 250.) (OUT) Upon success, the value pointed to is modified to specify the location of the next object found with that specified type. (See Section 15.1.2, “BA_UnitLocation” on page 250.) (IN) Specifies the type value to search for. If the value is BA_UnitTypeUnknown, then unit type is excluded from the search criteria. (See Section 15.1.4, “BA_UnitType typedef enum” on page 251.) (IN) Specifies the status value to search for. If the value is BA_UnitStatusUnknown, then unit status is excluded from the search criteria. See Section 15.1.3, “BA_UnitStatus typedef enum” on page 251.

next_object_ptr

object_type

object_status

Error Codes/Return Values
FFS_StatusSuccess FFS_StatusInvalidParameter Success Failure (No change has been made.)

Description
The DO_FindNextObject function is used for finding the next data object with the specified type.

Intel? Flash File System Core Reference Guide

65

Data Objects API Reference

6.6

DO_GetObjectInfo
Retrieves information, status, and type of the root of the data object Syntax
FFS_Status BA_UnitLocation BA_UnitType BA_UnitStatus DO_GetObjectInfo ( object_loc, *object_type_ptr, *object_status_ptr);

Parameters
Parameter object_loc object_type_ptr object_status_ptr Description (IN) The location of the data for which to get the status. (See Section 15.1.2, “BA_UnitLocation” on page 250.) (OUT) If not NULL upon successful return, indicates the type of the data specified. See Section 15.1.4, “BA_UnitType typedef enum” on page 251. (OUT) If not NULL upon successful return, contains the status of the data specified. See Section 15.1.3, “BA_UnitStatus typedef enum” on page 251.

Error Codes/Return Values
FFS_StatusSuccess FFS_StatusInvalidLogicalUnit FFS_StatusInvalidParameter Success Failure (No change has been made.) Failure (No change has been made.)

Description
The DO_GetObjectInfo function retrieves information, status, and type of the root of the data object.

66

Intel? Flash File System Core Reference Guide

Data Objects API Reference

6.7

DO_GetDataObjectSize
Returns the byte size of a selected object Syntax
FFS_Status DO_GetDataObjectSize ( size_ptr, object, object_level, last_frag_size, data_static_flag ); UINT32_PTR BA_UnitLocation UINT8 UINT32 UINT8

Parameters
Parameter size_ptr object Description (OUT) The byte size of the data portion of the object. (IN) Used to locate the object for which information will be returned. This value can be determined using the FindNextObject function or the AllocateObject function. This information is also stored in the BA_UnitLocation value. (See Section 15.1.2, “BA_UnitLocation” on page 250.) (IN) Sequence table level. (IN) Byte size of the last fragment. (IN) Indicates whether the data is static or dynamic. TRUE indicates that the data was only written once and never modified, meaning it can be written MLC. FALSE indicates that the data is dynamic or modifyable.

object_level last_frag_size data_static_flag

Error Codes/Return Values
FFS_StatusSuccess FFS_StatusEmptyTable FFS_StatusInvalidParameter Success Failure (No change has been made.) Failure (No change has been made.)

Description
The DO_GetDataObjectSize function returns the byte size of the selected object. This object can be located using the DO_FindDataObject function. The size of an object can also be located immediately after the DO_AllocateDataObject function (Section 6.1, on page 6-61) has completed and returned a newly allocated object.

Intel? Flash File System Core Reference Guide

67

Data Objects API Reference

6.8

DO_GetSeqTableInfo
Calculates the sequence table level and last fragment size Syntax
FFS_Status DO_GetSeqTableInfo ( last_fragment_size_ptr, seq_level_ptr, existing_data_size, data_static_flag ); UINT32_PTR UINT8_PTR UINT32 UINT8

Parameters
Parameter last_fragment_size_ptr seq_level_ptr existing_data_size data_static_flag Description (OUT) If not NULL upon successful return, reports the byte size of the last fragment. (OUT) If not NULL upon successful return, reports the sequence table level. (IN) Existing data size in bytes. (IN) The flag indicates whether the data is static or dynamic. TRUE indicates that the data was only written once and never modified, meaning it can be written MLC. FALSE indicates that the data is dynamic or modifyable.

Error Codes/Return Values
FFS_StatusSuccess Success

Description
The DO_GetSeqTableInfo function calculates the sequence table level and last fragment size, in bytes, according to the existing data size.

68

Intel? Flash File System Core Reference Guide

Data Objects API Reference

6.9

DO_GetVolumeInfo
Gets file system storage information Syntax
FFS_Status DO_GetVolumeInfo ( info_ptr ); FFS_VolumeInfoPtr

Parameters
Parameter info_ptr (OUT) File System information,. Description

Error Codes/Return Values
FFS_StatusSuccess FFS_StatusInvalidParameter Success Failure (No change has been made.)

Description
The DO_GetVolumeInfo function gets the file system storage information, such as available space.

Intel? Flash File System Core Reference Guide

69

Data Objects API Reference

6.10

DO_Init
Initializes all internal data structures and lower levels Syntax
FFS_Status DO_Init ( do_callback_fo_write_ptr, do_callback_fo_read_ptr, * volume_info_ptr, * format_ptr, * options_ptr, * init_info_ptr ); DO_CallbackWriteFunctionPtr DO_CallbackReadFunctionPtr void FFS_Format FFS_Options BA_InitInfo

Parameters
Parameter do_callback_fo_write_ptr do_callback_fo_read_ptr volume_info_ptr Description (IN) Pointer to the callback function for the Data Object Layer to the File Object Layer to update data object location and special information. (IN) Pointer to the callback function for the Data Object Layer to the File Object Layer to read special information of data. (IN) Volume information pointer. Must supply the address of a valid structure. The Data Object Layer does not use this information but simply passes it on to the Basic Allocation Layer initialization routines. (IN) The structure pointed to must contain valid format parameters for formatting the media if a format is to be performed. When this parameter is NULL, the file system will attempt to initialize using the volume’s existing format. If the volume is found to be unformatted or corrupt, initialization will fail and this function will return FFS_StatusInvalidMediaFormat. (See Section 15.2.2, “FFS_Format” on page 254.) (IN) Pointer to a valid, populated, file system options structure. The Data Object Layer does not use this information but simply passes it on to the Basic Allocation Layer initialization routines. (See Section 15.2.3, “FFS_Options” on page 254.) (OUT) Returns data byte size information and the location of any units of type root and type global that were found during initialization. (See Section 15.1.1, “BA_InitInfo” on page 249.)

format_ptr

options_ptr

init_info_ptr

Error Codes/Return Values
FFS_StatusSuccess FFS_StatusInvalidMediaFormat FFS_StatusInvalidParameter Success Failure (No change has been made.) Failure (No change has been made.)

Description
The DO_Init function initializes all internal data structures and lower levels.

70

Intel? Flash File System Core Reference Guide

Data Objects API Reference

6.11

DO_InvalidateDataObject
Invalidates an allocated or validated single logical unit Syntax
FFS_Status DO_InvalidateDataObject ( object ); BA_UnitLocation

Parameters
Parameter object Description (IN) Used to locate the object that is to be invalidated. This value can be determined using Allocate or a stored UnitLocation value. (See Section 15.1.2, “BA_UnitLocation” on page 250.)

Error Codes/Return Values
FFS_StatusSuccess Success

Description
The DO_InvalidateDataObject function invalidates the single instance data object that has been allocated or validated.

Intel? Flash File System Core Reference Guide

71

Data Objects API Reference

6.12

DO_InvalidateNewData
Invalidates new data, at hdr_allocating status, of specified data object Syntax
FFS_Status DO_InvalidateNewData ( object_loc, object_level, data_static_flag ); BA_UnitLocation UINT8 UINT8

Parameters
Parameter object_loc object_level data_static_flag Description (IN) Root of the object that contains data to be invalidated. (See Section 15.1.2, “BA_UnitLocation” on page 250.) (IN) Object level of the data. (IN) Indicates whether the data is static or dynamic. TRUE indicates that the data was only written once and never modified, meaning it can be written MLC. FALSE indicates that the data is dynamic or modifiable.

Error Codes/Return Values
FFS_StatusSuccess Success

Description
The DO_InvalidateNewData function invalidates new data, at hdr_allocating status of a specific data object. This function will not change the status of the root, so the caller must do this when appropriate.

72

Intel? Flash File System Core Reference Guide

Data Objects API Reference

6.13

DO_IsSizeMatched
Checks whether last fragment size and object level match data size Syntax
UINT8 DO_IsSizeMatched ( UINT32 UINT32 UINT8 UINT8 data_size, last_fragment_size, seq_level, data_static_flag );

Parameters
Parameter data_size last_fragment_size seq_level data_static_flag (IN) The data size in bytes. (IN) The byte size of the last fragment. (IN) The sequence table level. (IN) The flag indicates whether or not the data is static or dynamic. TRUE indicates that the data was only written once and never modified meaning it can be written MLC. FALSE indicates that the data is dynamic or modifiable. Description

Error Codes/Return Values
TRUE FALSE Match No match

Description
The DO_IsSizeMatched function checks whether the last fragment size and object level match the data size. If they match, this function returns TRUE. Otherwise, it returns FALSE.

Intel? Flash File System Core Reference Guide

73

Data Objects API Reference

6.14

DO_ModifyDataObject
Modifies data within an existing object Syntax
FFS_Status DO_ModifyDataObject ( data_ptr, object, size, offset, existing_data_size ); VOID_PTR BA_UnitLocation UINT32 UINT32 UINT32

Parameters
Parameter data_ptr object Description (IN) A pointer to the data buffer to be overwritten on the created object. If this value is NULL, the function returns an error. (IN) On entry, this value is used to locate the object that is to be modified. This value can be determined using the FindNextObject function or the AllocateObject function. This information is also stored in the BA_UnitLocation value. (See Section 15.1.2, “BA_UnitLocation” on page 250.) (IN) The size, in bytes, of the data buffer to be written. If the data_ptr is NULL this is amount of data to be blanked with 0xFFs.This size should also be the same size as the size specified when reserving the memory. (IN) The offset, in bytes, of where to start the write of the data. This offset plus size must be within the existing size of the object. (IN) Existing data size in bytes.

size

offset existing_data_size

Error Codes/Return Values
FFS_StatusSuccess FFS_StatusInvalidParameterr Success Failure (No change has been made.)

Description
The DO_ModifyDataObject function modifies data within an existing object. This function writes to the object without erasing the location, thereby allowing bit-twiddling within the flash media. This function will not allow additional data to be appended and requires no reserves.

74

Intel? Flash File System Core Reference Guide

Data Objects API Reference

6.15

DO_PLRDataRecovery
Scans the whole data object for power-loss-recovery Syntax
FFS_Status DO_PLRDataRecovery ( callback_info, object_ptr, object_level, data_static_flag ); FFS_DOCallbackInfo BA_UnitLocationPtr UINT8 UINT8

Parameters
Parameter callback_info object_ptr Description (IN) Information needed for callback function. This parameter is used in case of calling back to the File System. (IN/OUT) On entry, this value is used to locate the object that is to be scanned. On return, this value could be updated. (See Section 15.1.2, “BA_UnitLocation” on page 250.) (IN) The object level of the data. (IN) The flag indicates whether or not the data is static or dynamic. TRUE indicates that the data was only written once and never modified, meaning it can be written MLC. FALSE indicates that the data is dynamic or modifiable.

object_level data_static_flag

Error Codes/Return Values
FFS_StatusSuccess FFS_ParentReclaimNeeded FFS_StatusMediaFull Success Failure (No change has been made.) Failure (No change has been made.)

Description
The DO_PLRDataRecovery function scans the whole data object for power-loss-recovery (PLR). It will validate the new data of an append operation or invalidate the new data of a replace operation. The function may change the location of the data.

Intel? Flash File System Core Reference Guide

75

Data Objects API Reference

6.16

DO_PLRInvalidateNewData
Invalidates new data of a specified data object for power-lossrecovery Syntax
FFS_Status DO_PLRInvalidateNewData ( callback_info, object_ptr, object_level, data_static_flag ); FFS_DOCallbackInfo BA_UnitLocationPtr UINT8 UINT8

Parameters
Parameter callback_info object_ptr Description (IN) Information needed for callback function. This parameter is used in case of calling back to File System. (IN/OUT) On entry, this value is used to locate the object that is to be scanned. On return, this value could be updated. (See Section 15.1.2, “BA_UnitLocation” on page 250.) (IN) The object level of the data. (IN) The flag indicates whether or not the data is static or dynamic. TRUE indicates that the data was only written once and never modified meaning it can be written MLC. FALSE indicates that the data is dynamic or modifiable.

object_level data_static_flag

Error Codes/Return Value
FFS_StatusSuccess FFS_ParentReclaimNeeded Success Failure (No change has been made.)

Description
The DO_PLRInvalidateNewData function invalidates new data, at hdr_allocating status, of a specific data object for power loss recovery. The function may change the location of the data.

76

Intel? Flash File System Core Reference Guide

Data Objects API Reference

6.17

DO_PLRTruncateDataObject
Performs a truncate operation for power-loss-recovery Syntax
FFS_Status DO_PLRTruncateDataObject ( callback_info, object_ptr, new_size, orig_obj_level, update_size_info, data_static_flag ); FFS_DOCallbackInfo BA_UnitLocationPtr UINT32 UINT8 UINT8 UINT8

Parameters
Parameter callback_info Description (IN) Information needed for callback function.This parameter is used in case of calling back to File System. (IN/OUT) On entry, this value is used to locate the object that is to be truncated. This value can be determined using the FindNextObject function or the AllocateObject function. This information is also stored in the BA_UnitLocation value. On return and if the object was moved, this value will contain an updated value to the data location. (See Section 15.1.2, “BA_UnitLocation” on page 250.) new_size orig_obj_level update_size_info data_static_flag (IN) This value is used to indicate the new truncated size of the object. (IN) The object level of existing data. (IN) Flag indicates if size info update is needed. If TRUE, then size info will always be updated. (IN) The flag indicates whether or not the data is static or dynamic. TRUE indicates that the data was only written once and never modified, meaning it can be written MLC. FALSE indicates that the data is dynamic or modifiable.

object_ptr

Error Codes/Return Value
FFS_StatusSuccess FFS_ParentReclaimNeeded Success Failure (No change has been made.)

Description
The DO_PLRTruncateDataObject function performs the truncate operation for power-lossrecovery (PLR).

Intel? Flash File System Core Reference Guide

77

Data Objects API Reference

6.18

DO_PLRTruncateRecovery
Allows the caller to continue a truncate Syntax
FFS_Status DO_PLRTruncateRecovery ( callback_info, orig_root_ptr, new_root, new_size, orig_obj_level, data_static_flag ); FFS_DOCallbackInfo BA_UnitLocationPtr BA_UnitLocation UINT32 UINT8 UINT8

Parameters
Parameter callback_info Description (IN) Information needed for callback function.This parameter is used in case of calling back to File System. (IN) On entry, this value is used to locate the old object that is to be truncated. If the old root doesn't exist, this should be NULL. (See Section 15.1.2, “BA_UnitLocation” on page 250.) (IN) New root of the data object. (See Section 15.1.2, “BA_UnitLocation” on page 250.) (IN) This value is used to indicate the new truncated size of the object. (IN) The object level of the original data. If orig_root_ptr is NULL, then this value will be ignored. (IN) The flag indicates whether or not the data is static or dynamic. TRUE indicates that the data was only written once and never modified, meaning it can be written MLC. FALSE indicates that the data is dynamic or modifiable.

orig_root_ptr new_root new_size orig_obj_level data_static_flag

Error Codes/Return Value
FFS_StatusSuccess FFS_ParentReclaimNeeded Success Failure (No change has been made.)

Description
The DO_PLRTruncateRecovery function allows the caller to continue the truncate, which had resulted in an object level decrease. If the original root does not exist, orig_root_ptr should be NULL and old_level will be ignored.

78

Intel? Flash File System Core Reference Guide

Data Objects API Reference

6.19

DO_ReadDataObject
Reads data from an existing object, starting at the given offset Syntax
FFS_Status DO_ReadDataObject ( data_ptr, object, size_ptr, offset, existing_data_size, data_static_flag ); VOID_PTR BA_UnitLocation UINT32_PTR UINT32 UINT32 UINT8

Parameters
Parameter data_ptr object Description (OUT) A pointer to the data buffer to be overwritten with the data read from the object. A NULL value will cause this function to return an invalid parameter error. (IN) This value is used to locate the object that is to be read.This value can be determined using the FindNextObject function or the AllocateObject function. This information is also stored in the BA_UnitLocation value. (See Section 15.1.2, “BA_UnitLocation” on page 250.) (IN) The size, in bytes, of the amount of data to be read from the object and placed into the data buffer. (IN) The offset, in bytes, of where to start the read of the data. If this offset plus size is beyond the end of the object, an error will be returned and the data will not be read. (IN) The existing data size in bytes. (IN) The flag indicates whether or not the data is static or dynamic. TRUE indicates that the data was only written once and never modified, meaning it can be written MLC. FALSE indicates that the data is dynamic or modifiable.

size_ptr offset existing_data_size data_static_flag

Error Codes/Return Value
FFS_StatusSuccess FFS_StatusInvalidParameter Success Failure (No change has been made.)

Description
The DO_ReadDataObject function reads data from an existing object, starting at the given offset.

Intel? Flash File System Core Reference Guide

79

Data Objects API Reference

6.20

DO_Shutdown
Shuts down the data object module to free allocated resources Syntax
FFS_Status DO_Shutdown ( void );

Parameters
None

Error Codes/Return Values
FFS_StatusSuccess Success

Description
The DO_Shutdown function is called to shut down the data objects module and free any allocated resources.

80

Intel? Flash File System Core Reference Guide

Data Objects API Reference

6.21

DO_TruncateDataObject
Allows the caller to reduce an allocated object’s size Syntax
FFS_Status DO_TruncateDataObject ( callback_info, object_ptr, new_size, existing_data_size, data_static_flag ); FFS_DOCallbackInfo BA_UnitLocationPtr UINT32 UINT32 UINT8

Parameters
Parameter callback_info object_ptr Description (IN) Information needed for callback function. This parameter is used in case of calling back to File System. (IN/OUT) On entry, this value is used to locate the object that is to be truncated. This value can be determined using the FindNextObject function or the AllocateObject function. This information is also stored in the BA_UnitLocation value. On return and if the object was moved, this value will contain an updated value to the data location. (See Section 15.1.2, “BA_UnitLocation” on page 250.) new_size existing_data_size data_static_flag (IN) This value is used to indicate the new truncated size of the object. This value should not be zero (IN) The existing data size in bytes. (IN) The flag indicates whether or not the data is static or dynamic. TRUE indicates that the data was only written once and never modified, meaning it can be written MLC. FALSE indicates that the data is dynamic or modifiable.

Error Codes/Return Values
FFS_StatusSuccess FFS_StatusInvalidParameter FFS_ParentReclaimNeeded Success Failure (No change has been made.) Failure (No change has been made.)

Description
The DO_TruncateDataObject function allows the caller to reduce an allocated object's size. Reducing the size of the existing data causes the data at the end of the object to be lost. If the new size is zero (0) or larger than the existing size, this function causes an error to be returned; when the new size is zero (0), the caller needs to call the DO_DeleteDataObject (Section 6.4, on page 6-64)function instead. Note: To increase an allocated object’s size, use the DO_WriteDataObject (Section 6.24, on page 6-84) to append data.

Intel? Flash File System Core Reference Guide

81

Data Objects API Reference

6.22

DO_ValidateDataObject
Validates the single instance data object that has been allocated Syntax
FFS_Status DO_ValidateDataObject ( object); BA_UnitLocation

Parameters
Parameter object Description (IN) Used to locate the object that is to be validated.This value can be determined using Allocate or a stored UnitLocation value. (See Section 15.1.2, “BA_UnitLocation” on page 250.)

Error Codes/Return Values
FFS_StatusSuccess Success

Description
The DO_ValidateDataObject function validates the single instance data object that has been allocated

82

Intel? Flash File System Core Reference Guide

Data Objects API Reference

6.23

DO_ValidateNewData
Validates new data of a specified data object Syntax
FFS_Status DO_ValidateNewData ( object_loc, object_level, data_static_flag ); BA_UnitLocation UINT8 UINT8

Parameters
Parameter object_loc object_level data_static_flag Description (IN) The root of the object that contains data to be validated. (See Section 15.1.2, “BA_UnitLocation” on page 250.) (IN) The object level of the data. (IN) The flag indicates whether or not the data is static or dynamic. TRUE indicates that the data was only written once and never modified meaning it can be written MLC. FALSE indicates that the data is dynamic or modifiable.

Error Codes/Return Values
FFS_StatusSuccess Success

Description
The DO_ValidateNewData function validates new data, at hdr_allocating status, of a specific data object. It also invalidates any old data that has been replaced by the new data. This function won't change the status of the root, so caller needs to do this when appropriate.

Intel? Flash File System Core Reference Guide

83

Data Objects API Reference

6.24

DO_WriteDataObject
Writes data from a specified buffer to a data object Syntax
FFS_Status DO_WriteDataObject ( callback_info, object_ptr, data_ptr, size, offset, existing_data_size, bytes_written_ptr, size_changed_ptr, root_replaced_ptr, trans_flag, data_static_flag ); FFS_DOCallbackInfo BA_UnitLocationPtr VOID_PTR UINT32 UINT32 UINT32 UINT32_PTR UINT8_PTR UINT8_PTR UINT8 UINT8

Parameters
Parameter callback_info object_ptr Description (IN) Information needed for callback function. This parameter is used in case of calling back to the File System. (IN/OUT) On entry, this value is used to locate the object that is to be written. This value can be determined using the FindNextObject function or the AllocateObject function. This information is also stored in the BA_UnitLocation value. On return and if the object was moved, this value will contain an updated value to the data location. (See Section 15.1.2, “BA_UnitLocation” on page 250.) data_ptr size (IN) A pointer to the data buffer to be written to the created object. If this value is NULL, 0xFF (an erased state) will be written to the object. (IN) The size, in bytes, of the data buffer to be written. If the data_ptr is NULL, this is amount of data to be blanked with 0xFFs. This should also be the same size as that specified when reserving the memory. (IN) The offset, in bytes, of where to start the write of the data. This offset must be within the existing size of the object. (IN) The existing data size in bytes. (OUT) The number of bytes written. (OUT) On return, if size info is changed and trans_flag is TRUE, this flag will be set to TRUE. On entry, if size info has been changed and trans_flag is TRUE, this flag should be set to TRUE. This is used only for transaction. For non-transaction, the pointer should be NULL.

offset existing_data_size bytes_written_ptr size_changed_ptr

84

Intel? Flash File System Core Reference Guide

Data Objects API Reference

Parameter root_replaced_ptr

Description (IN/OUT) This is used only for transaction. For non-transaction, the pointer should be NULL. This flag will be set to TRUE if the root of the object, which is valid, is replaced during the write operation. Otherwise, this function will not change the initial value of the flag. (IN) Flag indicating if this operation is transacted. (IN) The flag indicates whether or not the data is static or dynamic. TRUE indicates that the data was only written once and never modified, meaning it can be written MLC. FALSE indicates that the data is dynamic and modifiable.

trans_flag data_static_flag

Error Codes/Return Values
FFS_StatusSuccess FFS_StatusInvalidParameter FFS_StatusInvalidTableLevel FFS_StatusMediaFull FFS_ParentReclaimNeeded Success Failure (No change has been made.) Failure (No change has been made.) Failure (No change has been made.) Failure (No change has been made.)

Description
The DO_WriteDataObject function writes data from the given buffer to a data object, starting at the given offset. If the data buffer pointer is not offered, it reserves the space needed, and the caller can later modify the reserved space.

Intel? Flash File System Core Reference Guide

85

Data Objects API Reference

6.25
6.25.1

Using the Write-Related Data Objects API
Creating Dynamic Information (Static Information)
DO_AllocateDataObject(obj_ptr); DO_ModifyDataObject(buffer_ptr, *obj_ptr, size, offset); DO_ValidateDataObject(obj_ptr);

6.25.2

Creating a Directory
DO_WriteDataObject (file_handle_ptr, obj_ptr, NULL, DIR_PAGE_SIZE, 0, 0, bytes_written_ptr);

6.25.3

Adding One Entry to a Directory With a Free Entry
DO_ModifyDataObject(buffer_ptr, *object_ptr, size, offset);

6.25.4

Adding One Entry to a Directory With No Free Entry
DO_WriteDataObject(file_handle_ptr, obj_ptr, NULL, DIR_PAGE_SIZE, existing_size, existing_size, bytes_written_ptr); DO_ModifyDataObject(buffer_ptr, *object_ptr, size, offset);

6.25.5

Writing File Data
DO_WriteDataObject(file_handle_ptr, obj_ptr, buffer_ptr, size, offset, existing_size, bytes_written_ptr);

6.25.6

Compile Time Options
#define DO_PARAM_CHECKING TRUE /* Setting this definition enables and disables any additional parameter checking done within the module */

86

Intel? Flash File System Core Reference Guide

Data Objects API Reference

6.26

Error Codes
Table 5. Error Codes
Meaning Success Failure (No change has been made.) Failure (No change has been made.) Failure (No change has been made.) Failure (No change has been made.) Failure (No change has been made.) Failure (No change has been made.) Failure (No change has been made.) Failure (No change has been made.)

Error Name FFS_StatusSuccess FFS_StatusInvalidParameter FFS_StatusMediaFull FFS_ErrorSystem FFS_StatusInvalidLogicalUnit FFS_StatusEmptyTable FFS_StatusInvalidMediaFormat FFS_ParentReclaimNeeded FFS_StatusInvalidTableLevel

§§

Intel? Flash File System Core Reference Guide

87

Data Objects API Reference

88

Intel? Flash File System Core Reference Guide

Basic Allocation Layer

Basic Allocation Layer

7

The Basic Allocation Layer, shown in Figure 7, “Flash File System Components” on page 90, interfaces with the Reclaim Manager, Data Objects Layer, and Flash Interface Layer.It is the component in the Flash File System that manages allocation of flash memory within a given preestablished volume. The Basic Allocation Layer accesses flash through the Flash Interface Layer therefore it is not concerned with the specifics of the device actually being written to. In addition to interfacing with the upper-layer Data Objects Layer, the Basic Allocation Layer interfaces with the Reclaim Module to perform a block reclaim. Reclaim is accomplished by assigning a logical block number to each physical erase block within the volume. Basic Allocation further divides and allocates the flash memory in each logical block into smaller logical units of equal and predetermined size. It keeps track of these individual logical units and their immediate status, such as allocating, valid, and invalid. Basic Allocation allocates units on requests from the Data Objects Layer, one logical unit at a time and is responsible for PLR on a single unit. It is unaware of whether a given unit is a sequence table, static file information, or dynamic file information. It keeps track of the free and dirty space in every erase block in the managed space. Refer to Chapter 15, “API Structures, Defines, and Enumerations” for API structure details.

Intel? Flash File System Core Reference Guide

89

Basic Allocation Layer

Figure 7. Flash File System Components

OS File System API

Real-time Operating System (RTOS) Wrapper Interface OS Resources Translation Layer

RAM FIFO Buffer

File System Layer

Data Objects Layer Flash File System Core Basic Allocation Layer Reclaim Module

Flash Interface Layer

OS Specific Layer

Translation Layer

Low-Level

Flash Hardware

7.1

Functionality
Most flash memory devices are internally partitioned into one or more physical units, known as erase blocks. An erase block is the smallest, most discreet, erasable portion of a flash memory device. In high-density flash memory devices, these erase blocks are typically 64 KB or greater in size. However, most applications involving data storage require the ability to store data objects that are much smaller than the size of the erase blocks. To do this efficiently, the Basic Allocation Layer divides each erase block into smaller logical units. The Basic Allocation Layer components are listed below and shown in Figure 8, “Basic Allocation Components” on page 91.

? Application Program Interface (BA_API): The API component defines the external
interface for the Basic Allocation Layer. It is used by upper file system layers to allocate flash memory for the storage of file system data.

90

Intel? Flash File System Core Reference Guide

OS External Libraries

Basic Allocation Layer

? Logical Volume (BA_LV): The Logical Volume component contains the information and
functionality needed to manage a logical volume.

? Logical Block (BA_LB): The Logical Block component manages logical to physical block
mappings and the amount of unallocated and dirty (invalid) space within each block.

? Physical Block (BA_PB: The Physical Block component manages the block format, status,
and other information, which is written within each physical erase block.

? Logical Unit (BA_LU): The Logical Unit component provides the basic functionality
necessary to read and write a logical unit's type, status, and data.

? Flash Interface (BA_FI): The Flash Interface component writes data to and reads data from
flash device according to the device's capabilities and limitations.

? EDAC (BA_EDAC): The EDAC component contains the algorithms needed to expand data
being written to or compress data being read from a flash device that supports error detection and correction. Figure 8. Basic Allocation Components
Data Objects Layer

Basic Allocation API (BA_API)

Logical Volume (BA_LV)

Logical Block (BA_LB) Reclaim

Physical Block (BA_PB)

Logical Unit (BA_LU)

Flash Interface (BA_FI)

EDAC (BA_EDAC)

Flash Interface Layer

Basic Allocation provides the following functionality:

? Maintains a logical block table (LBT) in RAM that monitors free and dirty space in each block
and the physical to logical block mapping. It also monitors the location of empty or available units in each block by a next unallocated index within the LBT, which gets moved to the next unallocated each time a unit gets allocated. The next unallocated unit is found by a simple incremental search through the logical unit headers.

? Allocates logical units on request from the Data Objects Layer.
Intel? Flash File System Core Reference Guide

91

Basic Allocation Layer

? Writes data from RAM or flash into logical units within the flash volume. ? Supports replacing all or part of the data within a logical unit by copying over any valid
portion of the data to a new logical unit along with any new data that is part of the replacement. The functionality provides truncate, append, and replace operations.

? Reads data from logical units in flash into a given RAM buffer. ? Writes the block information structure during a format operation and updates the structure
during reclaim.

? During initialization, Basic Allocation calls the Flash Interface Layer initialization function to
perform lower level initialization. It is also responsible for building the logical block table and starting the background reclaim task.

7.1.1

Application Program Interface (BA_API)
The Application Programming Interface (BA_API) component defines the external functions used by the higher-layer modules interface with the Basic Allocation Layer to allocate flash memory for storing file system data.

7.1.2

Logical Volume (BA_LV)
The Logical Volume (BA_LV) component maintains the information and defines the functionality needed to manage a logical volume. This component keeps track of the configured dynamics of the volume, such as the number of logical blocks within the volume and the fragment granularity with which the volume was formatted.

7.1.3

Logical Block (BA_LB)
The use of the Logical Block (BA_LB) component is critical to the reclaim process. Every time the Basic Allocation Layer performs a reclaim on an erase block, the content of the reclaim block (the source block) is transferred to a different physical block (the destination block). As a result, data written to flash memory rarely stays in the same physical block it was originally written to. See Figure 9, “Before Reclaim — After Reclaim” on page 93. If a pointer to a unit header references a specific physical erase block, the pointer becomes invalid the moment a reclaim is performed on the specified block. Furthermore, the selection of this new physical erase block is random, being simply another data block selected for reclaim. An erase block is designated for reclaim based on the quantity of invalid space it contains. That is determined by how frequently the system deletes or updates the data stored in that block. Since memory usage varies greatly from application to application, it is impossible for the Basic Allocation Layer to determine beforehand which erase blocks will be designated for reclamation. Instead, a logical blocking scheme is used. During the reclaim process, each physical erase block within a volume, except for the destination block, is assigned a unique logical block number. The logical block number for each erase block is stored in the erase block itself within the block information structure. Then, when reclaim is performed on a physical erase block, its logical block number is copied (along with the valid data) to the destination block as part of the reclaim process. Thus, the logical block number "follows" the data in the erase block as that data is moved by reclaim. Figure 9, “Before Reclaim — After Reclaim” on page 93 illustrates this concept. For more information on block reclaim, refer to the Chapter 9, “Reclaim Module.”

92

Intel? Flash File System Core Reference Guide

Basic Allocation Layer

Figure 9. Before Reclaim — After Reclaim
Before Reclaim After Reclaim

(Physical Block #1)

Destination Block

(Physical Block #1) (Physical Block #2) (Physical Block #3)

Logical Block #1

(Physical Block #2)

Logical Block #1

Destination Block

(Physical Block #3)

Logical Block #2

Logical Block #2

The logical blocking scheme implements a high-level pointer to a unit header, which indicates the logical block (instead of the physical block) in which the unit header resides. This logical block number will always indicate the correct unit header because the logical block number associated with the unit header in a given erase block is constant, regardless of the physical block the data is stored in. When the Basic Allocation Layer accesses a unit header using this high-level pointer, it must perform a logical-to-physical translation of the erase block number because the erase block number references a logical erase block while a physical block number is required to access the flash memory array. The logical-to-physical translation can occur by examining the contents of the block information structure for each erase block to find the specified logical block number. However, this is.extremely inefficient, especially since the logical-to-physical translation is frequently performed.

Intel? Flash File System Core Reference Guide

93

Basic Allocation Layer

For efficiency, the Logical Block component maintains logical-to-physical block mappings along with the amount of unallocated and invalid space within each block. To improve performance, a lookup table, called the logical block table, is maintained in system memory (RAM). This table implements an array of logical block information structures, one for every logical block. The most important piece of information stored in the logical block information structure is the physical block number.

7.1.4

Physical Block (BA_PB)
The Physical Block component manages control information for each physical block within a configured volume. It includes the functionality needed to format a block for use within a volume and to support block reclaim activities. It does this by writing and maintaining a block information structure at offset 0x00000000 of each physical erase block. This block information structure contains information about the physical block and the volume in which it resides. It also contains these current logical block assignment information and the current status of the block:

? ? ? ?

Physical Block: PB_BlockInfo.PB_PhysicalBlockInfo Physical Block’s volume: PB_BlockInfo.PB_PhysicalBlockInfo.PB_VolumeInfo Current logical block assignment information: PB_BlockInfo.PB_LogicalBlockInfo Current status of the block: PB_BlockInfo.PB_PhysicalBlockInfo.Status

It also includes a back-up mechanism used during reclaim. If a power loss were to occur, the recovery process restores physical block information that otherwise would be lost. The structure incorporates checksums and integrity fields so that the file system can detect any corruption to the structure. A version field is included within the physical block information so that if the structure or the format of the block is modified, the file system can detect and handle both the old and new format, if necessary.

94

Intel? Flash File System Core Reference Guide

Basic Allocation Layer

7.1.4.1

PB_VolumeInfo
The PB_VolumeInfo structure stores information about the volume (BA_PB.H).

Warning: Table 6.

Structure must be DWORD aligned, and the order must not change because it is written to flash. PB_VolumeInfo Structure typedef struct { UINT32 UINT16 UINT16 UINT16 UINT16 UINT16 UINT16 } PB_VolumeInfo; BlockByteSize; PhysicalBlockCount; LogicalBlockCount; UnitByte Size; UnitCountPerBlock; UnitsOverheadPerBlock; EDACWindowByteSize;

Member BlockByteSize PhysicalBlockCount LogicalBlockCount UnitByteSize UnitCountPerBlock UnitsOverheadPerBlock

Description The byte size of each physical/logical block within the volume. The number of physical erase blocks within the volume. The number of logical blocks within the volume. The bytes size of each logical unit. The number of logical units per block. The number of units held in overhead, per block. This number indicates that units can be overwritten when the media is full, thereby improving write performance as the flash data volume fills up. WARNING: Structure must be DWORD aligned, and the order of its members must not change because it is written to flash.

EDACWindowByteSize

Intel? Flash File System Core Reference Guide

95

Basic Allocation Layer

7.1.4.2

PB_PhysicalBlockInfo
The PB_PhysicalBlockInfo structure stores "physical" information for the erase block including volume information, erase count, and physical block index. (BA_PB.H)

Table 7.

PB_PhysicalBlockInfo Structure typedef struct { UINT32 UINT16 UINT16 PB_VolumeInfo UINT32 UINT16 UINT16 } PB_PhysicalBlockInfo; Integrity; Version; Reserved; VolumeInfo; EraseCount; Index; CheckSum;

Member Integrity

Description Contains the constant value 0xF0F0F0F0. This is used to locate, validate the integrity of, and determine the exact status of the information contained within the block information structure. Contains a value indicating the version of the file system for which this structure is formatted for. Reserved. Contains information about the logical volume in which the block resides as defined in BA_LV.H. Contains the number of times this block has been erased. For use by block reclaim wear-leveling algorithms. The physical index of this erase block within its logical volume. Contains a value that when added to the sum of the previous members in this structure equals a predetermined constant value (PB_ChecksumSignature). Note that the checksum does NOT include itself.

Version Reserved VolumeInfo EraseCount Index

Checksum

96

Intel? Flash File System Core Reference Guide

Basic Allocation Layer

7.1.4.3

PB_LogicalBlockInfo
The PB_LogicalBlockInfo structure stores the logical block information for the erase block. This information can be validated using the included checksum. (BA_PB.H)

Table 8.

PB_LogicalBlockInfo Structure typedef struct { UINT16 UINT16 } PB_LogicalBlockInfo; Index; CheckSum;

Member Index

Description The logical index of this erase block within its logical volume. The logical spare block should contain the value 0xFFFF. Contains a value that when added to the sum of the previous members in this structure equals a predetermined constant value (PB_ChecksumSignature). Note that the checksum does NOT include itself. The logical spare block should contain the value 0xFFFF.

Checksum

Intel? Flash File System Core Reference Guide

97

Basic Allocation Layer

7.1.4.4

PB_ReclaimBlockInfo
The PB_ReclaimBlockInfo structure is used to back up information during block reclaim for both the spare block and the reclaim block to ensure that the information is not lost if power loss occurs (BA_PB.H).

Table 9.

PB_ReclaimBlockInfo Structure typedef struct { UINT32 UINT16 UINT16 } PB_ReclaimBlockInfo; EraseCount; Index; Reserved;

Member EraseCount Index Reserved

Description Contains a copy of the erase count for the block specified by Index. Contains the physical index of the block within the logical volume. Reserved.

98

Intel? Flash File System Core Reference Guide

Basic Allocation Layer

7.1.4.5

PB_BlockInfo
The PB_BlockInfo structure contains status and format information about an erase block. This structure is written to every erase block that is managed by the Basic Allocation Layer. This information can be validated using the included checksum. (BA_PB.H)

Table 10. PB_BlockInfo Structure typedef struct { PB_PhysicalBlockInfo PB_LogicalBlockInfo struct { PB_ReclaimBlockInfo PB_ReclaimBlockInfo } Reclaim; UINT16 UINT16 } PB_BlockInfo; Reserved; Status; Src; Dst; Physical; Logical;

Member Physical Logical Src

Description Stores the information that establishes an erase block as a "physical block" within a given logical volume in flash. Stores the information that defines an erase block as a "logical block" within a predefined logical volume in flash. During a reclaim, this member is used to backup information about the physical block being reclaimed, known as the source reclaim block. In the event of power loss during reclaim, this information is used to restart any incomplete block reclaim tasks. Once reclaim is complete this contains information about the physical block at which the associated logical block was last located. During a reclaim, this member is used to backup information about the physical block the logical block is being relocated to, known as the destination reclaim block or logical spare block. In the event of power loss during reclaim, this information is used to restart any incomplete block reclaim tasks. Reserved. Contains the current status of the erase block as defined by the PB_Status enumeration.

Dst

Reserved Status

Intel? Flash File System Core Reference Guide

99

Basic Allocation Layer

7.1.5

typedef enum PB_Status
The typedef enum PB_Status defines the different status values for a block. Each status uses two bits so that if power is lost during a write, it can be detected and corrected during power loss recovery. (BA_PB.H)

Table 11. PB_Status typedef enum typedef enum { PB_StatusInvalid PB_StatusSpare PB_StatusRelocating PB_StatusRelocated PB_StatusErasing PB_StatusErased PB_StatusValid PB_StatusSelecting PB_StatusSelected } PB_Status; = 0xffff, = 0xfffc, = 0xfff0, = 0xffc0, = 0xff00, = 0xfc00, = 0xf000, = 0xc000, = 0x0000

100

Intel? Flash File System Core Reference Guide

Basic Allocation Layer

7.1.6

Logical Unit (BA_LU)
Each physical erase block within an established volume of flash memory is organized into multiple minimal units of allocation referred to as logical units. (See Figure 10, “Logical Units” on page 102.) Each logical unit consists of a header and a configurable fixed amount of data space. The header is used to store type and status information associated with the data contained within its associated logical unit of allocation. Logical units are referenced by a logical location consisting of a logical block number and logical unit index. The Logical Unit component provides the basic functionality necessary to read and write data to a specified logical unit along with its associated type and status information. The Basic Allocation Layer further divides the flash memory in each logical block into smaller units of allocation of predetermined size called logical units. The size of each logical unit is governed by the configured "FragmentGranularity" passed in as a number of bytes at system initialization. Space within the volume is allocated one logical unit at a time. Each logical unit consists of a header and a configurable fixed amount of data space. The format of each physical erase block is shown in Figure 10, “Logical Units” on page 102, where the first logical unit of space is reserved for the allocation control structures. When a volume is formatted, each erase block within the configured volume has a block information structure written to it at offset 0x00000000. The logical unit headers begin at an offset equal to half the configured size of a logical unit (FFS_Format.FragmentGranularity / 2). The logical unit data then begins at an offset equal the size of one fragment granularity (FFS_Format.FragmentGranularity). The header is used to store type and status information associated with the data contained within its associated logical unit of allocation. Logical units are referenced by logical location consisting of a logical block number and logical unit index. The Logical Unit component provides the basic functionality necessary to read and write data to a specified logical unit along with its associated type and status information. The valid types of logical units are as follows:

? BA_UnitTypeData: The logical unit contains file system data. ? BA_UnitTypeFileDir: The logical unit contains file or directory control information. ? BA_UnitTypeGlobal: Used to store information that is global to the file system volume. Only
one valid logical unit of this type should exist within each volume.

? BA_UnitTypeRoot: Used to demarcate the logical unit containing the root object of the
volume. Only one valid logical unit of this type should exist within each volume. A logical unit's status is kept in its associated header and is used to track the current state of the data it stores. A logical unit is marked:

? ? ? ?

Unallocated: Initial erased state Allocated: Allocated by calling BA_AllocateUnit() Valid: When BA_ValidateUnit() is called Invalid: When BA_InvalidateUnit() is called

Headers are dynamic data. The value of the header changes as the status of the logical unit is updated, therefore, headers are subject to EDAC restrictions with devices that feature EDAC.

Intel? Flash File System Core Reference Guide

101

Basic Allocation Layer

Figure 10. Logical Units
0x00000000

Block Information Structure

FFS_Format.FragmentGranularity / 2

Unit Header 1

Unit Header 2

Unit Header 3

FFS_Format.FragmentGranularity

Logical Unit 1

FFS_Format.FragmentGranularity * 2

Logical Unit 2

7.1.7

Flash Interface (BA_FI)
The Flash Interface component writes data to and reads data from the flash device according to the device's capabilities and limitations.

7.1.8

EDAC (BA_EDAC)
The EDAC component contains the algorithms needed to expand data being written to or compress data being read from a flash device that supports error detection and correction.

? Static data, which cannot be modified once written, can be written to a multi-level cell (MLC)
flash device as MLC data.

? Dynamic data, which can be modified, can also be written to an MLC flash device as MLC
data unless the device features EDAC. If the device features EDAC. the Flash Interface Basic Allocation Layer component will use the EDAC Basic Allocation Layer component to write dynamic data to flash as PSBC data. This leaves invalid zones empty, in their erased states, and writes data only to the valid data zones for PSBC mode writes.

102

Intel? Flash File System Core Reference Guide

Basic Allocation Layer

Note:

See the particular device documentation for device-specific information on the size of these valid and invalid zones when writing data in PSBC mode.

7.2

Basic Allocation Layer Interface
The basic flow of use for the Basic Allocation Layer interface is as follows: 1. Allocates a logical unit (BA_AllocateUnit). 2. Writes data to the logical unit using one of the functions provided and according to the type of data being written and the source of the data (BA_CopyUnitData, BA_ReplaceUnitData, BA_ModifyUnitData, BA_WriteUnitData). 3. Validates the logical unit (BA_ValidateUnit). 4. Reads data from the logical unit, as needed (BA_ReadUnitData). 5. When the unit is no longer valid, invalidates it (BA_InvalidateUnit). There are two types of data that can be written to a logical unit:

? Static data: Not modifiable and written to flash using the device multi-level cell (MLC)
capabilities, if the device is not EDAC enabled.

? Dynamic data: Can be modified and written to flash as MLC data using the device multi-level
cell (MLC) capabilities, except for an EDAC-compliant flash device. The EDAC-compliant device requires that dynamic data be written in pseudo single-bit per cell (PSBC) mode. The BA_ModifyUnitData API can be used only when writing and modifying dynamic data to a logical unit. When using the other three APIs which can write data to a logical unit (BA_CopyUnitData, BA_ReplaceUnitData, and BA_WriteUnitData), the type of data written must be specified. The Basic Allocation structures, typedefs, enumerations, #defines, compile options, and macros are explained in Chapter 15, “API Structures, Defines, and Enumerations”.

7.3

Other Component Dependency/Inter-Relationship
The Basic Allocation Layer functions are called by the Data Objects Layer and the Reclaim Module to perform the following:

? Allocates, reads, or writes a unit of data and determines the available space in the media per
call by the Data Objects Layer.

? Maintains the logical block table, which maps physical to logical blocks and also keeps track
of free and dirty space on flash. Note that the Reclaim Module calls the Basic Allocation Layer to update the free and dirty space in a block after reclaim operations are completed.

? Calls into the Flash Interface Layer, passing a volume offset, to perform writes or reads. The
Flash Interface Layer stores information about the beginning address of the volume, and so using this information and the volume offset, calculates the address for reading/writing.

§§

Intel? Flash File System Core Reference Guide

103

Basic Allocation Layer

104

Intel? Flash File System Core Reference Guide

Basic Allocation API Reference

Basic Allocation API Reference

8

The Basic Allocation Layer divides a physical erase block into units of equal size and keeps track of individual units and their immediate status, such as allocating, valid, and invalid. It allocates units on requests from the Data Objects Layer and is responsible for PLR on a single unit, regardless whether a given unit is a sequence table, static file information, or dynamic file information. It keeps track of the free and dirty space in every erase block in the managed space. Important: The RTOS Wrapper Interface is the primary interface to the Flash File System. As ports are made to other operating systems, the RTOS Wrapper Interface may be changed to provide for those OS needs. There may be a port of the RTOS Wrapper Interface for a specific OS; therefore, please check with an Intel representative. This Basic Allocation Layer is a Flash File System internal interface that may change and is provided only to enhance developer understanding of Flash File System functionality. This chapter lists and describes each function, in detail, alphabetically. For quick reference, the Basic Allocation Layer functions are listed Table 12, “Basic Allocation Functions, Listed Alphabetically” on page 105. Error codes are listed in Section 8.16, “Error Codes” on page 123. The structures and defines used by the Basic Allocation Layer functions are described in Chapter 15, “API Structures, Defines, and Enumerations.” Table 12. Basic Allocation Functions, Listed Alphabetically (Sheet 1 of 2)
Function (Ordered Alphabetically) BA_AllocateUnit BA_CopyUnitData BA_FindNextUnit BA_GetUnitsAvailable BA_GetUnitsInfo BA_GetUnitsInvalid BA_GetUnitsTotal BA_Init BA_InvalidateUnit BA_ModifyUnitData BA_ReadUnitData BA_ReplaceUnitData Task Allocates a new unused logical unit in flash memory, leaving it blank for future write / modifications. Copies portion of data, byte for byte, from one logical unit to another. Finds a logical unit matching the criteria specified or until it reaches the end of the volume. Gets Available Units: Returns available logical units that exist within the volume. Gets Information on Units: Retrieves information, status and type about the data written to the specified unit. Gets Invalid Units:Returns current number of invalid logical units that exist within the volume. Gets Total Units: Returns total number of logical units that exist within the volume. Initializes the Basic Allocation mode. Invalidates: Sets the specified logical unit's status to "invalid", indicating that the logical unit's data has been discarded and is no longer valid. Modifies data directly within a logical unit. Reads specified amount of data from the logical unit, beginning at the offset specified, into the buffer provided. Replaces: Copies source data to a buffer in RAM, replaces the specified data, then writes the resulting data buffer to the destination logical unit. Page 107 108 109 110 111 112 113 114 115 116 117 118

Intel? Flash File System Core Reference Guide

105

Basic Allocation API Reference

Table 12. Basic Allocation Functions, Listed Alphabetically (Sheet 2 of 2)
Function (Ordered Alphabetically) BA_Shutdown BA_ValidateUnit BA_WriteUnitData Task Shuts down the basic allocation portion of the FFS stack. Validate: Sets specified logical unit's status to "valid". Writes data to the specified logical unit. Page 120 121 122

106

Intel? Flash File System Core Reference Guide

Basic Allocation API Reference

8.1

BA_AllocateUnit
Allocates a new unused logical unit in flash memory Syntax
FFS_Status BA_AllocateUnit ( *dst_unit_loc_ptr, *src_unit_loc_ptr, dst_unit_type ); BA_UnitLocation BA_UnitLocation BA_UnitType

Parameters
Parameter dst_unit_loc_ptr Description (OUT) A pointer to a BA_UnitLocation structure. The target structure is filled in before this function returns, if no errors occur. The initial contents of the target structure are ignored. (See Section 15.1.2, “BA_UnitLocation” on page 250.) (IN) A BA_UnitLocation structure. NULL for a new logical unit allocation. Otherwise contains the location of an existing original unit to be overwritten truncated or appended to. If this is not supplied when a unit is being replaced, then the allocation routine will not be able to guarantee replacement in a flash full condition. (See Section 15.1.2, “BA_UnitLocation” on page 250.) (IN) Specifies the type of logical unit to be allocated. (See Section 15.1.4, “BA_UnitType typedef enum” on page 251.)

src_unit_loc_ptr

dst_unit_type

Error Codes/Return Values
FFS_StatusSuccess FFS_StatusInvalidLogicalUnit FFS_StatusInvalidParameter FFS_StatusSemaphoreFailure FFS_StatusMediaFull Success Failure (No change has been made.) Failure (No change has been made.) Failure (No change has been made.) Failure (No change has been made.)

Description
This function is used to allocate a new unused logical unit in flash memory, leaving it blank for future writes and modifications. If no errors occur, this function outputs the location of the new logical unit. The status of the header is marked "allocated", but not "valid". It is up to the caller to make sure that the unit gets marked "valid" upon completion of any appropriate write / modify operations to this unit by calling BA_ValidateUnit (Section 8.14, on page 8-121).

Intel? Flash File System Core Reference Guide

107

Basic Allocation API Reference

8.2

BA_CopyUnitData
Copies data from a specified logical unit to another Syntax
FFS_Status BA_CopyUnitData ( dst_unit_loc, src_unit_loc, data_byte_offset, data_byte_size, data_static_flag ); BA_UnitLocation BA_UnitLocation UINT16 UINT16 BOOL

Parameters
Parameter dst_unit_loc Description (IN) A BA_UnitLocation structure containing the location of a newly allocated logical unit to write a copy of the source logical unit's data to. (See Section 15.1.2, “BA_UnitLocation” on page 250.) (IN) A BA_UnitLocation structure containing the location of the logical unit with the data to be copied. (See Section 15.1.2, “BA_UnitLocation” on page 250.) (IN) The offset within the existing logical unit from which to copy the data and to which to write the data within the destination logical unit. This value must be between zero and the size of a logical unit. (IN) The total size of the data being copied (i.e. the number of bytes in the buffer specified by "data_ptr"). This value must be greater than zero and no larger than the size of a logical unit. (IN) This flag tells basic allocation whether or not the data is "static" so that it can handle the copy from devices with EDAC restrictions appropriately. TRUE indicates that the data was only written once and never modified meaning it can be written MLC. FALSE indicates that the data can be modified and must be handled as PSBC data.

src_unit_loc data_byte_offset

data_byte_size

data_static_flag

Error Codes/Return Values
FFS_StatusSuccess FFS_StatusInvalidLogicalUnit FFS_StatusInvalidParameter FFS_StatusSemaphoreFailure FFS_StatusOutOfMemory Success Failure (No change has been made.) Failure (No change has been made.) Failure (No change has been made.) Failure (No change has been made.)

Description
The CopyUnitData function copies a portion of data, byte for byte, from one logical unit (scr_unit_loc) to another logical unit (dst_unit_loc). It is assumed that the destination unit has not yet been written to, beginning at the specified offset. This function handles any device EDAC restrictions according to the value of the static data flag. For static data, the data byte offset must be 0. The caller is responsible for setting the status of the logical unit to valid by calling BA_ValidateUnit (Section 8.14, on page 8-121) once the operation is complete and any appropriate parent associations are completed.

108

Intel? Flash File System Core Reference Guide

Basic Allocation API Reference

8.3

BA_FindNextUnit
Searches a volume for a logical unit matching specified criteria Syntax
FFS_Status BA_FindNextUnit ( *begin_unit_loc_ptr, *next_unit_loc_ptr, unit_type, unit_status ); BA_UnitLocation BA_UnitLocation BA_UnitType BA_UnitStatus

Parameters
Parameter begin_unit_loc_ptr Description (IN) The location of the unit at which to begin/continue the search. NULL to search all units from the beginning of the volume. (See Section 15.1.2, “BA_UnitLocation” on page 250.) (OUT) Upon success (FFS_ErrorNone) the value pointed to is modified to specify the location of the next unit found to match the search criteria. (See Section 15.1.2, “BA_UnitLocation” on page 250.) (IN) Specifies the type value to search for. If the value is BA_UnitTypeUnknown then unit type is excluded from the search criteria. (See Section 15.1.4, “BA_UnitType typedef enum” on page 251.) (IN) Specifies the status value to search for. If the value is BA_UnitStatusUnknown then unit status is excluded from the search criteria. (See Section 15.1.3, “BA_UnitStatus typedef enum” on page 251.)

next_unit_loc_ptr

unit_type

unit_status

Error Codes/Return Values
FFS_StatusSuccess FFS_StatusInvalidLogicalUnit FFS_StatusInvalidParameter FFS_StatusSemaphoreFailure FFS_StatusNotFound Success Failure (No change has been made.) Failure (No change has been made.) Failure (No change has been made.) Failure (No change has been made.)

Description
This function searches through the volume, beginning with the unit specified (begin_unit_loc_ptr) until it locates a logical unit matching the criteria specified or it reaches the end of the volume. If a unit is found which matches the given criteria, its location is returned (next_unit_loc_ptr).

Intel? Flash File System Core Reference Guide

109

Basic Allocation API Reference

8.4

BA_GetUnitsAvailable
Returns the number of available logical units existing in a volume Syntax
FFS_Status UINT32 BA_GetUnitsAvailable ( *units_available_ptr );

Parameters
Parameter units_available_ptr Description (OUT) Pointer to a buffer that holds the number of available logical units.

Error Codes/Return Values
FFS_StatusSuccess FFS_StatusInvalidParameter FFS_StatusSemaphoreFailure Success Failure (No change has been made.) Failure (No change has been made.)

Description
This function returns the current number of available logical units that exist within the volume (unallocated + invalid).

110

Intel? Flash File System Core Reference Guide

Basic Allocation API Reference

8.5

BA_GetUnitInfo
Retrieves information about data written to a specified unit. Syntax
FFS_Status BA_GetUnitInfo ( unit_loc, *unit_type_ptr, *unit_status_ptr ); BA_UnitLocation BA_UnitType BA_UnitStatus

Parameters
Parameter unit_loc unit_type_ptr unit_status_ptr Description (IN) The location of the unit for which to get the status. (See Section 15.1.2, “BA_UnitLocation” on page 250.) (OUT) If not NULL, then upon successful return indicates the type of the unit specified. (See Section 15.1.4, “BA_UnitType typedef enum” on page 251.) (OUT) If not NULL, then upon successful return contains the status of the unit specified. (See Section 15.1.3, “BA_UnitStatus typedef enum” on page 251.)

Error Codes/Return Values
FFS_StatusSuccess FFS_StatusInvalidLogicalUnit FFS_StatusInvalidParameter FFS_StatusSemaphoreFailure Success Failure (No change has been made.) Failure (No change has been made.) Failure (No change has been made.)

Description
This function retrieves information, status and type about the data written to the specified unit.

Intel? Flash File System Core Reference Guide

111

Basic Allocation API Reference

8.6

BA_GetUnitsInvalid
Returns current number of invalid logical units existing in a volume Syntax
FFS_Status UINT32 BA_GetUnitsInvalid ( *units_invalid_ptr );

Parameters
Parameter units_invalid_ptr Description (OUT) Pointer to a buffer that holds the number of invalid logical units.

Error Codes/Return Values
FFS_StatusSuccess FFS_StatusInvalidParameter FFS_StatusSemaphoreFailure Success Failure (No change has been made.) Failure (No change has been made.)

Description
This function returns the current number of invalid logical units that exist within the volume.

112

Intel? Flash File System Core Reference Guide

Basic Allocation API Reference

8.7

BA_GetUnitsTotal
Returns total number of logical units existing in a volume Syntax
FFS_Status UINT32 BA_GetUnitsTotal ( *units_total_ptr );

Parameters
Parameter units_total_ptr Description (OUT) Pointer to a buffer that holds the number of logical units.

Error Codes/Return Values
FFS_StatusSuccess FFS_StatusInvalidParameter FFS_StatusSemaphoreFailure Success Failure (No change has been made.) Failure (No change has been made.)

Description
This function returns the total number of logical units that exist within the volume (allocated + unallocated + invalid).

Intel? Flash File System Core Reference Guide

113

Basic Allocation API Reference

8.8

BA_Init
Initializes the basic allocation module Syntax
FFS_Status BA_Init ( *volume_info_ptr *format_ptr, *options_ptr, *init_info_ptr ); void FFS_format FFS_Options BA_InitInfo

Parameters
Parameter volume_info_ptr format_ptr Description (IN) Volume information pointer. Must supply the address of a valid structure. BA does not use this information but just passes it on to the flash interface initialization routines. (IN) The structure pointed to must contain valid format parameters for formatting the media if a format is to be performed. When this parameter is NULL the file system will attempt to initialize using the volumes existing format. If the volume is found to be unformatted or corrupt initialization will fail and this function will return FFS_StatusInvalidFormat. (See Section 15.2.2, “FFS_Format” on page 254.) (IN) Pointer to a valid, populated, file system options structure. BA uses this structure, only to pass on the UserReclaimThreshold value to the reclaim module initialization routine. (See Section 15.2.3, “FFS_Options” on page 254.) (OUT) Returns data byte size information and the locations and count of any units of type BA_UnitTypeGlobal or BA_UnitTypeRoot that were found during initialization. (See Section 15.1.1, “BA_InitInfo” on page 249.)

options_ptr

init_info_ptr

Error Codes/Return Values
FFS_StatusSuccess FFS_StatusInvalidParameter FFS_StatusOutOfMemory FFS_StatusSemaphoreFailure FFS_StatusThreadFailure FFS_StatusInvalidFormat FFS_StatusBlockInfoCorrupt FFS_StatusGlobalInfoCorrupt FFS_StatusRootInfoCorrupt Success Failure Failure (No change has been made.) Failure (No change has been made.) Failure (No change has been made.) Failure (No change has been made.) Failure (No change has been made.) Failure (No change has been made.) Failure (No change has been made.)

Description
The BA_Init function is used to initialize the basic allocation module. No other basic allocation functions can be called until initialization has completed successfully.

114

Intel? Flash File System Core Reference Guide

Basic Allocation API Reference

8.9

BA_InvalidateUnit
Sets status of a specified logical unit to invalid Syntax
FFS_Status BA_InvalidateUnit ( unit_loc ); BA_UnitLocation

Parameters
Parameter unit_loc Description (IN) A BA_UnitLocation structure containing the location of the logical unit to set to status "invalid". (See Section 15.1.2, “BA_UnitLocation” on page 250.)

Error Codes/Return Values
FFS_StatusSuccess BA_ErrorInvalidLogicalUnit FFS_StatusSemaphoreFailure Success Failure (No change has been made.) Failure (No change has been made.)

Description
Sets the specified logical unit's status to "invalid", indicating that the logical unit's data has been discarded and is no longer valid. The space consumed by this unit will become available again when a reclaim occurs on this unit’s logical block.

Intel? Flash File System Core Reference Guide

115

Basic Allocation API Reference

8.10

BA_ModifyUnitData
Modifies data directly within a logical unit. Syntax
FFS_Status BA_ModifyUnitData ( dst_unit_loc, data_byte_offset, data_byte_size, *data_ptr ); BA_UnitLocation UINT16 UINT16 VOID

Parameters
Parameter dst_unit_loc data_byte_offset data_byte_size Description (IN) A BA_UnitLocation structure containing the location of the pre-allocated logical unit to be written to. (See Section 15.1.2, “BA_UnitLocation” on page 250.) (IN) The offset within the existing logical unit at which to begin writing data to. This value must be between zero and the size of a logical unit. (IN) The total size of the data being written (i.e., the number of bytes in the buffer specified by "data_ptr"). This value must be greater than zero and no larger than the size of a logical unit. (IN) A pointer to the data to be written to the specified logical unit. Cannot be NULL.

data_ptr

Error Codes/Return Values
FFS_StatusSuccess FFS_StatusInvalidLogicalUnit FFS_StatusInvalidParameter FFS_StatusSemaphoreFailure FFS_StatusOutOfMemory Success Failure (No change has been made.) Failure (No change has been made.) Failure (No change has been made.) Failure (No change has been made.)

Description
Modifies data directly within a logical unit. This function performs a "blind write", overwriting existing data without checking to verify the existing region is still "unprogrammed". Note: No PLR can be performed on this kind of write; it is entirely up to the caller to implement mechanisms to avoid corrupting the data within the logical unit and to handle potential power loss conditions. This function assumes dynamic data is being written and will handle any device EDAC restrictions accordingly. The caller is responsible for setting the status of the logical unit to valid by calling BA_ValidateUnit (Section 8.14, on page 8-121) once the operation is complete and any appropriate parent associations are completed.

116

Intel? Flash File System Core Reference Guide

Basic Allocation API Reference

8.11

BA_ReadUnitData
Reads specified data from a logical unit into a buffer Syntax
FFS_Status BA_ReadUnitData ( src_unit_loc, data_byte_offset, data_byte_size, *data_ptr, data_static_flag ); BA_UnitLocation UINT16 UINT16 VOID BOOL

Parameters
Parameter src_unit_loc data_byte_offset data_byte_size Description (IN) A BA_UnitLocation structure containing the location of the pre-allocated logical unit to be read from. (See Section 15.1.2, “BA_UnitLocation” on page 250.) (IN) The offset within the existing logical unit at which to begin writing data to. This value must be between zero and the size of a logical unit. (IN) The total size of the data being written (i.e., the number of bytes in the buffer specified by "data_ptr"). This value must be greater than zero and no larger than the size of a logical unit. (IN) A pointer to the data to be written to the specified logical unit. Cannot be NULL. (IN) This flag tells basic allocation whether or not the data is static so that it can handle the read from devices with EDAC restrictions appropriately. TRUE indicates that the data was only written once and never modified, meaning it can be written MLC. FALSE indicates that the data is modifiable and must be handled as PSBC data.

data_ptr data_static_flag

Error Codes/Return Values
FFS_StatusSuccess FFS_StatusInvalidLogicalUnit FFS_StatusInvalidParameter FFS_StatusSemaphoreFailure FFS_StatusOutOfMemory Success Failure (No change has been made.) Failure (No change has been made.) Failure (No change has been made.) Failure (No change has been made.)

Description
Reads the specified amount (data_byte_size) of data from the logical unit (src_unit_loc), beginning at the offset specified (data_byte_offset), into the buffer provided (data_ptr). Note: The offset plus the bytes to be read cannot exceed the total allocated size of a logical unit. The caller is responsible to ensure that the buffer is large enough to receive the specified amount of data.

Intel? Flash File System Core Reference Guide

117

Basic Allocation API Reference

8.12

BA_ReplaceUnitData
Replaces data at a specified destination logical unit Syntax
FFS_Status BA_ReplaceUnitData ( dst_unit_loc, src_unit_loc, data_byte_offset, data_byte_size, *data_ptr, data_static_flag ); BA_UnitLocation BA_UnitLocation UINT16 UINT16 VOID BOOL

Parameters
Parameter dst_unit_loc Description (IN) A BA_UnitLocation structure specifies the location of a newly allocated logical unit to write the resulting replaces data to (destination location). (See Section 15.1.2, “BA_UnitLocation” on page 250.) (IN) A BA_UnitLocation structure specifies the location of the logical unit containing the original data of which a portion is to be replaced. (See Section 15.1.2, “BA_UnitLocation” on page 250.) (IN) The offset within the existing logical unit at which to begin replacing data. This value must be between zero and the size of a logical unit. (IN) The total size of the data being replaced (i.e. the number of bytes in the buffer specified by "data_ptr"). This value must be greater than zero, and no larger than the size of a logical unit. (IN) A pointer to the replacement data to be written to the specified destination logical unit. If NULL the specified bytes of data are cleared by writing 0xFF to them. (IN) This flag tells basic allocation whether or not the data is "static" so that it can handle the read from devices with EDAC restrictions appropriately. TRUE indicates that the data was only written once and never modified, meaning it can be written MLC. FALSE indicates that the data is modifiable and must be handled as PSBC data.

src_unit_loc

data_byte_offset data_byte_size

data_ptr data_static_flag

Error Codes/Return Values
FFS_StatusSuccess FFS_StatusInvalidLogicalUnit FFS_StatusInvalidParameter FFS_StatusSemaphoreFailure FFS_StatusOutOfMemory Success Failure (No change has been made.) Failure (No change has been made.) Failure (No change has been made.) Failure (No change has been made.)

118

Intel? Flash File System Core Reference Guide

Basic Allocation API Reference

Description
The BA_ReplaceUnitData function copies the source data (src_unit_loc) to a buffer in RAM, replaces the specified data (data_byte_size from data_ptr), then writes the resulting data buffer to the destination logical unit (dst_unit_loc). If the data pointer (data_ptr) is NULL, the bytes indicated are replaced with the value 0xFF. This function assumes that resulting data is static and that the destination logical unit will only be written to once and will handle any device EDAC restrictions accordingly. If the unit will contain dynamic data where the unit has the potential of being written to more than once, use a combination of calls to BA_CopyUnitData() and BA_ModifyUnitData() instead. The caller is responsible for setting the status of the logical unit to valid by calling BA_ValidateUnit once the operation is complete and any appropriate parent associations are completed.

Intel? Flash File System Core Reference Guide

119

Basic Allocation API Reference

8.13

BA_Shutdown
Shuts down the basic allocation portion of the FFS stack and frees resources Syntax
FFS_Status void ); BA_Shutdown (

Parameters
None.

Error Code/Return Value
FFS_StatusSuccess Success

Description
The BA_Shutdown function must be called to shut down the basic allocation portion of the FFS stack and to free any resources that have been allocated.

120

Intel? Flash File System Core Reference Guide

Basic Allocation API Reference

8.14

BA_ValidateUnit
Sets a specified logical unit status to valid Syntax
FFS_Status BA_ValidateUnit ( unit_loc ); BA_UnitLocation

Parameters
Parameter unit_loc Description (IN) A BA_UnitLocation structure containing the location of the logical unit to set to status "valid". (See Section 15.1.2, “BA_UnitLocation” on page 250.)

Error Codes/Return Values
FFS_StatusSuccess BA_ErrorInvalidLogicalUnit FFS_StatusSemaphoreFailure Success Failure (No change has been made.) Failure (No change has been made.)

Description
Sets the specified logical unit's status to "valid", indicating that the logical unit's data has been completely written and is valid.

Intel? Flash File System Core Reference Guide

121

Basic Allocation API Reference

8.15

BA_WriteUnitData
Writes data to the specified logical unit Syntax
FFS_Status BA_WriteUnitData ( dst_unit_loc, data_byte_size, *data_ptr, data_static_flag ); BA_UnitLocation UINT16 VOID BOOL

Parameters
Parameter dst_unit_loc data_byte_size Description (IN) A BA_UnitLocation structure containing the location of a newly allocated logical unit to be written to. (See Section 15.1.2, “BA_UnitLocation” on page 250.) (IN) The total size of the data being written (i.e. the number of bytes in the buffer specified by data_ptr). This value must be greater than zero and no larger than the size of a logical unit. (IN) A pointer to the data to be written to the specified logical unit. Cannot be NULL. (IN) This flag tells basic allocation whether or not the data is "static" so that it can handle the read from devices with EDAC restrictions appropriately. TRUE indicates that the data was only written once and never modified, meaning it can be written MLC. FALSE indicates that the data is modifiable and must be handled as PSBC data.

data_ptr data_static_flag

Error Codes/Return Values
FFS_StatusSuccess FFS_StatusInvalidLogicalUnit FFS_StatusInvalidParameter FFS_StatusSemaphoreFailure FFS_StatusOutOfMemory Success Failure (No change has been made.) Failure (No change has been made.) Failure (No change has been made.) Failure (No change has been made.)

Description
The BA_WriteUnitData function writes data to the specified logical unit. This function assumes that the specified data will only be written to this logical unit once. If this unit has the potential of being written to more than once, use BA_ModifyUnitData (Section 8.10, on page 8-116), beginning at the initial write.The caller is responsible for setting the status of the logical unit to valid by calling BA_ValidateUnit (Section 8.14, on page 8-121) once the operation is complete and any appropriate parent associations are completed.

122

Intel? Flash File System Core Reference Guide

Basic Allocation API Reference

8.16

Error Codes
Table 13. Error Codes
Error Name FFS_StatusSuccess FFS_StatusSemaphoreFailure FFS_StatusInvalidLogicalUnit FFS_StatusInvalidParameter FFS_StatusMediaFull FFS_StatusNotFound FFS_StatusOutOfMemory FFS_StatusThreadFailure FFS_StatusInvalidFormat FFS_StatusBlockInfoCorrupt FFS_StatusGlobalInfoCorrupt FFS_StatusRootInfoCorrupt BA_ErrorInvalidLogicalUnit Success Failure (No change has been made.) Failure (No change has been made.) Failure (No change has been made.) Failure (No change has been made.) Failure (No change has been made.) Failure (No change has been made.) Failure (No change has been made.) Failure (No change has been made.) Failure (No change has been made.) Failure (No change has been made.) Failure (No change has been made.) Failure (No change has been made.) Meaning

§§§

Intel? Flash File System Core Reference Guide

123

Basic Allocation API Reference

124

Intel? Flash File System Core Reference Guide

Reclaim Module

Reclaim Module

9

The Reclaim Module, shown in Figure 11, “Flash File System Components” on page 125, is used to clean up the media and get back free space from the dirty space that has been generated during system operation. It copies all valid data from a block that is to be reclaimed (source block) to a destination block, and then erases the source block. The space for the dirty or invalid data becomes available free space that can be written to. The reclaim operation is completely power-loss recoverable. The Reclaim Module calls Basic Allocation Layer functions to maintain the block information structure in each block. A Reclaim Module external API enables users to manually initiate a reclaim operation to perform a preemptive reclaim before a large file is to be downloaded. The routine selects the block to be reclaimed based on the standard dirty space and wear-leveling criteria. Figure 11. Flash File System Components

OS File System API

Real-time Operating System (RTOS) Wrapper Interface OS Resources Translation Layer

RAM FIFO Buffer

File System Layer

Data Objects Layer Flash File System Core Basic Allocation Layer Reclaim Module

Flash Interface Layer

OS Specific Layer

Translation Layer

Low-Level

Flash Hardware

Intel? Flash File System Core Reference Guide

OS External Libraries

125

Reclaim Module

9.1

Reclaim Module Functionality
The Reclaim Module provides the following functionality:

? On request, reclaims dirty space in a specified block, or will choose the block to be reclaimed. ? Performs a reclaim using the functionality provided by the Basic Allocation Layer, so that the
logical block table gets updated accordingly. To free space consumed by invalid data, storage space in flash devices must be erased one block at a time before being reused. However, the Reclaim Module must first relocate any valid data that is in the same erase block as the invalid data. The reclaim operation is the process of copying the valid data to some other location before erasing the block. One quick method of doing this is to copy any valid data to RAM, erase the block, and then write the valid data back into the block. This process, however, has two drawbacks. First, erased blocks tend to be very large, usually 64 KB or greater, thus requiring a large amount of dedicated memory. Second, if power is lost while the valid data is in RAM, but before it has been written back to the erase block, the valid data will be lost. To overcome these problems, the Flash File System Core sets aside one erase block within the flash volume known as the reclaim destination block. The reclaim destination block is never used for storing data; it is used only during the reclaim process. Figure 12, “Reclaim Destination Block” on page 127 and the steps below illustrate and explain how the reclaim destination block is used. 1. When the invalid space in an erase block is needed for new allocations, the erase block is targeted for reclaim. The block that is targeted for reclaim is known as the reclaim source block. At the time reclaim begins, the destination block is erased and contains no data. 2. During reclaim, only valid data is copied from the source block to the destination block. As shown in Figure 12, “Reclaim Destination Block” on page 127, the valid data is copied from the source block to the same relative location within the destination block. 3. After all the valid data has been copied to the destination block, the source block is erased. At this point, the source block becomes the destination spare block. This process is repeated anytime there is invalid space to be reclaimed. There is always at least one copy of the valid data stored somewhere in the flash memory; if system power is lost, the data remains intact.

126

Intel? Flash File System Core Reference Guide

Reclaim Module

Figure 12. Reclaim Destination Block
Source Block 1 Valid Invalid Va

赞助商链接

更多相关文章:
Cisco密码初始化
The following commands will initialize the flash file system, and finish ...Intel Express 交换机口令的清除 适用范围:Intel Express 10 Switch/10 Switch+...
实验03--内核裁减与文件系...
flash chips <*> Support for Intel/Sharp flash chips <*> Support for AMD...(iso8859-1) Default iocharset for FAT < > NTFS file system support ...
sam-ba_2.12 usb 连接at91sam9260ek
sam-ba_2.12 usb 烧录 norflash at91sam9260ek ...Intel/Sharp Extended Query Table at 0x010A Intel...family 17 VFS: Mounted root (jffs2 filesystem)...
CISCO文件管理命令
System flash (Intel Strataflash) Directory of flash:/ 2 -rwx 18929780 Aug...浏览 Cisco IOS 文件系统 - 查看路由器中的配置文件以及 IOS 文件都 需要使用...
Mac_OS_X_Lion虚拟机完整镜像_Intel版+下载地址_图文
Intel PC 1) Download the additional files and ...Flash disk and external hard disk works fine in...As I said earlier, I did this in Intel Core2...
Mac OS X Lion虚拟机完整镜像 Intel
Intel PC 1) Download the additional files and ...Flash disk and external hard disk works fine in...As I said earlier, I did this in Intel Core2...
How to flash the BIOS(译)
Intel P4 478 type then look here 下载你同你的主板匹配的 BIOS 和版本号(...Flashing the BIOS for Non-FAT file system (Thanks to Forum Moderator Assaf...
基于vxworks的trueffs文件...
Key Words: TrueFFS; file system; function; configuration 引言 Tornado 的 ...已经包括了支持 Intel, AMD, Toshiba 等厂商的大多数 Flash 芯片的 MTD 层[2...
MIC编程指南初级教程
manycore-platform-software-stack -mpss 可以购买...user_prompt>sudo /opt/intel/mic/bin/micflash -...intel/mic/filesystem/mic1/etc/sysconfig/network/...
网管必学的10条思科IOS文件管理命令
System flash (Intel Strataflash) Directory of flash:/ 2 +00:00 3 -rwx...浏览 Cisco IOS 文件系统 — 查看路由器中的配置文件以及 IOS 文件都需要使用...
更多相关标签:

All rights reserved Powered by 甜梦文库 9512.net

copyright ©right 2010-2021。
甜梦文库内容来自网络,如有侵犯请联系客服。zhit325@126.com|网站地图