pynvcm.py

#!/usr/bin/env python
#
#  Copyright (C) 2021
#
#  * Trammell Hudson <hudson@trmm.net>
#  * Matthew Mets https://github.com/cibomahto
#  * Peter Lawrence https://github.com/majbthrd
#
#  Copyright (C) 2022, 2023 Tillitis AB
#
#  SPDX-License-Identifier: ISC
#
#  Permission to use, copy, modify, and/or distribute this software
#  for any purpose with or without fee is hereby granted, provided
#  that the above copyright notice and this permission notice
#  appear in all copies.
#
#  THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL
#  WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED
#  WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE
#  AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR
#  CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
#  LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
#  NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN
#  CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
#
"""NVCM programming tool for iCE40 FPGAs"""

import os
import sys
import struct
from time import sleep
from iceflasher import IceFlasher
from pybin2nvcm import pybin2nvcm


def assert_bytes_equal(
        name: str,
        expected: bytes,
        val: bytes) -> None:
    """ Check if two bytes objects are equal

    Keyword arguments:
    name -- Description to print if the assertion fails
    expected -- Expected value
    val -- Value to check
    """
    if expected != val:
        expected_str = ' '.join([f'{x:02x}' for x in expected])
        val_str = ' '.join([f'{x:02x}' for x in val])
        raise AssertionError(
            f'{name} expected:[{expected_str}] read:[{val_str}]')


