rustkey/

lib.rs

// rusTkey, a rust crate/library that provides a development API for the tillitis TKey.
// Copyright (C) 2024  Danny van Heumen
// SPDX-License-Identifier: BSD-2-Clause

#![no_std]
#![deny(unused_must_use)]
#![warn(clippy::pedantic)]
// Note: thread-safety is guaranteed; static mutable refs allowed by default.
#![allow(
    dead_code,
    clippy::identity_op,
    clippy::needless_range_loop,
    clippy::cast_lossless
)]

use core::ptr;

#[cfg(feature = "blake2-standalone")]
pub mod blake2s;

pub const ROM_BASE: usize = 0x0000_0000;
/// `ROM_SIZE` is not specified in tk1 memory model. Instead, this is the maximum allowed size that
/// is made available in EBR (Embedded Block RAM) in the verilog model. See
/// `hw/application_fpg/core/rom/rtl/rom.v` in the `tillitis-key1` repository containing the
/// hardware, fpga and firmware content.
///
/// `rom.v` (verilog):
///
///      "Max size for the ROM is 3072 [32-bit] words, and the address is 12 bits to support ROM
///      with this number of words."
pub const ROM_SIZE: usize = 3072 * 4;
pub const RAM_BASE: usize = 0x4000_0000;
pub const RAM_SIZE: usize = 0x2_0000;
const RESERVED_BASE: usize = 0x8000_0000;
const MMIO_BASE: usize = 0xc000_0000;
const MMIO_SIZE: usize = 0xffff_ffff - MMIO_BASE;

pub const TK1_CPU_FREQUENCY: u32 = 18_000_000;

/// The maximum possible size of an application, i.e. the size of available RAM.
pub const APP_MAX_SIZE: usize = RAM_SIZE;

const MMIO_TRNG_BASE: usize = MMIO_BASE | 0x0000_0000;
const MMIO_TIMER_BASE: usize = MMIO_BASE | 0x0100_0000;
const MMIO_UDS_BASE: usize = MMIO_BASE | 0x0200_0000;
const MMIO_TOUCH_BASE: usize = MMIO_BASE | 0x0400_0000;
const MMIO_FW_RAM_BASE: usize = MMIO_BASE | 0x1000_0000;
const MMIO_FW_RAM_SIZE: usize = 2048;
const MMIO_TK1_BASE: usize = MMIO_BASE | 0x3f00_0000;

/// `TK1_NAME0` is the address for the first 4-byte app-name.
pub const TK1_NAME0: *const u32 = (MMIO_TK1_BASE | 0x00) as *const u32;
/// `TK1_NAME1` is the address for the second 4-byte app-name.
pub const TK1_NAME1: *const u32 = (MMIO_TK1_BASE | 0x04) as *const u32;
/// `TK1_VERSION` is the address for the app version.
pub const TK1_VERSION: *const u32 = (MMIO_TK1_BASE | 0x08) as *const u32;

pub const TK1_SWITCH_APP: *const u8 = (MMIO_TK1_BASE | 0x20) as *const u8;

/// `TK1_APP_ADDR` the address to the start of the application loaded into TKey.
pub const TK1_APP_ADDR: *const usize = (MMIO_TK1_BASE | 0x30) as *const usize;
/// `TK1_APP_SIZE` the size of the application loaded into TKey.
pub const TK1_APP_SIZE: *const usize = (MMIO_TK1_BASE | 0x34) as *const usize;

/// `TK1_BLAKE2S_ADDR` provides the address to the `blake2s` function in TKey firmware.
pub const TK1_BLAKE2S_ADDR: *const usize = (MMIO_TK1_BASE | 0x40) as *const usize;

/// `TK1_CDI` provides access to the (application-specific) CDI value. (32 bytes, contiguous)
pub const TK1_CDI: *const u8 = (MMIO_TK1_BASE | 0x80) as *const u8;

#[derive(Debug, PartialEq, Eq, PartialOrd, Ord)]
pub enum Error {
    /// `InvalidInput` indicates that execution failed due to bad input arguments into the function.
    InvalidInput,
    /// `ProtocolViolation` indicates an error that is rooted in failing to follow the established
    /// protocol.
    ProtocolViolation(&'static str),
    /// `Underrun` represents a (buffer) underrun, i.e. no more data is available.
    Underrun,
    /// `Timeout` represents a reached deadline, i.e. the allocated time has passed.
    Timeout,
}

/// `io` module contains basic input/output operations.
pub mod io {
    use core::ptr;

    use crate::{timer, Error};

    const MMIO_UART_BASE: usize = crate::MMIO_BASE | 0x0300_0000;
    pub const UART_BITRATE: *mut u16 = (MMIO_UART_BASE | 0x40) as *mut u16;
    pub const UART_DATA_BITS: *mut u8 = (MMIO_UART_BASE | 0x44) as *mut u8;
    pub const UART_STOP_BITS: *mut u8 = (MMIO_UART_BASE | 0x48) as *mut u8;
    pub const UART_RX_STATUS: *const u8 = (MMIO_UART_BASE | 0x80) as *const u8;
    pub const UART_RX_DATA: *const u8 = (MMIO_UART_BASE | 0x84) as *const u8;
    pub const UART_RX_BYTES: *const u32 = (MMIO_UART_BASE | 0x88) as *const u32;
    pub const UART_TX_STATUS: *const u8 = (MMIO_UART_BASE | 0x100) as *const u8;
    pub const UART_TX_DATA: *mut u8 = (MMIO_UART_BASE | 0x104) as *mut u8;

