Svc::FileWorker

Svc::FileWorker is an active F' component used for writing and reading files on the filesystem. Other components needing to read or write files may use this component to perform large/slow file operations without missing their deadlines.

Requirements

Name	Description	Validation
FileWorker-001	FileWorker shall provide an async interface to read contents from a file and return the data in a client-provided buffer	Unit Test
FileWorker-002	FileWorker shall provide an interface to write contents to a file passed in from a client-provided buffer	Unit Test
FileWorker-003	FileWorker shall handle receiving read-done signals while in improper state	Unit Test
FileWorker-004	FileWorker shall handle cancel for reads	Unit Test
FileWorker-005	FileWorker shall validate the inputs to its read, write, and verify port handlers and report malformed inputs via an event and a failure status rather than asserting	Unit Test

Diagrams

States

State	Description
IDLE	FileWorker is ready to accept requests for transfer
READING	In the read process
WRITING	In the write process

Ports

Kind	Port Name	Port Type	Usage
async input	writeIn	Svc.FileWrite	Initiates a file write
output	writeDoneOut	Svc.SignalDone	File write has completed
async input	readIn	Svc.FileRead	Initiates a file read
output	readDoneOut	Svc.SignalDone	File read has completed
guarded input	cancelIn	Svc.CancelStatus	Cancels a current operation
async input	verifyIn	Svc.VerifyStatus	Initiates a verification of a file against an expected CRC checksum
output	verifyDoneOut	Svc.SignalDone	File verification results

Events

Event Name	Severity	Description	Throttle	Arguments
				Name	Type	Description
NotInIdle	warning high	"Not in IDLE state, currently in state: {}"	2	currState	U32
CrcFailed	warning high	"Failed CRC check with {} status"	2	crcStat	U32
CrcVerificationError	warning low	"Failed to verify file. Expected CRC {}. Actual CRC {}"		crcExp	U32
				crcCalculated	U32
ReadFailedFileSize	warning high	"Failed to get filesize with stat {} in read handler"	2	fsStat	U32
OpenFileError	warning high	"Failed to open file {} with stat {}"	2	fileName	string
				size FileNameStringSize fsStat	U32
ReadBegin	activity low	"Reading {} bytes from {}"		fileSize	FwSizeType
				fileName	string
ReadCompleted	activity low	"Finished reading {} bytes from {}"		fileSize	FwSizeType
				fileName	string
ReadError	warning high	"Failed after {} of {} bytes read to {}"		bytesRead	FwSizeType
				readSize	FwSizeType
				fileName	string
ReadAborted	warning low	"Aborted after {} of {} bytes read to {}"		bytesRead	FwSizeType
				readSize	FwSizeType
				fileName	string
ReadTimeout	warning high	"Failed after {} of {} bytes read to {} after exceeding timeout of {} microseconds"		bytesRead	FwSizeType
				readSize	FwSizeType
				fileName	string
				size FileNameStringSize timeout	U64
WriteBegin	activity low	"Beginning write of size {} to {}"		writeSize	FwSizeType
				fileName	string
WriteCompleted	activity low	"Completed write of size {} to {}"		writeSize	FwSizeType
				fileName	string
WriteFileError	warning high	"Failed after {} of {} bytes written to {} with write status {}"	2	bytesWritten	FwSizeType
				writeSize	FwSizeType
				fileName	string
				size FileNameStringSize status	I32
WriteValidationOpenError	warning high	"Failed to open validation file {} with status {}"	2	hashFileName	string
				size FileNameStringSize status	I32
WriteValidationReadError	warning high	"Failed to read validation file {} with status {}"	2	hashFileName	string
				size FileNameStringSize status	I32
WriteValidationError	warning low	"Failed to create hash file {}. Wrote {} bytes when expected to write {} bytes to hash file"		hashFileName	string
				size FileNameStringSize bytesWritten	FwSizeType
				hashSize	FwSizeType
WriteTimeout	warning high	"Failed after {} of {} bytes written to {} after exceeding timeout of {} microseconds"		bytesWritten	FwSizeType
				writeSize	FwSizeType
				fileName	string
				size FileNameStringSize timeout	U64
WriteAborted	warning low	"Aborted after {} of {} bytes written to {}"		bytesWritten	FwSizeType
				writeSize	FwSizeType
				fileName	string
InvalidInput	warning high	"Invalid input in {} handler: {}"		handler	string
				issue	string

3.4 Functional Description

Each *In port handler validates its arguments before performing any file operation. Malformed inputs — such as an empty path, an invalid (null or zero-length) buffer, a write offset past the end of the buffer, or a path too long for the filename buffer — are reported by emitting an InvalidInput warning event and returning INVALID_INPUT to the client, rather than triggering an FW_ASSERT. This ensures that invalid, externally supplied (e.g. ground-commanded) inputs are surfaced to operators as telemetry instead of causing an assertion failure.

3.4.1 writeIn_handler

Calling component passes in a buffer for writing to file, the file location is path, and the offset to start writing at.

1. Validate inputs. If the path is empty, the buffer is invalid, the write offset is past the end of the buffer, or the path is too long for the filename buffer, emit an InvalidInput event and return INVALID_INPUT
2. If not in IDLE state, return NOT_IDLE
3. Set state to WRITING
4. Open a file at the provided path and write contents of client-provided buffer to it
5. After file is finished being written to, also write a validation CRC file
6. Return to client with write size and set state to IDLE

3.4.2 readIn_handler

Calling component passes in a file path path to read and a buffer for client to read from

1. Validate inputs. If the path is empty or the buffer is invalid, emit an InvalidInput event and return INVALID_INPUT
2. If not in IDLE state, return NOT_IDLE
3. Set state to READING
4. Verify checksum. If checksum fails, return FAILED_CRC and set state to IDLE
5. Otherwise, get file size. If getting the file size fails, emit ReadFailedFileSize and return FAILED_FILE_SIZE, setting state to IDLE
6. Read from file into buffer provided by the client
7. Send back the buffer and set state to IDLE

3.4.3 verifyIn_handler

1. Validate the input path. If the path is empty, emit an InvalidInput event and return INVALID_INPUT
2. Verify checksum. If checksum fails, return FAILED_CRC
3. Get file size. If file size fails, return FAILED_FILE_SIZE
4. Return file size to client

3.4.4 cancelIn_handler

1. Set abort flag to true
2. Return DONE status