Merge pull request #15 from newaetech/uf2_all

Uf2 all

Author: alex-dewar

CMakeLists.txt

@@ -30,6 +30,7 @@ if (CMAKE_C_COMPILER_ID STREQUAL "GNU")
     add_compile_options(-Wno-pointer-sign)
     add_compile_options(-Wno-discarded-qualifiers)
     add_compile_options(-Wno-missing-braces)
+    add_compile_options(-Wno-unused-variable)
 endif()
 
 # Hardware-specific examples in subdirectories:

Developer Notes.md

@@ -0,0 +1,49 @@
+## Things This Firmware Does
+
+### Handling Bitstreams/Firmware
+
+This firmware enumerates as a FAT16 USB mass storage device and allows programming of both
+bitstreams to the onboard FPGA/SPI flash and UF2 files into the second SPI flash.
+
+The most important function for that is `tud_msc_write10_cb()` in `msc_disk.c`, which is called
+when the PC writes data to the disk. Most of the drive is "fake" (i.e. the file can't be read after
+being written).
+
+In practice, writes are typically the smaller of `CFG_TUD_MSC_EP_BUFSIZE` and the length of the remaining file.
+Writes to folder clusters (the file information), the file table, and the actual file data can be done in any order
+and this varies by operation system. For example, Windows will write file information before file data, but this
+is the opposite on Linux. Technically, data writes can be out of order, but this doesn't appear to happen in practice.
+
+Various FAT utility functions (such as writing to files, getting file info, etc) are in `fat_util.c`
+and flash functions are in `flash_util.c`. A CRC32C is used to verify the data written to flash.
+
+See `FAT Filesystem.md` for more information about the filesystem.
+
+### Config File
+
+This firmware includes a config file (`CONFIG.txt`) that appears in the root directory of the filesystem. Code for parsing
+this file is in `config.c`. Current options include SPI frequency and whether or not to save bitstreams to SPI flash.
+
+### Logging
+
+A logging file (`LOG.txt`) is also included.
+Different logging levels are available and can be selected with `-DDEBUG_LEVEL=N` where `N` is between 1 and 5. The levels available are:
+
+1. Critical
+1. Error
+1. Warning
+1. Info
+1. Debug
+
+with Info (4) being the default. Handling of the log file is done in `error.c` and `error.h`.
+
+###  Tests
+
+Some basic tests can be run by creating testing firmware with cmake: `-DTESTING_BUILD=ON`,
+then running either `tests/test_linux.py` or `tests/test_windows.py`, depending on your platform.
+
+Tests should be run after a fresh boot and nothing should be uploaded to the Sonata before running the tests.
+
+Some tests are done via functions in `tests.c`, but others are done inline in the code. Tests will be recorded
+in `LOG.txt` and in the form `"TEST %lu %4s: " + STR` where `%lu` is an incrementing integer, `%4s` is either
+`"PASS"` or `"FAIL"` and `STR` gives additional context for the test.

README.md

@@ -1,5 +1,38 @@
 # RP2040 Firmware for Sonata Board
 
+## Usage
+
+### Copying Bitstreams/Firmware
+
+Once plugged in, the Sonata board should enumerate as a USB mass storage device. Bitstreams
+and Sonata firmware can both be programmed by copying their respective files to the mass
+storage device. Bitstreams and firmware must be in UF2 format with a maximum block size
+of 256 bytes and device IDs of `0x6ce29e6b` and `0x6ce29e60`, respectively. Only the data
+portion of the UF2 block is written to flash.
+
+Note that the FPGA is currently erased during both firmware and bitstream programming,
+then reprogrammed afterwards.
+
+### Flash Slots
+
+Bitstream and firmware both have 3 flash slots, which can be selected via the 3 position
+Bitstream select switch by the USB port on the device. This controls both where
+bitstream/firmware are written to when programming, as well as where bitstreams
+are loaded from on device boot.
+
+### Logging/Options
+
+Important things such as firmware version, which slots have bitstreams/firmware, etc.
+is logged in LOG.TXT. Various options, such as programming speed and whether or not
+to write bitstreams to flash can be modified in OPTIONS.TXT.
+
+### Reprogramming/Updating Sonata
+
+The Sonata's firmware can be erased by holding down SW9 while plugging in the USB, after
+which the board should enumerate as a different USB mass storage device. New firmware is 
+avilable in UF2 format and can be programmed by copying the UF2 file into the drive, similar
+to how bitstream and firmware programming works on the Sonata board.
+
 ## Getting started
 
 ### Linux Setup
