pybricksdev._vendored: add pynxt library

This is a partial copy of the pynxt library from [1].

[1]: https://github.com/pybricks/nxos/tree/0d4878705b23e19d341d89e940bfbf4e59d274ea

Author: dlech

.gitignore

@@ -3,7 +3,6 @@
 *.o
 *.a
 *.elf
-*.bin
 *.map
 *.hex
 *.dis

pybricksdev/_vendored/pynxt/__init__.py

@@ -0,0 +1,11 @@
+# SPDX-License-Identifier: GPL-2.0-only
+# Copyright 2006 David Anderson <[email protected]>
+
+"""
+PyNXT is a Python module that enables developers to communicate with
+Lego Mindstorms NXT bricks at a low level. It currently facilitates
+scanning the USB chain for a NXT brick and implements the SAM-BA
+bootloader communication protocol. It comes with two utilities, fwflash
+and fwexec, which can be used to write a firmware to either flash memory
+or RAM, and execute it from there.
+"""

pybricksdev/_vendored/pynxt/firmware.py

@@ -0,0 +1,52 @@
+# SPDX-License-Identifier: GPL-2.0-only
+# Copyright 2006 David Anderson <[email protected]>
+# Copyright 2023 The Pybricks Authors
+
+import struct
+
+
+class Error(Exception):
+    """Exception base class for this program."""
+
+
+class FileTooSmall(Error):
+    """File is too small to be a firmware."""
+
+
+class FileTooLarge(Error):
+    """File is too large to fit in flash memory."""
+
+
+class InvalidHeader(Error):
+    """Firmware has invalid header."""
+
+
+class Firmware:
+    FLASH_SIZE = 256 * 1024  # NXT has 256 KiB flash memory
+    MIN_SIZE = 500  # needs at least a vector table and some init code
+    HEADER_DEF = "<5L?"
+    HEADER_SIZE = struct.calcsize(HEADER_DEF)
+
+    def __init__(self, fw_and_header: bytes):
+        if len(fw_and_header) < Firmware.HEADER_SIZE + Firmware.MIN_SIZE:
+            raise FileTooSmall("firmware is too small to be a valid firmware.")
+
+        header = fw_and_header[-self.HEADER_SIZE :]
+        self.firmware = fw_and_header[: -self.HEADER_SIZE]
+
+        (
+            magic,
+            self.ramsize,
+            self.romsize,
+            self.writeaddr,
+            self.loadaddr,
+            self.samba,
+        ) = struct.unpack(self.HEADER_DEF, header)
+
+        if magic != 0xDEADBEEF:
+            raise InvalidHeader("Bad magic on header")
+
+        if len(self.firmware) > Firmware.FLASH_SIZE:
+            raise FileTooLarge(
+                f"provided firmware is {len(self.firmware)} bytes but flash memory is only {Firmware.FLASH_SIZE} bytes"
+            )

pybricksdev/_vendored/pynxt/flash.py

