doc/syscalls/50004_isolated_nonvolatile_storage.md
This Driver provides access to a contiguous, fixed-size region of nonvolatile storage the application can use. This interface supports both 32-bit and 64-bit address spaces for the nonvolatile storage.
Note: use of this interface is protected by StoragePermissions, so
applications will need storage permissions to use this interface.
0Does the driver exist?
SUCCESS if it exists, otherwise NODEVICE.
1Get Size. Query the size of the nonvolatile storage region the application has access to in bytes.
Calling this command will allocate a storage region if one was not previously allocated to the application.
The get size command was accepted and the response will be issued via an upcall.
If the command does not succeed then no upcall will be issued and the command
returns type SyscallReturn::Failure with one of these error codes:
NOSUPPORT: The application does not have permissions to access the
nonvolatile storage.BUSY: A prior request is pending.2Read. Read a region of the app's nonvolatile storage.
The read is asynchronous as the nonvolatile storage may not be attached to main memory bus or mapped to the main address space. The data will be copied into the buffer shared with the kernel via read-write allow 0.
The read is specified by the offset (in bytes) from the beginning of the app's allocated nonvolatile storage region and the length (in bytes) of the read. The length is equal to the size of the allowed read buffer.
Calling this command will allocate a storage region if one was not previously allocated to the application.
The application must have permissions to access nonvolatile storage for the read to succeed. The permission check may be asynchronous, and a permissions error may be returned via the upcall.
The read command was accepted and a response will be issued via the upcall.
If the command does not succeed then no upcall will be issued and the command
returns type SyscallReturn::Failure with one of these error codes:
NOSUPPORT: The application does not have permissions to access the
nonvolatile storage.BUSY: A prior request is pending.3Write. Write a buffer to a region of the app's nonvolatile storage.
The write is asynchronous as the write may require an erase first or the nonvolatile storage may not be attached to main memory bus or mapped to the main address space. The data to be written will be copied from the buffer shared with the kernel via read-only allow 0.
The write is specified by the offset (in bytes) from the beginning of the app's allocated nonvolatile storage region and the length (in bytes) of the write. The length is equal to the size of the allowed buffer.
Calling this command will allocate a storage region if one was not previously allocated to the application.
The application must have permissions to access nonvolatile storage for the write to succeed. The permission check may be asynchronous, and a permissions error may be returned via the upcall.
The write command was accepted and a response will be issued via the upcall.
If the command does not succeed then no upcall will be issued and the command
returns type SyscallReturn::Failure with one of these error codes:
NOSUPPORT: The application does not have permissions to access the
nonvolatile storage.BUSY: A prior request is pending.0Subscribe to get size upcalls. This upcall provides the size of the app's nonvolatile storage region in bytes.
The upcall signature looks like:
fn upcall(s: Statuscode, length: usize);
Upcall arguments:
Statuscode returning the success or failure of the operation.The length argument is only valid if the status code is SUCCESS.
Statuscode ValuesSUCCESS: The get size command succeeded and length is set to the number
of bytes in the app's nonvolatile storage region.NOSUPPORT: The application does not have permissions to access the
nonvolatile storage.NOMEM: There is no space remaining.1Subscribe to read done upcalls. This upcall fires after a read command completes or encounters an error.
The upcall signature looks like:
fn upcall(s: Statuscode);
Upcall arguments:
Statuscode returning the success or failure of the operation.The length argument is only valid if the status code is SUCCESS.
Statuscode ValuesSUCCESS: The read command succeeded and length is set to the number
of bytes read into the allowed buffer.RESERVE: No buffer was allowed for read-write allow 0 or the allowed
buffer has a length of 0.NOMEM: The app has no nonvolatile storage region.NOSUPPORT: The application does not have permissions to access the
nonvolatile storage.INVAL: The read was not within the app's storage region.FAIL: There was an error accessing the underlying storage.2Subscribe to write done upcalls. This upcall fires after a write command completes or encounters an error.
The upcall signature looks like:
fn upcall(s: Statuscode);
Upcall arguments:
Statuscode returning the success or failure of the operation.The length argument is only valid if the status code is SUCCESS.
Statuscode ValuesSUCCESS: The read command succeeded and length is set to the number
of bytes written from the allowed buffer.RESERVE: No buffer was allowed for read-only allow 0 or the allowed
buffer has a length of 0.NOMEM: The app has no nonvolatile storage region.NOSUPPORT: The application does not have permissions to access the
nonvolatile storage.INVAL: The write was not within the app's storage region.FAIL: There was an error accessing the underlying storage.0This buffer to use for writes to the nonvolatile storage.
0This buffer to use for reads from the nonvolatile storage.