class Nvcm():
    """NVCM programming interface for ICE40 FPGAs"""
    id_table = {
        0x06: "ICE40LP8K / ICE40HX8K",
        0x07: "ICE40LP4K / ICE40HX4K",
        0x08: "ICE40LP1K / ICE40HX1K",
        0x09: "ICE40LP384",
        0x0E: "ICE40LP1K_SWG16",
        0x0F: "ICE40LP640_SWG16",
        0x10: "ICE5LP1K",
        0x11: "ICE5LP2K",
        0x12: "ICE5LP4K",
        0x14: "ICE40UL1K",
        0x15: "ICE40UL640",
        0x20: "ICE40UP5K",
        0x21: "ICE40UP3K",
    }

    banks = {
        'nvcm': 0x00,
        'trim': 0x10,
        'sig': 0x20
    }

    def __init__(
            self,
            pins: dict,
            spi_speed: int,
            debug: bool = False) -> None:
        self.pins = pins
        self.debug = debug

        self.flasher = IceFlasher()

        self.flasher.gpio_put(self.pins['5v_en'], False)
        self.flasher.gpio_put(self.pins['crst'], False)

        # Configure pins for talking to ice40
        self.flasher.gpio_set_direction(pins['ss'], True)
        self.flasher.gpio_set_direction(pins['mosi'], True)
        self.flasher.gpio_set_direction(pins['sck'], True)
        self.flasher.gpio_set_direction(pins['miso'], False)
        self.flasher.gpio_set_direction(pins['5v_en'], True)
        self.flasher.gpio_set_direction(pins['crst'], True)
        self.flasher.gpio_set_direction(pins['cdne'], False)

        self.flasher.spi_configure(
            pins['sck'],
            pins['ss'],
            pins['mosi'],
            pins['miso'],
            spi_speed
        )

    def power_on(self) -> None:
        """Enable power to the DUT"""
        self.flasher.gpio_put(self.pins['5v_en'], True)

    def power_off(self) -> None:
        """Disable power to the DUT"""
        self.flasher.gpio_put(self.pins['5v_en'], False)

    def enable(self, chip_select: bool, reset: bool = True) -> None:
        """Set the CS and Reset pin states"""
        self.flasher.gpio_put(self.pins['ss'], chip_select)
        self.flasher.gpio_put(self.pins['crst'], reset)

    def writehex(self, hex_data: str, toggle_cs: bool = True) -> None:
        """Write SPI data to the target device

        Keyword arguments:
        hex_data -- data to send (formatted as a string of hex data)
        toggle_cs -- If true, automatically lower the CS pin before
                     transmit, and raise it after transmit
        """
        if self.debug and not hex_data == "0500":
            print("TX", hex_data)
        data = bytes.fromhex(hex_data)

        self.flasher.spi_write(data, toggle_cs)

    def sendhex(self, hex_data: str) -> bytes:
        """Perform a full-duplex write/read on the target device

        Keyword arguments:
        s -- data to send (formatted as a string of hex data)
        """
        if self.debug and not hex_data == "0500":
            print("TX", hex_data)
        bytes_data = bytes.fromhex(hex_data)

        ret = self.flasher.spi_rxtx(bytes_data)

        if self.debug and not hex_data == "0500":
            print("RX", ret.hex())
        return ret

    def delay(self, count: int) -> None:
        """'Delay' by sending clocks with CS de-asserted

        Keyword arguments:
        count -- Number of bytes to clock
        """

        self.flasher.spi_clk_out(count)

    def init(self) -> None:
        """Reboot the part and enter SPI command mode"""
        if self.debug:
            print("init")
        self.enable(True, True)
        self.enable(True, False)
        self.enable(False, False)
        self.enable(False, True)
        sleep(0.1)
        self.enable(True, True)

    def status_wait(self) -> None:
        """Wait for the status register to clear"""
        for _ in range(0, 1000):
            self.delay(1250)
            ret = self.sendhex("0500")
            status = struct.unpack('>H', ret)[0]

            if (status & 0x00c1) == 0:
                return

        raise ValueError("status failed to clear")

    def command(self, cmd: str) -> None:
        """Send a command to the NVCM state machine"""
        self.writehex(cmd)
        self.status_wait()
        self.delay(2)

    def pgm_enable(self) -> None:
        """Enable program mode"""
        self.command("06")

    def pgm_disable(self) -> None:
        """Disable program mode"""
        self.command("04")

    def enable_access(self) -> None:
        """Send the 'access NVCM' instruction"""
        self.command("7eaa997e010e")

    def read_bytes(
            self,
            cmd: int,
            address: int,
            length: int = 8) -> bytes:
        """Read NVCM memory and return as a byte array

        Known read commands are:
        0x03: Read NVCM bank
        0x84: Read RF

        Keyword arguments:
        cmd -- Read command
        address -- NVCM memory address to read from
        length -- Number of bytes to read
        """

        msg = ''
        msg += (f"{cmd:02x}{address:06x}")
        msg += ("00" * 9)  # dummy bytes
        msg += ("00" * length)  # read
        ret = self.sendhex(msg)

        return ret[4 + 9:]

    def read_int(
            self,
            cmd: int,
            address: int) -> int:
        """Read NVCM memory and return as an integer

        Read commands are documented in read_bytes

        Keyword arguments:
        cmd -- Read command
        address -- NVCM memory address to read from
        """

        val = self.read_bytes(cmd, address, 8)
        return struct.unpack('>Q', val)[0]

    def write(self, cmd: int, address: int, data: str) -> None:
        """Write data to the NVCM memory

        Keyword arguments:
        cmd -- Write command
        address -- NVCM memory address to write to
        length -- Number of bytes to write
        """
        self.writehex(f"{cmd:02x}{address:06x}" + data)

        try:
            self.status_wait()
        except Exception as exc:
            raise IOError(
                f"WRITE FAILED: cmd={cmd:02x} address={address:%06x} data={data}"
            ) from exc

        self.delay(2)

    def bank_select(self, bank: str) -> None:
        """ Select the active NVCM bank to target

        Keyword arguments:
        bank -- NVCM bank: nvcm, trim, or sig
        """

        self.write(0x83, 0x000025, f"{self.banks[bank]:02x}")

    def read_trim(self) -> int:
        """Read the RF trim register"""
        self.enable_access()

        # ! Shift in READ_RF(0x84) instruction;
        # SDR 104 TDI(0x00000000000000000004000021);
        val = self.read_int(0x84, 0x000020)
        self.delay(2)

        # print("FSM Trim Register %x" % (x))

        self.bank_select('nvcm')
        return val

    def write_trim(self, data: str) -> None:
        """Write to the RF trim register

        Keyword arguments:
        data -- Hex-formatted string, should be 8 bytes of data
        """
        # ! Setup Programming Parameter in Trim Registers;
        # ! Shift in Trim setup-NVCM instruction;
        # TRIMInstruction[1] = 0x000000430F4FA80004000041;
        self.write(0x82, 0x000020, data)

    def nvcm_enable(self) -> None:
        """Enable NVCM interface by sending knock command"""
        if self.debug:
            print("enable")
        self.enable_access()

        # ! Setup Reading Parameter in Trim Registers;
        # ! Shift in Trim setup-NVCM instruction;
        # TRIMInstruction[1] = 0x000000230000000004000041;
        if self.debug:
            print("setup_nvcm")
        self.write_trim("00000000c4000000")

    def enable_trim(self) -> None:
        """Enable NVCM write commands"""
        # ! Setup Programming Parameter in Trim Registers;
        # ! Shift in Trim setup-NVCM instruction;
        # TRIMInstruction[1] = 0x000000430F4FA80004000041;
        self.write_trim("0015f2f0c2000000")

    def trim_blank_check(self) -> None:
        """Check that the NVCM trim parameters are blank"""

        print("NVCM Trim_Parameter_OTP blank check")

        self.bank_select('trim')

        ret = self.read_bytes(0x03, 0x000020, 1)[0]
        self.bank_select('nvcm')

        if ret != 0x00:
            raise ValueError(
                'NVCM Trim_Parameter_OTP Block not blank. ' +
                f'(read: 0x{ret:%02x})')

    def blank_check(self, total_fuse: int) -> None:
        """Check if sub-section of the NVCM memory is blank

        To check all of the memory, first determine how much NVCM
        memory your part actually has, or at least the size of the
        file that you plan to write to it.

        Keyword arguments:
        total_fuse -- Number of fuse bytes to read before stopping
        """
        self.bank_select('nvcm')

        status = True
        print("NVCM main memory blank check")
        contents = self.read_bytes(0x03, 0x000000, total_fuse)

        for index in range(0, total_fuse):
            val = contents[index]
            if self.debug:
                print(f"{index:08x}: {val:02x}")
            if val != 0:
                print(
                    f"{index:08x}: NVCM Memory Block is not blank.",
                    file=sys.stderr)
                status = False

        self.bank_select('nvcm')
        if not status:
            raise ValueError("NVCM Main Memory not blank")

    def program(self, rows: list[str]) -> None:
        """Program the memory by running an NVCM command sequence

        Keyword arguments:
        rows -- List of NVCM commands to run, formatted as hex
                strings
        """
        print("NVCM Program main memory")

        self.bank_select('nvcm')

        self.enable_trim()

        self.pgm_enable()

        i = 0
        for row in rows:
            # print('data for row:',i, row)
            if i % (1024 * 8) == 0:
                print("%6d / %6d bytes" % (i, len(rows) * 8))
            i += 8
            try:
                self.command(row)
            except Exception as exc:
                raise IOError(
                    "programming failed, row:{row}"
                ) from exc

        self.pgm_disable()

    def write_trim_pages(self, lock_bits: str) -> None:
        """Write to the trim pages

        The trim pages can be written multiple times. Known usages
        are to configure the device for NVCM boot, and to secure
        the device by disabling the NVCM interface.

        Keyword arguments:
        lock_bits -- Mas of bits to set in the trim pages
        """
        self.bank_select('nvcm')

        self.enable_trim()

        self.bank_select('trim')

        self.pgm_enable()

        # ! Program Security Bit row 1;
        # ! Shift in PAGEPGM instruction;
        # SDR 96 TDI(0x000000008000000C04000040);
        # ! Program Security Bit row 2;
        # SDR 96 TDI(0x000000008000000C06000040);
        # ! Program Security Bit row 3;
        # SDR 96 TDI(0x000000008000000C05000040);
        # ! Program Security Bit row 4;
        # SDR 96 TDI(0x00000000800000C07000040);
        self.write(0x02, 0x000020, lock_bits)
        self.write(0x02, 0x000060, lock_bits)
        self.write(0x02, 0x0000a0, lock_bits)
        self.write(0x02, 0x0000e0, lock_bits)

        self.pgm_disable()

        # verify a read back
        val = self.read_int(0x03, 0x000020)

        self.bank_select('nvcm')

        lock_bits_int = int(lock_bits, 16)
        if val & lock_bits_int != lock_bits_int:
            raise ValueError(
                "Failed to write trim lock bits: " +
                f"{val:016x} != expected {lock_bits_int:016x}"
            )

        print(f"New state {val:016x}")

    def trim_secure(self) -> None:
        """Disable NVCM readout by programming the security bits

        Use with caution- the device will no longer respond to NVCM
        commands after this command runs.
        """
        print("NVCM Secure")
        trim = self.read_trim()
        if (trim >> 60) & 0x3 != 0:
            print(
                "NVCM already secure? trim=%016x" %
                (trim), file=sys.stderr)

        self.write_trim_pages("3000000100000000")

    def trim_program(self) -> None:
        """Configure the device to boot from NVCM (?)

        Use with caution- the device will no longer boot from
        external SPI flash after this command runs.
        """
        print("NVCM Program Trim_Parameter_OTP")
        self.write_trim_pages("0015f2f1c4000000")

    def info(self) -> None:
        """ Print the contents of the configuration registers """
        self.bank_select('sig')
        sig1 = self.read_int(0x03, 0x000000)

        self.bank_select('sig')
        sig2 = self.read_int(0x03, 0x000008)

        # have to switch back to nvcm bank before switching to trim?
        self.bank_select('nvcm')
        trim = self.read_trim()

