Skip to main content

​
Address Space Overview

The Thru virtual machine uses a 48-bit segmented address space designed to provide memory isolation and efficient access to different types of data during program execution. The address format follows a three-component structure that enables both type safety and performance optimization.

​
Address Format

Each virtual address is composed of three fields packed into a 48-bit value: 
Bits: 47-40  |  39-24   |  23-0
     seg_type| seg_idx  | offset
    (8 bits) |(16 bits) |(24 bits)
The address construction macro: TN_VM_ADDR(seg_type, seg_idx, offset) = (seg_type << 40) | (seg_idx << 24) | offset

​
Address Components

  • Segment Type (8 bits): Determines the memory region type and access permissions
  • Segment Index (16 bits): Identifies the specific segment within the type
  • Offset (24 bits): Byte offset within the segment (up to 16MB per segment)

​
Memory Segment Types

​
0x00: Read-Only Data Segments

Contains immutable data that programs can read but never modify.
Segment IndexNamePurposeNotes
0x0000NULLInvalid/null segmentAlways causes access violation
0x0001TXN_DATATransaction dataContains serialized transaction
0x0002SHADOW_STACKVM shadow stackCall frame metadata (public portion)
0x0003RESERVEDUnusedReserved for future use
0x0004BLOCK_CTXBlock contextBlock metadata and timing info
Write operations to read-only segments cause access violations and will fail.

​
0x02: Account Metadata

Provides access to account metadata structures.
FieldDescriptionAccess Notes
seg_idxAccount index in transactionMust be < transaction account count
offsetByte offset in metadataLimited to sizeof(tn_account_meta_t)
  • Size: Fixed at sizeof(tn_account_meta_t) bytes
  • Access: Read-only from VM perspective
  • Non-existent accounts: Returns pointer to zeroed metadata structure
  • Invalid access: Access violations occur for out-of-bounds or invalid account indices

​
0x03: Account Data

Page-based access to account data with copy-on-write semantics. Programs execute directly from this segment type, using position-independent code at their account’s address.
FeatureDetails
Page Size4096 bytes
AlignmentEnforced at page boundaries for cross-page access
Write AccessRequires account to be writable by current program
COW PagesAutomatic copy-on-write for modifications
Program ExecutionPrograms stored as account data execute from 0x03XXXX000000 where XXXX is the account index
Account data accesses that span page boundaries cause access violations. Design your data structures to respect 4KB page alignment.
Program Execution Model: Programs are compiled as position-independent executables (PIE) and execute directly from their account data addresses. For example, a program at account index 5 executes from virtual address 0x030005000000.

​
0x04: Event Data

Reserved for event emission (implementation details in event subsystem).

​
0x05: Stack

Stack memory segment that grows downward from high addresses to low addresses.
CharacteristicValue
Growth DirectionDownward (0xFFFFFF → 0x000000)
Page Size4096 bytes
Max Segments1 per VM instance
Size Limit16MB per segment
Permission ModelFrame-based access control
Growth Behavior: The stack segment grows downward, meaning as more memory is allocated, the segment size increases toward lower addresses. When you allocate new stack space, the valid address range expands from the bottom (higher addresses) toward the top (lower addresses), similar to traditional hardware stacks. Address Layout:
  • Virtual address range: 0xFFFFFF down to current stack size
  • Stack pointer typically points to 0x000000 offset initially
  • As stack grows, valid addresses extend from 0xFFFFFF downward

​
0x07: Heap

Heap memory segment that grows upward from low addresses to high addresses.
CharacteristicValue
Growth DirectionUpward (0x000000 → 0xFFFFFF)
Page Size4096 bytes
Max Segments1 per VM instance
Size Limit16MB per segment
Permission ModelFrame-based access control
Growth Behavior: The heap segment grows upward, meaning as more memory is allocated, the segment size increases toward higher addresses. When you allocate new heap space, the valid address range expands from the base (0x000000) toward higher addresses, similar to traditional heap allocators.

​
Address Translation Process

The VM performs the following steps for each memory access:
1

Address Validation

Check if the upper 16 bits of the 64-bit address are zero (ensuring 48-bit address space).
2

Segment Extraction

Extract segment type, index, and offset from the address using bit manipulation.
3

Alignment Check

Verify that the offset is properly aligned for the requested access size.
4

Permission Validation

Check write permissions based on segment type and current execution context.
5

Translation

Convert virtual address to host address based on segment type-specific logic. If any validation fails, an access violation occurs.

​
Access Control and Permissions

​
Write Access Control

Segment TypeWrite BehaviorAccess Violation Conditions
Read-Only DataAlways failsAny write attempt causes violation
Account MetadataAlways failsRuntime-managed, no direct writes allowed
Account DataConditionalViolation if program doesn’t own account
Anonymous DataConditionalViolation if frame permissions insufficient

​
Frame-Based Security

Anonymous memory segments use a frame-based permission system:
  • Each page is tagged with the frame index (program invocation call depth) that allocated it
  • Pages can only be freed by program invocations at the same call depth or higher
  • Deeper called programs cannot free pages allocated by shallower called programs

​
Memory Management

​
Page Allocation

  • Page Size: 4096 bytes (TN_RUNTIME_PAGE_SZ)
  • Allocation: Dynamic allocation from a global page pool
  • Tracking: Inverted page table for efficient management
  • Limits: Enforced at transaction level for resource control

​
Copy-on-Write (COW)

Account data uses COW semantics:
  1. Initial State: Points to read-only account data
  2. First Write: Allocates writable page and copies original data
  3. Subsequent Writes: Operate on the writable copy
  4. Commit: Modified pages are written back during transaction commit

​
Access Violations

Memory access can fail in several ways, resulting in access violations:
Violation TypeCauseDetails
Invalid AddressMalformed address or out-of-boundsUpper 16 bits non-zero, or address exceeds segment bounds
Permission DeniedUnauthorized write accessAttempting to write to read-only segments or unowned accounts
Page Boundary CrossAccess spans multiple pagesSingle access cannot cross 4KB page boundaries
Resource ExhaustionNo free pages availableAnonymous memory allocation when page pool is exhausted
Alignment ViolationMisaligned accessOffset not aligned to required boundary for access size
Invalid SegmentUnknown segment type/indexSegment type not implemented or segment index out of range
Access Violation Behavior: When any of these violations occur the VM will fault and exit, reverting the transaction.

​
Performance Considerations

  • Page Alignment: Design data structures to fit within 4KB pages
  • Sequential Access: Prefer sequential memory access patterns
  • Segment Locality: Group related data within the same segment type
  • COW Overhead: First write to account data incurs page allocation cost

​
Example Address Calculations

// Stack segment at offset 0x1000
ulong stack_addr = TN_VM_ADDR(TN_VM_SEG_TYPE_STACK, 0x0000, 0x001000);
// Result: 0x050000001000