amx_sys/
lib.rs

1//! Pure Rust implementation of Apple's undocumented AMX (matrix acceleration) instructions.
2//!
3//! This crate provides software emulation of the AMX instruction set found on Apple M1, M2, M3, and M4 processors.
4//! AMX is a specialized hardware accelerator for matrix and vector operations, distinct from standard ARM NEON.
5//!
6//! # Architecture Overview
7//!
8//! The AMX register file contains:
9//! - 8 X registers (512 bytes total) - acts as a circular buffer
10//! - 8 Y registers (512 bytes total) - acts as a circular buffer  
11//! - 64 Z registers (4KB total) - arranged as a 64×64 byte matrix
12//!
13//! Operations work on 64-byte spans from X/Y and accumulate into Z using:
14//! - **Vector mode**: element-wise operations (Z[i] += X[i] * Y[i])
15//! - **Matrix mode**: outer product operations (Z[j][i] += X[i] * Y[j])
16//!
17//! # Example
18//!
19//! ```
20//! use amx_sys::registers::AmxState;
21//!
22//! let mut state = AmxState::new();
23//! // Emulate instruction operations...
24//! ```
25
26#![allow(non_camel_case_types)]
27
28pub mod registers;
29pub mod instructions;
30pub mod utils;
31pub mod test_helpers;
32
33pub use registers::{AmxState, AmxReg, DATA_TYPE};
34pub use instructions::*;
35pub use test_helpers::*;
36
37/// Initialize AMX hardware state - soft reset
38#[inline]
39pub fn amx_set() {
40    // AMX_SET instruction - zeros all X, Y, Z registers and resets state
41}
42
43/// Clear AMX state
44#[inline]
45pub fn amx_clr() {
46    // AMX_CLR instruction - alternative clear
47}
48
49#[cfg(test)]
50mod tests {
51    use super::*;
52
53    #[test]
54    fn test_register_sizes() {
55        // Verify register file structure matches specification
56        assert_eq!(size_of::<AmxReg>(), 64, "AmxReg should be 64 bytes");
57        assert_eq!(size_of::<AmxState>(), 5120, "AmxState should be 5120 bytes");
58    }
59
60    #[test]
61    fn test_state_initialization() {
62        let state = AmxState::new();
63        // State should be properly initialized
64        assert_eq!(state.x.len(), 8);
65        assert_eq!(state.y.len(), 8);
66        assert_eq!(state.z.len(), 64);
67    }
68}
amx_sys/lib.rs

amx_sys/
lib.rs
