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#
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_NONERTOS_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_NONERTOS_ERR_NOT_INITRTOS_ERR_BLK_DEV_OPENEDRTOS_ERR_BLK_DEV_LOW_FMT_INCOMPATIBLERTOS_ERR_BLK_DEV_LOW_FMT_INVALIDRTOS_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_NONERTOS_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_NONERTOS_ERR_BLK_DEV_CLOSEDRTOS_ERR_BLK_DEV_CORRUPTEDRTOS_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_NONERTOS_ERR_BLK_DEV_CLOSEDRTOS_ERR_BLK_DEV_CORRUPTEDRTOS_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_NONERTOS_ERR_BLK_DEV_CLOSEDRTOS_ERR_BLK_DEV_CORRUPTEDRTOS_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_NONERTOS_ERR_BLK_DEV_CLOSEDRTOS_ERR_BLK_DEV_CORRUPTEDRTOS_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_NONERTOS_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_NONERTOS_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_NONERTOS_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_NONERTOS_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_NONERTOS_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#
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_NONERTOS_ERR_NOT_INITRTOS_ERR_NOT_FOUNDRTOS_ERR_BLK_DEV_OPENEDRTOS_ERR_IO
Returned Value#
Notes / Warnings#
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_NONERTOS_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_NONERTOS_ERR_NOT_FOUNDRTOS_ERR_IO
Returned Value#
Type of the media. The possible types can be:
FS_MEDIA_TYPE_RAM_DISKFS_MEDIA_TYPE_NORFS_MEDIA_TYPE_NANDFS_MEDIA_TYPE_SD_SPIFS_MEDIA_TYPE_SD_CARDFS_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_DISKFS_MEDIA_TYPE_NORFS_MEDIA_TYPE_NANDFS_MEDIA_TYPE_SD_SPIFS_MEDIA_TYPE_SD_CARDFS_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_NONERTOS_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_NONERTOS_ERR_NOT_INITRTOS_ERR_IORTOS_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_NONERTOS_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_NONERTOS_ERR_IO
Returned Value#
none.
Notes / Warnings#
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_NONERTOS_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_NONERTOS_ERR_INVALID_STATERTOS_ERR_SEG_OVFRTOS_ERR_INVALID_CFG
Returned Value#
none.
Notes / Warnings#
FS_NAND_FTL_ConfigureLowParams()must be called prior toFSBlkDev_Open()orFSMedia_LowFmt(). It will configure a NAND FTL instance using the user specific parameters and allocate all needed resources by the FTL instance. ThenFSBlkDev_Open()orFSMedia_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.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_NONERTOS_ERR_NOT_INITRTOS_ERR_NOT_FOUNDRTOS_ERR_MEDIA_CLOSEDRTOS_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_NONERTOS_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_NONERTOS_ERR_IO
Returned Value#
none.
Notes / Warnings#
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_NONERTOS_ERR_IO
Returned Value#
none.
Notes / Warnings#
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.
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.
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.
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_NONERTOS_ERR_IO
Returned Value#
none.
Notes / Warnings#
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_NONERTOS_ERR_IO
Returned Value#
none.
Notes / Warnings#
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_NONERTOS_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_NONERTOS_ERR_SEG_OVF
Returned Value#
none.
Notes / Warnings#
FS_NOR_FTL_ConfigureLowParams()must be called prior toFSBlkDev_Open()orFSMedia_LowFmt(). It will configure a NOR FTL instance using the user specific parameters and allocate all needed resources by the FTL instance. ThenFSBlkDev_Open()orFSMedia_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.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_NONERTOS_ERR_BLK_DEV_CLOSEDRTOS_ERR_BLK_DEV_CORRUPTEDRTOS_ERR_IO
Returned Value#
none.
Notes / Warnings#
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_NONERTOS_ERR_BLK_DEV_CLOSEDRTOS_ERR_BLK_DEV_CORRUPTEDRTOS_ERR_IO
Returned Value#
none.
Notes / Warnings#
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_NONERTOS_ERR_NOT_INITRTOS_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_NONERTOS_ERR_NOT_INITRTOS_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_NONERTOS_ERR_NOT_INITRTOS_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_NONERTOS_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_NONERTOS_ERR_IO
Returned Value#
none.
Notes / Warnings#
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_NONERTOS_ERR_IO
Returned Value#
none.
Notes / Warnings#
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_NONERTOS_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#
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#
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#
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#
This macro should normally be called from the BSP.