    /// `configuration` returns the current I/O configuration as triple (`bitrate`, `data_bits`,
    /// `stop_bits`).
    ///
    /// Note that `bitrate` here represents the value that, when dividing `TK1_CPU_FREQUENCY`,
    /// produces the intended communication bitrate in bps.
    pub fn configuration() -> (u16, u8, u8) {
        (
            unsafe { ptr::read_volatile(UART_BITRATE) },
            unsafe { ptr::read_volatile(UART_DATA_BITS) },
            unsafe { ptr::read_volatile(UART_STOP_BITS) },
        )
    }

    /// Configure UART I/O communication.
    ///
    /// - `bitrate`: a value that cleanly divides `TK1_CPU_FREQUENCY`, default: 288 (62,500 bps)
    /// - `data_bits`: a value in range 0-16 (excl.), default: 8.
    /// - `stop_bits`: a value in range 0-4 (excl.), default: 1.
    ///
    /// # Panics
    /// - In case illegal value is provided for any parameter.
    pub fn configure(bitrate: u16, data_bits: u8, stop_bits: u8) {
        assert_eq!(0, crate::TK1_CPU_FREQUENCY % u32::from(bitrate));
        assert!(data_bits < 16);
        assert!(stop_bits < 4);
        unsafe {
            ptr::write_volatile(UART_BITRATE, bitrate);
            ptr::write_volatile(UART_DATA_BITS, data_bits);
            ptr::write_volatile(UART_STOP_BITS, stop_bits);
        }
    }

    /// `available` reports the number of bytes available in buffer ready to be read.
    #[must_use]
    pub fn available() -> usize {
        unsafe { ptr::read_volatile(UART_RX_BYTES) as usize }
    }

    /// `wait` blocks (actively checking status) until new bytes arrive to be read.
    pub fn wait() {
        while unsafe { ptr::read_volatile(UART_RX_STATUS) } == 0 {}
    }

    /// `read_u8` reads a single byte.
    #[must_use]
    pub fn read_u8() -> u8 {
        loop {
            unsafe {
                if ptr::read_volatile(UART_RX_STATUS) != 0 {
                    return ptr::read_volatile(UART_RX_DATA);
                }
            }
        }
    }

    /// `read_into` reads bytes with length of the slice into the provided slice.
    pub fn read_into(buffer: &mut [u8]) {
        for cell in buffer.iter_mut() {
            *cell = read_u8();
        }
    }

    /// `read_available` reads data that is currently available in receive-buffer into `buffer`,
    /// up until receive-buffer is empty or `buffer` is filled.
    /// Returns number of bytes read, possibly 0 if no bytes are available in the buffer.
    pub fn read_available(buffer: &mut [u8]) -> usize {
        let n = available();
        if n == 0 {
            return 0;
        }
        let n = n.min(buffer.len());
        read_into(&mut buffer[0..n]);
        n
    }

    /// `read_into_checked` reads to fill provided `buffer` iff sufficient data is available in
    /// receive-buffer.
    ///
    /// # Errors
    /// `Error::Underrun` in case availability of data in receive-buffer is short.
    pub fn read_into_checked(buffer: &mut [u8]) -> Result<(), Error> {
        if buffer.len() > available() {
            return Err(Error::Underrun);
        }
        read_into(buffer);
        Ok(())
    }

    /// `read_into_timed` receives data into `buffer` until buffer is filled or `timeout` is
    /// reached. `timeout` is a timeout in milliseconds.
    ///
    /// Note: this function uses the timer, so the timer must not be in use.
    ///
    /// # Errors
    /// In case of timeout before buffer is filled.
    ///
    /// # Panics
    /// In case timer is already running.
    pub fn read_into_timed(buffer: &mut [u8], timeout: u32) -> Result<(), Error> {
        assert!(!timer::running());
        timer::set_prescaler(timer::PRESCALE_MILLISECONDS);
        timer::initialize(timeout);
        timer::start();
        let mut i = 0usize;
        while timer::running() {
            // Read many bytes if available, so we read the maximum amount in case of looming
            // deadline (`timeout`). (As opposed to looping after reading a single byte.)
            i += read_available(&mut buffer[i..]);
            if i == buffer.len() {
                timer::stop();
                return Ok(());
            }
        }
        Err(Error::Timeout)
    }

    /// `read_into_restricted` will attempt to read data from receive-buffer. The read amount is
    /// either a full buffer, or whatever was available at that time. The maximum amount of time
    /// spent on receiving data is limited by `cycles` number of iterations.
    ///
    /// Returns number of bytes read, from 0 to `buffer.len()`.
    pub fn read_into_limited(buffer: &mut [u8], cycles: u32) -> usize {
        let mut n = 0usize;
        for _ in 0..cycles {
            n += read_available(&mut buffer[n..]);
            if n == buffer.len() {
                break;
            }
        }
        n
    }

    /// `read` reads N bytes.
    #[must_use]
    pub fn read<const N: usize>() -> [u8; N] {
        let mut buffer = [0u8; N];
        read_into(&mut buffer);
        buffer
    }

