fs: File system functions

Top  Previous  Next

The file system functions offers support for standard Windows FAT16/32 format 8.3 file systems. This provides applications with the opportunity to have an almost unlimited storage capacity for extensive data logging, databases, user configurations, etc.

By using standard SD-CARD technology or USB drives, it is straightforward to exchange data with any Windows PC (or any other FAT16/32-compatible platform).
 
 

This table show how the medias are identified in VPL:

 

 

Media

ID

Drive

SD-CARD

0

A:

Internal drive

1

B:

Project drive

2

P:

USB drive

3

U:

 

 

The drives are addressed by using the drive name A:, B:, P: or U:, for example "B:\DOC\MYLOG.TXT".

 

 

Functions operating on the media:

 


fsMediaPresent

Determines if the media is present.


fsMediaWriteProtected

Determines if the media is write-protected.


fsMediaOpen

Opens a media.


fsMediaClose

Closes a media.


fsMediaQuickFormat

Formats a media.


fsMediaEject

Ejects a media.


fsMediaSize

Retrieves the size of the media.


fsMediaFree

Retrieves the amount of the free space on the media.


fsStatusLEDEnable

Enables or disables status-LED.

 

 

Functions operating on directories:

 


fsDirCreate

Create a new directory.


fsDirChange

Change directory.


fsDirCurrent

Retrieves current directory path.


fsDirCatalog

Lists all directory items (files and directories).


fsDirDelete

Deletes a directory.

 

 

Functions operating on files:

 


fsFileCreate

Creates a new file.


fsFileOpen

Opens an existing file.


fsFileExists

Determines if a file exists.


fsFileRename

Renames a file.


fsFileMove

Moves a file.


fsFileDelete

Deletes a file.


fsFileStatus

Retrieves status of an opened file.


fsFileGetCreateTime

Retrieves the time of file creation.


fsFileGetSize

Retrieves the size of a file.


fsFileSeek

Moves the file pointer.


fsFilePosition

Gets the current file pointer position.


fsFileRead

Reads a block of data from the file.


fsFileReadString

Reads a string from the file.


fsFileWrite

Writes a block of data to the file.


fsFileWriteString

Writes a string to a file.


fsFileWriteStringNL

Writes a string that includes a line break at the end to a file.


fsFileClose

Closes a file.


fsFileFlush

Flushes cached write operations to the media.

 


Definitions:


Absolute path

A path to a file or directory that includes all sub-directories from the root directory, e.g. "\dir1\dir2\file.txt".


Relative path

A path to a file or directory relative to the current directory, e.g. "dir1\dir2\file.bin" or "..\dir1\file.dat".

 

File system Consistency

The firmware does everything possible to maintain the consistency of the file system. It is ensured that shutting down an operation or performing a controlled reset will automatically be handled by the firmware so that the file system is shut down in a consistent state.

Media removal without the use of fsMediaEject or hardware reset should be avoided as this can result in an inconsistent state of the file system and, in a worst case scenario, even loss of data.

In case of an uncontrolled shutdown, or reinserting a non-ejected media, the firmware will automatically check and repair the file system. As this phase can take some time, the file system will be unavailable until the completion of the operation. The file system API will return a -22 (media is busy) error code during this phase.

In case of a repair operation, the fault entry "Drive X: has been repaired due to unexpected shutdown." will be present in the fault log after the repair has completed, where X is the letter of the media.

 

 

The implementation of the FAT format 8.3 file system has the following limitations:

The absolute path is limited to 60 characters.

It is possible to have 16 files open simultaneously.

The file name is restricted to a maximum length of 8 characters plus the 3 file type characters. The "." separator is not included.

The file name must not contain spaces or special characters. "-" or "_" are both allowed, though.

A file with a long file name can be accessed with the "~" character, e.g. "Long Filename.txt" is accessed as "LONGFI~1.TXT".

A directory name must not contain "." or any other special characters as stated above.

"\" (backslash) is used as a directory separator.

It supports standard SD-CARDs (non-SDHC) with a capacity of up to 2 GB and SD-CARDs (SDHC) with a capacity of up to 32 GB.

