Api

The ppci library provides provides an intuitive api to the compiler, assembler and other tools. For example to assemble, compile, link and objcopy the msp430 blinky example project, the api can be used as follows:

>>> from ppci.api import asm, c3c, link, objcopy
>>> march = "msp430"
>>> o1 = asm('examples/msp430/blinky/boot.asm', march)
>>> o2 = c3c(['examples/msp430/blinky/blinky.c3'], [], march)
>>> o3 = link([o2, o1], layout='examples/msp430/blinky/msp430.mmap')
>>> objcopy(o3, 'flash', 'hex', 'blinky_msp430.hex')

Instead of using the api, a set of commandline tools are also prodived.

The api module contains a set of handy functions to invoke compilation, linking and assembling.

ppci.api.asm(source, march, debug=False)

Assemble the given source for machine march.

Parameters:
  • source (str) – can be a filename or a file like object.
  • march (str) – march can be a ppci.arch.arch.Architecture instance or a string indicating the machine architecture.
  • debug – generate debugging information
Returns:

A ppci.binutils.objectfile.ObjectFile object

 
>>> import io
>>> from ppci.api import asm
>>> source_file = io.StringIO("db 0x77")
>>> obj = asm(source_file, 'arm')
>>> print(obj)
CodeObject of 1 bytes
ppci.api.archive(objs)

Create an archive from multiple object files.

ppci.api.c3c(sources, includes, march, opt_level=0, reporter=None, debug=False, outstream=None)

Compile a set of sources into binary format for the given target.

Parameters:
  • sources – a collection of sources that will be compiled.
  • includes – a collection of sources that will be used for type and function information.
  • march – the architecture for which to compile.
  • reporter – reporter to write compilation report to
  • debug – include debugging information
Returns:

An object file

 
>>> import io
>>> from ppci.api import c3c
>>> source_file = io.StringIO("module main; var int a;")
>>> obj = c3c([source_file], [], 'arm')
>>> print(obj)
CodeObject of 4 bytes
ppci.api.cc(source: io.TextIOBase, march, coptions=None, opt_level=0, debug=False, reporter=None)

C compiler. compiles a single source file into an object file.

Parameters:
  • source – file like object from which text can be read
  • march – The architecture for which to compile
  • coptions – options for the C frontend
  • debug – Create debug info when set to True
Returns:

an object file

 
>>> import io
>>> from ppci.api import cc
>>> source_file = io.StringIO("void main() { int a; }")
>>> obj = cc(source_file, 'x86_64')
>>> print(obj)
CodeObject of 20 bytes

Links the iterable of objects into one using the given layout.

Parameters:
  • objects – a collection of objects to be linked together.
  • layout – optional memory layout.
  • use_runtime (bool) – also link compiler runtime functions
  • partial_link – Set this to true if you want to perform a partial link. This means, undefined symbols are no error.
  • debug (bool) – when true, keep debug information. Otherwise remove this debug information from the result.
  • extra_symbols – a dict of extra symbols which can be used during linking.
  • libraries – a list of libraries to use when searching for symbols.
  • entry – the entry symbol where execution should begin.
Returns:

The linked object file

 
>>> import io
>>> from ppci.api import asm, c3c, link
>>> asm_source = io.StringIO("db 0x77")
>>> obj1 = asm(asm_source, 'arm')
>>> c3_source = io.StringIO("module main; var int a;")
>>> obj2 = c3c([c3_source], [], 'arm')
>>> obj = link([obj1, obj2])
>>> print(obj)
CodeObject of 8 bytes
ppci.api.objcopy(obj: ppci.binutils.objectfile.ObjectFile, image_name: str, fmt: str, output_filename)

Copy some parts of an object file to an output

ppci.api.bfcompile(source, target, reporter=None)

Compile brainfuck source into binary format for the given target

Parameters:
  • source – a filename or a file like object.
  • march – a architecture instance or a string indicating the target.
Returns:

A new object.

 
>>> import io
>>> from ppci.api import bfcompile
>>> source_file = io.StringIO(">>[-]<<[->>+<<]")
>>> obj = bfcompile(source_file, 'arm')
>>> print(obj) 
CodeObject of ... bytes
ppci.api.construct(buildfile, targets=())

Construct the given buildfile.

Raise task error if something goes wrong.

ppci.api.optimize(ir_module, level=0, reporter=None)

Run a bag of tricks against the ir-code.

This is an in-place operation!

Parameters:
  • ir_module (ppci.ir.Module) – The ir module to optimize.
  • level – The optimization level, 0 is default. Can be 0,1,2 or s 0: No optimization 1: some optimization 2: more optimization s: optimize for size
  • reporter – Report detailed log to this reporter
ppci.api.preprocess(f, output_file, coptions=None)

Pre-process a file into the other file.

ppci.api.get_arch(arch)

Try to return an architecture instance.

Parameters:arch – can be a string in the form of arch:option1:option2 
>>> from ppci.api import get_arch
>>> arch = get_arch('msp430')
>>> arch
msp430-arch
>>> type(arch)
<class 'ppci.arch.msp430.arch.Msp430Arch'>
ppci.api.get_current_arch()

Try to get the architecture for the current platform

ppci.api.is_platform_supported()

Determine if this platform is supported

ppci.api.ir_to_object(ir_modules, march, reporter=None, debug=False, opt='speed', outstream=None)

Translate IR-modules into code for the given architecture.

Parameters:
  • ir_modules – a collection of ir-modules that will be transformed into machine code.
  • march – the architecture for which to compile.
  • reporter – reporter to write compilation report to
  • debug (bool) – include debugging information
  • opt (str) – optimization goal. Can be ‘speed’, ‘size’ or ‘co2’.
  • outstream – instruction stream to write instructions to
Returns:

An object file
Return type:

ObjectFile
ppci.api.ir_to_python(ir_modules, f, reporter=None)

Convert ir-code to python code

ppci.api.ir_to_assembly(ir_modules, march, add_binary=False)

Translate the given ir-code into assembly code.

ppci.api.bf_to_ir(source, target)

Compile brainfuck source into ir code

ppci.api.ws_to_ir(source)

Compile whitespace source