@@ -0,0 +1,109 @@
+# SPDX-License-Identifier: GPL-2.0-only
+# Copyright 2006 David Anderson <[email protected]>
+
+import math
+
+from importlib.resources import read_binary
+
+from . import resources
+
+# Mnemonics for the addresses of the various registers used by the flash
+# controller.
+PMC_MCKR = 0xFFFFFC30  # Master clock register
+MC_FMR = 0xFFFFFF60  # Flash mode register
+MC_FCR = 0xFFFFFF64  # Flash control register
+MC_FSR = 0xFFFFFF68  # Flash status register
+
+# The addresses in ram used by the flash driver.
+FLASH_DRIVER_ADDR = 0x202000
+FLASH_TARGET_BLOCK_NUM_ADDR = 0x202300
+FLASH_BLOCK_DATA_ADDR = 0x202100
+
+# The region lock control bits are non-volatile bits, which have special
+# timing requirements compared to the 'regular' flash memory. The
+# following constants define the timing settings for lock bits and for
+# normal flash memory.
+#
+# FMCN = 0x5, FWS = 0x1
+FLASH_REGION_LOCK_SETTING = (0x5 << 16) | (0x1 << 8)
+# FMCN = 0x34, FWS = 0x1
+FLASH_MEMORY_WRITE_SETTING = (0x34 << 16) | (0x1 << 8)
+
+# The base command to unlock a flash region, and a helper to generate the
+# correct region number.
+FLASH_REGION_UNLOCK_CMD = (0x5A << 24) | (0x4)
+
+
+def _unlock_region(region_num):
+    # The unlock command must specify the page number of any page within
+    # the region that you want to unlock. Since each region is 64 pages
+    # long, we just multiply the page number by 64 to get into the
+    # correct region.
+    return FLASH_REGION_UNLOCK_CMD | ((64 * region_num) << 8)
+
+
+class MissingFlashDriverFile(Exception):
+    """Could not find the flash driver firmware image."""
+
+
+class InvalidFirmwareImage(Exception):
+    """The given firmware image cannot be written."""
+
+
+class FlashController(object):
+    def __init__(self, brick):
+        self._brick = brick
+
+    def _wait_for_flash(self):
+        """Wait for the flash controller to become ready."""
+        status = self._brick.read_word(MC_FSR)
+        while not (status & 0x1):
+            status = self._brick.read_word(MC_FSR)
+
+    def _unlock_regions(self):
+        status = self._brick.read_word(MC_FSR)
+        if (status & 0xFFFF0000) == 0:
+            return
+
+        self._brick.write_word(MC_FMR, FLASH_REGION_LOCK_SETTING)
+        for i in range(16):
+            mask = 1 << (16 + i)
+            if status & mask:
+                self._brick.write_word(MC_FCR, _unlock_region(i))
+                self._wait_for_flash()
+        self._brick.write_word(MC_FMR, FLASH_MEMORY_WRITE_SETTING)
+
+    def _prepare_flash(self):
+        # Switch to the PLL clock with a /2 prescaler. The timing
+        # configurations we use are only valid for that configuration.
+        #
+        # TODO: The atmel tool does this as well, but according to the
+        # specs this is horribly wrong: one should absolutely not switch
+        # clock sources and prescalers in one go, much less switch to
+        # the PLL without configuring it and stabilizing it first. What
+        # the hell is this?
+        self._brick.write_word(PMC_MCKR, 0x7)
+
+        # Set the correct timings for flash writes.
+        self._brick.write_word(MC_FMR, FLASH_MEMORY_WRITE_SETTING)
+
+        # Check/unlock all flash regions.
+        self._unlock_regions()
+
+        # Send the flash driver to the brick.
+        driver = read_binary(resources, resources.FLASH_DRIVER)
+        self._brick.write_buffer(FLASH_DRIVER_ADDR, driver)
+
+    def flash(self, firmware):
+        self._prepare_flash()
+
+        num_pages = int(math.ceil(len(firmware) / 256))
+        if num_pages > 1024:
+            raise InvalidFirmwareImage("The firmware image must be smaller than 256kB")
+
+        for page_num in range(num_pages):
+            self._brick.write_word(FLASH_TARGET_BLOCK_NUM_ADDR, page_num)
+            self._brick.write_buffer(
+                FLASH_BLOCK_DATA_ADDR, firmware[page_num * 256 : (page_num + 1) * 256]
+            )
+            self._brick.jump(FLASH_DRIVER_ADDR)

pybricksdev/_vendored/pynxt/lowlevel.py

@@ -0,0 +1,73 @@
+# SPDX-License-Identifier: GPL-2.0-only
+# Copyright 2006 David Anderson <[email protected]>
+
+import usb
+import time
+
+USB_BULK_OUT_EP = 0x1
+USB_BULK_IN_EP = 0x82
+
+
+def enumerate_usb():
+    """Return a generator yielding all attached USB devices."""
+    busses = usb.busses()
+    for bus in busses:
+        devices = bus.devices
+        for dev in devices:
+            yield dev
+
+
+def get_device(vendor_id, product_id, version=0, timeout=None):
+    """Return the first device matching the given vendor/product ID."""
+    while True:
+        for dev in enumerate_usb():
+            if (
+                dev.idVendor == vendor_id
+                and dev.idProduct == product_id
+                and dev.iSerialNumber == version
+            ):
+                return UsbBrick(dev)
+        if timeout is None or timeout <= 0:
+            return None
+        sleep_time = min(1.0, timeout)
+        time.sleep(sleep_time)
+        timeout -= sleep_time
+
+
+class UsbBrick(object):
+    def __init__(self, dev):
+        self._dev = dev
+
+    def __del__(self):
+        try:
+            self.close()
+        except Exception:
+            pass
+
+    def open(self, interface, configuration=1, detach_kernel_driver=False):
+        self._iface = interface
+        self._config = configuration
+        self._hdl = self._dev.open()
+        if detach_kernel_driver:
+            self._hdl.detachKernelDriver(interface)
+        self._hdl.setConfiguration(configuration)
+        self._hdl.claimInterface(interface)
+
+    def close(self):
+        self._hdl.releaseInterface()
+        del self._hdl
+
+    def read(self, size, timeout=100):
+        """Read the given amount of data from the device and return it."""
+        # For some reason, bulkRead returns a tuple of longs. This is
+        # dumb, so we convert it back to a string before returning,
+        # kthx.
+        try:
+            data = self._hdl.bulkRead(USB_BULK_IN_EP, size, timeout)
+        except usb.USBError:
+            return None
+        return "".join(chr(x) for x in data)
+
+    def write(self, data, timeout=100):
+        """Write the given amount of data to the device."""
+        return self._hdl.bulkWrite(USB_BULK_OUT_EP, data, timeout)

