tvm.micro

MicroTVM module for bare-metal backends

Classes:

Artifact(base_dir, labelled_files, metadata)

Describes a compiler artifact and defines common logic to archive it for transport.

Compiler()

The compiler abstraction used with micro TVM.

DebugWrapperTransport(debugger, transport[, …])

A Transport wrapper class that launches a debugger before opening the transport.

DefaultCompiler([target])

A Compiler implementation that attempts to use the system-installed GCC.

Flasher()

An interface for flashing binaries and returning a transport factory.

GdbRemoteDebugger(gdb_binary, …[, …])

A Debugger that invokes GDB and attaches to a remote GDBserver-based target.

MicroBinary(base_dir, binary_file[, …])

An Artifact that describes a compiled binary.

MicroLibrary(base_dir, library_files[, …])

An Artifact that describes a compiled static library.

Session([binary, flasher, …])

MicroTVM Device Session

SubprocessTransport(args[, …])

A Transport implementation that uses a subprocess’s stdin/stdout as the channel.

TransportLogger(name, child[, logger, level])

Wraps a Transport implementation and logs traffic to the Python logging infrastructure.

Workspace([root, debug])

Defines helper functions for manipulating temporary compilation workspaces.

Exceptions:

SessionTerminatedError

Raised when a transport read operationd discovers that the remote session is terminated.

Functions:

build_static_runtime(workspace, compiler, module)

Build the on-device runtime, statically linking the given modules.

create_local_graph_runtime(graph_json_str, …)

Create a local graph runtime driving execution on the remote CPU context given.

default_options(target_include_dir)

Return default opts passed to Compile commands.

class tvm.micro.Artifact(base_dir, labelled_files, metadata, immobile=False)

Describes a compiler artifact and defines common logic to archive it for transport.

Methods:

abspath(rel_path)

Return absolute path to the member with the given relative path.

archive(archive_path[, metadata_only])

Create a relocatable tar archive of the artifacts.

label(label)

Return a list of relative paths to files with the given label.

unarchive(archive_path, base_dir)

Unarchive an artifact into base_dir.

classmethod unarchive(archive_path, base_dir)

Unarchive an artifact into base_dir.

Parameters
  • archive_path (str) – Path to the archive file.

  • base_dir (str) – Path to a non-existent, empty directory under which the artifact will live. If working with a metadata-only archive, this directory will just hold the metadata.json.

Returns

The unarchived artifact.

Return type

Artifact

abspath(rel_path)

Return absolute path to the member with the given relative path.

label(label)

Return a list of relative paths to files with the given label.

archive(archive_path, metadata_only=False)

Create a relocatable tar archive of the artifacts.

Parameters
  • archive_path (str) – Path to the tar file to create. Or, path to a directory, under which a tar file will be created named {base_dir}.tar.

  • metadata_only (bool) – If true, don’t archive artifacts; instead, just archive metadata plus original base_path. A metadata-only archive can be unarchived and used like a regular archive provided none of the files have changed in their original locations on-disk.

Returns

The value of archive_path, after potentially making the computation describe above.

Return type

str

Raises

ImmboileArtifactError : – When immobile=True was passed to the constructor.

tvm.micro.build_static_runtime(workspace, compiler, module, lib_opts=None, bin_opts=None, generated_lib_opts=None)

Build the on-device runtime, statically linking the given modules.

Parameters
  • compiler (tvm.micro.Compiler) – Compiler instance used to build the runtime.

  • module (IRModule) – Module to statically link.

  • lib_opts (Optional[dict]) – The options parameter passed to compiler.library().

  • bin_opts (Optional[dict]) – The options parameter passed to compiler.binary().

  • generated_lib_opts (Optional[dict]) – The options parameter passed to compiler.library() when compiling the generated TVM C source module.

Returns

The compiled runtime.

Return type

MicroBinary

tvm.micro.default_options(target_include_dir)

Return default opts passed to Compile commands.

class tvm.micro.Workspace(root=None, debug=False)

Defines helper functions for manipulating temporary compilation workspaces.

class tvm.micro.Compiler

The compiler abstraction used with micro TVM.

Methods:

binary(output, objects[, options, …])

Link a binary from the given object and/or source files.

flasher(**kw)

Return a Flasher that can be used to program a produced MicroBinary onto the target.

library(output, sources[, options])

Build a library from the given source files.

Attributes:

flasher_factory

Produce a FlasherFactory for a Flasher instance suitable for this Compiler.

abstract library(output, sources, options=None)

Build a library from the given source files.

