Crate micrortu_sdk 

MicroRTU SDK

Provides utilities to create wasm blocks for MicroRTU.

Documentation can be generated via cargo doc --open command.

Template

To generate a simple project, use that command. You should have cargo-generate installed.

cargo generate --git https://github.com/t-industry/micrortu_sdk

Example

This is a basic example of a block that adds two numbers.

use micrortu_sdk::{BlockPorts, FactoryInput, Shared, StepResult, params, ports, register_block};
use static_cell::StaticCell;

pub struct Counter;

ports! {
    #[block_names(counter)]
    pub struct Ports {
      count: TI13 InOut 1 1,
    }
}
params! {
    #[block_names(counter)]
    pub struct Params {}
}

pub fn factory(_: &FactoryInput) -> Option<&'static mut Counter> {
    static COUTNER: StaticCell<Counter> = StaticCell::new();
    Some(COUTNER.init(Counter))
}

pub fn init(_: &mut Shared, _: &mut Counter) -> StepResult {
    0
}

pub fn step(shared: &mut Shared, _: &mut Counter) -> StepResult {
    let ports = Ports::parse(&mut shared.latched_ports[..]);

    ports.count.value += 1.;

    0
}

register_block!(Counter, counter, factory, init, step);

The final crate must also call micrortu_sdk::finalize!(); at the top level, after all block registrations. It embeds the metadata and binding tables the firmware reads.

Block Libraries

Blocks can live in ordinary library crates and be reused from other crates. A library defines blocks as in the example above and closes with export_blocks!() instead of finalize!(). The consuming crate registers them with import_blocks!:

// in the library crate, after the block definitions
micrortu_sdk::export_blocks!(counter);

// in the final crate
micrortu_sdk::import_blocks!(my_library::counter);
micrortu_sdk::finalize!(counter);

Both closing macros optionally take the complete list of block names and fail the build unless it matches the registered blocks. Libraries can also import blocks from other libraries and re-export them alongside their own.

WASM Binary Layout for Non-Rust builds

If you don’t want to use Rust and micrortu_sdk macros, you can still create a wasm block for MicroRTU. The binary layout of the wasm blob must be as follows:

To define block block_name, that can be later referenced in MicroRTU configuration, you need export 3 functions from your final wasm blob.

Required Exports

init

init function with signature () -> ().

SHARED

SHARED symbol, aligned to 8 bytes, and must be valid for reads and writes for at least 512 bytes.

COLLECTED_STRINGS

It should be &[u8], which is a pointer to the start and length of the slice. It should point to all names of the ports and params, concatenated. name_offset and name_len are relative to this slice.

factory_{block_name}

factory_{block_name} is a function that will be called to produce a wasm block. It’s signature should be (i32) -> i32 and code must ensure it follows Rust’s semantics of that signagure:

for<'a> extern "C" fn(&'a FactoryInput) -> Option<&'static mut BlockName>;

Where BlockName is your block’s type.

init_{block_name}

init_{block_name} is a function that will be called before step. It’s signature should be (i32, i32) -> i32 and code must ensure it follows Rust’s semantics of that signagure:

for<'a> extern "C" fn(&'a mut Shared, &'a mut BlockName) -> StepResult;

step_{block_name}

step_{block_name} is a function that will be called to make a “step”. It’s signature should be (i32, i32) -> i32 and code must ensure it follows Rust’s semantics of that signature:

for<'a> extern "C" fn(&'a mut Shared, &'a mut BlockName) -> StepResult;

ports_{block_name} and params_{block_name}

There also must be exports for ports and params of type &[BindingDefinition], which is [i32; 2] in memory - pointer to the start and length of the slice.

Environment Variables

MICRORTU_BAIL_ON_DUPLICATES - if set, compiler will check for duplicate port/param definitions, confs and blocks themselves. If not set, last definition would be used.

Re-exports

pub use bump_allocator::BumpAllocator;

pub use bump_allocator::AllocError;

pub use ie_base;

pub use wasm_global_shared_data;

Modules

bump_allocator

log

trap_err

Helper trait for trapping errors in an iterator.

Macros

debug

error

export_blocks

Macros for generating parser of arguments block requires. Export the blocks of a library crate. Performs the same collection and validation as finalize! and exports one hidden replay macro per block, so a final crate can register them with import_blocks!. Emits no symbols, so it is the right closing macro for library crates. Optionally takes the complete block list, like finalize!.

finalize

Macros for generating parser of arguments block requires. Finalize the build process. That macro must be called after all block registrations in the same crate to embed metadata into the binary. It creates a link section “metadata” with json data of all registered blocks, an exported symbol COLLECTED_STRINGS with all port and param names, and the PORTS_*/PARAMS_* binding definition statics, whose name_offset and name_len reference COLLECTED_STRINGS.

import_blocks

Macros for generating parser of arguments block requires. Register blocks exported by other crates. Each path names the exporting crate and the block. The block’s metadata is replayed into this crate’s registry, so finalize! covers it; the block’s code and wasm symbols come from the exporting crate.

info

log

params

Macros for generating parser of arguments block requires.

ports

Macros for generating parser of arguments block requires.

register_block

Macros for generating parser of arguments block requires. Register block. That macro should be called for each block to register it.

trace

warn

Structs

BindingDefinition

A binding definition.

Direction

A direction of a binding. Meaningful values are IN, OUT, IN_OUT. All other values are invalid, but safe.

FactoryInput

Shared data between the wasm module and the host.

IEBuf

NativeBindingDefinition

A BindingDefinition for native (non-wasm) blocks.

Shared

Shared data between the wasm module and the host.

Enums

ParseError

Erorrs that can occur while parsing genarated ports from Shared, written by MicroRTU. Indicates misconfiguration of MicroRTU or a bug in ports! macro or MicroRTU firmware.

Constants

BINDINGS_BYTES_CAP

IN

Represents an input binding.

IN_OUT

Represents an input-output binding.

OUT

Represents an output binding.

REQUIRED

Traits

BlockPorts

Config

Functions

init_logger

parse_port

Type Aliases

StepResult

The result of a step. 0 means success, anything else is an error. Implementation could also trap, but it’s not recommended. Any error would be logged.

Derive Macros

Config

Macros for generating parser of arguments block requires. Derive macro for Config trait.