Instance Attributes

You can specify distinct arbitrary attributes for each box instance. The attributes can be specified at any level of the hierarchy. They will be inherited downward. Attributes are in the same name-space as the graph parameters: graph-macros and graph-variables. For more information, see Graph-Parameters.

You can assign attributes to an object when editing its properties. You will see a button on the properties dialogue called "Attributes". Clicking it will bring up an edit-window for adding or editing attributes.

Attributes work just like macros. Just type an equation. One attribute per line.

attribute_name = value/expression
Example:
Xproduce = 5
Yconsume = Xrate * 50.1
The macros (accessible under the Edit menu) belong to the top_level diagram, so they will be global or inherited by every object.

A lower level assignment to the same attribute-name will over-ride the upper one.
Example:

                top_level( A=2, B=3 )
                   |
                ---------
                |       |
           Diag_P       Diag_Q ( A=7, C=10 )
             |             |
        ---------       ---------
        |       |       |       |
     Box1    Box2      Box3     Box4( A=100, D=75 )

The attributes of:
   Box1 and Box2 are:  A=2, B=3

   Box3 are:	A=7, B=3, C=10

   Box4 are:	A=100, B=3, C=10, D=75
(Attributes do not have to be set to constants, but rather could be expressions involving other attributes, some of which could be supplied from the same or other levels.)

You can apply the attributes in the DFG-Node and Arc fields, such as the compute_time, arc threshold, consume, produce, init fields.

Accessing Attribute Values within Models:   CSIM_GET_ATTRIBUTE()