    /// `read_checked` reads `N` bytes after checking for availability in the current reception
    /// buffer.
    ///
    /// # Errors
    /// `Error::Underrun` in case availability of data in receive-buffer is short.
    pub fn read_checked<const N: usize>() -> Result<[u8; N], Error> {
        if N > available() {
            return Err(Error::Underrun);
        }
        Ok(read())
    }

    /// `read_timed` reads `N` bytes or until `timeout` (milliseconds) is reached.
    ///
    /// # Errors
    /// In case timeout is reached.
    pub fn read_timed<const N: usize>(timeout: u32) -> Result<[u8; N], Error> {
        let mut buffer = [0u8; N];
        read_into_timed(&mut buffer, timeout)?;
        Ok(buffer)
    }

    /// `write_u8` writes a single byte.
    pub fn write_u8(b: u8) {
        loop {
            unsafe {
                if ptr::read_volatile(UART_TX_STATUS) != 0 {
                    ptr::write_volatile(UART_TX_DATA, b);
                    return;
                }
            }
        }
    }

    /// `write` writes provided data.
    pub fn write(data: &[u8]) {
        for b in data {
            write_u8(*b);
        }
    }
}

/// `frame` module contains logic for constructing frames (header and payload) according to the
/// specified protocol.
pub mod frame {
    use crate::{io, Error};

    pub const LENGTH_MAX: usize = 128;

    /// `Endpoint` indicates the intended endpoint for a frame, as indicated in the header-byte.
    #[derive(Clone, Copy)]
    pub enum Endpoint {
        Firmware = 2,
        Software = 3,
    }

    /// `CommandLength` represents the command-length class.
    #[derive(Clone, Copy)]
    pub enum CommandLength {
        Length1 = 0,
        Length4 = 1,
        Length32 = 2,
        Length128 = 3,
    }

    /// `command_length` convertes command length indicator to a value.
    #[must_use]
    pub fn command_length(length: CommandLength) -> usize {
        match length {
            CommandLength::Length1 => 1,
            CommandLength::Length4 => 4,
            CommandLength::Length32 => 32,
            CommandLength::Length128 => 128,
        }
    }

    /// `create_headerbyte` creates a header-byte from individual values.
    #[must_use]
    pub fn create_headerbyte(id: u8, endpoint: Endpoint, status: u8, length: CommandLength) -> u8 {
        (id & 0b0000_0011) << 5 | (endpoint as u8) << 3 | (status & 0b0000_0001) << 2 | length as u8
    }

    /// `encode_header` encodes a header into a byte.
    #[must_use]
    pub fn encode_header(header: &Header) -> u8 {
        create_headerbyte(
            header.id,
            header.endpoint,
            u8::from(header.error),
            header.length,
        )
    }

    /// `Header` is the first byte of a frame, which contains an id, endpoint, status-bit (unused in
    /// requests, indicates error in responses), length (one of predefined request/response lengths).
    #[derive(Clone, Copy)]
    pub struct Header {
        /// `id` represents an 2-bit identifier to allow distinguishing several interweaved
        /// communication streams.
        pub id: u8,
        /// `endpoint` indicates whether the frame is intended for the firmware or the loaded
        /// application. The firmware or loaded application can then reject the frame early if addressed
        /// incorrectly.
        pub endpoint: Endpoint,
        /// `error`, `false` indicates a good result, or `true` to signal bad result (and consequently
        /// no frame-body).
        pub error: bool,
        /// `length` indicator for one of 4 variants of frame-length: 1, 4, 32 or 128 bytes.
        pub length: CommandLength,
    }

    /// `parse_into` parses the header-byte to reconstruct the header.
    ///
    /// # Errors
    /// In case of protocol violations or otherwise illegal values.
    ///
    /// # Panics
    /// In case of impossible situation, most likely indicating a bug.
    pub fn parse_into(dst: &mut Header, headerbyte: u8) -> Result<(), Error> {
        if headerbyte & 0b1000_0000 != 0 {
            return Err(Error::ProtocolViolation(
                "illegal value for reserved bit (protocol version)",
            ));
        }
        if headerbyte & 0b0000_0100 != 0 {
            return Err(Error::ProtocolViolation(
                "illegal value for unused bit (response status)",
            ));
        }
        dst.id = (headerbyte & 0b0110_0000) >> 5;
        dst.endpoint = match (headerbyte & 0b0001_1000) >> 3 {
            0 | 1 => return Err(Error::ProtocolViolation("illegal value for endpoint")),
            2 => Endpoint::Firmware,
            3 => Endpoint::Software,
            _ => panic!("BUG: impossible value for id in frame-byte"),
        };
        dst.error = false;
        dst.length = match headerbyte & 0b0000_0011 {
            0 => CommandLength::Length1,
            1 => CommandLength::Length4,
            2 => CommandLength::Length32,
            3 => CommandLength::Length128,
            _ => panic!("BUG: impossible value for command length in frame-byte"),
        };
        Ok(())
    }

    /// `parse` parses the header-byte of the frame.
    ///
    /// # Errors
    /// In case of protocol violation or otherwise illegal value.
    pub fn parse(headerbyte: u8) -> Result<Header, Error> {
        let mut header = Header {
            id: 0,
            endpoint: Endpoint::Firmware,
            error: false,
            length: CommandLength::Length1,
        };
        parse_into(&mut header, headerbyte)?;
        Ok(header)
    }

