Movatterモバイル変換

[0]ホーム
URL:

Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly

 Sign up
Appearance settings

Commit5c4d016

Browse files
authored
Merge pull request#89 from wnienhaus/disassembler
Add Disassembler
2 parentsba4e9ac +06b277e commit5c4d016

File tree

15 files changed

+1608
-1
lines changed

15 files changed

+1608
-1
lines changed

‎.github/workflows/run_tests.yaml‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -91,3 +91,10 @@ jobs:
9191
export PATH=$PATH:${{ steps.fetch_binutils.outputs.bin_dir }}
9292
cd tests
9393
./02_compat_rtc_tests.sh
94+
95+
-name:Run disassembler tests
96+
id:disassembler_tests
97+
run:|
98+
export PATH=$PATH:${{ steps.build_micropython.outputs.bin_dir }}
99+
cd tests
100+
./03_disassembler_tests.sh

‎README.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -35,6 +35,7 @@ The following features are supported:
3535
* expressions in assembly code and constant definitions
3636
* RTC convenience macros (e.g. ``WRITE_RTC_REG``)
3737
* many ESP32 ULP code examples found on the web will work unmodified
38+
* a simple disassembler is also provided
3839

3940

4041
Quick start

‎docs/disassembler.rst‎

Lines changed: 146 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,146 @@
1+
=====================
2+
Disassembler
3+
=====================
4+
5+
micropython-esp32-ulp contains a disassembler for disassembling code for the
6+
ESP32 ULP (Ultra Low-Power) Co-Processor.
7+
8+
The main purpose of this tool is to inspect what instructions our assembler
9+
created, what value each field is set to, and to compare this with the output
10+
created by the assembler from Espressif (part of their `binutils-gdb fork<https://github.com/espressif/binutils-gdb/tree/esp32ulp-elf-2.35>`_),
11+
which we use as our reference implementation.
12+
13+
14+
Usage
15+
------------------------
16+
17+
To disassemble a ULP binary, simply run:
18+
19+
..code-block::bash
20+
21+
micropython -m tools.disassemble path/to/binary.ulp
22+
23+
You can also specify additional options to ``disassemble.py`` as follows:
24+
25+
+--------------------------+----------------------------------------------------------------+
26+
| Option| Description|
27+
+==========================+================================================================+
28+
| ``-h``| Show help text|
29+
+--------------------------+----------------------------------------------------------------+
30+
|| ``-m <bytes sequence>`` || Disassemble a provided sequence of hex bytes|
31+
|| || (in this case any filename specified is ignored)|
32+
+--------------------------+----------------------------------------------------------------+
33+
| ``-v``| Verbose mode (shows ULP header and fields of each instruction)|
34+
+--------------------------+----------------------------------------------------------------+
35+
36+
37+
Disassembling a file
38+
------------------------
39+
40+
The simplest and default mode of the disassembler is to disassemble the
41+
specified file.
42+
43+
Note that the ULP header is validates and files with unknown magic bytes will be
44+
rejected. The correct 4 magic bytes at the start of a ULP binary are ``ulp\x00``.
45+
46+
Example:
47+
48+
..code-block::shell
49+
50+
$ micropython -m tools.disassemble path/to/binary.ulp
51+
.text
52+
0000 040000d0 LD r0, r1, 0
53+
0004 0e0400d0 LD r2, r3, 1
54+
0008 84010068 ST r0, r1, 0
55+
000c 8b090068 ST r3, r2, 2
56+
.data
57+
0000 00000000<empty>
58+
59+
60+
Disassembling a byte sequence
61+
-----------------------------
62+
63+
The ``-m`` option allows disassembling a sequences hex letters representing
64+
ULP instructions.
65+
66+
This option expects the actual instructions directly, without any ULP header.
67+
68+
The sequence must contain a number of hex letters exactly divisible by 8, i.e.
69+
8, 16, 24, etc, because each 32-bit word is made up of 8 hex letters. Spaces
70+
can be included in the sequence and they are ignored.
71+
72+
The typical use case for this feature is to copy/paste some instructions from
73+
a hexdump (e.g. xxd output) for analysis.
74+
75+
Example:
76+
77+
..code-block::shell
78+
79+
# hexdump binary.ulp
80+
$ xxd path/to/binary.ulp
81+
00000000: 756c 7000 0c00 2400 0400 0000 9300 8074 ulp...$........t
82+
00000010: 2a80 0488 2004 8074 1c00 0084 0000 0040*... ..t.......@
83+
(...)
84+
85+
# analyse the last 2 instructions
86+
$ micropython -m tools.disassemble -m"1c00 0084 0000 0040"
87+
0000 1c000084 JUMPS 0, 28, LT
88+
0004 00000040 NOP
89+
90+
91+
Verbose mode
92+
------------------------
93+
94+
In verbose mode the following extra outputs are enabled:
95+
96+
* ULP header (except when using ``-m``)
97+
* The fields of each instruction and their values
98+
99+
For example:
100+
101+
..code-block::
102+
103+
header
104+
ULP magic : b'ulp\x00' (0x00706c75)
105+
.text offset : 12 (0x0c)
106+
.text size : 36 (0x24)
107+
.data offset : 48 (0x30)
108+
.data size : 4 (0x04)
109+
.bss size : 0 (0x00)
110+
----------------------------------------
111+
.text
112+
0000 93008072 MOVE r3, 9
113+
dreg = 3
114+
imm = 9
115+
opcode = 7
116+
sel = 4 (MOV)
117+
sreg = 0
118+
sub_opcode = 1
119+
unused = 0
120+
(...detail truncated...)
121+
0020 000000b0 HALT
122+
opcode = 11 (0x0b)
123+
unused = 0
124+
----------------------------------------
125+
.data
126+
0000 00000000 <empty>
127+
128+
129+
Disassembling on device
130+
-----------------------------
131+
132+
The disassembler also works when used on an ESP32.
133+
134+
To use the disassembler on a real device:
135+
136+
* ensure ``micropython-esp32-ulp`` is installed on the device (see `docs/index.rst</docs/index.rst>`_).
137+
* upload ``tools/disassemble.py`` to the device (any directory will do)
138+
* run the following:
139+
140+
..code-block::python
141+
142+
from disassembleimport disassemble_file
143+
# then either:
144+
disassemble_file('path/to/file.ulp')# normal mode
145+
# or:
146+
disassemble_file('path/to/file.ulp',True)# verbose mode

