Andys Binary Folding Editor is primarily designed for structured browsing, although it also provides minimal editing facilities.
This program is designed to take in a set of binary files, and with the aid of an initialisation file, decode and display the definitions (structures or unions) within them. BE is particularly suited to displaying non-variable length definitions within the files.
This makes examination of known file types easy, and allows rapid and reliable navigation of memory dumps. BE is often used as the data navigation half of a debugger.
For a summary of how to use the editor, see the section Using the editor.
This documentation corresponds to the 9/7/04 version of BE. Features
BE has the following features :-
- Ability to decode definitions in (multiple) files.
- Ability to handle either endian multibyte values.
- Ability to handle signed or unsigned numeric values.
- Ability to display fields in definitions as ASCII, binary, EBCDIC, octal, decimal, hex, seconds since epoch, via symbol table lookup, or via a mapping table (enumerations and/or bit-flags).
- Fields can be numeric or buffers or nested definitions.
- Computed fields (whose values may be computed from a numeric expression, which may include references to other fields and/or memory locations).
- Selectable level of detail of display.
- Ability to suppress fields of structures considered irrelevant. This includes within nested sub-structures etc..
- Ability to expand sub-definitions or follow absolute or relative pointers to other definitions.
- Automatic linked-list following.
- Ability to write/append current view of data to a text file.
- Searching over data on display, optionally using Extended Regular Expressions.
- Include/exclude and sort lines features.
- Refresh data and auto-refresh data.
- Ability to edit data not actually in a file, but supplied by a (possibly user written) BE memory extension module. This feature can turn BE into the data-navigation half of a debugger!
- Tagging of lines on display, and rapid stepping between tags.
- Ability to view a text file.
- Ability to bring up online help.
- Ability to bring up initialisation file for user review.
- Shelling out to the operating system.
- Multiple sessions, with copying between sessions.
- Address sliding feature.
- Power address sliding feature, for systematically tracking down definitions at unknown locations in the file or memory space. Keeps decoding definition at successive addresses, until patterns match. This feature is truly awesome!
- Optional display of addresses, offsets, lengths and indices for fields in a definition. Indices of arrays displayable in ASCII, EBCDIC, binary, octal, decimal or hex. Addresses displayable as hex or symbol+offset. Ability to set initial display mode on the command line.
- ARM long-jump decoding of symbolic code addresses.
- Ability to use a symbol table file(s), so that addresses may be displayed symbol+offset, and so the user may refer to symbolic addresses in numeric expressions.
- Symbol files in a variety of formats are supported.
- User extendable initialisation file, defining definitions within the files or memory spaces.
- Initialisation file influencable via command line options.
- Macro support in the initialisation file.
- A non-interactive mode, where BE displays data to stdout and quits.
- Support for a plug-in disassembler.
- Support for AIX, Linux, HP-UX, SunOS, Cygwin, Windows (both NT and 9x), 32 bit OS/2, 32 bit DOS (via a DOS extender), NetWare and MIPS.
- Support for >32 bit datatypes and address space (upto 64 bit) on certain systems (subject to compiler support for long long, or __int64). These are currently all versions except 32 bit OS/2.
Command line arguments
usage: be [-i inifile] {-I incpath} {-D symbol} {-S name=val}
{ [-s s1-[s2]] [-d defn] [-a addr] [-f field] }
{-Y symfmt} {-y symfile[@bias]} [-C dx]
[-w width] [-h height] [-c colscheme] [-p] [-r] [-v viewflags]
[-g] [--] { binfile[@addr] | mx![args[@addr]] }
flags: -i inifile override default initialisation file
-I incpath append include path(s) for use by inifile
-D symbol pre-$define symbol(s) for use by inifile
-S name=val set constant name to be value
-s s1-s2 set sessions following -d, -a, -f and -p apply to
-d defn initial definition to use (default: main)
-a addr initial address to use (default: 0)
-f field field name within defn (list link, or array to expand)
-Y symfmt symbol table format
-y symfile@bias input symbol table file(s) (with optional biases)
-C dx code disassembler extension
-w width set screen width
-h height set screen height
-c colscheme set colour scheme (0 to 3, default: 0)
-p print data to stdout, non-interactive
-r restricted mode, no shelling out allowed
-v viewflags combinations of A,O,L,I,a,e,b,o,d,h,j,+,-
-g perform seg:off->physical mapping on all addresses
-A size address space size (8 to 64, default: 32)
binfile@addr binary file(s) (with optional address, default: 0)
mx!args@addr memory extension with arguments (and optional address)
The -i flag overrides the default initialisation file.
The -I flag affects the operation of the include command in the initialisation file.
The -D flag allows the definition of symbols which may be accessed via the $ifdef and similar directives in the initialisation file.
The -S flag allows the definition of a named constant for use in numeric expressions in the configuration file.
The editor has 10 editing sessions, and the -d, -a and -f options affect all of these (by default), unless the -s option is used to specify which session(s) are affected. By default only session 0 is shown by -p, but this too can be changed with the -s option.
The initial structure definition and address to decode on all/each session may be overridden with the -d and -a flags. Normally BE starts by looking up the definition of a 'main' definition, and decoding the data at address 0 as such. The address expression is allowed to refer to symbols in symbol tables, as it is evaluated after the symbol tables have been loaded. All the other numeric command line arguments are evaluated before any symbol table loading takes place, and so can't refer to symbols.
If the -f flag is used, it must identify a field within the specified structure. If the field is a pointer to a structure of the same type, BE will initially display a linked list of structures, rather than just one structure. Otherwise, the field is assumed to be an array of fields, and an element list is displayed instead.
Symbol table(s) may be specified using the -y flag. Symbol files are assumed to be the format generated by the ARM linker. However, the -Y flag can be used to tell BE that symbols in other formats follow. Multiple symbol files in differing formats may be specified, as in :-
be -Y aix_nm -y syms.nm -Y arm -y syms.sym ...
See the section on symbol table formats for a description of the supported file formats.
If a bias is specified, then it is added to each symbol value in the file. This is handy when a symbol table contains relative values, rather than absolute addresses.
The -C dx option may be used to extend BE by the use of a disassembler extension. This is a peice of code with a well defined interface, which BE uses to disassemble data annotated as code.
The -w and -h arguments can be used to try to override the current screen size. This doesn't work on UNIX or NetWare, but does on 32 bit DOS, 32 bit OS/2 and Windows. The -c argument allows you to choose from a small selection of colour schemes.
The -p flag causes BE to be invoked in a non-interactive manner. It decodes the address given, as a structure of the type specified, and writes the result to the screen (as stdout). Multiple structure dumps can be obtained by judicious use of the -s flag above.
The -r flag prevents a user of BE from shelling out a nested operating system command.
The -v flag allows you to state that addresses, offsets, lengths and array indices are to be displayed next to the data on display initially (note that -vI turns off indices). You can also turn on the symbolic display of addresses. In addition, you can specify the display mode of indices, one of binary, octal, decimal or hex. The + and - keys affect the initial level of detail of display, and only has effect when used with the -f flag. This is particularly useful when combined with the -p flag. Unfortunately, view flags are global, rather than per-session.
The -g argument is the 'segmented mode' switch. When enabled, BE translates all addresses prior to using them to fetch or store data. ie: address 0xSSSSOOOO is mapped to SSSS*16+OOOO. This is obviously intended for debugging dumps from embedded Intel processor dumps, and anyone with a sensible file format can ignore this flag.
Normally BE operates in a 32 bit address space. -A can be used to change this. For example, you could select a 24 bit address space. In this case BE would ignore bit 24 and above when addressing data, and would only show the bottom 24 bits when displaying addresses. Support for >32 bit address spaces is currently only available on certain operating systems versions of BE.
Multiple input binary files can be specified, and they should be loaded at non-overlapping address ranges.
BE supports the -- to end options and thus allow filenames given afterwards to have names starting with a -.
Each binary file provides data for a part of the memory space which BE can view or edit. Therefore each binary file may be described as a memory section.
Alternatively a memory section may be specified as mx!args. This instructs BE to load a memory extension, and to access the data indentified by the arguments via the memory extension. This feature allows BE to be extended to be able to edit non-file data directly, such as sectors on a disk.
Typical invokations of BE might be :-
be picture.bmp
to edit a file, which is loaded into the BE memory space at 0 onwards.
be -y gizmo.sym gizmo.rom gizmo.ram@0x8000 to edit dumps from the RAM and ROM of a coprocessor. where the ROM starts at 0, and the RAM at 0x8000. gizmo.sym is the symbols for the microcode the coprocessor was running.
be -Y map -y ucode.map -i ucode.ini -g -C i86 coproc!io=0x400,mem=0xc0000 to live edit a running coprocessor. ucode.map has the symbols for the microcode the coprocessor is running. ucode.ini is a custom initialisation file. BEcoproc.DLL provides BE with access to coprocessor memory. io=0x400,mem=0xc0000 tells BEcoproc.DLL how to find the coprocessor. BEi86.DLL allows BE to disassemble any code in the data.
be -d HEADER -a 512 -p -vA file.dat
display the header at 512 bytes into file.dat.
decoded data is to be written to stdout, BE is not interactive.
addresses are to be displayed next to the data.
be -s 1 -d STRUCT1 -a 0x1000 \
-s 2 -d STRUCT2 -a 0x2000 \
-s 3 -d STRUCT3 -a 0x3000 \
-s 1-3 -p \
filename.dat
to pick three structures at three addresses, and to have BE decode and display all three to stdout.