This commit is contained in:
Nilton Constantino
2026-01-30 16:21:02 +00:00
parent c797be9287
commit 8c161e3e13
11 changed files with 261 additions and 140 deletions
+70
View File
@@ -20,10 +20,36 @@ pub fn operand_size(opcode: OpCode) -> usize {
OpCode::GetLocal | OpCode::SetLocal => 4,
OpCode::Call => 8, // addr(u32) + args_count(u32)
OpCode::Syscall => 4,
OpCode::Alloc => 8, // type_id(u32) + slots(u32)
OpCode::GateLoad | OpCode::GateStore => 4, // offset(u32)
_ => 0,
}
}
// --- HIP Trap Codes ---
/// Attempted to access a gate that does not exist or has been recycled incorrectly.
pub const TRAP_INVALID_GATE: u32 = 0x01;
/// Attempted to access a gate that has been explicitly released (RC=0).
pub const TRAP_DEAD_GATE: u32 = 0x02;
/// Attempted to access a field or index beyond the allocated slots for a gate.
pub const TRAP_OOB: u32 = 0x03;
/// Attempted a typed operation on a gate whose storage type does not match.
pub const TRAP_TYPE: u32 = 0x04;
/// Detailed information about a runtime trap.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct TrapInfo {
/// The specific trap code (e.g., TRAP_OOB).
pub code: u32,
/// The numeric value of the opcode that triggered the trap.
pub opcode: u16,
/// A human-readable message explaining the trap.
pub message: String,
/// The absolute Program Counter (PC) address where the trap occurred.
pub pc: u32,
}
/// Checks if an instruction is a jump (branch) instruction.
pub fn is_jump(opcode: OpCode) -> bool {
match opcode {
@@ -36,3 +62,47 @@ pub fn is_jump(opcode: OpCode) -> bool {
pub fn has_immediate(opcode: OpCode) -> bool {
operand_size(opcode) > 0
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn test_trap_code_stability() {
// These numeric values are normative and must not change.
assert_eq!(TRAP_INVALID_GATE, 0x01);
assert_eq!(TRAP_DEAD_GATE, 0x02);
assert_eq!(TRAP_OOB, 0x03);
assert_eq!(TRAP_TYPE, 0x04);
}
#[test]
fn test_abi_documentation_snapshot() {
// Snapshot of the ABI rules for traps and operands.
let abi_info = r#"
HIP Traps:
- INVALID_GATE (0x01): Non-existent gate handle.
- DEAD_GATE (0x02): Gate handle with RC=0.
- OOB (0x03): Access beyond allocated slots.
- TYPE (0x04): Type mismatch during heap access.
Operand Sizes:
- Alloc: 8 bytes (u32 type_id, u32 slots)
- GateLoad: 4 bytes (u32 offset)
- GateStore: 4 bytes (u32 offset)
- PopN: 4 bytes (u32 count)
"#;
// This test serves as a "doc-lock".
// If you change the ABI, you must update this string.
let current_info = format!(
"\nHIP Traps:\n- INVALID_GATE (0x{:02X}): Non-existent gate handle.\n- DEAD_GATE (0x{:02X}): Gate handle with RC=0.\n- OOB (0x{:02X}): Access beyond allocated slots.\n- TYPE (0x{:02X}): Type mismatch during heap access.\n\nOperand Sizes:\n- Alloc: {} bytes (u32 type_id, u32 slots)\n- GateLoad: {} bytes (u32 offset)\n- GateStore: {} bytes (u32 offset)\n- PopN: {} bytes (u32 count)\n",
TRAP_INVALID_GATE, TRAP_DEAD_GATE, TRAP_OOB, TRAP_TYPE,
operand_size(OpCode::Alloc),
operand_size(OpCode::GateLoad),
operand_size(OpCode::GateStore),
operand_size(OpCode::PopN)
);
assert_eq!(current_info.trim(), abi_info.trim());
}
}
+17 -6
View File
@@ -26,12 +26,16 @@ pub enum ConstantPoolEntry {
///
/// The file format follows this structure (Little-Endian):
/// 1. Magic Header: "PPBC" (4 bytes)
/// 2. CP Count: u32
/// 3. CP Entries: [Tag (u8), Data...]
/// 4. ROM Size: u32
/// 5. ROM Data: [u16 OpCode, Operands...][]
/// 2. Version: u16 (Currently 0)
/// 3. Flags: u16 (Reserved)
/// 4. CP Count: u32
/// 5. CP Entries: [Tag (u8), Data...]
/// 6. ROM Size: u32
/// 7. ROM Data: [u16 OpCode, Operands...][]
#[derive(Debug, Clone, Default)]
pub struct PbcFile {
/// The file format version.
pub version: u16,
/// The list of constants used by the program.
pub cp: Vec<ConstantPoolEntry>,
/// The raw instruction bytes (ROM).
@@ -43,12 +47,15 @@ pub struct PbcFile {
/// This function validates the "PPBC" signature and reconstructs the
/// Constant Pool and ROM data from the binary format.
pub fn parse_pbc(bytes: &[u8]) -> Result<PbcFile, String> {
if bytes.len() < 4 || &bytes[0..4] != b"PPBC" {
if bytes.len() < 8 || &bytes[0..4] != b"PPBC" {
return Err("Invalid PBC signature".into());
}
let mut cursor = Cursor::new(&bytes[4..]);
let version = read_u16_le(&mut cursor).map_err(|e| e.to_string())?;
let _flags = read_u16_le(&mut cursor).map_err(|e| e.to_string())?;
let cp_count = read_u32_le(&mut cursor).map_err(|e| e.to_string())? as usize;
let mut cp = Vec::with_capacity(cp_count);
@@ -90,7 +97,7 @@ pub fn parse_pbc(bytes: &[u8]) -> Result<PbcFile, String> {
let mut rom = vec![0u8; rom_size];
cursor.read_exact(&mut rom).map_err(|e| e.to_string())?;
Ok(PbcFile { cp, rom })
Ok(PbcFile { version, cp, rom })
}
/// Serializes a `PbcFile` structure into a binary buffer.
@@ -100,6 +107,9 @@ pub fn write_pbc(pbc: &PbcFile) -> Result<Vec<u8>, String> {
let mut out = Vec::new();
out.write_all(b"PPBC").map_err(|e| e.to_string())?;
write_u16_le(&mut out, pbc.version).map_err(|e| e.to_string())?;
write_u16_le(&mut out, 0).map_err(|e| e.to_string())?; // Flags reserved
write_u32_le(&mut out, pbc.cp.len() as u32).map_err(|e| e.to_string())?;
for entry in &pbc.cp {
@@ -157,6 +167,7 @@ mod tests {
// 2. Create a PBC file
let pbc_file = PbcFile {
version: 0,
cp: vec![ConstantPoolEntry::Int32(100)], // Random CP entry
rom,
};