Chrysalide

Module pychrysalide.arch

Documentation

Python module for Chrysalide.arch

Sub modules

Classes

ArchInstruction
ArchOperand
ArchProcessor
ArchRegister
InstrIterator
ProcContext
mrange
vmpa

Class ArchInstruction

PyChrysalide instruction for a given architecture.

Hierarchy

builtins.object
 ╰── gi._gi.GObject
      ╰── pychrysalide.arch.ArchInstruction

Implements:

Known subclasses:

Methods

attach_operand(self, op)

Add a new operand to the instruction.

detach_operand(self, target)

Remove an operand from the instruction.

find_operand_path(self, target)

Compute the path leading to an instruction operand.

The target has to be an instance of ArchOperand included in the instruction.

The result is a string of the form 'n[:n:n:n]', where n is an internal index, or None if the target is not found. This kind of path is aimed to be built for the find_operand_path() function.

get_operand_from_path(self, path)

Retrieve an operand from an instruction by its path.

This path is a string of the form 'n[:n:n:n]', where n is an internal index. Such a path is usually built by the find_operand_path() function.

The result is an ArchOperand instance, or None if no operand was found.

replace_operand(self, old, new)

Replace an old instruction operand by a another one.

Attributes

destinations

Provide the instructions list following the current instruction.

Each item of the resulting tuple is a pair of ArchInstruction instance and InstructionLinkType value.

keyword

le name of the assembly instruction.

operands

ide the list of instruction attached operands.

range

access to the memory range covered by the current instruction.

sources

Provide the instructions list driving to the current instruction.

Each item of the resulting tuple is a pair of ArchInstruction instance and InstructionLinkType value.

uid

ide the unique identification number given to this kind of instruction.

Constants

ArchInstrFlag

Flags for some instruction properties.

1	= 0x1
2	= 0x2
4	= 0x4
8	= 0x8
16	= 0x10
128	= 0x80

InstrProcessHook

Kind of hook for instruction processing after disassembling.

0	= 0
1	= 1
2	= 2
3	= 3

InstructionLinkType

Kind of link between two instructions.

0	= 0
1	= 1
2	= 2
3	= 3
4	= 4
5	= 5
6	= 6
7	= 7
8	= 8
9	= 9

Class ArchOperand

The ArchOperand object aims to get subclassed to create operands of any kind for new architectures.

Calls to the __init__ constructor of this abstract object expect no particular argument.

The following methods have to be defined for new classes:

Some extra method definitions are optional for new classes:

Chrysalide creates an internal glue to provide rich comparisons for operands based on the old-style __cmp__ function.

The object can be compared using rich methods (like <= or !=).

Hierarchy

builtins.object
 ╰── gi._gi.GObject
      ╰── pychrysalide.arch.ArchOperand

Implements:

Known subclasses:

Methods

__cmp__(self, other)

Abstract method used to compare the operand with another one. This second object is always an ArchOperand instance.

This is the Python old-style comparison method, but Chrysalide provides a glue to automatically build a rich version of this function.

_find_inner_operand_path(self, target)

Abstract method used to compute the path leading to an inner operand.

The target has to be an instance of ArchOperand included in the operand.

The result is a string of the form 'n[:n:n:n]', where n is an internal index, or None if the target is not found. This kind of path is aimed to be built for the find_operand_path() function.

_get_inner_operand_from_path(self, path)

Abstract method used to retrieve an inner operand by its path.

This path is a string of the form 'n[:n:n:n]', where n is an internal index. Such a path is usually built by the find_operand_path() function.

The result is an ArchOperand instance, or None if no operand was found.

_print(self, line)

Abstract method used to print the operand into a rendering line, which is a provided BufferLine instance.

find_inner_operand_path(self, target)

Compute the path leading to an inner operand.

The target has to be an instance of ArchOperand included in the operand.

The result is a string of the form 'n[:n:n:n]', where n is an internal index, or None if the target is not found. This kind of path is aimed to be built for the find_operand_path() function.

get_inner_operand_from_path(self, path)

Retrieve an inner operand by its path.

This path is a string of the form 'n[:n:n:n]', where n is an internal index. Such a path is usually built by the find_operand_path() function.

The result is an ArchOperand instance, or None if no operand was found.

Class ArchProcessor

The ArchProcessor object aims to get subclassed to create processors for new architectures.

Several items have to be defined as class attributes in the final class:

_key: a string providing a small name used to identify the architecture;
_desc: a string for a human readable description of the new architecture;
_memory_size: size of the memory space, as a MemoryDataSize value;
_ins_min_size: size of the smallest instruction, as a MemoryDataSize value;
_virtual_space: a boolean value indicating if the architecture supports a virtual space.

Calls to the __init__ constructor of this abstract object expect the following arguments as keyword parameters:

endianness: endianness to apply to the binary content to disassemble, as a SourceEndian value.

Hierarchy

builtins.object
 ╰── gi._gi.GObject
      ╰── pychrysalide.arch.ArchProcessor

Implements: pychrysalide.analysis.storage.SerializableObject

Known subclasses:

Methods

add_error(self, type, addr, desc)

Extend the list of detected disassembling errors.

The type of error has to be one of the ArchProcessingError flags. The location of the error is a vmpa instance and a one-line description should give some details about what has failed.

disassemble(self, context, content, pos, format)