    /// `read_into` reads a complete frame into header and buffer.
    ///
    /// # Errors
    /// In case of protocol violation or otherwise illegal value in the header-byte.
    pub fn read_into(header: &mut Header, buffer: &mut [u8; LENGTH_MAX]) -> Result<(), Error> {
        let headerbyte = io::read_u8();
        parse_into(header, headerbyte)?;
        let length = command_length(header.length);
        io::read_into(&mut buffer[..length]);
        Ok(())
    }

    /// `write` writes a frame, both header and payload. Only as many bytes of payload are written,
    /// as is specified by the length in the header, so `1`, `4`, `32` or `128` bytes. A larger
    /// buffer may be provided, but will not be written fully.
    ///
    /// # Panics
    /// Panics if provided data-buffer is smaller than length specified in the provided header.
    pub fn write(header: &Header, data: &[u8]) {
        let length = command_length(header.length);
        assert!(data.len() >= length);
        io::write_u8(encode_header(header));
        io::write(&data[..length]);
    }
}

/// `gpio` provides only the constants for addressing the appropriate memory region. The GPIO pins
/// are not exposed in the ready-sold TKeys, so they are only of benefit for the unlocked versions.
pub mod gpio {
    use crate::MMIO_TK1_BASE;

    pub const TK1_GPIO: *mut u8 = (MMIO_TK1_BASE | 0x28) as *mut u8;
    pub const TK1_GPIO_BIT_1: u8 = 0;
    pub const TK1_GPIO_BIT_2: u8 = 1;
    pub const TK1_GPIO_BIT_3: u8 = 2;
    pub const TK1_GPIO_BIT_4: u8 = 3;
}

/// `trng` is the module for the true-RNG. Note that this RNG is not guaranteed cryptographically-
/// secure and it is recommended to mix the entropy from the TRNG with cryptographically-suitable
/// mechanisms.
///
/// Entropy is produced at a rate of approximately 66.6 times per second.
pub mod trng {
    use core::ptr;

    use crate::MMIO_TRNG_BASE;

    /// `TRNG_STATUS` the address that hosts the bit indicating whether the entropy-source is ready.
    pub const TRNG_STATUS: *const u8 = (MMIO_TRNG_BASE | 0x24) as *const u8;
    /// `TRNG_BIT_READY` is the bit (index) that hosts the ready-indicator.
    pub const TRNG_BIT_READY: u8 = 0;
    /// `TRNG_FLAG_READY` is the mask value for selecting specifically the 'ready'-bit.
    pub const TRNG_FLAG_READY: u8 = 1 << TRNG_BIT_READY;
    /// `TRNG_ENTROPY` is the address for the TRNG entropy-source.
    pub const TRNG_ENTROPY: *const u32 = (MMIO_TRNG_BASE | 0x80) as *const u32;

    /// `ready` returns true iff new entropy is available.
    #[must_use]
    pub fn ready() -> bool {
        unsafe { ptr::read_volatile(TRNG_STATUS) & TRNG_FLAG_READY != 0 }
    }

    /// `wait` waits for the entropy source to become ready. (blocking)
    ///
    /// Entropy is produced at a rate of approximately 66.6 times per second.
    pub fn wait() {
        while !ready() {}
    }

    /// `read` reads data from the TRNG entropy location, regardless of whether new entropy is
    /// available. (Check `ready` to check availability.)
    #[must_use]
    pub fn read() -> u32 {
        unsafe { ptr::read_volatile(TRNG_ENTROPY) }
    }

    /// `read_next` waits for the TRNG to become ready then reads the available entropy from the
    /// entropy source.
    ///
    /// Entropy is produced at a rate of approximately 66.6 times per second.
    #[must_use]
    pub fn read_next() -> u32 {
        wait();
        read()
    }

    /// `read_bytes` reads data, as 4 bytes, from the entropy source, regardless of whether new
    /// entropy is available. (Check `ready` for availability.)
    #[allow(clippy::cast_possible_truncation)]
    #[must_use]
    pub fn read_bytes() -> [u8; 4] {
        let v = read();
        [v as u8, (v >> 8) as u8, (v >> 16) as u8, (v >> 24) as u8]
    }

    /// `read_bytes_next` waits for the TRNG to become ready then reads the available entropy from
    /// the entropy source.
    ///
    /// Entropy is produced at a rate of approximately 66.6 times per second.
    #[must_use]
    pub fn read_bytes_next() -> [u8; 4] {
        wait();
        read_bytes()
    }

    /// `gather` reads entropy from the TRNG as it becomes ready and fills the provided buffer,
    /// blocking as it waits for new entropy to become available. The TRNG rate of production is
    /// about 66.6 times per second. This function should be used sparingly, if at all.
    ///
    /// Note: `gather` should not be used as a cryptographically-secure random-bytes generator. See
    /// `rustkey::random`.
    pub fn gather(buffer: &mut [u8]) {
        for i in (0..buffer.len()).step_by(4) {
            unsafe {
                // loop until new entropy is available
                while ptr::read_volatile(TRNG_STATUS) & TRNG_FLAG_READY == 0 {}
                ptr::copy_nonoverlapping(
                    TRNG_ENTROPY.cast::<u8>(),
                    buffer[i..].as_mut_ptr(),
                    4.min(buffer.len() - i),
                );
            }
        }
    }
}

/// `led` module controls the LED on the TKey.
pub mod led {
    use core::ptr;

