Add harm runtime

harm-runtime/Cargo.toml

@@ -12,4 +12,13 @@ publish = false
 
 [dependencies]
 harm = { workspace = true }
-memmap2 = "0.9.9"
+memmap2 = { version = "0.9.9", optional = true }
+thiserror = "2.0.18"
+
+[features]
+default = ["memmap2", "alloc"]
+memmap2 = ["dep:memmap2"]
+alloc = []
+
+[dev-dependencies]
+clear-cache = "0.1.3"

harm-runtime/src/builder.rs

@@ -0,0 +1,155 @@
+/* Copyright (C) 2026 Ivan Boldyrev
+ *
+ * This document is licensed under the BSD 3-clause license.
+ */
+
+use std::collections::HashMap;
+
+use harm::reloc::{Addr64, LabelId, Offset64, Rel64, Rel64Error};
+
+#[derive(Debug, thiserror::Error)]
+pub enum BuilderError {
+    #[error("Address overflow: base {0}, offset {1}")]
+    AddressOverflow(u64, usize),
+    #[error("Relocation error: {nested:?} at offset {offset}")]
+    Relocation { nested: Rel64Error, offset: usize },
+    #[error("Undefined label: {0:?}")]
+    UndefinedLabel(LabelId),
+}
+
+/// Do static relocations: recalculate labels and applies relocations, producing memory ready for execution.
+///
+/// Please note that real memory location may be different from base address: it allows to build at some buffer
+/// and then move data to real position later.
+pub struct Builder<'mem> {
+    mem: &'mem mut [u8], // real memory
+    base: Addr64,        // virtual base, on ARM system usually matches with `mem` start
+}
+
+impl<'mem> Builder<'mem> {
+    pub fn new(mem: &'mem mut [u8], base: Addr64) -> Self {
+        Self { mem, base }
+    }
+
+    pub fn build(
+        self,
+        named_labels: impl Iterator<Item = (&'mem str, LabelId)>,
+        labels: impl Iterator<Item = (LabelId, Offset64)>,
+        relocations: impl Iterator<Item = (usize, Rel64)>,
+    ) -> Result<HashMap<String, u64>, BuilderError> {
+        // Recalculate labels.
+        let labels: HashMap<_, _> = labels
+            .map(|(label_id, offset)| {
+                // TODO is it wrapping?
+                let addr = self.base.wrapping_add_signed(offset);
+                (label_id, addr)
+            })
+            .collect();
+
+        // Calculate label addresses.
+        let label_addresses = named_labels
+            .map(|(name, label_id)| {
+                let label_addr = labels
+                    .get(&label_id)
+                    .copied()
+                    .ok_or_else(|| BuilderError::UndefinedLabel(label_id))?;
+                Ok((name.to_owned(), label_addr))
+            })
+            .collect::<Result<_, BuilderError>>()?;
+
+        // Apply relocations to the self.mem.
+        for (offset, rel) in relocations {
+            let label_addr = labels
+                .get(&rel.label.id)
+                .copied()
+                .ok_or_else(|| BuilderError::UndefinedLabel(rel.label.id))?;
+            // TODO is it wrapping?
+            let label_ref_addr = label_addr.wrapping_add_signed(rel.label.addend);
+
+            rel.apply(self.base, label_ref_addr, self.mem, offset)
+                .map_err(|nested| BuilderError::Relocation { nested, offset })?;
+        }
+
+        Ok(label_addresses)
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use harm::reloc::{LabelId, LabelRef, Rel64Tag};
+
+    use super::*;
+
+    #[test]
+    fn test_good_offset() {
+        let mut mem = vec![0u8; 4];
+        let builder = Builder::new(&mut mem, 0);
+        let label_ref = LabelRef {
+            id: LabelId(0),
+            addend: 0,
+        };
+        let relocations = [(0, Rel64::new(Rel64Tag::NONE, label_ref))];
+        let res = builder.build(
+            [].into_iter(),
+            [(LabelId(0), 4)].into_iter(),
+            relocations.into_iter(),
+        );
+
+        assert!(res.is_ok(), "{res:?}");
+    }
+
+    #[test]
+    fn test_bad_offset() {
+        let mut mem = vec![0u8; 4];
+        let builder = Builder::new(&mut mem, 0);
+        let label_ref = LabelRef {
+            id: LabelId(0),
+            addend: 0,
+        };
+        // N.B. NONE relocation is 0 bytes wide, so 4 doesn't fail.  Use 5.
+        let relocations = [(5, Rel64::new(Rel64Tag::NONE, label_ref))];
+        let res = builder.build(
+            [].into_iter(),
+            [(LabelId(0), 4)].into_iter(),
+            relocations.into_iter(),
+        );
+
+        assert!(
+            matches!(
+                res,
+                Err(BuilderError::Relocation {
+                    nested: _,
+                    offset: _
+                })
+            ),
+            "{res:?}"
+        );
+    }
+
+    #[test]
+    fn test_bad_offset_max() {
+        let mut mem = vec![0u8; 4];
+        let builder = Builder::new(&mut mem, 0);
+        let label_ref = LabelRef {
+            id: LabelId(0),
+            addend: 0,
+        };
+        let relocations = [(usize::MAX, Rel64::new(Rel64Tag::NONE, label_ref))];
+        let res = builder.build(
+            [].into_iter(),
+            [(LabelId(0), 4)].into_iter(),
+            relocations.into_iter(),
+        );
+
+        assert!(
+            matches!(
+                res,
+                Err(BuilderError::Relocation {
+                    nested: _,
+                    offset: _
+                })
+            ),
+            "{res:?}"
+        );
+    }
+}

harm-runtime/src/labels.rs

@@ -3,11 +3,110 @@
  * This document is licensed under the BSD 3-clause license.
  */
 
-use harm::reloc::Offset;
+use std::collections::HashMap;
+
+use harm::reloc::{LabelId, Offset64};
 
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
 pub enum LabelInfo {
     Forward,
     // TODO segment
-    Offset(Offset),
+    Offset(Offset64),
+}
+
+#[derive(Debug, Default)]
+pub struct LabelRegistry {
+    named_labels: HashMap<String, LabelId>,
+    labels: HashMap<LabelId, LabelInfo>,
+    next_id: usize,
+}
+
+impl LabelRegistry {
+    #[inline]
+    pub fn new() -> Self {
+        Self::default()
+    }
+
+    #[inline]
+    pub fn get_forward_named_label(&mut self, name: &str) -> LabelId {
+        if let Some(id) = self.named_labels.get(name) {
+            *id
+        } else {
+            let id = self.next_label();
+            self.named_labels.insert(name.to_string(), id);
+            self.labels.insert(id, LabelInfo::Forward);
+            id
+        }
+    }
+
+    #[inline]
+    pub fn forward_label(&mut self) -> LabelId {
+        let id = self.next_label();
+        self.labels.insert(id, LabelInfo::Forward);
+        id
+    }
+
+    /// Define the label to have its address to be base address plus `offset`.
+    pub fn define_label(&mut self, label_id: LabelId, offset: Offset64) {
+        if let Some(info) = self.labels.get_mut(&label_id) {
+            match info {
+                LabelInfo::Forward => {
+                    *info = LabelInfo::Offset(offset);
+                }
+                LabelInfo::Offset(_) => {
+                    todo!("Label {label_id:?} is already defined");
+                }
+            }
+        } else {
+            todo!("Label {label_id:?} is not registered");
+        }
+    }
+
+    /// Define the label to have its address to be base address plus `offset`.
+    #[inline]
+    pub fn define_named_label(&mut self, name: &str, offset: Offset64) -> LabelId {
+        if let Some(id) = self.named_labels.get(name).copied() {
+            self.labels.insert(id, LabelInfo::Offset(offset));
+            id
+        } else {
+            let id = self.next_label();
+            self.named_labels.insert(name.to_string(), id);
+            self.labels.insert(id, LabelInfo::Offset(offset));
+            id
+        }
+    }
+
+    /// Turn the label into a named.
+    pub fn name_label(&mut self, id: LabelId, name: &str) {
+        if self.labels.contains_key(&id) {
+            self.named_labels.insert(name.to_string(), id);
+        } else {
+            todo!("Label {id:?} is not registered");
+        }
+    }
+
+    /// Return current label info.
+    #[inline]
+    pub fn label_info(&self, id: LabelId) -> Option<&LabelInfo> {
+        self.labels.get(&id)
+    }
+
+    pub fn get_named_labels(&self) -> impl Iterator<Item = (&str, LabelId)> {
+        self.named_labels
+            .iter()
+            .map(|(name, id)| (name.as_str(), *id))
+    }
+
+    pub fn get_defined_labels(&self) -> impl Iterator<Item = (LabelId, Offset64)> {
+        self.labels.iter().filter_map(|(id, info)| match info {
+            LabelInfo::Offset(offset) => Some((*id, *offset)),
+            LabelInfo::Forward => None,
+        })
+    }
+
+    fn next_label(&mut self) -> LabelId {
+        let id = LabelId(self.next_id);
+        self.next_id += 1;
+        id
+    }
 }

harm-runtime/src/lib.rs

@@ -1,6 +1,13 @@
-/* Copyright (C) 2025 Ivan Boldyrev
+/* Copyright (C) 2026 Ivan Boldyrev
  *
  * This document is licensed under the BSD 3-clause license.
  */
 
+
+#[cfg(feature = "alloc")]
+extern crate alloc;
+
+pub mod builder;
 pub mod labels;
+pub mod memory;
+pub mod runtime;

harm-runtime/src/memory.rs

@@ -0,0 +1,86 @@
+/* Copyright (C) 2026 Ivan Boldyrev
+ *
+ * This document is licensed under the BSD 3-clause license.
+ */
+
+#[cfg(feature = "memmap2")]
+mod memmap2;
+
+use harm::reloc::Addr64;
+
+#[cfg(feature = "memmap2")]
+pub use self::memmap2::{MmapBuffer, MmapPositionedMemory};
+
+#[cfg(feature = "alloc")]
+pub mod foreign_memory;
+#[cfg(feature = "alloc")]
+pub use self::foreign_memory::ForeignMemoryBuffer;
+
+pub trait Memory {
+    type ExtendError;
+
+    /// Current writing position.
+    fn pos(&self) -> usize;
+
+    /// If memory has fixed capacity, return it.
+    ///
+    /// A `Vec` is not considered a memory of fixed capacity because it can grow indefinitely.
+    fn capacity(&self) -> Option<usize>;
+
+    /// Append data to the memory.  Should fail when it reaches memory's capacity.
+    fn try_extend<I: Iterator<Item = u8>>(&mut self, bytes: I) -> Result<(), Self::ExtendError>;
+
+    /// Align position.
+    fn align(&mut self, alignment: usize) -> Result<(), Self::ExtendError> {
+        let pos = self.pos();
+        let remn = pos % alignment;
+        if remn != 0 {
+            self.try_extend(core::iter::repeat(0).take(alignment - remn))?;
+        }
+        Ok(())
+    }
+}
+
+pub trait IntoPositionedMemory<PM> {
+    type PositionedMemoryError;
+
+    /// Transform into positioned memory.
+    fn into_positioned_memory(self) -> Result<PM, Self::PositionedMemoryError>;
+}
+
+/// Memory with fixed location that can be transformed to an executable one after relocations are applied.
+pub trait PositionedMemory: AsMut<[u8]> {
+    fn get_base_address(&self) -> Addr64;
+}
+
+pub trait IntoExecutableMemory {
+    type ExecutableMemory;
+    type ExecutableMemoryError;
+
+    fn into_executable_memory(self) -> Result<Self::ExecutableMemory, Self::ExecutableMemoryError>;
+}
+
+#[cfg(test)]
+mod tests {
+    #[cfg(feature = "memmap2")]
+    #[test]
+    fn test_align() {
+        use super::*;
+
+        let mut data = &mut Vec::<u8>::new();
+
+        Memory::align(&mut data, 8);
+        assert!(data.is_empty());
+
+        data.push(1);
+        Memory::align(&mut data, 8);
+        assert_eq!(data.len(), 8);
+
+        Memory::align(&mut data, 8);
+        assert_eq!(data.len(), 8);
+
+        data.extend_from_slice(&[1, 2, 3, 4, 5, 6, 7]);
+        Memory::align(&mut data, 8);
+        assert_eq!(data.len(), 16);
+    }
+}