mirror of
https://github.com/nasa/fpp.git
synced 2026-04-12 05:01:36 -05:00
276 lines
8.8 KiB
Plaintext
276 lines
8.8 KiB
Plaintext
=== Connection Graph Specifiers
|
|
|
|
A *connection graph specifier* specifies one or more *connection graphs* as
|
|
part of a
|
|
<<Definitions_Topology-Definitions,topology definition>>.
|
|
A connection graph is a named set of *connections*.
|
|
A connection connects an
|
|
<<Ports_Port-Instances,output port instance>> of one
|
|
component instance or topology to an
|
|
<<Ports_Port-Instances,input port instance>> of
|
|
another one.
|
|
|
|
==== Syntax
|
|
|
|
A connection graph specifier is one of the following:
|
|
|
|
* A *direct graph specifier:*
|
|
`connections`
|
|
<<Lexical-Elements_Identifiers,_identifier_>>
|
|
`{` _connection-sequence_ `}`
|
|
|
|
* A *pattern graph specifier:*
|
|
_pattern-kind_
|
|
`connections`
|
|
`instance` <<Scoping-of-Names_Qualified-Identifiers,_qual-ident_>>
|
|
_[_
|
|
`{` _instance-sequence_ `}`
|
|
_]_
|
|
|
|
_connection-sequence_ is an
|
|
<<Element-Sequences,element sequence>> in
|
|
which each element is a *connection*,
|
|
and the terminating punctuation is a comma.
|
|
A connection is the following:
|
|
|
|
_[_
|
|
`unmatched`
|
|
_]_
|
|
<<Instance-Member-Identifiers_Port-Instance-Identifiers,_port-instance-id_>>
|
|
_[_
|
|
`[`
|
|
<<Expressions,_expression_>>
|
|
`]`
|
|
_]_
|
|
`pass:[->]`
|
|
<<Instance-Member-Identifiers_Port-Instance-Identifiers,_port-instance-id_>>
|
|
_[_
|
|
`[`
|
|
<<Expressions,_expression_>>
|
|
`]`
|
|
_]_
|
|
|
|
The syntax from the optional `unmatched` to the arrow is called the
|
|
*output endpoint* of the connection.
|
|
The syntax following the arrow is called the
|
|
*input endpoint* of the connection.
|
|
|
|
_pattern-kind_ is one of the following:
|
|
|
|
. `command`
|
|
|
|
. `event`
|
|
|
|
. `health`
|
|
|
|
. `param`
|
|
|
|
. `telemetry`
|
|
|
|
. `text` `event`
|
|
|
|
. `time`
|
|
|
|
_instance-sequence_ is an
|
|
<<Element-Sequences,element sequence>> in
|
|
which each element is a
|
|
<<Scoping-of-Names_Qualified-Identifiers,qualified identifier>>,
|
|
and the terminating punctuation is a comma.
|
|
|
|
==== Semantics
|
|
|
|
*Direct graph specifiers.*
|
|
A direct graph specifier directly specifies a named connection graph.
|
|
|
|
. The identifier following the keyword `connections` names
|
|
the connection graph.
|
|
|
|
. The connection sequence specifies the set of connections in the graph.
|
|
For each connection _C_:
|
|
|
|
.. The optional keyword `unmatched` is allowed only if _C_ is
|
|
<<Definitions_Topology-Definitions_Semantics_Automatic-Numbering-of-Ports,
|
|
match constrained>>.
|
|
In this case, if the keyword `unmatched` is present, then _C_ is
|
|
unmatched.
|
|
|
|
.. For each of the two endpoints _E_ in _C_:
|
|
|
|
... Let _I_ = _Q_ `.` _P_ be the
|
|
<<Instance-Member-Identifiers_Port-Instance-Identifiers,port instance
|
|
identifier>> appearing in _E_.
|
|
|
|
... The port interface instance _Q_ must exist in the enclosing
|
|
topology,
|
|
after
|
|
<<Definitions_Topology-Definitions_Semantics_Resolving-to-a-Partially-Numbered-Topology,
|
|
resolution to a partially numbered topology>>.
|
|
If _Q_ is a component instance, then _E_ is a *component instance endpoint*.
|
|
Otherwise _Q_ is a topology, and _E_ is a *topology endpoint*.
|
|
|
|
... The optional expression _e_ following _I_, if it is present,
|
|
represents a port number, i.e., an index into an
|
|
array of port instances.
|
|
The type of _e_ must be a
|
|
<<Types_Internal-Types_Numeric-Types,numeric type>>, and
|
|
_e_ must
|
|
<<Evaluation,evaluate>> to a compile-time constant
|
|
that becomes a non-negative integer _n_ when
|
|
<<Evaluation_Type-Conversion,converted to>> type _Integer_.
|
|
_n_ must lie in the range [0,2^31^) and must be in bounds for the
|
|
array size of the port instance _P_.
|
|
|
|
.. The arrow represents the direction of the connection (left to right).
|
|
|
|
.. The connection must go from an
|
|
<<Ports_Port-Instances,output port instance>>
|
|
to an
|
|
<<Ports_Port-Instances,input port instance>>.
|
|
|
|
.. The <<Specifiers_Port-Instance-Specifiers,port instance types>>
|
|
specified in the two port instances must be identical,
|
|
except that a `serial` port at either end can be connected
|
|
to any port at the other end.
|
|
|
|
.. If a `serial` port instance _S_ is connected to a typed port
|
|
instance _T_, then the <<Definitions_Port-Definitions,port type>>
|
|
specified in _T_ may not have a return type.
|
|
|
|
*Pattern graph specifiers.*
|
|
A pattern graph specifier indirectly specifies one or more named connection
|
|
graphs
|
|
by specifying a source component instance, a set of target component
|
|
instances, and a pattern for connecting the source instance to each of the
|
|
target instances.
|
|
|
|
. Each topology may contain at most one of each kind of graph pattern.
|
|
|
|
. The qualified identifier following the keyword `instance` must
|
|
<<Scoping-of-Names_Resolution-of-Qualified-Identifiers,refer to>>
|
|
a component instance that exists in the enclosing topology,
|
|
after resolving to a <<Definitions_Topology-Definitions_Semantics,
|
|
partially numbered topology>>.
|
|
|
|
. If the instance sequence _I_ appears, then each qualified identifier
|
|
_Q_ appearing in _I_ must refer to a component instance that exists
|
|
in the enclosing topology, after resolving to a partially numbered topology,
|
|
and each component instance must be valid for the pattern
|
|
(i.e., must have a port of the type required for the pattern).
|
|
The component instances in the sequence name the target component instances for
|
|
the
|
|
pattern. If no component instance sequence appears, then the target component
|
|
instances
|
|
are all component instances specified directly in the enclosing topology (not
|
|
via import)
|
|
that are valid for the pattern.
|
|
|
|
The meaning of specifier depends on the pattern kind, as follows:
|
|
|
|
. `command`: The source component instance _I_ is a command dispatcher.
|
|
The following connection graphs are generated:
|
|
|
|
.. A connection graph named `Command` consisting of all connections
|
|
from the output port of type `Fw::Cmd` of _I_ to the command input port
|
|
of each target component.
|
|
|
|
.. A connection graph named `CommandRegistration` consisting of all
|
|
connections from the command registration output port of
|
|
each target component
|
|
to the command registration input port of _I_.
|
|
|
|
.. A connection graph named `CommandResponse` consisting of all connections
|
|
from the command response output port of each target component
|
|
to the command response input port of _I_.
|
|
|
|
. `event`: The source component instance _I_ is an event logger
|
|
with an input port of type `Fw.Log`.
|
|
The generated connection graph has name `Events` and contains
|
|
all connections for sending events to _I_ through an event
|
|
output port.
|
|
|
|
. `health`: The source component instance _I_ is a health component.
|
|
The generated connection graph has name `Health` and contains
|
|
all connections between the health component and ping
|
|
ports of the target components of type `Svc.Ping`.
|
|
|
|
. `param`: The source component instance _I_ is a parameter database
|
|
component.
|
|
The generate connection graph has name `Parameters`
|
|
and contains all connections for (a) getting
|
|
parameters from the database and (b) saving
|
|
parameters to the database.
|
|
|
|
. `telemetry`: The source component instance _I_ is a telemetry database
|
|
with an input port of type `Fw.Tlm`.
|
|
The generated connection graph has name `Telemetry`
|
|
and contains all connections for sending telemetry to _I_
|
|
through a telemetry output port.
|
|
|
|
. `text event`: The source component instance _I_ is a text event
|
|
logger with an input port of type `Fw.LogText`.
|
|
The generated connection graph has name `TextEvents` and contains
|
|
all connections for sending events to _I_ through an event
|
|
output port.
|
|
|
|
. `time`: The source component instance _I_ is a time component.
|
|
The generated connection graph has name `Time` and contains
|
|
all connections for getting the time from _I_ through
|
|
a time get output port.
|
|
|
|
==== Example
|
|
|
|
Assume the following component instances are available in the enclosing topology,
|
|
and all have command ports:
|
|
|
|
[source,fpp]
|
|
----
|
|
commandDispatcher
|
|
commandSequencer
|
|
engineeringTelemetryLogger
|
|
eventLogger
|
|
telemetryDatabase
|
|
timeSource
|
|
----
|
|
|
|
Here is a pattern graph specifier:
|
|
|
|
[source,fpp]
|
|
----
|
|
command connections instance commandDispatcher
|
|
----
|
|
|
|
It is equivalent to the following direct graph specifiers:
|
|
|
|
[source,fpp]
|
|
----
|
|
connections CommandRegistration {
|
|
commandDispatcher.cmdRegOut -> commandDispatcher.cmdRegIn
|
|
commandSequencer.cmdRegOut -> commandDispatcher.cmdRegIn
|
|
engineeringTelemetryLogger.cmdRegOut -> commandDispatcher.cmdRegIn
|
|
eventLogger.cmdRegOut -> commandDispatcher.cmdRegIn
|
|
telemetryDatabase.cmdRegOut -> commandDispatcher.cmdRegIn
|
|
timeSource.cmdRegOut -> commandDispatcher.cmdRegIn
|
|
}
|
|
|
|
connections Command {
|
|
commandDispatcher.cmdOut -> commandDispatcher.cmdIn
|
|
commandDispatcher.cmdOut -> commandSequencer.cmdIn
|
|
commandDispatcher.cmdOut -> engineeringTelemetryLogger.cmdIn
|
|
commandDispatcher.cmdOut -> eventLogger.cmdIn
|
|
commandDispatcher.cmdOut -> telemetryDatabase.cmdIn
|
|
commandDispatcher.cmdOut -> timeSource.cmdIn
|
|
}
|
|
|
|
connections CommandResponse {
|
|
commandDispatcher.cmdRespOut -> commandDispatcher.cmdRespIn
|
|
commandSequencer.cmdRespOut -> commandDispatcher.cmdRespIn
|
|
engineeringTelemetryLogger.cmdRespOut -> commandDispatcher.cmdRespIn
|
|
eventLogger.cmdRespOut -> commandDispatcher.cmdRespIn
|
|
telemetryDatabase.cmdRespOut -> commandDispatcher.cmdRespIn
|
|
timeSource.cmdRespOut -> commandDispatcher.cmdRespIn
|
|
}
|
|
----
|
|
|
|
See also the <<Definitions_Topology-Definitions_Examples,examples for topology
|
|
definitions>>.
|