    use crate::{sleep, MMIO_TK1_BASE};

    /// `TK1_LED` is the address for controlling the LED.
    pub const TK1_LED: *mut u8 = (MMIO_TK1_BASE | 0x24) as *mut u8;
    /// `TK1_LED_BIT_RED` is the bit (index) that controls the red led.
    pub const TK1_LED_BIT_RED: u8 = 2;
    /// `TK1_LED_BIT_GREEN` is the bit (index) that controls the green led.
    pub const TK1_LED_BIT_GREEN: u8 = 1;
    /// `TK1_LED_BIT_BLUE` is the bit (index) that controls the blue led.
    pub const TK1_LED_BIT_BLUE: u8 = 0;

    pub const LED_OFF: u8 = 0;
    pub const LED_BLUE: u8 = 1 << TK1_LED_BIT_BLUE;
    pub const LED_GREEN: u8 = 1 << TK1_LED_BIT_GREEN;
    pub const LED_RED: u8 = 1 << TK1_LED_BIT_RED;
    pub const LED_YELLOW: u8 = LED_RED | LED_GREEN;
    pub const LED_PURPLE: u8 = LED_RED | LED_BLUE;
    pub const LED_CYAN: u8 = LED_GREEN | LED_BLUE;
    pub const LED_WHITE: u8 = LED_RED | LED_GREEN | LED_BLUE;

    /// `get` gets the current LED value.
    pub fn get() -> u8 {
        unsafe { ptr::read_volatile(TK1_LED) & 0x7 }
    }

    /// `set` sets the LED value.
    pub fn set(color: u8) {
        unsafe { ptr::write_volatile(TK1_LED, color & 0x7) }
    }

    /// `change` sets the LED to a new color and returns the previous color.
    #[must_use]
    pub fn change(color: u8) -> u8 {
        let prev = get();
        set(color);
        prev
    }

    /// `signal` performs `count` flashes uniformly between two LED-colors: `color1` and `color2`.
    /// Afterwards, the previous LED color is restored. Blinking the LED with alternating colors,
    /// is a simple but effective way to signal a user that is physically near the TKey device.
    pub fn signal(count: usize, color1: u8, color2: u8) {
        let restore = get();
        for _ in 0..count {
            set(color1);
            sleep(75000);
            set(color2);
            sleep(75000);
        }
        set(restore);
    }
}

/// `touch` represents the touch-sensor of the TKey.
pub mod touch {
    use core::ptr;

    use crate::{led, sleep, MMIO_TOUCH_BASE};

    pub const TOUCH_STATUS: *mut u8 = (MMIO_TOUCH_BASE | 0x24) as *mut u8;
    pub const TOUCH_STATUS_BIT_EVENT: u8 = 0;
    pub const TOUCH_STATUS_FLAG_EVENT: u8 = 1 << TOUCH_STATUS_BIT_EVENT;

    /// `reset` reset any previous touch-events.
    pub fn reset() {
        unsafe { ptr::write_volatile(TOUCH_STATUS, 0) };
    }

    /// `touched` returns true iff sensor registered a touch-event. (Use `reset` to clear a possible
    /// previous touch-event.)
    pub fn touched() -> bool {
        unsafe { ptr::read_volatile(TOUCH_STATUS) & TOUCH_STATUS_FLAG_EVENT != 0 }
    }

    /// `request` touch confirmation by initiating a (finite) loop that blinks the led and checks
    /// the touch-sensor for confirmation. The current led-color will be restored after use.
    ///
    /// Returns true iff sensor is touched within the request-period, or false if no touch was
    /// registered within this period.
    #[must_use]
    pub fn request(count: u16, color: u8) -> bool {
        let restore = led::get();
        reset();
        for i in 0..usize::from(count) * 4 {
            led::set(if i % 2 == 0 { led::LED_OFF } else { color });
            if touched() {
                led::set(restore);
                return true;
            }
            sleep(if i % 4 == 0 { 200_000 } else { 100_000 });
        }
        led::set(restore);
        false
    }
}

/// `timer` module provides access to the device's countdown-timer.
///
/// The timer counts down from the `initial` value and the resolution is scaled using the
/// `prescaler`. With a `prescaler` value of `0`, every clock-cycle is a timer-tick. For a timer
/// that ticks every second, set the `prescaler` to `18_000_000` and then `initialize` the timer
/// with however many seconds count-down is needed.
///
/// Note: these functions require knowledge of the current state of the timer (running/stopped),
/// because both initial timer value and prescaler can be modified, which completely alters the
/// interpretation of timer values, therefore it is critical to be aware of the current
/// configuration.
pub mod timer {
    use core::ptr;

    use crate::{MMIO_TIMER_BASE, TK1_CPU_FREQUENCY};

