pgoodman
commented
10 years ago There is no such document, unfortunately. For the time being I have no plans to make a document as I'm already working on the next version of Granary (very early stages, major differences in design).
Much of DynamoRIO's instruction manipulation API is maintained, as Granary internally uses DynamoRIO's instruction representation. Just about everything else is different though.
A major thing lacking is a high-level "how everything fits together" picture. This is exacerbated by how instrumentation clients are linked in with Granary.
For example, in the following from the null client:
/// Instrucment a basic block.
granary::instrumentation_policy null_policy::visit_app_instructions(
granary::cpu_state_handle cpu,
granary::basic_block_state &bb,
granary::instruction_list &ls
) throw() {
return granary::policy_for<null_policy>();
}The visit_app_instructions and visit_host_instructions methods on a "policy" class are functionally similar to DynamoRIO's BB instrumentation events. visit_app_instructions is invoked on module basic blocks, and visit_host_instructions is invoked on kernel basic blocks.
cpu allows your tool to access Granary-specific CPU-private state. Your client can extend Granary's CPU-private state by defining a struct cpu_state in the client namespace, doing a #define of CLIENT_cpu_state, and adding an client-specific #include of the file containing your struct cpu_state in granary/clients/state.h.
bb is like cpu, but it represents basic-block specific state. For example, if you wanted to count the number of executions of each basic block, and wanted Granary to be responsible for allocating the counter itself, then you'd put it into your own struct basic_block_state within the client namespace. Then #define CLIENT_basic_block_state, and do the same #include thing.
ls is a list of instructions. Some of the clients have examples of how to iterate over instructions, and inject new instructions. This is functionally similar to DynamoRIO's instrlist_t data structure. You can see examples of inserting instructions and call-outs here: https://github.com/Granary/granary/blob/master/clients/cfg/instrument.cc#L120
Now, you might be wondering "wtf is this policy stuff?". For the time being, my suggestion is to completely ignore it, but when you want to start something, just duplicate the clients/null folder, and search & replace every null with your own thing, e.g. shadow.
So, if you just copy & paste a lot of what is there in the null client, then it's a great starting point. There are other things in the null client's instrument.cc. namely: null_policy::handle_interrupt and handle_kernel_interrupt.
The first is a method that Granary invokes when code instrumented by the null policy is interrupted. The second is invoked by Granary when native kernel code is interrupted. These should only be defined / used if CONFIG_FEATURE_CLIENT_HANDLE_INTERRUPT is defined as 1 in granary/globals.h.
The way "everything" fits together is rather unusual, but some good starting points are to search the Granary source code for uses of the macro GRANARY_ENTRYPOINT, which document the entrypoint functions / methods into Granary from the code cache. A major difference between Granary and DynamoRIO is that there is no dispatcher per-se. The method code_cache::find( granary/code_cache.cc) generally handles this role, but you will notice that every GRANARY_ENTRYPOINT-marked method always returns, and doesn't do the sort of coroutine call_switch_stack as DynamoRIO does to return execution back to the code cache.
In Granary, execution transfers from the code cache onto a CPU-private stack, and then when on the CPU-private stack, some internal code calls into Granary's code_cache::find method. This can sort of be seen in granary/dbl.cc which is used to "mangle" direct branches into hot-code patchable direct branches, that start by branching into "edge code" that eventually invokes code_cache::find, then patches the direct branch to jump to its intended target elsewhere in the code cache.
Here's a walk through of how execution leaves the code cache and makes it to one of the instrumentation functions:
- This code https://github.com/Granary/granary/blob/master/granary/dbl.cc#L173 is targeted by some edge code, switches stacks, then calls the patch_instruction entrypoint function:
- (https://github.com/Granary/granary/blob/master/granary/dbl.cc#L63) which does a lookup in the code cache index by calling code_cache::find:
- (https://github.com/Granary/granary/blob/master/granary/dbl.cc#L129), which does a lookup in the code cache hash table: 4. https://github.com/Granary/granary/blob/master/granary/code_cache.cc#L109, and if this (and a few other lookups) fail, goes and builds the basic block: 5. https://github.com/Granary/granary/blob/master/granary/code_cache.cc#L204, which invokes the basic block decoder/translator: 6. https://github.com/Granary/granary/blob/master/granary/basic_block.cc#L1089, which decode and instruments one or more basic blocks according to an "instrumentation policy" (e.g. null_policy): 7. https://github.com/Granary/granary/blob/master/granary/basic_block.cc#L765, which invokes the policy's instrument method, that chooses one of visit_app_instructions or visit_host_instructions (based on module or kernel code):
- https://github.com/Granary/granary/blob/master/granary/policy.h#L208, and that leads to something like null_policy::visit_app_instructionsbeing invoked to manipulate the instructions.
Hopefully this will give you some more insight into the way things connect together. It is by no means well structured or engineered, and I apologize for that. Let me know if this clears up any questions or serves to raise more.
Best Regards,
Peter Goodman, http://www.petergoodman.me 65 High Park Ave., Toronto, Ontario M6P 2R7
On 10 March 2014 21:11, Ren Zhen notifications@github.com wrote:
Hi peter, So far, granary has not any API Document and a clear description of the interface between DynamoRIO and granary(how the both combined together). Lacking API documents make it so difficult to use the granary framework.
So,do you plan to do this work in future? I'd like to contribute to this work,but I'm just a newer here.
cheers up :)
Reply to this email directly or view it on GitHubhttps://github.com/Granary/granary/issues/20 .
renzhengeek
Hi peter, So far, granary has not any API Document and a clear description of the interface between DynamoRIO and granary(how the both combined together). Lacking API documents make it so difficult to use the granary framework.
So,do you plan to do this work in future? I'd like to contribute to this work,but I'm just a newer here.
cheers up :)