File System Storage API#

FSStorage_ConfigureMediaConnCallback()#

Description#

Set the media connection and disconnection callbacks.

Files#

fs_storage.h/fs_storage.c

Prototype#

void  FSStorage_ConfigureMediaConnCallback (void   (*on_conn)     (FS_MEDIA_HANDLE  media_handle),
                                            void   (*on_disconn)  (FS_MEDIA_HANDLE  media_handle))

Arguments#

on_conn

Callback that will be called whenever a removable media (SD or SCSI) is connected.

on_disconn

Callback that will be called whenever a removable media (SD or SCSI) is disconnected.

Returned Value#

none.

Notes / Warnings#

  1. If the connection callback is NOT provided, the poll task will not be started.

FSStorage_ConfigureMediaPollTaskStk()#

Description#

Set the media polling task stack start address and stack size.

Files#

fs_storage.h/fs_storage.c

Prototype#

void  FSStorage_ConfigureMediaPollTaskStk (void        *p_stk,
                                           CPU_INT32U   stk_size_elements)

Arguments#

p_stk

Pointer to the start of the stack memory region.

stk_size_elements

Size of the stack in stack size elements.

Returned Value#

none.

Notes / Warnings#

None.

FSStorage_ConfigureMemSeg()#

Description#

Configure memory segment for the storage module.

Files#

fs_storage.h/fs_storage.c

Prototype#

void  FSStorage_ConfigureMemSeg (MEM_SEG  *p_seg)

Arguments#

p_seg

Pointer to a user-defined memory segment.

Returned Value#

none.

Notes / Warnings#

None.

FSStorage_ConfigureMaxSCSILogicalUnitCnt()#

Description#

Configure the (fixed) quantity of SCSI logical units available.

Files#

fs_storage.h/fs_storage.c

Prototype#

void  FSStorage_ConfigureMaxSCSILogicalUnitCnt (CPU_SIZE_T  max_cnt)

Arguments#

max_cnt

Maximum SCSI logical unit available quantity.

Returned Value#

none.

Notes / Warnings#

None.

FSStorage_Init()#

Description#

Initialize the file system storage sub-module.

Files#

fs_storage.h/fs_storage.c

Prototype#

void  FSStorage_Init (RTOS_ERR  *p_err)

Arguments#

p_err

Pointer to variable that will receive the return error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_SEG_OVF

Returned Value#

none.

Notes / Warnings#

None.

FSStorage_PollTaskPeriodSet()#

Description#

Set the media poll task period.

Files#

fs_storage.h/fs_storage.c

Prototype#

void  FSStorage_PollTaskPeriodSet (CPU_INT32U   period_ms,
                                   RTOS_ERR    *p_err)

Arguments#

period_ms

Interval of time (in milliseconds) between two polling.

p_err

Pointer to variable that will receive the return error code(s) from this function:

  • RTOS_ERR_NONE

Returned Value#

none.

Notes / Warnings#

None.

FSStorage_PollTaskPrioSet()#

Description#

Set the priority of the media poll task.

Files#

fs_storage.h/fs_storage.c

Prototype#

void  FSStorage_PollTaskPrioSet (RTOS_TASK_PRIO   prio,
                                 RTOS_ERR        *p_err)

Arguments#

prio

New priority for the media poll task.

p_err

Pointer to variable that will receive the return error code(s) from this function:

  • RTOS_ERR_NONE

Returned Value#

none.

Notes / Warnings#

None.

FSBlkDev_Open()#

Description#

Open a block device.

Files#

fs_blk_dev.h/fs_blk_dev.c

Prototype#

FS_BLK_DEV_HANDLE  FSBlkDev_Open (FS_MEDIA_HANDLE   media_handle,
                                  RTOS_ERR         *p_err)

Arguments#

media_handle

Handle to a media.

p_err

Pointer to variable that will receive the return error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_NOT_INIT

  • RTOS_ERR_BLK_DEV_OPENED

  • RTOS_ERR_BLK_DEV_LOW_FMT_INCOMPATIBLE

  • RTOS_ERR_BLK_DEV_LOW_FMT_INVALID

  • RTOS_ERR_IO

Returned Value#

Handle to the opened block device.

Notes / Warnings#

None.

FSBlkDev_Close()#

Description#

Close a block device.

Files#

fs_blk_dev.h/fs_blk_dev.c

Prototype#

void  FSBlkDev_Close (FS_BLK_DEV_HANDLE   blk_dev_handle,
                      RTOS_ERR           *p_err)

Arguments#

blk_dev_handle

Handle to a block device.

p_err

Pointer to variable that will receive the return error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_BLK_DEV_CLOSED

Returned Value#

none.

Notes / Warnings#

None.

FSBlkDev_Rd()#

Description#

Read blocks from a block device.

Files#

fs_blk_dev.h/fs_blk_dev.c

Prototype#

void  FSBlkDev_Rd (FS_BLK_DEV_HANDLE   blk_dev_handle,
                   void               *p_dest,
                   FS_LB_NBR           start_lb_nbr,
                   FS_LB_QTY           lb_cnt,
                   RTOS_ERR           *p_err)

Arguments#

blk_dev_handle

Handle to a block device.

p_dest

Pointer to a destination buffer.

start_lb_nbr

Logical block number of the block to start reading from.

lb_cnt

Number of logical blocks to read.

p_err

