Welcome to Ducky’s documentation!¶

Ducky is a simple virtual CPU/machine simulator, with modular design and interesting features.

About¶

ducky¶

Ducky is a simple virtual CPU/machine simulator, with modular design and interesting features.

https://readthedocs.org/projects/ducky/badge/?version=latest

Ducky was created for learning purposes, no bigger ambitions. The goal was to experiment with CPU and virtual machine simulation, different instruction sets, and later working FORTH kernel become one of the main goals.

Features¶

Ducky - as in “Ducky, the CPU” - is a 32-bit RISC CPU. Ducky, “the VM”, is a simulator of Ducky CPU, adding few other modules to create the whole virtual machine, with CPUs, peripherals, storages and other components.

RISC instruction set¶

Instruction set was inspired by RISC CPUs, and sticks to LOAD/STORE aproach, with fixed-width instructions.

Memory model¶

Flat, paged, with linear addressing. Main memory consists of memory pages, each page supports simple access control - simple MMU is implemented.

Modular architecture¶

Virtual machine consists of several modules of different classes, and only few of them are necessary (e.g. CPU). Various peripherals are available, and it’s extremely easy to develop your own and plug them in.

SMP support¶

Multiple CPUs with multiple cores per each CPU, with shared memory. Each core can be restricted to its own segment of memory.

Persistent storage¶

Modular persistent storages are available, and accessible by block IO operations, or by mmap-ing storages directly into memory.

Bytecode files¶

Compiled programs are stored in bytecode files that are inspired by ELF executable format. These files consist of common sections (.text, .data, ...), symbols, and their content. Assembler (ducky-as) translates assembler sources into object files, and these are then processed by a linker (ducky-ld) into the final executable. Both object and executable files use the same format and bytecode for instructions and data.

Snapshots¶

Virtual machine can be suspended, saved, and later restored. This is also useful for debugging purposes, every bit of memory and CPU registers can be investigated.

Debugging support¶

Basic support is included - break points, watch points, stack traces, stepping, snapshots, ...

Tools¶

as for translating assembler sources to bytecode files
ld for linking bytecode files into the final executable
objdump for inspection of bytecode files
coredump for inspection of snapshots
vm for running virtual machine itself
img for converting binaries to images
and cc, an experimental C compiler

Planned features¶

FORTH kernel - basic functionality but at least ANS compliant
network support - it would be awesome to have a network stack available for running programs
functioning C compiler, with simple C library
and few others...

Need help?¶

The whole development is tracked on a GitHub page, including source codes and issue tracker.

Getting started¶

Installing¶

The easy way is to use package:

pip install ducky

Or, you can install Ducky by checking out the sources:

git clone https://github.com/happz/ducky.git
cd ducky
python setup.py

After this, you should have the ducky module on your path:

>>> import ducky
>>> ducky.__version__
'2.0'

Prerequisites¶

Ducky runs with both Python 2 and 3 - supported versions are 2.7, 3.3, 3.4 and 3.5. There are few other dependencies, installation process (or setup.py) should take care of them autmatically.

“Hello, world!” tutorial¶

Let’s try out the “Hello, world!” example. It’s a simple program that just prints out the well-known message.

Source code¶

Source is located in examples directory. If you check it out, it’s a plain and simple assembler:

.include "tty.asm"

.data

.type stack, space
.space 64

.type message, string
.string "Hello, world!"

.text

main:
  la sp, &stack
  add sp, 64

  la r0, &message
  call &writesn
  hlt 0x00

outb:
  ; > r0: port
  ; > r1: byte
  outb r0, r1
  ret

writesn:
  ; > r0: string address
  ; ...
  ;   r0: port
  ;   r1: current byte
  ;   r2: string ptr
  push r1
  push r2
  mov r2, r0
  li r0, $TTY_PORT_DATA
.__writesn_loop:
  lb r1, r2
  bz &.__writesn_write_nl
  call &outb
  inc r2
  j &.__writesn_loop
.__writesn_write_nl:
  ; \n
  li r1, 0x0000000A
  call &outb
  ; \r
  li r1, 0x0000000D
  call &outb
  li r0, 0x00000000
  pop r2
  pop r1
  ret

It’s a little bit more structured that necessary, just for educational purposes.

Binary¶

Virtual machine needs binary (or bytecode, as you wish...) code, and there’s a tool for it:

ducky-as -i examples/hello-world/hello-world.asm -o examples/hello-world/hello-world.o

This command will translate source code to object file, containing instructions for VM and other resources. You can inspect the object file using objdump tool:

ducky-objdump -i examples/hello-world/hello-world.o -a

This should produce output similar to this one:

[INFO] Input file: examples/hello-world.bin
[INFO]
[INFO] === File header ===
[INFO]   Magic:    0xDEAD
[INFO]   Version:  1
[INFO]   Sections: 4
[INFO]
[INFO] === Sections ===
[INFO]
[INFO]   Index  Name      Type     Flags        Base        Items    Size    Offset
[INFO] -------  --------  -------  -----------  --------  -------  ------  --------
[INFO]       0  .data     DATA     RW-- (0x03)  0x000000       14      14       104
[INFO]       1  .text     TEXT     RWX- (0x07)  0x000100       24      96       118
[INFO]       2  .symtab   SYMBOLS  ---- (0x00)  0x000200        6     120       214
[INFO]       3  .strings  STRINGS  ---- (0x00)  0x000000        0     122       334
[INFO]
[INFO] === Symbols ===
[INFO]
[INFO] Name                    Section    Address    Type            Size  File                      Line    Content
[INFO] ----------------------  ---------  ---------  ------------  ------  ------------------------  ------  ---------------
[INFO] message                 .data      0x000000   string (2)        14  examples/hello-world.asm  1       "Hello, world!"
[INFO] main                    .text      0x000100   function (3)       0  examples/hello-world.asm  4
[INFO] outb                    .text      0x000110   function (3)       0  examples/hello-world.asm  10
[INFO] writesn                 .text      0x000118   function (3)       0  examples/hello-world.asm  16
[INFO] .__fn_writesn_loop      .text      0x00012C   function (3)       0  examples/hello-world.asm  27
[INFO] .__fn_writesn_write_nl  .text      0x000140   function (3)       0  examples/hello-world.asm  33
[INFO]
[INFO] === Disassemble ==
[INFO]
[INFO]   Section .text
[INFO]   0x000100 (0x00000004) li r0, 0x0000
[INFO]   0x000104 (0x0000800D) call 0x0010
[INFO]   0x000108 (0x00000004) li r0, 0x0000
[INFO]   0x00010C (0x0000000B) int 0x0000
[INFO]   0x000110 (0x000000E3) outb r0, r1
[INFO]   0x000114 (0x0000000E) ret
[INFO]   0x000118 (0x000000D4) push r1
[INFO]   0x00011C (0x00000154) push r2
[INFO]   0x000120 (0x00000054) push r0
[INFO]   0x000124 (0x00000095) pop r2
[INFO]   0x000128 (0x00040004) li r0, 0x0100
[INFO]   0x00012C (0x00000842) lb r1, r2
[INFO]   0x000130 (0x00006029) bz 0x000C
[INFO]   0x000134 (0x0FFEC00D) call -0x0028
[INFO]   0x000138 (0x00000096) inc r2
[INFO]   0x00013C (0x0FFF6026) j -0x0014
[INFO]   0x000140 (0x00002844) li r1, 0x000A
[INFO]   0x000144 (0x0FFE400D) call -0x0038
[INFO]   0x000148 (0x00003444) li r1, 0x000D
[INFO]   0x00014C (0x0FFE000D) call -0x0040
[INFO]   0x000150 (0x00000004) li r0, 0x0000
[INFO]   0x000154 (0x00000095) pop r2
[INFO]   0x000158 (0x00000055) pop r1
[INFO]   0x00015C (0x0000000E) ret
[INFO]

You can see internal sections in the object file, list of symbols, and disassembled instructions, with labels replaced by dummy offsets. Offsets in jump instructions make no sense yet because object file is not the finalized binary - yet. For that, there’s another tool:

ducky-ld -i examples/hello-world/hello-world.o -o examples/hello-world/hello-world

This command will take object file (or many of them), and produce one binary by merging code, data and sections in object files, and updates addresses used by instructions to retrieve data and to perform jumps. You can inspect the binary file using objdump tool, too:

ducky-objdump -i examples/hello-world/hello-world -a

This should produce output very similar to the one you’ve already seen - not much had changed, there was only one object files, only offsets used by call and j instructions are now non-zero, meaning they are now pointing to the correct locations.

Running¶

Virtual machine configuration can get quite complicated, so I try to avoid too many command line options, and opt for using configuration files. For this example, there’s one already prepared. Go ahead and try it:

ducky-vm --machine-config=examples/hello-world/hello-world.conf -g

There are two other command line options that deserve some explanation:

-g - by default, VM prepares itself, and waits for user to press Enter to actually start running the loaded binaries. This option tells it to skip “press any key” phase and go ahead.

You should get output similar to this:

1441740855.82 [INFO] Ducky VM, version 1.0
1441740855.82 [INFO] mm: 16384.0KiB, 16383.5KiB available
1441740855.82 [INFO] hid: basic keyboard controller on [0x0100] as device-1
1441740855.83 [INFO] hid: basic tty on [0x0200] as device-2
1441740855.83 [INFO] hid: basic terminal (device-1, device-2)
1441740855.83 [INFO] snapshot: storage ready, backed by file ducky-snapshot.bin
1441740855.83 [INFO] RTC: time 21:34:15, date: 08/09/15
1441740855.83 [INFO] irq: loading routines from file interrupts
1441740856.02 [INFO] binary: loading from from file examples/hello-world/hello-world
1441740856.02 [INFO] #0:#0: CPU core is up
1441740856.02 [INFO] #0:#0:   check-frames: yes
1441740856.02 [INFO] #0:#0:   coprocessor: math
1441740856.02 [INFO] #0: CPU is up
Hello, world!
1441740856.04 [INFO] #0:#0: CPU core halted
1441740856.05 [INFO] #0: CPU halted
1441740856.05 [INFO] snapshot: saved in file ducky-snapshot.bin
1441740856.05 [INFO] Halted.
1441740856.05 [INFO]
1441740856.05 [INFO] Exit codes
1441740856.05 [INFO] Core      Exit code
1441740856.06 [INFO] ------  -----------
1441740856.06 [INFO] #0:#0             0
1441740856.06 [INFO]
1441740856.06 [INFO] Instruction caches
1441740856.06 [INFO] Core      Reads    Inserts    Hits    Misses    Prunes
1441740856.06 [INFO] ------  -------  ---------  ------  --------  --------
1441740856.06 [INFO] #0:#0       133         34      99        34         0
1441740856.06 [INFO]
1441740856.06 [INFO] Core    Ticks
1441740856.06 [INFO] ------  -------
1441740856.06 [INFO] #0:#0   133
1441740856.06 [INFO]
1441740856.06 [INFO] Executed instructions: 133 0.028670 (4639.0223/sec)
1441740856.06 [INFO]

