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;