1# Berberis
2
3Dynamic binary translator to run Android apps with riscv64 native code on x86_64 devices or emulators.
4
5Supported extensions include Zb* (bit manipulation) and most of Zv (vector). Some less commonly used vector instructions are not yet implemented, but Android CTS and some Android apps run with the current set of implemented instructions.
6
7Public mailing list: [email protected]
8
9## Getting Started
10
11Note: Googlers, read go/berberis and go/berberis-start first.
12
13### Build
14
15From your Android root checkout, run:
16
17```
18source build/envsetup.sh
19lunch sdk_phone64_x86_64_riscv64-trunk_staging-eng
20m berberis_all
21```
22
23For development, we recommend building all existing targets before uploading changes, since they are currently not always synchronized with `berberis_all`:
24
25```
26mmm frameworks/libs/binary_translation
27```
28
29### Run Hello World
30
31```
32out/host/linux-x86/bin/berberis_program_runner_riscv64 \
33out/target/product/emu64xr/testcases/berberis_hello_world_static.native_bridge/x86_64/berberis_hello_world_static
34```
35
36On success `Hello!` will be printed.
37
38### Run unit tests on host
39
40```
41m berberis_all berberis_run_host_tests
42```
43
44or
45
46```
47out/host/linux-x86/nativetest64/berberis_host_tests/berberis_host_tests
48```
49
50### Build and run emulator with Berberis support
51
52```
53m
54emulator -memory 4096 -writable-system -partition-size 65536 -qemu -cpu host &
55```
56
57### Run unit tests on device or emulator
58
59Note: Requires a running device or emulator with Berberis support.
60
611. Sync tests to the device:
62
63```
64adb root
65adb sync data
66```
67
682. Run guest loader tests:
69
70```
71adb shell /data/nativetest64/berberis_guest_loader_riscv64_tests/berberis_guest_loader_riscv64_tests
72```
73
743. Run program tests:
75
76```
77adb shell /data/nativetest64/berberis_ndk_program_tests/berberis_ndk_program_tests
78```
79
80## Bionic unit tests
81
82Note: Requires a running device or emulator with Berberis support.
83
841. Build Bionic unit tests:
85
86```
87m TARGET_PRODUCT=aosp_riscv64 bionic-unit-tests
88```
89
902. Push tests to emulator or device:
91
92```
93adb push out/target/product/generic_riscv64/data/nativetest64/bionic-loader-test-libs /data/local/tmp
94adb push out/target/product/generic_riscv64/data/nativetest64/bionic-unit-tests /data/local/tmp
95```
96
973. Run Bionic tests:
98
99```
100adb shell /system/bin/berberis_program_runner_riscv64 /data/local/tmp/bionic-unit-tests/bionic-unit-tests
101```
102
103## Development
104
105### Running Android Apps (APKs) on Berberis Emulator
106
107The steps for running Android apps on a Berberis emulator simply involve building and running the emulator (see instructions above), building your Android app, then installing it onto the emulator using `adb`.
108
109For example you can build then run the JNI test APK (see `tests/jni_tests/README.txt`) by running:
110
111```
112m TARGET_BUILD_VARIANT=userdebug TARGET_PRODUCT=aosp_riscv64 berberis_jni_tests
113```
114
115Install the app:
116
117```
118adb install out/target/product/generic_riscv64/testcases/berberis_jni_tests/riscv64/berberis_jni_tests.apk
119```
120
121Start the app:
122
123```
124adb shell am instrument -w com.berberis.jnitests/androidx.test.runner.AndroidJUnitRunner
125```
126
127Uninstall the app:
128
129```
130adb uninstall com.berberis.jnitests
131```
132
133## Debugging
134
135### Crash Reporting for Guest State
136
137When native code crashes a basic crash dump is written to `logcat` and a more detailed tombstone file is written to `/data/tombstones`. The tombstone file contains extra data about the crashed process. In particular, it contains stack traces for all the host threads and guest threads in the crashing process (not just the thread that caught the signal), a full memory map, and a list of all open file descriptors.
138
139To find the tombstone file, use `adb` to access the device or emulator (run `adb root` if you don't have permissions) and locate the file:
140
141```
142$ adb shell ls /data/tombstones/
143tombstone_00  tombstone_00.pb
144```
145`tombstone_00` is the output in human-readable text.
146
147Note: Guest thread information follows host thread information whenever it is available.
148
149Example tombstone output:
150
151```
152*** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
153Build fingerprint: 'Android/sdk_phone64_x86_64_riscv64/emu64xr:VanillaIceCream/MAIN/eng.sijiec.20240510.182325:eng/test-keys'
154Revision: '0'
155ABI: 'x86_64'
156Guest architecture: 'riscv64'
157Timestamp: 2024-05-13 18:38:56.175592859+0000
158Process uptime: 3s
159Cmdline: com.berberis.jnitests
160pid: 2875, tid: 2896, name: roidJUnitRunner  >>> com.berberis.jnitests <<<
161uid: 10147
162signal 11 (SIGSEGV), code -6 (SI_TKILL), fault addr --------
163    rax 0000000000000000  rbx 00007445aebb0000  rcx 000074458c73df08  rdx 000000000000000b
164    r8  00007442f18487d0  r9  00007442f18487d0  r10 00007442ecc87770  r11 0000000000000206
165    r12 0000000000000000  r13 00000000002e4e64  r14 00007445aebaf020  r15 00007442ed113d10
166    rdi 0000000000000b3b  rsi 0000000000000b50
167    rbp 00000000aebaf401  rsp 00007442ed111948  rip 000074458c73df08
168
1697 total frames
170backtrace:
171      #00 pc 0000000000081f08  /apex/com.android.runtime/lib64/bionic/libc.so (syscall+24) (BuildId: 071397dbd1881d18b5bff5dbfbd86eb7)
172      #01 pc 00000000014cca92  /system/lib64/libberberis_riscv64.so (berberis::RunGuestSyscall(berberis::ThreadState*)+82) (BuildId: f3326eacda7666bc0e85d13ef7281630)
173      #02 pc 000000000037d955  /system/lib64/libberberis_riscv64.so (berberis::Decoder<berberis::SemanticsPlayer<berberis::Interpreter> >::DecodeSystem()+133) (BuildId: f3326eacda7666bc0e85d13ef7281630)
174      #03 pc 000000000037b4cf  /system/lib64/libberberis_riscv64.so (berberis::Decoder<berberis::SemanticsPlayer<berberis::Interpreter> >::DecodeBaseInstruction()+831) (BuildId: f3326eacda7666bc0e85d13ef7281630)
175      #04 pc 000000000037a9f4  /system/lib64/libberberis_riscv64.so (berberis::InterpretInsn(berberis::ThreadState*)+100) (BuildId: f3326eacda7666bc0e85d13ef7281630)
176      #05 pc 00000000002c7325  /system/lib64/libberberis_riscv64.so (berberis_entry_Interpret+21) (BuildId: f3326eacda7666bc0e85d13ef7281630)
177      #06 pc 114f9329b57c0dac  <unknown>
178
179memory near rbx:
180    00007445aebaffe0 0000000000000000 0000000000000000  ................
181    00007445aebafff0 0000000000000000 0000000000000000  ................
182    00007445aebb0000 0000000000000000 00007442ecdb2000  ......... ..Bt..
183    00007445aebb0010 0000000000125000 0000000000010000  .P..............
184    00007445aebb0020 0000000000125000 00007442eced6ff0  .P.......o..Bt..
185    00007445aebb0030 00007445aebae000 000074428dee7000  ....Et...p..Bt..
186    00007445aebb0040 000074428dee8000 00007445aebaf020  ....Bt.. ...Et..
187    00007445aebb0050 0000000000000000 0000000000000000  ................
188    00007445aebb0060 00007442e7d9b448 00007443b7836ce0  H...Bt...l..Ct..
189    00007445aebb0070 00007442ed111ab0 0000000000000000  ....Bt..........
190    00007445aebb0080 0000000000000000 0000000000000000  ................
191    00007445aebb0090 0000000000000000 0000000000000000  ................
192    00007445aebb00a0 0000000000000000 0000000000000000  ................
193    00007445aebb00b0 0000000000000000 0000000000000000  ................
194    00007445aebb00c0 0000000000000000 0000000000000000  ................
195    00007445aebb00d0 0000000000000000 0000000000000000  ................
196
197...snippet
198
19905-13 18:38:55.898  2875  2896 I TestRunner: finished: testGetVersion(com.berberis.jnitests.JniTests)
20005-13 18:38:55.900  2875  2896 I TestRunner: started: testRegisterNatives(com.berberis.jnitests.JniTests)
201--- --- --- --- --- --- --- --- --- --- --- --- --- --- --- ---
202Guest thread information for tid: 2896
203    pc  00007442942e4e64  ra  00007442ecc88b08  sp  00007442eced6fc0  gp  000074428dee8000
204    tp  00007445aebae050  t0  0000000000000008  t1  00007442942ffb4c  t2  0000000000000000
205    t3  00007442942e4e60  t4  0000000000000000  t5  8d38b33c8bd53145  t6  736574696e6a2e73
206    s0  00007442eced6fe0  s1  000000000000002a  s2  0000000000000000  s3  0000000000000000
207    s4  0000000000000000  s5  0000000000000000  s6  0000000000000000  s7  0000000000000000
208    s8  0000000000000000  s9  0000000000000000  s10 0000000000000000  s11 0000000000000000
209    a0  0000000000000b3b  a1  0000000000000b50  a2  000000000000000b  a3  00007442ecc87770
210    a4  00007442f18487d0  a5  00007442f18487d0  a6  00007442f18487d0  a7  0000000000000083
211    vlenb 0000000000000000
212
2133 total frames
214backtrace:
215      #00 pc 000000000008de64  /system/lib64/riscv64/libc.so (tgkill+4) (BuildId: 7daa7d467f152da57592545534afd2ee)
216      #01 pc 0000000000001b04  /data/app/~~_CJlJwewmTxNSIr4kxVv7w==/com.berberis.jnitests-7MJzLGAPUFFAMt5wl-D-Hg==/base.apk!libberberis_jni_tests.so (offset 0x1000) ((anonymous namespace)::add42(_JNIEnv*, _jclass*, int)+18) (BuildId: 665cb51828ad4b5e3ddf149af15b31cc)
217      #02 pc 0000000000001004  /system/lib64/riscv64/libnative_bridge_vdso.so (BuildId: 3df95df99d97cad076b80c56aa20c552)
218
219memory near pc (/system/lib64/riscv64/libc.so):
220    00007442942e4e40 0000007308100893 01157363288578fd  ....s....x.(cs..
221    00007442942e4e50 b39540a005338082 0000001300000013  ..3..@..........
222    00007442942e4e60 0000007308300893 01157363288578fd  ..0.s....x.(cs..
223    00007442942e4e70 b39140a005338082 0000001300000013  ..3..@..........
224    00007442942e4e80 000000730d600893 01157363288578fd  ..`.s....x.(cs..
225    00007442942e4e90 b31540a005338082 0000001300000013  ..3..@..........
226    00007442942e4ea0 000000730dd00893 01157363288578fd  ....s....x.(cs..
227    00007442942e4eb0 b31140a005338082 0000001300000013  ..3..@..........
228    00007442942e4ec0 0000007307500893 01157363288578fd  ..P.s....x.(cs..
229    00007442942e4ed0 b1d540a005338082 0000001300000013  ..3..@..........
230    00007442942e4ee0 000000730a500893 01157363288578fd  ..P.s....x.(cs..
231    00007442942e4ef0 b1d140a005338082 0000001300000013  ..3..@..........
232    00007442942e4f00 0000007308d00893 01157363288578fd  ....s....x.(cs..
233    00007442942e4f10 b15540a005338082 0000001300000013  ..3..@U.........
234    00007442942e4f20 0000007308c00893 01157363288578fd  ....s....x.(cs..
235    00007442942e4f30 b15140a005338082 0000001300000013  ..3..@Q.........
236
237...snippet
238```
239