Pointer to variable that will receive the return error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_BLK_DEV_CLOSED

  • RTOS_ERR_BLK_DEV_CORRUPTED

  • RTOS_ERR_IO

Returned Value#

none.

Notes / Warnings#

None.

FSBlkDev_Wr()#

Description#

Write blocks to a block device.

Files#

fs_blk_dev.h/fs_blk_dev.c

Prototype#

void  FSBlkDev_Wr (FS_BLK_DEV_HANDLE   blk_dev_handle,
                   void               *p_src,
                   FS_LB_NBR           start_lb_nbr,
                   FS_LB_QTY           lb_cnt,
                   RTOS_ERR           *p_err)

Arguments#

blk_dev_handle

Handle to a block device.

p_src

Pointer to a source buffer.

start_lb_nbr

Logical block number of the block to start writing to.

lb_cnt

Number of logical blocks to write.

p_err

Pointer to variable that will receive the return error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_BLK_DEV_CLOSED

  • RTOS_ERR_BLK_DEV_CORRUPTED

  • RTOS_ERR_IO

Returned Value#

none.

Notes / Warnings#

None.

FSBlkDev_Sync()#

Description#

Sync a block device.

Files#

fs_blk_dev.h/fs_blk_dev.c

Prototype#

void  FSBlkDev_Sync (FS_BLK_DEV_HANDLE   blk_dev_handle,
                     RTOS_ERR           *p_err)

Arguments#

blk_dev_handle

Handle to a block device.

p_err

Pointer to variable that will receive the return error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_BLK_DEV_CLOSED

  • RTOS_ERR_BLK_DEV_CORRUPTED

  • RTOS_ERR_IO

Returned Value#

none.

Notes / Warnings#

None.

FSBlkDev_Trim()#

Description#

Trim a block device.

Files#

fs_blk_dev.h/fs_blk_dev.c

Prototype#

void  FSBlkDev_Trim (FS_BLK_DEV_HANDLE   blk_dev_handle,
                     FS_LB_NBR           start_lb_nbr,
                     FS_LB_QTY           lb_cnt,
                     RTOS_ERR           *p_err)

Arguments#

blk_dev_handle

Handle to a block device.

start_lb_nbr

Logical block number of the block to start trimming from.

lb_cnt

Number of logical blocks to trim.

p_err

Pointer to variable that will receive the return error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_BLK_DEV_CLOSED

  • RTOS_ERR_BLK_DEV_CORRUPTED

  • RTOS_ERR_IO

Returned Value#

none.

Notes / Warnings#

None.

FSBlkDev_AlignReqGet()#

Description#

Get the alignment requirement.

Files#

fs_blk_dev.h/fs_blk_dev.c

Prototype#

CPU_SIZE_T  FSBlkDev_AlignReqGet (FS_BLK_DEV_HANDLE   blk_dev_handle,
                                  RTOS_ERR           *p_err)

Arguments#

blk_dev_handle

Handle to a block device.

p_err

Pointer to variable that will receive the return error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_BLK_DEV_CLOSED

Returned Value#

  • Alignment requirement in bytes, if NO error(s).

  • 0, otherwise.

Notes / Warnings#

None.

FSBlkDev_LbCntGet()#

Description#

Get the number of logical blocks on a block device.

Files#

fs_blk_dev.h/fs_blk_dev.c

Prototype#

FS_LB_QTY  FSBlkDev_LbCntGet (FS_BLK_DEV_HANDLE   blk_dev_handle,
                              RTOS_ERR           *p_err)

Arguments#

blk_dev_handle

Handle to a block device.

p_err

Pointer to variable that will receive the return error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_BLK_DEV_CLOSED

Returned Value#

  • Number of logical blocks, if NO error(s).

  • 0, otherwise.

Notes / Warnings#

None.

FSBlkDev_LbSizeGet()#

Description#

Get logical block size.

Files#

fs_blk_dev.h/fs_blk_dev.c

Prototype#

FS_LB_SIZE  FSBlkDev_LbSizeGet (FS_BLK_DEV_HANDLE   blk_dev_handle,
                                RTOS_ERR           *p_err)

Arguments#

blk_dev_handle

Handle to a block device.

p_err

Pointer to variable that will receive the return error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_BLK_DEV_CLOSED

Returned Value#

Logical block size.

Notes / Warnings#

None.

FSBlkDev_LbSizeLog2Get()#

Description#

Get base-2 logarithm of the logical block size.

Files#

fs_blk_dev.h/fs_blk_dev.c

Prototype#

CPU_INT08U  FSBlkDev_LbSizeLog2Get (FS_BLK_DEV_HANDLE   blk_dev_handle,
                                    RTOS_ERR           *p_err)

Arguments#

blk_dev_handle

Handle to a block device.

p_err

Pointer to variable that will receive the return error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_BLK_DEV_CLOSED

Returned Value#

Base-2 logarithm of the logical block size.

Notes / Warnings#

None.

FSBlkDev_Get()#

Description#

Get a block device handle from the media handle.

Files#

fs_blk_dev.h/fs_blk_dev.c

Prototype#

FS_BLK_DEV_HANDLE  FSBlkDev_Get (FS_MEDIA_HANDLE  media_handle)

Arguments#

media_handle

Handle to a media.

Returned Value#

Handle to the block device.

Notes / Warnings#

