mirror of
https://github.com/revng/revng
synced 2026-06-21 14:07:57 +00:00
docs: fix
Fix the docs so that `revng test-docs` passes. Rework the `model-from-scrach.md` to use the new pipeline.
This commit is contained in:
Giacomo Vercesi
committed by
Alessandro Di Federico
Alessandro Di Federico
parent
bc765c1104
commit
a0e3fd419e
@@ -378,6 +378,8 @@ add_custom_command(
|
||||
"share/doc/revng/references/cli/revng-common.md"
|
||||
"share/doc/revng/references/cli/revng-artifact.md"
|
||||
"share/doc/revng/references/cli/revng-analyze.md"
|
||||
"share/doc/revng/references/cli/revng2-project-analyze.md"
|
||||
"share/doc/revng/references/cli/revng2-project-artifact.md"
|
||||
"share/doc/revng/user-manual/index.md"
|
||||
"share/doc/revng/user-manual/initial-setup.md"
|
||||
"share/doc/revng/user-manual/key-concepts/metaaddress.md"
|
||||
|
||||
@@ -36,6 +36,8 @@ nav:
|
||||
- revng-common: references/cli/revng-common.md
|
||||
- revng-artifact: references/cli/revng-artifact.md
|
||||
- revng-analyze: references/cli/revng-analyze.md
|
||||
- revng2-project-artifact: references/cli/revng2-project-artifact.md
|
||||
- revng2-project-analyze: references/cli/revng2-project-analyze.md
|
||||
- "MIME types": references/mime-types.md
|
||||
- PTML: references/ptml.md
|
||||
- Pipeline: references/pipeline.md
|
||||
|
||||
@@ -0,0 +1,48 @@
|
||||
`revng2-project-analyze`
|
||||
================
|
||||
|
||||
NAME
|
||||
----
|
||||
|
||||
`revng2 project analyze` - Run an analysis or analysis list.
|
||||
|
||||
SYNOPSIS
|
||||
--------
|
||||
|
||||
revng2 project analyze ANALYSIS [options]
|
||||
|
||||
DESCRIPTION
|
||||
-----------
|
||||
|
||||
Runs the analysis `ANALYSIS`.
|
||||
|
||||
Run `revng2 project analyze --help` to list the available analyses.
|
||||
The documentation describes [what an analysis is](../../user-manual/key-concepts/artifacts-and-analyses.md#analyses), the [available analyses and their options](../analyses.md).
|
||||
|
||||
OPTIONS
|
||||
-------
|
||||
|
||||
<!-- TODO: use mkdocs-click or something similar to auto-generate the list command line options -->
|
||||
|
||||
`-C DIR`
|
||||
: When running the command, make it as the command was run in the directory `DIR`
|
||||
|
||||
`-o PATH`
|
||||
: Instead of dumping the model to standard output, save it to `PATH`.
|
||||
|
||||
`-c CONFIGURATION`
|
||||
: Use the specified configuration string when running the analysis.
|
||||
|
||||
EXAMPLES
|
||||
--------
|
||||
|
||||
A single command to run the initial auto analysis:
|
||||
|
||||
```{bash notest}
|
||||
revng project analyze initial-auto-analysis
|
||||
```
|
||||
|
||||
SEE ALSO
|
||||
--------
|
||||
|
||||
[`revng2-project-artifact`](revng2-project-artifact.md)
|
||||
@@ -0,0 +1,54 @@
|
||||
`revng2-project-artifact`
|
||||
================
|
||||
|
||||
NAME
|
||||
----
|
||||
|
||||
`revng2 project artifact` - Produce an artifact.
|
||||
|
||||
SYNOPSIS
|
||||
--------
|
||||
|
||||
revng2 project artifact ARTIFACT [OPTIONS] [OBJECT [OBJECT [...]]]
|
||||
|
||||
DESCRIPTION
|
||||
-----------
|
||||
|
||||
Produces the artifact `ARTIFACT`.
|
||||
|
||||
If no `OBJECT` is specified then the command will produce all available objects.
|
||||
|
||||
Run `revng2 project artifact --help` to list the available artifacts.
|
||||
The documentation describes [what an artifact is](../../user-manual/key-concepts/artifacts-and-analyses.md#artifacts) and the [available artifacts](../artifacts.md).
|
||||
|
||||
OPTIONS
|
||||
-------
|
||||
|
||||
<!-- TODO: use mkdocs-click or something similar to auto-generate the list command line options -->
|
||||
|
||||
`-C DIR`
|
||||
: When running the command, make it as the command was run in the directory `DIR`
|
||||
|
||||
`--list`
|
||||
: List the available objects for this artifact and the quit.
|
||||
|
||||
`-o PATH`
|
||||
: Store the artifact to `PATH`.
|
||||
By default, the artifact is written to standard output.
|
||||
|
||||
`--format [tar|yaml]` `--tar` `--yaml`
|
||||
: Select the output format. By default the artifact is emitted as a YAML dictionary `object -> data`, where `data` is text data if the artifact's MIME is textual or a Base64 encoding if it's binary. Tar output emits a plain tar (without compression) without any transformation to the data.
|
||||
|
||||
EXAMPLES
|
||||
--------
|
||||
|
||||
A single command to produce the decompiled code saving the result to `decompiled.c`:
|
||||
|
||||
```{bash notest}
|
||||
revng2 project artifact emit-c-as-single-file -o decompiled.c.yml
|
||||
```
|
||||
|
||||
SEE ALSO
|
||||
--------
|
||||
|
||||
[`revng2-project-analyze`](revng2-project-analyze.md)
|
||||
@@ -36,24 +36,21 @@ After that, you can to import a binary and run the [*initial auto analyses*](ref
|
||||
|
||||
Once you have successfully loaded a binary, you can obtain the available artifacts:
|
||||
|
||||
```{python ignoreoutput=2,6,9,13,20}
|
||||
# Get artifact through the `project`
|
||||
```{python ignoreoutput=3,7,11,14,17}
|
||||
# Get artifact through the `project`, this will return a dictionary mapping the
|
||||
# Object ID to the data
|
||||
>>> project.model.get_artifact("disassemble")
|
||||
|
||||
# Pass functions that you want to get artifacts from, the second argument is a
|
||||
# `list` so you can pass multiple functions
|
||||
>>> project.model.get_artifact("disassemble", [project.model.Functions[0]])
|
||||
|
||||
# Get artifact through a `function`, this is equal to above
|
||||
# Get artifact through a `function`, this is the same as above but
|
||||
# automatically returns a single element
|
||||
>>> project.model.Functions[0].get_artifact("disassemble")
|
||||
|
||||
# Get multiple artifacts at once. Pass `None` if you wish to get the artifact
|
||||
# for all the targets
|
||||
>>> project.model.get_artifacts({
|
||||
... "disassemble": [project.model.Functions[0],
|
||||
... project.model.Functions[1]],
|
||||
... "decompile": None
|
||||
... })
|
||||
# Short-hand for the above
|
||||
>>> project.model.Functions[0].disassemble
|
||||
|
||||
# You can also get the artifact for `TypeDefinitions`
|
||||
>>> project.model.TypeDefinitions[1].get_artifact("emit-type-definitions")
|
||||
@@ -62,14 +59,14 @@ Once you have successfully loaded a binary, you can obtain the available artifac
|
||||
You can also `parse` the result with `ptml`:
|
||||
|
||||
```{python ignoreoutput=2}
|
||||
>>> result = project.model.Functions[0].get_artifact("disassemble")
|
||||
>>> result = project.model.Functions[0].disassemble
|
||||
>>> result.parse()
|
||||
```
|
||||
|
||||
LLVM modules can be parsed and explored via the `llvmcpy` python module:
|
||||
|
||||
```python
|
||||
>>> lifted = project.model.get_artifact("lift")
|
||||
>>> lifted = project.model.get_artifact("lift")["/binary"]
|
||||
|
||||
# Use the parsed IR
|
||||
>>> for function in lifted.module().iter_functions():
|
||||
@@ -104,7 +101,7 @@ After you make a change, you need to invoke the `commit` method in order for the
|
||||
If you want to run a set of predefined analyses, you can run them with:
|
||||
|
||||
```python
|
||||
>>> project.model.analyses_list("revng-initial-auto-analysis")
|
||||
>>> project.model.analyze("initial-auto-analysis")
|
||||
```
|
||||
|
||||
If you want to run a specific [analysis](../analyses/) instead, you can do that too.
|
||||
|
||||
@@ -36,7 +36,19 @@ Let's now create a simple model that enables us to decompile this simple functio
|
||||
|
||||
### Step 1: Loading
|
||||
|
||||
The first thing rev.ng needs to know is the architecture and the ABI of the program:
|
||||
The first thing rev.ng needs to know is which binary to load, this is done by specifying a [`BinaryIdentifier`](../../references/model.md#binaryidentifier) entry in `Binaries`:
|
||||
|
||||
```yaml title="model.yml"
|
||||
Binaries:
|
||||
- Index: 0
|
||||
Name: sum
|
||||
# Output of `sha256sum sum`
|
||||
Hash: bba591a825f58c1b94fc4d8c13f5d3531a89282cb3319a1418ee3f8396880567
|
||||
# Output of `wc -c sum`
|
||||
Size: 8
|
||||
```
|
||||
|
||||
Then rev.ng needs to know is the architecture and the ABI of the program:
|
||||
|
||||
```yaml title="model.yml"
|
||||
Architecture: x86_64
|
||||
@@ -60,9 +72,10 @@ Segments:
|
||||
IsReadable: true
|
||||
IsWriteable: false
|
||||
IsExecutable: true
|
||||
Binary: /Binaries/0
|
||||
```
|
||||
|
||||
The piece of model above tells rev.ng to take 7 bytes from the file and load them at address `0x400000` as `+rx` data (i.e., code).
|
||||
The piece of model above tells rev.ng to take 7 bytes from the file and load them at address `0x400000` as `r-x` data (i.e., code).
|
||||
|
||||
### Step 2: Function list
|
||||
|
||||
@@ -80,22 +93,20 @@ Note how here the type of the `MetaAddress` is not `Generic64` but `Code_x86_64`
|
||||
### Step 3: Disassembly
|
||||
|
||||
At this point, we provided rev.ng enough information to be able to show us the disassembly of our program.
|
||||
Let's produce the [`disassemble` artifact](../../references/artifacts.md#disassemble-artifact) using [`revng-artifact`](../../references/cli/revng-artifact.md).
|
||||
Let's produce the [`disassemble` artifact](../../references/artifacts.md#disassemble-artifact) using [`revng2 project artifact`](../../references/cli/revng2-project-artifact.md).
|
||||
|
||||
```bash
|
||||
$ revng artifact disassemble sum --model model.yml | revng ptml
|
||||
0x400000:Code_x86_64: |-
|
||||
$ revng2 project artifact disassemble | revng ptml
|
||||
/function/0x400000:Code_x86_64: |-
|
||||
function_0x400000_Code_x86_64:
|
||||
400000: 48 01 f7 add rdi, rsi
|
||||
400003: 48 89 f8 mov rax, rdi
|
||||
400006: c3 ret
|
||||
```
|
||||
|
||||
The output of the `revng artifact disassemble` command is a `tar.gz` composed by one file for each input function. Each file is an assembly listing decorated using [PTML](../../references/ptml.md).
|
||||
The output of the `revng2 project artifact disassemble` command is a `yaml` composed by one entry for each input function. Each file is an assembly listing decorated using [PTML](../../references/ptml.md).
|
||||
<br />`revng ptml` strips away all this details and outputs a YAML dictionary with one entry for each disassembled function.
|
||||
|
||||
For further information on the file types emitted by `revng artifact`, see the [MIME types documentation](../../references/mime-types.md).
|
||||
|
||||
### Step 4: Defining a function prototype
|
||||
|
||||
In order to decompile the function, we need to provide a function prototype.
|
||||
@@ -168,14 +179,15 @@ Basically, this specifies that the function type we created above is the prototy
|
||||
### Step 5: Decompiling
|
||||
|
||||
At this point, we have all the information we need to successfully decompile our example program.
|
||||
To do so, we can ask rev.ng to produce the [`decompile` artifact](../../references/artifacts.md#decompile-artifact):
|
||||
To do so, we can ask rev.ng to produce the [`emit-c` artifact](../../references/artifacts.md#emit-c-artifact):
|
||||
|
||||
```c
|
||||
$ revng artifact decompile sum --model model.yml | revng ptml
|
||||
0x400000:Code_x86_64:
|
||||
uint64_t function_0x400000_Code_x86_64(uint64_t unnamed_arg_0, uint64_t unnamed_arg_1) {
|
||||
return unnamed_arg_0 + unnamed_arg_1;
|
||||
```bash
|
||||
$ revng2 project artifact emit-c | revng ptml
|
||||
/function/0x400000:Code_x86_64: |-
|
||||
uint64_t function_0x400000_Code_x86_64(uint64_t argument_0, uint64_t argument_1) {
|
||||
return (uint64_t) ((generic64_t) argument_0 + (generic64_t) argument_1);
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
### Step 6: Renaming
|
||||
@@ -229,11 +241,10 @@ Almost everything in the model can have a name. Let's add a name to the function
|
||||
Here's what we get now if we try to decompile again:
|
||||
|
||||
```bash
|
||||
$ revng artifact decompile sum --model model.yml | revng ptml
|
||||
0x400000:Code_x86_64: |-
|
||||
_ABI(SystemV_x86_64)
|
||||
$ revng2 project artifact emit-c | revng ptml
|
||||
/function/0x400000:Code_x86_64: |-
|
||||
uint64_t Sum(uint64_t FirstAddend, uint64_t SecondAddend) {
|
||||
return FirstAddend + SecondAddend;
|
||||
return (uint64_t) ((generic64_t) FirstAddend + (generic64_t) SecondAddend);
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user