From 449950cac747161b923c5624f8203f0d9009d91f Mon Sep 17 00:00:00 2001 From: Christoph Hindermann <10599299+BitMaskMixer@users.noreply.github.com> Date: Wed, 17 Jul 2024 07:59:20 +0200 Subject: [PATCH] update the FAQ section with a how-to enable the logging --- docs/FAQ.md | 70 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 70 insertions(+) diff --git a/docs/FAQ.md b/docs/FAQ.md index f3043abe..835760d2 100644 --- a/docs/FAQ.md +++ b/docs/FAQ.md @@ -123,6 +123,76 @@ Therefore, if you still prefer the previous `paddr = vaddr` simple mapping, we h In theory, `UC_TLB_VIRTUAL` will achieve better performance as it skips all MMU details, though not benchmarked. +## Something is wrong - I would like to dig deeper + +Unicorn uses at several places logging by the qemu implementation. +This might provide a first glance what could be wrong. + +The logs contains optionally the filename and the line number including +additional messages to indicate what is happening. +However, the qemu logs are partially commented-out and incomplete, but give it a try. +You might want to dig deeper - and add your own log messages where you expect or try to find the bug. + +See the `unicorn/qemu/include/qemu/log.h` file for details. +To enable logs, you must recompile Unicorn with the enabled `LOGGING_ENABLED` define. + +Logs are written in different log levels, which might result into a very verbose logging if enabled. +To control the log level information, two environment variables could be used. + +`UNICORN_LOG_LEVEL` and `UNICORN_LOG_DETAIL_LEVEL`. + +These environment variables are parsed into `uint32_t` values once, (due to performance reasons) +so set these environment variables before you execute any line of Unicorn. +Allowed are hexa-decimal, decimal and octal values, which fits into a buffer of 10 chars. (see stroul for details). + +To define how detailed and what should be logged, use the following environment variables: + +- `UNICORN_LOG_LEVEL`=\<32bit mask\> + - The qemu bit mask what should be logged. + - Use the value of `UINT32_MAX` to log everything. + - If no bit is set in the mask, there will be no logging. +- `UNICORN_LOG_DETAIL_LEVEL`=\ + - The level defines how the filename and line is constructed. + - 0: no filename and no line is used. + - 1: full filename including the leading path is used with line information. + - 2: just the filename with line information. It might be a little confusing, + as the file name can be used in several places. + - If unsure or unwanted, leave this variable undefined or set it to 0. + +As an example to set up the environment for python correctly, see the example below. + +```python +import os +os.environ['UNICORN_LOG_LEVEL'] = "0xFFFFFFFF" # verbose - print anything +os.environ['UNICORN_LOG_DETAIL_LEVEL'] = "1" # full filename with line info +``` + +Please note that file names are statically compiled in and can reveal the paths +of the file system used during compilation. + +## My code does not do what I would expect - is this a bug? + +Please create an github issue and provide as much details as possible. + +- [ ] Simplified version of your script / source + - Make sure that "no" external dependencies are needed. + - E.g. remove additional use of capstone or CTF tools. +- [ ] Used Unicorn git-hash commit + - Make sure to exclude any changes of you made in unicorn. + - Alternativily provide the repo link to your commit. +- [ ] Detailed explaination what is expected + - Try to verify if the instructions can be processed by qemu. + - Dumping the registers of unicorn and qemu helps a lot. +- [ ] Detailed explaination what is observed + - Describe what's going on (and what you might think about it). +- [ ] Output from your executed script + - You might have additional log messages which could be helpful. +- [ ] Output from the qemu-logs + - Try to gather more informations by enabling the qemu logging. +- [ ] More details + - Attach more details to help reproduce the bug. + - Like attaching a repo link to the CTF challenge containing the binary or source code. + ## I'd like to make contributions, where do I start? See [milestones](https://github.com/unicorn-engine/unicorn/milestones) and [coding convention](https://github.com/unicorn-engine/unicorn/wiki/Coding-Convention