SIM_ASSERT_CELL_CONTEXT — assert Cell Context
#include <simics/device-api.h> // in C
// not available in DML
SIM_ASSERT_CELL_CONTEXT(obj);
The SIM_ASSERT_CELL_CONTEXT function verifies that cell thread domain associated with obj is held by the calling thread and raises a hard failure if this is not the case.
In other worlds, the macro ensures that the execution context is either Cell Context or Global Context.
SIM_ASSERT_OBJECT_LOCK — assert thread domain is held
#include <simics/device-api.h> // in C
// not available in DML
SIM_ASSERT_OBJECT_LOCK(obj);
The SIM_ASSERT_OBJECT_LOCK function checks that the thread domain associated with obj is held. A hard failure is raised if the thread domain is not held.
SIM_acquire_cell, SIM_release_cell, SIM_ACQUIRE_CELL, SIM_RELEASE_CELL — enter Cell Context
#include <simics/device-api.h> // in C
// always available in DML
domain_lock_t *
SIM_acquire_cell(conf_object_t *NOTNULL obj,
const char *NOTNULL function_name,
const char *NOTNULL source_location);
void
SIM_release_cell(conf_object_t *NOTNULL obj, domain_lock_t *lock);
// not available in DML
SIM_ACQUIRE_CELL(obj, lockp);
SIM_RELEASE_CELL(obj, lockp);
import simics
simics.SIM_acquire_cell(...)
simics.SIM_release_cell(...)
Enters Cell Context for the cell associated with the object obj.
As part of entering Cell Context, the cell thread domain for the cell associated with obj is acquired.
Entering Cell Context multiple times is allowed, but acquired thread domains must be released in strict reverse order.
This function will block until the cell is available if another thread is currently holding the cell thread domain. While blocking, any previously held domains can be acquired by the thread already in Cell Context. Thus, the caller must be prepared to handle e.g. incoming interface calls.
In Cell Context, API functions marked with Cell Context or Global Context can be called safely, and interfaces on objects belonging to the same cell can be called directly. More generally, the full Standard Device Model applies in Cell Context. Refer to the chapter about threading in the API Reference Manual for more details.
The macro version of this API call, SIM_ACQUIRE_CELL, sets the function_name and source_location arguments automatically with the information where the API call was made. This data is used when lock statistics collection is enabled through the enable-object-lock-stats command.
SIM_acquire_cell returns a domain lock handle which should be passed as an argument to SIM_release_cell when the lock is released. SIM_ACQUIRE_CELL does not return anything but instead stores the domain lock handle in the pointer passed as the second argument.
Any
SIM_acquire_object, SIM_release_object, SIM_ACQUIRE_OBJECT, SIM_RELEASE_OBJECT — acquire thread domain
#include <simics/device-api.h> // in C
// always available in DML
domain_lock_t *
SIM_acquire_object(conf_object_t *NOTNULL obj,
const char *NOTNULL function_name,
const char *NOTNULL source_location);
void
SIM_release_object(conf_object_t *NOTNULL obj, domain_lock_t *lock);
// not available in DML
SIM_ACQUIRE_OBJECT(obj, lockp);
SIM_RELEASE_OBJECT(obj, lockp);
import simics
simics.SIM_acquire_object(...)
simics.SIM_release_object(...)
Acquires the thread domain associated with the object obj.
A particular thread domain can only be held by a single thread at a time, and this function blocks until the domain is available. Once the domain is held, the thread can safely access state protected by the domain.
While blocking, any previously held domains can be acquired by threads with higher priority, such as a thread running in Cell Context.
More than one thread domain can be held simultaneously, and the same thread domain may be acquired multiple times. However, domains must be released in strict reverse order.
This function is typically used by models using the Threaded Device Model to acquire the model’s own thread domain from its interface methods. In this case, obj is set to the model itself.
The macro version of this API call, SIM_ACQUIRE_OBJECT, sets the function_name and source_location arguments automatically with the information where the API call was made. This data is used when lock statistics collection is enabled through the enable-object-lock-stats command.
More details about thread domains and the threading model are available in the chapter about threading in the API Reference Manual.
SIM_acquire_object returns a domain lock handle which should be passed as an argument to SIM_release_object when the lock is released. SIM_ACQUIRE_OBJECT does not return anything but instead stores the domain lock handle in the pointer passed as the second argument.
Any
SIM_acquire_object_for_execution — acquire object lock for execution
#include <simics/device-api.h> // in C
// always available in DML
domain_lock_t *
SIM_acquire_object_for_execution(conf_object_t *NOTNULL obj);
import simics
simics.SIM_acquire_object_for_execution(...)
Acquire the thread domain lock associated with object arg.
This API function is considered tech-preview and may change without notice.
Domain lock handle which should be passed as an argument to SIM_release_object when the lock is released.
Any
SIM_acquire_target, SIM_release_target, SIM_ACQUIRE_TARGET, SIM_RELEASE_TARGET — conditionally enter Cell Context
#include <simics/device-api.h> // in C
// always available in DML
domain_lock_t *
SIM_acquire_target(conf_object_t *NOTNULL obj,
const char *NOTNULL function_name,
const char *NOTNULL source_location);
void
SIM_release_target(conf_object_t *NOTNULL obj, domain_lock_t *lock);
// not available in DML
SIM_ACQUIRE_TARGET(obj, lockp);
SIM_RELEASE_TARGET(obj, lockp);
import simics
simics.SIM_acquire_target(...)
simics.SIM_release_target(...)
Enters Cell Context if the specified object obj uses the Standard Device Model. The function does nothing if obj is a thread-aware object, i.e., if the object belongs to a thread-domain other than the cell.
The intended use for this function is ensuring that Cell Context is entered before a code running in Threaded Context invokes an interface on some external object. If the external object is thread aware, and does not require Cell Context, this function avoids entering Cell Context as an optimization.
The macro version of this API call, SIM_ACQUIRE_TARGET sets the function_name and source_location arguments automatically with the information where the API call was made. This data is used when lock statistics collection is enabled through the enable-object-lock-stats command.
SIM_acquire_target returns a domain lock handle which should be passed as an argument to SIM_release_target when the lock is released. SIM_ACQUIRE_TARGET does not return anything but instead stores the domain lock handle in the pointer passed as the second argument.
Any
SIM_drop_thread_domains, SIM_reacquire_thread_domains, SIM_DROP_THREAD_DOMAINS, SIM_REACQUIRE_THREAD_DOMAINS — temporarily release all held thread domains
#include <simics/device-api.h> // in C
// always available in DML
domain_lock_t *
SIM_drop_thread_domains();
void
SIM_reacquire_thread_domains(domain_lock_t *dl);
// not available in DML
SIM_DROP_THREAD_DOMAINS(obj, lockp);
SIM_REACQUIRE_THREAD_DOMAINS(obj, lockp);
import simics
simics.SIM_drop_thread_domains(...)
simics.SIM_reacquire_thread_domains(...)
Temporarily releases all held thread domains and enters Threaded Context.
This function is intended to use before blocking is initiated on an external synchronization mechanism, like a condition variable. Releasing thread domains before blocking is often necessary to avoid deadlock situations where other threads get stuck trying to acquire thread domains held by the blocking thread.
Each call to SIM_drop_thread_domains must be followed with a call to SIM_reacquire_thread_domains to reacquire the released thread domains. This must be done from the same thread.
If the purpose of the call is just to provide other threads an opportunity to acquire held domains, then the more efficient SIM_yield_thread_domains should be used instead.
The macro versions of the API calls are currently wrappers of the corresponding SIM-function. In the future, they might collect extra information about where in the code the domain locks are reacquired.
SIM_drop_thread_domains returns a domain lock handle which should be passed as an argument to SIM_reacquire_thread_domains_object. The SIM_DROP_THREAD_DOMAINS does not return anything but instead stores the domain lock handle in the pointer passed as the second argument.
Any
SIM_yield_thread_domains — yield held thread domains
#include <simics/device-api.h> // in C
// always available in DML
void
SIM_yield_thread_domains();
import simics
simics.SIM_yield_thread_domains(...)
Yields held thread domains if there are other threads waiting to acquire them.
The function blocks until all threads waiting for one of the held domains have had the opportunity to acquire the domain in question, and then resumes execution with the domains held again.
One example usage of this function is when a CPU model is notified through the execute_control interface that another thread wants to acquire the CPU’s thread domain. Then the CPU function should call this function as quickly as possible, preferably before starting the simulation of the next instruction.
Any