Composing microblx systems

Building a microblx application typically involves instantiating blocks, configuring and interconnecting these and finally starting these up. The recommended way to do this is by specifying the system using the microblx composition DSL.

Microblx System Composition DSL (usc files)

usc are declarative descriptions of microblx systems that can be validated and instantiated using the ubx_launch tool. A usc model describes one microblx system, as illustrated by the following minimal example:

local bd = require("blockdiagram")

return bd.system
{
   -- import microblx modules
   imports = {
      "stdtypes", "ptrig", "lfds_cyclic", "myblocks",
   },

   -- describe which blocks to instantiate
   blocks = {
      { name="x1", type="myblocks/x" },
      { name="y1", type="myblocks/y" },
      { name="ptrig1", type="std_triggers/ptrig" },
      ...
   },

   -- connect blocks
   connections = {
      { src="x1.out", tgt="y1.in",  },
      { src="y1.out", tgt="x1.in",  },
   },

   -- configure blocks
   configurations = {
      { name="x1", config = { cfg1="foo", cfg2=33.4 } },
      { name="y1", config = { cfgA={ p=1,z=22.3 }, cfg2=33.4 } },

      -- configure a trigger
      { name="trig1", config = { period = {sec=0, usec=100000 },
                                 sched_policy="SCHED_OTHER",
                                 sched_priority=0,
                                 trig_blocks={
                                    -- the #<blockname> directive will
                                    -- be resolved to an actual
                                    -- reference to the respective
                                    -- block once instantiated
                                    { b="#x1", num_steps=1, measure=0 },
                                    { b="#y1", num_steps=1, measure=0 } } } }
   },
}

Launching

usc files like the above example can be launched using ubx_launch tool. Run with -h for further information on the options. The following simple example:

$ ubx_launch -webif -c examples/trig_rnd_hexdump.usc

this will launch the given system composition and in addition create and configure a web server block to allow the system to be introspected via a browser.

Unless the -nostart option is provided, all blocks will be initialized, configured and started. ubx_launch takes care to do this is safe way by starting up active blocks and triggers after all other blocks (In earlier versions, there was start directive to list these types of blocks, today this attribute is defined active and trigger blocks)

Node configs

Node configs allow to assign the same configuration to multiple blocks. This is useful for global configuration values which are the same for all blocks.

For this, a new top level section node_configurations is introduced, which allows to defined named configurations.

node_configurations = {
    global_rnd_conf = {
        type = "struct random_config",
        config = { min=333, max=999 },
    }
}

These configurations can then be assigned to multiple blocks:

{ name="b1", config = { min_max_config = "&global_rnd_conf"} },
{ name="b2", config = { min_max_config = "&global_rnd_conf"} },

Please refer to examples/systemmodels/node_config_demo.usc for a full example.

Alternatives

Although using usc model is the preferred approach, there are others way to launch a microblx application:

1. by writing a Lua called “deployment script” (e.g. see examples/trig_rnd_to_hexdump.lua). This is not recommended under normal circumstances, but can be useful in specific cases such as for building dedicated test tools.
2. by assembling everything in C/C++. Possible, but somewhat painful to do by hand. This would be better solved by introducing a usc-compiler tool. Please ask on the mailing list.