#        self.bank_select('nvcm')

        self.bank_select('trim')
        trim0 = self.read_int(0x03, 0x000020)

        self.bank_select('trim')
        trim1 = self.read_int(0x03, 0x000060)

        self.bank_select('trim')
        trim2 = self.read_int(0x03, 0x0000a0)

        self.bank_select('trim')
        trim3 = self.read_int(0x03, 0x0000e0)

        self.bank_select('nvcm')

        secured = (trim >> 60) & 0x3
        device_id = (sig1 >> 56) & 0xFF

        print("Device: %s (%02x) secure=%d" % (
            self.id_table.get(device_id, "Unknown"),
            device_id,
            secured
        ))
        print("Sig  0: %016x" % (sig1))
        print("Sig  1: %016x" % (sig2))

        print("TrimRF: %016x" % (trim))
        print("Trim 0: %016x" % (trim0))
        print("Trim 1: %016x" % (trim1))
        print("Trim 2: %016x" % (trim2))
        print("Trim 3: %016x" % (trim3))

    def read_nvcm(self, length: int) -> bytes:
        """ Read out the contents of the NVCM fuses

        Keyword arguments:
        length: Length of data to read
        """

        self.bank_select('nvcm')

        # contents = bytearray()
        #
        # for offset in range(0, length, 8):
        #    if offset % (1024 * 8) == 0:
        #        print("%6d / %6d bytes" % (offset, length))

        #    nvcm_addr = int(offset / 328) * 4096 + (offset % 328)
        #    contents += self.read_bytes(0x03, nvcm_addr, 8)
        #    self.delay(2)

        # return bytes(contents)
        return self.read_bytes(0x03, 0x000000, length)

    def read_file(self, filename: str, length: int) -> None:
        """ Read the contents of the NVCM to a file

        Keyword arguments:
        filename -- File to write to, or '-' to write to stdout
        length -- Number of bytes to read from NVCM
        """

        contents = bytearray()

        # prepend a header to the file, to identify it as an FPGA
        # bitstream
        contents += bytes([0xff, 0x00, 0x00, 0xff])

        contents += self.read_nvcm(length)

        if filename == '-':
            with os.fdopen(sys.stdout.fileno(),
                           "wb",
                           closefd=False) as out_file:
                out_file.write(contents)
                out_file.flush()
        else:
            with open(filename, "wb") as out_file:
                out_file.write(contents)
                out_file.flush()

    def verify(self, filename: str) -> None:
        """ Verify that the contents of the NVCM match a file

        Keyword arguments:
        filename -- File to compare
        """
        with open(filename, "rb") as verify_file:
            compare = verify_file.read()

        assert len(compare) > 0

        contents = bytearray()
        contents += bytes([0xff, 0x00, 0x00, 0xff])
        contents += self.read_nvcm(len(compare))

        # We might have read more than needed because of read
        # boundaries
        if len(contents) > len(compare):
            contents = contents[:len(compare)]

        assert compare == contents
        print('Verification complete, NVCM contents match file')


