mirror of
https://github.com/lifting-bits/remill
synced 2026-06-21 13:56:07 +00:00
[DOCS] Included doxygen for better code documentation
This commit is contained in:
wizardengineer
committed by
Kyle Elliott
Kyle Elliott
parent
4f08aef71d
commit
bfd4b05a8e
@@ -101,3 +101,6 @@ obj-intel64/*
|
||||
|
||||
#VERSION files from CI
|
||||
VERSION
|
||||
|
||||
# Doxygen generated documentation
|
||||
docs/doxygen/
|
||||
|
||||
@@ -347,3 +347,9 @@ if(REMILL_ENABLE_TESTING)
|
||||
add_subdirectory(tests/AArch64)
|
||||
endif()
|
||||
endif()
|
||||
|
||||
#
|
||||
# Documentation
|
||||
#
|
||||
|
||||
include("${CMAKE_CURRENT_SOURCE_DIR}/cmake/doxygen.cmake")
|
||||
|
||||
@@ -0,0 +1,359 @@
|
||||
# Doxyfile for Remill
|
||||
# Configuration file for Doxygen documentation generation
|
||||
|
||||
#---------------------------------------------------------------------------
|
||||
# Project related configuration options
|
||||
#---------------------------------------------------------------------------
|
||||
|
||||
DOXYFILE_ENCODING = UTF-8
|
||||
PROJECT_NAME = "Remill"
|
||||
PROJECT_NUMBER =
|
||||
PROJECT_BRIEF = "Machine code to LLVM bitcode binary translation library"
|
||||
PROJECT_LOGO = NO
|
||||
OUTPUT_DIRECTORY = docs/doxygen
|
||||
CREATE_SUBDIRS = NO
|
||||
ALLOW_UNICODE_NAMES = NO
|
||||
OUTPUT_LANGUAGE = English
|
||||
BRIEF_MEMBER_DESC = YES
|
||||
REPEAT_BRIEF = YES
|
||||
ABBREVIATE_BRIEF =
|
||||
ALWAYS_DETAILED_SEC = NO
|
||||
INLINE_INHERITED_MEMB = NO
|
||||
FULL_PATH_NAMES = YES
|
||||
STRIP_FROM_PATH =
|
||||
STRIP_FROM_INC_PATH =
|
||||
SHORT_NAMES = NO
|
||||
JAVADOC_AUTOBRIEF = YES
|
||||
JAVADOC_BANNER = NO
|
||||
QT_AUTOBRIEF = NO
|
||||
MULTILINE_CPP_IS_BRIEF = NO
|
||||
PYTHON_DOCSTRING = YES
|
||||
INHERIT_DOCS = YES
|
||||
SEPARATE_MEMBER_PAGES = NO
|
||||
TAB_SIZE = 2
|
||||
ALIASES =
|
||||
OPTIMIZE_OUTPUT_FOR_C = NO
|
||||
OPTIMIZE_OUTPUT_JAVA = NO
|
||||
OPTIMIZE_FOR_FORTRAN = NO
|
||||
OPTIMIZE_OUTPUT_VHDL = NO
|
||||
OPTIMIZE_OUTPUT_SLICE = NO
|
||||
EXTENSION_MAPPING =
|
||||
MARKDOWN_SUPPORT = YES
|
||||
TOC_INCLUDE_HEADINGS = 5
|
||||
MARKDOWN_ID_STYLE = DOXYGEN
|
||||
AUTOLINK_SUPPORT = YES
|
||||
BUILTIN_STL_SUPPORT = YES
|
||||
CPP_CLI_SUPPORT = NO
|
||||
SIP_SUPPORT = NO
|
||||
IDL_PROPERTY_SUPPORT = YES
|
||||
DISTRIBUTE_GROUP_DOC = NO
|
||||
GROUP_NESTED_COMPOUNDS = NO
|
||||
SUBGROUPING = YES
|
||||
INLINE_GROUPED_CLASSES = NO
|
||||
INLINE_SIMPLE_STRUCTS = NO
|
||||
TYPEDEF_HIDES_STRUCT = NO
|
||||
LOOKUP_CACHE_SIZE = 0
|
||||
NUM_PROC_THREADS = 1
|
||||
|
||||
#---------------------------------------------------------------------------
|
||||
# Build related configuration options
|
||||
#---------------------------------------------------------------------------
|
||||
|
||||
EXTRACT_ALL = YES
|
||||
EXTRACT_PRIVATE = NO
|
||||
EXTRACT_PRIV_VIRTUAL = NO
|
||||
EXTRACT_PACKAGE = NO
|
||||
EXTRACT_STATIC = YES
|
||||
EXTRACT_LOCAL_CLASSES = YES
|
||||
EXTRACT_LOCAL_METHODS = NO
|
||||
EXTRACT_ANON_NSPACES = NO
|
||||
RESOLVE_UNNAMED_PARAMS = YES
|
||||
HIDE_UNDOC_MEMBERS = NO
|
||||
HIDE_UNDOC_CLASSES = NO
|
||||
HIDE_FRIEND_COMPOUNDS = NO
|
||||
HIDE_IN_BODY_DOCS = NO
|
||||
INTERNAL_DOCS = NO
|
||||
CASE_SENSE_NAMES = YES
|
||||
HIDE_SCOPE_NAMES = NO
|
||||
HIDE_COMPOUND_REFERENCE= NO
|
||||
SHOW_HEADERFILE = YES
|
||||
SHOW_INCLUDE_FILES = YES
|
||||
SHOW_GROUPED_MEMB_INC = NO
|
||||
FORCE_LOCAL_INCLUDES = NO
|
||||
INLINE_INFO = YES
|
||||
SORT_MEMBER_DOCS = YES
|
||||
SORT_BRIEF_DOCS = NO
|
||||
SORT_MEMBERS_CTORS_1ST = NO
|
||||
SORT_GROUP_NAMES = NO
|
||||
SORT_BY_SCOPE_NAME = NO
|
||||
STRICT_PROTO_MATCHING = NO
|
||||
GENERATE_TODOLIST = YES
|
||||
GENERATE_TESTLIST = YES
|
||||
GENERATE_BUGLIST = YES
|
||||
GENERATE_DEPRECATEDLIST= YES
|
||||
ENABLED_SECTIONS =
|
||||
MAX_INITIALIZER_LINES = 30
|
||||
SHOW_USED_FILES = YES
|
||||
SHOW_FILES = YES
|
||||
SHOW_NAMESPACES = YES
|
||||
FILE_VERSION_FILTER =
|
||||
LAYOUT_FILE =
|
||||
CITE_BIB_FILES =
|
||||
|
||||
#---------------------------------------------------------------------------
|
||||
# Configuration options related to warning and progress messages
|
||||
#---------------------------------------------------------------------------
|
||||
|
||||
QUIET = NO
|
||||
WARNINGS = YES
|
||||
WARN_IF_UNDOCUMENTED = YES
|
||||
WARN_IF_DOC_ERROR = YES
|
||||
WARN_IF_INCOMPLETE_DOC = YES
|
||||
WARN_NO_PARAMDOC = NO
|
||||
WARN_IF_UNDOC_ENUM_VAL = NO
|
||||
WARN_AS_ERROR = NO
|
||||
WARN_FORMAT = "$file:$line: $text"
|
||||
WARN_LINE_FORMAT = "at line $line of file $file"
|
||||
WARN_LOGFILE =
|
||||
|
||||
#---------------------------------------------------------------------------
|
||||
# Configuration options related to the input files
|
||||
#---------------------------------------------------------------------------
|
||||
|
||||
INPUT = include/remill \
|
||||
lib \
|
||||
docs/README.md \
|
||||
docs/DESIGN.md \
|
||||
docs/INTRINSICS.md \
|
||||
docs/LIFE_OF_AN_INSTRUCTION.md \
|
||||
docs/ADD_AN_INSTRUCTION.md \
|
||||
docs/CONTRIBUTING.md \
|
||||
README.md
|
||||
INPUT_ENCODING = UTF-8
|
||||
INPUT_FILE_ENCODING =
|
||||
FILE_PATTERNS = *.h \
|
||||
*.cpp \
|
||||
*.md
|
||||
RECURSIVE = YES
|
||||
EXCLUDE = build \
|
||||
dependencies \
|
||||
tests
|
||||
EXCLUDE_SYMLINKS = NO
|
||||
EXCLUDE_PATTERNS = */build/* \
|
||||
*/dependencies/* \
|
||||
*/.git/* \
|
||||
*/test/*
|
||||
EXCLUDE_SYMBOLS =
|
||||
EXAMPLE_PATH =
|
||||
EXAMPLE_PATTERNS =
|
||||
EXAMPLE_RECURSIVE = NO
|
||||
IMAGE_PATH = docs/images
|
||||
INPUT_FILTER =
|
||||
FILTER_PATTERNS =
|
||||
FILTER_SOURCE_FILES = NO
|
||||
FILTER_SOURCE_PATTERNS =
|
||||
USE_MDFILE_AS_MAINPAGE = README.md
|
||||
|
||||
#---------------------------------------------------------------------------
|
||||
# Configuration options related to source browsing
|
||||
#---------------------------------------------------------------------------
|
||||
|
||||
SOURCE_BROWSER = YES
|
||||
INLINE_SOURCES = NO
|
||||
STRIP_CODE_COMMENTS = YES
|
||||
REFERENCED_BY_RELATION = YES
|
||||
REFERENCES_RELATION = YES
|
||||
REFERENCES_LINK_SOURCE = YES
|
||||
SOURCE_TOOLTIPS = YES
|
||||
USE_HTAGS = NO
|
||||
VERBATIM_HEADERS = YES
|
||||
CLANG_ASSISTED_PARSING = NO
|
||||
CLANG_ADD_INC_PATHS = YES
|
||||
CLANG_OPTIONS =
|
||||
CLANG_DATABASE_PATH =
|
||||
|
||||
#---------------------------------------------------------------------------
|
||||
# Configuration options related to the alphabetical class index
|
||||
#---------------------------------------------------------------------------
|
||||
|
||||
ALPHABETICAL_INDEX = YES
|
||||
IGNORE_PREFIX =
|
||||
|
||||
#---------------------------------------------------------------------------
|
||||
# Configuration options related to the HTML output
|
||||
#---------------------------------------------------------------------------
|
||||
|
||||
GENERATE_HTML = YES
|
||||
HTML_OUTPUT = html
|
||||
HTML_FILE_EXTENSION = .html
|
||||
HTML_HEADER =
|
||||
HTML_FOOTER =
|
||||
HTML_STYLESHEET =
|
||||
HTML_EXTRA_STYLESHEET =
|
||||
HTML_EXTRA_FILES =
|
||||
HTML_COLORSTYLE = AUTO_LIGHT
|
||||
HTML_COLORSTYLE_HUE = 220
|
||||
HTML_COLORSTYLE_SAT = 100
|
||||
HTML_COLORSTYLE_GAMMA = 80
|
||||
HTML_DYNAMIC_MENUS = YES
|
||||
HTML_DYNAMIC_SECTIONS = NO
|
||||
HTML_CODE_FOLDING = YES
|
||||
HTML_COPY_CLIPBOARD = YES
|
||||
HTML_PROJECT_COOKIE =
|
||||
HTML_INDEX_NUM_ENTRIES = 100
|
||||
GENERATE_DOCSET = NO
|
||||
GENERATE_HTMLHELP = NO
|
||||
GENERATE_QHP = NO
|
||||
GENERATE_ECLIPSEHELP = NO
|
||||
DISABLE_INDEX = NO
|
||||
GENERATE_TREEVIEW = YES
|
||||
FULL_SIDEBAR = NO
|
||||
ENUM_VALUES_PER_LINE = 4
|
||||
TREEVIEW_WIDTH = 250
|
||||
EXT_LINKS_IN_WINDOW = NO
|
||||
OBFUSCATE_EMAILS = YES
|
||||
HTML_FORMULA_FORMAT = png
|
||||
FORMULA_FONTSIZE = 10
|
||||
FORMULA_MACROFILE =
|
||||
USE_MATHJAX = NO
|
||||
SEARCHENGINE = YES
|
||||
SERVER_BASED_SEARCH = NO
|
||||
EXTERNAL_SEARCH = NO
|
||||
SEARCHENGINE_URL =
|
||||
SEARCHDATA_FILE = searchdata.xml
|
||||
EXTERNAL_SEARCH_ID =
|
||||
EXTRA_SEARCH_MAPPINGS =
|
||||
|
||||
#---------------------------------------------------------------------------
|
||||
# Configuration options related to the LaTeX output
|
||||
#---------------------------------------------------------------------------
|
||||
|
||||
GENERATE_LATEX = NO
|
||||
LATEX_OUTPUT = latex
|
||||
LATEX_CMD_NAME =
|
||||
MAKEINDEX_CMD_NAME = makeindex
|
||||
LATEX_MAKEINDEX_CMD = makeindex
|
||||
COMPACT_LATEX = NO
|
||||
PAPER_TYPE = a4
|
||||
EXTRA_PACKAGES =
|
||||
LATEX_HEADER =
|
||||
LATEX_FOOTER =
|
||||
LATEX_EXTRA_STYLESHEET =
|
||||
LATEX_EXTRA_FILES =
|
||||
PDF_HYPERLINKS = YES
|
||||
USE_PDFLATEX = YES
|
||||
LATEX_BATCHMODE = NO
|
||||
LATEX_HIDE_INDICES = NO
|
||||
LATEX_BIB_STYLE = plain
|
||||
LATEX_EMOJI_DIRECTORY =
|
||||
|
||||
#---------------------------------------------------------------------------
|
||||
# Configuration options related to the RTF output
|
||||
#---------------------------------------------------------------------------
|
||||
|
||||
GENERATE_RTF = NO
|
||||
|
||||
#---------------------------------------------------------------------------
|
||||
# Configuration options related to the man page output
|
||||
#---------------------------------------------------------------------------
|
||||
|
||||
GENERATE_MAN = NO
|
||||
|
||||
#---------------------------------------------------------------------------
|
||||
# Configuration options related to the XML output
|
||||
#---------------------------------------------------------------------------
|
||||
|
||||
GENERATE_XML = NO
|
||||
|
||||
#---------------------------------------------------------------------------
|
||||
# Configuration options related to the DOCBOOK output
|
||||
#---------------------------------------------------------------------------
|
||||
|
||||
GENERATE_DOCBOOK = NO
|
||||
|
||||
#---------------------------------------------------------------------------
|
||||
# Configuration options for the AutoGen Definitions output
|
||||
#---------------------------------------------------------------------------
|
||||
|
||||
GENERATE_AUTOGEN_DEF = NO
|
||||
|
||||
#---------------------------------------------------------------------------
|
||||
# Configuration options related to Sqlite3 output
|
||||
#---------------------------------------------------------------------------
|
||||
|
||||
GENERATE_SQLITE3 = NO
|
||||
|
||||
#---------------------------------------------------------------------------
|
||||
# Configuration options related to the Perl module output
|
||||
#---------------------------------------------------------------------------
|
||||
|
||||
GENERATE_PERLMOD = NO
|
||||
|
||||
#---------------------------------------------------------------------------
|
||||
# Configuration options related to the preprocessor
|
||||
#---------------------------------------------------------------------------
|
||||
|
||||
ENABLE_PREPROCESSING = YES
|
||||
MACRO_EXPANSION = YES
|
||||
EXPAND_ONLY_PREDEF = NO
|
||||
SEARCH_INCLUDES = YES
|
||||
INCLUDE_PATH = include
|
||||
INCLUDE_FILE_PATTERNS =
|
||||
PREDEFINED = __cplusplus \
|
||||
LLVM_VERSION_MAJOR=17
|
||||
EXPAND_AS_DEFINED =
|
||||
SKIP_FUNCTION_MACROS = YES
|
||||
|
||||
#---------------------------------------------------------------------------
|
||||
# Configuration options related to external references
|
||||
#---------------------------------------------------------------------------
|
||||
|
||||
TAGFILES =
|
||||
GENERATE_TAGFILE =
|
||||
ALLEXTERNALS = NO
|
||||
EXTERNAL_GROUPS = YES
|
||||
EXTERNAL_PAGES = YES
|
||||
|
||||
#---------------------------------------------------------------------------
|
||||
# Configuration options related to diagram generator tools
|
||||
#---------------------------------------------------------------------------
|
||||
|
||||
HIDE_UNDOC_RELATIONS = YES
|
||||
HAVE_DOT = YES
|
||||
DOT_NUM_THREADS = 0
|
||||
DOT_COMMON_ATTR = "fontname=Helvetica,fontsize=10"
|
||||
DOT_EDGE_ATTR = "labelfontname=Helvetica,labelfontsize=10"
|
||||
DOT_NODE_ATTR = "shape=box,height=0.2,width=0.4"
|
||||
DOT_FONTPATH =
|
||||
CLASS_GRAPH = YES
|
||||
COLLABORATION_GRAPH = YES
|
||||
GROUP_GRAPHS = YES
|
||||
UML_LOOK = NO
|
||||
UML_LIMIT_NUM_FIELDS = 10
|
||||
DOT_UML_DETAILS = NO
|
||||
DOT_WRAP_THRESHOLD = 17
|
||||
TEMPLATE_RELATIONS = YES
|
||||
INCLUDE_GRAPH = YES
|
||||
INCLUDED_BY_GRAPH = YES
|
||||
CALL_GRAPH = NO
|
||||
CALLER_GRAPH = NO
|
||||
GRAPHICAL_HIERARCHY = YES
|
||||
DIRECTORY_GRAPH = YES
|
||||
DIR_GRAPH_MAX_DEPTH = 1
|
||||
DOT_IMAGE_FORMAT = svg
|
||||
INTERACTIVE_SVG = YES
|
||||
DOT_PATH =
|
||||
DOTFILE_DIRS =
|
||||
DIA_PATH =
|
||||
DIAFILE_DIRS =
|
||||
PLANTUML_JAR_PATH =
|
||||
PLANTUML_CFG_FILE =
|
||||
PLANTUML_INCLUDE_PATH =
|
||||
DOT_GRAPH_MAX_NODES = 50
|
||||
MAX_DOT_GRAPH_DEPTH = 0
|
||||
DOT_MULTI_TARGETS = NO
|
||||
GENERATE_LEGEND = YES
|
||||
DOT_CLEANUP = YES
|
||||
MSCGEN_TOOL =
|
||||
MSCFILE_DIRS =
|
||||
|
||||
@@ -22,6 +22,25 @@ To understand how Remill works you can take a look at the following resources:
|
||||
|
||||
If you would like to contribute you can check out: [How to contribute](docs/CONTRIBUTING.md)
|
||||
|
||||
### API Documentation
|
||||
|
||||
Generate detailed API documentation using Doxygen:
|
||||
|
||||
```bash
|
||||
# Install Doxygen (macOS)
|
||||
brew install doxygen graphviz
|
||||
|
||||
# Install Doxygen (Ubuntu/Debian)
|
||||
sudo apt-get install doxygen graphviz
|
||||
|
||||
# Generate documentation
|
||||
doxygen
|
||||
|
||||
# Open docs/doxygen/html/index.html in your browser
|
||||
```
|
||||
|
||||
See [docs/DOCUMENTATION.md](docs/DOCUMENTATION.md) for more details on documentation style and contributing.
|
||||
|
||||
## Getting Help
|
||||
|
||||
If you are experiencing undocumented problems with Remill then ask for help in the `#binary-lifting` channel of the [Empire Hacking Slack](https://slack.empirehacking.nyc/).
|
||||
|
||||
@@ -0,0 +1,61 @@
|
||||
# Copyright (c) 2024 Trail of Bits, Inc.
|
||||
#
|
||||
# Licensed under the Apache License, Version 2.0 (the "License");
|
||||
# you may not use this file except in compliance with the License.
|
||||
# You may obtain a copy of the License at
|
||||
#
|
||||
# http://www.apache.org/licenses/LICENSE-2.0
|
||||
#
|
||||
# Unless required by applicable law or agreed to in writing, software
|
||||
# distributed under the License is distributed on an "AS IS" BASIS,
|
||||
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
||||
# See the License for the specific language governing permissions and
|
||||
# limitations under the License.
|
||||
|
||||
# Doxygen documentation generation
|
||||
|
||||
option(REMILL_BUILD_DOCS "Build Doxygen documentation" OFF)
|
||||
|
||||
if(REMILL_BUILD_DOCS)
|
||||
find_package(Doxygen)
|
||||
|
||||
if(DOXYGEN_FOUND)
|
||||
message(STATUS "Doxygen found: ${DOXYGEN_EXECUTABLE}")
|
||||
|
||||
# Set input and output files
|
||||
set(DOXYGEN_IN ${CMAKE_CURRENT_SOURCE_DIR}/Doxyfile)
|
||||
set(DOXYGEN_OUT ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile)
|
||||
|
||||
# Configure the Doxyfile
|
||||
configure_file(${DOXYGEN_IN} ${DOXYGEN_OUT} @ONLY)
|
||||
|
||||
# Create output directory
|
||||
file(MAKE_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}/docs/doxygen)
|
||||
|
||||
# Add custom target for building documentation
|
||||
add_custom_target(docs
|
||||
COMMAND ${DOXYGEN_EXECUTABLE} ${DOXYGEN_OUT}
|
||||
WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}
|
||||
COMMENT "Generating API documentation with Doxygen"
|
||||
VERBATIM
|
||||
)
|
||||
|
||||
# Add custom target for cleaning documentation
|
||||
add_custom_target(docs-clean
|
||||
COMMAND ${CMAKE_COMMAND} -E remove_directory ${CMAKE_CURRENT_SOURCE_DIR}/docs/doxygen
|
||||
COMMENT "Cleaning generated documentation"
|
||||
VERBATIM
|
||||
)
|
||||
|
||||
message(STATUS "Doxygen documentation target 'docs' added")
|
||||
message(STATUS "Run 'cmake --build build --target docs' to generate documentation")
|
||||
|
||||
else()
|
||||
message(WARNING "Doxygen not found. Documentation will not be built.")
|
||||
message(WARNING "Install Doxygen to enable documentation generation:")
|
||||
message(WARNING " - macOS: brew install doxygen graphviz")
|
||||
message(WARNING " - Ubuntu/Debian: sudo apt-get install doxygen graphviz")
|
||||
message(WARNING " - Windows: Download from https://www.doxygen.nl/download.html")
|
||||
endif()
|
||||
endif()
|
||||
|
||||
@@ -0,0 +1,58 @@
|
||||
# API Documentation Guide
|
||||
|
||||
This guide explains how to document Remill code for API documentation generation.
|
||||
|
||||
## Doxygen Comment Style
|
||||
|
||||
When contributing to Remill, please add Doxygen comments to public APIs using Javadoc-style:
|
||||
|
||||
```cpp
|
||||
/**
|
||||
* @brief Short description (one line)
|
||||
*
|
||||
* Longer description with more details.
|
||||
* Can span multiple lines.
|
||||
*
|
||||
* @param name Parameter description
|
||||
* @return Return value description
|
||||
* @throws ExceptionType When this exception is thrown
|
||||
* @see RelatedFunction
|
||||
* @note Important notes
|
||||
* @warning Warnings about usage
|
||||
*/
|
||||
```
|
||||
|
||||
### Common Doxygen Tags
|
||||
|
||||
- `@brief` - Short description
|
||||
- `@param` - Parameter description
|
||||
- `@return` - Return value description
|
||||
- `@throws` - Exception information
|
||||
- `@see` - Cross-references
|
||||
- `@note` - Additional notes
|
||||
- `@warning` - Important warnings
|
||||
- `@deprecated` - Deprecated functionality
|
||||
- `@example` - Usage examples
|
||||
|
||||
### Example
|
||||
|
||||
```cpp
|
||||
/**
|
||||
* @brief Decode a single instruction from bytes
|
||||
*
|
||||
* This function decodes a machine code instruction from the provided
|
||||
* byte buffer and populates the Instruction object.
|
||||
*
|
||||
* @param address The virtual address of the instruction
|
||||
* @param bytes Pointer to the instruction bytes
|
||||
* @param inst Output parameter for the decoded instruction
|
||||
* @return true if decoding was successful, false otherwise
|
||||
*/
|
||||
bool DecodeInstruction(uint64_t address, const uint8_t *bytes,
|
||||
Instruction &inst);
|
||||
```
|
||||
|
||||
## Resources
|
||||
|
||||
- [Doxygen Manual](https://www.doxygen.nl/manual/)
|
||||
- [Doxygen Special Commands](https://www.doxygen.nl/manual/commands.html)
|
||||
@@ -0,0 +1,114 @@
|
||||
# Remill API Documentation {#mainpage}
|
||||
|
||||
|
||||
|
||||
## Overview
|
||||
|
||||
Remill is a static binary translator that translates machine code instructions into [LLVM bitcode](http://llvm.org/docs/LangRef.html).
|
||||
|
||||
### Supported Architectures
|
||||
|
||||
Remill supports the following architectures:
|
||||
- **x86 and AMD64** (including AVX and AVX512)
|
||||
- **AArch64** (64-bit ARMv8)
|
||||
- **AArch32** (32-bit ARMv8 / ARMv7)
|
||||
- **SPARC32** (SPARCv8)
|
||||
- **SPARC64** (SPARCv9)
|
||||
- **PowerPC** (PPC)
|
||||
|
||||
## Key Components
|
||||
|
||||
### Architecture Support (remill::Arch)
|
||||
|
||||
The @ref remill::Arch class is the main entry point for architecture-specific functionality. It provides:
|
||||
- Instruction decoding
|
||||
- Register definitions
|
||||
- Architecture-specific semantics
|
||||
- LLVM module initialization
|
||||
|
||||
See @ref remill/Arch/Arch.h for the main architecture interface.
|
||||
|
||||
### Instruction Lifting
|
||||
|
||||
Remill provides several classes for lifting machine code to LLVM bitcode:
|
||||
|
||||
- @ref remill::InstructionLifter - Lifts individual instructions
|
||||
- @ref remill::TraceLifter - Lifts sequences of instructions (traces)
|
||||
- @ref remill::OperandLifter - Base class for lifting operands
|
||||
|
||||
See @ref remill/BC/InstructionLifter.h and @ref remill/BC/TraceLifter.h for details.
|
||||
|
||||
### Intrinsics
|
||||
|
||||
Remill uses intrinsics to defer implementation of memory accesses and certain control flow operations to consumers of the bitcode. This allows downstream tools to customize behavior.
|
||||
|
||||
See @ref remill/Arch/Runtime/Intrinsics.h for available intrinsics.
|
||||
|
||||
## Getting Started
|
||||
|
||||
### Basic Usage Example
|
||||
|
||||
```cpp
|
||||
#include <remill/Arch/Arch.h>
|
||||
#include <remill/BC/InstructionLifter.h>
|
||||
#include <llvm/IR/LLVMContext.h>
|
||||
|
||||
// Create LLVM context
|
||||
llvm::LLVMContext context;
|
||||
|
||||
// Get architecture instance
|
||||
auto arch = remill::Arch::Get(context, "linux", "amd64");
|
||||
|
||||
// Decode an instruction
|
||||
remill::Instruction inst;
|
||||
auto bytes = /* your instruction bytes */;
|
||||
arch->DecodeInstruction(address, bytes, inst);
|
||||
|
||||
// Lift the instruction
|
||||
remill::InstructionLifter lifter(arch.get(), intrinsics);
|
||||
lifter.LiftIntoBlock(inst, basic_block, state_ptr);
|
||||
```
|
||||
|
||||
## Documentation Sections
|
||||
|
||||
### Architecture Documentation
|
||||
- @ref remill::Arch - Main architecture interface
|
||||
- @ref remill::Instruction - Decoded instruction representation
|
||||
- @ref remill::Register - Register definitions
|
||||
- @ref remill::DecodingContext - Context for instruction decoding
|
||||
|
||||
### Bitcode Generation
|
||||
- @ref remill::InstructionLifter - Single instruction lifting
|
||||
- @ref remill::TraceLifter - Trace lifting
|
||||
- @ref remill::IntrinsicTable - Intrinsic function management
|
||||
- @ref remill::OperandLifter - Operand lifting interface
|
||||
|
||||
### Utilities
|
||||
- @ref remill::BC - Bitcode utilities
|
||||
- @ref remill::OS - Operating system abstractions
|
||||
|
||||
## Additional Resources
|
||||
|
||||
For more detailed information, see:
|
||||
- [Design and Architecture](DESIGN.md)
|
||||
- [Life of an Instruction](LIFE_OF_AN_INSTRUCTION.md)
|
||||
- [How to Add an Instruction](ADD_AN_INSTRUCTION.md)
|
||||
- [Intrinsics Documentation](INTRINSICS.md)
|
||||
- [Contributing Guide](CONTRIBUTING.md)
|
||||
|
||||
## License
|
||||
|
||||
Remill is licensed under the Apache License 2.0. See the LICENSE file for details.
|
||||
|
||||
## Support
|
||||
|
||||
For questions and support:
|
||||
- GitHub Issues: https://github.com/lifting-bits/remill/issues
|
||||
- Slack: #binary-lifting channel on [Empire Hacking Slack](https://slack.empirehacking.nyc/)
|
||||
|
||||
## Project Information
|
||||
|
||||
- **Project Homepage**: https://github.com/lifting-bits/remill
|
||||
- **Developed by**: Trail of Bits
|
||||
- **Related Projects**: [McSema](https://github.com/lifting-bits/mcsema)
|
||||
|
||||
Reference in New Issue
Block a user