The-Homebrew-Cloud/SummerCart64
2
0
Fork 0
mirror of https://github.com/Polprzewodnikowy/SummerCart64.git synced 2024-11-21 21:49:15 +01:00
Code Issues Packages Projects Releases Wiki Activity

[SC64][DOCS] Updated documentation

Browse Source
This commit is contained in:
Mateusz Faderewski 2023-08-30 18:14:24 +02:00
parent 129bb4b800
commit a28e118cba
4 changed files with 149 additions and 55 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
README.md
View File

@ -1,5 +1,5 @@
# <p style="text-align: center;">SummerCart64 - a fully open source Nintendo 64 flashcart</p> # SummerCart64 - a fully open source Nintendo 64 flashcart
[<p style="text-align: center;"><img src="assets/sc64_logo.svg" /></p>](assets/sc64_logo.svg) [<img src="assets/sc64_logo.svg" />](assets/sc64_logo.svg)
## Features ## Features
- 64 MiB SDRAM memory for game and save data - 64 MiB SDRAM memory for game and save data

11
docs/01_memory_map.md
View File

@ -18,15 +18,16 @@ This mapping is used internally by FPGA/μC and when accessing flashcart from US
| section | base | size | access | device | | section | base | size | access | device |
| ------------------- | ------------- | ---------------- | ------ | -------- | | ------------------- | ------------- | ---------------- | ------ | -------- |
| SDRAM | `0x0000_0000` | 64 MiB | RW | SDRAM | | SDRAM | `0x0000_0000` | 64 MiB | RW | SDRAM |
| Flash | `0x0400_0000` | 16 MiB | RW | Flash | | Flash [1] | `0x0400_0000` | 16 MiB | RW/R | Flash |
| Data buffer | `0x0500_0000` | 8 kiB | RW | BlockRAM | | Data buffer | `0x0500_0000` | 8 kiB | RW | BlockRAM |
| EEPROM | `0x0500_2000` | 2 kiB | RW | BlockRAM | | EEPROM | `0x0500_2000` | 2 kiB | RW | BlockRAM |
| 64DD buffer | `0x0500_2800` | 256 bytes | RW | BlockRAM | | 64DD buffer | `0x0500_2800` | 256 bytes | RW | BlockRAM |
| FlashRAM buffer [1] | `0x0500_2900` | 128 bytes | R | BlockRAM | | FlashRAM buffer [2] | `0x0500_2900` | 128 bytes | R | BlockRAM |
| N/A [2] | `0x0500_2980` | to `0x07FF_FFFF` | R | N/A | | N/A [3] | `0x0500_2980` | to `0x07FF_FFFF` | R | N/A |
- Note [1]: Due to BlockRAM usage optimization this section is read only. - Note [1]: Flash memory region `0x04E0_0000` - `0x04FD_FFFF` is write protected as it contains N64 bootloader. This section can be overwritten only via firmware update process.
- Note [2]: Read returns `0`. Maximum accessibe address space is 128 MiB. - Note [2]: Due to BlockRAM usage optimization this section is read only.
- Note [3]: Read returns `0`. Maximum accessibe address space is 128 MiB.
--- ---

185
docs/03_usb_interface.md
View File

