Chapter 13. Annotating Models
AADL allows you to annotate your model in several ways. You can document your model using comments, you can add information about a model element using properties, and you can annotate classifiers using annex sublanguages. We describe the use of comments and properties in this chapter and introduce annex annotations in the next chapter.
13.1. Documenting Model Elements
AADL offers several ways of documenting components of a system. In previous chapters, you have learned how to use features to specify the interface of components, and properties to record characteristics relevant to analyses. In this section, you will learn about comments, and about the ability to record that you intentionally left a section of a component specification empty.
13.1.1. Comments and Description Properties
You can include comments with any model element. This means you can add comments in either the graphical view or textual representation and they are visible in the other. In the graphical view, you do so by selecting the model element in a graphical editor and fill in the comment field for the model element. In the textual representation, you do so by prefacing the comment with two hyphens (--). All text on that line following these hyphens is treated as a comment. You can place a comment on the same line after a declaration. This is shown in Listing 13-1, where the comment “a thread instance.” is contained on the same line as the thread subcomponent declaration. AADL does not have a special multiline comment symbol. This means that each line containing a comment must have the comment symbol, as shown in the first four lines in Listing 13-1. AADL does not place any restrictions on the formatting of comments.
Listing 13-1. Example Comments in an AADL Model
--
-- The process controller.speed provides the basic
-- speed control functions for the system.
--
process implementation controller.speed
subcomponents
control_laws: thread c_laws.speed; -- a thread instance
end controller.speed;
You can also define a Description property that has a string value and is applicable to all elements of an AADL model. You can then use it to provide additional documentation. You can further provide properties as to the authorship of the component and other relevant documentation.
13.1.2. Empty Component Sections
Component type, component implementation, feature group type, and package declarations consist of several sections that are optional. As you learned earlier, you can partially specify these model elements and later fill in missing sections during refinement. If you want to indicate that a part is intended to be empty, you can use a none statement (none;). This allows a consistency checker to determine whether you accidentally left a part empty. The declarations and the specific sections in which a none statement can be used are summarized in Table 13-1.
Table 13-1. None Statement Options
13.2. Using Properties
Properties define characteristics for the elements that comprise an AADL model. These elements include those declared using AADL standard constructs, such as processors, threads or ports, as well as elements declared as part of an annex such as error states and error events in the Error Model Annex. Each property has a name and a type. Its definition also specifies which model elements the property applies to. A property type establishes the values that can be assigned to a property.
There are AADL standard (predeclared) properties and property types. Collectively, these standard properties and property types encompass common attributes for the elements of the language. For example, a standard property of a port is Required_Connection, which is of standard type aadlboolean and has a value of true or false. Its default value is true. However, you can use a property association to assign the value false to this property for a port, allowing that port to be unconnected. The predeclared properties are organized into a collection of property sets and can be referenced without identifying the property set name.
The predeclared properties of the AADL standard are organized into the following property sets:
• Thread_Properties related to tasks and their interfaces
• Timing_Properties related to task execution and communication timing
• Memory_Properties related to the use of memory as storage and data access
• Programming_Properties related to mapping application components to source code
• Deployment_Properties related to the binding of application software to computer hardware
• Modeling_Properties related to the model itself
The AADL also permits users to define additional properties, property types, and property constants through additional property sets. The language constructs for doing so are discussed in Chapter 14. Property sets have been introduced as part of Annex standard documents. For example, the Error Model Annex standard [EAnnex] defines a property to specify the probability of occurrence of faults. Similarly, the Data Modeling Annex standard [DAnnex] defines properties for data components to characterize relevant aspects of data models (e.g., base types, type constructors such as record or array, or measurement units). The data model itself may exist in a data modeling language such as UML class diagrams, ASN.1, or in data types of programming languages. Other property sets are introduced with analysis tools in support of certain system analyses. For example, to support a security analysis plug-in to the OSATE toolset the Software Engineering Institute has introduced a collection of properties to specify security levels, categories of documents with different security requirements, and policies for handling declassification [Hansson 08].
13.2.1. Assigning Property Values
You assign values to properties and associate them with model elements through property associations. A basic property association consists of a property name, an assignment (association) operator, an optional constant keyword, and the value or list of values to be assigned to the property. The template for a basic property association declaration is shown in the following box.
<property name> => [constant] <property value>;
For predeclared properties you can just use the property name. For other properties you must include the name of the property set in which you defined the property (for example, Property_Set_Name::property). The property value can be a single value whose type must match the type specified by the property definition, or it can be a list of values of the same type if the property has been defined to accept such a list. The list of values is a comma-separated list placed in parentheses.
With the constant keyword, you indicate that the property value assigned through this property association cannot be changed. For example, when you declare a property association of Period => constant 20 ms for a thread type, it becomes the Period value for all instances of this thread type, and it cannot be changed by a thread implementation, subcomponent, or specific instance of this type. If the property association is declared without the constant keyword, you can assign a different value for different implementations of this thread type, or even different values for different instances. For more on how property values are determined, see Section 13.2.3.
A few basic example property associations are shown in Table 13-2.
Table 13-2. Basic Property Association Examples
In the case of properties that accept lists of values you can specify a single value without placing it within parentheses. For such properties you can also append values to a previously assigned list of values. You do this with the operator +=>. For example, you may have specified a list of C header files for a process type with the Source_Text property. You can add C implementation files to each of the process implementations that contain the respective source code.
You can also assign property values that only hold under certain conditions. For example, you can assign different execution time values for a thread when it executes under different modes. You do this by constraining the value with an in modes statement as shown in Table 13-3.
Table 13-3. More Property Association Examples
You can also assign property values to software components that only hold when the component is involved in binding to a particular hardware component. For example, you can assign different execution times to a thread depending on whether it is bound to one type of processor or a different type of processor by using the in binding statement. An example is shown in Table 13-3.
13.2.2. AADL Property Types and Values
Each property has a type that defines the specific values that can be assigned to the property. The various values that can be assigned to properties and example property associations for those types are summarized in Table 13-4.
Table 13-4. A Summary of Property Values
The numeric values of integer and real or their ranges must be specified with a unit if the property definition states that the property requires a unit.
The range of integer or real values represents closed intervals of numbers that includes a lower bound of the interval, an upper bound of the interval, and (optionally) a delta indicating the difference between adjacent values. The delta may be unspecified as shown in Table 13-4.
Property constants provide a simple way of parameterizing the values assigned to properties in different parts of a model. Constants can be used anywhere a value of the same type is expected. For example, the property associations in Listing 13-2 assign values to the Period and PBA::Max_Control_Dimensions properties of the thread algorithm.impl. In the property set timing, the property HiRate is defined as a constant of the type Time with a value of 5ms. Time is a standard property type whose values are integers with time units. A change in the period of all instances of this thread type (as well as any other thread type with the same property association) can be accomplished simply by changing the value of HiRate in the property set. Similarly, you can parameterize the value of an integer property PBA::Max_Control_Dimensions with the integer constant Max_Size. Please note that property constants cannot be defined for reference value or classifier values.
Listing 13-2. Property Associations That Reference a Property Constant
thread implementation algorithm.impl
properties
Period => timing::HiRate;
PBA::Max_Control_Dimensions => PBA::Max_Size;
end algorithm.impl;
--
property set timing is
HiRate: constant Time => 5 ms;
end timing;
property set PBA is
Max_Control_Dimensions: aadlinteger applies to (all);
Max_Size constant aadlinteger => 5;
end PBA;
Property values that are reference values refer to specific instances of model elements using the containment hierarchy. You specify the path of the reference relative to the location at which the property association is declared. You have seen the use of reference values in software to hardware binding declarations such as Actual_Processor_Binding.
The property type computed allows you to specify that the value of a property is determined by invocation of a user defined function whose parameter is the model element for which the property values is retrieved. This function, available in a source code library to the tool environment, can for example calculate the value of the property for a component by summing up its subcomponent property values. In the example of Table 13-4 the function is assumed to add up the net mass of all subcomponents and the component itself to determine its gross mass.
13.2.3. Determining a Property Value
AADL has rules for determining the property value of a model element. For example, if you associate a Period property value of 20ms with a thread type, all instances of this type have this property value. In this section, you will learn what these rules are.
A property value for a model element is determined according to the following rules (in order):
• According to the highest contained property association in the hierarchy (see Section 13.2.4); if not present then
• According to basic property associations; if not present then
• By inheritance from enclosing components if the property is defined as inherit; if not present then
• The default value specified as part of the property definition; if not present then the value is considered to be undefined.
You can declare basic property associations in the properties section of component types, component implementations, feature group types, and packages. You can also declare basic property associations as part of declarations of subcomponents, features, and other elements inside component types and implementations, and feature group types by placing them in curly brackets.
The property value of an instance model element is determined by the property value of the subcomponent, connection, feature, flow specification, end-to-end flow, mode, or mode transition that has been instantiated. Table 13-5 defines the rules for determining these property values. If no property value is found according to this table, the inheritance and default value rules are used.
Table 13-5. Summary of Property Determination Rules
13.2.4. Contained Property Associations
Contained property associations provide a way of attaching property values to model elements within the hierarchy of a model instance. You do this by declaring the property association at a higher level of the model and indicate a path to the model element to which the property value belongs. The applies to statement allows you to specify multiple paths in a comma-separated list as shown in the following box:
<property name> => <property value> applies to <path>
( , <path )*;
You can declare contained property associations at any level of the model hierarchy. If more than one contained property association attaches a property value to a model element, the contained property association declared at the highest level of the hierarchy takes precedence.
With contained property associations, you can define configuration parameters for a system at a single point (e.g., at the highest point possible in the component hierarchy). In that way, the parameters are in a centralized location for elements of a model and you can readily identify, adjust, and review them. This central location can be used even for elements that are deeply nested within a component. In Section 11.2.1 you used contained property associations when specifying deployment configurations as bindings of software components to hardware components.
Contained property associations are required when a property value involves a reference to another part of a model. In these associations, the property value that is assigned to the property is a reference to an element within the model. For example, the binding property of a thread must reference (identify) the processor to which it is bound. To accomplish this, the property association must be declared as contained property association attached to a model component that is the common parent of the component being referenced and the component to which the property value belongs.
13.2.5. Determining the Property Value: An Example
Listing 13-3 shows an example with contained property associations as well as basic property associations. Two contained property associations are declared within the system implementation cc_complete.impl. In the first association, the computation time for the compute entry point of the subcomponent thread control_algorithm is assigned the range of 2 ms..5 ms. The thread control_algorithm is contained within the process control_laws that is a subcomponent of the system cruise_control. In the second association, the Required_Connection property is assigned the value false for the out data port out_port of the thread adjust, which is contained in the control_laws instance of process implementation control.impl. The process control has a contained property association for the Required_Connection property that applies to one of its own ports. The Period property is declared for the system cruise_control with the value 20ms. Since it is an inheritable property this value is the default for all threads that do not have their own property association. In the case of the adjust thread the Period property value is 10ms because the subcomponent declaration for this thread includes a property association. The graphical representation shown in the lower portion of that table highlights the assignment of property values relating to the thread subcomponents adjust and control_algorithms.
Listing 13-3. Contained Property Associations
system cc_complete
end cc_complete;
--
system implementation cc_complete.impl
subcomponents
brake_pedal: device brake_pedal;
cruise_control: system cruise_control.impl;
throttle_actuator: device throttle_actuator;
connections
C1: port brake_pedal.brake_event -> cruise_control.brake_event;
C2: port cruise_control.throttle_setting -> throttle_actuator.throttle_setting;
properties
Compute_Execution_Time => 2 ms..5 ms applies to
cruise_control.control_laws.control_algorithm;
Required_Connection => false applies to
cruise_control.control_laws.adjust.out_port;
end cc_complete.impl;
--
system cruise_control
features
brake_event: in event data port;
throttle_setting: out data port;
properties
Period => 20ms;
end cruise_control;
--
system implementation cruise_control.impl
subcomponents
data_in: process interface;
control_laws: process control.impl;
connections
C1: port brake_event -> data_in.brake_event;
C3: port data_in.out_port -> control_laws.in_port;
C5: port control_laws.out_port -> throttle_setting;
end cruise_control.impl;
--
process control
features
in_port: in data port ;
out_port: out data port ;
properties
Required_Connection => false applies to out_port;
end control;
--
process implementation control.impl
subcomponents
adjust: thread adjust_sensor_value.impl {Period => 10 ms;};
control_algorithm: thread algorithm.impl;
end control.impl;
--
thread adjust_sensor_value
features
in_port: in data port;
out_port: out data port;
end adjust_sensor_value;
--
thread implementation adjust_sensor_value.impl
end adjust_sensor_value.impl;
--
thread algorithm
features
in_port: in data port;
out_port: out data port;
end algorithm;
--
thread implementation algorithm.impl
end algorithm.impl;
