doc: add basics about composing_systems

Signed-off-by: Markus Klotzbuecher <mk@mkio.de>

docs/user/composing_systems.rst

@@ -1,31 +1,126 @@
 Composing microblx systems
 ==========================
 
-To build a microblx application, blocks need to be instantiated,
-configured, connected and started up according to the life-cycle
-FSM. There are different ways to do this:
+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.
 
-- by using microblx system composition files (the ``*.usc`` files
-  under examples). ``usc`` stands for microblx system
-  composition). These can be launched using the ``ubx_launch``
-  tool. For example:
+
+Microblx System Composition DSL (usc files)
+-------------------------------------------
+
+``usc`` are declarative descriptions of microblx systems that can be
+validated and instantiated using the ``ubx_launch`` tool.
+
+The following minimal example illustrates the basic syntax:
+
+.. code:: lua
+
+	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:
 
 .. code:: bash
 
 	  $ 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.
+
+TODO: starting up 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.
+
+.. code:: lua
+
+     node_configurations = {
+         global_rnd_conf = {
+             type = "struct random_config",
+	     config = { min=333, max=999 },
+         }
+     }
+
+
+These configurations can then be assigned to multiple blocks:
+
+.. code:: lua
+	  
+      { 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.
 
-this will launch the given system composition and additionally create
-a webserver block to allow system to be introspected via a
-browser. Using the usc files is the preferred approach.
 
-- 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.
+Alternatives
+------------
 
-- 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.
+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.