Parameters
  • output (str) – The path to the library that should be created. The containing directory is guaranteed to be empty and should be the base_dir for the returned Artifact.

  • sources (List[str]) – A list of paths to source files that should be compiled.

  • options (Optional[List[str]]) – If given, additional command-line flags to pass to the compiler.

Returns

The compiled library, as a MicroLibrary instance.

Return type

MicroLibrary

abstract binary(output, objects, options=None, link_main=True, main_options=None)

Link a binary from the given object and/or source files.

Parameters
  • output (str) – The path to the binary that should be created. The containing directory is guaranteed to be empty and should be the base_dir for the returned Artifact.

  • objects (List[MicroLibrary]) – A list of paths to source files or libraries that should be compiled. The final binary should be statically-linked.

  • options (Optional[List[str]]) – If given, additional command-line flags to pass to the compiler.

  • link_main (Optional[bool]) – True if the standard main entry point for this Compiler should be included in the binary. False if a main entry point is provided in one of objects.

  • main_options (Optional[List[str]]) – If given, additional command-line flags to pass to the compiler when compiling the main() library. In some cases, the main() may be compiled directly into the final binary along with objects for logistical reasons. In those cases, specifying main_options is an error and ValueError will be raised.

Returns

The compiled binary, as a MicroBinary instance.

Return type

MicroBinary

property flasher_factory

Produce a FlasherFactory for a Flasher instance suitable for this Compiler.

flasher(**kw)

Return a Flasher that can be used to program a produced MicroBinary onto the target.

class tvm.micro.DefaultCompiler(target=None)

A Compiler implementation that attempts to use the system-installed GCC.

Methods:

binary(output, objects[, options, …])

Link a binary from the given object and/or source files.

library(output, sources[, options])

Build a library from the given source files.

Attributes:

flasher_factory

Produce a FlasherFactory for a Flasher instance suitable for this Compiler.

library(output, sources, options=None)

Build a library from the given source files.

Parameters
  • output (str) – The path to the library that should be created. The containing directory is guaranteed to be empty and should be the base_dir for the returned Artifact.

  • sources (List[str]) – A list of paths to source files that should be compiled.

  • options (Optional[List[str]]) – If given, additional command-line flags to pass to the compiler.

Returns

The compiled library, as a MicroLibrary instance.

Return type

MicroLibrary

binary(output, objects, options=None, link_main=True, main_options=None)

Link a binary from the given object and/or source files.

Parameters
  • output (str) – The path to the binary that should be created. The containing directory is guaranteed to be empty and should be the base_dir for the returned Artifact.

  • objects (List[MicroLibrary]) – A list of paths to source files or libraries that should be compiled. The final binary should be statically-linked.

  • options (Optional[List[str]]) – If given, additional command-line flags to pass to the compiler.

  • link_main (Optional[bool]) – True if the standard main entry point for this Compiler should be included in the binary. False if a main entry point is provided in one of objects.

  • main_options (Optional[List[str]]) – If given, additional command-line flags to pass to the compiler when compiling the main() library. In some cases, the main() may be compiled directly into the final binary along with objects for logistical reasons. In those cases, specifying main_options is an error and ValueError will be raised.

Returns

The compiled binary, as a MicroBinary instance.

Return type

MicroBinary

property flasher_factory

Produce a FlasherFactory for a Flasher instance suitable for this Compiler.

class tvm.micro.Flasher

An interface for flashing binaries and returning a transport factory.

Methods:

flash(micro_binary)

Flash a binary onto the device.

abstract flash(micro_binary)

Flash a binary onto the device.

Parameters

micro_binary (MicroBinary) – A MicroBinary instance.

Returns

A ContextManager that can be used to create and tear down an RPC transport layer between this TVM instance and the newly-flashed binary.

Return type

transport.TransportContextManager

class tvm.micro.GdbRemoteDebugger(gdb_binary, remote_hostport, debug_binary, wrapping_context_manager=None, **popen_kw)

A Debugger that invokes GDB and attaches to a remote GDBserver-based target.

Methods:

start()

Start the debugger, but do not block on it.

stop()

Terminate the debugger.

start()

Start the debugger, but do not block on it.

The runtime will continue to be driven in the background.

stop()

Terminate the debugger.

class tvm.micro.MicroLibrary(base_dir, library_files, debug_files=None, labelled_files=None, metadata=None, immobile=False)

An Artifact that describes a compiled static library.

class tvm.micro.MicroBinary(base_dir, binary_file, debug_files=None, labelled_files=None, metadata=None, immobile=False)

An Artifact that describes a compiled binary.

