1Building and using the Library {#build_lib} 2============================== 3 4@brief How to build the library and test programs and include the library in an application 5 6Platform Support 7---------------- 8 9The current makefiles and build projects support building the library on: 10 - Linux and Windows, x86 or x64 hosts. 11 - ARM linux - AArch32 and AArch64 12 - ARM aarch32 and aarch64 libs, x-compiled on x86/64 hosts. 13 - MacOS - x64 and AArch64 (Apple Silicon) 14 15In addition to building the library from the project, the library may be installed into the standard 16`/usr/lib/` area in Linux, and will soon be available as a package from Linux Distros. 17 18Building the Library 19-------------------- 20 21The library and test programs are built from the library `./build/<platform>` directory, where 22<platform> is either 'linux', 'macos', or 'win-vs2022' 23 24See [`./docs/test_progs.md`](@ref test_progs) for further information on use of the test 25programs. 26 27### Linux x86/x64/ARM ### 28 29GCC is assumed to be the default compiler. 30 31Libraries are built into a <tgt_dir>. This is used as the final output directory for the 32libraries in `decoder/lib/<tgt_dir>`, and also as a sub-directory of the build process for 33intermediate files - `decoder/build/linux/ref_trace_decode_lib/<tgt_dir>`. 34 35For a standard build, go to the `./build/linux/` and run `make` in that directory. 36 37This will set <tgt_dir> to `builddir` for all build variants of the library. Using this only one variant of the library can be built at any one time. 38 39For development, alternatively use `make -f makefile.dev` 40 41This will set <tgt_dir> to `linux<bit-variant>/<dbg|rel>` and therefore build libraries into the 42`decoder/lib/linux<bit-variant>/<dbg|rel>` directories, allowing multiple variants of the library 43to be present during development. 44 45e.g. 46 47`./lib/linux64/rel` will contain the linux 64 bit release libraries. 48 49`./lib/linux-arm64/dbg` will contain the linux aarch 64 debug libraries for ARM. 50 51Options to pass to both makefiles are:- 52- `DEBUG=1` : build the debug version of the library. 53 54Options to pass to makefile.dev are:- 55- ARCH=<arch> : sets the bit variant in the delivery directories. Set if cross compilation for ARCH 56 other than host. Otherwise ARCH is auto-detected. 57 <arch> can be x86, x86_64, arm, arm64, aarch64, aarch32 58 59For cross compilation, set the environment variable `CROSS_COMPILE` to the name path/prefix for the 60compiler to use. The following would set the environment to cross-compile for ARM 61 62 export PATH=$PATH:~/work/gcc-x-aarch64-6.2/bin 63 export ARCH=arm64 64 export CROSS_COMPILE=aarch64-linux-gnu- 65 66The makefile will scan the `ocsd_if_version.h` to get the library version numbers and use these 67in the form Major.minor.patch when naming the output .so files. 68 69Main C++ library names: 70- `libcstraced.so.M.m.p` : shared library containing the main C++ based decoder library 71- `libcstrace.so.M` : symbolic link name to library - major version only. 72- `libcstrace.so` : symbolic link name to library - no version. 73 74C API wrapper library names: 75- `libcstraced_c_api.so.M.m.p` : shared library containing the C-API wrapper library. Dependent on `libcstraced.so.M` 76- `libcstraced_c_api.so.M` : symbolic link name to library - major version only. 77- `libcstraced_c_api.so` : symbolic link name to library - no version. 78 79Static versions of the libraries: 80- `libcstraced.a` : static library containing the main C++ based decoder library. 81- `libcstraced_c_api.a` : static library containing the C-API wrapper library. 82 83Test programs are delivered to the `./tests/bin/<tgt_dir>` directories. 84 85The test programs are built to used the .so versions of the libraries. 86- `trc_pkt_lister` - dependent on `libcstraced.so`. 87- `simple_pkt_print_c_api` - dependent on `libcstraced_c_api.so` & hence `libcstraced.so`. 88 89The test program build for `trc_pkt_lister` also builds an auxiliary library used by this program for test purposes only. 90This is the `libsnapshot_parser.a` library, delivered to the `./tests/lib/<tgt_dir>` directories. 91 92**Note on Linux Build Directory Names** 93 94Due to tool limitations, the makefiles will not operate correctly if the path to the opencsd directories contains spaces. 95 96e.g. checking out the project into a directory such as ` /home/name/my opencsd/` will result in build failures. 97 98__Installing on Linux__ 99 100The libraries can be installed on linux using the `make install` command. This will usually require root privileges. Installation will be the version in the `./lib/<tgt_dir>` directory, according to options chosen. 101 102e.g. ` make -f makefile.dev DEBUG=1 install` 103 104will install from `./lib/linux64/dbg` 105 106The libraries `libopencsd` and `libopencsd_c_api` are installed to `/usr/lib`. 107 108Sufficient header files to build using the C-API library will be installed to `/usr/include/opencsd`. 109 110The installation can be removed using `make clean_install`. No additional options are necessary. 111 112 113### MacOS x64/AArch64 ### 114 115Clang is assumed to be the default compiler. 116 117Go to the `./decoder/build/macos/` directory and run `make`. 118 119Output libraries will be placed in the same folders as for the Linux build (`decoder/lib/builddir/` 120and `decoder/tests/lib/builddir/`). 121 122`DYLD_LIBRARY_PATH` will need to be specified to run an executable that depends on the libraries. For example, 123to run `trc_pkt_lister` from the base directory: 124 125 DYLD_LIBRARY_PATH=./decoder/lib/builddir ./decoder/tests/bin/builddir/trc_pkt_lister -h 126 127For development, alternatively use `make -f makefile.dev` 128 129Similar to the Linux makefile.dev, this will build libraries into the `decoder/lib/darwin<bit-variant>/<dbg|rel>` 130directories, allowing multiple variants of the library to be present during development. 131 132Options to pass to both makefiles are:- 133- `DEBUG=1` : build the debug version of the library. 134 135Options to pass to makefile.dev are:- 136- ARCH=<arch> : Set this if needing to build for x86_64 from an arm64 host, or to build for arm64 from an x86_64 host. 137 Otherwise ARCH is auto-detected. 138 <arch> can be x86_64, arm64 139 140 141### Windows (x86/x64) ### 142 143Use the `.\build\win\ref_trace_decode_lib\ref_trace_decode_lib.sln` file to load a solution 144which contains all library and test build projects. 145 146Libraries are delivered to the `./lib/win<bitsize>/<dbg\rel>` directories. 147e.g. `./lib/win64/rel` will contain the windows 64 bit release libraries. 148 149The solution contains four configurations:- 150- *Debug* : builds debug versions of static C++ main library and C-API libraries, test programs linked to the static library. 151- *Debug-dll* : builds debug versions of static main library and C-API DLL. C-API statically linked to the main library. 152C-API test built as `c_api_pkt_print_test_dll.exe` and linked against the DLL version of the C-API library. 153- *Release* : builds release static library versions, test programs linked to static libraries. 154- *Release-dll* : builds release C-API DLL, static main library. 155 156_Note_: Currently there is no Windows DLL version of the main C++ library. This may follow once 157the project is nearer completion with further decode protocols, and the classes requiring export are established.. 158 159Libraries built are:- 160- `libopencsd.lib` : static main C++ decoder library. 161- `libopencsd_c_api.lib` : C-API static library. 162- `libopencsd_c_api.dll` : C-API DLL library. Statically linked against `libcstraced.lib` at .DLL build time. Built using the release-dll or debug-dll solution configurations. 163 164 165There is also a project file to build an auxiliary library used `trc_pkt_lister` for test purposes only. 166This is the `snapshot_parser_lib.lib` library, delivered to the `./tests/lib/win<bitsize>/<dgb\rel>` directories. 167 168 169### Additional Build Options ### 170 171__Library Virtual Address Size__ 172 173The ocsd_if_types.h file includes a #define that controls the size of the virtual addresses 174used within the library. By default this is a 64 bit `uint64_t` value. 175 176When building for ARM architectures that have only a 32 bit Virtual Address, and building on 17732 bit ARM architectures it may be desirable to build a library that uses a v-addr size of 17832 bits. Define `USE_32BIT_V_ADDR` to enable this option 179 180 181Including the Library in an Application 182--------------------------------------- 183 184The user source code includes a header according to the API to be used:- 185 186- Main C++ decoder library - include `opencsd.h`. Link to C++ library. 187- C-API library - include `opencsd_c_api.h`. Link to C-API library. 188 189### Linux build ### 190 191By default linux builds will link against the .so versions of the library. Using the C-API library will also 192introduce a dependency on the main C++ decoder .so. Ensure that the library paths and link commands are part of the 193application makefile. 194 195To use the static versions use appropriate linker options. 196 197### MacOS build ### 198 199The same applies as for the Linux build w.r.t the .dylib versions of the library. 200 201### Windows build ### 202 203To link against the C-API DLL, include the .DLL name as a dependency in the application project options. 204 205To link against the C-API static library, include the library name in the dependency list, and define the macro 206`OCSD_USE_STATIC_C_API` in the preprocessor definitions. This ensures that the correct static bindings are declared in 207the header file. Also link against the main C++ library. 208 209To link against the main C++ library include the library name in the dependency list. 210 211 212Library Performance Options 213--------------------------- 214 215The library caches parts of the memory images requested during the decode process, to improve performance by reducing the number of requests to the memory accessor (memacc) objects or callbacks. 216 217The default settings can be adjusted at runtime either by programmable API, or using environment variables. 218 219Cache parameters can be set in terms of page size and number of pages. 220Caching can also be disabled. 221 222Page size can vary between 64 bytes and 16384 bytes. 223Number of pages can vary between 4 and 256. 224 225Default values are set at 16 pages of 2048 bytes. 226 227### Environment variables to control caching ### 228 229- `OPENCSD_MEMACC_CACHE_PAGE_SIZE` : Page size in bytes. 230- `OPENCSD_MEMACC_CACHE_PAGE_NUM` : number of pages. 231- `OPENCSD_MEMACC_CACHE_OFF` : disable memacc caching. 232 233 234Library Debug Options 235--------------------- 236 237### ETMv4 / ETE instruction run limit ### 238 239The ETMv4 / ETE decoder has an optional run length limit for the amount of instructions in a range permitted before an error code will be returned. 240 241This option allows debug of potential runaway decode if incorrect memory image imformation is provided to the debuger. 242 243Option controlled by environment variable `OPENCSD_INSTR_RANGE_LIMIT`. Set value to number of instructions as the limit. 244 245### AA64 Invalid opcode detection ### 246 247The instruction decode part of the library can be set to detect invalid aarch64 opcodes and throw an error. 248 249In the aarch64 opcodes define any opcode with the top 16 bits as 0x0000 as an invalid opcode range - which is the range detected by the library. 250Any other opcodes that are undefined or invalid that are not in this range will not be detected. 251 252This also allows the potential to detect runaway decode where incorrect memory information is supplied which contains data sections initilised with 0x00000000. 253 254Option is controlled by environment variable `OPENCSD_ERR_ON_AA64_BAD_OPCODE`. If this is set then the invalid opcodes will be detected. 255 256