def sleep_flash(pins: dict, spi_speed: int) -> None:
    """ Put the SPI bootloader flash in deep sleep mode

    Keyword arguments:
    pins -- Dictionary of pins to use for SPI interface
    """
    flasher = IceFlasher()

    # Disable board power
    flasher.gpio_put(pins['5v_en'], False)
    flasher.gpio_set_direction(pins['5v_en'], True)

    # Pull CRST low to prevent FPGA from starting
    flasher.gpio_set_direction(pins['crst'], True)
    flasher.gpio_put(pins['crst'], False)

    # Enable board power
    flasher.gpio_put(pins['5v_en'], True)

    # Configure pins for talking to flash
    flasher.gpio_set_direction(pins['ss'], True)
    flasher.gpio_set_direction(pins['mosi'], False)
    flasher.gpio_set_direction(pins['sck'], True)
    flasher.gpio_set_direction(pins['miso'], True)

    flasher.spi_configure(
        pins['sck'],
        pins['ss'],
        pins['miso'],
        pins['mosi'],
        spi_speed
    )

    sleep(0.5)

    # Wake the flash up
    flasher.spi_write(bytes([0xAB]))

    # Confirm we can talk to flash
    data = flasher.spi_rxtx(bytes([0x9f, 0, 0]))

    assert_bytes_equal('flash_id', bytes([0xff, 0xef, 0x40]), data)

    # put the flash to sleep
    flasher.spi_write(bytes([0xb9]))

    # Confirm flash is asleep
    data = flasher.spi_rxtx(bytes([0x9f, 0, 0]))

    assert_bytes_equal('flash_sleep', bytes([0xff, 0xff, 0xff]), data)