    pub const TIMER_CTRL: *mut u32 = (MMIO_TIMER_BASE | 0x20) as *mut u32;
    pub const TIMER_CTRL_BIT_START: u32 = 0;
    pub const TIMER_CTRL_FLAG_START: u32 = 1 << TIMER_CTRL_BIT_START;
    pub const TIMER_CTRL_BIT_STOP: u32 = 1;
    pub const TIMER_CTRL_FLAG_STOP: u32 = 1 << TIMER_CTRL_BIT_STOP;
    pub const TIMER_STATUS: *const u32 = (MMIO_TIMER_BASE | 0x24) as *mut u32;
    pub const TIMER_STATUS_BIT_RUNNING: u32 = 0;
    pub const TIMER_STATUS_FLAG_RUNNING: u32 = 1 << TIMER_STATUS_BIT_RUNNING;
    pub const TIMER_PRESCALER: *mut u32 = (MMIO_TIMER_BASE | 0x28) as *mut u32;
    pub const TIMER_TIMER: *mut u32 = (MMIO_TIMER_BASE | 0x2c) as *mut u32;

    /// `PRESCALE_SECONDS` is the prescaler value that results in 1-second timer-ticks. (Given an
    /// 18 MHz processor, a second is about 18,000,000 cycles.)
    pub const PRESCALE_SECONDS: u32 = TK1_CPU_FREQUENCY;
    /// `PRESCALE_MILLISECONDS` is the prescaler value that results in 0.001-second timer-ticks.
    /// (Given an 18 MHz processor, a millisecond is about 18,000 cycles.)
    pub const PRESCALE_MILLISECONDS: u32 = TK1_CPU_FREQUENCY / 1000;

    /// `running()` indicates the current status of the timer: false if stopped, true if running.
    #[must_use]
    pub fn running() -> bool {
        unsafe { ptr::read_volatile(TIMER_STATUS) & TIMER_STATUS_FLAG_RUNNING != 0 }
    }

    /// `set_prescaler` sets the prescaler. A value is `18_000_000`, i.e. gives one tick per
    /// second given that the processor operates at 18 MHz. The prescaler can be used to scale the
    /// timer from very high frequencies (microseconds) with low or zero prescaler, to low
    /// frequencies (seconds) with high prescaler.
    ///
    /// # Panics
    /// Panics if timer is already running.
    pub fn set_prescaler(prescaler: u32) {
        assert!(!running());
        unsafe { ptr::write_volatile(TIMER_PRESCALER, prescaler) }
    }

    /// `initialize` sets the initial timer value. Only allowed if timer is not running.
    ///
    /// # Panics
    /// Panics if timer is already running.
    pub fn initialize(initial: u32) {
        assert!(!running());
        unsafe { ptr::write_volatile(TIMER_TIMER, initial) }
    }

    /// `current` gets the initial timer value if stopped, or the current timer value if running.
    pub fn current() -> u32 {
        unsafe { ptr::read_volatile(TIMER_TIMER) }
    }

    /// `start` starts the timer if stopped.
    ///
    /// Note: upon timer completion (counted down to `1`), the timer value resets to its initial
    /// value.
    ///
    /// Repeat calls of `start()` have no effect.
    pub fn start() {
        unsafe { ptr::write_volatile(TIMER_CTRL, TIMER_CTRL_FLAG_START) }
    }

    /// `stop` stops the timer if started.
    ///
    /// Note: upon stopping the timer, the timer value is reset to its initial value.
    ///
    /// Repeat calls of `stop()` have no effect.
    pub fn stop() {
        unsafe { ptr::write_volatile(TIMER_CTRL, TIMER_CTRL_FLAG_STOP) }
    }

    /// `wait` waits until the timer has stopped.
    pub fn wait() {
        while running() {}
    }

    /// `wait_until` waits until the timer count-down reaches or has passed the specified value.
    /// The timer must be running.
    ///
    /// # Panics
    /// Panics if timer is not running.
    pub fn wait_until(value: u32) {
        assert!(running());
        while current() > value {}
    }

    /// `wait_for` waits for a specified number of ticks of the timer to pass.
    /// The timer must be running.
    ///
    /// # Panics
    /// Panics if the timer is not running.
    pub fn wait_for(ticks: u32) {
        wait_until(current() - ticks);
    }

    /// `sleep` use timer to perform a timed sleep in amount of seconds. (Blocking until timer
    /// expires.)
    ///
    /// This function is a utility that (re)configures the prescaler for seconds, then initiates a
    /// timer with the specified number of seconds. The timer must be available.
    ///
    /// # Panics
    /// If called when timer is already running.
    pub fn sleep(seconds: u32) {
        assert!(!running());
        set_prescaler(PRESCALE_SECONDS);
        initialize(seconds);
        start();
        wait();
    }
}

/// `cpumonitor` module provides access to the CPU execution monitor.
pub mod cpumonitor {
    use core::ptr;

    use crate::MMIO_TK1_BASE;

    pub const TK1_CPU_MONITOR_CTRL: *mut u32 = (MMIO_TK1_BASE | 0x180) as *mut u32;
    pub const TK1_CPU_MONITOR_FIRST: *mut usize = (MMIO_TK1_BASE | 0x184) as *mut usize;
    pub const TK1_CPU_MONITOR_LAST: *mut usize = (MMIO_TK1_BASE | 0x188) as *mut usize;