pybricksdev/_vendored/pynxt/resources/Makefile

@@ -0,0 +1,23 @@
+#all:
+#	gcc -Wall -O0 -mcpu=arm7tdmi-s -mapcs -mthumb-interwork -o flash.o flash.c -nostartfiles -nodefaultlibs -nostdlib -Wl,-e,main
+#	objcopy -Obinary -j.text flash.o flash.bin
+#	objdump --disassemble-all -bbinary -marm7tdmi flash.bin > flash.asm
+#
+
+CC=arm-none-eabi-gcc
+AS=arm-none-eabi-as
+LD=arm-none-eabi-ld
+OBJCOPY=arm-none-eabi-objcopy
+
+TARGET = flash_driver.bin
+
+all:
+	$(CC) -W -Wall -Os -msoft-float -mcpu=arm7tdmi -mapcs -c -o flash.o flash.c
+	$(AS) --warn -mfpu=softfpa -mcpu=arm7tdmi -mapcs-32 -o crt0.o crt0.s
+	$(LD) -Os --gc-sections crt0.o flash.o -o flash.elf
+	$(OBJCOPY) -O binary flash.elf $(TARGET)
+	chmod -x $(TARGET)
+	rm -f flash.o crt0.o flash.elf
+
+clean:
+	rm -f flash.o crt0.o flash.elf $(TARGET)

pybricksdev/_vendored/pynxt/resources/__init__.py

@@ -0,0 +1,11 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2021 The Pybricks Authors
+
+"""Resource files.
+
+These resources are intended to be used with the standard ``importlib.resources``
+module.
+"""
+
+FLASH_DRIVER = "flash_driver.bin"
+"""Application running from NXT RAM to install new firmware on flash."""

pybricksdev/_vendored/pynxt/resources/crt0.s

@@ -0,0 +1,23 @@
+/* SPDX-License-Identifier: GPL-2.0-or-later */
+/* Copyright 2006 David Anderson <[email protected]> */
+
+/**
+ * NXT bootstrap interface; NXT onboard flashing driver bootstrap.
+ */
+
+.text
+.align 4
+.globl _start
+
+_start:
+	/* Initialize the stack */
+	mov sp, #0x210000
+
+	/* Preserve old link register */
+	stmfd sp!, {lr}
+
+	/* Call main */
+	bl do_flash_write
+
+	/* Return */
+	ldmfd sp!, {pc}

pybricksdev/_vendored/pynxt/resources/flash.c

@@ -0,0 +1,32 @@
+/* SPDX-License-Identifier: GPL-2.0-or-later */
+/* Copyright 2006 David Anderson <[email protected]> */
+
+/**
+ * NXT bootstrap interface; NXT onboard flashing driver.
+ */
+
+#define VINTPTR(addr) ((volatile unsigned int *)(addr))
+#define VINT(addr) (*(VINTPTR(addr)))
+
+#define USER_PAGE VINTPTR(0x00202100)
+#define USER_PAGE_NUM VINT(0x00202300)
+
+#define FLASH_BASE VINTPTR(0x00100000)
+#define FLASH_CMD_REG VINT(0xFFFFFF64)
+#define FLASH_STATUS_REG VINT(0xFFFFFF68)
+#define OFFSET_PAGE_NUM ((USER_PAGE_NUM & 0x000003FF) << 8)
+#define FLASH_CMD_WRITE (0x5A000001 + OFFSET_PAGE_NUM)
+
+void do_flash_write(void)
+{
+  unsigned long i;
+
+  while (!(FLASH_STATUS_REG & 0x1));
+
+  for (i = 0; i < 64; i++)
+    FLASH_BASE[(USER_PAGE_NUM*64)+i] = USER_PAGE[i];
+
+  FLASH_CMD_REG = FLASH_CMD_WRITE;
+
+  while (!(FLASH_STATUS_REG & 0x1));
+}