ducky.mm package

Submodules

• ducky.mm.binary module

Module contents

class ducky.mm.AnonymousMemoryPage(controller, index)

Bases: ducky.mm.MemoryPage

“Anonymous” memory page - this page is just a plain array of bytes, and is not backed by any storage. Its content lives only in the memory.

Page is created with all bytes set to zero.

clear()

read_u16(offset)

read_u32(offset)

read_u8(offset)

write_u16(offset, value)

write_u32(offset, value)

write_u8(offset, value)

class ducky.mm.ExternalMemoryPage(controller, index, data, offset=0)

Bases: ducky.mm.MemoryPage

Memory page backed by an external source. Source is an array of bytes, and can be provided by device driver, mmaped file, or by any other mean.

clear()

get(offset)

Get one byte from page. Override this method in case you need a different offset of requested byte.

Parameters:offset (int) – offset of the requested byte. Return type:int Returns:byte at position in page.

put(offset, b)

Put one byte into page. Override this method in case you need a different offset of requested byte.

Parameters:

• offset (int) – offset of modified byte.
• b (int) – new value.

read_u16(offset)

read_u32(offset)

read_u8(offset)

save_state(parent)

write_u16(offset, value)

write_u32(offset, value)

write_u8(offset, value)

class ducky.mm.MMOperationList

Bases: enum.IntEnum

ALLOC = 3

FREE = 4

MMAP = 6

UNMMAP = 7

UNUSED = 5

_member_map_ = OrderedDict([('ALLOC', <MMOperationList.ALLOC: 3>), ('FREE', <MMOperationList.FREE: 4>), ('UNUSED', <MMOperationList.UNUSED: 5>), ('MMAP', <MMOperationList.MMAP: 6>), ('UNMMAP', <MMOperationList.UNMMAP: 7>)])

_member_names_ = ['ALLOC', 'FREE', 'UNUSED', 'MMAP', 'UNMMAP']

_member_type_

alias of int

_value2member_map_ = {3: <MMOperationList.ALLOC: 3>, 4: <MMOperationList.FREE: 4>, 5: <MMOperationList.UNUSED: 5>, 6: <MMOperationList.MMAP: 6>, 7: <MMOperationList.UNMMAP: 7>}

exception ducky.mm.MalformedBinaryError

Bases: exceptions.Exception

class ducky.mm.MemoryController(machine, size=16777216)

Bases: object

Memory controller handles all operations regarding main memory.

Parameters:

• machine (ducky.machine.Machine) – virtual machine that owns this controller.
• size (int) – size of memory, in bytes.

Raises:

ducky.errors.InvalidResourceError – when memory size is not multiple of ducky.mm.PAGE_SIZE.

_MemoryController__alloc_page(index)

Allocate new anonymous page for usage. The first available index is used.

Be aware that this method does NOT check if page is already allocated. If it is, it is just overwritten by new anonymous page.

Parameters:index (int) – index of requested page. Returns:newly reserved page. Return type:ducky.mm.AnonymousMemoryPage

_MemoryController__remove_page(pg)

Removes page object for a specific memory page.

Parameters:pg (ducky.mm.MemoryPage) – page to be removed

_MemoryController__set_page(pg)

Install page object for a specific memory page.

Parameters:pg (ducky.mm.MemoryPage) – page to be installed Returns:installed page Return type:ducky.mm.MemoryPage

alloc_page(base=None)

Allocate new anonymous page for usage. The first available index is used.

Parameters:base (int) – if set, start searching pages from this address. Returns:newly reserved page. Return type:ducky.mm.AnonymousMemoryPage Raises:ducky.errors.InvalidResourceError – when there is no available page.

alloc_pages(base=None, count=1)

Allocate continuous sequence of anonymous pages.

Parameters:

• base (u24) – if set, start searching pages from this address.
• count (int) – number of requested pages.

Returns:

list of newly allocated pages.

Return type:

list of ducky.mm.AnonymousMemoryPage

Raises:

ducky.errors.InvalidResourceError – when there is no available sequence of pages.

alloc_specific_page(index)

Allocate new anonymous page with specific index for usage.

Parameters:index (int) – allocate page with this particular index. Returns:newly reserved page. Return type:ducky.mm.AnonymousMemoryPage Raises:ducky.errors.AccessViolationError – when page is already allocated.

boot()

Prepare memory controller for immediate usage by other components.

free_page(page)

Free memory page when it’s no longer needed.

Parameters:page (ducky.mm.MemoryPage) – page to be freed.

free_pages(page, count=1)

Free a continuous sequence of pages when they are no longer needed.

Parameters:

• page (ducky.mm.MemoryPage) – first page in series.
• count (int) – number of pages.

get_page(index)

Return memory page, specified by its index from the beginning of memory.

Parameters:index (int) – index of requested page. Return type:ducky.mm.MemoryPage Raises:ducky.errors.AccessViolationError – when requested page is not allocated.

