documentation update

README.md

@@ -18,6 +18,7 @@
  - Dedicated open source menu written specifically for this flashcart - [N64FlashcartMenu](https://github.com/Polprzewodnikowy/N64FlashcartMenu)
  - Enhanced [UltraCIC_C](https://github.com/jago85/UltraCIC_C) emulation with automatic region switching and programmable seed/checksum values
  - PC app for communicating with flashcart (game/save data upload/download, feature enable control and debug terminal)
+ - SD card accessible via USB interface with the use of the PC app
  - [UNFLoader](https://github.com/buu342/N64-UNFLoader) support
  - Initial programming via UART header or dedicated JTAG/SWD interfaces
  - Software and firmware updatable via USB interface

docs/00_quick_startup_guide.md

@@ -1,50 +1,38 @@
-- [First time setup on PC](#first-time-setup-on-pc)
+- [First time setup](#first-time-setup)
-- [Firmware backup/update](#firmware-backupupdate)
+  - [Standalone mode (Running menu and games on the N64)](#standalone-mode-running-menu-and-games-on-the-n64)
-- [Running menu in standalone mode](#running-menu-in-standalone-mode)
+  - [Developer mode (Uploading ROMs from the PC, and more)](#developer-mode-uploading-roms-from-the-pc-and-more)
-- [Uploading game and/or save from PC](#uploading-game-andor-save-from-pc)
+    - [Uploading game and/or save from PC](#uploading-game-andor-save-from-pc)
-- [Downloading save to PC](#downloading-save-to-pc)
+    - [Downloading save to PC](#downloading-save-to-pc)
-- [Running 64DD games from PC](#running-64dd-games-from-pc)
+    - [Running 64DD games from PC](#running-64dd-games-from-pc)
-- [Direct boot option](#direct-boot-option)
+    - [Direct boot option](#direct-boot-option)
-- [Debug terminal on PC](#debug-terminal-on-pc)
+    - [Debug terminal on PC](#debug-terminal-on-pc)
+    - [Firmware backup/update](#firmware-backupupdate)
 - [LED blink patters](#led-blink-patters)
 
 ---
 
-## First time setup on PC
+# First time setup
 
-**Windows platform: replace `./sc64deployer` in examples below with `sc64deployer.exe`**
+## Standalone mode (Running menu and games on the N64)
-
-1. Download the latest deployer tool (`sc64-deployer-{os}-{version}.{ext}`) and firmware (`sc64-firmware-{version}.bin`) from GitHub releases page
-2. Extract deployer tool package contents to a folder and place firmware file inside it
-3. Connect SC64 device to your computer with USB type C cable
-4. Run `./sc64deployer list` to check if device is detected in the system
-5. Update SC64 firmware to the latest version with `./sc64deployer firmware update sc64-firmware-{version}.bin`
-6. Run `./sc64deployer info` to check if update process finished successfully and SC64 is detected correctly
-
----
-
-## Firmware backup/update
-
-Keeping SC64 firmware up to date is highly recommended.
-`sc64deployer` application is tightly coupled with specific firmware versions and will error out when it detects unsupported firmware version.
-
-To download and backup current version of the SC64 firmware run `./sc64deployer firmware backup sc64-firmware-backup.bin`
-
-To update SC64 firmware run `./sc64deployer firmware update sc64-firmware-{version}.bin`
-
-To print firmware metadata run `./sc64deployer firmware info sc64-firmware-{version}.bin`
-
----
-
-## Running menu in standalone mode
 
 Menu, as known from 64drive or EverDrive-64, is developed in another repository: [N64FlashcartMenu](https://github.com/Polprzewodnikowy/N64FlashcartMenu).
 Download latest version from [here](https://github.com/Polprzewodnikowy/N64FlashcartMenu/releases) and put `sc64menu.n64` file in the root directory of the SD card.
+Additionally, follow the instructions in the N64FlashcartMenu repository for more information about thr SD card setup and extra functionality.
 When N64 is powered on menu is automatically loaded from the SD card. Supported file system formats are FAT32 and exFAT.
 
 ---
 
-## Uploading game and/or save from PC
+## Developer mode (Uploading ROMs from the PC, and more)
+
+**Windows platform: replace `./sc64deployer` in examples below with `sc64deployer.exe`**
+
+1. Download the latest deployer tool (`sc64-deployer-{os}-{version}.{ext}`) from the GitHub releases page
+2. Extract deployer tool package contents to a folder
+3. Connect SC64 device to your computer with USB type C cable
+4. Run `./sc64deployer list` to check if device is detected in the system
+5. Follow instructions below for specific use cases
+
+### Uploading game and/or save from PC
 
 `./sc64deployer upload path_to_rom.n64 --save-type eeprom4k --save path_to_save.sav`
 
@@ -53,18 +41,14 @@ Application will try to autodetect used save type so explicitly setting save typ
 Check included help in the application to list available save types.
 Arguments `--save-type` and/or `--save` can be omitted if game doesn't require any save or you want to start with fresh save file.
 
----
+### Downloading save to PC
-
-## Downloading save to PC
 
 `./sc64deployer download save path_to_save.sav`
 
 Replace `path_to_save.sav` with appropriate value.
 Command will raise error when no save type is currently enabled in the SC64 device.
 
----
+### Running 64DD games from PC
-
-## Running 64DD games from PC
 
 64DD games require DDIPL ROM and disk images.
 To run disk game type `./sc64deployer 64dd path_to_ddipl.n64 path_to_disk_1.ndd path_to_disk_2.ndd`.
@@ -79,31 +63,38 @@ Make sure retail and development disks formats aren't mixed together.
 If disk game supports running in conjunction with cartridge game then `--rom path_to_rom.n64` argument can be added to command above.
 N64 will boot cartridge game instead of 64DD IPL.
 
----
+### Direct boot option
-
-## Direct boot option
 
 If booting game through included bootloader isn't a desired option then flashcart can be put in special mode that omits this step.
 Pass `--direct` option in `upload` or `64dd` command to disable bootloader during boot and console reset.
 This option is useful only for very specific cases (e.g. testing custom IPL3 or running SC64 on top of GameShark).
 TV type cannot be forced when direct boot mode is enabled.
 
----
+### Debug terminal on PC
-
-## Debug terminal on PC
 
 `sc64deployer` application supports UNFLoader protocol and has same functionality implemented as aforementioned program.
 Type `./sc64deployer debug` to activate it.
 
+### Firmware backup/update
+
+Keeping SC64 firmware up to date is highly recommended.
+`sc64deployer` application is tightly coupled with specific firmware versions and will error out when it detects unsupported firmware version.
+
+To download and backup current version of the SC64 firmware run `./sc64deployer firmware backup sc64-firmware-backup.bin`
+
+To update SC64 firmware run `./sc64deployer firmware update sc64-firmware-{version}.bin`
+
+To print firmware metadata run `./sc64deployer firmware info sc64-firmware-{version}.bin`
+
 ---
 
-## LED blink patters
+# LED blink patters
 
 LED on SC64 board can blink in certain situations. Most of them during normal use are related to SD card access. Here's list of blink patterns:
 
 | Pattern                              | Meaning                                                                                                      |
 | ------------------------------------ | ------------------------------------------------------------------------------------------------------------ |
-| Nx [Short ON - Short OFF]            | SD card access is in progress (initialization or data read/write) or save writeback is in progress           |
+| Irregular                            | SD card access is in progress (initialization or data read/write) or save writeback was finished             |
 | Nx [Medium ON - Long OFF]            | CIC region did not match, please power off console and power on again                                        |
 | 2x [Very short ON - Short OFF]       | Pattern used during firmware update process, it means that specific part of firmware has started programming |
 | 10x [Very short ON - Very short OFF] | Firmware has been successfully updated                                                                       |
@@ -112,4 +103,4 @@ LED on SC64 board can blink in certain situations. Most of them during normal us
 Nx means that blink count is varied.
 
 LED blinking on SD card access can be disabled through `sc64deployer` application.
-Please refer to included help for option to change the LED behavior.
+Please refer to the included help for option to change the LED behavior.

docs/03_usb_interface.md

@@ -45,6 +45,22 @@
     - [`data` (data)](#data-data-1)
   - [`X`: **AUX\_WRITE**](#x-aux_write)
     - [`arg0` (data)](#arg0-data)
+  - [`i`: **SD\_CARD\_OP**](#i-sd_card_op)
+    - [`arg0` (address)](#arg0-address-2)
+    - [`arg1` (operation)](#arg1-operation)
+    - [`response` (result/status)](#response-resultstatus)
+    - [Available SD card operations](#available-sd-card-operations)
+    - [SD card status](#sd-card-status)
+  - [`s`: **SD\_READ**](#s-sd_read)
+    - [`arg0` (address)](#arg0-address-3)
+    - [`arg1` (sector\_count)](#arg1-sector_count)
+    - [`data` (sector)](#data-sector)
+    - [`response` (result)](#response-result)
+  - [`S`: **SD\_WRITE**](#s-sd_write)
+    - [`arg0` (address)](#arg0-address-4)
+    - [`arg1` (sector\_count)](#arg1-sector_count-1)
+    - [`data` (sector)](#data-sector-1)
+    - [`response` (result)](#response-result-1)
   - [`D`: **DD\_SET\_BLOCK\_READY**](#d-dd_set_block_ready)
     - [`arg0` (error)](#arg0-error)
   - [`W`: **WRITEBACK\_ENABLE**](#w-writeback_enable)
@@ -168,9 +184,9 @@ Available packet IDs are listed in the [asynchronous packets](#asynchronous-pack
 | `M` | [**MEMORY_WRITE**](#m-memory_write)             | address      | length        | data   | ---              | Write data to specified memory address                         |
 | `U` | [**USB_WRITE**](#u-usb_write)                   | type         | length        | data   | N/A              | Send data to be received by app running on N64 (no response!)  |
 | `X` | [**AUX_WRITE**](#x-aux_write)                   | data         | ---           | ---    | ---              | Send small auxiliary data to be received by app running on N64 |
-| `i` | **SD_CARD_OP**                                  | address      | operation     | ---    | result/status    | Perform special operation on the SD card                       |
+| `i` | [**SD_CARD_OP**](#i-sd_card_op)                 | address      | operation     | ---    | result/status    | Perform special operation on the SD card                       |
-| `s` | **SD_READ**                                     | address      | sector_count  | sector | result           | Read sectors from the SD card to flashcart memory space        |
+| `s` | [**SD_READ**](#s-sd_read)                       | address      | sector_count  | sector | result           | Read sectors from the SD card to flashcart memory space        |
-| `S` | **SD_WRITE**                                    | address      | sector_count  | sector | result           | Write sectors from the flashcart memory space to the SD card   |
+| `S` | [**SD_WRITE**](#s-sd_write)                     | address      | sector_count  | sector | result           | Write sectors from the flashcart memory space to the SD card   |
 | `D` | [**DD_SET_BLOCK_READY**](#d-dd_set_block_ready) | error        | ---           | ---    | ---              | Notify flashcart about 64DD block readiness                    |
 | `W` | [**WRITEBACK_ENABLE**](#w-writeback_enable)     | ---          | ---           | ---    | ---              | Enable save writeback through USB packet                       |
 | `p` | **FLASH_WAIT_BUSY**                             | wait         | ---           | ---    | erase_block_size | Wait until flash ready / Get flash block erase size            |
@@ -226,7 +242,7 @@ _This command does not require arguments or data._
 _This command does not send response data._
 
 This command is used to reset most of the config options to default state (same as on power-up).
-Additionally, CIC emulation is enabled and 6102/7101 seed/checksum values are set.
+Additionally, CIC emulation is enabled, 6102/7101 seed/checksum values are set and SD card lock is released.
 
 ---
 
@@ -470,6 +486,110 @@ This command puts 32 bits of data to the AUX register accessible from the N64 si
 
 ---
 
+### `i`: **SD_CARD_OP**
+
+**Perform special operation on the SD card**
+
+#### `arg0` (address)
+| bits     | description |
+| -------- | ----------- |
+| `[31:0]` | Address     |
+
+#### `arg1` (operation)
+| bits     | description |
+| -------- | ----------- |
+| `[31:0]` | Operation   |
+
+#### `response` (result/status)
+| offset | type     | description                                                                                    |
+| ------ | -------- | ---------------------------------------------------------------------------------------------- |
+| `0`    | uint32_t | Operation result (valid values are listed in the [sd_error_t](../sw/controller/src/sd.h) enum) |
+| `4`    | uint32_t | SD card status (always returned regardless of the SD card operation result)                    |
+
+This command performs special operation on the SD card. When operation result is not `SD_OK`, then `ERR` packet is returned.
+PC and N64 cannot use the SD card interface at the same time. Lock mechanism is implemented to prevent data corruption.
+SD card access is locked when PC or N64 requests SD card initialization, and unlocked when the card is uninitialized.
+Lock is also released when certain conditions occur - when N64 side lock is active then it is released when the console is powered off
+and save writeback operation is not pending. PC side lock is released when USB interface is in reset state, or the USB cable is unplugged.
+
+#### Available SD card operations
+| operation | description                                                                                    |
+| --------- | ---------------------------------------------------------------------------------------------- |
+| `0`       | Init SD card                                                                                   |
+| `1`       | Deinit SD card                                                                                 |
+| `2`       | Get SD card status                                                                             |
+| `3`       | Get SD card info (loads CSD and CID registers to a specified address, data length is 32 bytes) |
+| `4`       | Turn on byte swap                                                                              |
+| `5`       | Turn off byte swap                                                                             |
+
+#### SD card status
+| bits     | description                                                                |
+| -------- | -------------------------------------------------------------------------- |
+| `[31:5]` | _Unused_                                                                   |
+| `[4]`    | `0` - Byte swap disabled, `1` - Byte swap enabled (valid when initialized) |
+| `[3]`    | `0` - 25 MHz clock, `1` - 50 MHz clock (valid when initialized)            |
+| `[2]`    | `0` - Byte addressed, `1` - Sector addressed (valid when initialized)      |
+| `[1]`    | `0` - SD card not initialized, `1` - SD card initialized                   |
+| `[0]`    | `0` - SD card not inserted, `1` - SD card inserted                         |
+
+---
+
+### `s`: **SD_READ**
+
+**Read sectors from the SD card to flashcart memory space**
+
+#### `arg0` (address)
+| bits     | description |
+| -------- | ----------- |
+| `[31:0]` | Address     |
+
+#### `arg1` (sector_count)
+| bits     | description  |
+| -------- | ------------ |
+| `[31:0]` | Sector count |
+
+#### `data` (sector)
+| offset | type     | description     |
+| ------ | -------- | --------------- |
+| `0`    | uint32_t | Starting sector |
+
+#### `response` (result)
+| offset | type     | description                                                                                    |
+| ------ | -------- | ---------------------------------------------------------------------------------------------- |
+| `0`    | uint32_t | Operation result (valid values are listed in the [sd_error_t](../sw/controller/src/sd.h) enum) |
+
+This command reads sectors from the SD card to a specified memory address. When operation result is not `SD_OK`, then `ERR` packet is returned.
+
+---
+
+### `S`: **SD_WRITE**
+
+**Write sectors from the flashcart memory space to the SD card**
+
+#### `arg0` (address)
+| bits     | description |
+| -------- | ----------- |
+| `[31:0]` | Address     |
+
+#### `arg1` (sector_count)
+| bits     | description  |
+| -------- | ------------ |
+| `[31:0]` | Sector count |
+
+#### `data` (sector)
+| offset | type     | description     |
+| ------ | -------- | --------------- |
+| `0`    | uint32_t | Starting sector |
+
+#### `response` (result)
+| offset | type     | description                                                                                    |
+| ------ | -------- | ---------------------------------------------------------------------------------------------- |
+| `0`    | uint32_t | Operation result (valid values are listed in the [sd_error_t](../sw/controller/src/sd.h) enum) |
+
+This command writes sectors from a specified memory address to the SD card. When operation result is not `SD_OK`, then `ERR` packet is returned.
+
+---
+
 ### `D`: **DD_SET_BLOCK_READY**
 
 **Notify flashcart about 64DD block readiness**