(1) If a block device has no been open, the returned handle is NULL. You may check for NULL handle using the macro FS_BLK_DEV_HANDLE_IS_NULL().

FSBlkDev_NameGet()#

Description#

Get block device name.

Files#

fs_blk_dev.h/fs_blk_dev.c

Prototype#

void  FSBlkDev_NameGet (FS_BLK_DEV_HANDLE   blk_dev_handle,
                        CPU_CHAR           *p_buf,
                        CPU_SIZE_T          buf_size,
                        RTOS_ERR           *p_err)

Arguments#

blk_dev_handle

Handle to a block device.

p_buf

Pointer to a buffer that will receive the block device name.

buf_size

Size of the given buffer.

p_err

Pointer to variable that will receive the return error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_BLK_DEV_CLOSED

Returned Value#

none.

Notes / Warnings#

None.

FSBlkDev_MediaGet()#

Description#

Get parent media.

Files#

fs_blk_dev.h/fs_blk_dev.c

Prototype#

FS_MEDIA_HANDLE  FSBlkDev_MediaGet (FS_BLK_DEV_HANDLE  blk_dev_handle)

Arguments#

blk_dev_handle

Handle to a block device.

Returned Value#

Handle to the parent media or NULL handle if the block device handle is invalid.

Notes / Warnings#

None.

FSMedia_Get()#

Description#

Get a handle to a media by name.

Files#

fs_media.h/fs_media.c

Prototype#

FS_MEDIA_HANDLE  FSMedia_Get (const  CPU_CHAR  *p_name)

Arguments#

p_name

Pointer to media name.

Returned Value#

Handle to a media

NULL handle if no media is found with the given name.

Notes / Warnings#

  1. You may check for NULL handle using the macro FS_MEDIA_HANDLE_IS_NULL().

FSMedia_FirstGet()#

Description#

Get the first added media.

Files#

fs_media.h/fs_media.c

Prototype#

FS_MEDIA_HANDLE  FSMedia_FirstGet (void)

Arguments#

Returned Value#

Handle to a media.

Notes / Warnings#

None.

FSMedia_LowFmt()#

Description#

Low-level format a media so that it can be opened as a block device.

Files#

fs_media.h/fs_media.c

Prototype#

void  FSMedia_LowFmt (FS_MEDIA_HANDLE   media_handle,
                      RTOS_ERR         *p_err)

Arguments#

media_handle

Handle to a media.

p_err

Pointer to variable that will receive the return error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_NOT_INIT

  • RTOS_ERR_NOT_FOUND

  • RTOS_ERR_BLK_DEV_OPENED

  • RTOS_ERR_IO

Returned Value#

Notes / Warnings#

  1. This function will write flash translation layer metadata to NOR and NAND flash memories. For other types of media, this function does nothing.

FSMedia_IsConn()#

Description#

Check whether a media is connected.

Files#

fs_media.h/fs_media.c

Prototype#

CPU_BOOLEAN  FSMedia_IsConn (FS_MEDIA_HANDLE  media_handle)

Arguments#

media_handle

Handle to a media.

Returned Value#

  • DEF_YES, if the media is connected.

  • DEF_NO, otherwise.

Notes / Warnings#

None.

FSMedia_NameGet()#

Description#

Get a media name.

Files#

fs_media.h/fs_media.c

Prototype#

void  FSMedia_NameGet (FS_MEDIA_HANDLE   media_handle,
                       CPU_CHAR         *p_buf,
                       CPU_SIZE_T        buf_size,
                       RTOS_ERR         *p_err)

Arguments#

media_handle

Handle to a media.

p_buf

Pointer to a buffer that will receive the media name.

buf_size

Size of the given buffer.

p_err

Pointer to variable that will receive the return error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_IO

Returned Value#

none.

Notes / Warnings#

None.

FSMedia_MaxCntGet()#

Description#

Get the maximum number of co-existing media.

Files#

fs_media.h/fs_media.c

Prototype#

CPU_SIZE_T  FSMedia_MaxCntGet (void)

Arguments#

Returned Value#

Maximum number of media.

Notes / Warnings#

None.

FSMedia_TypeGet()#

Description#

Get the type of a media.

Files#

fs_media.h/fs_media.c

Prototype#

FS_MEDIA_TYPE  FSMedia_TypeGet (FS_MEDIA_HANDLE  media_handle,
                                RTOS_ERR        *p_err)

Arguments#

media_handle

Handle to a media.

p_err

Pointer to variable that will receive the return error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_NOT_FOUND

  • RTOS_ERR_IO

Returned Value#

Type of the media. The possible types can be:

  • FS_MEDIA_TYPE_RAM_DISK

  • FS_MEDIA_TYPE_NOR

  • FS_MEDIA_TYPE_NAND

  • FS_MEDIA_TYPE_SD_SPI

  • FS_MEDIA_TYPE_SD_CARD

  • FS_MEDIA_TYPE_SCSI

Notes / Warnings#

None.

FSMedia_TypeStrGet()#

Description#

Get a string corresponding to the given media type.

Files#

fs_media.h/fs_media.c

Prototype#

const  CPU_CHAR  *FSMedia_TypeStrGet (FS_MEDIA_TYPE  type)

Arguments#

type

Media type.

  • FS_MEDIA_TYPE_RAM_DISK

  • FS_MEDIA_TYPE_NOR

  • FS_MEDIA_TYPE_NAND

  • FS_MEDIA_TYPE_SD_SPI

  • FS_MEDIA_TYPE_SD_CARD

  • FS_MEDIA_TYPE_SCSI