tvm.micro.create_local_graph_runtime(graph_json_str, mod, ctx)

Create a local graph runtime driving execution on the remote CPU context given.

Parameters
  • graph_json_str (str) – A string containing the graph representation.

  • mod (tvm.runtime.Module) – The remote module containing functions in graph_json_str.

  • ctx (tvm.Context) – The remote CPU execution context.

Returns

A local graph runtime instance that executes on the remote device.

Return type

tvm.contrib.GraphRuntime

class tvm.micro.Session(binary=None, flasher=None, transport_context_manager=None, session_name='micro-rpc', timeout_override=None)

MicroTVM Device Session

Parameters

config (dict) – configuration for this session (as generated by tvm.micro.device.host.default_config(), for example)

Example

c_mod = ...  # some module generated with "c" as the target
dev_config = micro.device.arm.stm32f746xx.default_config('127.0.0.1', 6666)
with tvm.micro.Session(dev_config) as sess:
    micro_mod = sess.create_micro_mod(c_mod)
exception tvm.micro.SessionTerminatedError

Raised when a transport read operationd discovers that the remote session is terminated.

class tvm.micro.TransportLogger(name, child, logger=None, level=20)

Wraps a Transport implementation and logs traffic to the Python logging infrastructure.

Methods:

close()

Release resources associated with this transport.

open()

Open any resources needed to send and receive RPC protocol data for a single session.

read(n, timeout_sec)

Read up to n bytes from the transport.

timeouts()

Return TransportTimeouts suitable for use with this transport.

write(data, timeout_sec)

Write data to the transport channel.

timeouts()

Return TransportTimeouts suitable for use with this transport.

See the TransportTimeouts documentation in python/tvm/micro/session.py.

open()

Open any resources needed to send and receive RPC protocol data for a single session.

close()

Release resources associated with this transport.

read(n, timeout_sec)

Read up to n bytes from the transport.

Parameters
  • n (int) – Maximum number of bytes to read from the transport.

  • timeout_sec (Union[float, None]) – Number of seconds to wait for all n bytes to be received before timing out. The transport can wait additional time to account for transport latency or bandwidth limitations based on the selected configuration and number of bytes being received. If timeout_sec is 0, read should attempt to service the request in a non-blocking fashion. If timeout_sec is None, read should block until at least 1 byte of data can be returned.

Returns

Data read from the channel. Less than n bytes may be returned, but 0 bytes should never be returned. If returning less than n bytes, the full timeout_sec, plus any internally-added timeout, should be waited. If a timeout or transport error occurs, an exception should be raised rather than simply returning empty bytes.

Return type

bytes

Raises
  • TransportClosedError : – When the transport layer determines that the transport can no longer send or receive data due to an underlying I/O problem (i.e. file descriptor closed, cable removed, etc).

  • IoTimeoutError : – When timeout_sec elapses without receiving any data.

write(data, timeout_sec)

Write data to the transport channel.

Parameters
  • data (bytes) – The data to write over the channel.

  • timeout_sec (Union[float, None]) – Number of seconds to wait for at least one byte to be written before timing out. The transport can wait additional time to account for transport latency or bandwidth limitations based on the selected configuration and number of bytes being received. If timeout_sec is 0, write should attempt to service the request in a non-blocking fashion. If timeout_sec is None, write should block until at least 1 byte of data can be returned.

Returns

The number of bytes written to the underlying channel. This can be less than the length of data, but cannot be 0 (raise an exception instead).

Return type

int

Raises
  • TransportClosedError : – When the transport layer determines that the transport can no longer send or receive data due to an underlying I/O problem (i.e. file descriptor closed, cable removed, etc).

  • IoTimeoutError : – When timeout_sec elapses without receiving any data.

class tvm.micro.DebugWrapperTransport(debugger, transport, disable_session_start_retry=False)

A Transport wrapper class that launches a debugger before opening the transport.

This is primiarly useful when debugging the other end of a SubprocessTransport. It allows you to pipe data through the GDB process to drive the subprocess with a debugger attached.

Methods:

close()

Release resources associated with this transport.

open()

Open any resources needed to send and receive RPC protocol data for a single session.

read(n, timeout_sec)

Read up to n bytes from the transport.

timeouts()

Return TransportTimeouts suitable for use with this transport.

write(data, timeout_sec)

Write data to the transport channel.

timeouts()

Return TransportTimeouts suitable for use with this transport.

See the TransportTimeouts documentation in python/tvm/micro/session.py.

open()

Open any resources needed to send and receive RPC protocol data for a single session.

write(data, timeout_sec)