And there, on line 15, between all that funny nonsenses, it is! :) The rest of the output are just various notes about loaded binaries, CPU caches, nothing important right now - as I said, terminal is dedicated to VM itself.

Virtual hardware¶

CPU¶

Ducky VM can have multiple CPUs, each with multiple cores. Each core is a 32-bit microprocessor, with 32 32-bit registers, connected to main memory. It is equiped with MMU, and its own instruction cache.

CPU core can work in privileged and unprivileged modes, allowing use of several protected instructions in privileged mode.

Registers¶

32 32-bit registers - registers r0 to r28 are general purpose registers - r30 is reserved, and used as a stack pointer register, SP - contains address of the last push’ed value on stack - r29 is reserved, and used as a frame pointer register, FP - contains content of SP in time of the last call or int instruction - r31 is reserved, and used as a instruction pointer register, IP - contains address of next instruction to be executed

flags register

IP and flags registers are protected, and cannot be modified by standard means (push flags; <modify flags>; pop flags) when CPU is in user mode

Flags register¶

Mask	Flags	Usage
0x00	`privileged`	If set, CPU runs in privileged mode, and usage of protected instructions is allowed
0x01	`hwint_allowed`	If set, HW interrupts can be delivered to this core
0x04	`e`	Set if the last two compared registers were equal
0x08	`z`	Set if the last arithmetic operation produced zero
0x10	`o`	Set if the last arithmetic operation overflown
0x20	`s`	Set if the last arithmetic operation produced negative result

Instruction set¶

CPU supports multiple instruction set. The default one, ducky, is the main workhorse, suited for general coding, but other instruction sets can exist, e.g. coprocessor may use its own instruction set for its operations.

Design principles¶

load and store operations are performed by dedicated instructions

all memory-register transfers work with 32-bit operands, 16-bit and 8-bit operands are handled by special instructions when necessary

all memory-register transfers work with addresses that are aligned to the size of their operands (1 byte alignment - so no alignment at all - for 8-bit operands)

in most cases, destination operand is the first one. Exceptions are instructions that work with IO ports.

when content of a register is changed by an instruction, several flags can be modified subsequently. E.g. when new value of register is zero, z flag is set.

Notes on documentation¶

rN refers to generaly any register, from r0 up to r28 - special registers are refered to by their common names (e.g. SP).

rA, rB refer to the first and the second instruction operand respectively and stand for any register.

<value> means immediate, absolute value. This covers both integers, specified as base 10 or base 16 integers, both positive and negative, and labels and addresses, specified as &label

when instruction accepts more than one operand type, it is documented using | character, e.g. (rA|<value>) means either register or immediate value

Ducky instruction set¶

Design principles¶

basic data unit is a word, 4 bytes, 32 bits. Other units are short and byte. Instructions often have variants for different data units, distinguished by a suffix (w for words, s for shorts, and b for single bytes)

load and store operations are performed by dedicated instructions

memory-register transfers work with addresses that are aligned to the size of their operands (1 byte alignment - so no alignment at all - for byte operands)

in most cases, destination operand is the first one. Exceptions are instructions that work with IO ports.

when content of a register is changed by instruction, several flags can be modified subsequently. E.g. when new value of register is zero, z flag is set.

Notes on documentation¶

rN refers to generaly any register, from r0 up to r28 - special registers are refered to by their common names (e.g. SP).

rA, rB refer to the first and the second instruction operand respectively and stand for any register.

<value> means immediate, absolute value. This covers both integers (specified as base 10 or base 16 integers, both positive and negative), and labels and addresses, specified as &label

when instruction accepts more than one operand type, it is documented using | character, e.g. (rA|<value>) means either register or immediate value

Stack frames¶

Several instructions transfer control to other routines, with possibility of returning back to previous spot. It is done by creating a stack frame. When stack frame is created, CPU performs these steps:

IP is pushed onto the stack

FP is pushed onto the stack

FP is loaded with value of SP

Destroying stack frame - reverting the steps above - effectively transfers control back to the point where the subroutine was called from.

Arithmetic¶

All arithmetic instructions take at least one operand, a register. In case of binary operations, the second operand can be a register, or an immediate value (15 bits wide, sign-extended to 32 bits). The result is always stored in the first operand.

add rA, (rB|<value>)

dec rA

inc rA

mul rA, (rB|<value>)

sub rA, (rB|<value>)

Bitwise operations¶

All bitwise operations - with exception of not - take two operands, a register, and either another register or an immediate value (15 bits wide, sign-extended to 32 bits). The result if always stored in the first operand.

and rA, (rB|<value>)

not rA

or rA, (rB|<value>)

shiftl rA, (rB|<value>)

shiftr rA, (rB|<value>)

xor rA, (rB|<values>)

Branching instructions¶

Branching instructions come in form <inst> (rA|<address>). If certain conditions are met, branching instruction will perform jump by adding value of the operand to the current value of PC (which, when instruction is being executed, points to the next instruction already). If the operand is an immediate address, it is encoded in the instruction as an immediate value (16 bit wide, sign-extended to 32 bits). This limits range of addresses that can be reached using this form of branching instructions.

Branching instructions do not create new stack frame.

Unconditional branching¶

j (rA|<value>)

Conditional branching¶

Instruction	Jump when ...
`be` `bne` `bs` `bns` `bz` `bnz` `bo` `bno` `bg` `bge` `bl` `ble`	`e = 1` `e = 0` `s = 1` `s = 0` `z = 1` `z = 0` `o = 1` `o = 0` `e = 0` and `s = 0` `e = 1` or `s = 0` `e = 0` and `s = 1` `e = 1` or `s = 1`

Conditional setting¶

All conditional setting instructions come in form <inst> rA. Depending on relevant flags, rA is set to 1 if condition is evaluated to be true, or to 0 otherwise.

For flags relevant for each instruction, see branching instruction with the same suffix (e.g. setle evaluates the same flags with the same result as ble).

Instruction

sete setne setz setnz seto setno sets setns setg setge setl setle

Comparing¶

Two instructions are available for comparing of values. Compare their operands and sets corresponding flags. The second operand can be either a register or an immediate value (15 bits wide).

cmp rA, (rB|<value>) - immediate value is sign-extended to 32 bits.

cmpu rA, (rB|<value>) - treat operands as unsigned values, immediate value is zero-extended to 32 bits.

Port IO¶

All IO instructions take two operands: port number, specified by register or immediate value, and register.

inw (rA|<port>), rB - read word from port and store it in rB

ins (rA|<port>), rB - read short from port and store it in rB

inb (rA|<port>), rB - read byte from port and store it in rB

outw (rA|<port>), rB - write value from rB to port

outs (rA|<port>), rB - write lower short of rB to port

outb (rA|<port>), rB - write lowest byte of rB to port

Interrupts¶

Delivery¶

If flag hwint_allowed is unset, no hardware IRQ can be accepted by CPU and stays queued. All queued IRQs will be delivered as soon as flag is set.

cli - clear hwint flag

sti - set hwint flag

In need of waiting for external events it is possible to suspend CPU until the next IRQ is delivered.

idle - wait until next IRQ

Invocation¶

Any interrupt service routine can be invoked by means of special instruction. When invoked several events take place:

SP is saved in temporary space

IP and SP are set to values that are stored in IVT in the corresponding entry

important registers are pushed onto new stack (in this order): old SP, flags

new stack frame is created

privileged mode is enabled

When routine ends (via retint), these steps are undone, and content of saved registers is restored.

int (rA|<index>)

retint - return from interrupt routine

Inter-processor interrupts (IPI) can be delivered to other processors, via dedicated instruction, similar to int but specifying CPUID of target core in the first operand.

ipi rA, (rB|<index>)

Routines¶

When routine is called, new stack frame is created, and CPU continues with instructions pointed to by the first operand. For its meaning (and limitations) see Branching instructions.

call (rA|<address>)

ret

Stack¶

pop rA

push (rA|<value>)

Miscellaneous¶

nop - do absolutely nothing

hlt (rA|<value>) - Halt CPU and set its exit code to specified value.

rst - reset CPU state. All flags cleared, privileged = 1, hwint_allowed = 0, all registers set to 0

mov rA, rB - copy value of rB into rA

swp rA, rB - swap content of two registers

sis <value> - switch instruction set to a different one

Memory access¶

Address operand - {address} - can be specified in different ways:

rA - address is stored in register

rA[<offset>] - address is computed by addition of rA and offset. offset can be both positive and negative. fp and sp can be also used as rA. <offset> is an immediate value, 15 bits wide, sign-extended to 32 bits.

Read¶

lw rA, {address} - load word from memory

ls rA, {address} - load short from memory

lb rA, {address} - load byte from memory

Write¶

stw {address}, rA

stb {addres}, rA - store lower byte of rA

Constants¶

Instructions for filling registers with values known in compile time.

li rA, <constant> - load constant into register. constant is encoded into instruction as an immediate value (20 bits wide, sign-extended to 32 bits)

liu rA, <constant> - load constant into the upper half of register. constant is encoded into instruction as an immediate value (20 bits wide immediate, only lower 16 bits are used)

la rA, <constant> - load constant into the register. constant is an immediate value (20 bits wide, sign-extended to 32 bits), and is treated as an offset from the current value of PC - register is loaded with the result of PC + constant.

Compare-and-swap¶

cas rA, rB, rC - read word from address in register rA. Compare it with value in register rB - if both are equal, take content of rC and store it in memory on address rA, else store memory value in rB.

