sc64.py is gone

build.sh

@@ -5,16 +5,15 @@ set -e
 PACKAGE_FILE_NAME="sc64-extra"
 
 TOP_FILES=(
-    "./sw/pc/primer.py"
+    "./fw/ftdi/ft232h_config.xml"
-    "./sw/pc/requirements.txt"
+    "./sw/tools/primer.py"
-    "./sw/pc/sc64.py"
+    "./sw/tools/requirements.txt"
-    "./sw/update/sc64-firmware.bin"
+    "./sw/tools/sc64-firmware.bin"
 )
 
 FILES=(
     "./assets/*"
     "./docs/*"
-    "./fw/ftdi/ft232h_config.xml"
     "./hw/pcb/sc64_hw_v2.0a_bom.html"
     "./hw/pcb/sc64v2.kicad_pcb"
     "./hw/pcb/sc64v2.kicad_pro"
@@ -84,7 +83,7 @@ build_update () {
     build_controller
     build_fpga
 
-    pushd sw/update > /dev/null
+    pushd sw/tools > /dev/null
     if [ "$FORCE_CLEAN" = true ]; then
         rm -f ./sc64-firmware.bin
     fi
@@ -117,7 +116,7 @@ build_release () {
     zip -j -r $PACKAGE ${TOP_FILES[@]}
     zip -r $PACKAGE ${FILES[@]}
 
-    cp sw/update/sc64-firmware.bin ./sc64-firmware${SC64_VERSION}.bin
+    cp sw/tools/sc64-firmware.bin ./sc64-firmware${SC64_VERSION}.bin
 
     BUILT_RELEASE=true
 }

docs/06_manufacturing_guidelines.md

@@ -11,7 +11,8 @@
 
 ## Step by step guide how to make SC64
 
-All necessary manufacturing files are packaged in every `sc64-extra-{version}.zip` file in GitHub releases. Please download latest release before proceeding with the instructions.
+All necessary manufacturing files are packaged in every `sc64-extra-{version}.zip` file in GitHub releases.
+Please download latest release before proceeding with the instructions.
 
 ---
 
@@ -45,13 +46,16 @@ All necessary manufacturing files are packaged in every `sc64-extra-{version}.zi
 
   1. Locate `.stl` files inside `hw/shell` folder
   2. Use these files in the slicer and 3D printer of your choice or order ready made prints from 3D printing company
-  3. Find matching screws, dimensions are the same as on retail N64 cartridges
+  3. Find matching screws, go to discussions tab for community recommendations
 
 ---
 
 ### **Putting it together**
 
-There are no special requirements for soldering components to board. All chips and connectors can be soldered with standard manual soldering iron, although hot air station is recommended. Interactive BOM has every component and its value highlighted on PCB drawings and it's strongly recommended to use during assembly process. You can skip this step if PCB assembly service was used in previous steps.
+There are no special requirements for soldering components to board.
+All chips and connectors can be soldered with standard manual soldering iron, although hot air station is recommended.
+Interactive BOM has every component and its value highlighted on PCB drawings and it's strongly recommended to use during assembly process.
+You can skip this step if PCB assembly service was used in previous steps.
 
 ---
 
@@ -59,17 +63,18 @@ There are no special requirements for soldering components to board. All chips a
 
 **Please read the following instructions carefully before proceeding with programming.**
 
-For initial programming you are going to need a PC and a USB to UART (serial) adapter (3.3V signaling is required). These steps assume you are using modern Windows OS (version 10 or higher).
+For initial programming you are going to need a PC and a USB to UART (serial) adapter (3.3V signaling is required).
+These steps assume you are using modern Windows OS (version 10 or higher).
 
 As for software here's list of required applications:
  - [FT_PROG](https://ftdichip.com/utilities/#ft_prog) - FTDI FT232H EEPROM programming software
- - [Python 3](https://www.python.org/downloads/) with `pip3` - necessary for initial programming script, `primer.py`
+ - [Python 3](https://www.python.org/downloads/) with `pip3` - necessary for initial programming script: `primer.py`
 
 Programming must be done in specific order for `primer.py` script to work correctly.
 
 First, program FT232H EEPROM:
  1. Connect SC64 board to the PC with USB-C cable
- 2. Locate FT232H EEPROM template in `fw/ftdi` folder
+ 2. Locate FT232H EEPROM template `ft232h_config.xml`
  3. Launch `FT_PROG` software
  4. Click on `Scan and parse` if no device has shown up
  5. Right click on SC64 device and choose `Apply Template -> From File`
@@ -78,18 +83,18 @@ First, program FT232H EEPROM:
 
 Your SC64 should be ready for next programming step.
 
-Second, program FPGA, microcontroller and Flash memory:
+Second, program FPGA, microcontroller and bootloader:
  1. Disconnect SC64 board from power (unplug USB-C cable)
  2. Connect serial adapter to `TX/RX/GND` pads marked on the PCB
  3. Connect serial adapter to the PC
  4. Check in device manager which port number `COMx` is assigned to serial adapter
  5. Connect SC64 board to the PC with USB-C cable (***IMPORTANT:*** connect it to the same computer as serial adapter)
  6. Locate `primer.py` script in root folder
- 7. Make sure these files are located in the same folder as `primer.py` script: `requirements.txt`, `sc64.py`, `sc64-firmware.bin`
+ 7. Make sure these files are located in the same folder as `primer.py` script: `requirements.txt`, `sc64-firmware.bin`
  8. Run `pip3 install -r requirements.txt` to install required python packages
  9. Run `python3 primer.py COMx sc64-firmware.bin` (replace `COMx` with port located in step **4**)
  10. Follow the instructions on the screen
- 11. Wait until programming process has finished (**DO NOT STOP PROGRAMMING PROCESS OR DISCONNECT SC64 BOARD FROM PC**, doing so might irrecoverably break programming through UART header and you would need to program microcontroller, FPGA and bootloader with separate dedicated programming interfaces through *Tag-Connect* connector on the PCB)
+ 11. Wait until programming process has finished (**DO NOT STOP PROGRAMMING PROCESS OR DISCONNECT SC64 BOARD FROM PC**, doing so might irrecoverably break programming through UART header and you would need to program FPGA and/or microcontroller with separate dedicated programming interfaces through *Tag-Connect* connector on the PCB)
 
 Congratulations! Your SC64 flashcart should be ready for use!
 
@@ -99,4 +104,7 @@ Congratulations! Your SC64 flashcart should be ready for use!
 
 *`primer.py` threw error on `Bootloader -> SC64 FLASH` step*
 
-This issue can be attributed to incorrectly programmed FT232H EEPROM in the first programming step. Check again in `FT_PROG` program if device was configured properly. Once FPGA and microcontroller has been programmed successfully `primer.py` script needs to be run in special mode. Please use command `python3 primer.py COMx sc64-firmware.bin --only-bootloader` to try programming bootloader again.
+This issue can be attributed to incorrectly programmed FT232H EEPROM in the first programming step.
+Check again in `FT_PROG` application if device was configured properly.
+Once FPGA and microcontroller has been programmed successfully `primer.py` script needs to be run in special mode.
+Please use command `python3 primer.py COMx sc64-firmware.bin --bootloader-only` to try programming bootloader again.

sw/controller/src/cfg.c

@@ -397,10 +397,8 @@ bool cfg_update_setting (uint32_t *args) {
     return false;
 }
 
-bool cfg_set_rom_write_enable (bool value) {
+void cfg_set_rom_write_enable (bool value) {
-    uint32_t scr = fpga_reg_get(REG_CFG_SCR);
     cfg_change_scr_bits(CFG_SCR_ROM_WRITE_ENABLED, value);
-    return (scr & CFG_SCR_ROM_WRITE_ENABLED);
 }
 
 save_type_t cfg_get_save_type (void) {

sw/controller/src/cfg.h

@@ -21,7 +21,7 @@ bool cfg_query (uint32_t *args);
 bool cfg_update (uint32_t *args);
 bool cfg_query_setting (uint32_t *args);
 bool cfg_update_setting (uint32_t *args);
-bool cfg_set_rom_write_enable (bool value);
+void cfg_set_rom_write_enable (bool value);
 save_type_t cfg_get_save_type (void);
 void cfg_get_time (uint32_t *args);
 void cfg_set_time (uint32_t *args);

sw/controller/src/usb.c

@@ -281,7 +281,9 @@ static void usb_rx_process (void) {
                 break;
 
             case 'U':
-                if ((p.read_length > 0) && usb_dma_ready()) {
+                if (p.rx_args[1] == 0) {
+                    p.rx_state = RX_STATE_IDLE;
+                } else if ((p.read_length > 0) && usb_dma_ready()) {
                     uint32_t length = (p.read_length > p.rx_args[1]) ? p.rx_args[1] : p.read_length;
                     if (!p.rx_dma_running) {
                         fpga_reg_set(REG_USB_DMA_ADDRESS, p.read_address);
@@ -295,9 +297,6 @@ static void usb_rx_process (void) {
                         p.read_length -= length;
                         p.read_address += length;
                         p.read_ready = true;
-                        if (p.rx_args[1] == 0) {
-                            p.rx_state = RX_STATE_IDLE;
-                        }
                     }
                 }
                 break;
@@ -328,19 +327,17 @@ static void usb_rx_process (void) {
                 p.response_pending = true;
                 break;
 
-            case 'f': {
+            case 'f':
-                bool rom_write_enable_restore = cfg_set_rom_write_enable(false);
+                cfg_set_rom_write_enable(false);
                 p.response_info.data[0] = update_backup(p.rx_args[0], &p.response_info.data[1]);
                 p.rx_state = RX_STATE_IDLE;
                 p.response_pending = true;
                 p.response_error = (p.response_info.data[0] != UPDATE_OK);
                 p.response_info.data_length = 8;
-                cfg_set_rom_write_enable(rom_write_enable_restore);
                 break;
-            }
 
-            case 'F': {
+            case 'F':
-                bool rom_write_enable_restore = cfg_set_rom_write_enable(false);
+                cfg_set_rom_write_enable(false);
                 p.response_info.data[0] = update_prepare(p.rx_args[0], p.rx_args[1]);
                 p.rx_state = RX_STATE_IDLE;
                 p.response_pending = true;
@@ -349,10 +346,8 @@ static void usb_rx_process (void) {
                     p.response_info.done_callback = update_start;
                 } else {
                     p.response_error = true;
-                    cfg_set_rom_write_enable(rom_write_enable_restore);
                 }
                 break;
-            }
 
             case '?':
                 p.rx_state = RX_STATE_IDLE;

sw/deployer/src/n64.rs

@@ -10,7 +10,7 @@ pub enum SaveType {
     Sram128kB,
 }
 
-const HASH_CHUNK_LENGTH: usize = 256 * 1024;
+const HASH_CHUNK_LENGTH: usize = 1 * 1024 * 1024;
 
 pub fn guess_save_type<T: Read + Seek>(
     reader: &mut T,

sw/pc/.gitignore

@@ -1,11 +0,0 @@
-/__pycache__
-/build
-/dist
-*.bin
-*.eep
-*.fla
-*.n64
-*.spec
-*.srm
-*.v64
-*.z64

sw/tools/primer.py

@@ -2,12 +2,14 @@
 
 import io
 import os
+import queue
 import serial
 import signal
 import sys
 import time
 from binascii import crc32
-from sc64 import SC64
+from enum import IntEnum
+from serial.tools import list_ports
 from sys import exit
 from typing import Callable, Optional
 
@@ -61,6 +63,7 @@ class SC64UpdateDataException(Exception):
 
 class SC64UpdateData:
     __UPDATE_TOKEN              = b'SC64 Update v2.0'
+
     __CHUNK_ID_UPDATE_INFO      = 1
     __CHUNK_ID_MCU_DATA         = 2
     __CHUNK_ID_FPGA_DATA        = 3
@@ -73,6 +76,14 @@ class SC64UpdateData:
     __bootloader_data: Optional[bytes]
     __primer_data: Optional[bytes]
 
+    def __int_to_bytes(self, value: int) -> bytes:
+        return value.to_bytes(4, byteorder='little')
+    
+    def __align(self, value: int) -> int:
+        if (value % 16 != 0):
+            value += (16 - (value % 16))
+        return value
+
     def __load_int(self, f: io.BufferedReader) -> int:
         try:
             data = f.read(4)
@@ -156,6 +167,24 @@ class SC64UpdateData:
     def get_primer_data(self) -> Optional[bytes]:
         return self.__primer_data
     
+    def create_bootloader_only_firmware(self):
+        if (self.__bootloader_data == None):
+            raise SC64UpdateDataException('No bootloader data available for firmware creation')
+
+        chunk = b''
+        chunk += self.__int_to_bytes(self.__CHUNK_ID_BOOTLOADER_DATA)
+        chunk += self.__int_to_bytes(8 + self.__align(len(self.__bootloader_data)))
+        chunk += self.__int_to_bytes(crc32(self.__bootloader_data))
+        chunk += self.__int_to_bytes(len(self.__bootloader_data))
+        chunk += self.__bootloader_data
+        chunk += bytes([0] * (self.__align(len(chunk)) - len(chunk)))
+
+        data = b''
+        data += self.__UPDATE_TOKEN
+        data += chunk
+
+        return data
+
 
 class STM32BootloaderException(Exception):
     pass
@@ -408,6 +437,138 @@ class LCMXO2Primer:
         self.__cmd_execute(self.__CMD_RESTART)
 
 
+class SC64Exception(Exception):
+    pass
+
+class SC64:
+    __serial: Optional[serial.Serial] = None
+    __packets = queue.Queue()
+
+    class __UpdateStatus(IntEnum):
+        MCU = 1
+        FPGA = 2
+        BOOTLOADER = 3
+        DONE = 0x80
+        ERROR = 0xFF
+
+    def __init__(self) -> None:
+        SC64_VID = 0x0403
+        SC64_PID = 0x6014
+        SC64_SID = "SC64"
+        for p in list_ports.comports():
+            if (p.vid == SC64_VID and p.pid == SC64_PID and p.serial_number.startswith(SC64_SID)):
+                try:
+                    self.__serial = serial.Serial(p.device, timeout=10.0, write_timeout=10.0)
+                except serial.SerialException:
+                    if (self.__serial):
+                        self.__serial.close()
+                    continue
+                return
+        raise SC64Exception('No SC64 USB device found')
+
+    def __reset(self) -> None:
+        WAIT_DURATION = 0.01
+        RETRY_COUNT = 100
+
+        self.__serial.dtr = 1
+        for n in range(0, RETRY_COUNT + 1):
+            self.__serial.reset_input_buffer()
+            self.__serial.reset_output_buffer()
+            time.sleep(WAIT_DURATION)
+            if (self.__serial.dsr == 1):
+                break
+            if n == RETRY_COUNT:
+                raise SC64Exception('Couldn\'t reset SC64 device (on)')
+
+        self.__serial.dtr = 0
+        for n in range(0, RETRY_COUNT + 1):
+            time.sleep(WAIT_DURATION)
+            if (self.__serial.dsr == 0):
+                break
+            if n == RETRY_COUNT:
+                raise SC64Exception('Couldn\'t reset SC64 device (on)')
+
+    def __process_incoming_data(self, wait_for_response: bool) -> Optional[tuple[bytes, bytes]]:
+        while (wait_for_response or self.__serial.in_waiting >= 4):
+            buffer = self.__serial.read(4)
+            token = buffer[0:3]
+            id = buffer[3:4]
+            if (token == b'CMP'):
+                length = int.from_bytes(self.__serial.read(4), byteorder='big')
+                data = self.__serial.read(length)
+                return (id, data)
+            elif (token == b'PKT'):
+                length = int.from_bytes(self.__serial.read(4), byteorder='big')
+                data = self.__serial.read(length)
+                self.__packets.put((id, data))
+                if (not wait_for_response):
+                    break
+            elif (token == b'ERR'):
+                raise SC64Exception('Command response error')
+            else:
+                raise SC64Exception('Invalid token received')
+        return None
+
+    def __execute_command(self, cmd: bytes, args: list[int]=[0, 0], data: bytes=b'') -> bytes:
+        if (len(cmd) != 1):
+            raise SC64Exception('Length of command is different than 1 byte')
+        if (len(args) != 2):
+            raise SC64Exception('Number of arguments is different than 2')
+        try:
+            self.__serial.write(b'CMD' + cmd)
+            self.__serial.write(args[0].to_bytes(4, byteorder='big'))
+            self.__serial.write(args[1].to_bytes(4, byteorder='big'))
+            if (len(data) > 0):
+                self.__serial.write(data)
+            self.__serial.flush()
+            (id, response) = self.__process_incoming_data(True)
+            if (cmd != id):
+                raise SC64Exception('Command response ID didn\'t match')
+            return response
+        except serial.SerialException as e:
+            raise SC64Exception(f'Serial exception: {e}')
+
+    def __receive_data_packet(self) -> Optional[tuple[bytes, bytes]]:
+        if (self.__packets.empty()):
+            try:
+                if (self.__process_incoming_data(False) != None):
+                    raise SC64Exception('Unexpected command response')
+            except serial.SerialException as e:
+                raise SC64Exception(f'Serial exception: {e}')
+        if (not self.__packets.empty()):
+            packet = self.__packets.get()
+            self.__packets.task_done()
+            return packet
+        return None
+
+    def update_firmware(self, data: bytes) -> None:
+        FIRMWARE_ADDRESS = 0x00100000
+        FIRMWARE_UPDATE_TIMEOUT = 90.0
+
+        self.__reset()
+        self.__execute_command(b'R')
+        self.__execute_command(b'M', [FIRMWARE_ADDRESS, len(data)], data)
+        self.__execute_command(b'F', [FIRMWARE_ADDRESS, len(data)])
+
+        timeout = time.time() + FIRMWARE_UPDATE_TIMEOUT
+        while True:
+            if (time.time() > timeout):
+                raise SC64Exception('Firmware update timeout')
+            packet = self.__receive_data_packet()
+            if (packet == None):
+                time.sleep(0.001)
+                continue
+            (id, packet_data) = packet
+            if (id != b'F'):
+                raise SC64Exception('Unexpected packet id received')
+            status = self.__UpdateStatus(int.from_bytes(packet_data[0:4], byteorder='big'))
+            if (status == self.__UpdateStatus.ERROR):
+                raise SC64Exception('Firmware update error')
+            if (status == self.__UpdateStatus.DONE):
+                time.sleep(2)
+                break
+
+
 class SC64BringUp:
     __SERIAL_BAUD: int      = 115200
     __SERIAL_TIMEOUT: float = 6.0
@@ -419,14 +580,17 @@ class SC64BringUp:
     def load_update_data(self, path: str) -> None:
         self.__sc64_update_data = SC64UpdateData()
         self.__sc64_update_data.load(path, require_all=True)
+        self.__bootloader_only_firmware = self.__sc64_update_data.create_bootloader_only_firmware()
 
     def get_update_info(self) -> str:
         return self.__sc64_update_data.get_update_info()
 
-    def start_bring_up(self, port: str, only_bootloader: bool=False) -> None:
+    def start_bring_up(self, port: str, bootloader_only: bool=False) -> None:
         link = None
+        sc64 = SC64()
+
         try:
-            if (not only_bootloader):
+            if (not bootloader_only):
                 link = serial.Serial(
                     port,
                     baudrate=self.__SERIAL_BAUD,
@@ -453,11 +617,10 @@ class SC64BringUp:
                 time.sleep(self.__INTERVAL_TIME)
                 link.read_all()
 
-            bootloader_description = 'Bootloader -> SC64 FLASH'
+            bootloader_description = 'Bootloader -> SC64 FLASH (no progress reporting)'
-            bootloader_data = self.__sc64_update_data.get_bootloader_data()
+            bootloader_length = len(self.__bootloader_only_firmware)
-            bootloader_length = len(bootloader_data)
             self.__progress(bootloader_length, 0, bootloader_description)
-            SC64().upload_bootloader(bootloader_data)
+            sc64.update_firmware(self.__bootloader_only_firmware)
             self.__progress(bootloader_length, bootloader_length, bootloader_description)
         finally:
             if (link and link.is_open):
@@ -467,14 +630,14 @@ class SC64BringUp:
 if __name__ == '__main__':
     nargs = len(sys.argv)
     if (nargs < 3 or nargs > 4):
-        Utils.die(f'Usage: {sys.argv[0]} serial_port update_file [--only-bootloader]')
+        Utils.die(f'Usage: {sys.argv[0]} serial_port update_file [--bootloader-only]')
 
     port = sys.argv[1]
     update_data_path = sys.argv[2]
-    only_bootloader = False
+    bootloader_only = False
     if (nargs == 4):
-        if (sys.argv[3] == '--only-bootloader'):
+        if (sys.argv[3] == '--bootloader-only'):
-            only_bootloader = True
+            bootloader_only = True
         else:
             Utils.die(f'Unknown argument: {sys.argv[3]}')
 
@@ -491,12 +654,12 @@ if __name__ == '__main__':
         sc64_bring_up.load_update_data(update_data_path)
     except SC64UpdateDataException as e:
         Utils.die(f'Provided \'{update_data_path}\' file is invalid: {e}')
-    Utils.log_no_end('Update info: ')
+    Utils.log('Update info: ')
     Utils.log(sc64_bring_up.get_update_info())
     Utils.log()
 
-    if (only_bootloader):
+    if bootloader_only:
-        Utils.log('Running in "only bootloader" mode')
+        Utils.log('Running in "bootloader only" mode')
         Utils.log()
 
     Utils.warning('[  CAUTION  ]')
@@ -520,8 +683,8 @@ if __name__ == '__main__':
     original_sigint_handler = signal.getsignal(signal.SIGINT)
     try:
         signal.signal(signal.SIGINT, lambda *kwargs: utils.exit_warning())
-        sc64_bring_up.start_bring_up(port, only_bootloader)
+        sc64_bring_up.start_bring_up(port, bootloader_only)
-    except (serial.SerialException, STM32BootloaderException, LCMXO2PrimerException) as e:
+    except (serial.SerialException, STM32BootloaderException, LCMXO2PrimerException, SC64Exception) as e:
         if (utils.get_progress_active):
             Utils.log()
         Utils.die(f'Error while running bring-up: {e}')

sw/tools/requirements.txt

@@ -1,2 +1 @@
-Pillow==9.2.0
 pyserial==3.5

sw/tools/update.py

@@ -145,13 +145,13 @@ class JedecFile:
 
 
 class SC64UpdateData:
-    __UPDATE_TOKEN = b'SC64 Update v2.0'
+    __UPDATE_TOKEN              = b'SC64 Update v2.0'
 
-    __CHUNK_ID_UPDATE_INFO = 1
+    __CHUNK_ID_UPDATE_INFO      = 1
-    __CHUNK_ID_MCU_DATA = 2
+    __CHUNK_ID_MCU_DATA         = 2
-    __CHUNK_ID_FPGA_DATA = 3
+    __CHUNK_ID_FPGA_DATA        = 3
-    __CHUNK_ID_BOOTLOADER_DATA = 4
+    __CHUNK_ID_BOOTLOADER_DATA  = 4
-    __CHUNK_ID_PRIMER_DATA = 5
+    __CHUNK_ID_PRIMER_DATA      = 5
 
     __data = b''