if __name__ == "__main__":

    import argparse

    parser = argparse.ArgumentParser()

    parser.add_argument(
        '-v',
        '--verbose',
        dest='verbose',
        action='store_true',
        help='Show debug information and serial read/writes')

    parser.add_argument(
        '-f',
        '--sleep_flash',
        dest='sleep_flash',
        action='store_true',
        help='Put an attached SPI flash chip in deep sleep')

    parser.add_argument(
        '-b',
        '--boot',
        dest='do_boot',
        action='store_true',
        help='Deassert the reset line to allow the FPGA to boot')

    parser.add_argument(
        '--speed',
        dest='spi_speed',
        type=int,
        default=15,
        help='SPI clock speed, in MHz')

    parser.add_argument('-i', '--info',
                        dest='read_info',
                        action='store_true',
                        help='Read chip ID, trim and other info')

    parser.add_argument('--read',
                        dest='read_file',
                        type=str,
                        default=None,
                        help='Read contents of NVCM')

    parser.add_argument('--verify',
                        dest='verify_file',
                        type=str,
                        default=None,
                        help='Verify the contents of NVCM')

    parser.add_argument(
        '--write',
        dest='write_file',
        type=str,
        default=None,
        help='bitstream file to write to NVCM ' +
        '(warning: not reversable!)')

    parser.add_argument('--ignore-blank',
                        dest='ignore_blank',
                        action='store_true',
                        help='Proceed even if the chip is not blank')

    parser.add_argument(
        '--secure',
        dest='set_secure',
        action='store_true',
        help='Set security bits to prevent modification ' +
        '(warning: not reversable!)')

    parser.add_argument(
        '--my-design-is-good-enough',
        dest='good_enough',
        action='store_true',
        help='Enable the dangerous commands --write and --secure')

    args = parser.parse_args()

    if not args.good_enough \
            and (args.write_file or args.set_secure):
        print(
            "Are you sure your design is good enough?",
            file=sys.stderr)
        sys.exit(1)

    tp1_pins = {
        '5v_en': 7,
        'sck': 10,
        'mosi': 11,
        'ss': 12,
        'miso': 13,
        'crst': 14,
        'cdne': 15
    }

    if args.sleep_flash:
        sleep_flash(tp1_pins, args.spi_speed)

    nvcm = Nvcm(
        tp1_pins,
        args.spi_speed,
        debug=args.verbose)
    nvcm.power_on()

    # # Turn on ICE40 in CRAM boot mode
    nvcm.init()
    nvcm.nvcm_enable()

    if args.read_info:
        nvcm.info()

    if args.write_file:
        with open(args.write_file, "rb") as in_file:
            bitstream = in_file.read()
        print(f"read {len(bitstream)} bytes")
        cmds = pybin2nvcm(bitstream)

        if not args.ignore_blank:
            nvcm.trim_blank_check()
            # how much should we check?
            nvcm.blank_check(100000)

        # this is it!
        nvcm.program(cmds)

        # update the trim to boot from nvcm
        nvcm.trim_program()

    if args.read_file:
        # read back after writing to the NVCM
        nvcm.read_file(args.read_file, 104090)

    if args.verify_file:
        # read back after writing to the NVCM
        nvcm.verify(args.verify_file)

    if args.set_secure:
        nvcm.trim_secure()

    if args.do_boot:
        # hold reset low for half a second
        nvcm.enable(True, False)
        sleep(0.5)
        nvcm.enable(True, True)