Disassemble a portion of binary content into one instruction.

find_instr_by_addr(self, addr)

Look for an instruction located at a given address.

get_context(self)

Provide a new disassembly context.

Attributes

desc

Provide a human readable description of the new architecture, as a simple string.

endianness

Provide the processor endianness, as a SourceEndian value.

errors

List of all detected errors which occurred during the disassembling process.

The result is a tuple of (ArchProcessingError, vmpa, string) values, providing a location and a description for each error.

ins_min_size

Provide the minimal size of one processor instruction, as a MemoryDataSize value.

instrs

access to the disassembled instructions run by the current processor.

key

Provide the small name used to identify the architecture, as a code string.

memory_size

Provide the size of the architecture memory address space, as a MemoryDataSize value.

virtual_space

Tell if the processor provides a virtual address space. This status is a boolean value.

Constants

ArchProcessingError

Flags for error occurring while disassembling instructions.

= 1

Class ArchRegister

The ArchRegister object aims to get subclassed to create registers suitable for new architectures.

Calls to the __init__ constructor of this abstract object expect no particular argument.

The following methods have to be defined for new classes:

Chrysalide creates an internal glue to provide rich comparisons for registers based on the old-style __cmp__ function.

The object can be compared using rich methods (like <= or !=).

Hierarchy

builtins.object
 ╰── gi._gi.GObject
      ╰── pychrysalide.arch.ArchRegister

Implements: pychrysalide.analysis.storage.SerializableObject

Methods

__cmp__(self, other)

Abstract method used to compare the register with another one. This second object is always an ArchRegister instance.

This is the Python old-style comparison method, but Chrysalide provides a glue to automatically build a rich version of this function.

__hash__(self)

Abstract method used to produce a hash of the object. The result must be an integer value.

_is_base_pointer(self)

Abstract method used to tell if the register is handling a base pointer. The result must be a boolean value.

_is_stack_pointer(self)

Abstract method used to tell if the register is handling a stack pointer. The result must be a boolean value.

_print(self, line)

Abstract method used to print the register into a rendering line, which is a provided BufferLine instance.

Attributes

is_base_pointer

Tell if the register is a base pointer or not.

is_stack_pointer

Tell if the register is a stack pointer or not.

Class InstrIterator

Iterator for Chrysalide instructions loaded in a given processor.

Hierarchy

builtins.object
 ╰── pychrysalide.arch.InstrIterator

Methods

__iter__(self)

Implement iter(self).

__next__(self)

Implement next(self).

restrict(self, range)

Limit the instruction iterator to a memory range.

Class ProcContext

The ProcContext object is a disassembling companion for architecture processors and is usually provided by the get_context() method.

So each kind of processor should have its dedicated context.

The role of a ProcContext instance is to collect on demand next points to process during a disassembling operation.

The following method may be defined for new classes:

_push_drop_point();

Calls to the __init__ constructor of this abstract object expect no particular argument.

Hierarchy

builtins.object
 ╰── gi._gi.GObject
      ╰── pychrysalide.format.PreloadInfo
           ╰── pychrysalide.arch.ProcContext

Methods

_push_drop_point(self, level, addr, extra=None)

Abstract method used to inject a new virtual address to disassemble during the disassembling process.

The priority of this point is given by the DisassPriorityLevel value. Extra information may also be provided, as a Python object.

If this method is not defined, the default behavior is to inject the point without any further treatment, as if extra does not carry any valuable information.

add_db_item(self, item)

Collect an extra item to include in the final disassembled content.

The item to consider has to be a DbItem instance.

push_drop_point(self, level, addr, extra=None)

Inject a new virtual address to disassemble during the disassembling process.

The priority of this point is given by the DisassPriorityLevel value. Extra information may also be provided, as a Python object.

push_new_symbol_at(self, addr)

Collect the location of a symbol for the disassembling process.

This location must be able to get converted into a vmpa instance.

Constants

DisassPriorityLevel

Level of priority for a given point during the disassembling process.

1	= 1
2	= 2
4	= 4

Class mrange

Python object for mrange_t.

The object can be compared using rich methods (like <= or !=) and produce an "informal" string representation of itself with a call to str().

Hierarchy

builtins.object
 ╰── pychrysalide.arch.mrange

Methods

contains(self, other)

Tell if the current range contains another given range or address.

Attributes

addr

access to the start location of the memory range.

end

ide the final external point of the memory range.

length

access to the length of the memory range.

Class vmpa

VMPA stands for Virtual Memory or Physical Address.

Thus vmpa objects are locations inside a binary content. Their coordinates are composed of a physical offset and a virtual address. Both of them can be undefined thanks to special values VmpaSpecialValue.

Instances can be created using the following constructor:

vmpa(phys=NO_PHYSICAL, virt=NO_VIRTUAL)

Where phys and virt are the values of the physical and virtual positions for the location.

The object can be compared using rich methods (like <= or !=), has some methods suitable for number operations (such as & or |) and produce an "informal" string representation of itself with a call to str().

Hierarchy

builtins.object
 ╰── pychrysalide.arch.vmpa

Attributes

phys

access to the physical offset of the location.

virt

access to the virtual address of the location.

Constants

VmpaSpecialValue

Special values for memory locations.

18446744073709551615	= 0xffffffffffffffff
18446744073709551614	= 0xfffffffffffffffe