Math coprocessor instruction set¶

This page describes instruction set of math coprocessor.

Manipulating registers¶

Instructions for moving values between coprocessor stack and memory or CPU registers.

itol

utol

ltoi

ltoii

iitol

dupl

Arithmetic operations¶

incl

decl

addl

subl

mull

divl

modl

symdivl

symmodl

Memory¶

Memory model¶

the full addressable memory is 4 GB, but it is quite unrealistic expectation. I usually stick to 24-bits for addresses, which leads to 16MB of main memory

memory is organized into pages of 256 bytes - each page can be restricted for read, write and execute operations

Memory layout¶

Interrupt Vector table¶

Interrupt vector table (IVT), located in main memory, is by default located at address 0x00000000. IVT address can be set per CPU core. IVT is 256 bytes long, providing enough space for 64 entries. Typically, lower 32 entries are reserved for hardware interrupts, provided by devices, and upper 32 entries leads to software routines that provide additional functionality for binaries. Each entry has the same layout:

IP - 32 bits SP - 32 bits

When CPU is interrupted - by hardware (device generates interrupt) or software (program executes int instruction) interrupt - corresponding entry is located in IVT, using interrupt ID as an index.

Stack¶

standard LIFO data structure

grows from higher addresses to lower

there is no pre-allocated stack, every bit of code needs to prepare its own if it intends to use instructions that operate with stack

when push’ing value to stack, SP is decreased by 4 (size of general register), and then value is stored on this address

each IVT provides its own stack pointer

Software¶

Calling convention¶

I use very simple calling convention in my code:

all arguments are in registers

first argument in r0, second in r1, ... You get the picture.

if there’s too many arguments, refactor your code or use a stack...

return value is in r0

callee is reponsible for save/restore of registers it’s using, with exception of:

registers that were used for passing arguments - these are expected to have undefined value when callee returns

r0 if callee returns value back to caller

All virtual interrupt routines, assembler code, any pieces of software I’ve written for this virtual machine follows this calling convention - unless stated otherwise...

Software interrupts¶

Software interrupts provide access to library of common functions, and - in case of virtual interrupts - to internal, complex and otherwise inaccessible resources of virtual machine itself.

For the list for existing interrupts and their numbers, see ducky.irq.IRQList. However, by the nature of invoking a software interrupt, this list is not carved into a stone. You may easily provide your own IVT, with entries leading to your own routines, and use e.g. the 33th entry, HALT, to sing a song.

All values are defined in files in defs/ directory which you can - and should - include into your assembler sources.

`BLOCKIO`¶

`IVT` entry	`33`
		Read mode	Write mode
Parameters	`r0`	device id
	`r1`	bit #0: `0` for read, `1` for write bit #1: `0` for synchronous, `1` for asynchronous operation
	`r2`	block id	src memory address
	`r3`	dst memory address	block id
	`r4`	number of blocks
Returns	`r0`	`0` for success

Perform block IO operation - transfer block between memory and storage device. Use the lowest bit of r1 to specify direction:

0 - read mode, blocks are transfered from storage into memory

1 - write mode, blocks are tranfered from memory to storage

Current data segment is used for addressing memory locations.

If everything went fine, 0 is returned, any other value means error happened.

IO operation is a blocking action, interrupt will return back to the caller once the IO is finished. Non-blocking (DMA-like) mode is planned but not yet implemented.

This operation is implemented as a virtual interrupt, see ducky.blockio.BlockIOInterrupt for details.

`VMDEBUG`¶

`IVT` entry	`34`
		`QUIET` mode
Parameters	`r0`	`0`
Parameters	`r1`	`0` for quiet mode, anything else for full mode
Returns	`r0`	`0` for success

VM interrupt allows control of VM debugging output. Currently, only two levels of verbosity that are available are quiet and full mode. In quiet mode, VM produces no logging output at all.

This interrupt can control level amount of debugging output in case when developer is interested only in debugging only a specific part of his code. Run VM with debugging turned on (-d option), turn the debugging off at the beggining of the code, and turn it on again at the beggining of the interesting part to get detailed output.

Tools¶

Ducky comes with basic toolchain necessary for development of complex programs. One piece missing is the C cross-compiler with simple C library but this issue will be resolved one day.

Common options¶

All tools accept few common options:

`-q, --quiet`¶

