portal-pc-asm-common

Common types shared across the asm-* crates in the portal-pc project. The library provides a vocabulary of enums and structs used when describing, rewriting, or transforming assembly-level code.

What this is

This is a no_std Rust library at version 0.1.1. It does not implement any assembly parsing, encoding, or execution. It defines the shared data types that other crates in this workspace use when passing assembly-related information between components.

The library is part of a larger system (the portal-hot workspace) concerned with assembly rewriting — transforming binary code rather than executing it directly.

Modules

types::ops

Enums for arithmetic and logical operations:

• Arith — Add, Sub, Mul, Div(Sign), Rem(Sign), And, Or, Xor, Shl, Shr(Sign), Rotl(Sign), Rotr(Sign)
• Sign — Signed or Unsigned (parameterises operations where signedness matters)
• Endian — Little or Big
• Ext — Sign or Zero (how to extend a value to a larger bit width)
• Cmp — Le(Sign), Lt(Sign), Eq, Gt(Sign), Ge(Sign), Ne

All enums are #[non_exhaustive].

types::perms

Types for tracking per-byte permissions on code:

• Perm — enum of Read, Write, Exec, NoJump
• Perms<T> — struct holding a T for each of the four permissions (r, w, x, nj). Generic so it can hold bool, &BitSlice, BitVec, etc.
• InputRef<'a> — borrowed view of a byte slice paired with four BitSlices of permission bits (one bit per byte). Construction checks all slices are the same length.
• Input — owned equivalent of InputRef using Vec<u8> and BitVec. Requires the alloc feature.
• InputStream — trait (analogous to embedded_io::Write) for consumers that accept InputRef chunks.

The NoJump permission marks bytes that are not valid branch targets, independent of executability.

types::reg

• Reg(u8) — a register identifier. Up to 256 registers. Reg::CTX (255) is a reserved context register.
  • .r32() — normalises to the range 0–31 via modulo 32.
  • .r32_swap_0_and_31() — swaps registers 0 and 31 within a 32-register set (for ABI conventions).

types::mem

• MemorySize — enum of access widths: _8, _16, _32, _64 (default), _128, _256, _512.
• MemorySized<T> — wraps any value with a MemorySize.

types::value

• Bitness { log2: u8 } — bit width stored as a power of two. log2 = 6 means 64 bits.
• Constant { data: [u64; 8] } — up to 512-bit constant value stored as eight native-endian u64s. Methods: .bytes(Bitness), .bits(Bitness), from_bytes(...), from_bits(...).
• Value<G> { offset: G, bitness: Bitness } — a value at some location (register, address, etc.) with a known bit width.
• LoadStoreFrame<G> — either a Value (at a register/address with a bit offset) or a Constant. Used to represent load/store operands.
• Any, All, AssignChain — marker traits for iterators, used to distinguish semantic intent in the type system.

types::code

Low-level instruction encoding helpers (no doc comment; not re-exported from types):

• InstCodeI4(u32) — wraps a 32-bit instruction word. .with(field_ranges, value) inserts a value across non-contiguous bit ranges. .extract(field_ranges) reads them back.
• InstCodeSlice<S> — same concept for variable-length instruction encodings backed by a byte slice.

ratchet (feature: ratchet)

• Ratchet { seed: [u8; 32] } — generates a deterministic sequence of 32-byte values by repeatedly applying SHA3-256 to an internal seed. Each call to .next() returns the current seed and advances it.
• .split(data) / .split_mut(data, replacer) — splits a byte slice at positions where ratchet-generated marker values appear. Used to mark sections of assembled code for post-processing; the markers are invalid on real hardware (preventing accidental execution).

Optional features

Feature	What it enables
serde	Serialize/Deserialize on all public types via serde
rkyv-impl	Archive/Serialize/Deserialize via rkyv for zero-copy use
enum-map	enum_map::Enum derives; Perms<T> ↔ EnumMap<Perm, T> conversions
exhaust	exhaust::Exhaust derives (exhaustive iteration over enum variants)
alloc	Enables Input, BitVec, and Vec-based APIs
sha3	SHA3-256 hashing support
ratchet	The ratchet module (requires sha3)

None of the optional features are enabled by default.

Deprecations

Since 0.1.1, glob re-exports from the types module root (use portal_pc_asm_common::types::*) are deprecated and will be removed in the next minor version. Use the submodules directly:

use portal_pc_asm_common::types::ops::{Arith, Sign};
use portal_pc_asm_common::types::perms::{Perm, Perms, InputRef};
use portal_pc_asm_common::types::value::{Bitness, Constant, Value};

Installation

[dependencies]
portal-pc-asm-common = "0.1.1"

# With common optional features:
portal-pc-asm-common = { version = "0.1.1", features = ["serde", "alloc"] }

License

CC0-1.0. See LICENSE or https://creativecommons.org/publicdomain/zero/1.0/.