Code Review / openocd.git / blob
? search:
summary | shortlog | log | commit | commitdiff | review | tree
history | raw | HEAD
openocd: src/target: replace the GPL-2.0-or-later license tag
[openocd.git] / src / target / armv4_5.c
1 /* SPDX-License-Identifier: GPL-2.0-or-later */
2
3 /***************************************************************************
4 * Copyright (C) 2005 by Dominic Rath *
5 * Dominic.Rath@gmx.de *
6 * *
7 * Copyright (C) 2008 by Spencer Oliver *
8 * spen@spen-soft.co.uk *
9 * *
10 * Copyright (C) 2008 by Oyvind Harboe *
11 * oyvind.harboe@zylin.com *
12 * *
13 * Copyright (C) 2018 by Liviu Ionescu *
14 * <ilg@livius.net> *
15 ***************************************************************************/
16
17 #ifdef HAVE_CONFIG_H
18 #include "config.h"
19 #endif
20
21 #include "arm.h"
22 #include "armv4_5.h"
23 #include "arm_jtag.h"
24 #include "breakpoints.h"
25 #include "arm_disassembler.h"
26 #include <helper/binarybuffer.h>
27 #include "algorithm.h"
28 #include "register.h"
29 #include "semihosting_common.h"
30
31 /* offsets into armv4_5 core register cache */
32 enum {
33 /* ARMV4_5_CPSR = 31, */
34 ARMV4_5_SPSR_FIQ = 32,
35 ARMV4_5_SPSR_IRQ = 33,
36 ARMV4_5_SPSR_SVC = 34,
37 ARMV4_5_SPSR_ABT = 35,
38 ARMV4_5_SPSR_UND = 36,
39 ARM_SPSR_MON = 41,
40 ARM_SPSR_HYP = 43,
41 };
42
43 static const uint8_t arm_usr_indices[17] = {
44 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, ARMV4_5_CPSR,
45 };
46
47 static const uint8_t arm_fiq_indices[8] = {
48 16, 17, 18, 19, 20, 21, 22, ARMV4_5_SPSR_FIQ,
49 };
50
51 static const uint8_t arm_irq_indices[3] = {
52 23, 24, ARMV4_5_SPSR_IRQ,
53 };
54
55 static const uint8_t arm_svc_indices[3] = {
56 25, 26, ARMV4_5_SPSR_SVC,
57 };
58
59 static const uint8_t arm_abt_indices[3] = {
60 27, 28, ARMV4_5_SPSR_ABT,
61 };
62
63 static const uint8_t arm_und_indices[3] = {
64 29, 30, ARMV4_5_SPSR_UND,
65 };
66
67 static const uint8_t arm_mon_indices[3] = {
68 39, 40, ARM_SPSR_MON,
69 };
70
71 static const uint8_t arm_hyp_indices[2] = {
72 42, ARM_SPSR_HYP,
73 };
74
75 static const struct {
76 const char *name;
77 unsigned short psr;
78 /* For user and system modes, these list indices for all registers.
79 * otherwise they're just indices for the shadow registers and SPSR.
80 */
81 unsigned short n_indices;
82 const uint8_t *indices;
83 } arm_mode_data[] = {
84 /* Seven modes are standard from ARM7 on. "System" and "User" share
85 * the same registers; other modes shadow from 3 to 8 registers.
86 */
87 {
88 .name = "User",
89 .psr = ARM_MODE_USR,
90 .n_indices = ARRAY_SIZE(arm_usr_indices),
91 .indices = arm_usr_indices,
92 },
93 {
94 .name = "FIQ",
95 .psr = ARM_MODE_FIQ,
96 .n_indices = ARRAY_SIZE(arm_fiq_indices),
97 .indices = arm_fiq_indices,
98 },
99 {
100 .name = "Supervisor",
101 .psr = ARM_MODE_SVC,
102 .n_indices = ARRAY_SIZE(arm_svc_indices),
103 .indices = arm_svc_indices,
104 },
105 {
106 .name = "Abort",
107 .psr = ARM_MODE_ABT,
108 .n_indices = ARRAY_SIZE(arm_abt_indices),
109 .indices = arm_abt_indices,
110 },
111 {
112 .name = "IRQ",
113 .psr = ARM_MODE_IRQ,
114 .n_indices = ARRAY_SIZE(arm_irq_indices),
115 .indices = arm_irq_indices,
116 },
117 {
118 .name = "Undefined instruction",
119 .psr = ARM_MODE_UND,
120 .n_indices = ARRAY_SIZE(arm_und_indices),
121 .indices = arm_und_indices,
122 },
123 {
124 .name = "System",
125 .psr = ARM_MODE_SYS,
126 .n_indices = ARRAY_SIZE(arm_usr_indices),
127 .indices = arm_usr_indices,
128 },
129 /* TrustZone "Security Extensions" add a secure monitor mode.
130 * This is distinct from a "debug monitor" which can support
131 * non-halting debug, in conjunction with some debuggers.
132 */
133 {
134 .name = "Secure Monitor",
135 .psr = ARM_MODE_MON,
136 .n_indices = ARRAY_SIZE(arm_mon_indices),
137 .indices = arm_mon_indices,
138 },
139 {
140 .name = "Secure Monitor ARM1176JZF-S",
141 .psr = ARM_MODE_1176_MON,
142 .n_indices = ARRAY_SIZE(arm_mon_indices),
143 .indices = arm_mon_indices,
144 },
145
146 /* These special modes are currently only supported
147 * by ARMv6M and ARMv7M profiles */
148 {
149 .name = "Thread",
150 .psr = ARM_MODE_THREAD,
151 },
152 {
153 .name = "Thread (User)",
154 .psr = ARM_MODE_USER_THREAD,
155 },
156 {
157 .name = "Handler",
158 .psr = ARM_MODE_HANDLER,
159 },
160
161 /* armv7-a with virtualization extension */
162 {
163 .name = "Hypervisor",
164 .psr = ARM_MODE_HYP,
165 .n_indices = ARRAY_SIZE(arm_hyp_indices),
166 .indices = arm_hyp_indices,
167 },
168 };
169
170 /** Map PSR mode bits to the name of an ARM processor operating mode. */
171 const char *arm_mode_name(unsigned psr_mode)
172 {
173 for (unsigned i = 0; i < ARRAY_SIZE(arm_mode_data); i++) {
174 if (arm_mode_data[i].psr == psr_mode)
175 return arm_mode_data[i].name;
176 }
177 LOG_ERROR("unrecognized psr mode: %#02x", psr_mode);
178 return "UNRECOGNIZED";
179 }
180
181 /** Return true iff the parameter denotes a valid ARM processor mode. */
182 bool is_arm_mode(unsigned psr_mode)
183 {
184 for (unsigned i = 0; i < ARRAY_SIZE(arm_mode_data); i++) {
185 if (arm_mode_data[i].psr == psr_mode)
186 return true;
187 }
188 return false;
189 }
190
191 /** Map PSR mode bits to linear number indexing armv4_5_core_reg_map */
192 int arm_mode_to_number(enum arm_mode mode)
193 {
194 switch (mode) {
195 case ARM_MODE_ANY:
196 /* map MODE_ANY to user mode */
197 case ARM_MODE_USR:
198 return 0;
199 case ARM_MODE_FIQ:
200 return 1;
201 case ARM_MODE_IRQ:
202 return 2;
203 case ARM_MODE_SVC:
204 return 3;
205 case ARM_MODE_ABT:
206 return 4;
207 case ARM_MODE_UND:
208 return 5;
209 case ARM_MODE_SYS:
210 return 6;
211 case ARM_MODE_MON:
212 case ARM_MODE_1176_MON:
213 return 7;
214 case ARM_MODE_HYP:
215 return 8;
216 default:
217 LOG_ERROR("invalid mode value encountered %d", mode);
218 return -1;
219 }
220 }
221
222 /** Map linear number indexing armv4_5_core_reg_map to PSR mode bits. */
223 enum arm_mode armv4_5_number_to_mode(int number)
224 {
225 switch (number) {
226 case 0:
227 return ARM_MODE_USR;
228 case 1:
229 return ARM_MODE_FIQ;
230 case 2:
231 return ARM_MODE_IRQ;
232 case 3:
233 return ARM_MODE_SVC;
234 case 4:
235 return ARM_MODE_ABT;
236 case 5:
237 return ARM_MODE_UND;
238 case 6:
239 return ARM_MODE_SYS;
240 case 7:
241 return ARM_MODE_MON;
242 case 8:
243 return ARM_MODE_HYP;
244 default:
245 LOG_ERROR("mode index out of bounds %d", number);
246 return ARM_MODE_ANY;
247 }
248 }
249
250 static const char *arm_state_strings[] = {
251 "ARM", "Thumb", "Jazelle", "ThumbEE",
252 };
253
254 /* Templates for ARM core registers.
255 *
256 * NOTE: offsets in this table are coupled to the arm_mode_data
257 * table above, the armv4_5_core_reg_map array below, and also to
258 * the ARMV4_5_CPSR symbol (which should vanish after ARM11 updates).
259 */
260 static const struct {
261 /* The name is used for e.g. the "regs" command. */
262 const char *name;
263
264 /* The {cookie, mode} tuple uniquely identifies one register.
265 * In a given mode, cookies 0..15 map to registers R0..R15,
266 * with R13..R15 usually called SP, LR, PC.
267 *
268 * MODE_ANY is used as *input* to the mapping, and indicates
269 * various special cases (sigh) and errors.
270 *
271 * Cookie 16 is (currently) confusing, since it indicates
272 * CPSR -or- SPSR depending on whether 'mode' is MODE_ANY.
273 * (Exception modes have both CPSR and SPSR registers ...)
274 */
275 unsigned cookie;
276 unsigned gdb_index;
277 enum arm_mode mode;
278 } arm_core_regs[] = {
279 /* IMPORTANT: we guarantee that the first eight cached registers
280 * correspond to r0..r7, and the fifteenth to PC, so that callers
281 * don't need to map them.
282 */
283 [0] = { .name = "r0", .cookie = 0, .mode = ARM_MODE_ANY, .gdb_index = 0, },
284 [1] = { .name = "r1", .cookie = 1, .mode = ARM_MODE_ANY, .gdb_index = 1, },
285 [2] = { .name = "r2", .cookie = 2, .mode = ARM_MODE_ANY, .gdb_index = 2, },
286 [3] = { .name = "r3", .cookie = 3, .mode = ARM_MODE_ANY, .gdb_index = 3, },
287 [4] = { .name = "r4", .cookie = 4, .mode = ARM_MODE_ANY, .gdb_index = 4, },
288 [5] = { .name = "r5", .cookie = 5, .mode = ARM_MODE_ANY, .gdb_index = 5, },
289 [6] = { .name = "r6", .cookie = 6, .mode = ARM_MODE_ANY, .gdb_index = 6, },
290 [7] = { .name = "r7", .cookie = 7, .mode = ARM_MODE_ANY, .gdb_index = 7, },
291
292 /* NOTE: regs 8..12 might be shadowed by FIQ ... flagging
293 * them as MODE_ANY creates special cases. (ANY means
294 * "not mapped" elsewhere; here it's "everything but FIQ".)
295 */
296 [8] = { .name = "r8", .cookie = 8, .mode = ARM_MODE_ANY, .gdb_index = 8, },
297 [9] = { .name = "r9", .cookie = 9, .mode = ARM_MODE_ANY, .gdb_index = 9, },
298 [10] = { .name = "r10", .cookie = 10, .mode = ARM_MODE_ANY, .gdb_index = 10, },
299 [11] = { .name = "r11", .cookie = 11, .mode = ARM_MODE_ANY, .gdb_index = 11, },
300 [12] = { .name = "r12", .cookie = 12, .mode = ARM_MODE_ANY, .gdb_index = 12, },
301
302 /* Historical GDB mapping of indices:
303 * - 13-14 are sp and lr, but banked counterparts are used
304 * - 16-24 are left for deprecated 8 FPA + 1 FPS
305 * - 25 is the cpsr
306 */
307
308 /* NOTE all MODE_USR registers are equivalent to MODE_SYS ones */
309 [13] = { .name = "sp_usr", .cookie = 13, .mode = ARM_MODE_USR, .gdb_index = 26, },
310 [14] = { .name = "lr_usr", .cookie = 14, .mode = ARM_MODE_USR, .gdb_index = 27, },
311
312 /* guaranteed to be at index 15 */
313 [15] = { .name = "pc", .cookie = 15, .mode = ARM_MODE_ANY, .gdb_index = 15, },
314 [16] = { .name = "r8_fiq", .cookie = 8, .mode = ARM_MODE_FIQ, .gdb_index = 28, },
315 [17] = { .name = "r9_fiq", .cookie = 9, .mode = ARM_MODE_FIQ, .gdb_index = 29, },
316 [18] = { .name = "r10_fiq", .cookie = 10, .mode = ARM_MODE_FIQ, .gdb_index = 30, },
317 [19] = { .name = "r11_fiq", .cookie = 11, .mode = ARM_MODE_FIQ, .gdb_index = 31, },
318 [20] = { .name = "r12_fiq", .cookie = 12, .mode = ARM_MODE_FIQ, .gdb_index = 32, },
319
320 [21] = { .name = "sp_fiq", .cookie = 13, .mode = ARM_MODE_FIQ, .gdb_index = 33, },
321 [22] = { .name = "lr_fiq", .cookie = 14, .mode = ARM_MODE_FIQ, .gdb_index = 34, },
322
323 [23] = { .name = "sp_irq", .cookie = 13, .mode = ARM_MODE_IRQ, .gdb_index = 35, },
324 [24] = { .name = "lr_irq", .cookie = 14, .mode = ARM_MODE_IRQ, .gdb_index = 36, },
325
326 [25] = { .name = "sp_svc", .cookie = 13, .mode = ARM_MODE_SVC, .gdb_index = 37, },
327 [26] = { .name = "lr_svc", .cookie = 14, .mode = ARM_MODE_SVC, .gdb_index = 38, },
328
329 [27] = { .name = "sp_abt", .cookie = 13, .mode = ARM_MODE_ABT, .gdb_index = 39, },
330 [28] = { .name = "lr_abt", .cookie = 14, .mode = ARM_MODE_ABT, .gdb_index = 40, },
331
332 [29] = { .name = "sp_und", .cookie = 13, .mode = ARM_MODE_UND, .gdb_index = 41, },
333 [30] = { .name = "lr_und", .cookie = 14, .mode = ARM_MODE_UND, .gdb_index = 42, },
334
335 [31] = { .name = "cpsr", .cookie = 16, .mode = ARM_MODE_ANY, .gdb_index = 25, },
336 [32] = { .name = "spsr_fiq", .cookie = 16, .mode = ARM_MODE_FIQ, .gdb_index = 43, },
337 [33] = { .name = "spsr_irq", .cookie = 16, .mode = ARM_MODE_IRQ, .gdb_index = 44, },
338 [34] = { .name = "spsr_svc", .cookie = 16, .mode = ARM_MODE_SVC, .gdb_index = 45, },
339 [35] = { .name = "spsr_abt", .cookie = 16, .mode = ARM_MODE_ABT, .gdb_index = 46, },
340 [36] = { .name = "spsr_und", .cookie = 16, .mode = ARM_MODE_UND, .gdb_index = 47, },
341
342 /* These are only used for GDB target description, banked registers are accessed instead */
343 [37] = { .name = "sp", .cookie = 13, .mode = ARM_MODE_ANY, .gdb_index = 13, },
344 [38] = { .name = "lr", .cookie = 14, .mode = ARM_MODE_ANY, .gdb_index = 14, },
345
346 /* These exist only when the Security Extension (TrustZone) is present */
347 [39] = { .name = "sp_mon", .cookie = 13, .mode = ARM_MODE_MON, .gdb_index = 48, },
348 [40] = { .name = "lr_mon", .cookie = 14, .mode = ARM_MODE_MON, .gdb_index = 49, },
349 [41] = { .name = "spsr_mon", .cookie = 16, .mode = ARM_MODE_MON, .gdb_index = 50, },
350
351 /* These exist only when the Virtualization Extensions is present */
352 [42] = { .name = "sp_hyp", .cookie = 13, .mode = ARM_MODE_HYP, .gdb_index = 51, },
353 [43] = { .name = "spsr_hyp", .cookie = 16, .mode = ARM_MODE_HYP, .gdb_index = 52, },
354 };
355
356 static const struct {
357 unsigned int id;
358 const char *name;
359 uint32_t bits;
360 enum arm_mode mode;
361 enum reg_type type;
362 const char *group;
363 const char *feature;
364 } arm_vfp_v3_regs[] = {
365 { ARM_VFP_V3_D0, "d0", 64, ARM_MODE_ANY, REG_TYPE_IEEE_DOUBLE, NULL, "org.gnu.gdb.arm.vfp"},
366 { ARM_VFP_V3_D1, "d1", 64, ARM_MODE_ANY, REG_TYPE_IEEE_DOUBLE, NULL, "org.gnu.gdb.arm.vfp"},
367 { ARM_VFP_V3_D2, "d2", 64, ARM_MODE_ANY, REG_TYPE_IEEE_DOUBLE, NULL, "org.gnu.gdb.arm.vfp"},
368 { ARM_VFP_V3_D3, "d3", 64, ARM_MODE_ANY, REG_TYPE_IEEE_DOUBLE, NULL, "org.gnu.gdb.arm.vfp"},
369 { ARM_VFP_V3_D4, "d4", 64, ARM_MODE_ANY, REG_TYPE_IEEE_DOUBLE, NULL, "org.gnu.gdb.arm.vfp"},
370 { ARM_VFP_V3_D5, "d5", 64, ARM_MODE_ANY, REG_TYPE_IEEE_DOUBLE, NULL, "org.gnu.gdb.arm.vfp"},
371 { ARM_VFP_V3_D6, "d6", 64, ARM_MODE_ANY, REG_TYPE_IEEE_DOUBLE, NULL, "org.gnu.gdb.arm.vfp"},
372 { ARM_VFP_V3_D7, "d7", 64, ARM_MODE_ANY, REG_TYPE_IEEE_DOUBLE, NULL, "org.gnu.gdb.arm.vfp"},
373 { ARM_VFP_V3_D8, "d8", 64, ARM_MODE_ANY, REG_TYPE_IEEE_DOUBLE, NULL, "org.gnu.gdb.arm.vfp"},
374 { ARM_VFP_V3_D9, "d9", 64, ARM_MODE_ANY, REG_TYPE_IEEE_DOUBLE, NULL, "org.gnu.gdb.arm.vfp"},
375 { ARM_VFP_V3_D10, "d10", 64, ARM_MODE_ANY, REG_TYPE_IEEE_DOUBLE, NULL, "org.gnu.gdb.arm.vfp"},
376 { ARM_VFP_V3_D11, "d11", 64, ARM_MODE_ANY, REG_TYPE_IEEE_DOUBLE, NULL, "org.gnu.gdb.arm.vfp"},
377 { ARM_VFP_V3_D12, "d12", 64, ARM_MODE_ANY, REG_TYPE_IEEE_DOUBLE, NULL, "org.gnu.gdb.arm.vfp"},
378 { ARM_VFP_V3_D13, "d13", 64, ARM_MODE_ANY, REG_TYPE_IEEE_DOUBLE, NULL, "org.gnu.gdb.arm.vfp"},
379 { ARM_VFP_V3_D14, "d14", 64, ARM_MODE_ANY, REG_TYPE_IEEE_DOUBLE, NULL, "org.gnu.gdb.arm.vfp"},
380 { ARM_VFP_V3_D15, "d15", 64, ARM_MODE_ANY, REG_TYPE_IEEE_DOUBLE, NULL, "org.gnu.gdb.arm.vfp"},
381 { ARM_VFP_V3_D16, "d16", 64, ARM_MODE_ANY, REG_TYPE_IEEE_DOUBLE, NULL, "org.gnu.gdb.arm.vfp"},
382 { ARM_VFP_V3_D17, "d17", 64, ARM_MODE_ANY, REG_TYPE_IEEE_DOUBLE, NULL, "org.gnu.gdb.arm.vfp"},
383 { ARM_VFP_V3_D18, "d18", 64, ARM_MODE_ANY, REG_TYPE_IEEE_DOUBLE, NULL, "org.gnu.gdb.arm.vfp"},
384 { ARM_VFP_V3_D19, "d19", 64, ARM_MODE_ANY, REG_TYPE_IEEE_DOUBLE, NULL, "org.gnu.gdb.arm.vfp"},
385 { ARM_VFP_V3_D20, "d20", 64, ARM_MODE_ANY, REG_TYPE_IEEE_DOUBLE, NULL, "org.gnu.gdb.arm.vfp"},
386 { ARM_VFP_V3_D21, "d21", 64, ARM_MODE_ANY, REG_TYPE_IEEE_DOUBLE, NULL, "org.gnu.gdb.arm.vfp"},
387 { ARM_VFP_V3_D22, "d22", 64, ARM_MODE_ANY, REG_TYPE_IEEE_DOUBLE, NULL, "org.gnu.gdb.arm.vfp"},
388 { ARM_VFP_V3_D23, "d23", 64, ARM_MODE_ANY, REG_TYPE_IEEE_DOUBLE, NULL, "org.gnu.gdb.arm.vfp"},
389 { ARM_VFP_V3_D24, "d24", 64, ARM_MODE_ANY, REG_TYPE_IEEE_DOUBLE, NULL, "org.gnu.gdb.arm.vfp"},
390 { ARM_VFP_V3_D25, "d25", 64, ARM_MODE_ANY, REG_TYPE_IEEE_DOUBLE, NULL, "org.gnu.gdb.arm.vfp"},
391 { ARM_VFP_V3_D26, "d26", 64, ARM_MODE_ANY, REG_TYPE_IEEE_DOUBLE, NULL, "org.gnu.gdb.arm.vfp"},
392 { ARM_VFP_V3_D27, "d27", 64, ARM_MODE_ANY, REG_TYPE_IEEE_DOUBLE, NULL, "org.gnu.gdb.arm.vfp"},
393 { ARM_VFP_V3_D28, "d28", 64, ARM_MODE_ANY, REG_TYPE_IEEE_DOUBLE, NULL, "org.gnu.gdb.arm.vfp"},
394 { ARM_VFP_V3_D29, "d29", 64, ARM_MODE_ANY, REG_TYPE_IEEE_DOUBLE, NULL, "org.gnu.gdb.arm.vfp"},
395 { ARM_VFP_V3_D30, "d30", 64, ARM_MODE_ANY, REG_TYPE_IEEE_DOUBLE, NULL, "org.gnu.gdb.arm.vfp"},
396 { ARM_VFP_V3_D31, "d31", 64, ARM_MODE_ANY, REG_TYPE_IEEE_DOUBLE, NULL, "org.gnu.gdb.arm.vfp"},
397 { ARM_VFP_V3_FPSCR, "fpscr", 32, ARM_MODE_ANY, REG_TYPE_INT, "float", "org.gnu.gdb.arm.vfp"},
398 };
399
400 /* map core mode (USR, FIQ, ...) and register number to
401 * indices into the register cache
402 */
403 const int armv4_5_core_reg_map[9][17] = {
404 { /* USR */
405 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 31
406 },
407 { /* FIQ (8 shadows of USR, vs normal 3) */
408 0, 1, 2, 3, 4, 5, 6, 7, 16, 17, 18, 19, 20, 21, 22, 15, 32
409 },
410 { /* IRQ */
411 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 23, 24, 15, 33
412 },
413 { /* SVC */
414 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 25, 26, 15, 34
415 },
416 { /* ABT */
417 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 27, 28, 15, 35
418 },
419 { /* UND */
420 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 29, 30, 15, 36
421 },
422 { /* SYS (same registers as USR) */
423 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 31
424 },
425 { /* MON */
426 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 39, 40, 15, 41,
427 },
428 { /* HYP */
429 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 42, 14, 15, 43,
430 }
431 };
432
433 /**
434 * Configures host-side ARM records to reflect the specified CPSR.
435 * Later, code can use arm_reg_current() to map register numbers
436 * according to how they are exposed by this mode.
437 */
438 void arm_set_cpsr(struct arm *arm, uint32_t cpsr)
439 {
440 enum arm_mode mode = cpsr & 0x1f;
441 int num;
442
443 /* NOTE: this may be called very early, before the register
444 * cache is set up. We can't defend against many errors, in
445 * particular against CPSRs that aren't valid *here* ...
446 */
447 if (arm->cpsr) {
448 buf_set_u32(arm->cpsr->value, 0, 32, cpsr);
449 arm->cpsr->valid = true;
450 arm->cpsr->dirty = false;
451 }
452
453 arm->core_mode = mode;
454
455 /* mode_to_number() warned; set up a somewhat-sane mapping */
456 num = arm_mode_to_number(mode);
457 if (num < 0) {
458 mode = ARM_MODE_USR;
459 num = 0;
460 }
461
462 arm->map = &armv4_5_core_reg_map[num][0];
463 arm->spsr = (mode == ARM_MODE_USR || mode == ARM_MODE_SYS)
464 ? NULL
465 : arm->core_cache->reg_list + arm->map[16];
466
467 /* Older ARMs won't have the J bit */
468 enum arm_state state;
469
470 if (cpsr & (1 << 5)) { /* T */
471 if (cpsr & (1 << 24)) { /* J */
472 LOG_WARNING("ThumbEE -- incomplete support");
473 state = ARM_STATE_THUMB_EE;
474 } else
475 state = ARM_STATE_THUMB;
476 } else {
477 if (cpsr & (1 << 24)) { /* J */
478 LOG_ERROR("Jazelle state handling is BROKEN!");
479 state = ARM_STATE_JAZELLE;
480 } else
481 state = ARM_STATE_ARM;
482 }
483 arm->core_state = state;
484
485 LOG_DEBUG("set CPSR %#8.8x: %s mode, %s state", (unsigned) cpsr,
486 arm_mode_name(mode),
487 arm_state_strings[arm->core_state]);
488 }
489
490 /**
491 * Returns handle to the register currently mapped to a given number.
492 * Someone must have called arm_set_cpsr() before.
493 *
494 * \param arm This core's state and registers are used.
495 * \param regnum From 0..15 corresponding to R0..R14 and PC.
496 * Note that R0..R7 don't require mapping; you may access those
497 * as the first eight entries in the register cache. Likewise
498 * R15 (PC) doesn't need mapping; you may also access it directly.
499 * However, R8..R14, and SPSR (arm->spsr) *must* be mapped.
500 * CPSR (arm->cpsr) is also not mapped.
501 */
502 struct reg *arm_reg_current(struct arm *arm, unsigned regnum)
503 {
504 struct reg *r;
505
506 if (regnum > 16)
507 return NULL;
508
509 if (!arm->map) {
510 LOG_ERROR("Register map is not available yet, the target is not fully initialised");
511 r = arm->core_cache->reg_list + regnum;
512 } else
513 r = arm->core_cache->reg_list + arm->map[regnum];
514
515 /* e.g. invalid CPSR said "secure monitor" mode on a core
516 * that doesn't support it...
517 */
518 if (!r) {
519 LOG_ERROR("Invalid CPSR mode");
520 r = arm->core_cache->reg_list + regnum;
521 }
522
523 return r;
524 }
525
526 static const uint8_t arm_gdb_dummy_fp_value[12];
527
528 static struct reg_feature arm_gdb_dummy_fp_features = {
529 .name = "net.sourceforge.openocd.fake_fpa"
530 };
531
532 /**
533 * Dummy FPA registers are required to support GDB on ARM.
534 * Register packets require eight obsolete FPA register values.
535 * Modern ARM cores use Vector Floating Point (VFP), if they
536 * have any floating point support. VFP is not FPA-compatible.
537 */
538 struct reg arm_gdb_dummy_fp_reg = {
539 .name = "GDB dummy FPA register",
540 .value = (uint8_t *) arm_gdb_dummy_fp_value,
541 .valid = true,
542 .size = 96,
543 .exist = false,
544 .number = 16,
545 .feature = &arm_gdb_dummy_fp_features,
546 .group = "fake_fpa",
547 };
548
549 static const uint8_t arm_gdb_dummy_fps_value[4];
550
551 /**
552 * Dummy FPA status registers are required to support GDB on ARM.
553 * Register packets require an obsolete FPA status register.
554 */
555 struct reg arm_gdb_dummy_fps_reg = {
556 .name = "GDB dummy FPA status register",
557 .value = (uint8_t *) arm_gdb_dummy_fps_value,
558 .valid = true,
559 .size = 32,
560 .exist = false,
561 .number = 24,
562 .feature = &arm_gdb_dummy_fp_features,
563 .group = "fake_fpa",
564 };
565
566 static void arm_gdb_dummy_init(void) __attribute__ ((constructor));
567
568 static void arm_gdb_dummy_init(void)
569 {
570 register_init_dummy(&arm_gdb_dummy_fp_reg);
571 register_init_dummy(&arm_gdb_dummy_fps_reg);
572 }
573
574 static int armv4_5_get_core_reg(struct reg *reg)
575 {
576 int retval;
577 struct arm_reg *reg_arch_info = reg->arch_info;
578 struct target *target = reg_arch_info->target;
579
580 if (target->state != TARGET_HALTED) {
581 LOG_ERROR("Target not halted");
582 return ERROR_TARGET_NOT_HALTED;
583 }
584
585 retval = reg_arch_info->arm->read_core_reg(target, reg,
586 reg_arch_info->num, reg_arch_info->mode);
587 if (retval == ERROR_OK) {
588 reg->valid = true;
589 reg->dirty = false;
590 }
591
592 return retval;
593 }
594
595 static int armv4_5_set_core_reg(struct reg *reg, uint8_t *buf)
596 {
597 struct arm_reg *reg_arch_info = reg->arch_info;
598 struct target *target = reg_arch_info->target;
599 struct arm *armv4_5_target = target_to_arm(target);
600 uint32_t value = buf_get_u32(buf, 0, 32);
601
602 if (target->state != TARGET_HALTED) {
603 LOG_ERROR("Target not halted");
604 return ERROR_TARGET_NOT_HALTED;
605 }
606
607 /* Except for CPSR, the "reg" command exposes a writeback model
608 * for the register cache.
609 */
610 if (reg == armv4_5_target->cpsr) {
611 arm_set_cpsr(armv4_5_target, value);
612
613 /* Older cores need help to be in ARM mode during halt
614 * mode debug, so we clear the J and T bits if we flush.
615 * For newer cores (v6/v7a/v7r) we don't need that, but
616 * it won't hurt since CPSR is always flushed anyway.
617 */
618 if (armv4_5_target->core_mode !=
619 (enum arm_mode)(value & 0x1f)) {
620 LOG_DEBUG("changing ARM core mode to '%s'",
621 arm_mode_name(value & 0x1f));
622 value &= ~((1 << 24) | (1 << 5));
623 uint8_t t[4];
624 buf_set_u32(t, 0, 32, value);
625 armv4_5_target->write_core_reg(target, reg,
626 16, ARM_MODE_ANY, t);
627 }
628 } else {
629 buf_set_u32(reg->value, 0, 32, value);
630 if (reg->size == 64) {
631 value = buf_get_u32(buf + 4, 0, 32);
632 buf_set_u32(reg->value + 4, 0, 32, value);
633 }
634 reg->valid = true;
635 }
636 reg->dirty = true;
637
638 return ERROR_OK;
639 }
640
641 static const struct reg_arch_type arm_reg_type = {
642 .get = armv4_5_get_core_reg,
643 .set = armv4_5_set_core_reg,
644 };
645
646 struct reg_cache *arm_build_reg_cache(struct target *target, struct arm *arm)
647 {
648 int num_regs = ARRAY_SIZE(arm_core_regs);
649 int num_core_regs = num_regs;
650 if (arm->arm_vfp_version == ARM_VFP_V3)
651 num_regs += ARRAY_SIZE(arm_vfp_v3_regs);
652
653 struct reg_cache *cache = malloc(sizeof(struct reg_cache));
654 struct reg *reg_list = calloc(num_regs, sizeof(struct reg));
655 struct arm_reg *reg_arch_info = calloc(num_regs, sizeof(struct arm_reg));
656 int i;
657
658 if (!cache || !reg_list || !reg_arch_info) {
659 free(cache);
660 free(reg_list);
661 free(reg_arch_info);
662 return NULL;
663 }
664
665 cache->name = "ARM registers";
666 cache->next = NULL;
667 cache->reg_list = reg_list;
668 cache->num_regs = 0;
669
670 for (i = 0; i < num_core_regs; i++) {
671 /* Skip registers this core doesn't expose */
672 if (arm_core_regs[i].mode == ARM_MODE_MON
673 && arm->core_type != ARM_CORE_TYPE_SEC_EXT
674 && arm->core_type != ARM_CORE_TYPE_VIRT_EXT)
675 continue;
676 if (arm_core_regs[i].mode == ARM_MODE_HYP
677 && arm->core_type != ARM_CORE_TYPE_VIRT_EXT)
678 continue;
679
680 /* REVISIT handle Cortex-M, which only shadows R13/SP */
681
682 reg_arch_info[i].num = arm_core_regs[i].cookie;
683 reg_arch_info[i].mode = arm_core_regs[i].mode;
684 reg_arch_info[i].target = target;
685 reg_arch_info[i].arm = arm;
686
687 reg_list[i].name = arm_core_regs[i].name;
688 reg_list[i].number = arm_core_regs[i].gdb_index;
689 reg_list[i].size = 32;
690 reg_list[i].value = reg_arch_info[i].value;
691 reg_list[i].type = &arm_reg_type;
692 reg_list[i].arch_info = &reg_arch_info[i];
693 reg_list[i].exist = true;
694
695 /* This really depends on the calling convention in use */
696 reg_list[i].caller_save = false;
697
698 /* Registers data type, as used by GDB target description */
699 reg_list[i].reg_data_type = malloc(sizeof(struct reg_data_type));
700 switch (arm_core_regs[i].cookie) {
701 case 13:
702 reg_list[i].reg_data_type->type = REG_TYPE_DATA_PTR;
703 break;
704 case 14:
705 case 15:
706 reg_list[i].reg_data_type->type = REG_TYPE_CODE_PTR;
707 break;
708 default:
709 reg_list[i].reg_data_type->type = REG_TYPE_UINT32;
710 break;
711 }
712
713 /* let GDB shows banked registers only in "info all-reg" */
714 reg_list[i].feature = malloc(sizeof(struct reg_feature));
715 if (reg_list[i].number <= 15 || reg_list[i].number == 25) {
716 reg_list[i].feature->name = "org.gnu.gdb.arm.core";
717 reg_list[i].group = "general";
718 } else {
719 reg_list[i].feature->name = "net.sourceforge.openocd.banked";
720 reg_list[i].group = "banked";
721 }
722
723 cache->num_regs++;
724 }
725
726 int j;
727 for (i = num_core_regs, j = 0; i < num_regs; i++, j++) {
728 reg_arch_info[i].num = arm_vfp_v3_regs[j].id;
729 reg_arch_info[i].mode = arm_vfp_v3_regs[j].mode;
730 reg_arch_info[i].target = target;
731 reg_arch_info[i].arm = arm;
732
733 reg_list[i].name = arm_vfp_v3_regs[j].name;
734 reg_list[i].number = arm_vfp_v3_regs[j].id;
735 reg_list[i].size = arm_vfp_v3_regs[j].bits;
736 reg_list[i].value = reg_arch_info[i].value;
737 reg_list[i].type = &arm_reg_type;
738 reg_list[i].arch_info = &reg_arch_info[i];
739 reg_list[i].exist = true;
740
741 reg_list[i].caller_save = false;
742
743 reg_list[i].reg_data_type = malloc(sizeof(struct reg_data_type));
744 reg_list[i].reg_data_type->type = arm_vfp_v3_regs[j].type;
745
746 reg_list[i].feature = malloc(sizeof(struct reg_feature));
747 reg_list[i].feature->name = arm_vfp_v3_regs[j].feature;
748
749 reg_list[i].group = arm_vfp_v3_regs[j].group;
750
751 cache->num_regs++;
752 }
753
754 arm->pc = reg_list + 15;
755 arm->cpsr = reg_list + ARMV4_5_CPSR;
756 arm->core_cache = cache;
757
758 return cache;
759 }
760
761 void arm_free_reg_cache(struct arm *arm)
762 {
763 if (!arm || !arm->core_cache)
764 return;
765
766 struct reg_cache *cache = arm->core_cache;
767
768 for (unsigned int i = 0; i < cache->num_regs; i++) {
769 struct reg *reg = &cache->reg_list[i];
770
771 free(reg->feature);
772 free(reg->reg_data_type);
773 }
774
775 free(cache->reg_list[0].arch_info);
776 free(cache->reg_list);
777 free(cache);
778
779 arm->core_cache = NULL;
780 }
781
782 int arm_arch_state(struct target *target)
783 {
784 struct arm *arm = target_to_arm(target);
785
786 if (arm->common_magic != ARM_COMMON_MAGIC) {
787 LOG_ERROR("BUG: called for a non-ARM target");
788 return ERROR_FAIL;
789 }
790
791 /* avoid filling log waiting for fileio reply */
792 if (target->semihosting && target->semihosting->hit_fileio)
793 return ERROR_OK;
794
795 LOG_USER("target halted in %s state due to %s, current mode: %s\n"
796 "cpsr: 0x%8.8" PRIx32 " pc: 0x%8.8" PRIx32 "%s%s",
797 arm_state_strings[arm->core_state],
798 debug_reason_name(target),
799 arm_mode_name(arm->core_mode),
800 buf_get_u32(arm->cpsr->value, 0, 32),
801 buf_get_u32(arm->pc->value, 0, 32),
802 (target->semihosting && target->semihosting->is_active) ? ", semihosting" : "",
803 (target->semihosting && target->semihosting->is_fileio) ? " fileio" : "");
804
805 return ERROR_OK;
806 }
807
808 COMMAND_HANDLER(handle_armv4_5_reg_command)
809 {
810 struct target *target = get_current_target(CMD_CTX);
811 struct arm *arm = target_to_arm(target);
812 struct reg *regs;
813
814 if (!is_arm(arm)) {
815 command_print(CMD, "current target isn't an ARM");
816 return ERROR_FAIL;
817 }
818
819 if (target->state != TARGET_HALTED) {
820 command_print(CMD, "error: target must be halted for register accesses");
821 return ERROR_FAIL;
822 }
823
824 if (arm->core_type != ARM_CORE_TYPE_STD) {
825 command_print(CMD,
826 "Microcontroller Profile not supported - use standard reg cmd");
827 return ERROR_OK;
828 }
829
830 if (!is_arm_mode(arm->core_mode)) {
831 LOG_ERROR("not a valid arm core mode - communication failure?");
832 return ERROR_FAIL;
833 }
834
835 if (!arm->full_context) {
836 command_print(CMD, "error: target doesn't support %s",
837 CMD_NAME);
838 return ERROR_FAIL;
839 }
840
841 regs = arm->core_cache->reg_list;
842
843 for (unsigned mode = 0; mode < ARRAY_SIZE(arm_mode_data); mode++) {
844 const char *name;
845 char *sep = "\n";
846 char *shadow = "";
847
848 if (!arm_mode_data[mode].n_indices)
849 continue;
850
851 /* label this bank of registers (or shadows) */
852 switch (arm_mode_data[mode].psr) {
853 case ARM_MODE_SYS:
854 continue;
855 case ARM_MODE_USR:
856 name = "System and User";
857 sep = "";
858 break;
859 case ARM_MODE_HYP:
860 if (arm->core_type != ARM_CORE_TYPE_VIRT_EXT)
861 continue;
862 /* FALLTHROUGH */
863 case ARM_MODE_MON:
864 case ARM_MODE_1176_MON:
865 if (arm->core_type != ARM_CORE_TYPE_SEC_EXT
866 && arm->core_type != ARM_CORE_TYPE_VIRT_EXT)
867 continue;
868 /* FALLTHROUGH */
869 default:
870 name = arm_mode_data[mode].name;
871 shadow = "shadow ";
872 break;
873 }
874 command_print(CMD, "%s%s mode %sregisters",
875 sep, name, shadow);
876
877 /* display N rows of up to 4 registers each */
878 for (unsigned i = 0; i < arm_mode_data[mode].n_indices; ) {
879 char output[80];
880 int output_len = 0;
881
882 for (unsigned j = 0; j < 4; j++, i++) {
883 uint32_t value;
884 struct reg *reg = regs;
885
886 if (i >= arm_mode_data[mode].n_indices)
887 break;
888
889 reg += arm_mode_data[mode].indices[i];
890
891 /* REVISIT be smarter about faults... */
892 if (!reg->valid)
893 arm->full_context(target);
894
895 value = buf_get_u32(reg->value, 0, 32);
896 output_len += snprintf(output + output_len,
897 sizeof(output) - output_len,
898 "%8s: %8.8" PRIx32 " ",
899 reg->name, value);
900 }
901 command_print(CMD, "%s", output);
902 }
903 }
904
905 return ERROR_OK;
906 }
907
908 COMMAND_HANDLER(handle_armv4_5_core_state_command)
909 {
910 struct target *target = get_current_target(CMD_CTX);
911 struct arm *arm = target_to_arm(target);
912
913 if (!is_arm(arm)) {
914 command_print(CMD, "current target isn't an ARM");
915 return ERROR_FAIL;
916 }
917
918 if (arm->core_type == ARM_CORE_TYPE_M_PROFILE) {
919 /* armv7m not supported */
920 command_print(CMD, "Unsupported Command");
921 return ERROR_OK;
922 }
923
924 if (CMD_ARGC > 0) {
925 if (strcmp(CMD_ARGV[0], "arm") == 0)
926 arm->core_state = ARM_STATE_ARM;
927 if (strcmp(CMD_ARGV[0], "thumb") == 0)
928 arm->core_state = ARM_STATE_THUMB;
929 }
930
931 command_print(CMD, "core state: %s", arm_state_strings[arm->core_state]);
932
933 return ERROR_OK;
934 }
935
936 COMMAND_HANDLER(handle_arm_disassemble_command)
937 {
938 #if HAVE_CAPSTONE
939 struct target *target = get_current_target(CMD_CTX);
940
941 if (!target) {
942 LOG_ERROR("No target selected");
943 return ERROR_FAIL;
944 }
945
946 struct arm *arm = target_to_arm(target);
947 target_addr_t address;
948 unsigned int count = 1;
949 bool thumb = false;
950
951 if (!is_arm(arm)) {
952 command_print(CMD, "current target isn't an ARM");
953 return ERROR_FAIL;
954 }
955
956 if (arm->core_type == ARM_CORE_TYPE_M_PROFILE) {
957 /* armv7m is always thumb mode */
958 thumb = true;
959 }
960
961 switch (CMD_ARGC) {
962 case 3:
963 if (strcmp(CMD_ARGV[2], "thumb") != 0)
964 return ERROR_COMMAND_SYNTAX_ERROR;
965 thumb = true;
966 /* FALL THROUGH */
967 case 2:
968 COMMAND_PARSE_NUMBER(uint, CMD_ARGV[1], count);
969 /* FALL THROUGH */
970 case 1:
971 COMMAND_PARSE_ADDRESS(CMD_ARGV[0], address);
972 if (address & 0x01) {
973 if (!thumb) {
974 command_print(CMD, "Disassemble as Thumb");
975 thumb = true;
976 }
977 address &= ~1;
978 }
979 break;
980 default:
981 return ERROR_COMMAND_SYNTAX_ERROR;
982 }
983
984 return arm_disassemble(CMD, target, address, count, thumb);
985 #else
986 command_print(CMD, "capstone disassembly framework required");
987 return ERROR_FAIL;
988 #endif
989 }
990
991 static int jim_mcrmrc(Jim_Interp *interp, int argc, Jim_Obj * const *argv)
992 {
993 struct command_context *context;
994 struct target *target;
995 struct arm *arm;
996 int retval;
997
998 context = current_command_context(interp);
999 assert(context);
1000
1001 target = get_current_target(context);
1002 if (!target) {
1003 LOG_ERROR("%s: no current target", __func__);
1004 return JIM_ERR;
1005 }
1006 if (!target_was_examined(target)) {
1007 LOG_ERROR("%s: not yet examined", target_name(target));
1008 return JIM_ERR;
1009 }
1010 arm = target_to_arm(target);
1011 if (!is_arm(arm)) {
1012 LOG_ERROR("%s: not an ARM", target_name(target));
1013 return JIM_ERR;
1014 }
1015
1016 if ((argc < 6) || (argc > 7)) {
1017 /* FIXME use the command name to verify # params... */
1018 LOG_ERROR("%s: wrong number of arguments", __func__);
1019 return JIM_ERR;
1020 }
1021
1022 int cpnum;
1023 uint32_t op1;
1024 uint32_t op2;
1025 uint32_t crn;
1026 uint32_t crm;
1027 uint32_t value;
1028 long l;
1029
1030 /* NOTE: parameter sequence matches ARM instruction set usage:
1031 * MCR pNUM, op1, rX, CRn, CRm, op2 ; write CP from rX
1032 * MRC pNUM, op1, rX, CRn, CRm, op2 ; read CP into rX
1033 * The "rX" is necessarily omitted; it uses Tcl mechanisms.
1034 */
1035 retval = Jim_GetLong(interp, argv[1], &l);
1036 if (retval != JIM_OK)
1037 return retval;
1038 if (l & ~0xf) {
1039 LOG_ERROR("%s: %s %d out of range", __func__,
1040 "coprocessor", (int) l);
1041 return JIM_ERR;
1042 }
1043 cpnum = l;
1044
1045 retval = Jim_GetLong(interp, argv[2], &l);
1046 if (retval != JIM_OK)
1047 return retval;
1048 if (l & ~0x7) {
1049 LOG_ERROR("%s: %s %d out of range", __func__,
1050 "op1", (int) l);
1051 return JIM_ERR;
1052 }
1053 op1 = l;
1054
1055 retval = Jim_GetLong(interp, argv[3], &l);
1056 if (retval != JIM_OK)
1057 return retval;
1058 if (l & ~0xf) {
1059 LOG_ERROR("%s: %s %d out of range", __func__,
1060 "CRn", (int) l);
1061 return JIM_ERR;
1062 }
1063 crn = l;
1064
1065 retval = Jim_GetLong(interp, argv[4], &l);
1066 if (retval != JIM_OK)
1067 return retval;
1068 if (l & ~0xf) {
1069 LOG_ERROR("%s: %s %d out of range", __func__,
1070 "CRm", (int) l);
1071 return JIM_ERR;
1072 }
1073 crm = l;
1074
1075 retval = Jim_GetLong(interp, argv[5], &l);
1076 if (retval != JIM_OK)
1077 return retval;
1078 if (l & ~0x7) {
1079 LOG_ERROR("%s: %s %d out of range", __func__,
1080 "op2", (int) l);
1081 return JIM_ERR;
1082 }
1083 op2 = l;
1084
1085 value = 0;
1086
1087 /* FIXME don't assume "mrc" vs "mcr" from the number of params;
1088 * that could easily be a typo! Check both...
1089 *
1090 * FIXME change the call syntax here ... simplest to just pass
1091 * the MRC() or MCR() instruction to be executed. That will also
1092 * let us support the "mrc2" and "mcr2" opcodes (toggling one bit)
1093 * if that's ever needed.
1094 */
1095 if (argc == 7) {
1096 retval = Jim_GetLong(interp, argv[6], &l);
1097 if (retval != JIM_OK)
1098 return retval;
1099 value = l;
1100
1101 /* NOTE: parameters reordered! */
1102 /* ARMV4_5_MCR(cpnum, op1, 0, crn, crm, op2) */
1103 retval = arm->mcr(target, cpnum, op1, op2, crn, crm, value);
1104 if (retval != ERROR_OK)
1105 return JIM_ERR;
1106 } else {
1107 /* NOTE: parameters reordered! */
1108 /* ARMV4_5_MRC(cpnum, op1, 0, crn, crm, op2) */
1109 retval = arm->mrc(target, cpnum, op1, op2, crn, crm, &value);
1110 if (retval != ERROR_OK)
1111 return JIM_ERR;
1112
1113 Jim_SetResult(interp, Jim_NewIntObj(interp, value));
1114 }
1115
1116 return JIM_OK;
1117 }
1118
1119 extern const struct command_registration semihosting_common_handlers[];
1120
1121 static const struct command_registration arm_exec_command_handlers[] = {
1122 {
1123 .name = "reg",
1124 .handler = handle_armv4_5_reg_command,
1125 .mode = COMMAND_EXEC,
1126 .help = "display ARM core registers",
1127 .usage = "",
1128 },
1129 {
1130 .name = "core_state",
1131 .handler = handle_armv4_5_core_state_command,
1132 .mode = COMMAND_EXEC,
1133 .usage = "['arm'|'thumb']",
1134 .help = "display/change ARM core state",
1135 },
1136 {
1137 .name = "disassemble",
1138 .handler = handle_arm_disassemble_command,
1139 .mode = COMMAND_EXEC,
1140 .usage = "address [count ['thumb']]",
1141 .help = "disassemble instructions",
1142 },
1143 {
1144 .name = "mcr",
1145 .mode = COMMAND_EXEC,
1146 .jim_handler = &jim_mcrmrc,
1147 .help = "write coprocessor register",
1148 .usage = "cpnum op1 CRn CRm op2 value",
1149 },
1150 {
1151 .name = "mrc",
1152 .mode = COMMAND_EXEC,
1153 .jim_handler = &jim_mcrmrc,
1154 .help = "read coprocessor register",
1155 .usage = "cpnum op1 CRn CRm op2",
1156 },
1157 {
1158 .chain = semihosting_common_handlers,
1159 },
1160 COMMAND_REGISTRATION_DONE
1161 };
1162 const struct command_registration arm_command_handlers[] = {
1163 {
1164 .name = "arm",
1165 .mode = COMMAND_ANY,
1166 .help = "ARM command group",
1167 .usage = "",
1168 .chain = arm_exec_command_handlers,
1169 },
1170 COMMAND_REGISTRATION_DONE
1171 };
1172
1173 /*
1174 * gdb for arm targets (e.g. arm-none-eabi-gdb) supports several variants
1175 * of arm architecture. You can list them using the autocompletion of gdb
1176 * command prompt by typing "set architecture " and then press TAB key.
1177 * The default, selected automatically, is "arm".
1178 * Let's use the default value, here, to make gdb-multiarch behave in the
1179 * same way as a gdb for arm. This can be changed later on. User can still
1180 * set the specific architecture variant with the gdb command.
1181 */
1182 const char *arm_get_gdb_arch(struct target *target)
1183 {
1184 return "arm";
1185 }
1186
1187 int arm_get_gdb_reg_list(struct target *target,
1188 struct reg **reg_list[], int *reg_list_size,
1189 enum target_register_class reg_class)
1190 {
1191 struct arm *arm = target_to_arm(target);
1192 unsigned int i;
1193
1194 if (!is_arm_mode(arm->core_mode)) {
1195 LOG_ERROR("not a valid arm core mode - communication failure?");
1196 return ERROR_FAIL;
1197 }
1198
1199 switch (reg_class) {
1200 case REG_CLASS_GENERAL:
1201 *reg_list_size = 26;
1202 *reg_list = malloc(sizeof(struct reg *) * (*reg_list_size));
1203
1204 for (i = 0; i < 16; i++)
1205 (*reg_list)[i] = arm_reg_current(arm, i);
1206
1207 /* For GDB compatibility, take FPA registers size into account and zero-fill it*/
1208 for (i = 16; i < 24; i++)
1209 (*reg_list)[i] = &arm_gdb_dummy_fp_reg;
1210 (*reg_list)[24] = &arm_gdb_dummy_fps_reg;
1211
1212 (*reg_list)[25] = arm->cpsr;
1213
1214 return ERROR_OK;
1215
1216 case REG_CLASS_ALL:
1217 switch (arm->core_type) {
1218 case ARM_CORE_TYPE_SEC_EXT:
1219 *reg_list_size = 51;
1220 break;
1221 case ARM_CORE_TYPE_VIRT_EXT:
1222 *reg_list_size = 53;
1223 break;
1224 default:
1225 *reg_list_size = 48;
1226 }
1227 unsigned int list_size_core = *reg_list_size;
1228 if (arm->arm_vfp_version == ARM_VFP_V3)
1229 *reg_list_size += 33;
1230
1231 *reg_list = malloc(sizeof(struct reg *) * (*reg_list_size));
1232
1233 for (i = 0; i < 16; i++)
1234 (*reg_list)[i] = arm_reg_current(arm, i);
1235
1236 for (i = 13; i < ARRAY_SIZE(arm_core_regs); i++) {
1237 int reg_index = arm->core_cache->reg_list[i].number;
1238
1239 if (arm_core_regs[i].mode == ARM_MODE_MON
1240 && arm->core_type != ARM_CORE_TYPE_SEC_EXT
1241 && arm->core_type != ARM_CORE_TYPE_VIRT_EXT)
1242 continue;
1243 if (arm_core_regs[i].mode == ARM_MODE_HYP
1244 && arm->core_type != ARM_CORE_TYPE_VIRT_EXT)
1245 continue;
1246 (*reg_list)[reg_index] = &(arm->core_cache->reg_list[i]);
1247 }
1248
1249 /* When we supply the target description, there is no need for fake FPA */
1250 for (i = 16; i < 24; i++) {
1251 (*reg_list)[i] = &arm_gdb_dummy_fp_reg;
1252 (*reg_list)[i]->size = 0;
1253 }
1254 (*reg_list)[24] = &arm_gdb_dummy_fps_reg;
1255 (*reg_list)[24]->size = 0;
1256
1257 if (arm->arm_vfp_version == ARM_VFP_V3) {
1258 unsigned int num_core_regs = ARRAY_SIZE(arm_core_regs);
1259 for (i = 0; i < 33; i++)
1260 (*reg_list)[list_size_core + i] = &(arm->core_cache->reg_list[num_core_regs + i]);
1261 }
1262
1263 return ERROR_OK;
1264
1265 default:
1266 LOG_ERROR("not a valid register class type in query.");
1267 return ERROR_FAIL;
1268 }
1269 }
1270
1271 /* wait for execution to complete and check exit point */
1272 static int armv4_5_run_algorithm_completion(struct target *target,
1273 uint32_t exit_point,
1274 int timeout_ms,
1275 void *arch_info)
1276 {
1277 int retval;
1278 struct arm *arm = target_to_arm(target);
1279
1280 retval = target_wait_state(target, TARGET_HALTED, timeout_ms);
1281 if (retval != ERROR_OK)
1282 return retval;
1283 if (target->state != TARGET_HALTED) {
1284 retval = target_halt(target);
1285 if (retval != ERROR_OK)
1286 return retval;
1287 retval = target_wait_state(target, TARGET_HALTED, 500);
1288 if (retval != ERROR_OK)
1289 return retval;
1290 return ERROR_TARGET_TIMEOUT;
1291 }
1292
1293 /* fast exit: ARMv5+ code can use BKPT */
1294 if (exit_point && buf_get_u32(arm->pc->value, 0, 32) != exit_point) {
1295 LOG_WARNING(
1296 "target reentered debug state, but not at the desired exit point: 0x%4.4" PRIx32 "",
1297 buf_get_u32(arm->pc->value, 0, 32));
1298 return ERROR_TARGET_TIMEOUT;
1299 }
1300
1301 return ERROR_OK;
1302 }
1303
1304 int armv4_5_run_algorithm_inner(struct target *target,
1305 int num_mem_params, struct mem_param *mem_params,
1306 int num_reg_params, struct reg_param *reg_params,
1307 uint32_t entry_point, uint32_t exit_point,
1308 int timeout_ms, void *arch_info,
1309 int (*run_it)(struct target *target, uint32_t exit_point,
1310 int timeout_ms, void *arch_info))
1311 {
1312 struct arm *arm = target_to_arm(target);
1313 struct arm_algorithm *arm_algorithm_info = arch_info;
1314 enum arm_state core_state = arm->core_state;
1315 uint32_t context[17];
1316 uint32_t cpsr;
1317 int exit_breakpoint_size = 0;
1318 int i;
1319 int retval = ERROR_OK;
1320
1321 LOG_DEBUG("Running algorithm");
1322
1323 if (arm_algorithm_info->common_magic != ARM_COMMON_MAGIC) {
1324 LOG_ERROR("current target isn't an ARMV4/5 target");
1325 return ERROR_TARGET_INVALID;
1326 }
1327
1328 if (target->state != TARGET_HALTED) {
1329 LOG_WARNING("target not halted");
1330 return ERROR_TARGET_NOT_HALTED;
1331 }
1332
1333 if (!is_arm_mode(arm->core_mode)) {
1334 LOG_ERROR("not a valid arm core mode - communication failure?");
1335 return ERROR_FAIL;
1336 }
1337
1338 /* armv5 and later can terminate with BKPT instruction; less overhead */
1339 if (!exit_point && arm->arch == ARM_ARCH_V4) {
1340 LOG_ERROR("ARMv4 target needs HW breakpoint location");
1341 return ERROR_FAIL;
1342 }
1343
1344 /* save r0..pc, cpsr-or-spsr, and then cpsr-for-sure;
1345 * they'll be restored later.
1346 */
1347 for (i = 0; i <= 16; i++) {
1348 struct reg *r;
1349
1350 r = &ARMV4_5_CORE_REG_MODE(arm->core_cache,
1351 arm_algorithm_info->core_mode, i);
1352 if (!r->valid)
1353 arm->read_core_reg(target, r, i,
1354 arm_algorithm_info->core_mode);
1355 context[i] = buf_get_u32(r->value, 0, 32);
1356 }
1357 cpsr = buf_get_u32(arm->cpsr->value, 0, 32);
1358
1359 for (i = 0; i < num_mem_params; i++) {
1360 if (mem_params[i].direction == PARAM_IN)
1361 continue;
1362 retval = target_write_buffer(target, mem_params[i].address, mem_params[i].size,
1363 mem_params[i].value);
1364 if (retval != ERROR_OK)
1365 return retval;
1366 }
1367
1368 for (i = 0; i < num_reg_params; i++) {
1369 if (reg_params[i].direction == PARAM_IN)
1370 continue;
1371
1372 struct reg *reg = register_get_by_name(arm->core_cache, reg_params[i].reg_name, false);
1373 if (!reg) {
1374 LOG_ERROR("BUG: register '%s' not found", reg_params[i].reg_name);
1375 return ERROR_COMMAND_SYNTAX_ERROR;
1376 }
1377
1378 if (reg->size != reg_params[i].size) {
1379 LOG_ERROR("BUG: register '%s' size doesn't match reg_params[i].size",
1380 reg_params[i].reg_name);
1381 return ERROR_COMMAND_SYNTAX_ERROR;
1382 }
1383
1384 retval = armv4_5_set_core_reg(reg, reg_params[i].value);
1385 if (retval != ERROR_OK)
1386 return retval;
1387 }
1388
1389 arm->core_state = arm_algorithm_info->core_state;
1390 if (arm->core_state == ARM_STATE_ARM)
1391 exit_breakpoint_size = 4;
1392 else if (arm->core_state == ARM_STATE_THUMB)
1393 exit_breakpoint_size = 2;
1394 else {
1395 LOG_ERROR("BUG: can't execute algorithms when not in ARM or Thumb state");
1396 return ERROR_COMMAND_SYNTAX_ERROR;
1397 }
1398
1399 if (arm_algorithm_info->core_mode != ARM_MODE_ANY) {
1400 LOG_DEBUG("setting core_mode: 0x%2.2x",
1401 arm_algorithm_info->core_mode);
1402 buf_set_u32(arm->cpsr->value, 0, 5,
1403 arm_algorithm_info->core_mode);
1404 arm->cpsr->dirty = true;
1405 arm->cpsr->valid = true;
1406 }
1407
1408 /* terminate using a hardware or (ARMv5+) software breakpoint */
1409 if (exit_point) {
1410 retval = breakpoint_add(target, exit_point,
1411 exit_breakpoint_size, BKPT_HARD);
1412 if (retval != ERROR_OK) {
1413 LOG_ERROR("can't add HW breakpoint to terminate algorithm");
1414 return ERROR_TARGET_FAILURE;
1415 }
1416 }
1417
1418 retval = target_resume(target, 0, entry_point, 1, 1);
1419 if (retval != ERROR_OK)
1420 return retval;
1421 retval = run_it(target, exit_point, timeout_ms, arch_info);
1422
1423 if (exit_point)
1424 breakpoint_remove(target, exit_point);
1425
1426 if (retval != ERROR_OK)
1427 return retval;
1428
1429 for (i = 0; i < num_mem_params; i++) {
1430 if (mem_params[i].direction != PARAM_OUT) {
1431 int retvaltemp = target_read_buffer(target, mem_params[i].address,
1432 mem_params[i].size,
1433 mem_params[i].value);
1434 if (retvaltemp != ERROR_OK)
1435 retval = retvaltemp;
1436 }
1437 }
1438
1439 for (i = 0; i < num_reg_params; i++) {
1440 if (reg_params[i].direction != PARAM_OUT) {
1441
1442 struct reg *reg = register_get_by_name(arm->core_cache,
1443 reg_params[i].reg_name,
1444 false);
1445 if (!reg) {
1446 LOG_ERROR("BUG: register '%s' not found", reg_params[i].reg_name);
1447 retval = ERROR_COMMAND_SYNTAX_ERROR;
1448 continue;
1449 }
1450
1451 if (reg->size != reg_params[i].size) {
1452 LOG_ERROR(
1453 "BUG: register '%s' size doesn't match reg_params[i].size",
1454 reg_params[i].reg_name);
1455 retval = ERROR_COMMAND_SYNTAX_ERROR;
1456 continue;
1457 }
1458
1459 buf_set_u32(reg_params[i].value, 0, 32, buf_get_u32(reg->value, 0, 32));
1460 }
1461 }
1462
1463 /* restore everything we saved before (17 or 18 registers) */
1464 for (i = 0; i <= 16; i++) {
1465 uint32_t regvalue;
1466 regvalue = buf_get_u32(ARMV4_5_CORE_REG_MODE(arm->core_cache,
1467 arm_algorithm_info->core_mode, i).value, 0, 32);
1468 if (regvalue != context[i]) {
1469 LOG_DEBUG("restoring register %s with value 0x%8.8" PRIx32 "",
1470 ARMV4_5_CORE_REG_MODE(arm->core_cache,
1471 arm_algorithm_info->core_mode, i).name, context[i]);
1472 buf_set_u32(ARMV4_5_CORE_REG_MODE(arm->core_cache,
1473 arm_algorithm_info->core_mode, i).value, 0, 32, context[i]);
1474 ARMV4_5_CORE_REG_MODE(arm->core_cache, arm_algorithm_info->core_mode,
1475 i).valid = true;
1476 ARMV4_5_CORE_REG_MODE(arm->core_cache, arm_algorithm_info->core_mode,
1477 i).dirty = true;
1478 }
1479 }
1480
1481 arm_set_cpsr(arm, cpsr);
1482 arm->cpsr->dirty = true;
1483
1484 arm->core_state = core_state;
1485
1486 return retval;
1487 }
1488
1489 int armv4_5_run_algorithm(struct target *target,
1490 int num_mem_params,
1491 struct mem_param *mem_params,
1492 int num_reg_params,
1493 struct reg_param *reg_params,
1494 target_addr_t entry_point,
1495 target_addr_t exit_point,
1496 int timeout_ms,
1497 void *arch_info)
1498 {
1499 return armv4_5_run_algorithm_inner(target,
1500 num_mem_params,
1501 mem_params,
1502 num_reg_params,
1503 reg_params,
1504 (uint32_t)entry_point,
1505 (uint32_t)exit_point,
1506 timeout_ms,
1507 arch_info,
1508 armv4_5_run_algorithm_completion);
1509 }
1510
1511 /**
1512 * Runs ARM code in the target to calculate a CRC32 checksum.
1513 *
1514 */
1515 int arm_checksum_memory(struct target *target,
1516 target_addr_t address, uint32_t count, uint32_t *checksum)
1517 {
1518 struct working_area *crc_algorithm;
1519 struct arm_algorithm arm_algo;
1520 struct arm *arm = target_to_arm(target);
1521 struct reg_param reg_params[2];
1522 int retval;
1523 uint32_t i;
1524 uint32_t exit_var = 0;
1525
1526 static const uint8_t arm_crc_code_le[] = {
1527 #include "../../contrib/loaders/checksum/armv4_5_crc.inc"
1528 };
1529
1530 assert(sizeof(arm_crc_code_le) % 4 == 0);
1531
1532 retval = target_alloc_working_area(target,
1533 sizeof(arm_crc_code_le), &crc_algorithm);
1534 if (retval != ERROR_OK)
1535 return retval;
1536
1537 /* convert code into a buffer in target endianness */
1538 for (i = 0; i < ARRAY_SIZE(arm_crc_code_le) / 4; i++) {
1539 retval = target_write_u32(target,
1540 crc_algorithm->address + i * sizeof(uint32_t),
1541 le_to_h_u32(&arm_crc_code_le[i * 4]));
1542 if (retval != ERROR_OK)
1543 goto cleanup;
1544 }
1545
1546 arm_algo.common_magic = ARM_COMMON_MAGIC;
1547 arm_algo.core_mode = ARM_MODE_SVC;
1548 arm_algo.core_state = ARM_STATE_ARM;
1549
1550 init_reg_param(&reg_params[0], "r0", 32, PARAM_IN_OUT);
1551 init_reg_param(&reg_params[1], "r1", 32, PARAM_OUT);
1552
1553 buf_set_u32(reg_params[0].value, 0, 32, address);
1554 buf_set_u32(reg_params[1].value, 0, 32, count);
1555
1556 /* 20 second timeout/megabyte */
1557 int timeout = 20000 * (1 + (count / (1024 * 1024)));
1558
1559 /* armv4 must exit using a hardware breakpoint */
1560 if (arm->arch == ARM_ARCH_V4)
1561 exit_var = crc_algorithm->address + sizeof(arm_crc_code_le) - 8;
1562
1563 retval = target_run_algorithm(target, 0, NULL, 2, reg_params,
1564 crc_algorithm->address,
1565 exit_var,
1566 timeout, &arm_algo);
1567
1568 if (retval == ERROR_OK)
1569 *checksum = buf_get_u32(reg_params[0].value, 0, 32);
1570 else
1571 LOG_ERROR("error executing ARM crc algorithm");
1572
1573 destroy_reg_param(&reg_params[0]);
1574 destroy_reg_param(&reg_params[1]);
1575
1576 cleanup:
1577 target_free_working_area(target, crc_algorithm);
1578
1579 return retval;
1580 }
1581
1582 /**
1583 * Runs ARM code in the target to check whether a memory block holds
1584 * all ones. NOR flash which has been erased, and thus may be written,
1585 * holds all ones.
1586 *
1587 */
1588 int arm_blank_check_memory(struct target *target,
1589 struct target_memory_check_block *blocks, int num_blocks, uint8_t erased_value)
1590 {
1591 struct working_area *check_algorithm;
1592 struct reg_param reg_params[3];
1593 struct arm_algorithm arm_algo;
1594 struct arm *arm = target_to_arm(target);
1595 int retval;
1596 uint32_t i;
1597 uint32_t exit_var = 0;
1598
1599 static const uint8_t check_code_le[] = {
1600 #include "../../contrib/loaders/erase_check/armv4_5_erase_check.inc"
1601 };
1602
1603 assert(sizeof(check_code_le) % 4 == 0);
1604
1605 if (erased_value != 0xff) {
1606 LOG_ERROR("Erase value 0x%02" PRIx8 " not yet supported for ARMv4/v5 targets",
1607 erased_value);
1608 return ERROR_FAIL;
1609 }
1610
1611 /* make sure we have a working area */
1612 retval = target_alloc_working_area(target,
1613 sizeof(check_code_le), &check_algorithm);
1614 if (retval != ERROR_OK)
1615 return retval;
1616
1617 /* convert code into a buffer in target endianness */
1618 for (i = 0; i < ARRAY_SIZE(check_code_le) / 4; i++) {
1619 retval = target_write_u32(target,
1620 check_algorithm->address
1621 + i * sizeof(uint32_t),
1622 le_to_h_u32(&check_code_le[i * 4]));
1623 if (retval != ERROR_OK)
1624 goto cleanup;
1625 }
1626
1627 arm_algo.common_magic = ARM_COMMON_MAGIC;
1628 arm_algo.core_mode = ARM_MODE_SVC;
1629 arm_algo.core_state = ARM_STATE_ARM;
1630
1631 init_reg_param(&reg_params[0], "r0", 32, PARAM_OUT);
1632 buf_set_u32(reg_params[0].value, 0, 32, blocks[0].address);
1633
1634 init_reg_param(&reg_params[1], "r1", 32, PARAM_OUT);
1635 buf_set_u32(reg_params[1].value, 0, 32, blocks[0].size);
1636
1637 init_reg_param(&reg_params[2], "r2", 32, PARAM_IN_OUT);
1638 buf_set_u32(reg_params[2].value, 0, 32, erased_value);
1639
1640 /* armv4 must exit using a hardware breakpoint */
1641 if (arm->arch == ARM_ARCH_V4)
1642 exit_var = check_algorithm->address + sizeof(check_code_le) - 4;
1643
1644 retval = target_run_algorithm(target, 0, NULL, 3, reg_params,
1645 check_algorithm->address,
1646 exit_var,
1647 10000, &arm_algo);
1648
1649 if (retval == ERROR_OK)
1650 blocks[0].result = buf_get_u32(reg_params[2].value, 0, 32);
1651
1652 destroy_reg_param(&reg_params[0]);
1653 destroy_reg_param(&reg_params[1]);
1654 destroy_reg_param(&reg_params[2]);
1655
1656 cleanup:
1657 target_free_working_area(target, check_algorithm);
1658
1659 if (retval != ERROR_OK)
1660 return retval;
1661
1662 return 1; /* only one block has been checked */
1663 }
1664
1665 static int arm_full_context(struct target *target)
1666 {
1667 struct arm *arm = target_to_arm(target);
1668 unsigned num_regs = arm->core_cache->num_regs;
1669 struct reg *reg = arm->core_cache->reg_list;
1670 int retval = ERROR_OK;
1671
1672 for (; num_regs && retval == ERROR_OK; num_regs--, reg++) {
1673 if (!reg->exist || reg->valid)
1674 continue;
1675 retval = armv4_5_get_core_reg(reg);
1676 }
1677 return retval;
1678 }
1679
1680 static int arm_default_mrc(struct target *target, int cpnum,
1681 uint32_t op1, uint32_t op2,
1682 uint32_t crn, uint32_t crm,
1683 uint32_t *value)
1684 {
1685 LOG_ERROR("%s doesn't implement MRC", target_type_name(target));
1686 return ERROR_FAIL;
1687 }
1688
1689 static int arm_default_mcr(struct target *target, int cpnum,
1690 uint32_t op1, uint32_t op2,
1691 uint32_t crn, uint32_t crm,
1692 uint32_t value)
1693 {
1694 LOG_ERROR("%s doesn't implement MCR", target_type_name(target));
1695 return ERROR_FAIL;
1696 }
1697
1698 int arm_init_arch_info(struct target *target, struct arm *arm)
1699 {
1700 target->arch_info = arm;
1701 arm->target = target;
1702
1703 arm->common_magic = ARM_COMMON_MAGIC;
1704
1705 /* core_type may be overridden by subtype logic */
1706 if (arm->core_type != ARM_CORE_TYPE_M_PROFILE) {
1707 arm->core_type = ARM_CORE_TYPE_STD;
1708 arm_set_cpsr(arm, ARM_MODE_USR);
1709 }
1710
1711 /* default full_context() has no core-specific optimizations */
1712 if (!arm->full_context && arm->read_core_reg)
1713 arm->full_context = arm_full_context;
1714
1715 if (!arm->mrc)
1716 arm->mrc = arm_default_mrc;
1717 if (!arm->mcr)
1718 arm->mcr = arm_default_mcr;
1719
1720 return ERROR_OK;
1721 }
Open On-Chip Debugger

