ANML Documentation

Macro Definition

A macro definition defines the content of a macro and its interface. The definition may contain instances of other macros, enabling the support of hierarchical macro designs. A macro definition cannot contain another macro definition.

A macro definition is comprised of four required attributes and three optional attributes.

Required attributes:

  • ID
  • name
  • header
  • body

Optional attributes:

  • description
  • port declarations
  • parameter declarations
Figure 1. Macro Definition
Railroad macro definition

ID Attribute

The ID attribute is a user-defined unique identifier (name) for the macro. The ID attribute must start with a character, but can then contain other characters, digits, or underscore symbols.

Name Attribute

The name attribute is a user-defined name (label) for identifying the macro. The name is only for a designer's benefit; it is not used by other elements in the network.

Header Attribute

The header attribute describes the macro’s interface, essentially describing how the macro is to be used. The header should contain information that will assist the user of the macro with understanding the macro's function and how to connect to its interface.

Figure 2. Header Attribute
Railroad macro header

A macro contains two categories of information that define the connections and parameters associated with the macro:

  • Port declarations

    Statements that describe how outside entities may connect to the macro, containing three types of connections: in, out, and report.

  • Parameter declarations

    Placeholders for values that may be assigned to the macro when it is instantiated.

Port Declarations

Figure 3. Port Declarations Header
Railroad port declarations

Port Declaration Types

  • inReceives an activation input and connects that activation signal to a resource within the macro. An in statement must be connected to a resource within the body of the macro; unconnected in ports are not allowed.
  • out The inverse of an in port. It connects an activation signal from within the macro to the outside world (elements outside of the macro).
  • report Provides an optional way to attach identifiers to reporting elements within the macro. Also provides a way to group similar reporting elements together.

Parameter Declarations

Parameters provide a way of generalizing a macro. Parameters are placeholders for actual values specified when a macro instance is created in a design. Parameters must be assigned default values. If a macro instantiation does not assign a parameter value, the default value will be used.

Figure 4. Parameter Declarations Header
Railroad macro parameter declarations

Items that may be parameterized:

  • STE symbol sets
  • Counter target values

Parameters must be prefixed with a percent sign (for example, %a, %target_count, %match_string, and so on). For example: a macro may contain a counter with its target count set to the parameter %tcount with a default of 15. When instantiated, the user could leave the %tcount value unassigned, in which the default value of 15 will be used. Another macro reference could be created and it could assign the value of 10 as the value assigned to %tcount. In this case, the 10 would override the default value of 15.

At the time of this writing, parameter expressions are not supported. That means, if a parameter substitution is desired, the parameter expression cannot contain any extraneous characters. For example, a user may try to enter a range expression using the parameter %a as "%a-z". This will not behave as expected. The compiler will not treat %a in this context as a parameter, but rather as the literal characters "%" followed by the range "a-z".

Body Attribute

The body attribute contains the resources and connections that comprise the content of the macro as well as the statements that connect those macro resources to the interface connections declared in the header.

The body attribute can be either plain text (specified with <body>) or binary encoding (specified with <bond-binary>). Binary encodings are created using specific API calls to the Automata Processor SDK. They exist for the purpose of obfuscating macros (and, in some cases, facilitating faster design compilations). This allows a macro to be shared without revealing the details of its implementation.

Figure 5. Body Attribute
Railroad macro body

Port Definitions

A port definition associates an element with a port declared in the port declarations section of the header attribute. Just as there are three different port declaration types, there are three different port definition types. A port definition must be associated with a port declaration of the same type.

  • port-in An input port that receives an activation signal from the outside of the macro. The port-in contains an ID followed by at least one, but possibly many, activate-on-event statements. Each activate-on-event statement connects the activation signal for this port with a different resource within the macro body.
  • port-out Connects an activation signal from within the macro to other elements within the automata network outside this macro definition. The port-out must be associated with one and only one resource within the macro. This is done by specifying the driving resource in the activate-from-event element ID.
  • report-alias Provides a way to determine which specific resource within the macro generated a report event. One or more resource IDs from within the macro can be associated with a report-alias ID. If a report alias is specified, it must be associated with at least one resource within the macro.

Macro Connections

After defining a port definition, define the content of the macro by adding various network elements or references to other macro instances, just as when constructing an automata network.