sam-t2/docs/mmi/index.html

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
  <title>SPARC Architectural Model: Device Model API</title>
</head>
<body bgcolor="#ffffff" lang="en-US">
<h1>SPARC Architectural Model: Device Model API</h1>
<h2>Introduction</h2>
This document describes the MMI device-model API for the SPARC
Architectural Model (SAM).
A SAM device model is built as a shared library (loadable module) which
is dynamically loaded into SAM during initialization.
<p>The <tt>sysconf</tt> directives in the input configuration file
specify the device module, instance name and its associated properties.
</p>
<p>API function and type names are prefixed with <tt>mmi_</tt>
(which means Module Model Interfaced).
</p>
<p></p>
<h4>Attaching Modules</h4>
<li> A device-model is built as a shared object (.so file). A shared
object typically has only one visible module that plugs into SAM.
Internally within the device model, there can be a hierarchy of
components (for example, Niagara ethernet module).</li>
<br>
<li>An <i>instance</i> is what actually represents a device in SAM.
There are generally multiple instances of a given device module.</li>
<br>
<li> The <tt><b>sysconf</b></tt> directive
  <p></p>
  <ul>
    <tt>sysconf</tt> directives are specified in the simulation
configuration file. Each sysconf line specifies
the module to be loaded if necessary, and the name of the device node
to be instantiated. This is followed by the properties associated with
the instance, in the form of name=value words.
To properly instantiate the device node,
SAM calls the instance creator function registered from within the
module.
  </ul>
</li>
<h4> The <tt>mmi_instance_t</tt> handle</h4>
Each instance can be referred to using an opaque <tt>mmi_instance_t</tt>
handle. This includes code referring to its own instance (for example, to
register certain callback functions) as well as other instances (for example,
to get an exported interface).
<h4>Threading Model </h4>
SAM can be run in multi-threaDed mode. It is recommended that module
developers for SAM
assume that simulated SPARCv9 CPUs may be bound to separate host
threads, running on different
processors on the host machine running the simulation.
<p>
A strand, however, is never simulated by more than one simulation
thread, and
when a strand performs a callback to the module it may be assumed that
strand execution
is stopped at the point of callback.
<h4>Module to Module Interaction </h4>
Modules may be loaded in any order (as specified in the sysconf file).
In some cases, modules may be unloaded at any time.
The SAM sysconf mechanism does not allow for device modules to be
unloaded but the older <tt>ldm</tt> UI command does allow this.
<p>Each module is notified when another module changes status
(<a href="mmi_register_config_cb.html">mmi_register_config_cb</a>).
</p>
<p>Modules may call each other by getting pointers to their interfaces
(<a href="%20mmi_get_interface.html">mmi_get_interface</a>).
When a module is unloaded, other modules should receive the
corresponding configuration (config) change notification and remove
their interface pointers to the unloaded module.
</p>
<h2>API Overview</h2>
<h4>Module instantiation</h4>
<ul>
  <li><a href="mmi_register_instance_creator.html">mmi_register_instance_creator</a>
  </li>
  <li><a href="mmi_register_instance.html">mmi_register_instance</a> </li>
  <li><a href="mmi_get_instance.html">mmi_get_instance</a>
  </li>
</ul>
<h4>Module connectivity</h4>
<ul>
  <li><a href="mmi_map_physio.html">mmi_map_physio</a> </li>
  <li><a href="mmi_register_config_cb.html">mmi_register_config_cb</a> </li>
  <li><a href="mmi_register_interface_cb.html">mmi_register_interface_cb</a>
  </li>
  <li><a href="mmi_get_interface.html">mmi_get_interface</a> </li>
  <li><a href="mmi_register_modinfo_cb.html">mmi_register_modinfo_cb</a></li>
  <li><a href="mmi_register_asi_action.html">mmi_register_asi_action</a></li>
  <li><a href="mmi_register_asi_cb_data.html">mmi_register_asi_cb_data</a><br>
  </li>
</ul>
<h4>Memory Access</h4>
<ul>
  <li><a href="mmi_memaccess.html">mmi_memread</a> </li>
  <li><a href="mmi_memaccess.html">mmi_memwrite</a>
  </li>
</ul>
<h4>Interrupts</h4>
<ul>
  <li><a href="mmi_interrupt.html">mmi_interrupt_packet</a> </li>
  <li><a href="mmi_interrupt.html">mmi_interrupt_vector</a>
  </li>
</ul>
</body>
</html>