1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
//! A decoder, disassembler, assembler and detour installer for the Renesas H8
//! family (H8/300, H8/300H, H8S/2000, H8S/2600 and H8SX), operating on a flat
//! big-endian `&[u8]` image where file offset and load address are the same
//! number.
//!
//! [`isa::insn_len`], [`isa::decode_insn`], [`isa::encode_insn`] and
//! [`isa::disassemble_insn`] cover all five targets through the legacy opcode
//! maps and all 8,493 reviewed H8SX manual rows. The original narrow H8/300 and
//! H8SX APIs remain available. [`Asm`], [`relocate`], [`detour`], [`image`] and
//! [`analysis`] provide checked assembly, patch planning and conservative
//! control-flow analysis. Delayed, PC-indexed and compound relative relocation
//! is explicitly refused where safe rewriting cannot be established.
//!
//! Instruction-aware APIs require the core ([`Target`]) and operating mode
//! ([`Mode`]). Both change what bytes mean and must come from the caller's
//! knowledge of the firmware, not a guess from its byte patterns.
//!
//! ```
//! use h8_asm::{isa, Mode, Target};
//!
//! let bytes = [0x0c, 0x89]; // MOV.B R0L,R1L
//! let decoded = isa::decode_insn(&bytes, Target::H8_300, Mode::Normal).unwrap();
//! assert_eq!(decoded.len, 2);
//! assert_eq!(
//! isa::encode_insn(decoded.insn, Target::H8_300, Mode::Normal).unwrap(),
//! bytes
//! );
//! ```
//!
//! Every encoding claim in this crate cites its section in Renesas' software
//! manuals under `spec/` (H8/300 ADE-602-025, H8/300H REJ09B0213, H8S
//! REJ09B0139, H8SX REJ09B0102).
pub use ;
pub use Asm;
/// The H8 core an image was written for.
///
/// Each generation is a superset of the one before it, so the same bytes can
/// decode differently, or only decode at all, depending on the target. This
/// is the same "confident wrong answer" risk that `thumb_asm::isa::Target`
/// exists for.
///
/// `#[non_exhaustive]` so that adding a core, or splitting one (the H8SX
/// manual notes product-specific differences), is not a breaking change.
/// The CPU operating mode, which sets the width of the address space, of
/// branch and call targets, of vector-table entries and of stacked `PC`s.
///
/// The mode is fixed by the chip's mode pins or its configuration and cannot be
/// read from the image, so the caller has to state it. Guessing wrong corrupts
/// every absolute address and every vector-table decode, not just a single
/// instruction.