Write data to the transport channel.

Parameters
  • data (bytes) – The data to write over the channel.

  • timeout_sec (Union[float, None]) – Number of seconds to wait for at least one byte to be written before timing out. The transport can wait additional time to account for transport latency or bandwidth limitations based on the selected configuration and number of bytes being received. If timeout_sec is 0, write should attempt to service the request in a non-blocking fashion. If timeout_sec is None, write should block until at least 1 byte of data can be returned.

Returns

The number of bytes written to the underlying channel. This can be less than the length of data, but cannot be 0 (raise an exception instead).

Return type

int

Raises
  • TransportClosedError : – When the transport layer determines that the transport can no longer send or receive data due to an underlying I/O problem (i.e. file descriptor closed, cable removed, etc).

  • IoTimeoutError : – When timeout_sec elapses without receiving any data.

read(n, timeout_sec)

Read up to n bytes from the transport.

Parameters
  • n (int) – Maximum number of bytes to read from the transport.

  • timeout_sec (Union[float, None]) – Number of seconds to wait for all n bytes to be received before timing out. The transport can wait additional time to account for transport latency or bandwidth limitations based on the selected configuration and number of bytes being received. If timeout_sec is 0, read should attempt to service the request in a non-blocking fashion. If timeout_sec is None, read should block until at least 1 byte of data can be returned.

Returns

Data read from the channel. Less than n bytes may be returned, but 0 bytes should never be returned. If returning less than n bytes, the full timeout_sec, plus any internally-added timeout, should be waited. If a timeout or transport error occurs, an exception should be raised rather than simply returning empty bytes.

Return type

bytes

Raises
  • TransportClosedError : – When the transport layer determines that the transport can no longer send or receive data due to an underlying I/O problem (i.e. file descriptor closed, cable removed, etc).

  • IoTimeoutError : – When timeout_sec elapses without receiving any data.

close()

Release resources associated with this transport.

class tvm.micro.SubprocessTransport(args, max_startup_latency_sec=5.0, max_latency_sec=5.0, **kwargs)

A Transport implementation that uses a subprocess’s stdin/stdout as the channel.

Methods:

close()

Release resources associated with this transport.

open()

Open any resources needed to send and receive RPC protocol data for a single session.

read(n, timeout_sec)

Read up to n bytes from the transport.

timeouts()

Return TransportTimeouts suitable for use with this transport.

write(data, timeout_sec)

Write data to the transport channel.

timeouts()

Return TransportTimeouts suitable for use with this transport.

See the TransportTimeouts documentation in python/tvm/micro/session.py.

open()

Open any resources needed to send and receive RPC protocol data for a single session.

write(data, timeout_sec)

Write data to the transport channel.

Parameters
  • data (bytes) – The data to write over the channel.

  • timeout_sec (Union[float, None]) – Number of seconds to wait for at least one byte to be written before timing out. The transport can wait additional time to account for transport latency or bandwidth limitations based on the selected configuration and number of bytes being received. If timeout_sec is 0, write should attempt to service the request in a non-blocking fashion. If timeout_sec is None, write should block until at least 1 byte of data can be returned.

Returns

The number of bytes written to the underlying channel. This can be less than the length of data, but cannot be 0 (raise an exception instead).

Return type

int

Raises
  • TransportClosedError : – When the transport layer determines that the transport can no longer send or receive data due to an underlying I/O problem (i.e. file descriptor closed, cable removed, etc).

  • IoTimeoutError : – When timeout_sec elapses without receiving any data.

read(n, timeout_sec)

Read up to n bytes from the transport.

Parameters
  • n (int) – Maximum number of bytes to read from the transport.

  • timeout_sec (Union[float, None]) – Number of seconds to wait for all n bytes to be received before timing out. The transport can wait additional time to account for transport latency or bandwidth limitations based on the selected configuration and number of bytes being received. If timeout_sec is 0, read should attempt to service the request in a non-blocking fashion. If timeout_sec is None, read should block until at least 1 byte of data can be returned.

Returns

Data read from the channel. Less than n bytes may be returned, but 0 bytes should never be returned. If returning less than n bytes, the full timeout_sec, plus any internally-added timeout, should be waited. If a timeout or transport error occurs, an exception should be raised rather than simply returning empty bytes.

Return type

bytes

Raises
  • TransportClosedError : – When the transport layer determines that the transport can no longer send or receive data due to an underlying I/O problem (i.e. file descriptor closed, cable removed, etc).

  • IoTimeoutError : – When timeout_sec elapses without receiving any data.

close()

Release resources associated with this transport.