Skip to content

Latest commit

 

History

History
643 lines (420 loc) · 21.3 KB

filesystem-interfaces.md

File metadata and controls

643 lines (420 loc) · 21.3 KB
Raw

Filesystem interfaces

Filesystem interfaces are services that act as a layer of indirection between a storage driver and the sys::fs service. Their role is to translate all common filesystem operations, such as items management and modification, for filesystems that aren't natively supported. They heavily communicate with the sys::hw service to communicate with the underlying storage device.

A filesystem is tied to only one partition, and each partition has a filesystem. A storage space is made, unless empty, of a partitions table which lists all the available partitions.

Most methods and notifications of filesystems interfaces are also available in the sys::fs service, with first perform permissions checking and determines the device and location to perform the operation on. It also leverages many more powerful features such as items watching, and features that are our of the scope of a filesystem interface such as partitions management.

As an application can only expose one single filesystem interface service, the said service will handle all of the hardware devices driven by the said process. This is why the the SOR of the target partition and filesystem is provided for each request.

Nomenclature

Storage operating range

The storage operating range (SOR) is a 40-byte information transmitted to all operation methods of the filesystem interface to indicate where the requested operation should be performed and on which devices.

It is composed of:

  • The device's UDI (8 bytes)
  • The partition's first byte address on the device (8 bytes)
  • The partition's last byte address on the device (8 bytes)
  • Authorization token (8 bytes)
  • The filesystem's FSID (8 bytes)

The FSID is only useful to identify partitions more easily, and to inform clients in notifications.

All SOR sent to the interface service are guaranteed to follow this specification, but may be invalid in case of a bad timing (e.g. authorization is revoked just before a request is performed).

Filesystem paths

Filesystem paths are used to refer to specific filesystem elements and are encoded as either a 0x01 byte followed by a FEID, or a 0x02 byte followed by a split path.

All filesystem paths sent to the interface service are guaranteed to follow this specification.

Split paths

All paths manipulated and returned by a filesystem interface services are encoded as split paths: delimited lists of delimited strings.

Each entry of the list must be a path's component. The entries, joined with a slash (/), should form a valid path.

Empty and . components are ignored, while components equal to .. will make this component ignored and remove the previous component in the list.

The slash (/) character is forbidden in components.

An empty path refers to the root directory (when applicable).

Filenames

Filenames are a delimited strings with a few restrictions:

  • Slash / characters are forbidden
  • NULL characters (U+0000) are forbidden

Moreover, filenames cannot be:

  • Empty
  • Be made only of spaces or insecable spaces
  • Strictly equal to .
  • Strictly equal to ..
  • Longer than 65535 characters

Additional limitations may apply for some filesystems. Refer to each filesystem's specification to see the eventual limitations on filenames.

All filenames sent to the interface service are guaranteed to be follow this specification.

Capabilities list

