@@ -24,5 +24,93 @@ was almost 100 times slower, making it prohibitively expensive to use.
24
24
[ The unofficial DynASM Documentation] ( https://corsix.github.io/dynasm-doc/tutorial.html )
25
25
has a tutorial, reference, and instruction listing.
26
26
27
- ` zend_jit_x86.dasc ` gets automatically converted to ` zend_jit_x86.c ` by the bundled
27
+ In x86 builds, ` zend_jit_x86.dasc ` gets automatically converted to ` zend_jit_x86.c ` by the bundled
28
28
` dynasm ` during ` make ` .
29
+
30
+ In arm64 builds, ` zend_jit_x86.dasc ` gets automatically converted to ` zend_jit_arm64.c ` by the bundled
31
+ ` dynasm ` during ` make ` .
32
+
33
+ Running tests of the JIT
34
+ ------------------------
35
+
36
+ Then, to test the JIT, e.g. with opcache.jit=tracing, an example command
37
+ based on what is used to test in Azure CI:
38
+
39
+ ```
40
+ make test TESTS="-d opcache.jit_buffer_size=16M -d opcache.enable=1 -d opcache.enable_cli=1 -d opcache.protect_memory=1 -d opcache.jit=tracing --repeat 2 --show-diff -j$(nproc) ext/opcache"
41
+ ```
42
+
43
+ - ` opcache.jit_buffer_size=16M ` enables the JIT in tests by providing 16 megabytes of
44
+ memory to use with the JIT to test with.
45
+ - ` opcache.protect_memory=1 ` will detect writing to memory that is meant to be
46
+ read-only, which is sometimes the cause of opcache bugs.
47
+ - ` --repeat 2 ` is optional, but used in CI since some JIT bugs only show up after processing a
48
+ request multiple times, e.g. due to a bug in the engine or bad data in the
49
+ runtime cache of the interpreter.
50
+ - ` -j$(nproc) ` runs as many workers to run tests as there are CPUs.
51
+ - ` ext/opcache/ ` is the folder with the tests to run, in this case opcache
52
+ itself. If no folders are provided, all tests are run.
53
+
54
+ When investigating test failures such as segmentation faults, adding
55
+ ` -m --show-mem ` may be useful to test with [ valgrind] ( https://valgrind.org/ ) to detect out of bounds memory accesses.
56
+
57
+ Note that the JIT supports 3 different architectures: ` X86_64 ` , ` i386 ` , and ` arm64 ` .
58
+
59
+ Miscellaneous
60
+ -------------
61
+
62
+ ### Checking dasc files for in a different architecture
63
+
64
+ The following command can be run to manually check if the modified ` .dasc code ` is at least transpilable
65
+ for an architecture you're not using, e.g.:
66
+
67
+ For arm64: ` ext/opcache/minilua ext/opcache/jit/dynasm/dynasm.lua -D ARM64=1 -o ext/opcache/jit/zend_jit_arm64.ignored.c ext/opcache/jit/zend_jit_arm64.dasc `
68
+
69
+ For x86_64: ` ext/opcache/minilua ext/opcache/jit/dynasm/dynasm.lua -D X64=1 -o ext/opcache/jit/zend_jit_x86.ignored.c ext/opcache/jit/zend_jit_x86.dasc `
70
+
71
+ For i386 (i.e. 32-bit): ` ext/opcache/minilua ext/opcache/jit/dynasm/dynasm.lua -o ext/opcache/jit/zend_jit_x86.ignored.c ext/opcache/jit/zend_jit_x86.dasc `
72
+
73
+ ### How to build 32-bit builds on x86_64 environments
74
+
75
+ Refer to [ ../../../azure/i386] ( ../../../azure/i386/apt.yml ) for examples of
76
+ dependencies to install.
77
+
78
+ If you are running this natively (outside of Docker or a VM):
79
+
80
+ - Consider running in docker/a VM instead if you are unfamiliar with this.
81
+ - Avoid purging packages.
82
+ - Avoid ` -y ` - if the package manager warns you that the dependencies conflict
83
+ then ** don't** try to force install them.
84
+
85
+ #### Prerequisites for 32-bit builds
86
+
87
+ This assumes you are using a Debian-based Linux distribution and have already
88
+ set up prerequisites for regular development.
89
+
90
+ ```
91
+ sudo dpkg --add-architecture i386
92
+ sudo apt-get update -y
93
+ # As well as anything else from azure/i386/apt.yml that you're testing locally
94
+ sudo apt-get install \
95
+ gcc-multilib g++-multilib \
96
+ libxml2-dev:i386 \
97
+ libc6:i386
98
+ ```
99
+
100
+ #### Compiling 32-bit builds
101
+
102
+ This assumes you are using a Debian-based Linux distribution and have already
103
+ set up prerequisites for 32-bit development.
104
+
105
+ ```
106
+ export LDFLAGS=-L/usr/lib/i386-linux-gnu
107
+ export CFLAGS='-m32'
108
+ export CXXFLAGS='-m32'
109
+ export PKG_CONFIG=/usr/bin/i686-linux-gnu-pkg-config
110
+ ./configure --disable-all --enable-opcache --build=i686-pc-linux-gnu
111
+ make -j$(nproc)
112
+ ```
113
+
114
+ #### Running tests of the JIT on 32-bit builds
115
+
116
+ See the section "Running tests of the JIT".
0 commit comments