@@ -30,6 +63,18 @@ cd build
 PICO_SDK_PATH=/path-to/pico-sdk cmake ..
 make # or ninja if on Windows
 ```
+## Logging
+
+Different logging levels are available and can be selected with `-DDEBUG_LEVEL=N` where `N` is
+between 1 and 5. The levels available are:
+
+1. Critical
+1. Error
+1. Warning
+1. Info
+1. Debug
+
+with Info (4) being the default. Logs are written to `LOG.txt`.
 
 ## Debugging
 
@@ -50,6 +95,13 @@ cd build
 arm-none-eabi-gdb usb_msc/usb_msc.elf -ex "target extended-remote localhost:3333" -ex "load" -ex "monitor reset init"
 ```
 
+## Testing
+
+Some basic tests can be run by creating testing firmware with cmake: `-DTESTING_BUILD=ON`,
+then running either `tests/test_linux.py` or `tests/test_windows.py`, depending on your platform.
+
+Tests should be run after a fresh boot and nothing should be uploaded to the Sonata before running the tests.
+
 ## Notes
 
 ### Windows Quirks

tests/bitstream.bit.uf2

@@ -0,0 +1,12 @@
+from test_common import xorshift, xor_fill_buf, gen_xorshift_crc32
+from crc32c import crc32c
+
+sums = gen_xorshift_crc32()
+print("xorshift gen crc32: " + ", ".join("0x{:04X}".format(sum) for sum in sums))
+
+files = ["sonata_top_lrlcd.bit", "sonata-exceptions.bit", "sonata.bit", "usb_msc.uf2"]
+for file in files:
+    with open(file, "rb") as f:
+        data = f.read()
+        crc = crc32c(data)
+        print("Crc for {} is 0x{:04X}".format(file, crc))

tests/firmware.elf.uf2

@@ -25,6 +25,10 @@ def xor_fill_buf(buf, seed):
 
     return buf
 
+def clear_log_file(sonata_path):
+    with open(sonata_path + "/LOG.TXT", "w") as f:
+        f.close()
+
 def get_windows_drive_letter():
     import wmi
     sonata_letter = None
@@ -69,13 +73,17 @@ def gen_xorshift_crc32(seeds=[0xDEADBEEF, 0x11223344, 0xF0F0A7A7]):
 "
 
 def copy_sonata_bitstream(sonata_path):
-    shutil.copyfile("./sonata.bit", sonata_path + "/sonata.bit")
+    shutil.copyfile("./bitstream.bit.uf2", sonata_path + "/bs.uf2")
+
+def copy_firmware(sonata_path):
+    shutil.copyfile("./firmware.elf.uf2", sonata_path + "/fw.uf2")
 
 def write_options(sonata_path, string):
-    option_file = open(sonata_path + "/OPTIONS.txt", "w")
+    option_file = open(sonata_path + "/OPTIONS.TXT", "w")
     option_file.write(string)
     logging.debug("Writing")
     logging.debug(string)
+    option_file.flush() # shouldn't be necessary
     option_file.close()
 
 def write_all_options(sonata_path):
@@ -88,7 +96,7 @@ def write_all_options(sonata_path):
 
 def get_test_results(sonata_path):
     results = []
-    option_file = open(sonata_path + "/LOG.txt", "r")
+    option_file = open(sonata_path + "/LOG.TXT", "r")
     string = option_file.read()
     option_file.close()
 
@@ -111,4 +119,14 @@ def test_passed(test_string):
 
 def get_test_name(test_string):
     strs = test_string.split(':')
-    return strs[-1]
+    return strs[-1]
+
+def get_test_names():
+    names = []
+    with open("../usb_msc/test_names.h") as name_file:
+        data = name_file.read()
+        for line in data.split('\n'):
+            if "#define" in line:
+                name = line.split(" ")[-1]
+                print(name)
+        pass