@ -14,6 +14,18 @@
- [`B`: **CIC\_PARAMS\_SET**](#b-cic_params_set) - [`B`: **CIC\_PARAMS\_SET**](#b-cic_params_set)
- [`arg0` (cic\_params\_0)](#arg0-cic_params_0) - [`arg0` (cic\_params\_0)](#arg0-cic_params_0)
- [`arg1` (cic\_params\_1)](#arg1-cic_params_1) - [`arg1` (cic\_params\_1)](#arg1-cic_params_1)
- [`c`: **CONFIG\_GET**](#c-config_get)
- [`arg0` (config\_id)](#arg0-config_id)
- [`response` (config\_value)](#response-config_value)
- [`C`: **CONFIG\_SET**](#c-config_set)
- [`arg0` (config\_id)](#arg0-config_id-1)
- [`arg1` (config\_value)](#arg1-config_value)
- [`a`: **SETTING\_GET**](#a-setting_get)
- [`arg0` (setting\_id)](#arg0-setting_id)
- [`response` (setting\_value)](#response-setting_value)
- [`A`: **SETTING\_SET**](#a-setting_set)
- [`arg0` (setting\_id)](#arg0-setting_id-1)
- [`arg1` (setting\_value)](#arg1-setting_value)
- [`t`: **TIME\_GET**](#t-time_get) - [`t`: **TIME\_GET**](#t-time_get)
- [`response` (time)](#response-time) - [`response` (time)](#response-time)
- [`T`: **TIME\_SET**](#t-time_set) - [`T`: **TIME\_SET**](#t-time_set)
@ -25,7 +37,7 @@
## Protocol ## Protocol
SC64 exposes itself in the system as simple serial device. This allows it to work without manually installed drivers. SC64 exposes itself in the system as a simple serial device. This allows it to work without manually installed drivers.
Serial communication is also well supported in almost all programming languages making it easy to work with. Serial communication is also well supported in almost all programming languages making it easy to work with.
USB protocol use simple packet based communication. Every packet starts with 3 byte identifier and 1 byte data ID. USB protocol use simple packet based communication. Every packet starts with 3 byte identifier and 1 byte data ID.
Every argument/data is sent as big-endian value. Every argument/data is sent as big-endian value.
@ -47,7 +59,7 @@ Flashcart should be ready to accept new commands.
| `CMD` | Send command to the SC64 | | `CMD` | Send command to the SC64 |
SC64 understands only one packet identifier - `CMD`. SC64 understands only one packet identifier - `CMD`.
Fourth byte denotes command type listed in [supported commands](#supported-commands) section. Fourth byte denotes command ID listed in [supported commands](#supported-commands) section.
#### **`CMD`** packet #### **`CMD`** packet
@ -61,22 +73,22 @@ General structure of packet:
| `12` | uint8_t[data_length] | Command data (if required) | | `12` | uint8_t[data_length] | Command data (if required) |
`CMD` packet always require arguments to be sent even if command does not require them. `CMD` packet always require arguments to be sent even if command does not require them.
Arbitrary data length is derived from the argument if specific command supports it. Packet data length is derived from the argument if specific command supports it.
### SC64 -> PC packets ### SC64 -> PC packets
| identifier | description | | identifier | description |
| ---------- | ------------------------------------ | | ---------- | ---------------------------------------- |
| `RSP` | Success response to the sent command | | `RSP` | Success response to the received command |
| `ERR` | Error response to the sent command | | `ERR` | Error response to the received command |
| `PKT` | Asynchronous data packet | | `PKT` | Asynchronous data packet |
SC64 sends response packet `RSP`/`ERR` to almost every command sent from the PC. SC64 sends response packet `RSP`/`ERR` to almost every command received from the PC.
Fourth byte is the same as in the command that triggered the response. Fourth byte is the same as in the command that triggered the response.
If command execution was not successful, then `RSP` identifier is replaced by the `ERR` identifier. If command execution was not successful, then `RSP` identifier is replaced by the `ERR` identifier.
SC64 can also send `PKT` packet at any time as a response to action triggered by the N64 or the flashcart itself. SC64 can also send `PKT` packet at any time as a response to action triggered by the N64 or the flashcart itself.
Fourth byte denotes packet type listed in the [asynchronous packets](#asynchronous-packets) section. Fourth byte denotes packet ID listed in the [asynchronous packets](#asynchronous-packets) section.
#### **`RSP`/`ERR`** packets #### **`RSP`/`ERR`** packets
@ -94,48 +106,48 @@ General structure of packet:
#### **`PKT`** packet #### **`PKT`** packet
General structure of packet: General structure of packet:
| offset | type | description | | offset | type | description |
| ------ | -------------------- | ---------------------- | | ------ | -------------------- | -------------------- |
| `0` | char[3] | `PKT` identifier | | `0` | char[3] | `PKT` identifier |
| `3` | char[1] | Asynchronous packet ID | | `3` | char[1] | Packet ID |
| `4` | uint32_t | Data length | | `4` | uint32_t | Data length |
| `8` | uint8_t[data_length] | Packet data (if any) | | `8` | uint8_t[data_length] | Packet data (if any) |
Available packet types are listed in the [asynchronous packets](#asynchronous-packets) section. Available packet IDs are listed in the [asynchronous packets](#asynchronous-packets) section.
--- ---
## Supported commands ## Supported commands
| id | name | arg0 | arg1 | data | response | description | | id | name | arg0 | arg1 | data | response | description |
| --- | --------------------------------------- | ------------ | ------------ | ---- | ---------------- | ------------------------------------------------------------- | | --- | --------------------------------------- | ------------ | ------------- | ---- | ---------------- | ------------------------------------------------------------- |
| `v` | [**IDENTIFIER_GET**](#v-identifier_get) | --- | --- | --- | identifier | Get flashcart identifier `SCv2` | | `v` | [**IDENTIFIER_GET**](#v-identifier_get) | --- | --- | --- | identifier | Get flashcart identifier `SCv2` |
| `V` | [**VERSION_GET**](#v-version_get) | --- | --- | --- | version | Get flashcart firmware version | | `V` | [**VERSION_GET**](#v-version_get) | --- | --- | --- | version | Get flashcart firmware version |
| `R` | [**STATE_RESET**](#r-state_reset) | --- | --- | --- | --- | Reset flashcart state (CIC params and config options) | | `R` | [**STATE_RESET**](#r-state_reset) | --- | --- | --- | --- | Reset flashcart state (CIC params and config options) |
| `B` | [**CIC_PARAMS_SET**](#b-cic_params_set) | cic_params_0 | cic_params_1 | --- | --- | Set CIC emulation parameters (disable/seed/checksum) | | `B` | [**CIC_PARAMS_SET**](#b-cic_params_set) | cic_params_0 | cic_params_1 | --- | --- | Set CIC emulation parameters (disable/seed/checksum) |
| `c` | **CONFIG_GET** | config_id | --- | --- | current_value | Get config option | | `c` | [**CONFIG_GET**](#c-config_get) | config_id | --- | --- | config_value | Get config option |
| `C` | **CONFIG_SET** | config_id | new_value | --- | --- | Set config option | | `C` | [**CONFIG_SET**](#c-config_set) | config_id | config_value | --- | --- | Set config option |
| `a` | **SETTING_GET** | setting_id | --- | --- | current_value | Get persistent setting option | | `a` | [**SETTING_GET**](#a-setting_get) | setting_id | --- | --- | setting_value | Get persistent setting option |
| `A` | **SETTING_SET** | setting_id | new_value | --- | --- | Set persistent setting option | | `A` | [**SETTING_SET**](#a-setting_set) | setting_id | setting_value | --- | --- | Set persistent setting option |
| `t` | [**TIME_GET**](#t-time_get) | --- | --- | --- | time | Get current RTC value | | `t` | [**TIME_GET**](#t-time_get) | --- | --- | --- | time | Get current RTC value |
| `T` | [**TIME_SET**](#t-time_set) | time_0 | time_1 | --- | --- | Set new RTC value | | `T` | [**TIME_SET**](#t-time_set) | time_0 | time_1 | --- | --- | Set new RTC value |
| `m` | **MEMORY_READ** | address | length | --- | data | Read data from specified memory address | | `m` | **MEMORY_READ** | address | length | --- | data | Read data from specified memory address |
| `M` | **MEMORY_WRITE** | address | length | data | --- | Write data to specified memory address | | `M` | **MEMORY_WRITE** | address | length | data | --- | Write data to specified memory address |
| `U` | **USB_WRITE** | type | length | data | N/A | Send data to be received by app running on N64 (no response!) | | `U` | **USB_WRITE** | type | length | data | N/A | Send data to be received by app running on N64 (no response!) |
| `D` | **DD_SET_BLOCK_READY** | success | --- | --- | --- | Notify flashcart about 64DD block readiness | | `D` | **DD_SET_BLOCK_READY** | success | --- | --- | --- | Notify flashcart about 64DD block readiness |
| `W` | **WRITEBACK_ENABLE** | --- | --- | --- | --- | Enable save writeback through USB packet | | `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 | | `p` | **FLASH_WAIT_BUSY** | wait | --- | --- | erase_block_size | Wait until flash ready / Get flash block erase size |
| `P` | **FLASH_ERASE_BLOCK** | address | --- | --- | --- | Start flash block erase | | `P` | **FLASH_ERASE_BLOCK** | address | --- | --- | --- | Start flash block erase |
| `f` | **FIRMWARE_BACKUP** | address | --- | --- | status/length | Backup firmware to specified memory address | | `f` | **FIRMWARE_BACKUP** | address | --- | --- | status/length | Backup firmware to specified memory address |
| `F` | **FIRMWARE_UPDATE** | address | length | --- | status | Update firmware from specified memory address | | `F` | **FIRMWARE_UPDATE** | address | length | --- | status | Update firmware from specified memory address |
| `?` | **DEBUG_GET** | --- | --- | --- | debug_data | Get internal FPGA debug info | | `?` | **DEBUG_GET** | --- | --- | --- | debug_data | Get internal FPGA debug info |
| `%` | **STACK_USAGE_GET** | --- | --- | --- | stack_usage | Get per task stack usage | | `%` | **STACK_USAGE_GET** | --- | --- | --- | stack_usage | Get per task stack usage |
--- ---
### `v`: **IDENTIFIER_GET** ### `v`: **IDENTIFIER_GET**
Get flashcart identifier `SCv2` **Get flashcart identifier `SCv2`**
_This command does not require arguments or data._ _This command does not require arguments or data._
@ -150,7 +162,7 @@ Identifier is always `SCv2` represented in ASCII code.
### `V`: **VERSION_GET** ### `V`: **VERSION_GET**
Get flashcart firmware version **Get flashcart firmware version**
_This command does not require arguments or data._ _This command does not require arguments or data._
@ -170,17 +182,20 @@ Increment in revision field represents no API changes, usually it's denoting bug
--- ---
### `R`: **STATE_RESET** ### `R`: **STATE_RESET**
Reset flashcart state (CIC params and config options) **Reset flashcart state (CIC params and config options)**
_This command does not require arguments or data._ _This command does not require arguments or data._
_This command does not send response 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.
--- ---
### `B`: **CIC_PARAMS_SET** ### `B`: **CIC_PARAMS_SET**
Set CIC emulation parameters (disable/seed/checksum) **Set CIC emulation parameters (disable/seed/checksum)**
#### `arg0` (cic_params_0) #### `arg0` (cic_params_0)
| bits | description | | bits | description |
@ -197,11 +212,85 @@ Set CIC emulation parameters (disable/seed/checksum)
_This command does not send response data._ _This command does not send response data._
Use this command to set custom seed/checksum CIC values. Very useful for testing custom IPL3 replacements.
---
### `c`: **CONFIG_GET**
**Get config option**
#### `arg0` (config_id)
| bits | description |
| -------- | ----------- |
| `[31:0]` | Config ID |
#### `response` (config_value)
| offset | type | description |
| ------ | -------- | ------------ |
| `0` | uint32_t | Config value |
Use this command to get value of config option. Available config options are listed [here](./04_config_options.md).
---
### `C`: **CONFIG_SET**
**Set config option**
#### `arg0` (config_id)
| bits | description |
| -------- | ----------- |
| `[31:0]` | Config ID |
#### `arg1` (config_value)
| bits | description |
| -------- | ------------ |
| `[31:0]` | Config value |
Use this command to set value of config option. Available config options are listed [here](./04_config_options.md).
---
### `a`: **SETTING_GET**
**Get persistent setting option**
#### `arg0` (setting_id)
| bits | description |
| -------- | ----------- |
| `[31:0]` | Setting ID |
#### `response` (setting_value)
| offset | type | description |
| ------ | -------- | ------------- |
| `0` | uint32_t | Setting value |
Use this command to get value of persistent setting option. Available persistent setting options are listed [here](./04_config_options.md).
---
### `A`: **SETTING_SET**
**Set persistent setting option**
#### `arg0` (setting_id)
| bits | description |
| -------- | ----------- |
| `[31:0]` | Setting ID |
#### `arg1` (setting_value)
| bits | description |
| -------- | ------------- |
| `[31:0]` | Setting value |
Use this command to set value of persistent setting option. Available persistent setting options are listed [here](./04_config_options.md).
--- ---
### `t`: **TIME_GET** ### `t`: **TIME_GET**
Date/time values use the [BCD](https://en.wikipedia.org/wiki/Binary-coded_decimal) format. **Get current RTC value**
_This command does not require arguments or data._ _This command does not require arguments or data._
@ -217,11 +306,13 @@ _This command does not require arguments or data._
| `6` | uint8_t | Month (1 - 12) | | `6` | uint8_t | Month (1 - 12) |
| `7` | uint8_t | Day (1 - 31) | | `7` | uint8_t | Day (1 - 31) |
Date/time values use the [BCD](https://en.wikipedia.org/wiki/Binary-coded_decimal) format.
--- ---
### `T`: **TIME_SET** ### `T`: **TIME_SET**
Date/time values use the [BCD](https://en.wikipedia.org/wiki/Binary-coded_decimal) format. **Set new RTC value**
#### `arg0` (time_0) #### `arg0` (time_0)
| bits | description | | bits | description |
@ -241,6 +332,8 @@ Date/time values use the [BCD](https://en.wikipedia.org/wiki/Binary-coded_decima
_This command does not send response data._ _This command does not send response data._
Date/time values use the [BCD](https://en.wikipedia.org/wiki/Binary-coded_decimal) format.
## Asynchronous packets ## Asynchronous packets
| id | name | data | description | | id | name | data | description |

4
docs/README.md
View File

@ -1,5 +1,5 @@
# <p style="text-align: center;">SummerCart64 - a fully open source Nintendo 64 flashcart</p> # SummerCart64 - a fully open source Nintendo 64 flashcart
[<p style="text-align: center;"><img src="../assets/sc64_logo.svg" /></p>](../assets/sc64_logo.svg) [<img src="../assets/sc64_logo.svg" />](../assets/sc64_logo.svg)
## Documentation ## Documentation