From 7e93f81bd3346f44d08139472ee41866ce338252 Mon Sep 17 00:00:00 2001 From: Xusheng Date: Thu, 27 May 2021 11:53:16 +0800 Subject: Add user docs for automatic structure member creation --- docs/guide/type.md | 26 ++++++++++++++++++++++++++ docs/img/auto-create-members.png | Bin 0 -> 28429 bytes docs/img/auto-create-one-member.png | Bin 0 -> 22854 bytes docs/img/type-view-accesses.png | Bin 0 -> 17547 bytes 4 files changed, 26 insertions(+) create mode 100644 docs/img/auto-create-members.png create mode 100644 docs/img/auto-create-one-member.png create mode 100644 docs/img/type-view-accesses.png (limited to 'docs') diff --git a/docs/guide/type.md b/docs/guide/type.md index d704cbd2..2429dc52 100644 --- a/docs/guide/type.md +++ b/docs/guide/type.md @@ -147,6 +147,25 @@ We can either update our automatically created structure by pressing `y` to chan ![Taped HLIL](../img/taped-hlil.png "Taped HLIL") +### Automatically Creating Structure Member(s) + +Starting from `dev 2.3.2827` (and the subsequent stable 2.4), we offer a more automated way of creating structure members. You can select a structure or a particular structure offset, and create member(s) based on the accesses to the offset(s). The operation takes into consideration of both incoming and outgoing type information for the accessed offsets and selects the most confident one as the type for the offset. + +When no type information can be used to create the structure member, we fall back to creating an integer type based on the size of accesses, similar to what we do for the `s` hotkey (discussed above). In case there are different sizes of accesses, we do not create the member. You will need to examine the conflicting size information and decide how to create a member. + +The automatic structure member creation can be triggered in both types view and linear/graph view. In types view, you can right-click a structure definition line and select the "Create Members at Accessed Offsets" to create new members at all offsets that are accessed in the structure. + +![Auto Create Members](../img/auto-create-members.png "Auto Create Members") + +Alternatively, you can right-click on a padding byte or an access annotation, and select "Create Member At Current Offset", which creates a new structure member at the byte's offset. + +![Auto Create One Member](../img/auto-create-one-member.png "Auto Create One Member") + +Note, the second action can only be triggered on an offset that does not already have a member. If you wish to run it on an offset that already has a member, you must first undefine the member by pressing `u`. + +In graph/linear view, you can select either a token that has a structure name, or a variable that has a structure type, and then right-click and select the menu item. Besides, you can select a token with struct offset, e.g., `__offset(0x10).q` and right-click to automatically create one member. + + ### Types View To see all types in a Binary View, use the types view. It can be accessed from the menu `View > Types`. Alternatively, you can access it with the `t` hotkey from most other views, or using `[CMD/CTRL] p` to access the command-palette and typing "types". This is the most common interface for creating structures, unions and types using C-style syntax. @@ -189,6 +208,13 @@ __convention("customconvention") ``` +#### Structure Access Annotations + +Types view now annotates code references to structure offsets. It uses the same convention as in the graph/linear view. For example, the `__offset(0x8).q` token means the code references the offset 0x8 of this structure, and the size of the access is a qword. This will make it easier to see which offsets of a structure are being used, and aid in the process of creating structure members. + +![Type View Accesses](../img/type-view-accesses.png "Type View Accesses") + + #### Applying Structures and Types ![Changing a type](../img/change-type.png "Changing a type") diff --git a/docs/img/auto-create-members.png b/docs/img/auto-create-members.png new file mode 100644 index 00000000..b9a25fa1 Binary files /dev/null and b/docs/img/auto-create-members.png differ diff --git a/docs/img/auto-create-one-member.png b/docs/img/auto-create-one-member.png new file mode 100644 index 00000000..cc0a7250 Binary files /dev/null and b/docs/img/auto-create-one-member.png differ diff --git a/docs/img/type-view-accesses.png b/docs/img/type-view-accesses.png new file mode 100644 index 00000000..d34410a9 Binary files /dev/null and b/docs/img/type-view-accesses.png differ -- cgit v1.3.1