Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[SC64][SW] Added access to the SD card via USB interface #90

Merged
merged 12 commits into from
Sep 29, 2024
Merged

[SC64][SW] Added access to the SD card via USB interface #90

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
12 commits
Select commit Hold shift + click to select a range
bf721ac
[SC64][SW] Added access to the SD card via USB interface
Polprzewodnikowy Sep 26, 2024
eef6198
Added format option + small cleanup
Polprzewodnikowy Sep 27, 2024
3c9f42d
documentation update
Polprzewodnikowy Sep 27, 2024
2f79863
bold names
Polprzewodnikowy Sep 27, 2024
4ab7533
documentation update
Polprzewodnikowy Sep 28, 2024
8ba2f95
documentation update
Polprzewodnikowy Sep 28, 2024
6dbd773
warn when console is on
Polprzewodnikowy Sep 28, 2024
5850ebd
documentation update
Polprzewodnikowy Sep 28, 2024
5aa250f
fix no color on old windows cmd
Polprzewodnikowy Sep 28, 2024
b54fcad
bram extension
Polprzewodnikowy Sep 29, 2024
3b54b6f
little cleanup
Polprzewodnikowy Sep 29, 2024
802e882
little cleanup
Polprzewodnikowy Sep 29, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)
- Access to the SD card 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
Expand Down
91 changes: 41 additions & 50 deletions docs/00_quick_startup_guide.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,50 +1,38 @@
- [First time setup on PC](#first-time-setup-on-pc)
- [Firmware backup/update](#firmware-backupupdate)
- [Running menu in standalone mode](#running-menu-in-standalone-mode)
- [Uploading game and/or save from PC](#uploading-game-andor-save-from-pc)
- [Downloading save to PC](#downloading-save-to-pc)
- [Running 64DD games from PC](#running-64dd-games-from-pc)
- [Direct boot option](#direct-boot-option)
- [Debug terminal on PC](#debug-terminal-on-pc)
- [First time setup](#first-time-setup)
- [Standalone mode (Running menu and games on the N64)](#standalone-mode-running-menu-and-games-on-the-n64)
- [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)
- [Downloading save to PC](#downloading-save-to-pc)
- [Running 64DD games from PC](#running-64dd-games-from-pc)
- [Direct boot option](#direct-boot-option)
- [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`**

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
## Standalone mode (Running menu and games on the N64)

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`

Expand All @@ -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`.
Expand All @@ -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 strongly 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 |
Expand All @@ -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.
10 changes: 5 additions & 5 deletions docs/01_memory_map.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,9 +25,9 @@ This mapping is used internally by FPGA/μC and when accessing flashcart from US
| Flash [1] | `0x0400_0000` | 16 MiB | RW/R | Flash |
| Data buffer | `0x0500_0000` | 8 kiB | RW | BlockRAM |
| EEPROM | `0x0500_2000` | 2 kiB | RW | BlockRAM |
| 64DD buffer | `0x0500_2800` | 256 bytes | RW | BlockRAM |
| FlashRAM buffer [2] | `0x0500_2900` | 128 bytes | R | BlockRAM |
| N/A [3] | `0x0500_2980` | to `0x07FF_FFFF` | R | N/A |
| 64DD/MCU buffer | `0x0500_2800` | 1 kiB | RW | BlockRAM |
| FlashRAM buffer [2] | `0x0500_2C00` | 128 bytes | R | BlockRAM |
| N/A [3] | `0x0500_2C80` | to `0x07FF_FFFF` | R | N/A |

- 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]: Due to BlockRAM usage optimization this section is read only.
Expand All @@ -53,8 +53,8 @@ This mapping is used when accessing flashcart from N64 side.
| ROM shadow [7] | `0x1FFC_0000` | 128 kiB | R | `0x04FE_0000` | Flash | mem bus | SC64 register access is enabled |
| Data buffer | `0x1FFE_0000` | 8 kiB | RW | `0x0500_0000` | Block RAM | mem bus | SC64 register access is enabled |
| EEPROM | `0x1FFE_2000` | 2 kiB | RW | `0x0500_2000` | Block RAM | mem bus | SC64 register access is enabled |
| 64DD buffer [8] | `0x1FFE_2800` | 256 bytes | RW | `0x0500_2800` | Block RAM | mem bus | SC64 register access is enabled |
| FlashRAM buffer [8] | `0x1FFE_2900` | 128 bytes | R | `0x0500_2900` | Block RAM | mem bus | SC64 register access is enabled |
| 64DD/MCU buffer [8] | `0x1FFE_2800` | 1 kiB | RW | `0x0500_2800` | Block RAM | mem bus | SC64 register access is enabled |
| FlashRAM buffer [8] | `0x1FFE_2C00` | 128 bytes | R | `0x0500_2C00` | Block RAM | mem bus | SC64 register access is enabled |
| SC64 registers | `0x1FFF_0000` | 28 bytes | RW | N/A | Flashcart Interface | reg bus | SC64 register access is enabled |

- Note [1]: 64DD IPL share SDRAM memory space with ROM (last 4 MiB minus 128 kiB for saves). Write access is always disabled for this section.
Expand Down
50 changes: 25 additions & 25 deletions docs/02_n64_commands.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,28 +4,28 @@

## N64 commands

| id | name | arg0 | arg1 | rsp0 | rsp1 | description |
| --- | --------------------- | ------------- | ------------ | ---------------- | -------------- | ---------------------------------------------------------- |
| `v` | **IDENTIFIER_GET** | --- | --- | identifier | --- | Get flashcart identifier `SCv2` |
| `V` | **VERSION_GET** | --- | --- | major/minor | revision | Get flashcart firmware version |
| `c` | **CONFIG_GET** | config_id | --- | --- | current_value | Get config option |
| `C` | **CONFIG_SET** | config_id | new_value | --- | previous_value | Set config option and get previous value |
| `a` | **SETTING_GET** | setting_id | --- | --- | current_value | Get persistent setting option |
| `A` | **SETTING_SET** | setting_id | new_value | --- | --- | Set persistent setting option |
| `t` | **TIME_GET** | --- | --- | time_0 | time_1 | Get current RTC value |
| `T` | **TIME_SET** | time_0 | time_1 | --- | --- | Set new RTC value |
| `m` | **USB_READ** | pi_address | length | --- | --- | Receive data from USB to flashcart |
| `M` | **USB_WRITE** | pi_address | length/type | --- | --- | Send data from from flashcart to USB |
| `u` | **USB_READ_STATUS** | --- | --- | read_status/type | length | Get USB read status and type/length |
| `U` | **USB_WRITE_STATUS** | --- | --- | write_status | --- | Get USB write status |
| `i` | **SD_CARD_OP** | pi_address | operation | --- | return_data | Perform special operation on SD card |
| `I` | **SD_SECTOR_SET** | sector | --- | --- | --- | Set starting sector for next SD card R/W operation |
| `s` | **SD_READ** | pi_address | sector_count | --- | --- | Read sectors from SD card to flashcart |
| `S` | **SD_WRITE** | pi_address | sector_count | --- | --- | Write sectors from flashcart to SD card |
| `D` | **DISK_MAPPING_SET** | pi_address | table_size | --- | --- | Set 64DD disk mapping for SD mode |
| `w` | **WRITEBACK_PENDING** | --- | --- | pending_status | --- | Get save writeback status (is write queued to the SD card) |
| `W` | **WRITEBACK_SD_INFO** | pi_address | --- | --- | --- | Load writeback SD sector table and enable it |
| `K` | **FLASH_PROGRAM** | pi_address | length | --- | --- | Program flash with bytes loaded into data buffer |
| `p` | **FLASH_WAIT_BUSY** | wait | --- | erase_block_size | --- | Wait until flash ready / get block erase size |
| `P` | **FLASH_ERASE_BLOCK** | pi_address | --- | --- | --- | Start flash block erase |
| `%` | **DIAGNOSTIC_GET** | diagnostic_id | --- | --- | value | Get diagnostic data |
| id | name | arg0 | arg1 | rsp0 | rsp1 | description |
| --- | --------------------- | ------------- | ------------ | ---------------- | -------------- | ------------------------------------------------------------ |
| `v` | **IDENTIFIER_GET** | --- | --- | identifier | --- | Get flashcart identifier `SCv2` |
| `V` | **VERSION_GET** | --- | --- | major/minor | revision | Get flashcart firmware version |
| `c` | **CONFIG_GET** | config_id | --- | --- | current_value | Get config option |
| `C` | **CONFIG_SET** | config_id | new_value | --- | previous_value | Set config option and get previous value |
| `a` | **SETTING_GET** | setting_id | --- | --- | current_value | Get persistent setting option |
| `A` | **SETTING_SET** | setting_id | new_value | --- | --- | Set persistent setting option |
| `t` | **TIME_GET** | --- | --- | time_0 | time_1 | Get current RTC value |
| `T` | **TIME_SET** | time_0 | time_1 | --- | --- | Set new RTC value |
| `m` | **USB_READ** | pi_address | length | --- | --- | Receive data from USB to flashcart |
| `M` | **USB_WRITE** | pi_address | length/type | --- | --- | Send data from from flashcart to USB |
| `u` | **USB_READ_STATUS** | --- | --- | read_status/type | length | Get USB read status and type/length |
| `U` | **USB_WRITE_STATUS** | --- | --- | write_status | --- | Get USB write status |
| `i` | **SD_CARD_OP** | pi_address | operation | --- | return_data | Perform special operation on the SD card |
| `I` | **SD_SECTOR_SET** | sector | --- | --- | --- | Set starting sector for next SD card R/W operation |
| `s` | **SD_READ** | pi_address | sector_count | --- | --- | Read sectors from the SD card to flashcart memory space |
| `S` | **SD_WRITE** | pi_address | sector_count | --- | --- | Write sectors from the flashcart memory space to the SD card |
| `D` | **DISK_MAPPING_SET** | pi_address | table_size | --- | --- | Set 64DD disk mapping for SD mode |
| `w` | **WRITEBACK_PENDING** | --- | --- | pending_status | --- | Get save writeback status (is write queued to the SD card) |
| `W` | **WRITEBACK_SD_INFO** | pi_address | --- | --- | --- | Load writeback SD sector table and enable it |
| `K` | **FLASH_PROGRAM** | pi_address | length | --- | --- | Program flash with bytes loaded into data buffer |
| `p` | **FLASH_WAIT_BUSY** | wait | --- | erase_block_size | --- | Wait until flash ready / get block erase size |
| `P` | **FLASH_ERASE_BLOCK** | pi_address | --- | --- | --- | Start flash block erase |
| `%` | **DIAGNOSTIC_GET** | diagnostic_id | --- | --- | value | Get diagnostic data |
Loading