ternaria_dev/

block.rs

//! A block device backed by host bytes.
//!
//! | Offset | Register | Behaviour |
//! |--------|----------|-----------|
//! | 0..3 | `SECTOR` | Which sector the next load transfers. Word-sized. |
//! | 3 | `CONTROL` | Write 1 to load the selected sector, 2 to store it. |
//! | 4 | `STATUS` | 0 after a successful transfer, -1 if the sector is out of range. |
//! | 5.. | window | The staging buffer, one byte per tryte (D-04). Readable and writable. |
//!
//! The backing bytes come from a host file or an in-memory image. A load past
//! the end of the image zeroes the window and sets `STATUS` to -1.
//!
//! # Writing
//!
//! A store copies the window back to the selected sector. The window holds
//! trytes and the image holds bytes, so every tryte in the window must be in
//! 0..=255; one that is not fails the store with `NotAByte` and leaves the
//! image untouched. The check runs over the whole window before anything is
//! written, so a store either happens completely or not at all.
//!
//! A store to the sector one past the end appends, growing the image by one
//! sector. Anything further out is an error. This is enough for a filesystem
//! to extend a file without needing a separate resize operation, and it stops
//! a stray sector number from inflating the image by a wild amount.

use crate::{Device, SECTOR_SIZE, unmapped};
use ternaria_arith::{Tryte, Word};
use ternaria_mem::{
    MemoryError,
    bytes::{byte_to_tryte, tryte_to_byte},
};

/// Offset of the first tryte of the sector register.
pub const SECTOR: i64 = 0;
/// Offset of the control register.
pub const CONTROL: i64 = 3;
/// Control value that loads the selected sector into the window.
pub const CONTROL_LOAD: i32 = 1;
/// Control value that stores the window to the selected sector.
pub const CONTROL_STORE: i32 = 2;
/// Offset of the status register.
pub const STATUS: i64 = 4;
/// Offset of the first tryte of the sector window.
pub const WINDOW: i64 = 5;

/// A sector-addressed block device.
pub struct BlockDevice {
    image: Vec<u8>,
    sector: i64,
    status: i32,
    window: Vec<Tryte>,
}

impl BlockDevice {
    /// A device backed by the given bytes.
    pub fn new(image: impl Into<Vec<u8>>) -> BlockDevice {
        BlockDevice {
            image: image.into(),
            sector: 0,
            status: 0,
            window: vec![Tryte::ZERO; SECTOR_SIZE as usize],
        }
    }

    /// A device backed by the contents of a host file.
    pub fn from_file(path: impl AsRef<std::path::Path>) -> std::io::Result<BlockDevice> {
        Ok(BlockDevice::new(std::fs::read(path)?))
    }

    /// How many whole or partial sectors the image contains.
    pub fn sector_count(&self) -> i64 {
        self.image.len().div_ceil(SECTOR_SIZE as usize) as i64
    }

    /// Copies the selected sector into the window.
    ///
    /// A short final sector is zero-padded. A sector past the end of the image
    /// leaves the window zeroed and sets `STATUS` to -1.
    fn load(&mut self) {
        self.window.fill(Tryte::ZERO);
        if self.sector < 0 || self.sector >= self.sector_count() {
            self.status = -1;
            return;
        }
        let start = self.sector as usize * SECTOR_SIZE as usize;
        let end = (start + SECTOR_SIZE as usize).min(self.image.len());
        for (i, b) in self.image[start..end].iter().enumerate() {
            self.window[i] = byte_to_tryte(*b);
        }
        self.status = 0;
    }

    /// Copies the window back to the selected sector.
    ///
    /// Every tryte must be a byte. The check runs first, over the whole
    /// window, so a window holding one bad value leaves the image unchanged
    /// rather than half written.
    fn store(&mut self) -> Result<(), MemoryError> {
        if self.sector < 0 || self.sector > self.sector_count() {
            self.status = -1;
            return Ok(());
        }
        let mut bytes = [0u8; SECTOR_SIZE as usize];
        for (slot, t) in bytes.iter_mut().zip(self.window.iter()) {
            *slot = tryte_to_byte(*t).ok_or(MemoryError::NotAByte {
                value: t.value() as i64,
            })?;
        }
        let start = self.sector as usize * SECTOR_SIZE as usize;
        let end = start + SECTOR_SIZE as usize;
        if end > self.image.len() {
            self.image.resize(end, 0);
        }
        self.image[start..end].copy_from_slice(&bytes);
        self.status = 0;
        Ok(())
    }

    /// The backing bytes, for a host writing an image back to a file.
    pub fn image(&self) -> &[u8] {
        &self.image
    }

    /// Replaces one tryte of the sector register, leaving the others alone.
    ///
    /// The register is word-sized, so a program may set it with one `sw` or
    /// one tryte at a time.
    fn set_sector_tryte(&mut self, index: usize, value: Tryte) {
        let current = Word::from_value(self.sector);
        let mut trytes = [Tryte::ZERO; Word::TRYTES];
        for (i, slot) in trytes.iter_mut().enumerate() {
            *slot = current.tryte(i);
        }
        trytes[index] = value;
        self.sector = Word::from_trytes(trytes).value();
    }
}

impl Device for BlockDevice {
    fn name(&self) -> &'static str {
        "block"
    }

    fn read(&mut self, offset: i64) -> Result<Tryte, MemoryError> {
        match offset {
            0..=2 => Ok(Word::from_value(self.sector).tryte(offset as usize)),
            CONTROL => Ok(Tryte::ZERO),
            STATUS => Ok(Tryte::from_value(self.status)),
            _ if (WINDOW..WINDOW + SECTOR_SIZE).contains(&offset) => {
                Ok(self.window[(offset - WINDOW) as usize])
            }
            _ => Err(unmapped(offset)),
        }
    }

    fn write(&mut self, offset: i64, value: Tryte) -> Result<(), MemoryError> {
        match offset {
            0..=2 => {
                self.set_sector_tryte(offset as usize, value);
                Ok(())
            }
            CONTROL => match value.value() {
                CONTROL_LOAD => {
                    self.load();
                    Ok(())
                }
                CONTROL_STORE => self.store(),
                // Any other value is a no-op rather than an error, so that a
                // zero written to clear the register does nothing.
                _ => Ok(()),
            },
            STATUS => Err(MemoryError::Device {
                addr: offset,
                reason: "block status is read-only",
            }),
            _ if (WINDOW..WINDOW + SECTOR_SIZE).contains(&offset) => {
                self.window[(offset - WINDOW) as usize] = value;
                Ok(())
            }
            _ => Err(unmapped(offset)),
        }
    }
}