Lower verbosity level by one. By default, it is set to info, more quiet levels are warnings, `error and critical.

`-v, --verbose`¶

Increase verbosity level by one. By default, it is set to info, more verbose levels is debug. debug level is not available for ducky-vm unless -d option is set.

`-d, --debug`¶

Set logging level to debug immediately. ducky-vm also requires this option to even provide any debugging output - it is not possible to emit debug output by setting -v enough times if -d is not specified on command-line.

When option takes an address as an argument, address can be specified either using decimal or hexadecimal base. Usually, the absolute address is necessary when option is not binary-aware, yet some options are tied closely to particular binary, such options can also accept name of a symbol. Option handling code will try to find corresponding address in binary’s symbol table. This is valid for both command-line options and configuration files.

as¶

Assembler. Translates assembler files (.asm) to object files (.o) - files containing bytecode, symbols information, etc.

Options¶

`-i FILE`¶

Take assembly FILE, and create an object file from its content. It can be specified multiple times, each input file will be processed.

`-o FILE`¶

Write resulting object data into FILE.

This options is optional. If no -o is specified, ducky-as will then create output file for each input one by replacing its suffix by .o. If it is specified, number of -o options must match the number of -i options.

`-f`¶

When output file exists already, ducky-as will refuse to overwrite it, unless -f is set.

`-D VAR`¶

Define name, passed to processed assembly sources. User can check for its existence in source by .ifdef/.ifndef directives.

`-I DIR`¶

Add DIR to list of directories that are searched for files, when .include directive asks assembler to process additional source file.

`-m, --mmapable-sections`¶

Create object file with sections that can be loaded using mmap() syscall. This option can save time during VMstartup, when binaries can be simply mmapped into VM’s memory space, but it also creates larger binary files because of the alignment of sections in file.

-w, --writable-sections

By default, .text and .rodata sections are read-only. This option lowers this restriction, allowing binary to e.g. modify its own code.

ld¶

Linker. Takes (one or multiple) object files (.o) and merges them into one, binary, which can be executed by VM.

Options¶

`-i FILE`¶

Take object FILE, and create binary file out of it. It can be specified multiple times, all input files will be processed into one binary file.

`-o FILE`¶

Output file.

`-f`¶

When output file exists already, ducky-ld will refuse to overwrite it, unless -f is set.

`--section-base=SECTION=ADDRESS`¶

Linker tries to merge all sections into a binary in a semi-random way - it can be influenced by order of sections in source and object files, and order of input files passed to linker. It is in fact implementation detail and can change in the future. If you need specific section to have its base set to known address, use this option. Be aware that linker may run out of space if you pass conflicting values, or force sections to create too small gaps between each other so other sections would not fit in.

coredump¶

Prints information stored in a saved VM snapshot.

objdump¶

Prints information about object and binary files.

profile¶

Prints information stored in profiling data, created by VM. Used for profiling running binaries.

vm¶

Stand-alone virtual machine - takes binary, configuration files, and other resources, and executes binaries.

VM Configuration file¶

Number of available options can easily get quite high, especially when different devices come into play, and setting all of them on command line is not very clear. To ease this part of VM processes, user can create a configuration file. Syntax is based on Python’s ConfigParser (or Windows .ini) configuration files. It consists of sections, setting options for different subsystems (VM, CPUs, ...). You can find few configuration files in examples/ directory.

When option takes an address as an argument, address can be specified either using decimal or hexadecimal base. Usually, the absolute address is necessary when option is not binary-aware, yet some options are tied closely to particular binary, such options can also accept name of a symbol. Option handling code will try to find corresponding address in binary’s symbol table. This is valid for both command-line options and configuration files.

[machine]¶

cpus¶

Number of separate CPUs.

int, default 1

cores¶

Number of cores per CPU.

int, default 1

[memory]¶

size¶

Memory size in bytes.

int, default 0x1000000

force-aligned-access¶

When set, unaligned memory access will lead to exception.

bool, default yes

[cpu]¶

math-coprocessor¶

When set, each CPU core will have its own math coprocessor.

bool, default no

control-coprocessor¶

When set, each CPU core will have its own control coprocessor.

bool, default yes

inst-cache¶

Number of slots in instruction cache.

int, default 256

check-frame¶

When set, CPU cores will check if stack frames were cleaned properly when ret or iret is executed.

bool, default yes

ivt-address¶

Address of interrupt vector table.

int, default 0x000000

[bootloader]¶

file¶

Path to bootloader file.

str, required

[device-N]¶

Each section starting with device- tells VM to create virtual device, and provide it to running binaries. Device sections have few options, common for all kinds of devices, and a set of options, specific for each different device or driver.

klass¶

Device class - arbitrary string, describing family of devices. E.g. I use input for devices processing user input (e.g. keyboard controllers).

str, required

driver¶

Python class that is the device driver.

str, required

master¶

If set, master is superior device, with some responsibilities over its subordinates.

str, optional

Options¶

`--machine-config=PATH`¶

Specify PATH to VM configuration file. For its content, see VM Configuration file.

`--set-option=SECTION:OPTION=VALUE`¶

`--add-option=SECTION:OPTION=VALUE`¶

These two options allow user to modify the content of configuration file, by adding of new options or by changing the existing ones.

Lets have (incomplete) config file vm.conf:

[machine]
cpu = 1
core = 1

[binary-0]

You can use it to run different binaries without having separate config file for each of them, just by telling ducky-vm to load configuration file, and then change one option:

$ ducky-vm --machine-config=vm.conf --add-option=binary-0:file=<path to binary of your choice>

Similarly, you can modify existing options. Lets have (incomplete) config file vm.conf:

[machine]
cpus = 1
cores = 1

[binary-0]
file = some/terminal/app

[device-1]
klass = input
driver = ducky.devices.keyboard.KeyboardController
master = device-3

[device-2]
klass = output
driver = ducky.devices.tty.TTY
master = device-3

[device-3]
klass = terminal
driver = ducky.devices.terminal.StandardIOTerminal
input = device-1
output = device-2

Your app will run using VM’s standard IO streams for input and out. But you may want to start it with a different kind of terminal, e.g. PTY one, and attach to it using screen:

$ ducky-vm --machine-config=vm.conf --set-option=device-3:driver=ducky.devices.terminal.StandalonePTYTerminal

`--enable-device=DEVICE`¶

`--disable-device=DEVICE`¶

Shortcuts for --set-option=DEVICE:enabled=yes and --set-option=DEVICE:enabled=no respectively.

`--poke=ADDRESS:VALUE:LENGTH`¶

poke option allows modification of VM’s memory after all binaries and resources are loaded, just before the VM starts execution of binaries. It can be used for setting runtime-specific values, e.g. argument for a binary.

Consider a simple binary, running a loop for specified number of iterations:

By default, 10 iterations are hard-coded into binary. If you want to termporarily change number of iterations, it’s not necessary to recompile binary. By default, this binary, being the only one running, would get segment 0x02, it’s .data section was mentioned first, therefore its base address will be 0x0000, leading to loops having absolute address 0x020000. Then:

$ ducky-vm --machine-config=vm.conf --poke=0x020000:100:2

will load binary, then modify its .data section by changing value at address 0x020000 to 100, which is new number of iterations. Meta variable LENGTH specifies number of bytes to overwrite by poke value, and poke will change exactly LENGTH bytes - if VALUE cannot fit into available bits, exceeding bits of VALUE are masked out, and VALUE that can fit is zero-extended to use all LENGTH bytes.

`--stdio-console`¶

Enable console terminal with stdin and stdout as its IO streams. User can then enter commands in via the keyboard, while VM and its binaries use e.g. stand-alone pty terminals.

`-g, --go-on`¶

By default, ducky-vm creates a VM and boots it, but before handing the constrol to it, ducky-vm will ask user to press any key. -g option tells ducky-vm to skip this part, and immediately start execution of binaries.

img¶

Converts binaries to binary images that can be loaded by boot loader.

Options¶

`-i FILE`¶

Take binary FILE, and create a binary image from its content.

`-o FILE`¶

Write resulting object data into FILE.

`-f`¶

When output file exists already, ducky-img will refuse to overwrite it, unless -f is set.

Examples¶

“Hello, world!”¶

“Hello, world!” using library¶

VGA¶

Clock¶

Code Documentation¶

ducky.boot module¶

This file provides necessary code to allow boot up of a virtual machine with the correct program running. This code can 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 mm.MMapArea instances, and if such area was opened as shared, every change in this page content will affect the content of 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(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

boot()[source]¶

halt()[source]¶

load_data(base, content)[source]¶

load_text(base, content)[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]¶

setup_debugging()[source]¶

setup_hdt()[source]¶

Initialize memory area that contains HDT.

If VM config file specifies HDT image file, it is loaded, otherwise HDT is constructed for the actual configuration. It is then 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 – HDT image to load. If not set, HDT is constructed for the actual VM’s configuration.

setup_mmaps()[source]¶

unmmap_area(mmap_area)[source]¶

ducky.config module¶

VM configuration management

class ducky.config.MachineConfig(*args, **kwargs)[source]¶

Bases: ConfigParser.ConfigParser

Contains configuration of the whole VM, and provides methods for parsing, inspection and extending this configuration.

add_breakpoint(core, address, active=None, flip=None, ephemeral=None, countdown=None)[source]¶

add_device(klass, driver, **kwargs)[source]¶

Add another device to the configuration.

Parameters:	klass (string) – class of the device (`klass` option). driver (string) – device driver - dot-separated path to class (`driver` option). kwargs – all keyword arguments will be added to the section as device options.

add_mmap(filepath, address, size, offset=None, access=None, shared=None)[source]¶

add_storage(driver, sid, filepath=None)[source]¶

Add another storage to the configuration.

Parameters:	driver (string) – storage’s driver - dot-separated path to class (`driver` option). sid (int) – storage’s SID (`sid` options). filepath (string) – path to backend file, if there’s any (`filepath` option).

create_getters(section)[source]¶

dumps()[source]¶

get(section, option, default=None, **kwargs)[source]¶

Get value for an option.

Parameters:	section (string) – config section. option (string) – option name, default – this value will be returned, if no such option exists.
Return type:	string
Returns:	value of config option.

getbool(section, option, default=None)[source]¶

getfloat(section, option, default=None)[source]¶

getint(section, option, default=None)[source]¶

iter_breakpoints()[source]¶

iter_devices()[source]¶

iter_mmaps()[source]¶

iter_storages()[source]¶

read(*args, **kwargs)[source]¶

set(section, option, value, *args, **kwargs)[source]¶

ducky.config.bool2option(b)[source]¶

Get config-file-usable string representation of boolean value.

Parameters:	b (bool) – value to convert.
Return type:	string
Returns:	`yes` if input is `True`, `no` otherwise.

ducky.console module¶

class ducky.console.ConsoleConnection(cid, master, stream_in, stream_out)[source]¶

Bases: object

boot()[source]¶

die(exc)[source]¶

execute(cmd)[source]¶

halt()[source]¶

log(logger, msg, *args)[source]¶

prompt()[source]¶

read_input()[source]¶

table(table, **kwargs)[source]¶

write(buff, *args)[source]¶

writeln(buff, *args)[source]¶

class ducky.console.ConsoleMaster(machine)[source]¶

Bases: object

boot()[source]¶

connect(slave)[source]¶

console_id = 0¶

halt()[source]¶

is_registered_command(name)[source]¶

register_command(name, callback, *args, **kwargs)[source]¶

register_commands(commands, *args, **kwargs)[source]¶

unregister_command(name)[source]¶

class ducky.console.TerminalConsoleConnection(cid, master)[source]¶

Bases: ducky.console.ConsoleConnection

halt()[source]¶

ducky.console.cmd_help(console, cmd)[source]¶: List all available command and their descriptions

ducky.cc package¶

Subpackages¶

ducky.cc.passes package¶

Submodules¶

ducky.cc.passes.ast_codegen module¶

class ducky.cc.passes.ast_codegen.CodegenVisitor(*args, **kwargs)[source]¶

Bases: ducky.cc.passes.ASTVisitor

block(stage=None, *args, **kwargs)[source]¶

emit_epilog()[source]¶

emit_prolog()[source]¶

emit_string_literals()[source]¶

emit_trampoline()[source]¶

generic_visit(node, **kwargs)[source]¶

get_new_label(name=None)[source]¶

get_new_literal_label()[source]¶

get_new_local_storage(size)[source]¶

make_current(block)[source]¶

materialize()[source]¶

pop_scope()[source]¶

priority = 1000¶

process_cond(node, iftrue_label=None, iffalse_label=None)[source]¶

push_scope()[source]¶

reset_scope()[source]¶

visit(node, **kwargs)[source]¶

visit_ArrayRef(node, preferred=None, keep=None)[source]¶

visit_Assignment(node, preferred=None, keep=None)[source]¶

visit_BinaryOp(node, preferred=None, keep=None)[source]¶

visit_Cast(node, **kwargs)[source]¶

visit_Compound(node, create_scope=True)[source]¶

visit_Constant(node, preferred=None, keep=None)[source]¶

visit_Decl(node)[source]¶

visit_ExprList(node)[source]¶

visit_FileAST(node)[source]¶

visit_For(node)[source]¶

visit_FuncCall(node, preferred=None, keep=None)[source]¶

visit_FuncDef(node)[source]¶

visit_ID(node, preferred=None, keep=None)[source]¶

visit_If(node)[source]¶

visit_Return(node)[source]¶

visit_StructRef(node, **kwargs)[source]¶

visit_TypeDecl(node, **kwargs)[source]¶

visit_Typedef(node)[source]¶

visit_Typename(node, **kwargs)[source]¶

visit_UnaryOp(node, preferred=None, keep=None)[source]¶

visit_While(node)[source]¶

visit_constant_value(node)[source]¶

visit_expr(node, preferred=None, keep=None)[source]¶

ducky.cc.passes.ast_constprop module¶

class ducky.cc.passes.ast_constprop.ConstantFoldingVisitor(logger, *args, **kwargs)[source]¶

Bases: ducky.cc.passes.ASTOptVisitor

priority = 100¶

visit_BinaryOp(node)[source]¶

ducky.cc.passes.ast_dce module¶

class ducky.cc.passes.ast_dce.DSEVisitor(logger, *args, **kwargs)[source]¶

Bases: ducky.cc.passes.ASTOptVisitor

priority = 500¶

visit_Compound(node)[source]¶

ducky.cc.passes.ast_visualise module¶

class ducky.cc.passes.ast_visualise.ASTVisualiseVisitor(*args, **kwargs)[source]¶

Bases: ducky.cc.passes.ASTVisitor

generic_visit(node, shape='box')[source]¶

get_index(node)[source]¶

visit_BinaryOp(node, shape='box')[source]¶

visit_Constant(node, shape='box')[source]¶

visit_FileAST(node)[source]¶

visit_ID(node, shape='box')[source]¶

visit_If(node)[source]¶

visit_UnaryOp(node, shape='box')[source]¶

visit_While(node)[source]¶

ducky.cc.passes.bt_peephole module¶

class ducky.cc.passes.bt_peephole.BTPeepholeVisitor(logger, *args, **kwargs)[source]¶

Bases: ducky.cc.passes.BlockVisitor

do_visit_block(block)[source]¶

priority = 100¶

ducky.cc.passes.bt_simplify module¶

class ducky.cc.passes.bt_simplify.BlockTreeSimplifyVisitor(logger, *args, **kwargs)[source]¶

Bases: ducky.cc.passes.BlockVisitor

do_visit_fn(fn)[source]¶

priority = 500¶

ducky.cc.passes.bt_visualise module¶

class ducky.cc.passes.bt_visualise.BlockTreeVisualiseVisitor(*args, **kwargs)[source]¶

Bases: ducky.cc.passes.BlockVisitor

do_visit_block(block)[source]¶

priority = 1000¶

visit(cv)[source]¶

Module contents¶

class ducky.cc.passes.ASTOptVisitor(logger, *args, **kwargs)[source]¶

Bases: ducky.cc.passes.ASTVisitor

replace_child(current_node, new_node)[source]¶

class ducky.cc.passes.ASTVisitor(logger, *args, **kwargs)[source]¶

Bases: pycparser.c_ast.NodeVisitor

DOWN()[source]¶

UP()[source]¶

generic_visit(node)[source]¶

priority = 99¶

visit(node, **kwargs)[source]¶

class ducky.cc.passes.BlockVisitor(logger, *args, **kwargs)[source]¶

Bases: object

DOWN()[source]¶

UP()[source]¶

do_visit(cv)[source]¶

do_visit_block(block)[source]¶

do_visit_fn(fn)[source]¶

priority = 99¶

visit(cv)[source]¶

visit_block(block)[source]¶

visit_fn(fn)[source]¶

ducky.cc.passes.load(logger)[source]¶

Submodules¶

ducky.cc.types module¶

class ducky.cc.types.ArrayType(item_type, size=None, *args, **kwargs)[source]¶: Bases: ducky.cc.types.CType

class ducky.cc.types.CType(visitor, decl=None)[source]¶

Bases: object

static create_from_decl(visitor, decl)[source]¶

static get_from_decl(visitor, decl)[source]¶

static get_from_desc(visitor, desc)[source]¶

types = {}¶

class ducky.cc.types.CharType(visitor, decl=None)[source]¶: Bases: ducky.cc.types.CType

class ducky.cc.types.FunctionType(*args, **kwargs)[source]¶: Bases: ducky.cc.types.CType

class ducky.cc.types.IntType(visitor, decl=None)[source]¶: Bases: ducky.cc.types.CType

class ducky.cc.types.PointerType(ptr_to_type, *args, **kwargs)[source]¶: Bases: ducky.cc.types.CType

class ducky.cc.types.StructType(name, *args, **kwargs)[source]¶

Bases: ducky.cc.types.CType

field_offset(name)[source]¶

field_type(name)[source]¶

class ducky.cc.types.UnsignedCharType(visitor, decl=None)[source]¶: Bases: ducky.cc.types.CharType

class ducky.cc.types.UnsignedIntType(visitor, decl=None)[source]¶: Bases: ducky.cc.types.IntType

class ducky.cc.types.VoidType(visitor, decl=None)[source]¶: Bases: ducky.cc.types.CType

Module contents¶

class ducky.cc.ADD(*operands)[source]¶: Bases: ducky.cc.Instruction

class ducky.cc.AND(*operands)[source]¶: Bases: ducky.cc.Instruction

class ducky.cc.BE(label)[source]¶: Bases: ducky.cc.Instruction

class ducky.cc.BG(label)[source]¶: Bases: ducky.cc.Instruction

class ducky.cc.BGE(label)[source]¶: Bases: ducky.cc.Instruction

class ducky.cc.BL(label)[source]¶: Bases: ducky.cc.Instruction

class ducky.cc.BLE(label)[source]¶: Bases: ducky.cc.Instruction

class ducky.cc.BNE(label)[source]¶: Bases: ducky.cc.Instruction

class ducky.cc.Block(name=None, comment=None)[source]¶

Bases: object

add_incoming(block)[source]¶

add_name(name)[source]¶

add_outgoing(block)[source]¶

connect(next)[source]¶

emit(inst)[source]¶

id = 0¶

instructions()[source]¶

materialize(code)[source]¶

class ducky.cc.CALL(label)[source]¶: Bases: ducky.cc.Instruction

class ducky.cc.CMP(left, right)[source]¶: Bases: ducky.cc.Instruction

class ducky.cc.Comment(comment)[source]¶

Bases: object

materialize()[source]¶

exception ducky.cc.CompilerError(location, msg)[source]¶: Bases: exceptions.Exception

class ducky.cc.ConstantValue(value)[source]¶: Bases: ducky.cc.NamedValue

class ducky.cc.Directive(directive)[source]¶

Bases: ducky.cc.Instruction

materialize()[source]¶

class ducky.cc.Expression(value=None, type=None, klass=<ExpressionClass.RVALUE: 2>)[source]¶

Bases: object

is_lvalue()[source]¶

is_mlvalue()[source]¶

is_rvalue()[source]¶

to_rvalue(visitor, preferred=None, keep=None)[source]¶

class ducky.cc.ExpressionClass[source]¶

Bases: enum.Enum

LVALUE = <ExpressionClass.LVALUE: 0>¶

MLVALUE = <ExpressionClass.MLVALUE: 1>¶

RVALUE = <ExpressionClass.RVALUE: 2>¶

class ducky.cc.Function(visitor, decl, ftype, args_types=None)[source]¶

Bases: object

args_block()[source]¶

block(*args, **kwargs)[source]¶

body_block()[source]¶

epilog_block()[source]¶

finish()[source]¶

header_block()[source]¶

materialize()[source]¶

prolog_block()[source]¶

class ducky.cc.HLT(isr)[source]¶: Bases: ducky.cc.Instruction

class ducky.cc.INC(reg)[source]¶: Bases: ducky.cc.Instruction

class ducky.cc.INT(isr)[source]¶: Bases: ducky.cc.Instruction

exception ducky.cc.IncompatibleTypesError(loc, t1, t2)[source]¶: Bases: ducky.cc.CompilerError

class ducky.cc.InlineAsm(code)[source]¶

Bases: ducky.cc.Instruction

materialize()[source]¶

class ducky.cc.Instruction(opcode, *operands)[source]¶

Bases: object

materialize()[source]¶

exception ducky.cc.IsAPointerError(loc, t)[source]¶: Bases: ducky.cc.CompilerError

class ducky.cc.J(label)[source]¶: Bases: ducky.cc.Instruction

class ducky.cc.LA(reg, value)[source]¶: Bases: ducky.cc.Instruction

class ducky.cc.LB(reg, addr)[source]¶: Bases: ducky.cc.Instruction

class ducky.cc.LI(reg, value)[source]¶: Bases: ducky.cc.Instruction

class ducky.cc.LS(reg, addr)[source]¶: Bases: ducky.cc.Instruction

class ducky.cc.LValueExpression(*args, **kwargs)[source]¶: Bases: ducky.cc.Expression

class ducky.cc.LW(reg, addr)[source]¶: Bases: ducky.cc.Instruction

class ducky.cc.MLValueExpression(*args, **kwargs)[source]¶: Bases: ducky.cc.Expression

class ducky.cc.MOV(*operands)[source]¶: Bases: ducky.cc.Instruction

class ducky.cc.MUL(*operands)[source]¶: Bases: ducky.cc.Instruction

class ducky.cc.MemorySlotStorage(symbol, label)[source]¶

Bases: ducky.cc.SymbolStorage

addrof(register, emit)[source]¶

name()[source]¶

class ducky.cc.MemorySlotValue(storage)[source]¶: Bases: ducky.cc.NamedValue

class ducky.cc.NOT(*operands)[source]¶: Bases: ducky.cc.Instruction

class ducky.cc.NamedValue(name)[source]¶

Bases: object

backing_register()[source]¶

can_register_backed()[source]¶

is_register_backed()[source]¶

exception ducky.cc.NotAPointerError(loc, t)[source]¶: Bases: ducky.cc.CompilerError

class ducky.cc.OR(*operands)[source]¶: Bases: ducky.cc.Instruction

class ducky.cc.POP(reg)[source]¶: Bases: ducky.cc.Instruction

class ducky.cc.PUSH(reg)[source]¶: Bases: ducky.cc.Instruction

class ducky.cc.RET[source]¶: Bases: ducky.cc.Instruction

class ducky.cc.RValueExpression(*args, **kwargs)[source]¶: Bases: ducky.cc.Expression

class ducky.cc.Register(rset, index)[source]¶

Bases: object

free()[source]¶

put()[source]¶

class ducky.cc.RegisterMemorySlotValue(register)[source]¶: Bases: ducky.cc.NamedValue

class ducky.cc.RegisterSet(fn)[source]¶

Bases: object

get(preferred=None, keep=None)[source]¶

restore_callee_saves(block)[source]¶

save_callee_saves(block)[source]¶

class ducky.cc.RegisterValue(register)[source]¶: Bases: ducky.cc.NamedValue

class ducky.cc.SHL(reg, ri)[source]¶: Bases: ducky.cc.Instruction

class ducky.cc.SHR(reg, ri)[source]¶: Bases: ducky.cc.Instruction

class ducky.cc.STB(addr, reg)[source]¶: Bases: ducky.cc.Instruction

class ducky.cc.STS(addr, reg)[source]¶: Bases: ducky.cc.Instruction

class ducky.cc.STW(addr, reg)[source]¶: Bases: ducky.cc.Instruction

class ducky.cc.SUB(*operands)[source]¶: Bases: ducky.cc.Instruction

class ducky.cc.Scope(visitor, parent=None)[source]¶

Bases: object

add(loc, symbol)[source]¶

get(name)[source]¶

scope_id = 0¶

class ducky.cc.StackSlotStorage(symbol, offset)[source]¶

Bases: ducky.cc.SymbolStorage

addrof(register, emit)[source]¶

name()[source]¶

class ducky.cc.StackSlotValue(storage)[source]¶: Bases: ducky.cc.NamedValue

class ducky.cc.StringConstantValue(value)[source]¶: Bases: ducky.cc.ConstantValue

class ducky.cc.Symbol(visitor, name, decl_type, extern=False, defined=False, const=False)[source]¶: Bases: object

exception ducky.cc.SymbolAlreadyDefinedError(loc, symbol)[source]¶: Bases: ducky.cc.CompilerError

exception ducky.cc.SymbolConflictError(location, msg)[source]¶: Bases: ducky.cc.CompilerError

class ducky.cc.SymbolStorage(symbol, register=None)[source]¶

Bases: object

acquire_register(register)[source]¶

addrof(reg, emit)[source]¶

has_register()[source]¶

name()[source]¶

release_register()[source]¶

spill_register(visitor)[source]¶

unspill_register(visitor, register)[source]¶

exception ducky.cc.SymbolUndefined(loc, symbol)[source]¶: Bases: ducky.cc.CompilerError

exception ducky.cc.UnableToImplicitCastError(loc, t1, t2)[source]¶: Bases: ducky.cc.CompilerError

exception ducky.cc.UndefinedStructMemberError(loc, s, m)[source]¶: Bases: ducky.cc.CompilerError

ducky.cc.dump_node(node)[source]¶

ducky.cc.show_node(node)[source]¶

ducky.cpu package¶

Subpackages¶

ducky.cpu.coprocessor package¶

Submodules¶

ducky.cpu.coprocessor.control module¶

class ducky.cpu.coprocessor.control.ControlCoprocessor(core)[source]¶

Bases: ducky.interfaces.ISnapshotable, ducky.cpu.coprocessor.Coprocessor

read(r)[source]¶

read_cr0()[source]¶

read_cr1()[source]¶

read_cr2()[source]¶

read_cr3()[source]¶

write(r, value)[source]¶

write_cr1(address)[source]¶

write_cr2(address)[source]¶

write_cr3(value)[source]¶

class ducky.cpu.coprocessor.control.ControlRegisters[source]¶

Bases: enum.IntEnum

CR0 = <ControlRegisters.CR0: 0>¶

CR1 = <ControlRegisters.CR1: 1>¶

CR2 = <ControlRegisters.CR2: 2>¶

CR3 = <ControlRegisters.CR3: 3>¶

class ducky.cpu.coprocessor.control.CoreFlags[source]¶: Bases: ducky.util.Flags

exception ducky.cpu.coprocessor.control.ReadOnlyRegisterError(r, *args, **kwargs)[source]¶: Bases: ducky.cpu.CPUException

exception ducky.cpu.coprocessor.control.WriteOnlyRegisterError(r, *args, **kwargs)[source]¶: Bases: ducky.cpu.CPUException

ducky.cpu.coprocessor.math_copro module¶

Stack-based coprocessor, providing several arithmetic operations with “long” numbers.

Coprocessor’s instructions operates on a stack of (by default) 8 slots. Operations to move values between math stack and registers/data stack are also available.

In the following documentation several different data types are used:

int - standard word, 32-bit wide integer

long - long integer, 64-bit wide

Unless said otherwise, instruction takes its arguments from the stack, removing the values in the process, and pushes the result - if any - back on the stack.

class ducky.cpu.coprocessor.math_copro.ADDL(instruction_set)[source]¶

Bases: ducky.cpu.coprocessor.math_copro.Descriptor_MATH

static execute(core, inst)[source]¶

mnemonic = 'addl'¶

opcode = <MathCoprocessorOpcodes.ADDL: 32>¶

class ducky.cpu.coprocessor.math_copro.DECL(instruction_set)[source]¶

Bases: ducky.cpu.coprocessor.math_copro.Descriptor_MATH

Decrement top of the stack by one.

static execute(core, inst)[source]¶

mnemonic = 'decl'¶

opcode = <MathCoprocessorOpcodes.DECL: 31>¶

class ducky.cpu.coprocessor.math_copro.DIVL(instruction_set)[source]¶

Bases: ducky.cpu.coprocessor.math_copro.Descriptor_MATH

Divide the value below the top of the math stack by the topmost value.

static execute(core, inst)[source]¶

mnemonic = 'divl'¶

opcode = <MathCoprocessorOpcodes.DIVL: 11>¶

class ducky.cpu.coprocessor.math_copro.DROP(instruction_set)[source]¶

Bases: ducky.cpu.coprocessor.math_copro.Descriptor_MATH

static execute(core, inst)[source]¶

mnemonic = 'drop'¶

opcode = <MathCoprocessorOpcodes.DROP: 23>¶

class ducky.cpu.coprocessor.math_copro.DUP(instruction_set)[source]¶

Bases: ducky.cpu.coprocessor.math_copro.Descriptor_MATH

static execute(core, inst)[source]¶

mnemonic = 'dup'¶

opcode = <MathCoprocessorOpcodes.DUP: 20>¶

class ducky.cpu.coprocessor.math_copro.DUP2(instruction_set)[source]¶

Bases: ducky.cpu.coprocessor.math_copro.Descriptor_MATH

static execute(core, inst)[source]¶

mnemonic = 'dup2'¶

opcode = <MathCoprocessorOpcodes.DUP2: 21>¶

class ducky.cpu.coprocessor.math_copro.Descriptor_MATH(instruction_set)[source]¶

Bases: ducky.cpu.instructions.Descriptor_R_R

static assemble_operands(logger, buffer, inst, operands)[source]¶

static disassemble_operands(logger, inst)[source]¶

operands = ''¶

exception ducky.cpu.coprocessor.math_copro.EmptyMathStackError(*args, **kwargs)[source]¶

Bases: ducky.cpu.CPUException

Raised when operation expects at least one value on math stack but stack is empty.

exception ducky.cpu.coprocessor.math_copro.FullMathStackError(*args, **kwargs)[source]¶

Bases: ducky.cpu.CPUException

Raised when operation tries to put value on math stack but there is no empty spot available.

class ducky.cpu.coprocessor.math_copro.INCL(instruction_set)[source]¶

Bases: ducky.cpu.coprocessor.math_copro.Descriptor_MATH

Increment top of the stack by one.

static execute(core, inst)[source]¶

mnemonic = 'incl'¶

opcode = <MathCoprocessorOpcodes.INCL: 30>¶

class ducky.cpu.coprocessor.math_copro.LOAD(instruction_set)[source]¶

Bases: ducky.cpu.coprocessor.math_copro.Descriptor_MATH

Merge two registers together, and make the result new TOS.

static assemble_operands(logger, buffer, inst, operands)[source]¶

static disassemble_operands(logger, inst)[source]¶

static execute(core, inst)[source]¶

mnemonic = 'load'¶

opcode = <MathCoprocessorOpcodes.LOAD: 9>¶

operands = 'r,r'¶

class ducky.cpu.coprocessor.math_copro.LOADUW(instruction_set)[source]¶

Bases: ducky.cpu.coprocessor.math_copro.Descriptor_MATH

Take a value from register, extend it to long, and make the result TOS.

static assemble_operands(logger, buffer, inst, operands)[source]¶

static disassemble_operands(logger, inst)[source]¶

static execute(core, inst)[source]¶

mnemonic = 'loaduw'¶

opcode = <MathCoprocessorOpcodes.LOADUW: 5>¶

operands = 'r'¶

class ducky.cpu.coprocessor.math_copro.LOADW(instruction_set)[source]¶

Bases: ducky.cpu.coprocessor.math_copro.Descriptor_MATH

Take a value from register, extend it to long, and make the result TOS.

static assemble_operands(logger, buffer, inst, operands)[source]¶

static disassemble_operands(logger, inst)[source]¶

static execute(core, inst)[source]¶

mnemonic = 'loadw'¶

opcode = <MathCoprocessorOpcodes.LOADW: 4>¶

operands = 'r'¶

class ducky.cpu.coprocessor.math_copro.MODL(instruction_set)[source]¶

Bases: ducky.cpu.coprocessor.math_copro.Descriptor_MATH

static execute(core, inst)[source]¶

mnemonic = 'modl'¶

opcode = <MathCoprocessorOpcodes.MODL: 12>¶

class ducky.cpu.coprocessor.math_copro.MULL(instruction_set)[source]¶

Bases: ducky.cpu.coprocessor.math_copro.Descriptor_MATH

Multiply two top-most numbers on the stack.

static execute(core, inst)[source]¶

mnemonic = 'mull'¶

opcode = <MathCoprocessorOpcodes.MULL: 10>¶

class ducky.cpu.coprocessor.math_copro.MathCoprocessor(core, *args, **kwargs)[source]¶

Bases: ducky.interfaces.ISnapshotable, ducky.cpu.coprocessor.Coprocessor

Coprocessor itself, includes its register set (“math stack”).

Parameters:	core (ducky.cpu.CPUCore) – CPU core coprocessor belongs to.

dump_stack()[source]¶: Log content of the stack using parent’s DEBUG method.

extend_with_push(u32)[source]¶

load_state(state)[source]¶

save_state(parent)[source]¶

sign_extend_with_push(i32)[source]¶

class ducky.cpu.coprocessor.math_copro.MathCoprocessorInstructionSet[source]¶

Bases: ducky.cpu.instructions.InstructionSet

Math coprocessor’s instruction set.

instruction_set_id = 1¶

instructions = [<ducky.cpu.coprocessor.math_copro.ADDL object at 0x7f923a8e83d0>, <ducky.cpu.coprocessor.math_copro.INCL object at 0x7f923a8e8d90>, <ducky.cpu.coprocessor.math_copro.DECL object at 0x7f923a8e81d0>, <ducky.cpu.coprocessor.math_copro.MULL object at 0x7f923a8e8810>, <ducky.cpu.coprocessor.math_copro.DIVL object at 0x7f923a8e8d10>, <ducky.cpu.coprocessor.math_copro.MODL object at 0x7f923a8e8290>, <ducky.cpu.coprocessor.math_copro.UDIVL object at 0x7f923a8e85d0>, <ducky.cpu.coprocessor.math_copro.UMODL object at 0x7f923a8e8cd0>, <ducky.cpu.coprocessor.math_copro.SYMDIVL object at 0x7f923a8e8b90>, <ducky.cpu.coprocessor.math_copro.SYMMODL object at 0x7f923a8e8b10>, <ducky.cpu.coprocessor.math_copro.DUP object at 0x7f923a8e8f90>, <ducky.cpu.coprocessor.math_copro.DUP2 object at 0x7f923a8e8850>, <ducky.cpu.coprocessor.math_copro.SWP object at 0x7f923a974750>, <ducky.cpu.coprocessor.math_copro.DROP object at 0x7f923a974790>, <ducky.cpu.coprocessor.math_copro.PUSHW object at 0x7f923a974d10>, <ducky.cpu.coprocessor.math_copro.SAVEW object at 0x7f923a974950>, <ducky.cpu.coprocessor.math_copro.POPW object at 0x7f923a974f50>, <ducky.cpu.coprocessor.math_copro.LOADW object at 0x7f923a974b90>, <ducky.cpu.coprocessor.math_copro.POPUW object at 0x7f923a9746d0>, <ducky.cpu.coprocessor.math_copro.LOADUW object at 0x7f923a974bd0>, <ducky.cpu.coprocessor.math_copro.PUSH object at 0x7f923a974b10>, <ducky.cpu.coprocessor.math_copro.SAVE object at 0x7f923a974dd0>, <ducky.cpu.coprocessor.math_copro.POP object at 0x7f923a974990>, <ducky.cpu.coprocessor.math_copro.LOAD object at 0x7f923a974cd0>, <ducky.cpu.instructions.SIS object at 0x7f923a974fd0>]¶

opcode_desc_map = {<MathCoprocessorOpcodes.POPW: 0>: <ducky.cpu.coprocessor.math_copro.POPW object at 0x7f923a974f50>, <MathCoprocessorOpcodes.POPUW: 1>: <ducky.cpu.coprocessor.math_copro.POPUW object at 0x7f923a9746d0>, <MathCoprocessorOpcodes.PUSHW: 2>: <ducky.cpu.coprocessor.math_copro.PUSHW object at 0x7f923a974d10>, <MathCoprocessorOpcodes.SAVEW: 3>: <ducky.cpu.coprocessor.math_copro.SAVEW object at 0x7f923a974950>, <MathCoprocessorOpcodes.LOADW: 4>: <ducky.cpu.coprocessor.math_copro.LOADW object at 0x7f923a974b90>, <MathCoprocessorOpcodes.LOADUW: 5>: <ducky.cpu.coprocessor.math_copro.LOADUW object at 0x7f923a974bd0>, <MathCoprocessorOpcodes.POP: 6>: <ducky.cpu.coprocessor.math_copro.POP object at 0x7f923a974990>, <MathCoprocessorOpcodes.SAVE: 7>: <ducky.cpu.coprocessor.math_copro.SAVE object at 0x7f923a974dd0>, <MathCoprocessorOpcodes.PUSH: 8>: <ducky.cpu.coprocessor.math_copro.PUSH object at 0x7f923a974b10>, <MathCoprocessorOpcodes.LOAD: 9>: <ducky.cpu.coprocessor.math_copro.LOAD object at 0x7f923a974cd0>, <MathCoprocessorOpcodes.MULL: 10>: <ducky.cpu.coprocessor.math_copro.MULL object at 0x7f923a8e8810>, <MathCoprocessorOpcodes.DIVL: 11>: <ducky.cpu.coprocessor.math_copro.DIVL object at 0x7f923a8e8d10>, <MathCoprocessorOpcodes.MODL: 12>: <ducky.cpu.coprocessor.math_copro.MODL object at 0x7f923a8e8290>, <MathCoprocessorOpcodes.SYMDIVL: 13>: <ducky.cpu.coprocessor.math_copro.SYMDIVL object at 0x7f923a8e8b90>, <MathCoprocessorOpcodes.SYMMODL: 14>: <ducky.cpu.coprocessor.math_copro.SYMMODL object at 0x7f923a8e8b10>, <MathCoprocessorOpcodes.UDIVL: 15>: <ducky.cpu.coprocessor.math_copro.UDIVL object at 0x7f923a8e85d0>, <MathCoprocessorOpcodes.UMODL: 16>: <ducky.cpu.coprocessor.math_copro.UMODL object at 0x7f923a8e8cd0>, <MathCoprocessorOpcodes.DUP: 20>: <ducky.cpu.coprocessor.math_copro.DUP object at 0x7f923a8e8f90>, <MathCoprocessorOpcodes.DUP2: 21>: <ducky.cpu.coprocessor.math_copro.DUP2 object at 0x7f923a8e8850>, <MathCoprocessorOpcodes.SWP: 22>: <ducky.cpu.coprocessor.math_copro.SWP object at 0x7f923a974750>, <MathCoprocessorOpcodes.DROP: 23>: <ducky.cpu.coprocessor.math_copro.DROP object at 0x7f923a974790>, <MathCoprocessorOpcodes.INCL: 30>: <ducky.cpu.coprocessor.math_copro.INCL object at 0x7f923a8e8d90>, <MathCoprocessorOpcodes.DECL: 31>: <ducky.cpu.coprocessor.math_copro.DECL object at 0x7f923a8e81d0>, <MathCoprocessorOpcodes.ADDL: 32>: <ducky.cpu.coprocessor.math_copro.ADDL object at 0x7f923a8e83d0>, <DuckyOpcodes.SIS: 63>: <ducky.cpu.instructions.SIS object at 0x7f923a974fd0>}¶

opcode_encoding_map = {<MathCoprocessorOpcodes.POPW: 0>: <class 'ducky.cpu.instructions.EncodingR'>, <MathCoprocessorOpcodes.POPUW: 1>: <class 'ducky.cpu.instructions.EncodingR'>, <MathCoprocessorOpcodes.PUSHW: 2>: <class 'ducky.cpu.instructions.EncodingR'>, <MathCoprocessorOpcodes.SAVEW: 3>: <class 'ducky.cpu.instructions.EncodingR'>, <MathCoprocessorOpcodes.LOADW: 4>: <class 'ducky.cpu.instructions.EncodingR'>, <MathCoprocessorOpcodes.LOADUW: 5>: <class 'ducky.cpu.instructions.EncodingR'>, <MathCoprocessorOpcodes.POP: 6>: <class 'ducky.cpu.instructions.EncodingR'>, <MathCoprocessorOpcodes.SAVE: 7>: <class 'ducky.cpu.instructions.EncodingR'>, <MathCoprocessorOpcodes.PUSH: 8>: <class 'ducky.cpu.instructions.EncodingR'>, <MathCoprocessorOpcodes.LOAD: 9>: <class 'ducky.cpu.instructions.EncodingR'>, <MathCoprocessorOpcodes.MULL: 10>: <class 'ducky.cpu.instructions.EncodingR'>, <MathCoprocessorOpcodes.DIVL: 11>: <class 'ducky.cpu.instructions.EncodingR'>, <MathCoprocessorOpcodes.MODL: 12>: <class 'ducky.cpu.instructions.EncodingR'>, <MathCoprocessorOpcodes.SYMDIVL: 13>: <class 'ducky.cpu.instructions.EncodingR'>, <MathCoprocessorOpcodes.SYMMODL: 14>: <class 'ducky.cpu.instructions.EncodingR'>, <MathCoprocessorOpcodes.UDIVL: 15>: <class 'ducky.cpu.instructions.EncodingR'>, <MathCoprocessorOpcodes.UMODL: 16>: <class 'ducky.cpu.instructions.EncodingR'>, <MathCoprocessorOpcodes.DUP: 20>: <class 'ducky.cpu.instructions.EncodingR'>, <MathCoprocessorOpcodes.DUP2: 21>: <class 'ducky.cpu.instructions.EncodingR'>, <MathCoprocessorOpcodes.SWP: 22>: <class 'ducky.cpu.instructions.EncodingR'>, <MathCoprocessorOpcodes.DROP: 23>: <class 'ducky.cpu.instructions.EncodingR'>, <MathCoprocessorOpcodes.INCL: 30>: <class 'ducky.cpu.instructions.EncodingR'>, <MathCoprocessorOpcodes.DECL: 31>: <class 'ducky.cpu.instructions.EncodingR'>, <MathCoprocessorOpcodes.ADDL: 32>: <class 'ducky.cpu.instructions.EncodingR'>, <DuckyOpcodes.SIS: 63>: <class 'ducky.cpu.instructions.EncodingI'>}¶

opcodes¶: alias of MathCoprocessorOpcodes

class ducky.cpu.coprocessor.math_copro.MathCoprocessorOpcodes[source]¶

Bases: enum.IntEnum

Math coprocessor’s instruction opcodes.

ADDL = <MathCoprocessorOpcodes.ADDL: 32>¶

DECL = <MathCoprocessorOpcodes.DECL: 31>¶

DIVL = <MathCoprocessorOpcodes.DIVL: 11>¶

DROP = <MathCoprocessorOpcodes.DROP: 23>¶

DUP = <MathCoprocessorOpcodes.DUP: 20>¶

DUP2 = <MathCoprocessorOpcodes.DUP2: 21>¶

INCL = <MathCoprocessorOpcodes.INCL: 30>¶

LOAD = <MathCoprocessorOpcodes.LOAD: 9>¶

LOADUW = <MathCoprocessorOpcodes.LOADUW: 5>¶

LOADW = <MathCoprocessorOpcodes.LOADW: 4>¶

MODL = <MathCoprocessorOpcodes.MODL: 12>¶

MULL = <MathCoprocessorOpcodes.MULL: 10>¶

POP = <MathCoprocessorOpcodes.POP: 6>¶

POPUW = <MathCoprocessorOpcodes.POPUW: 1>¶

POPW = <MathCoprocessorOpcodes.POPW: 0>¶

PUSH = <MathCoprocessorOpcodes.PUSH: 8>¶

PUSHW = <MathCoprocessorOpcodes.PUSHW: 2>¶

SAVE = <MathCoprocessorOpcodes.SAVE: 7>¶

SAVEW = <MathCoprocessorOpcodes.SAVEW: 3>¶

SIS = <MathCoprocessorOpcodes.SIS: 63>¶

SWP = <MathCoprocessorOpcodes.SWP: 22>¶

SYMDIVL = <MathCoprocessorOpcodes.SYMDIVL: 13>¶

SYMMODL = <MathCoprocessorOpcodes.SYMMODL: 14>¶

UDIVL = <MathCoprocessorOpcodes.UDIVL: 15>¶

UMODL = <MathCoprocessorOpcodes.UMODL: 16>¶

class ducky.cpu.coprocessor.math_copro.MathCoprocessorState[source]¶

Bases: ducky.snapshot.SnapshotNode

Snapshot node holding the state of math coprocessor.

class ducky.cpu.coprocessor.math_copro.POP(instruction_set)[source]¶

Bases: ducky.cpu.coprocessor.math_copro.Descriptor_MATH

Pop the long from data stack, and make it new TOS.

static execute(core, inst)[source]¶

mnemonic = 'pop'¶

opcode = <MathCoprocessorOpcodes.POP: 6>¶

class ducky.cpu.coprocessor.math_copro.POPUW(instruction_set)[source]¶

Bases: ducky.cpu.coprocessor.math_copro.Descriptor_MATH

Pop the int``from data stack, extend it to ``long, and make the result TOS.

static execute(core, inst)[source]¶

mnemonic = 'popuw'¶

opcode = <MathCoprocessorOpcodes.POPUW: 1>¶

class ducky.cpu.coprocessor.math_copro.POPW(instruction_set)[source]¶

Bases: ducky.cpu.coprocessor.math_copro.Descriptor_MATH

Pop the int from data stack, extend it to long, and make the result TOS.

static execute(core, inst)[source]¶

mnemonic = 'popw'¶

opcode = <MathCoprocessorOpcodes.POPW: 0>¶

class ducky.cpu.coprocessor.math_copro.PUSH(instruction_set)[source]¶

Bases: ducky.cpu.coprocessor.math_copro.Descriptor_MATH

Push the TOS on the data stack.

static execute(core, inst)[source]¶

mnemonic = 'push'¶

opcode = <MathCoprocessorOpcodes.PUSH: 8>¶

class ducky.cpu.coprocessor.math_copro.PUSHW(instruction_set)[source]¶

Bases: ducky.cpu.coprocessor.math_copro.Descriptor_MATH

Downsize TOS to int, and push the result on the data stack.

static execute(core, inst)[source]¶

mnemonic = 'pushw'¶

opcode = <MathCoprocessorOpcodes.PUSHW: 2>¶

class ducky.cpu.coprocessor.math_copro.RegisterSet(core)[source]¶

Bases: ducky.interfaces.ISnapshotable

Math stack wrapping class. Provides basic push/pop access, and direct access to a top of the stack.

Parameters:	core (ducky.cpu.CPUCore) – CPU core registers belong to.

load_state(state)[source]¶

pop()[source]¶

Pop the top value from stack and return it.

Raises:	ducky.cpu.coprocessor.math_copro.EmptyMathStackError – if there are no values on the stack.

push(v)[source]¶

Push new value on top of the stack.

Raises:	ducky.cpu.coprocessor.math_copro.FullMathStackError – if there is no space available on the stack.

save_state(parent)[source]¶

tos()[source]¶

Return the top of the stack, without removing it from a stack.

Raises:	ducky.cpu.coprocessor.math_copro.EmptyMathStackError – if there are no values on the stack.

tos1()[source]¶

Return the item below the top of the stack, without removing it from a stack.

Raises:	ducky.cpu.coprocessor.math_copro.EmptyMathStackError – if there are no values on the stack.

class ducky.cpu.coprocessor.math_copro.SAVE(instruction_set)[source]¶

Bases: ducky.cpu.coprocessor.math_copro.Descriptor_MATH

Store TOS in two registers.

static assemble_operands(logger, buffer, inst, operands)[source]¶

static disassemble_operands(logger, inst)[source]¶

static execute(core, inst)[source]¶

mnemonic = 'save'¶

opcode = <MathCoprocessorOpcodes.SAVE: 7>¶

operands = 'r,r'¶

class ducky.cpu.coprocessor.math_copro.SAVEW(instruction_set)[source]¶

Bases: ducky.cpu.coprocessor.math_copro.Descriptor_MATH

Downsize TOS to int, and store the result in register.

static assemble_operands(logger, buffer, inst, operands)[source]¶

static disassemble_operands(logger, inst)[source]¶

static execute(core, inst)[source]¶

mnemonic = 'savew'¶

opcode = <MathCoprocessorOpcodes.SAVEW: 3>¶

operands = 'r'¶

ducky.cpu.coprocessor.math_copro.STACK_DEPTH = 8¶: Number of available spots on the math stack.

class ducky.cpu.coprocessor.math_copro.SWP(instruction_set)[source]¶

Bases: ducky.cpu.coprocessor.math_copro.Descriptor_MATH

static execute(core, inst)[source]¶

mnemonic = 'swp'¶

opcode = <MathCoprocessorOpcodes.SWP: 22>¶

class ducky.cpu.coprocessor.math_copro.SYMDIVL(instruction_set)[source]¶

Bases: ducky.cpu.coprocessor.math_copro.Descriptor_MATH

The same operation like DIVL but provides symmetric results.

static execute(core, inst)[source]¶

mnemonic = 'symdivl'¶

opcode = <MathCoprocessorOpcodes.SYMDIVL: 13>¶

class ducky.cpu.coprocessor.math_copro.SYMMODL(instruction_set)[source]¶

Bases: ducky.cpu.coprocessor.math_copro.Descriptor_MATH

static execute(core, inst)[source]¶

mnemonic = 'symmodl'¶

opcode = <MathCoprocessorOpcodes.SYMMODL: 14>¶

class ducky.cpu.coprocessor.math_copro.UDIVL(instruction_set)[source]¶

Bases: ducky.cpu.coprocessor.math_copro.Descriptor_MATH

Divide the value below the top of the math stack by the topmost value.

static execute(core, inst)[source]¶

mnemonic = 'udivl'¶

opcode = <MathCoprocessorOpcodes.UDIVL: 15>¶

class ducky.cpu.coprocessor.math_copro.UMODL(instruction_set)[source]¶

Bases: ducky.cpu.coprocessor.math_copro.Descriptor_MATH

static execute(core, inst)[source]¶

mnemonic = 'umodl'¶

opcode = <MathCoprocessorOpcodes.UMODL: 16>¶

Module contents¶

Coprocessors are intended to extend operations of CPUs. They are optional, and can cover wide range of operations, e.g. floating point arithmetic, encryption, or graphics. They are always attached to a CPU core, and may contain and use internal resources, e.g. their very own register sets, machine’s memory, or their parent’s caches.

class ducky.cpu.coprocessor.Coprocessor(core)[source]¶

Bases: object

Base class for per-core coprocessors.

Submodules¶

ducky.cpu.assemble module¶

class ducky.cpu.assemble.AlignSlot(boundary)[source]¶: Bases: ducky.cpu.assemble.DataSlot

class ducky.cpu.assemble.AsciiSlot[source]¶

Bases: ducky.cpu.assemble.DataSlot

close()[source]¶

symbol_type = <SymbolDataTypes.ASCII: 5>¶

class ducky.cpu.assemble.BssSection(s_name, flags=None, **kwargs)[source]¶: Bases: ducky.cpu.assemble.Section

class ducky.cpu.assemble.Buffer(logger, filename, buff)[source]¶

Bases: object

get_error(cls, info, column=None, length=None, **kwargs)[source]¶

get_line()[source]¶

has_lines()[source]¶

put_buffer(buff, filename=None)[source]¶

put_line(line)[source]¶

class ducky.cpu.assemble.ByteSlot[source]¶

Bases: ducky.cpu.assemble.DataSlot

close()[source]¶

symbol_type = <SymbolDataTypes.CHAR: 2>¶

class ducky.cpu.assemble.BytesSlot[source]¶

Bases: ducky.cpu.assemble.DataSlot

close()[source]¶

symbol_type = <SymbolDataTypes.ASCII: 5>¶

class ducky.cpu.assemble.CharSlot[source]¶

Bases: ducky.cpu.assemble.DataSlot

close()[source]¶

symbol_type = <SymbolDataTypes.CHAR: 2>¶

class ducky.cpu.assemble.DataSection(s_name, flags=None, **kwargs)[source]¶: Bases: ducky.cpu.assemble.Section

class ducky.cpu.assemble.DataSlot[source]¶

Bases: object

close()[source]¶

class ducky.cpu.assemble.FunctionSlot[source]¶

Bases: ducky.cpu.assemble.DataSlot

close()[source]¶

symbol_type = <SymbolDataTypes.FUNCTION: 6>¶

class ducky.cpu.assemble.IntSlot[source]¶

Bases: ducky.cpu.assemble.DataSlot

close()[source]¶

symbol_type = <SymbolDataTypes.INT: 0>¶

class ducky.cpu.assemble.Label(name, section, location)[source]¶: Bases: object

ducky.cpu.assemble.PATTERN(pattern)[source]¶

class ducky.cpu.assemble.RODataSection(s_name, flags=None, **kwargs)[source]¶: Bases: ducky.cpu.assemble.Section

class ducky.cpu.assemble.Reference(add=None, label=None)[source]¶: Bases: object

class ducky.cpu.assemble.RelocSection(s_name, flags=None, **kwargs)[source]¶: Bases: ducky.cpu.assemble.Section

class ducky.cpu.assemble.RelocSlot(name, flags=None, patch_section=None, patch_address=None, patch_offset=None, patch_size=None, patch_add=None)[source]¶: Bases: object

class ducky.cpu.assemble.Section(s_name, s_type, s_flags)[source]¶: Bases: object

class ducky.cpu.assemble.ShortSlot[source]¶

Bases: ducky.cpu.assemble.DataSlot

close()[source]¶

symbol_type = <SymbolDataTypes.SHORT: 1>¶

class ducky.cpu.assemble.SourceLocation(filename=None, lineno=None, column=None, length=None)[source]¶

Bases: object

copy()[source]¶

class ducky.cpu.assemble.SpaceSlot[source]¶

Bases: ducky.cpu.assemble.DataSlot

close()[source]¶

symbol_type = <SymbolDataTypes.ASCII: 5>¶

class ducky.cpu.assemble.StringSlot[source]¶

Bases: ducky.cpu.assemble.DataSlot

close()[source]¶

symbol_type = <SymbolDataTypes.STRING: 4>¶

class ducky.cpu.assemble.SymbolsSection(s_name, flags=None, **kwargs)[source]¶: Bases: ducky.cpu.assemble.Section

class ducky.cpu.assemble.TextSection(s_name, flags=None, **kwargs)[source]¶: Bases: ducky.cpu.assemble.Section

ducky.cpu.assemble.decode_string(s)[source]¶

ducky.cpu.assemble.sizeof(o)[source]¶

ducky.cpu.assemble.translate_buffer(logger, buff, base_address=None, mmapable_sections=False, writable_sections=False, filename=None, defines=None, includes=None, verify_disassemble=False)[source]¶

ducky.cpu.instructions module¶

class ducky.cpu.instructions.ADD(instruction_set)[source]¶

Bases: ducky.cpu.instructions._BINOP

static jit(core, inst)[source]¶

mnemonic = 'add'¶

opcode = <DuckyOpcodes.ADD: 28>¶

class ducky.cpu.instructions.AND(instruction_set)[source]¶

Bases: ducky.cpu.instructions._BITOP

static jit(core, inst)[source]¶

mnemonic = 'and'¶

opcode = <DuckyOpcodes.AND: 34>¶

class ducky.cpu.instructions.BE(instruction_set)[source]¶