The capabitilies list is a 2-byte long value which indicate the capabitilies of a given filesystem:

  • Bit 0: set if the filesystem is writable
  • Bit 1: set if the filesystem handles symbolic links
  • Bit 2: set if the filesystem allows symbolic links to non-existing items
  • Bit 3: set if the filesystem allows symbolic links to cross-filesystem items (need to store the target's FSID)
  • Bit 3: set if the filesystem supports hidden flag
  • Bit 4: set if the filesystem supports readonly flag
  • Bit 5: set if the filesystem can store creation dates
  • Bit 6: set if the filesystem can store modification dates
  • Bit 7: set if the filesystem can store last access dates
  • Bit 8: set if the filesystem can store an owner UID on 8 bytes
  • Bit 9: set if the filesystem can natively store a storage permissions map
  • Bit 10: set if the interface can store a storage permissions map in the filesystem
  • Bit 11: set if the filesystem supports ahead space reservation

In case the filesystem can't natively handle a storage permissions map (SPM), the interface is allowed to store, query and update the map in the filesystem by itself, using non-native ways such as extended attributes. In such case, the relevant bit must be set to indicate a SPM can be stored on this filesystem.

This list acts as a contract between the service and the sys::fs service ; if a capability bit is not set, the related methods are guaranteed to never be called. If it is set, the "incompatibility" error code present in such methods cannot be returned or it will be considered a bug.

Filesystem metadata

A filesystem metadata is a structure describing the a single filesystem:

  • Capabilities list (2 bytes)
  • Cluster size in bytes (4 bytes)
  • Partition's total size in bytes (8 bytes)
  • Partition's used space in bytes (8 bytes)
  • Partition's free space in bytes (8 bytes) - used in case a part of the partition could not be used for any reason
  • Optional partition's name as a delimited string
  • Optional partition's icon

Item type byte

An item type byte is a single-byte value describing the type of a single item in a filesystem:

  • 0x01: directory
  • 0x02: file
  • 0x03: symbolic link
  • 0xFF: unknown item type

Item flags

Each item has associated flags:

  • Bit 0: hidden flag
  • Bit 1: read-only flag

Item metadata

An item metadata is a structure describing the content of a single item in a filesystem:

Methods

0x0001 HANDLED_FS_LIST

Get informations about each filesystem handled by the current interface.

Arguments:

None

Answer:

Errors:

none

0x0002 IS_VALID_PARTITION

Check if a given partition is of the type of filesystem handled by the current interface.

Arguments:

  • First bytes of the partition (512 bytes)
  • Last bytes of the partition (512 bytes)

Answer:

  • Identifier of the filesystem if it can be handled by the current interface, 0 otherwise (1 byte)

Errors:

None

0x0003 FS_METADATA

Get metadata on a given filesystem.

Arguments:

  • SOR (40 bytes)

Return value:

Error codes:

  • 0x3000: Invalid SOR provided

0x1000 ITEM_EXISTS

Check if a given item exists.

Arguments:

Return value:

Errors:

  • 0x3000: Invalid SOR provided

0x1001 FEID_TO_SPLIT

Convert a FEID to the corresponding split path.

Arguments:

Return value:

Errors:

  • 0x3000: Invalid SOR provided
  • 0x3001: The provided FEID was not found in the filesystem

0x1002 ITEM_METADATA

Get the metadata of a given item.

Arguments:

Return value:

Errors:

  • 0x3000: Invalid SOR provided
  • 0x3001: The provided path was not found

0x1003 RENAME_ITEM

Rename an existing item.

Arguments:

Errors:

  • 0x3000: Invalid filename provided
  • 0x3001: Invalid SOR provided
  • 0x3002: The provided path was not foud

0x1004 MOVE_ITEM

Move an existing item.

Arguments:

Errors:

  • 0x1000: Invalid filename provided
  • 0x3000: Invalid SOR provided
  • 0x3001: The provided path was not found
  • 0x3002: Target directory was not found
  • 0x4000: Target directory's maximum capacity has been reached
  • 0x4001: Maximum nested items number has been reached
  • 0x4002: Maximum path length has been reached
  • 0x4003: Item cannot be moved for unspecified reasons
  • 0x4FFF: Unspecified filesystem error

0x1005 DELETE_ITEM

Delete an item.

Arguments:

Return value:

None

Errors:

  • 0x3000: Invalid SOR provided
  • 0x3001: Item was not found
  • 0x3002: Cannot remove a non-empty directory
  • 0x4FFF: Unspecified filesystem error

0x2000 CREATE_DIRECTORY

Create a directory.

Arguments:

Return value:

None

Errors:

  • 0x1000: Invalid filename provided
  • 0x3000: Invalid SOR provided
  • 0x3001: Parent directory was not found
  • 0x4000: Directory's maximum capacity has been reached
  • 0x4001: Maximum nested items number has been reached
  • 0x4002: Maximum path length has been reached
  • 0x4FFF: Unspecified filesystem error

0x2001 READ_DIRECTORY

List all entries in a directory.

If the provided offset is larger than the number of entries in the directory, all remaining items must be returned.
If the number of items to get is larger than the number of entries in the directory less the start offset, all remaining items must be returned.

Arguments:

  • SOR (40 bytes)
  • Filesystem path
  • Start offset (8 bytes)
  • Number of items to get (8 bytes) - 0 to list all items at once
  • Optional total number of entries, if available (1 + 8 bytes)
  • Hidden flag match (1 byte): set to 0x00 to match only non-hidden items, 0x01 to match all items

Return value:

Errors:

  • 0x3000: Invalid SOR provided
  • 0x3001: Directory was not found
  • 0x4FFF: Unspecified filesystem error

0x3000 CREATE_FILE

Create a file.

The reserved size is only provided if the interface reported the filesystem as supporting this feature.

Arguments:

Return value:

None

Errors:

  • 0x1000: Invalid filename provided
  • 0x3000: Invalid SOR provided
  • 0x3001: Parent directory was not found
  • 0x4000: Directory's maximum capacity has been reached
  • 0x4001: Maximum nested items number has been reached
  • 0x4002: Maximum path length has been reached
  • 0x4003: Storage's capacity exceeded
  • 0x4004: Maximum individual file size exceeded
  • 0x4005: Filesystem's free space exceeded
  • 0x4FFF: Unspecified filesystem error

0x3001 READ_FILE_SYNC

Read a file synchronously.

If no read length is provided, the whole file must be read.

Arguments:

  • SOR (40 bytes)
  • File's path
  • Start offset address (8 bytes)
  • Optional length to read (1 + 8 bytes)

Return value:

  • Number of read bytes (8 bytes)
  • File's content

Errors:

  • 0x3000: Invalid SOR provided
  • 0x3001: Start offset is out-of-range
  • 0x4FFF: Unspecified filesystem error

0x3002 READ_FILE_ASYNC

Asynchronously read a file to a writable abstract memory segment (AMS).

THe number of bytes to read is always provided to ensure it does not accidentally exceed the AMS's size.

When the read is complete, a FILE_READ notification must be sent to the client.

Arguments:

  • SOR (40 bytes)
  • File's path
  • Start offset address (8 bytes)
  • Number of bytes to read (8 bytes)
  • AMS identifier (8 bytes)

Return value:

  • Generated task identifier (8 bytes)

Errors:

  • 0x3000: Invalid SOR provided
  • 0x3001: Invalid AMS ID provided
  • 0x4FFF: Unspecified filesystem error

0x3003 WRITE_FILE_SYNC

Synchronously write a buffer to a file.

If no offset address is provided, the file's content must be completely overriden with the provided buffer.

Arguments:

  • SOR (40 bytes)
  • File's path
  • Optional write offset address (1 + 8 bytes)
  • Number of bytes to write (8 bytes)
  • Buffer to write (8 bytes)

Return value:

None

Errors:

  • 0x3000: Invalid SOR provided
  • 0x3001: Offset is out-of-range
  • 0x4000: Storage's capacity exceeded
  • 0x4001: Maximum individual file size exceeded
  • 0x4002: Filesystem's free space exceeded
  • 0x4FFF: Unspecified filesystem error

0x3004 WRITE_FILE_ASYNC

Asynchronously write a readable abstract memory segment (AMS) to a file.

If no offset address is provided, the file's content must be completely overriden with the provided buffer.

When the writing is complete, a FILE_WRITTEN notification must be sent to the client. The notification must not be sent before the current method returned successfully.

Arguments:

  • SOR (40 bytes)
  • File's path
  • Optional write offset address (1 + 8 bytes)
  • Number of bytes to write (8 bytes)
  • AMS identifier (8 bytes)

Return value:

  • Generated task identifier (8 bytes)

Errors:

  • 0x3000: Invalid SOR provided
  • 0x3001: Invalid AMS ID provided
  • 0x4FFF: Unspecified filesystem error

0x4000 CREATE_SYMLINK

Create a symbolic link.

Arguments:

Return value:

None

Errors:

  • 0x1000: Invalid filename provided
  • 0x3000: Invalid SOR provided
  • 0x3001: Parent directory was not found
  • 0x3002: Cannot create symbolic links to cross-filesystem items
  • 0x3003: Cannot create symbolic links to non-existing items
  • 0x4000: Directory's maximum capacity has been reached
  • 0x4001: Maximum nested items number has been reached
  • 0x4002: Maximum path length has been reached
  • 0x4003: Storage's capacity exceeded

0x4001 UPDATE_SYMLINK

Create a symbolic link.

Arguments:

Return value:

None

Errors:

  • 0x3000: Invalid SOR provided
  • 0x3001: Provided path was not found
  • 0x3002: Cannot crate symbolic links to cross-filesystem items
  • 0x3003: Cannot crate symbolic links to non-existing items

0x4002 READ_SYMLINK

Read a symbolic link's target.

Arguments:

Return value:

Errors:

  • 0x3000: Invalid SOR provided
  • 0x3001: Provided path was not found
  • 0x4000: Symbolic link is cyclic

0xF000 FORMAT_ASYNC

Asynchronously format the partition to get an empty filesystem. Once the formatting is complete,

Arguments:

  • SOR (40 bytes)
  • Optional new partition's sector size, in bytes (8 bytes)

Return value:

  • Generated task identifier (8 bytes)

Error codes:

  • 0x1000: Invalid sector size provided
  • 0x3000: Invalid SOR provided

Notifications

0x3002 FILE_READ

Sent to a client after an asynchronous file reading requested using the READ_FILE_ASYNC method completed.

Datafield:

  • Task identifier (8 bytes)
  • Fallible result with:
    • Success data: number of bytes read (8 bytes)
    • Error code (1 byte)
      • 0x20: Start offset is out-of-range
      • 0x40: Unspecified filesystem error

0x3004 FILE_WRITTEN

Sent to a client after an asynchronous file writing requested using the WRITE_FILE_ASYNC method completed.

Datafield:

  • Task identifier (8 bytes)
  • Fallible result with:
    • Success data: None
    • Error code (1 byte):
      • 0x20: Start offset is out-of-range
      • 0x31: Maximum individual file size exceeded
      • 0x32: Filesystem's free space exceeded
      • 0x40: Unspecified filesystem error

0xF000 FORMATTED

Sent to a client after an formatting requested using the FORMAT_ASYC method completed.

Datafield:

  • Task identifier (8 bytes)
  • Fallible result with:
    • Success data: None
    • Error code (1 byte):
      • 0x40: Unspecified filesystem error