ducky.boot module

This file provides necessary code to allow boot up of a virtual machine with the correct program running. This code may provide slightly different environment when compared to real hardware process, since e.g. external files can be mmap-ed into VM’s memory for writing.

ducky.boot.DEFAULT_BOOTLOADER_ADDRESS = 131072

By default, CPU starts executing instructions at this address after boot.

ducky.boot.DEFAULT_HDT_ADDRESS = 256

By default, Hardware Description Table starts at this address after boot.

class ducky.boot.MMapArea(ptr, address, size, file_path, offset, pages_start, pages_cnt, flags)[source]

Bases: object

Objects of this class represent one mmaped memory area each, to track this information for later use.

Parameters:
  • ptr – mmap object, as returned by mmap.mmap() function.
  • address (u32_t) – address of the first byte of an area in the memory.
  • size (u32_t) – length of the area, in bytes.
  • file_path – path to a source file.
  • offset (u32_t) – offset of the first byte in the source file.
  • pages_start (int) – first page of the area.
  • pages_cnt (int) – number of pages in the area.
  • flags (mm.binary.SectionFlags) – flags applied to this area.
load_state(state)[source]
save_state(parent)[source]
class ducky.boot.MMapAreaState[source]

Bases: ducky.snapshot.SnapshotNode

class ducky.boot.MMapMemoryPage(area, *args, **kwargs)[source]

Bases: ducky.mm.ExternalMemoryPage

Memory page backed by an external file that is accessible via mmap() call. It’s a part of one of ducky.boot.MMapArea instances, and if such area was opened as shared, every change in the content of its pages will reflect onto the content of an external file, and vice versa, every change of external file will be reflected in content of this page (if this page lies in affected area).

Parameters:area (MMapArea) – area this page belongs to.
_get_py2(offset)[source]

Read one byte from page.

Parameters:offset (int) – offset of the requested byte.
Return type:int
_get_py3(offset)[source]

Read one byte from page.

Parameters:offset (int) – offset of the requested byte.
Return type:int
_put_py2(offset, b)[source]

Write one byte to page.

Parameters:
  • offset (int) – offset of the modified byte.
  • b (int) – new value of the modified byte.
_put_py3(offset, b)[source]

Write one byte to page.

Parameters:
  • offset (int) – offset of the modified byte.
  • b (int) – new value of the modified byte.
get(offset)[source]

Read one byte from page.

This is an abstract method, __init__ is expected to replace it with a method, tailored for the Python version used.

Parameters:offset (int) – offset of the requested byte.
Return type:int
put(offset, b)[source]

Write one byte to page.

This is an abstract method, __init__ is expected to replace it with a method, tailored for the Python version used.

Parameters:
  • offset (int) – offset of the modified byte.
  • b (int) – new value of the modified byte.
class ducky.boot.ROMLoader(machine)[source]

Bases: ducky.interfaces.IMachineWorker

This class provides methods for loading all necessary pieces into VM’s memory. These methods are called in VM’s boot phase.

_get_mmap_fileno(file_path)[source]
_put_mmap_fileno(file_path)[source]
boot()[source]
halt()[source]
mmap_area(file_path, address, size, offset=0, flags=None, shared=False)[source]

Assign set of memory pages to mirror external file, mapped into memory.

Parameters:
  • file_path (string) – path of external file, whose content new area should reflect.
  • address (u24) – address where new area should start.
  • size (u24) – length of area, in bytes.
  • offset (int) – starting point of the area in mmaped file.
  • flags (ducky.mm.binary.SectionFlags) – specifies required flags for mmaped pages.
  • shared (bool) – if True, content of external file is mmaped as shared, i.e. all changes are visible to all processes, not only to the current ducky virtual machine.
Returns:

newly created mmap area.
Return type:

ducky.mm.MMapArea
Raises:

ducky.errors.InvalidResourceError – when size is not multiply of ducky.mm.PAGE_SIZE, or when address is not multiply of ducky.mm.PAGE_SIZE, or when any of pages in the affected area is already allocated.
poke(address, value, length)[source]
setup_bootloader(filepath, base=None)[source]

Load bootloader into main memory.

In the world of a real hardware, bootloader binary would be transformed into an image, and then “burned” in some form into the memory - main, or some kind of ROM from which it’d be loaded into main memory at the very beginning of boot process.

Parameters:
setup_debugging()[source]
setup_hdt()[source]

Initialize memory area containing Hardware Description Table.

If VM config file specifies HDT image file, it is loaded, otherwise HDT is constructed for the actual configuration, and then it’s copied into memory.

Parameters:
  • machine.hdt-address (u32_t) – Base address of HDT in memory. If not set, ducky.boot.DEFAULT_HDT_ADDRESS is used.
  • machine.hdt-image (str) – HDT image to load. If not set, HDT is constructed for the actual VM’s configuration.
setup_mmaps()[source]
unmmap_area(mmap_area)[source]