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], 'examples/msp430/blinky/msp430.mmap', march)
>>> 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.c3c(sources, includes, march, opt_level=0, reporter=None, debug=False)

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

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

Parameters:
  • objects – a collection of objects to be linked together.
  • use_runtime (bool) – also link compiler runtime functions
  • debug (bool) – when true, keep debug information. Otherwise remove this debug information from the result.
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, image_name, fmt, 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, debug_db=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
ppci.api.get_arch(arch)

Try to return an architecture instance. 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'>