SIM_alloc_attr_dict — create empty attribute dictionary
#include <simics/device-api.h> // in C
// always available in DML
attr_value_t
SIM_alloc_attr_dict(unsigned length);
Returns an attr_value_t of type dict with size len. The dictionary elements are initialized to invalid values.
All contexts (including Threaded Context)
SIM_alloc_attr_list — create uninitialized attribute list
#include <simics/device-api.h> // in C
// always available in DML
attr_value_t
SIM_alloc_attr_list(unsigned length);
Returns an attr_value_t of type list with size length. The list elements are initialized to invalid values.
All contexts (including Threaded Context)
SIM_attr_copy — copy attribute value
#include <simics/device-api.h> // in C
// always available in DML
attr_value_t
SIM_attr_copy(attr_value_t val);
Return a deep copy of val. The caller obtains ownership of the copy and needs to free it after use; the argument is not modified.
This function is not available from Python.
All contexts (including Threaded Context)
SIM_attr_dict_resize — resize dict attribute value
#include <simics/device-api.h> // in C
// always available in DML
void
SIM_attr_dict_resize(attr_value_t *NOTNULL attr, unsigned newsize);
Resize attr, which must be of dict type, to newsize elements. New elements are marked invalid. Dropped elements are freed.
Cell Context
SIM_attr_dict_set_item — set dict attribute element
#include <simics/device-api.h> // in C
// always available in DML
void
SIM_attr_dict_set_item(attr_value_t *NOTNULL attr, unsigned index,
attr_value_t key, attr_value_t value);
Set the element numbered index of the dict attr to key and value. The previous key and value at that position are freed. The ownership for key and value is transferred from the caller to attr. The key must be of integer, string or object type.
Cell Context
SIM_attr_free, SIM_free_attribute — free attribute
#include <simics/device-api.h> // in C
// always available in DML
void
SIM_attr_free(attr_value_t *NOTNULL value);
void
SIM_free_attribute(attr_value_t value);
Free the memory allocation used by the value pointed to by value. For values of list or dict type, this recursively frees all contents; for string or data values, the allocation containing the payload is freed. It is an error to use the value or any sub-part of it after it has been freed.
SIM_attr_free is the preferred call because it changes the type of the argument variable to Invalid, preventing accidental use after freeing. SIM_free_attribute only differs in how the argument is passed, but cannot change the argument variable as it is passed by value.
These functions are not available in Python; memory allocation is managed automatically there.
All contexts (including Threaded Context)
SIM_attr_integer, SIM_attr_boolean, SIM_attr_string, SIM_attr_string_detach, SIM_attr_floating, SIM_attr_object, SIM_attr_object_or_nil, SIM_attr_data_size, SIM_attr_data, SIM_attr_list_size, SIM_attr_list_item, SIM_attr_list, SIM_attr_dict_size, SIM_attr_dict_key, SIM_attr_dict_value — extract values stored in attr_value_t values
#include <simics/device-api.h> // in C
// always available in DML
FORCE_INLINE int64
SIM_attr_integer(attr_value_t attr);
FORCE_INLINE bool
SIM_attr_boolean(attr_value_t attr);
FORCE_INLINE const char *
SIM_attr_string(attr_value_t attr);
FORCE_INLINE char *
SIM_attr_string_detach(attr_value_t *attr);
FORCE_INLINE double
SIM_attr_floating(attr_value_t attr);
FORCE_INLINE conf_object_t *
SIM_attr_object(attr_value_t attr);
FORCE_INLINE conf_object_t *
SIM_attr_object_or_nil(attr_value_t attr);
FORCE_INLINE unsigned
SIM_attr_data_size(attr_value_t attr);
FORCE_INLINE const uint8 *
SIM_attr_data(attr_value_t attr);
FORCE_INLINE unsigned
SIM_attr_list_size(attr_value_t attr);
FORCE_INLINE attr_value_t
SIM_attr_list_item(attr_value_t attr, unsigned index);
FORCE_INLINE attr_value_t *
SIM_attr_list(attr_value_t attr);
FORCE_INLINE unsigned
SIM_attr_dict_size(attr_value_t attr);
FORCE_INLINE attr_value_t
SIM_attr_dict_key(attr_value_t attr, unsigned index);
FORCE_INLINE attr_value_t
SIM_attr_dict_value(attr_value_t attr, unsigned index);
Extract a value encapsulated in attr. It is an error to call an accessor function with an attr of the wrong type.
SIM_attr_integer returns the integer attribute value modulo-reduced to the interval [-2**63,2**(63-1)]. (Converting the return value to uint64 gives the integer attribute value modulo-reduced to [0,2**(64-1)].)
SIM_attr_string, SIM_attr_data and SIM_attr_list return values owned by attr. Ownership is not transferred to the caller.
SIM_attr_string_detach returns the string in attr and changes the value pointed to by attr into a nil attribute. Ownership of the string is transferred to the caller.
SIM_attr_object_or_nil accepts an attr parameter of either object or nil type. In case of a nil attribute, the function returns NULL.
SIM_attr_list_size and SIM_attr_dict_size return the number of items in the list and key-value pairs in the dict respectively. SIM_attr_data_size returns the number of bytes in the data value.
SIM_attr_list_item returns the item at index. The index must be less than the number of items in the list. The item returned is still owned by attr. Ownership is not transferred to the caller.
SIM_attr_list returns a pointer directly into the internal array of the attribute value; it is mainly present as an optimisation. Use SIM_attr_list_item and SIM_attr_list_set_item for type-safety instead.
SIM_attr_dict_key and SIM_attr_dict_value return the key and value at index. The index must be less than the number of items in the dict. The value returned is still owned by attr. Ownership is not transferred to the caller.
All contexts (including Threaded Context)
SIM_attr_is_nil, SIM_attr_is_int64, SIM_attr_is_uint64, SIM_attr_is_integer, SIM_attr_is_boolean, SIM_attr_is_string, SIM_attr_is_floating, SIM_attr_is_object, SIM_attr_is_invalid, SIM_attr_is_data, SIM_attr_is_list, SIM_attr_is_dict — attr_value_t type predicates
#include <simics/device-api.h> // in C
// always available in DML
FORCE_INLINE bool
SIM_attr_is_nil(attr_value_t attr);
FORCE_INLINE bool
SIM_attr_is_int64(attr_value_t attr);
FORCE_INLINE bool
SIM_attr_is_uint64(attr_value_t attr);
FORCE_INLINE bool
SIM_attr_is_integer(attr_value_t attr);
FORCE_INLINE bool
SIM_attr_is_boolean(attr_value_t attr);
FORCE_INLINE bool
SIM_attr_is_string(attr_value_t attr);
FORCE_INLINE bool
SIM_attr_is_floating(attr_value_t attr);
FORCE_INLINE bool
SIM_attr_is_object(attr_value_t attr);
FORCE_INLINE bool
SIM_attr_is_invalid(attr_value_t attr);
FORCE_INLINE bool
SIM_attr_is_data(attr_value_t attr);
FORCE_INLINE bool
SIM_attr_is_list(attr_value_t attr);
FORCE_INLINE bool
SIM_attr_is_dict(attr_value_t attr);
Indicates whether the value stored in attr is of the specified type. SIM_attr_is_int64 and SIM_attr_is_uint64 additionally test whether the integer value would fit in the given C type.
Cell Context
SIM_attr_list_resize — resize list attribute value
#include <simics/device-api.h> // in C
// always available in DML
void
SIM_attr_list_resize(attr_value_t *NOTNULL attr, unsigned newsize);
Resize attr, which must be of list type, to newsize elements. New elements are set to invalid value. Dropped elements are freed.
Cell Context
SIM_attr_list_set_item — set list attribute element
#include <simics/device-api.h> // in C
// always available in DML
void
SIM_attr_list_set_item(attr_value_t *NOTNULL attr, unsigned index,
attr_value_t elem);
Set the element numbered index of the list attr to elem. The previous value at that position is freed. The ownership for elem is transferred from the caller to attr.
Cell Context
SIM_attr_scanf, SIM_ascanf — parse list attribute values
#include <simics/device-api.h> // in C
// always available in DML
bool
SIM_attr_scanf(attr_value_t *NOTNULL list, const char *NOTNULL fmt, ...);
bool
SIM_ascanf(attr_value_t *NOTNULL list,
const char *NOTNULL fmt, ...) __attribute__((alias("SIM_attr_scanf")));
Reads and converts entries in list according to the format string fmt. Returns true if all elements were successfully converted, false otherwise.
The characters in the format string mean:
| format char | argument type | element must be |
|---|---|---|
i | int64 * | integer |
b | int * | boolean |
f | double * | floating |
s | const char ** | string |
S | const char ** | string or nil |
o | conf_object_t ** | object |
O | conf_object_t ** | object or nil |
l | attr_value_t ** | list |
d | attr_value_t ** | data |
a | attr_value_t ** | any except invalid |
The fmt string may also include a period (.) at the end, taken to mean that more elements may follow. If the period is not present, the length of the list must equal the number of specified elements.
Converted values of type attr_value_t * and const char * are still owned by list.
SIM_ascanf is an alias of SIM_attr_scanf and will be deprecated.
All contexts (including Threaded Context)
SIM_make_attr_boolean — make boolean attribute
#include <simics/device-api.h> // in C
// always available in DML
FORCE_INLINE attr_value_t
SIM_make_attr_boolean(bool b);
Returns an attr_value_t of boolean type.
Cell Context
SIM_make_attr_data, SIM_make_attr_data_adopt — create raw data attribute
#include <simics/device-api.h> // in C
// always available in DML
attr_value_t
SIM_make_attr_data(size_t size, const void *data);
FORCE_INLINE attr_value_t
SIM_make_attr_data_adopt(size_t size, void *data);
Returns an attr_value_t of type data using size and data for the binary data. The maximum size of the binary data is 2**32-1 bytes, i.e. size should fit into a 32-bit unsigned integer.
SIM_make_attr_data will make a copy of the argument data.
SIM_make_attr_data_adopt is mainly provided for compatibility; it will assume ownership of the argument data, which must have been allocated using one of the MM_MALLOC functions.
All contexts (including Threaded Context)
SIM_make_attr_floating — make floating point attribute
#include <simics/device-api.h> // in C
// always available in DML
FORCE_INLINE attr_value_t
SIM_make_attr_floating(double d);
Returns an attr_value_t of floating type with value d.
Cell Context
SIM_make_attr_uint64, SIM_make_attr_int64 — make integer attribute
#include <simics/device-api.h> // in C
// always available in DML
FORCE_INLINE attr_value_t
SIM_make_attr_uint64(uint64 i);
FORCE_INLINE attr_value_t
SIM_make_attr_int64(int64 i);
Returns an attr_value_t of integer type with value i.
Cell Context
SIM_make_attr_invalid — make invalid attribute
#include <simics/device-api.h> // in C
// always available in DML
FORCE_INLINE attr_value_t
SIM_make_attr_invalid(void);
Returns an attr_value_t of invalid type.
Cell Context
SIM_make_attr_list, SIM_make_attr_list_vararg — make list attribute
#include <simics/device-api.h> // in C
// always available in DML
attr_value_t
SIM_make_attr_list(unsigned length, ...);
// not available in DML
attr_value_t
SIM_make_attr_list_vararg(unsigned length, va_list va);
Returns an attr_value_t of type list with size length. The list is filled with data from the arguments following, which should be of type attr_value_t.
This function must be called with exactly length+1 arguments. The attribute parameters should all be valid attributes; e.g., attributes of invalid type are not allowed. The length argument must be a constant expression.
The newly created list assumes ownership of the passed parameters, which therefore should not be freed.
All contexts (including Threaded Context)
SIM_make_attr_nil — make nil attribute
#include <simics/device-api.h> // in C
// always available in DML
FORCE_INLINE attr_value_t
SIM_make_attr_nil(void);
Returns an attr_value_t of type nil.
Cell Context
SIM_make_attr_object — make object attribute
#include <simics/device-api.h> // in C
// always available in DML
FORCE_INLINE attr_value_t
SIM_make_attr_object(conf_object_t *obj);
Returns an attr_value_t of object type with value obj. Returns a nil value if obj is NULL.
Cell Context
SIM_make_attr_string, SIM_make_attr_string_adopt — make string attribute
#include <simics/device-api.h> // in C
// always available in DML
attr_value_t
SIM_make_attr_string(const char *str);
FORCE_INLINE attr_value_t
SIM_make_attr_string_adopt(char *str);
Returns an attr_value_t of type string with value str. Returns Nil if str is NULL.
SIM_make_attr_string will make a copy of the argument string.
SIM_make_attr_string_adopt is mainly provided for compatibility; it will assume ownership of the argument string, which must have been allocated using one the MM_MALLOC functions.
All contexts (including Threaded Context)