Within hardware models, you can access to the attribute values with the CSIM_GET_ATTRIBUTE(char *attribute_name, char *value, int maxstrlen) function. The function takes the attribute_name and returns its value as a character string. The maxstrlen parameter sets a limit on the maximum string length that can be returned, for safety. It should be less than or equal to the size of the character string array you provide for the returned value.
Example:

	{
	 char value[100];

	 CSIM_GET_ATTRIBUTE( "Xproduce", value, 100 );
	 csim_printf("My Xproduce = %s\n", value );

	 CSIM_GET_ATTRIBUTE( "A", value, 100 );
	 if (strlen(value)==0) 
	  { csim_printf("'A' is not set for me.\n");
	  }
	 else
	  {
	   sscanf(value,"%d", &i);
	   csim_printf("My 'A' = %d\n", i );	
	  }

 

Setting Default Node Attributes:

Models may declare their attributes and give them default values by the DEFAULT_ATTRIBUTES(); construct at the top of their device-definition. These attributes will appear as default-attributes in the GUI when editing the properties of the box. They are helpful in letting user's know the available attributes of a model, as well as their nominal values. The attributes will take their default values unless overridden by an instance attribute on the box-instance, or at a higher level of the topology, as described above.
Example:
	DEFINE_DEVICE_TYPE:  processor_A
                 PORT_LIST( IO_PORT, Mem_port );
                 DEFAULT_ATTRIBUTES( clock_rate=360, alpha=7 );
                 .....
You can provide default values for a node's default attributes.
For example:
		DEFAULT_ATTRIBUTES( clk_rate=6e9, overhead=alpha );
The default values for attributes have the lowest order of precedence. The default value of an attribute will be overridden if the attribute is set to another value at any other level (IE. globally, at a higher level of hierarchy, or at the box instance). The attribute will take the default value, only if the attribute is not otherwise assigned in the hierarchy or explicitly on the box instance.

You can provide a list of values that are selectable from the GUI by enclosing them in squiggley ({}) brackets and separating them by spaces.
For example:

		DEFAULT_ATTRIBUTES( clk_rate={2e9 4e9 6e9}, overhead={alpha beta gamma} );
In the above example, opening the properties of an instance of a box with the above default attributes in the GUI, and clicking on the attribute clk_rate, will pop-up a selection list containing the available settings. Selecting one of the choices will set the default attribute of the given box-instance to that value. If the user does not explicitly select any values, and the attribute is not set at a higher level, the the attribute defaults to the first value in the list.

Setting Default Module Attributes:

(This is a new feature. See: Default Module Attributes )


Precedence of Instance Attributes in Hierarchy:

The precedence of macro/variable/attribute symbols is as follows, (in decreasing order of precedence):
  1. Instance-Attribute on Leaf Box.
  2. Instance-Attribute on Module (above leaf box).
  3. Global Macro or Variable.
  4. Default Attribute.
In other words, the Default_Attribute value is at the lowest order of precedence. The default value will be valid only if the given symbol name is not defined at any other level.

Next, if a symbol name is defined as a global macro or variable, it will override any default settings of that symbol name.

Next, if a symbol name is defined as an attribute of a module instance in a hierarchical diagram, its value will override the any settings of that symbol name as a global macro, variable, or any default values for that symbol name.

Finally, if a symbol name is defined as an attribute of a leaf box (not a default-attribute, but an instance-attribute), then its value will override any settings of that symbol name at higher levels of the module hierarchy, as a global macro, variable, or any default values for that symbol name.



Getting Literal Attributes:   CSIM_GET_LITERAL_ATTRIBUTE

The CSIM_GET_ATTRIBUTE() function, described above, will attempt to numerically evaluate the value returned by the attribute. This is often not problematic, as the parser can usually distinguish a purely textual word from numeric expressions. However, the parser may become confused if the value of an attribute is intended as text-string, but contains arithmetic operators such as +-/*(), or contains spaces indicating a missing operand.

To avoid numerically evaluating the results returned from attributes, use the the CSIM_GET_LITERAL_ATTRIBUTE function. CSIM_GET_LITERAL_ATTRIBUTE() accepts and returns the same parameters that CSIM_GET_ATTRIBUTE() does. See above.



Accessing Attributes of Other Objects:   CSIM_lookup_attribute

The routines above access the attributes of the object under which the calling-code is executing. However, you can access the attributes of other objects by the CSIM_lookup_attribute() function.
CSIM_lookup_attribute( name, value, maxlength, attrlst )
Where name is the character-string name of the attribute, and value is a character-string variable to return the contents of the attribute. The fourth parameter is the attribute list of the object. In hardware graphs, the device attributes are held in the global structure: DEVICE_INSTANCE[x].attributes, where x is the logical ID of the device. (The logical device ID is equal to MY_ID within each device.) In Data Flow Graphs, the attributes of each node are held in the structure: thisnode->attributes.

A companion function CSIM_literal_attribute( name, value, maxstrlen, attrlst ) exists, which is similar to CSIM_lookup_attribute, but does not attempt to evaluate the attribute numerically.



Adding / Updating Attributes:   CSIM_add_attribute

You can add or update new attribute values by the CSIM_add_attribute function.
CSIM_add_attribute( &attrlst, name, value )
Where attrlst is the attribute list of the object you wish to update. In hardware graphs, the device attributes are held in the structure: DEVICE_INSTANCE[x].attributes, where x is the logical ID of the device. For example, if a device wishes to update or add a new attribute value to itself, say xyz = 7:
CSIM_add_attribute( &(DEVICE_INSTANCE[MY_ID].attributes), "xyz", "7" );
In Data Flow Graphs, the attributes of each node are held in the structure: thisnode->attributes.

The second parameter, name, is the character-string name of the attribute to set. The third parameter, value is a character-string value to set the attribute to.



Getting Link Attributes:   CSIM_GET_LINK_ATTRIBUTE

Code from within a model box can get the values of the attributes on any links attached to the given box.
CSIM_GET_LINK_ATTRIBUTE( port_name, attribute_name, result_value, maxlen )
The first three arguments are character stings. The first one references the port_name to which the given link is connected on the current box. The second parameter provides the name of the attribute to look for. The third argument is the pre-allocated (or pre-declared) character string which will received the resulting value of the attribute as a character string. The final value is the maximum length of the result value, sometimes called the buffer size.