Linking to existing account procedure

If you already have an account and want to add another login method you MUST first sign in with your existing account and then change URL to read https://review.openocd.org/login/?link to get to this page again but this time it'll work for linking. Thank you.

SSH host keys fingerprints

1024 SHA256:YKx8b7u5ZWdcbp7/4AeXNaqElP49m6QrwfXaqQGJAOk gerrit-code-review@openocd.zylin.com (DSA)
384 SHA256:jHIbSQa4REvwCFG4cq5LBlBLxmxSqelQPem/EXIrxjk gerrit-code-review@openocd.org (ECDSA)
521 SHA256:UAOPYkU9Fjtcao0Ul/Rrlnj/OsQvt+pgdYSZ4jOYdgs gerrit-code-review@openocd.org (ECDSA)
256 SHA256:A13M5QlnozFOvTllybRZH6vm7iSt0XLxbA48yfc2yfY gerrit-code-review@openocd.org (ECDSA)
256 SHA256:spYMBqEYoAOtK7yZBrcwE8ZpYt6b68Cfh9yEVetvbXg gerrit-code-review@openocd.org (ED25519)
+--[ED25519 256]--+
|=..              |
|+o..   .         |
|*.o   . .        |
|+B . . .         |
|Bo. = o S        |
|Oo.+ + =         |
|oB=.* = . o      |
| =+=.+   + E     |
|. .=o   . o      |
+----[SHA256]-----+
2048 SHA256:0Onrb7/PHjpo6iVZ7xQX2riKN83FJ3KGU0TvI0TaFG4 gerrit-code-review@openocd.zylin.com (RSA)