Returned Value#

Pointer to a string literal corresponding to the given media type.

Notes / Warnings#

None.

FSMedia_AlignReqGet()#

Description#

Get the read/write buffer alignment requirement for a media.

Files#

fs_media.h/fs_media.c

Prototype#

CPU_SIZE_T  FSMedia_AlignReqGet (FS_MEDIA_HANDLE   media_handle,
                                 RTOS_ERR         *p_err)

Arguments#

media_handle

Handle to a media.

p_err

Pointer to variable that will receive the return error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_IO

Returned Value#

Alignment requirement.

Notes / Warnings#

None.

FS_NAND_Open()#

Description#

Open a NAND media.

Files#

fs_nand.h/fs_nand.c

Prototype#

FS_NAND_HANDLE  FS_NAND_Open (FS_MEDIA_HANDLE   media_handle,
                              RTOS_ERR         *p_err)

Arguments#

media_handle

Handle to a media.

p_err

Pointer to variable that will receive the return error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_NOT_INIT

  • RTOS_ERR_IO

  • RTOS_ERR_NOT_FOUND

Returned Value#

Handle to the opened NAND.

Notes / Warnings#

None.

FS_NAND_Close()#

Description#

Close a NAND media.

Files#

fs_nand.h/fs_nand.c

Prototype#

void  FS_NAND_Close (FS_NAND_HANDLE   nand_handle,
                     RTOS_ERR        *p_err)

Arguments#

nand_handle

Handle to a NAND.

p_err

Pointer to variable that will receive the return error code(s) from this function:

  • RTOS_ERR_NONE

Returned Value#

none.

Notes / Warnings#

None.

FS_NAND_BlkErase()#

Description#

Erase a physical block.

Files#

fs_nand.h/fs_nand.c

Prototype#

void   FS_NAND_BlkErase (FS_NAND_HANDLE    nand_handle,
                         FS_NAND_BLK_QTY   blk_ix,
                         RTOS_ERR         *p_err)

Arguments#

nand_handle

Handle to a NAND.

blk_ix

Index of the block to be erased.

p_err

Pointer to variable that will receive the return error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_IO

Returned Value#

none.

Notes / Warnings#

None.

FS_NAND_ChipErase()#

Description#

Erase an entire NAND chip. Erase counts for each block will also be erased, affecting wear leveling mechanism.

Files#

fs_nand.h/fs_nand.c

Prototype#

void  FS_NAND_ChipErase (FS_NAND_HANDLE   nand_handle,
                         RTOS_ERR        *p_err)

Arguments#

nand_handle

Handle to a NAND.

p_err

Pointer to variable that will receive the return error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_IO

Returned Value#

none.

Notes / Warnings#

  1. WARNING: this function will reset erase counts, affecting wear leveling algorithms. Use this function only in very specific cases when a low-level format does not suffice.

FS_NAND_Dump()#

Description#

Dumps raw NAND contents in multiple data chunks through a user-supplied callback function.

Files#

fs_nand.h/fs_nand.c

Prototype#

void  FS_NAND_Dump (FS_NAND_HANDLE      nand_handle,
                    FS_NAND_DUMP_FUNC   dump_func,
                    void               *p_buf,
                    FS_NAND_BLK_QTY     first_blk_ix,
                    FS_NAND_BLK_QTY     blk_cnt,
                    RTOS_ERR           *p_err)

Arguments#

nand_handle

Handle to a NAND.

dump_fnct

Callback that will return the read raw NAND data in chunks.

p_buf

Pointer to a buffer long enough to contain a NAND page.

first_blk_ix

Index of the block to start dumping at.

blk_cnt

Number of blocks to dump.

p_err

Pointer to variable that will receive the return error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_IO

Returned Value#

none.

Notes / Warnings#

None.

FS_NAND_FTL_ConfigureLowParams()#

Description#

Configure NAND FTL parameters.

Files#

fs_nand_ftl.h/fs_nand_ftl.c

Prototype#

void  FS_NAND_FTL_ConfigureLowParams (      FS_MEDIA_HANDLE   media_handle,
                                      const FS_NAND_FTL_CFG  *p_nand_cfg,
                                            RTOS_ERR         *p_err)

Arguments#

media_handle

Handle to a media.

p_nand_cfg

Pointer to a NAND FTL configuration structure.

p_err

Pointer to variable that will receive the return error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_INVALID_STATE

  • RTOS_ERR_SEG_OVF

  • RTOS_ERR_INVALID_CFG

Returned Value#

none.

Notes / Warnings#

  1. FS_NAND_FTL_ConfigureLowParams() must be called prior to FSBlkDev_Open() or FSMedia_LowFmt(). It will configure a NAND FTL instance using the user specific parameters and allocate all needed resources by the FTL instance. Then FSBlkDev_Open() or FSMedia_LowFmt() can be called and the NAND FTL instance can be obtained from the internal NAND FTL list. Thus avoiding to reallocate resources once more time for the same NAND instance.

  2. The NAND FTL configuration structure has the following fields:

typedef  struct  fs_nand_ftl_cfg {
    FS_LB_SIZE       SecSize;                                   /* Sec size in octets.                                  */
    FS_NAND_BLK_QTY  BlkCnt;                                    /* Total blk cnt.                                       */
    FS_NAND_BLK_QTY  BlkIxFirst;                                /* Ix of first blk to be used.                          */
    FS_NAND_UB_QTY   UB_CntMax;                                 /* Max nbr of Update Blocks.                            */
    CPU_INT08U       RUB_MaxAssoc;                              /* Max assoc of Random Update Blocks.                   */
    CPU_INT08U       AvailBlkTblEntryCntMax;                    /* Nbr of entries in avail blk tbl.                     */
} FS_NAND_FTL_CFG;

FS_NOR_Open()#

Description#

Open a NOR for raw access.

Files#

fs_nor.h/fs_nor.c

Prototype#

FS_NOR_HANDLE  FS_NOR_Open (FS_MEDIA_HANDLE  media_handle,
                            RTOS_ERR        *p_err)

Arguments#

media_handle

Handle to a media.

p_err

Pointer to variable that will receive the return error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_NOT_INIT

  • RTOS_ERR_NOT_FOUND

  • RTOS_ERR_MEDIA_CLOSED

  • RTOS_ERR_IO

Returned Value#

Handle to the opened NOR.

Notes / Warnings#

None.

FS_NOR_Close()#

Description#

Close a NOR.

Files#

fs_nor.h/fs_nor.c

Prototype#

void  FS_NOR_Close (FS_NOR_HANDLE   nor_handle,
                    RTOS_ERR       *p_err)

Arguments#

nor_handle

Handle to a NOR.

p_err

Pointer to variable that will receive the return error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_IO

Returned Value#

none.

Notes / Warnings#

None.

FS_NOR_Rd()#

Description#

Read from a NOR.

Files#

fs_nor.h/fs_nor.c

Prototype#

void  FS_NOR_Rd (FS_NOR_HANDLE   nor_handle,
                 void           *p_dest,
                 CPU_INT32U      start_addr,
                 CPU_INT32U      cnt,
                 RTOS_ERR       *p_err)

Arguments#

nor_handle

Handle to a NOR media instance.

p_dest

Pointer to destination buffer.

start_addr