If more than one partition is present on the media, the file system will use the first.

There is a separate working directory for each thread. When the thread is first started, the working directory is the root of the drive.

 

 

Using the Internal Flash drive.

 

NX32L devices:

The capacity of the internal drive of an NX32L devices ranges from 61 MB to 4 GB and utilizes different types of flash technology.

The total number of writable bytes are limited for any flash technology and is calculated as follows:

 

TBW = (CAP * PE) / WAF

 

TBW is the Total Bytes Written before exceeding the guaranteed endurance of the device.

CAP is the size of the partition where the wear-leveling is performed by the system or media controller. This size will often be different than the size of the internal drive due to compression and other data at the same partition.

PE is the Program/Erase factory that depends on the NAND flash technology used.

WAF  (Write Amplification Factor) is between 4 and 8, that depends on the applications write behavior.

For example, large sequential writes produce a lower WAF, while random writes of small data blocks produce a higher WAF. Typically WAF is set to 8.

 

The values for CAP and PE are as follows:

Device

Capacity (CAP)

Program/Erase (PE)

RTCU NX-200 / NX-400 / NX-900

270 MB

100000

RTCU LX5 pro / LX5 eco

180 MB

80000

RTCU LX4 pro

61 MB

80000

RTCU LX2 pro

4000 MB

3000

 

Assuming that WAF=8 then TBW can be calculated for each device:

Device

Calculation

TBW (MB)

RTCU NX-200 / NX-400 / NX-900

(270*100000) / 8

3375000

RTCU LX5 pro / LX5 eco

(180*80000) / 8

1800000

RTCU LX4 pro

(61*80000) / 8

610000

RTCU LX2 pro

(4000*3000) / 8

1500000

 

 

For example, a workload featuring 500 MB of daily write usage cycle will reach end of life as follows:

Device

Calculation

Duration

RTCU NX-200 / NX-400 / NX-900

3375000 / 500

6750 days = ~18 years

RTCU LX5 eco / LX5 pro

1800000 / 500

3600 days = ~9 years

RTCU LX4 pro

610000 / 500

1220 days = ~3 years

RTCU LX2 pro

1500000 / 500

3000 days = ~8 years

 

 

The above table shows that care must be taken for write data intensive applications and on the RTCU LX4 pro it is recommended to use an SD-CARD for such applications.

 

 

 

X32/NX32 devices:

The size of the internal flash drive is specified in the data sheet and/or technical manual of the device in question.

When using the internal flash drive, it must be observed that the flash memory technology used is the same as used for Persistent Memory and Datalogger storage. For this reason, there is a limited number of write operations possible, and the following must therefore be observed:

 

The file system will automatically perform wear leveling - thus swapping heavily used sectors in the flash with lesser used sectors.

The size of a sector is 512 bytes.

 

Using a device with 4 MB or 8 MB internal flash drive the wear leveling, combined with the effective write throughput, basically means that there is no write endurance limitations to be observed.

 

For devices with a small internal flash drive of 512 KBytes the write endurance limitation must however be observed.
512 KBytes translates into initially 1020 usable sectors, each sector can be rewritten a minimum 100,000 times before wear-out occurs.

 

The following number of write operations can be expected on the Internal Flash drive:

 

With a file OPEN, WRITE and CLOSE operation on the same 512 bytes file, a total number of approx. 51 million write operations can be made.

With a file CREATE, WRITE and CLOSE operation on a 512 bytes file, a total number of approx. 25.5 million write operations can be made.

 

With a file OPEN, WRITE and CLOSE operation on the same 1024 bytes file, a total number of approx. 34 million write operations can be made.

With a file CREATE, WRITE and CLOSE operation on a 1024 bytes file, a total number of approx. 20.4 million write operations can be made.

 

Writing every 10 seconds, 24 hours a day, will allow CREATE, WRITE and CLOSE operations on a 1024 bytes file for more than 6 years!

 

 

 

Using the Intellisync Project Drive.

The Intellisync Project Drive is read-only from VPL, and does not support directories. To write to the project drive, it must be synchronized using e.g. the RTCU IDE, using User files. It is not possible to read VSX files from the project drive.