Previous - Up - Next

2.5   Configuration Attributes

A Simics configuration consists of a machine description and a few other parts, and it is divided into a number of configuration objects. Each device instance in the configuration is represented by such an object. Any Simics configuration object has a number of attributes. An attribute is a named property that can be read or written using the Simics API. The value of an attribute can be an integer, a floating-point number, a string, an object reference, a boolean value, a list of values, or a mapping from values to other values.

Attributes are used for several related purposes, but the most important uses are for configuration and checkpointing. All the internal state of a device object must be available through the attributes, so that a checkpoint of the current state can be saved by reading all the attributes and storing the values to disk. By reloading a configuration and setting all attributes from the previously saved checkpoint, the states of all devices can be restored to the checkpointed state and simulation can continue as if it had never been interrupted. When creating a new configuration, some of the state must be given an explicit initial assignment, which makes those attributes also part of the configuration. There may also be attributes that are not part of the state, in the sense that they don't change during simulation. Instead, they control the behavior of the model, such as buffer sizes, timing parameters etc. Those configuration attributes can generally not be modified once the object has been created.

Attributes can also be used as a simple interface to an object, e.g., for inspecting or manipulating the state for debugging purposes.

A DML device model usually defines a number of attributes. By default, each register defines a corresponding attribute that can be used to get or set the register value, but more attributes can be defined by explicitly declaring them in the DML source. In our example above, for the register r0 of bank b there will be a device attribute named b_r0 (note the underscore).

2.5.1   Using Register Attributes

The get and set methods of a register are different from its read and write methods in that they do not simulate a hardware access (which often triggers side-effects in devices). Instead, they offer a direct way of reading or modifying the value of the register.

We can access the attribute from the Simics command line. Continuing our example from the previous sections, enter:

  simics> dev1->b_r0 = 17

  simics> dev1->b_r0

However, if we make a new memory access, as before:

  simics> phys_mem.get 0x1000

The answer is of course that we had hard-coded the read method to always return 42, no matter what. But this does not affect the behavior of get and set, or the write method. Let's try to make a write access:

  simics> phys_mem.set 0x1000 0xff

    result = 42;

    result = $this;

It is in fact often useful to create registers which either return a constant (usually zero), or return a value that is computed on the fly. For such registers, it is unnecessary to allocate memory for storing the value inbetween calls. The allocation can be turned off by adding the following line to the body of the register:

    parameter allocate = false;

A full implementation of such a "synthetic" constant register could contain method definitions like the following:

    method write(value) {
        /* do nothing */
    }
    method get -> (value) {
        value = 42;
    }
    method set(value) {
        if (value != 42)
            throw;
    }

The standard library file utility.dml contains several pre-defined templates for common implementations such as this. To use it, add the declaration "import "utility.dml";" to your source file. The constant register can now simply be implemented as follows:

      register r0 size 4 @0x0000 is (constant) {
          parameter value = 42;
      }

      register r0 size 4 @0x0000 is (constant) {
          parameter value = 42;
          method read() -> (result) {
              log "info", 1, 0: "Hello, bus!";
              result = $value;
          }
      }

2.5.2   User-defined Attributes

It is sometimes useful to have device attributes that are not associated with any register. If we just want the attribute to behave as a data field, which stores a value of a simple data type such as int32 or bool, we only have to specify the parameter allocate_type, as follows:

    attribute foo "an integer attribute" {
        parameter allocate_type = "int32";
    }

  simics> help attribute:dev1.foo

You can now experiment with setting and getting the value of the attribute; e.g., entering

  simics> dev1->foo = 4711
  simics> dev1->foo

If it is important that other parts of the device are updated whenever the value of the attribute is modified, the method after_set can be overridden to perform such updates. (By default, it does nothing.) For example:

    method after_set {
        log "info": "Someone updated the attribute!";
    }

If you want the attribute to do things differently, such as not store the value between calls, or use a more complex data type, you need to do more work on your own, instead of using the allocate_type parameter; see the DML Reference Manual for details.

Previous - Up - Next