diff --git a/.gitignore b/.gitignore index f70e3e10..14b31c30 100644 --- a/.gitignore +++ b/.gitignore @@ -101,3 +101,6 @@ obj-intel64/* #VERSION files from CI VERSION + +# Doxygen generated documentation +docs/doxygen/ diff --git a/CMakeLists.txt b/CMakeLists.txt index aaf2b350..5769f9dc 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -347,3 +347,9 @@ if(REMILL_ENABLE_TESTING) add_subdirectory(tests/AArch64) endif() endif() + +# +# Documentation +# + +include("${CMAKE_CURRENT_SOURCE_DIR}/cmake/doxygen.cmake") diff --git a/Doxyfile b/Doxyfile new file mode 100644 index 00000000..f2a87295 --- /dev/null +++ b/Doxyfile @@ -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 = + diff --git a/README.md b/README.md index b2e5d2ac..db19c380 100644 --- a/README.md +++ b/README.md @@ -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/). diff --git a/cmake/doxygen.cmake b/cmake/doxygen.cmake new file mode 100644 index 00000000..8c3e0dfe --- /dev/null +++ b/cmake/doxygen.cmake @@ -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() + diff --git a/docs/DOCUMENTATION.md b/docs/DOCUMENTATION.md new file mode 100644 index 00000000..82f9abbb --- /dev/null +++ b/docs/DOCUMENTATION.md @@ -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) diff --git a/docs/doxygen-mainpage.md b/docs/doxygen-mainpage.md new file mode 100644 index 00000000..e8d8af93 --- /dev/null +++ b/docs/doxygen-mainpage.md @@ -0,0 +1,114 @@ +# Remill API Documentation {#mainpage} + +![Remill Logo](remill_logo.png) + +## 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 +#include +#include + +// 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) +