    /// `monitor_range` initializes the CPU execution monitor to the specified address range.
    /// - `first`: the first (start) address for the range.
    /// - `last`: the last address (_inclusive_) for the range.
    ///
    /// Note: only one CPU execution monitor can be set, and once set cannot be disabled.
    ///
    /// According to the developer guide, the application is loaded at the start of RAM, so
    /// `RAM_BASE == *TK1_APP_ADDR`. Therefore, setting up the CPU execution monitor for start of
    /// RAM, will always immediately result in cpu abort being triggered. So it seems the earliest
    /// starting point is at `*TK1_APP_ADDR + *TK1_APP_SIZE`, and last address
    /// `RAM_BASE + RAM_SIZE - 4`. That is, if we set the monitor for the extent of available
    /// application RAM.
    ///
    /// To see CPU execution monitor in action, set the monitoring range to a range that includes
    /// application memory (`[*TK1_APP_ADDR, *TK1_APP_ADDR+*TK1_APP_SIZE]`) and have it trigger
    /// immediately. (This is obviously useless in practice, but does trigger the execution
    /// monitor.)
    ///
    /// # Panics
    /// - In case of incorrect input arguments, such as `first` > `last`.
    /// - In case CPU execution monitor is set up more than once.
    pub fn monitor_range(first: usize, last: usize) {
        static mut AVAILABLE: bool = true;
        assert!(first <= last);
        unsafe {
            assert!(AVAILABLE);
            ptr::write_volatile(TK1_CPU_MONITOR_FIRST, first);
            ptr::write_volatile(TK1_CPU_MONITOR_LAST, last);
            ptr::write_volatile(TK1_CPU_MONITOR_CTRL, 1);
            AVAILABLE = false;
        }
    }

