Input/output#

File operations are supported in the hardware abstraction layer using an abstraction that roughly maps onto standard file operations on most platforms. The file operations only support a single file open at one time so no file handle is passed in to any of the operations. Files must still be opened before they are used and closed when they are finished with (to allow subsequent file operations).

Instead of a file path an enumeration is used which represents a particular file that should be saved. This is so an appropriate location can be chosen for the given platform.

Functions#

Enums

enum ioFilePath_t#

Abstracted file path.

All file operations use an abstracted path so they can be stored in the appropriate location dependent on the platform.

Values:

enumerator ioPathSaveFile#

save file used in SAVE and LOAD functions

enumerator ioPathPgmFile#

program file

enumerator ioPathTestPgms#

test programs

enumerator ioPathBackup#

backup file for full state used in simulators

enum ioFileMode_t#

File open mode.

Files must be opened with a mode to indicate whether they will be read, or written to, or both. All operations are in binary modes where the platform allows this to be specified.

Values:

enumerator ioModeRead#

open the file in read-only mode

enumerator ioModeWrite#

open the file in write-only mode

enumerator ioModeUpdate#

open the file in read/write mode

Functions

bool ioFileOpen(ioFilePath_t path, ioFileMode_t mode)#

Open a file.

File operations require a file to be opened first. Opening the file returns true if the file was opened and false otherwise. The HAL only allows a single open file at any one time and this should be closed with ioFileClose as soon as possible.

Parameters

  • path – [in] the enumeration value for the particular file to open

  • mode – [in] the mode to open the file (read, write, update)

Returns

true if file opened successfully

void ioFileWrite(const void *buffer, uint32_t size)#

Write to the open file.

Parameters

  • buffer – [in] the binary stream to write

  • size – [in] how many bytes to write

uint32_t ioFileRead(void *buffer, uint32_t size)#

Read from the open file.

The buffer must have an allocated size at least as long as the specified size.

Parameters

  • buffer – [out] the allocated buffer to read into

  • size – [in] how many bytes to read

Returns

how many bytes were actually read

void ioFileSeek(uint32_t position)#

Move to a particular position in the file.

This is an absolute position from the beginning of the file.

Parameters

  • position – [in] position to move to

void ioFileClose(void)#

Close the open file.

Files must be closed to avoid resource leaks.

bool ioFileRemove(ioFilePath_t path, uint32_t *errorNumber)#

Delete the given file.

The file should not be open.

Parameters

  • path – [in] file to delete

  • errorNumber – [out] error code given by the platform if there’s an error

Returns

true if delete succeeded

Example#

File operations should always close the file after it has been opened. Here is a read-only example:

ioFileOpen(ioPathSaveFile, ioModeRead);
char buffer[256];
ioFileRead(buffer, 256);
ioFileClose();