tests/generate_crc.py

@@ -12,12 +12,14 @@ def get_sonata_path():
     result = subprocess.run(['blkid', '-l', '-o', 'device', '-t', 
                              'LABEL=SONATA', '-c', '/dev/null'],
                              capture_output=True)
-    mnt = result.stdout().decode().strip()
+    mnt = result.stdout.decode().strip()
     result = subprocess.run(['findmnt', mnt, '-no', 'TARGET'], capture_output=True)
-    return result.stdout().decode().strip()
+    return result.stdout.decode().strip()
 
 
-sonata_path = "../../sonata" #TODO: make this better
+#sonata_path = "../../sonata" #TODO: make this better
+sonata_path = get_sonata_path()
+os.sync()
 print("Copying sonata.bit...")
 copy_sonata_bitstream(sonata_path)
 os.sync() #ensure above write finishes
@@ -30,6 +32,11 @@ def get_sonata_path():
 print("Done. Ejecting drive...")
 sleep(0.25)
 
+print("Copying firmware")
+copy_firmware(sonata_path)
+os.sync()
+
+
 results, full_file = get_test_results(sonata_path)
 intended_failures = (3, 4) # these ones check to make sure invalid 
 any_failures = 0
@@ -38,12 +45,16 @@ def get_sonata_path():
         if result['passed']:
             print("Passed test that should have failed {}".format(str(result)))
             any_failures = 1
+        else:
+            print("Passed test {}".format(str(result['name'])))
     else:
         if not result['passed']:
             print("Failed test {}".format(str(result)))
             any_failures = 1
+        else:
+            print("Passed test {}".format(str(result['name'])))
 
-with open('LOG.txt', "w") as f:
+with open('LOG.TXT', "w") as f:
     f.write(str(full_file))
 
 if not any_failures:

tests/test_common.py

@@ -1,32 +1,47 @@
 import numpy as np
-from time import sleep
+from time import sleep, perf_counter
 from test_common import *
 import logging
 
 # shutil.copyfile("")
 # logging.getLogger().setLevel(logging.DEBUG)
 # ps_run("./eject.ps1")
+
+test_names = get_test_names()
+
 logging.basicConfig(filename="log.txt", level=logging.DEBUG, filemode='w', 
                     format='%(asctime)s,%(msecs)d %(name)s %(levelname)s %(message)s',
                     datefmt='%H:%M:%S',)
 sonata_letter = get_windows_drive_letter()
 
+
 if not sonata_letter:
     print("Sonata drive not found")
     exit(1)
 
 print("Sonata at " + sonata_letter)
+print("Clearing log file...")
+clear_log_file(sonata_letter)
 print("Copying sonata.bit...")
+t0 = perf_counter()
 copy_sonata_bitstream(sonata_letter)
+t1 = perf_counter()
+total = t1 - t0
 
-print ("Done copy. Testing config write and parse...")
+print ("Done copy, took {}. Testing config write and parse...".format(total))
 
 write_all_options(sonata_letter)
 
 print("Done. Ejecting drive...")
 sleep(0.25)
 win_eject_drive()
 
+print("Copying firmware")
+copy_firmware(sonata_letter)
+print("Done. Ejecting drive...")
+sleep(0.25)
+win_eject_drive()
+
 results, full_file = get_test_results(sonata_letter)
 intended_failures = (3, 4) # these ones check to make sure invalid 
 any_failures = 0
@@ -35,10 +50,14 @@
         if result['passed']:
             print("Passed test that should have failed {}".format(str(result)))
             any_failures = 1
+        else:
+            print("Passed test {}".format(str(result['name'])))
     else:
         if not result['passed']:
             print("Failed test {}".format(str(result)))
             any_failures = 1
+        else:
+            print("Passed test {}".format(str(result['name'])))
 
 with open('LOG.txt', "w") as f:
     f.write(str(full_file))

tests/test_linux.py

@@ -0,0 +1,7 @@
+from crc32c import crc32c
+
+with open("usb_msc.uf2", "rb") as f:
+    data = f.read()
+    # print(data)
+    crc = crc32c(data)
+    print(hex(crc))