    /// `monitor_application_memory` sets up the CPU execution monitor to monitor all RAM memory
    /// past the application binary code. Therefore, all memory available to the application is
    /// monitored, regardless of how this memory is used.
    ///
    /// Note: only one CPU execution monitor can be set, and once set cannot be disabled.
    ///
    /// # Panics
    /// - In case CPU execution monitor is set up more than once.
    pub fn monitor_application_memory() {
        monitor_range(
            unsafe { *crate::TK1_APP_ADDR + *crate::TK1_APP_SIZE },
            crate::RAM_BASE + crate::RAM_SIZE - 1,
        );
    }
}

/// `read_name_version` reads the name addresses and the version address.
#[must_use]
pub fn read_name_version() -> ([u8; 4], [u8; 4], u32) {
    let mut name0 = [0u8; 4];
    let mut name1 = [0u8; 4];
    let version: u32;
    unsafe {
        ptr::copy_nonoverlapping(TK1_NAME0.cast::<u8>(), name0.as_mut_ptr(), 4);
        ptr::copy_nonoverlapping(TK1_NAME1.cast::<u8>(), name1.as_mut_ptr(), 4);
        version = ptr::read_volatile(TK1_VERSION);
    }
    (name0, name1, version)
}

/// `read_cdi` reads the compound device identifier (CDI).
// TODO track <https://github.com/tillitis/tillitis-key1/pull/204> for disabling access to CDI.
#[must_use]
pub fn read_cdi() -> [u8; 32] {
    let mut cdi = [0u8; 32];
    unsafe {
        ptr::copy_nonoverlapping(TK1_CDI, cdi.as_mut_ptr(), 32);
    }
    cdi
}

#[repr(C)]
#[derive(Copy, Clone)]
struct Blake2sContext {
    pub b: [u8; 64],
    pub h: [u32; 8],
    pub t: [u32; 2],
    pub c: usize,
    pub outlen: usize,
}

/// `blake2s` performs a Blake2s hash calculation with immediate result.
/// - `N`: size of resulting digest, must be larger than 0 and at most 32 bytes.
/// - `key`: an optional key (for purpose of keyed-hash) of at most 32 bytes.
/// - `content`: the content of which to produce the digest, of any length.
///
/// Returns the resulting digest, an array of size `N`.
///
/// `blake2s` does not expose the used context-struct. Given that stack-allocation takes minimal
/// overhead and firmware's `blake2s` function is self-contained, the provided context is always
/// (re)initialized and in the end finalized.
///
/// # Errors
/// In case of bad input arguments.
///
/// # Panics
/// In case of incorrect use, such as N too big, key length too big, etc.
#[cfg(feature = "blake2-firmware")]
pub fn blake2s(out: &mut [u8], key: &[u8], content: &[u8]) -> Result<(), Error> {
    if out.is_empty() || out.len() > 32 || key.len() > 32 {
        return Err(Error::InvalidInput);
    }
    let mut ctx = Blake2sContext {
        b: [0; 64],
        h: [0; 8],
        t: [0; 2],
        c: 0,
        outlen: 0,
    };
    unsafe {
        let blake2s_fw: unsafe extern "C" fn(
            out: *mut u8,
            outlen: usize,
            key: *const u8,
            keylen: usize,
            content: *const u8,
            contentlen: usize,
            ctx: *mut Blake2sContext,
        ) -> i32 = core::mem::transmute(*TK1_BLAKE2S_ADDR);
        let ret = blake2s_fw(
            out.as_mut_ptr(),
            out.len(),
            key.as_ptr(),
            key.len(),
            content.as_ptr(),
            content.len(),
            &mut ctx,
        );
        // `ret != 0` should be impossible given that we verify arguments before calling blake2s.
        // However, do not let it pass unchecked. Now we at least have a way to detect unexpected
        // incorrect use of the firmware's blake2s function.
        assert_eq!(0, ret);
    }
    Ok(())
}

/// Blake2s from stand-alone implementation.
///
/// # Errors
/// In case of incorrect input arguments.
///
/// # Panics
/// In case of incorrect input.
#[cfg(all(not(feature = "blake2-firmware"), feature = "blake2-standalone"))]
pub fn blake2s(out: &mut [u8], key: &[u8], content: &[u8]) -> Result<(), Error> {
    blake2s::blake2s(out, key, content).map_err(|e| match e {
        blake2s::Error::InvalidInput => Error::InvalidInput,
    })
}

/// _EXPERIMENTAL!_ `hash_firmware_rom` computes the Blake2s hash-value of the TKey firmware in ROM.
/// The ROM is monitored for execution once the program-binary is loaded to prevent malicious
/// activity, but it is still readable. A checksum of the firmware may be useful to determine what
/// exact firmware is running on the device. Especially if (minor) changes are made to the
/// (memory-mapped) API.
///
/// `key` must be at most 32 bytes. (see requirements of `blake2s`)
///
/// # Errors
/// In case of invalid input, e.g. key.
#[must_use = "Firmware ROM digest stored in the return value."]
pub fn hash_firmware_rom(key: &[u8]) -> Result<[u8; 32], Error> {
    let mut out = [0u8; 32];
    blake2s(&mut out, key, unsafe {
        core::slice::from_raw_parts(ROM_BASE as *const u8, ROM_SIZE)
    })?;
    Ok(out)
}

/// `random` produces (reasonably) cryptographically-secure (needs to be verified/proved) random
/// bytes, using the TRNG, Blake2s and optionally seed data. If strong randomness is needed from
/// very first use, it is recommended to contribute some `seed`-entropy to get the buffer mixed up
/// faster.
///
/// `seed` input is processed in 32-byte chunks, provided as keyed input, to be mixed in with
/// buffer. (So, for example, providing the in-memory application bytes will do more than simply
/// calculate the hash-digest of that input.)
///
/// Note: `random` isn't free. Use `bench.rs` program for querying random for testing the production
/// rate or evaluating the quality of the output.
///
/// The exact implementation is not fixed, but currently uses an internal buffer to maintain some
/// buffered random data to be mixed in with other sources of entropy and seed data.
///
/// # Panics
/// In case of bugs. (Should not panic.)
// TODO provide function for some initial seeding of random? (E.g. use firmware-ROM checksum, CDI derivations, etc. to mix up some unpredictable initial buffer.)
// TODO currently ignoring `static_mut_refs`.
#[allow(static_mut_refs)]
pub fn random(out: &mut [u8], seed: &[u8]) {
    static mut BUFFER: [u8; 32] = [0u8; 32];
    for i in (0..seed.len()).step_by(32) {
        unsafe {
            blake2s(
                &mut BUFFER,
                &seed[i..32.min(seed.len() - i)],
                &*ptr::addr_of_mut!(BUFFER),
            )
            .unwrap();
        };
    }
    if out.is_empty() {
        // Allow seeding the buffer without taking any output randomness.
        return;
    }
    // Assumption: don't wait for entropy status for initial randomness for key. Instead, assume
    // that there is some randomness present. This is only for initialization.
    let mut key: [u8; 4] = trng::read_bytes();
    for i in (0..out.len()).step_by(32) {
        // TRNG has low rate for entropy production, so until true-randomness is available, reuse
        // known entropy in unpredictable way.
        if trng::ready() {
            // TODO this ready-case won't be touched very often, because we start out reading from the TRNG. We should probably approach this in a different way.
            key = trng::read_bytes();
        } else {
            key[0] ^= unsafe { BUFFER[key[0] as usize % BUFFER.len()] };
            key[1] ^= unsafe { BUFFER[key[1] as usize % BUFFER.len()] };
            key[2] ^= unsafe { BUFFER[key[2] as usize % BUFFER.len()] };
            key[3] ^= unsafe { BUFFER[key[3] as usize % BUFFER.len()] };
        }
        // TODO using the key for randomness, means that only 4 bytes contribute to the unpredictable next bytes. Can we make it a bit more unpredictable?
        unsafe {
            blake2s(&mut BUFFER, &key, &*ptr::addr_of_mut!(BUFFER)).unwrap();
        };
        let size = 32.min(out.len() - i);
        // TODO should we blake2s-hash the buffer to produce output-randomness? (Avoids reconstructing internal state, even if this state is still changed before next use.)
        out[i..i + size].copy_from_slice(unsafe { &BUFFER[..size] });
    }
    unsafe {
        blake2s(
            &mut BUFFER,
            "ByeByeOutputBytes".as_bytes(),
            &*ptr::addr_of_mut!(BUFFER),
        )
        .unwrap();
    };
}

/// `sleep` for specified number of cycles (delay by virtue of volatile writes).
pub fn sleep(n: usize) {
    let mut i = 0usize;
    while i < n {
        unsafe { ptr::write_volatile(&mut i, i + 1) };
    }
}

/// `done` enters an infinite loop, effectively halting execution.
#[allow(clippy::empty_loop)]
pub fn done() -> ! {
    loop {}
}

/// `abort` enters infinite loop, effectively aborting execution, with blinking red LED.
/// It uses 400,000 cycles for sleeps, therefore flashes at about twice as rapid as CPU halt on
/// illegal instruction.
pub fn abort() -> ! {
    loop {
        led::set(led::LED_RED);
        sleep(400_000);
        led::set(led::LED_OFF);
        sleep(400_000);
    }
}