get_pages(pages_start=0, pages_cnt=None, ignore_missing=False)

Return list of memory pages.

Parameters:

• pages_start (int) – index of the first page, 0 by default.
• pages_cnt (int) – number of pages to get, number of all memory pages by default.
• ignore_missing (bool) – if True, ignore missing pages, False by default.

Raises:

ducky.errors.AccessViolationError – when ignore_missing == False and there’s a missing page in requested range, this exception is rised.

Returns:

list of pages in area

Return type:

list of ducky.mm.MemoryPage

halt()

load_state(state)

pages_in_area(address=0, size=None, ignore_missing=False)

Return list of memory pages.

Parameters:

• address (u24) – beggining address of the area, by default 0.
• size (u24) – size of the area, by default the whole memory size.
• ignore_missing (bool) – if True, ignore missing pages, False by default.

Raises:

ducky.errors.AccessViolationError – when ignore_missing == False and there’s a missing page in requested range, this exception is rised.

Returns:

list of pages in area

Return type:

list of ducky.mm.MemoryPage

read_u16(addr)

read_u32(addr)

read_u8(addr)

register_page(pg)

Install page object for a specific memory page. This method is intended for external objects, e.g. device drivers to install their memory page objects to handle memory-mapped IO.

Parameters:pg (ducky.mm.MemoryPage) – page to be installed Returns:installed page Return type:ducky.mm.AnonymousMemoryPage Raises:ducky.errors.AccessViolationError – when there is already allocated page

save_state(parent)

unregister_page(pg)

Remove page object for a specific memory page. This method is intende for external objects, e.g. device drivers to remove their memory page objects handling memory-mapped IO.

Parameters:pg (ducky.mm.MemoryPage) – page to be removed Raises:ducky.errors.AccessViolationError – when there is no allocated page

write_u16(addr, value)

write_u32(addr, value)

write_u8(addr, value)

class ducky.mm.MemoryPage(controller, index)

Bases: object

Base class for all memory pages of any kinds.

Memory page has a set of boolean flags that determine access to and behavior of the page.

Flag	Meaning	Default
read	page is readable by executed instructions	False
write	page is writable by executed instructions	False
execute	content of the page can be used as executable instructions	False
dirty	there have been write access to this page, its content has changed	False

Parameters:

• controller (ducky.mm.MemoryController) – Controller that owns this page.
• index (int) – Serial number of this page.

clear()

Clear page.

This operation is implemented by child classes.

load_state(state)

Restore page from a snapshot.

read_u16(offset)

Read word.

This operation is implemented by child classes.

Parameters:offset (int) – offset of requested word. Return type:int

read_u32(offset)

Read longword.

This operation is implemented by child classes.

Parameters:offset (int) – offset of requested longword. Return type:int

read_u8(offset)

Read byte.

This operation is implemented by child classes.

Parameters:offset (int) – offset of requested byte. Return type:int

save_state(parent)

Create state of this page, and attach it to snapshot tree.

Parameters:parent (ducky.snapshot.SnapshotNode) – Parent snapshot node.

write_u16(offset, value)

Write word.

This operation is implemented by child classes.

Parameters:

• offset (int) – offset of requested word.
• value (int) – value to write into memory.

write_u32(offset, value)

Write longword.

This operation is implemented by child classes.

Parameters:

• offset (int) – offset of requested longword.
• value (int) – value to write into memory.

write_u8(offset, value)

Write byte.

This operation is implemented by child classes.

Parameters:

• offset (int) – offset of requested byte.
• value (int) – value to write into memory.

class ducky.mm.MemoryPageState(*args, **kwargs)

Bases: ducky.snapshot.SnapshotNode

class ducky.mm.MemoryRegion(mc, name, address, size, flags)

Bases: ducky.interfaces.ISnapshotable, object

load_state(state)

region_id = 0

save_state(parent)

class ducky.mm.MemoryRegionState

Bases: ducky.snapshot.SnapshotNode

class ducky.mm.MemoryState

Bases: ducky.snapshot.SnapshotNode

get_page_states()

ducky.mm.OFFSET_FMT(offset)

ducky.mm.PAGE_SIZE = 256

Size of memory page, in bytes.

class ducky.mm.PageTableEntry

Bases: ducky.util.Flags

DIRTY = 8

EXECUTE = 4

READ = 1

WRITE = 2

_flags = ['read', 'write', 'execute', 'dirty']

_labels = 'RWXD'

ducky.mm.SIZE_FMT(size)

class ducky.mm.VirtualMemoryPage(controller, index)

Bases: ducky.mm.MemoryPage

Memory page without any real storage backend.

save_state(parent)

ducky.mm.addr_to_offset(addr)

ducky.mm.addr_to_page(addr)

ducky.mm.area_to_pages(addr, size)