Start address of read (see Note #1).

cnt

Number of octets to read.

p_err

Pointer to variable that will receive return the error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_IO

Returned Value#

none.

Notes / Warnings#

  1. Start address represents the flash device physical address from which the read must start. For instance if the flash device has a size of 32Mb, the physical address range is 0x00000000-0x003FFFFF. In this example, the start address must be in this range. Note that the start address is relative to the absolute start of the flash device. There is no offset to account for.

FS_NOR_Wr()#

Description#

Write to a NOR.

Files#

fs_nor.h/fs_nor.c

Prototype#

void  FS_NOR_Wr (FS_NOR_HANDLE   nor_handle,
                 void           *p_src,
                 CPU_INT32U      start_addr,
                 CPU_INT32U      cnt,
                 RTOS_ERR       *p_err)

Arguments#

nor_handle

Handle to a NOR.

p_src

Pointer to source buffer.

start_addr

Start address of write (see Note #1).

cnt

Number of octets to write.

p_err

Pointer to variable that will receive return the error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_IO

Returned Value#

none.

Notes / Warnings#

  1. Start address represents the flash device physical address from which the write must start. For instance if the flash device has a size of 32Mb, the physical address range is 0x00000000-0x003FFFFF. In this example, the start address must be in this range. Note that the start address is relative to the absolute start of the flash device. There is no offset to account for.

  2. Care should be taken if this function is used while a file system exists on the device, or if the device is low-level formatted. The octet location(s) modified are NOT verified as being outside any existing file system or low-level format information.

  3. During a program operation, only '1' bits can be changed; a '0' bit cannot be changed to a '1'. The application MUST know that the octets being programmed have not already been programmed.

  4. The success of high-level write operations can be checked by volume write check functionality. The check here covers write operations for low-level data (e.g., block & sector headers).

FS_NOR_BlkErase()#

Description#

Erase a block on a NOR.

Files#

fs_nor.h/fs_nor.c

Prototype#

void  FS_NOR_BlkErase (FS_NOR_HANDLE   nor_handle,
                       CPU_INT32U      blk_ix,
                       RTOS_ERR       *p_err)

Arguments#

nor_handle

Handle to a NOR.

blk_ix

Index of the block to be erased.

p_err

Pointer to variable that will receive return the error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_IO

Returned Value#

none.

Notes / Warnings#

  1. Care should be taken if this function is used while a file system exists on the device, or if the device is low-level formatted. The erased block is NOT verified as being outside any existing file system or low-level format information.

FS_NOR_ChipErase()#

Description#

Erase an entire NOR.

Files#

fs_nor.h/fs_nor.c

Prototype#

void  FS_NOR_ChipErase (FS_NOR_HANDLE   nor_handle,
                        RTOS_ERR       *p_err)

Arguments#

nor_handle

Handle to a NOR.

p_err

Pointer to variable that will receive return the error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_IO

Returned Value#

none.

Notes / Warnings#

  1. This function should NOT be used while a file system exists on the device, or if the device is low-level formatted, unless the intent is to destroy all existing information.

FS_NOR_XIP_Cfg()#

Description#

Configure NOR flash and (Quad) SPI controller in XIP (eXecute-In-Place) mode.

Files#

fs_nor.h/fs_nor.c

Prototype#

void  FS_NOR_XIP_Cfg (FS_NOR_HANDLE nor_handle,
                      CPU_BOOLEAN   xip_en,
                      RTOS_ERR     *p_err)

Arguments#

nor_handle

Handle to a NOR.

xip_en

XIP mode enable/disable flag.

p_err

Pointer to variable that will receive return the error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_IO

Returned Value#

none.

Notes / Warnings#

none.

FS_NOR_Get()#

Description#

Get an NOR handle from a given media handle.

Files#

fs_nor.h/fs_nor.c

Prototype#

FS_NOR_HANDLE  FS_NOR_Get (FS_MEDIA_HANDLE  media_handle)

Arguments#

media_handle

Handle to a media.

Returned Value#

Handle to a NOR.

Notes / Warnings#

None.

FS_NOR_BlkCntGet()#

Description#

Get the number of blocks on a NOR.

Files#

fs_nor.h/fs_nor.c

Prototype#

CPU_INT32U  FS_NOR_BlkCntGet (FS_NOR_HANDLE   nor_handle,
                              RTOS_ERR       *p_err)

Arguments#

nor_handle

Handle to a NOR.

p_err

Pointer to variable that will receive the return error code(s) from this function:

  • RTOS_ERR_NONE

Returned Value#

The number of blocks.

Notes / Warnings#

None.

FS_NOR_BlkSizeLog2Get()#

Description#

Get the base-2 logarithm of a NOR block size.

Files#

fs_nor.h/fs_nor.c

Prototype#

CPU_INT08U  FS_NOR_BlkSizeLog2Get (FS_NOR_HANDLE   nor_handle,
                                   RTOS_ERR       *p_err)

Arguments#

nor_handle

Handle to a NOR.

p_err

Pointer to variable that will receive the return error code(s) from this function:

  • RTOS_ERR_NONE

Returned Value#

Base-2 logarithm of the block size.

Notes / Warnings#

None.

FS_NOR_FTL_ConfigureLowParams()#

Description#

Configure NOR FTL parameters.

Files#

fs_nor_ftl.h/fs_nor_ftl.c

Prototype#

void  FS_NOR_FTL_ConfigureLowParams (      FS_MEDIA_HANDLE   media_handle,
                                     const FS_NOR_FTL_CFG   *p_cfg,
                                           RTOS_ERR         *p_err)

Arguments#

media_handle

Handle to a media.

p_cfg

Pointer to a NOR FTL configuration structure.

p_err

Pointer to variable that will receive the return error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_SEG_OVF

Returned Value#

none.

Notes / Warnings#

  1. FS_NOR_FTL_ConfigureLowParams() must be called prior to FSBlkDev_Open() or FSMedia_LowFmt(). It will configure a NOR FTL instance using the user specific parameters and allocate all needed resources by the FTL instance. Then FSBlkDev_Open() or FSMedia_LowFmt() can be called and the NOR FTL instance can be obtained from the internal NOR FTL list. Thus avoiding to reallocate resources once more time for the same NOR instance.

  2. The NOR FTL configuration structure has the following fields:

typedef  struct  fs_nor_ftl_cfg {
    CPU_INT08U  RegionNbr;                                      /* Block region within flash.                           */
    CPU_ADDR    StartOffset;                                    /* Start address of data within flash.                  */
    CPU_INT08U  PctRsvd;                                        /* Percentage of device area reserved.                  */
    CPU_INT16U  EraseCntDiffTh;                                 /* Erase count difference threshold.                    */
    CPU_INT32U  DevSize;                                        /* Size of flash, in octets.                            */
    FS_LB_SIZE  SecSize;                                        /* Sector size of low-level formatted flash.            */
} FS_NOR_FTL_CFG;

FS_NOR_FTL_LowCompact()#

Description#

Low-level compact a NOR device.

Files#

fs_nor_ftl.h/fs_nor_ftl.c

Prototype#

void  FS_NOR_FTL_LowCompact (FS_BLK_DEV_HANDLE   blk_dev_handle,
                             RTOS_ERR           *p_err)

Arguments#

blk_dev_handle

Handle to a NOR-based block device.

p_err

Pointer to variable that will receive the return error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_BLK_DEV_CLOSED

  • RTOS_ERR_BLK_DEV_CORRUPTED

  • RTOS_ERR_IO

Returned Value#

none.

Notes / Warnings#

  1. Compacting groups sectors containing high-level data into as few blocks as possible. If an image of a file system is to be formed for deployment, to be burned into chips for production, then it should be compacted after all files & directories are created.

FS_NOR_FTL_LowDefrag()#

Description#

Low-level defragment a NOR device.

Files#

fs_nor_ftl.h/fs_nor_ftl.c

Prototype#

void  FS_NOR_FTL_LowDefrag (FS_BLK_DEV_HANDLE   blk_dev_handle,
                            RTOS_ERR           *p_err)

Arguments#

blk_dev_handle

Handle to a NOR-based block device.

p_err

Pointer to variable that will receive the return error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_BLK_DEV_CLOSED

  • RTOS_ERR_BLK_DEV_CORRUPTED

  • RTOS_ERR_IO

Returned Value#

none.

Notes / Warnings#

  1. Defragmentation groups sectors containing high-level data into as few blocks as possible, in order of logical sector. A defragmented file system should have near-optimal access speeds in a read-only environment. See also 'FS_NOR_FTL_LowCompact() Note #1'.

FS_RAM_Disk_Add()#

Description#

Add a RAM disk instance.

Files#

fs_ramdisk.h/fs_ramdisk.c

Prototype#

void  FS_RAM_Disk_Add (const  CPU_CHAR         *name,
                       const  FS_RAM_DISK_CFG  *p_cfg,
                              RTOS_ERR         *p_err)

Arguments#

name

Media name to be assigned to the created RAM disk.

p_cfg

Pointer to a RAM disk configuration structure.

p_err

Pointer to variable that will receive the return error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_NOT_INIT

  • RTOS_ERR_SEG_OVF

Returned Value#

none.

Notes / Warnings#

(1) The RAM disk configuration structure has the following fields:

typedef  struct  fs_ram_disk_cfg {
    void        *DiskPtr;                                       /* Pointer to region simulating a RAM disk.             */
    FS_LB_QTY    LbCnt;                                         /* Number of logical blocks composing RAM disk region.  */
    FS_LB_SIZE   LbSize;                                        /* Logical block size in bytes.                         */
} FS_RAM_DISK_CFG;

FS_SCSI_Open()#

Description#

Open a SCSI device.

Files#

fs_scsi.h/fs_scsi.c

Prototype#

FS_SCSI_HANDLE  FS_SCSI_Open (FS_MEDIA_HANDLE   media_handle,
                              RTOS_ERR         *p_err)

Arguments#

media_handle

Handle to a media.

p_err

Pointer to variable that will receive the return error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_NOT_INIT

  • RTOS_ERR_IO

Returned Value#

Handle to a SCSI device.

Notes / Warnings#

None.

FS_SCSI_Close()#

Description#

Close a SCSI device.

Files#

fs_scsi.h/fs_scsi.c

Prototype#

void  FS_SCSI_Close (FS_SCSI_HANDLE   scsi_handle,
                     RTOS_ERR        *p_err)

Arguments#

sd_handle

Handle to a SCSI device.

p_err

Pointer to variable that will receive the return error code(s) from this function:

  • RTOS_ERR_NONE

Returned Value#

none.

Notes / Warnings#

None.

FS_SCSI_LU_InfoGet()#

Description#

Get SCSI logical unit information.

Files#

fs_scsi.h/fs_scsi.c

Prototype#

void FS_SCSI_LU_InfoGet (FS_SCSI_HANDLE    scsi_handle,
                         FS_SCSI_LU_INFO  *p_lu_info,
                         RTOS_ERR         *p_err)

Arguments#

ssci_handle

Handle to a SCSI device.

p_lu_info

Pointer to logical unit information structure to be populated.

p_err

Pointer to variable that will receive the return error code(s) from this function:

  • RTOS_ERR_NONE

Returned Value#

none.

Notes / Warnings#

(1) The SCSI logical unit information structure has the following fields:

typedef  struct  fs_scsi_lu_info {
    CPU_BOOLEAN  Removable;                                     /* Flag indicating if LU is removable.                  */
    FS_LB_SIZE   SecDfltSize;                                   /* Default size of a sector.                            */
    FS_LB_QTY    SecCnt;                                        /* Number of sectors composing the device.              */
    CPU_CHAR     VendorID_StrTbl[FS_SCSI_CMD_INQUIRY_VID_FIELD_LEN + 1u];
    CPU_CHAR     ProductID_StrTbl[FS_SCSI_CMD_INQUIRY_PID_FIELD_LEN + 1u];
    CPU_CHAR     ProdRevLevelStrTbl[FS_SCSI_CMD_INQUIRY_PROD_REV_LEVEL_FIELD_LEN + 1u];
} FS_SCSI_LU_INFO;

FS_SD_Open()#

Description#

Open a SD Card or SPI.

Files#

fs_sd.h/fs_sd.c

Prototype#

FS_SD_HANDLE  FS_SD_Open (FS_MEDIA_HANDLE   media_handle,
                          RTOS_ERR         *p_err)

Arguments#

media_handle

Handle to a media.

p_err

Pointer to variable that will receive the return error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_NOT_INIT

  • RTOS_ERR_IO

Returned Value#

Handle to a SD Card or SPI.

Notes / Warnings#

None.

FS_SD_Close()#

Description#

Close a SD Card or SPI.

Files#

fs_sd.h/fs_sd.c

Prototype#

void  FS_SD_Close (FS_SD_HANDLE   sd_handle,
                   RTOS_ERR      *p_err)

Arguments#

sd_handle

Handle to a SD Card or SPI.

p_err

Pointer to variable that will receive the return error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_IO

Returned Value#

none.

Notes / Warnings#

None.

FS_SD_CID_Rd()#

Description#

Read SD CID (Card IDentification number) register.

Files#

fs_sd.h/fs_sd.c

Prototype#

void  FS_SD_CID_Rd (FS_SD_HANDLE   sd_handle,
                    CPU_INT08U    *p_dest,
                    RTOS_ERR      *p_err)

Arguments#

sd_handle

Handle to a SD card.

p_dest

Pointer to 16-byte buffer that will receive SD/MMC Card ID register.

p_err

Pointer to variable that will receive the return error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_IO

Returned Value#

none.

Notes / Warnings#

  1. Refer to specification "Physical Layer Simplified Specification Version 4.10", section '5.2 CID register' for more details about CID fields.

FS_SD_CSD_Rd()#

Description#

Read SD CSD (Card Specific Data) register.

Files#

fs_sd.h/fs_sd.c

Prototype#

void FS_SD_CSD_Rd (FS_SD_HANDLE   sd_handle,
                   CPU_INT08U    *p_dest,
                   RTOS_ERR      *p_err)

Arguments#

sd_handle

Handle to a SD card.

p_dest

Pointer to 16-byte buffer that will receive SD/MMC Card Specific Data register.

p_err

Pointer to variable that will receive the return error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_IO

Returned Value#

none.

Notes / Warnings#

  1. Refer to specification "Physical Layer Simplified Specification Version 4.10", section '5.3.2 CSD Register' for more details about CSD fields.

FS_SD_InfoGet()#

Description#

Get SD information.

Files#

fs_sd.h/fs_sd.c

Prototype#

void  FS_SD_InfoGet (FS_SD_HANDLE   sd_handle,
                     FS_SD_INFO    *p_sd_info,
                     RTOS_ERR      *p_err)

Arguments#

sd_handle

Handle to a SD card.

p_sd_info

Pointer to a SD information structure to be populated.

p_err

Pointer to variable that will receive the return error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_IO

Returned Value#

none.

Notes / Warnings#

(1) The SD information structure has the following fields:

typedef  struct  fs_sd_info {
    CPU_INT32U   BlkSize;                                       /* Block size, in octets (typically 512).               */
    CPU_INT32U   NbrBlks;                                       /* Capacity of device, in blocks.                       */
    CPU_INT32U   ClkFreq;                                       /* Max supported clock freq, in Hz.                     */
    CPU_INT32U   Timeout;                                       /* Communication timeout, in cycles.                    */
    CPU_INT08U   CardType;                                      /* Card type.                                           */
    CPU_BOOLEAN  HighCapacity;                                  /* Standard capacity/high capacity.                     */
    CPU_INT08U   ManufID;                                       /* Manufacturer ID.                                     */
    CPU_INT16U   OEM_ID;                                        /* OEM/Application ID.                                  */
    CPU_INT32U   ProdSN;                                        /* Product serial number.                               */
    CPU_CHAR     ProdName[7];                                   /* Product name.                                        */
    CPU_INT16U   ProdRev;                                       /* Product revision.                                    */
    CPU_INT16U   Date;                                          /* Date.                                                */
} FS_SD_INFO;

FS_NAND_HW_INFO_REG()#

Description#

Registers a NAND memory controller to the platform manager.

Files#

fs_nand.h

Prototype#

FS_NAND_HW_INFO_REG(name, p_hw_info)

Arguments#

name

Unique name for the NAND memory controller. It is recommended to follow the standard "nandX" where X is a digit.

p_hw_info

Pointer to the NAND hardware information structure of type FS_NAND_HW_INFO.

Returned Value#

None.

Notes / Warnings#

  1. This macro should normally be called from the BSP.

FS_NOR_QUAD_SPI_HW_INFO_REG()#

Description#

Registers a Quad SPI controller to the platform manager. A Quad SPI controller interfaces only to NOR flash devices.

Files#

fs_nor.h

Prototype#

FS_NOR_QUAD_SPI_HW_INFO_REG(p_name, p_hw_info)

Arguments#

name

Unique name for the Quad SPI controller. It is recommended to follow the standard "norX" where X is a digit.

p_hw_info

Pointer to the NOR Quad SPI hardware information structure of type FS_NOR_QUAD_SPI_HW_INFO.

Returned Value#

None.

Notes / Warnings#

  1. This macro should normally be called from the BSP.

FS_SD_CARD_HW_INFO_REG()#

Description#

Registers a SD Card (also called SD Host Controller [SDHC]) controller to the platform manager. The SDHC controller is a peripheral found on a microcontroller.

Files#

fs_sd_card.h

Prototype#

FS_SD_CARD_HW_INFO_REG(p_name, p_hw_info)

Arguments#

name

Unique name for the SD Card controller. It is recommended to follow the standard "sdX" where X is a digit.

p_hw_info

Pointer to the SD Card hardware information structure of type FS_SD_CARD_HW_INFO.

Returned Value#

None.

Notes / Warnings#

  1. This macro should normally be called from the BSP.

FS_SD_SPI_HW_INFO_REG()#

Description#

Registers a SD SPI controller to the platform manager. A SD SPI controller refers here to the controller embedded in an external SD card. This SD card is connected to the microcontroller via a SPI interface and thus communicates with a SPI controller located inside the microcontroller. This macro requires that a SPI controller is registered to the platform manager with the macro IO_SERIAL_CTRLR_REG().

Files#

fs_sd_spi.h

Prototype#

FS_SD_SPI_HW_INFO_REG(p_name, p_ctrlr_name, slave_id)

Arguments#

p_name

Unique name for the SD SPI controller. It is recommended to follow the standard "sdX" where X is a digit.

p_ctrlr_name

Unique name identifying a SPI controller registered with IO_SERIAL_CTRLR_REG(). The name should be "spiX" where X is a digit.

slave_id

Slave ID of the SD card on the SPI bus. The same SPI bus can be shared among several slaves (for instance, a Wi-Fi device, a NOR flash device, etc.). In that case, the slave ID allows to select the SD card when transferring data.

Returned Value#

None.

Notes / Warnings#

  1. This macro should normally be called from the BSP.