Skip to main content

scaleservers_arm32_assembly/
lib.rs

1// Copyright (c) Scaleservers LLC
2
3// Feature-gated `no_std`: the default build is `std`, but `--no-default-features` builds against
4// `core` + `alloc` only. The `extern crate alloc;` below (an item) must follow ALL inner `#![...]`
5// attributes, so it sits just after the `#![allow(...)]` block.
6#![cfg_attr(not(feature = "std"), no_std)]
7#![forbid(unsafe_code)]
8// ARM instruction encodings are bit-fields, so literals group by field width (e.g. 0xFFE0_0F80, masks like
9// 0b1111_1000_0000_0000_1101_0000_0000_0000) rather than by uniform nibbles -- clippy's uniform-grouping
10// heuristic is noise here.
11#![allow(clippy::unusual_byte_groupings)]
12// Encode helpers take one argument per instruction field; >7 args is natural for an ISA codec, not a smell.
13#![allow(clippy::too_many_arguments)]
14
15//! ARM 32-bit assembly encode/decode library -- the ARM32 member of the scaleservers assembler family
16//! (the 32-bit sibling of `scaleservers-arm64-assembly`).
17//!
18//! There are two central models, kept as **separate types** so a compiler backend cannot mix the two
19//! instruction sets within one code stream: [`ArmT32Instruction`] (Thumb / T32 -- the full M-profile set:
20//! ARMv6-M, ARMv7-M, ARMv7E-M DSP + hardware floating point, the ARMv8-M Security Extension, and the complete
21//! ARMv8.1-M MVE/"Helium" vector extension) and [`ArmA32Instruction`] (ARM state / A32 -- the A/R-profile set
22//! including NEON + VFP). [`Arm32Instruction`] is the interworking union of both. Every instruction offers the
23//! family signatures: `encode` (model -> machine bytes), `decode` (bytes -> model, the exact inverse of
24//! `encode`), `encode_for_target(&ArmTargetProfile)` (target/ISA gating -- refuses forms the chosen CPU cannot
25//! run), and `to_assembly_string(syntax)` (model -> UAL text, in LLVM or GNU flavor). The console `armasm`
26//! (assembler) and `armdasm` (disassembler) are thin tools over this library.
27//!
28//! Decoding never panics on arbitrary input -- malformed bytes yield a [`DecodeError`], never a crash (a
29//! disassembler consumes untrusted binaries); this is enforced by deterministic robustness sweeps and a
30//! cargo-fuzz campaign.
31//!
32//! ```
33//! use scaleservers_arm32_assembly::{ArmT32Instruction, ArmAssemblySyntax};
34//!
35//! // model -> machine bytes (Thumb is little-endian; NOP is the halfword 0xBF00)
36//! let nop = ArmT32Instruction::Nop_T1;
37//! assert_eq!(nop.encode().unwrap(), [0x00, 0xbf]);
38//!
39//! // model -> UAL assembly text
40//! assert_eq!(nop.to_assembly_string(ArmAssemblySyntax::Gnu), "nop");
41//!
42//! // machine bytes -> model (decode is the exact inverse of encode)
43//! let bytes = [0x00u8, 0xbf];
44//! let mut offset = 0;
45//! let decoded = ArmT32Instruction::decode(&mut bytes.iter(), &mut offset).unwrap().unwrap();
46//! assert_eq!(decoded, nop);
47//! ```
48
49// `alloc` supplies the heap collections (`Vec`/`String`/`Box`) the codec returns under `no_std`; `#[macro_use]`
50// brings the `vec!`/`format!` macros into scope crate-wide so per-file imports stay minimal. (Placed after the
51// inner attributes / crate doc comment, since `extern crate` is an item and inner attributes must precede it.)
52#[macro_use]
53extern crate alloc;
54
55mod enums;
56pub use enums::{
57    Arm32BlockAddressMode,
58    // neutral ARM-wide aliases (the 4-bit condition code and barrel-shift operand are shared by A32 + T32)
59    Arm32Condition,
60    Arm32CpsMode,
61    Arm32DirectedRound,
62    Arm32DoublePrecisionRegister,
63    Arm32ExtendType,
64    Arm32FpDataOperation2,
65    Arm32FpDataOperation3,
66    Arm32GeneralPurposeRegister,
67    Arm32IndexMode,
68    Arm32LowGeneralPurposeRegister,
69    Arm32MemoryOffset,
70    Arm32MemoryOffset8,
71    Arm32MveBitwiseOp,
72    Arm32MveFloatArithOp,
73    Arm32MveFloatReduceOp,
74    Arm32MveFloatSize,
75    Arm32MveIntArithOp,
76    Arm32MveLongMacOp,
77    Arm32MveMisc2FloatOp,
78    Arm32MveMisc2Op,
79    Arm32MveQMovnKind,
80    Arm32MveReduceOp,
81    Arm32MveShiftImmOp,
82    Arm32MveShiftNarrowOp,
83    Arm32MveSize,
84    Arm32MveVcmpCondition,
85    Arm32MveVecScalarFloatOp,
86    Arm32MveVecScalarIntOp,
87    Arm32MveVectorRegister,
88    Arm32MveVrintOp,
89    Arm32NeonAesOp,
90    Arm32NeonBitwiseOp,
91    Arm32NeonDiffLongOp,
92    Arm32NeonDiffNarrowOp,
93    Arm32NeonDiffWideOp,
94    Arm32NeonFloatOp,
95    Arm32NeonIntegerOp,
96    Arm32NeonLoadStoreAddress,
97    Arm32NeonMisc2FixedOp,
98    Arm32NeonMisc2SizedOp,
99    Arm32NeonNarrowOp,
100    Arm32NeonScalarLongOp,
101    Arm32NeonScalarOp,
102    Arm32NeonSha2Op,
103    Arm32NeonSha3Op,
104    Arm32NeonShiftNarrowOp,
105    Arm32NeonShiftOp,
106    Arm32NeonSize,
107    Arm32ParallelOperation,
108    Arm32ParallelPrefix,
109    Arm32QuadwordRegister,
110    Arm32RegisterShift,
111    Arm32ShiftType,
112    Arm32SinglePrecisionRegister,
113    Arm32VmovLaneSize,
114    Arm32VrintMode,
115    Arm32VselCondition,
116    ArmT32CpsPrimaskEffect,
117    ArmT32FpDataOperation2,
118    ArmT32FpDataOperation3,
119    ArmT32IndexMode,
120    ArmT32InstructionCondition,
121    ArmT32MemoryBarrierOption,
122    ArmT32ParallelOperation,
123    ArmT32ParallelPrefix,
124    ArmT32RegisterShift,
125    ArmT32SpecialRegister,
126    mve_predicate_mask_from_suffix,
127};
128
129mod errors;
130pub use errors::{DecodeError, EncodeError};
131
132// Decode-time context for the family-wide Rule R4 ("same bytes, different meaning" -> disambiguate by an
133// explicit decode context). Used by `ArmT32Instruction::decode_with` to choose between a CDE custom-datapath
134// instruction and a generic coprocessor instruction on coprocessors 0-7.
135mod arm32_decode_context;
136pub use arm32_decode_context::ArmDecodeContext;
137
138mod armt32_instruction;
139pub use armt32_instruction::ArmT32Instruction;
140
141// A32 ("ARM" state) -- the sibling instruction set to T32, kept as a SEPARATE type so a compiler backend
142// cannot mix the two sets within one code stream. `Arm32Instruction` is the interworking union of both.
143mod arma32_instruction;
144pub use arma32_instruction::ArmA32Instruction;
145
146mod arm32_instruction;
147pub use arm32_instruction::{Arm32Instruction, ArmInstructionSet};
148
149// The VFP modified-immediate codec for VMOV (immediate).
150pub mod floating_point_immediate;
151pub use floating_point_immediate::{
152    vfp_encode_f64_to_imm8, vfp_expand_imm8_to_f32, vfp_expand_imm8_to_f64,
153};
154
155// Assembly-string emission (model -> UAL text). Adds `to_assembly_string` / `to_assembly_string_at`
156// inherent methods to ArmT32Instruction; the disassembler renders through this layer. `ArmAssemblySyntax`
157// selects LLVM- or GNU-flavored formatting.
158pub mod emit;
159pub use emit::ArmAssemblySyntax;
160pub use emit::apply_it_block_condition;
161pub use emit::apply_vpt_block_suffix;
162
163// Target-architecture gating: restrict the emittable set to a processor profile. The implemented set spans
164// the full M-profile -- ARMv6-M, ARMv7-M, and ARMv7E-M (DSP + floating-point) -- and the gate refuses any
165// form the chosen profile can't run.
166pub mod targets;
167pub use targets::{ArmCpuFeature, ArmInstructionRequirement, ArmIsaVersion, ArmTargetProfile};
168
169// NOTE: the programmatic label/relocation backend (`ArmThumbCodeBuffer impl AsmBackend`) + the ELF object
170// writer live in the SEPARATE crate `scaleservers-arm32-codegen`, which depends on this instruction model
171// plus the shared scaleservers compiler crates. Kept out of here so this crate stays a standalone,
172// zero-dependency library (cargo requires optional path-deps to exist even for a no-feature build, so a
173// `codegen` feature here would couple every build to those crates).
174
175mod tests;
176
177mod utils;