henrygab
commented
3 weeks ago original post
Ian has chosen the following path for the near-future: * [ ] CLI command (+ binmode API) to switch storage amongst the four supported modes: * `Host-only` (R/W) * `Firmware-only` (R/W) * `Host and Firmware` (both R/O) * `No access` (e.g., not formatted, both get no access) * [ ] On boot: * [ ] initial mode is `Firmware-only` * [ ] if button is being held down at boot, read configuration, then switch to `Host-only`. * _Intent appears to be to make it easier to copy files to/from the BP5, when terminal software is not (easily) available?_ * [ ] Transitions from `Firmware-only` mode: * [ ] FAIL when the firmware has an open handle * [ ] Handle count appears to already be tracked * [ ] Transitions from `Host-only` mode: * [ ] FAIL when host used `PREVENT_ALLOW_MEDIUM_REMOVAL` and media is still locked * Nota Bene: Since the bus (USB) is still hot-plug, Windows (and likely other OS) will still apply conservative approaches to caching writes, and surprise-removal is still possible. * Nota Bene: May require host-side to initiate a safe-removal / unmount procedure for unlock to be sent * Note that use and support of `PREVENT_ALLOW_MEDIUM_REMOVAL` is an **_aspirational goal_** ... additional testing is needed to verify how the lock and unlock sequences are applied on various host OS. * Although aspirational, if the host is kind enough to give hints that it is writing to the media, may as well try to cooperate (at least when in host-exclusive mode).
Current Design Target
Four NAND Volume States
The state of the NAND volume may exist in one of the following four states: ```c typedef enum _nand_volume_state_t { NAND_VOLUME_STATE_EJECTED = 0, NAND_VOLUME_STATE_SHARED_READONLY, NAND_VOLUME_STATE_FW_EXCLUSIVE, NAND_VOLUME_STATE_HOST_EXCLUSIVE, } nand_volume_state_t; ``` In addition, there is a `MediaChangeNotification` flag, which stores whether the host must see a sequence of Sense/ASC/ASCQ errors when it tries to access the volume.State Transition Table
from \ to | `ejected` | `shared R/O` | `FW Exc` | `Host Exc` ----------|-----:|-----:|-----:|-----: `ejected` | `Y` | `M` | `Y` | `M` `shared R/O` | `Y` | `Y` | `Y` | `M` `FW Exc` | `Y` | `M` | `Y` | `M` `Host Exc` | `Y` | `X` | `Y` | `Y` Where `M` indicates allowed, but must set `MediaChangeNotification` flag. Where `X` may not be permitted ... to be decided later.Main Transition Events
Transition to `NAND_VOLUME_STATE_FW_EXCLUSIVE`, unless media is ejected (e.g., in process of formatting, mounting, ...): * [ ] `nand/nand/ftl_diskio.c / diskio_write()` When calling `f_close()`, check if the handle being closed is a write-capable handle. If so, and this is the final write-capable handle being closed: * [ ] Assert state is `NAND_VOLUME_STATE_FW_EXCLUSIVE` and transition to state `NAND_VOLUME_STATE_SHARED_RO`Non-FileHandle Events
The following FW APIs do not use a file handle, but may change the media state. Therefore, they should set the `MediaChangeNotification` flag explicitly on success. Note that it's safe to set this flag even if the host is not permitted to access the volume: * [ ] `f_mkdir()` * [ ] `f_unlink()` * [ ] `f_rename()` * [ ] `f_chmod()` * [ ] `f_setlabel()`Events to be specially handled
The following change the volume state at a fundamental level, if successful, and should set state to `NAND_VOLUME_STATE_SHARED_READONLY` and explicitly set `MediaChangeNotification`. * [ ] `f_mkfs()` * [ ] `f_mount()` * [ ] `f_fdisk()`Assertions to help validate correctness
The following APIs each require the use of a write-capable file handle. To help catch any missed edge cases, assert that state ends up as `NAND_VOLUME_STATE_FW_EXCLUSIVE` for successful calls to: * [ ] `f_write()` * [ ] `f_truncate()` * [ ] `f_sync()` * [ ] `f_forward()` * [ ] `f_expand()` * [ ] `f_putc()` * [ ] `f_puts()` * [ ] `f_printf()`By deferring the switch from `NAND_VOLUME_STATE_SHARED_RO` to `NAND_VOLUME_STATE_FW_EXCLUSIVE` until there is an actual write to the media, it is hoped to reduce the frequency that the host sees the media eject. (e.g., won't occur if file opened for write, but never written to). Future work: enabling `NAND_VOLUME_STATE_HOST_EXCLUSIVE`.