macaw/symbolic/README.org

* Overview

The macaw-symbolic library provides a mechanism for translating machine code functions discovered by macaw into Crucible CFGs that can then be symbolically simulated.

The core macaw-symbolic library supports translating generic macaw into crucible, but is not a standalone library.  To translate actual machine code, an /architecture-specific backend/ is required.  For example, macaw-x86-symbolic can be used to translate x86_64 binaries into crucible.  Examples for using macaw-symbolic (and architecture-specific backends) are available in Data.Macaw.Symbolic.

In order to avoid API bloat, the definitions required to implement a new architecture-specific backend are exported through the Data.Macaw.Symbolic.Backend module.

An additional module, Data.Macaw.Symbolic.Memory, provides an example of how to handle memory address translation in the simulator for machine code programs.  There are other possible ways to translate memory addresses, but this module provides a versatile example that can serve many common use cases.
Clean up and document the macaw-symbolic API This cleanup consolidates the interface to macaw symbolic into two (and a half) modules: - Data.Macaw.Symbolic for clients who just need to symbolically simulate machine code - Data.Macaw.Symbolic.Backend for clients that need to implement new architectures - Data.Macaw.Symbolic.Memory provides a reusable example implementation of machine pointer to LLVM memory model pointer mapping Most functions are now documented and are grouped by use case. There are two worked (compiling) examples in the haddocks that show how to translate Macaw into Crucible and then symbolically simulate the results (including setting up all aspects of Crucible). The examples are included in the symbolic/examples directory and can be loaded with GHCi to type check them. The Data.Macaw.Symbolic.Memory module still needs a worked example. There were very few changes to actual code as part of this overhaul, but there are a few places where complicated functions were hidden behind newtypes, as users never need to construct the values themselves (e.g., MacawArchEvalFn and MacawSymbolicArchFunctions). There was also a slight consolidation of constraint synonyms to reduce duplication. All callers will have to be updated. There is also now a README for macaw-symbolic that explains its purpose and includes pointers to the new haddocks. This commit also fixes up the (minor) breakage in the macaw-x86-symbolic implementation from the API changes. 2019-01-11 05:10:30 +03:00			`* Overview`

			`The macaw-symbolic library provides a mechanism for translating machine code functions discovered by macaw into Crucible CFGs that can then be symbolically simulated.`

			`The core macaw-symbolic library supports translating generic macaw into crucible, but is not a standalone library. To translate actual machine code, an /architecture-specific backend/ is required. For example, macaw-x86-symbolic can be used to translate x86_64 binaries into crucible. Examples for using macaw-symbolic (and architecture-specific backends) are available in Data.Macaw.Symbolic.`

			`In order to avoid API bloat, the definitions required to implement a new architecture-specific backend are exported through the Data.Macaw.Symbolic.Backend module.`

			`An additional module, Data.Macaw.Symbolic.Memory, provides an example of how to handle memory address translation in the simulator for machine code programs. There are other possible ways to translate memory addresses, but this module provides a versatile example that can serve many common use cases.`