File IO

Component Type: Input/Output

Status: Implemented

Overview

CIOFile provides read/write access to files on the device file system through the standard Dawn IO abstraction. This lets protocols perform large data transfers (firmware images, authorization data, binary databases) through a uniform interface without needing protocol-specific file handling logic.

Implementation

Security

File access is restricted to two allowed directory prefixes:

  • /data/ - persistent storage

  • /tmp/ - temporary storage

Any path that does not start with one of these prefixes is rejected with -EACCES at init() time, before the file is opened. Paths containing the .. sequence are also rejected unconditionally to prevent directory traversal attacks.

The file path is read-only configuration embedded in the device descriptor. It cannot be changed at runtime, eliminating the attack surface of a descriptor that redirects IO to sensitive system files.

Permissions

The permission mode is configured as a descriptor config item:

Enum value

Meaning

IO_FILE_PERM_READ (0)

File can only be read

IO_FILE_PERM_WRITE (1)

File can only be written; created if it does not exist

IO_FILE_PERM_RW (2)

File can be read and written; created if it does not exist

IO_FILE_PERM_WRITE_ONCE (3)

File can be written exactly once; any later write returns -EPERM

isRead() and isWrite() return based on the configured permission so that protocols can query capability before performing I/O.

Data Model

CIOFile uses DTYPE_BLOCK with 1-byte data units and is seekable (isSeekable() returns true).

  • getDataSize() - returns the tracked file size in bytes. It is initialized from fstat() when the file is opened and updated after successful writes.

  • getDataDim() - same as getDataSize() (1-byte units).

  • getDataImpl() / setDataImpl() - whole-file access (seek to offset 0 then read/write the entire file).

  • getDataAtImpl() / setDataAtImpl() - partial access at a byte offset (lseek + read/write), used by protocols for chunked file transfer.

Typical Use Cases

Descriptor access

Mount the device descriptor binary as a read-only file IO so that a protocol can download the full descriptor in chunks.

Firmware update

A write-only file IO pointing to an update staging file allows a firmware update protocol to stream the image in chunks without special-casing file handling.

Authorization data

Write-only IO for a credentials or token file, written once during provisioning.

Database / buffer

Read-write IO pointing to a persistent data file that multiple protocols can read from or write to.

Configuration

Kconfig

  • CONFIG_DAWN_IO_FILE: enables file-system IO support. Depends on CONFIG_DAWN_IO_SEEKABLE.

YAML

ios:
  - id: file1
    type: fileio
    config:
      path: "/tmp/mydata.bin"
      perm: 0

Supported perm values:

  • 0: read

  • 1: write

  • 2: read-write

  • 3: write-once

External Control

ControlIO: not supported.

TriggerIO: not supported.

Doxygen