‎docs/index.rst‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -136,6 +136,15 @@ found as part of Arduino/ESP-IDF projects.
136136
The preprocessor and how to use it is documented here: `Preprocessor support</docs/preprocess.rst>`_.
137137

138138

139+
Disassembler
140+
------------
141+
There is a disassembler for disassembling ULP binary code. This is mainly used to
142+
inspect what instructions our assembler created, however it can be used to analyse
143+
any ULP binaries.
144+
145+
The disassembler and how to use it is documented here: `Disassembler</docs/disassembler.rst>`_.
146+
147+
139148
Limitations
140149
-----------
141150

‎tests/00_unit_tests.sh‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,9 @@
44

55
set -e
66

7-
forfilein opcodes assemble link util preprocess definesdb;do
7+
LIST=${1:-opcodes assemble link util preprocess definesdb disassemble}
8+
9+
forfilein$LIST;do
810
echo testing$file...
911
micropython$file.py
1012
done

‎tests/03_disassembler_tests.sh‎

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
#!/bin/bash
2+
3+
set -e
4+
5+
test_disassembling_a_file() {
6+
local verbose
7+
if ["$1"== verbose ];then
8+
verbose=-v
9+
echo -e"Testing disassembling a file in VERBOSE mode"
10+
else
11+
echo -e"Testing disassembling a file in NORMAL mode"
12+
fi
13+
14+
testname=all_opcodes
15+
fixture=fixtures/${testname}.S
16+
echo -e"\tBuilding$fixture using micropython-esp32-ulp"
17+
18+
log_file="${testname}.log"
19+
ulp_file="fixtures/${testname}.ulp"
20+
micropython -m esp32_ulp$fixture1>$log_file# generates $ulp_file
21+
22+
lst_file="${testname}.lst"
23+
lst_file_fixture=fixtures/${testname}${verbose}.lst
24+
echo -e"\tDisassembling$ulp_file using micropython-esp32-ulp disassembler"
25+
micropython tools/disassemble.py$verbose$ulp_file>$lst_file
26+
27+
if! diff$lst_file_fixture$lst_file1>/dev/null;then
28+
echo -e"\tDisassembled output differs from expected output!"
29+
echo""
30+
echo"Disassembly test failed for$fixture"
31+
echo"micropython-esp32-ulp log:"
32+
cat$log_file
33+
echo"Diff of disassembly: expected vs actual"
34+
diff -u$lst_file_fixture$lst_file
35+
fi
36+
}
37+
38+
test_disassembling_a_manual_sequence() {
39+
local verbose
40+
if ["$1"== verbose ];then
41+
verbose=-v
42+
echo -e"Testing disassembling a manual byte sequence in VERBOSE mode"
43+
else
44+
echo -e"Testing disassembling a manual byte sequence in NORMAL mode"
45+
fi
46+
47+
sequence="e1af 8c72 0100 0068 2705 cc19 0005 681d 0000 00a0 0000 0074"
48+
49+
lst_file="manual_bytes.lst"
50+
lst_file_fixture=fixtures/manual_bytes${verbose}.lst
51+
echo -e"\tDisassembling manual byte sequence using micropython-esp32-ulp disassembler"
52+
micropython tools/disassemble.py$verbose -m$sequence>$lst_file
53+
54+
if! diff$lst_file_fixture$lst_file1>/dev/null;then
55+
echo -e"\tDisassembled output differs from expected output!"
56+
echo""
57+
echo"Disassembly test failed for manual byte sequence"
58+
echo"Diff of disassembly: expected vs actual"
59+
diff -u$lst_file_fixture$lst_file
60+
fi
61+
}
62+
63+
test_disassembling_a_file
64+
test_disassembling_a_file verbose
65+
66+
test_disassembling_a_manual_sequence
67+
test_disassembling_a_manual_sequence verbose

0 commit comments

Comments
 (0)
[8]ページ先頭
©2009-2025 Movatter.jp