Skip to content

Commit

Permalink
Added docs to support serializable changes
Browse files Browse the repository at this point in the history
  • Loading branch information
@coretl @c-mita
coretl authored and c-mita committed Jun 28, 2016
1 parent e11949f commit dbeec6c
Showing 1 changed file with 117 additions and 51 deletions.
168 changes: 117 additions & 51 deletions docs/arch/structure.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,9 @@ Block Structure

To describe how a Block is structured, we will use the `pvData Meta Language`_.
It is important to note that although many EPICS conventions are followed in
Malcolm, it is not a required part of it.
Malcolm, it is not a required part of it. The typeid of structures (in italics)
will appear as a string typeid field in JSON serialized messages, and as the
typeid in pvData serialized messages.

There are a number of operations that can be performed on the Block structure,
such as Get, Put, Subscribe, Post. These will be described in the
Expand All @@ -16,8 +18,7 @@ conditions between substructure updates, but some of the protocols supported

Also note the placement of meta objects in the Block structure. The presence of
a meta element in the structure allows separation of the current value from the
metadata about the element. This is why there is no Method in the Block
structure, only a MethodMeta.
metadata about the element.

.. _pvData Meta Language:
http://epics-pvdata.sourceforge.net/docbuild/pvDataJava/tip/documentation/
Expand All @@ -26,17 +27,23 @@ structure, only a MethodMeta.
A Block looks like this::

Block :=
Attribute state // type=enum
Attribute status // type=string
Attribute busy // type=bool
{Attribute <attribute-name>}0+
{MethodMeta <method-name>}0+

malcolm:core/Block:1.0

BlockMeta meta
Attribute state // ChoiceMeta
Attribute status // StringMeta
Attribute busy // BooleanMeta
{Attribute <attribute-name>}0+
{Method <method-name>}0+


BlockMeta :=
string metaOf // E.g. malcolm:zebra2/Zebra2:1.0

malcolm:core/BlockMeta:1.0

string description // Description of Block
string[] tags // e.g. "instance:FlowGraph"
string[] tags :opt // e.g. "instance:FlowGraph"

The `state` Attribute corresponds to the state described in the
:ref:`statemachine` section. The `status` Attribute will hold any status
Expand All @@ -49,71 +56,130 @@ An Attribute looks like this::

Attribute := Scalar | ScalarArray | Table

Scalar :=

NTScalar :=

epics:nt/NTScalar:1.0 // Conformant but optional fields -> meta

scalar_t value
alarm_t alarm
time_t timeStamp
ScalarMeta meta
alarm_t alarm :opt
time_t timeStamp :opt
ScalarMeta meta :opt


ScalarArray :=
scalar_t[] value
alarm_t alarm
time_t timeStamp
ScalarMeta meta

epics:nt/NTScalarArray:1.0 // Conformant but optional fields -> meta

scalar_t[] value
alarm_t alarm :opt
time_t timeStamp :opt
ScalarArrayMeta meta :opt


Table :=

malcolm:core/TableAttribute:1.0 // Not conformant to NTTable: labels

structure value
{scalar_t[] <colname>}0+
alarm_t alarm
time_t timeStamp
TableMeta meta
alarm_t alarm :opt
time_t timeStamp :opt
TableMeta meta :opt

The structures are very similar, and all hold the current value in whatever
type is appropriate for the Attribute. Each structure contains a `meta` field
that describes the values that are allowed to be passed to the value field of
the structure::

ScalarMeta :=
string description // Description of attribute
string metaOf // E.g. malcolm:core/UIntArray:1.0
bool writeable :opt // True if you can Put at the moment
string[] tags :opt // e.g. "widget:textinput"
display_t display :opt // Display limits, units, etc, for numbers
control_t control :opt // For writeable numbers
string[] oneOf :opt // Allowed values if type is "Enum"
string label :opt // Short label if different to name
ScalarMeta := BooleanMeta | StringMeta | ChoiceMeta | NumberMeta


BooleanMeta :=

malcolm:core/BooleanMeta:1.0

string description // Description of attribute
string[] tags :opt // e.g. "widget:led"
bool writeable :opt // True if you can Put at the moment
string label :opt // Short label if different to name


StringMeta :=

malcolm:core/StringMeta:1.0

string description // Description of attribute
string[] tags :opt // e.g. "widget:textinput"
bool writeable :opt // True if you can Put at the moment
string label :opt // Short label if different to name


ChoiceMeta :=

malcolm:core/ChoiceMeta:1.0

string[] choices // Value will be one of these
string description // Description of attribute
string[] tags :opt // e.g. "widget:combo"
bool writeable :opt // True if you can Put at the moment
string label :opt // Short label if different to name


NumberMeta :=

malcolm:core/NumberMeta:1.0

string dtype // e.g. int8, uint32, float64
string description // Description of attribute
string[] tags :opt // e.g. "widget:textupdate"
bool writeable :opt // True if you can Put at the moment
string label :opt // Short label if different to name
display_t display :opt // Display limits, units, etc
control_t control :opt // Control limits for writeable numbers

The ScalarArrayMeta structures are identical to the ScalarMeta structures, but
have "Array" in their typeid. TableMeta has similar fields::

TableMeta :=

malcolm:core/TableMeta:1.0

structure elements // Metadata for each column
{ScalarArrayMeta <elname>}0+
string description // Description of attribute
string metaOf // E.g. malcolm:core/Table:1.0
structure elements // Metadata for each column, must have array
{ScalarMeta <elname>}0+ // type
string[] tags :opt // e.g. "widget:table"
string[] labels :opt // List of column labels if different to
bool writeable :opt // True if you can Put at the moment
string label :opt // Short label if different to name
string[] headings :opt // List of column headings if different to
// element names

ScalarMeta has a number of fields that will be present or not depending on the
contents of the type field. TableMeta contains a structure of elements that
describe the subelements that are allowed in the Table. The metaOf field
contains information about the type of the structure, which is explained in
more detail in the :ref:`types` section.
It contains a structure of elements that describe the subelements that are
allowed in the Table.

A MethodMeta looks like this::
A Method looks like this::

MethodMeta :=
string metaOf // E.g. malcolm:core/Method:1.0
string description // Docstring
MapMeta takes // Argument spec
Method :=

malcolm:core/Method:1.0

MapMeta takes // Argument spec
structure defaults
{any <argname>}0+ // The defaults if not supplied
MapMeta returns :opt // Return value spec if any
bool writeable :opt // True if you can Post at the moment
string[] tags :opt // e.g. "widget:confirmbutton"
{any <argname>}0+ // The defaults if not supplied
string description // Docstring
string[] tags :opt // e.g. "widget:confirmbutton"
bool writeable :opt // True if you can Post at the moment
string label :opt // Short label if different to name
MapMeta returns :opt // Return value spec if any


MapMeta :=
string metaOf // E.g. malcolm:xspress3/Config:1.0

malcolm:core/MapMeta:1.0

structure elements // Metadata for each element in map
{ScalarMeta | TableMeta <elname>}0+
{ScalarMeta | ScalarArrayMeta | TableMeta <elname>}0+
string description // Description of what the map is for
string[] tags :opt // e.g. "widget:group"
string[] required :opt // These fields will always be present

Expand All @@ -123,6 +189,6 @@ The `defaults` structure contains default values that will be used if the
argument is not supplied.

Methods are called by sending a Post message to the block with the name of the
method and the arguments described in the MethodMeta.
method and the arguments described in the takes MapMeta.


0 comments on commit dbeec6c

Please sign in to comment.