Wiki

Differences

This shows you the differences between two versions of the page.


Previous revision
resources:technical-guides:motifapi [07 Oct 2014 22:07] (current) – [API] Tom MacLeod
Line 1: Line 1:
 +====== MOTIF Operational Simulator API ======
 +
 +===== Overview =====
 +The intent of this page is to document the API so that any client can interface with the MOTIF operational simulator.\\ \\
 +The simulator supports the loading of product model files (PMF) to create product instances in memory.  Any number of PMFs can be loaded (even duplicates) into memory concurrently. Upon loading a PMF, the client may set or retrieve information pertinent to that instance, such as setting a property value or querying the interface.  The client may run a simulation of a model instance against some input vector.  It is contingent upon the client to manage instances and to deallocate them upon completion of a simulation session (intermittent simulation calls of arbitrary length are permitted).\\ \\
 +
 +===== Structure =====
 +Before the API can be documented, it is important to understand precisely what is loaded into memory and how the memory is structured.  As stated in the Overview section, any number of PMFs may be loaded concurrently into memory.  The client interface accesses instances through a unique identifier called a key.\\ \\
 +Every model instance has at least one mode, but possibly more. A mode is used to encapsulate and describe unique product states of the device. Modes are typically high level (broad), full chip settings rather than the toggling of one particular setting. The client software can query the current mode setting, query other possible modes of operation, and set the desired mode.\\ \\
 +For any given mode, the simulator model receives its behavior through a collection of processing blocks. Each block contains properties which, in turn, have access permissions (read, read/write, or hidden). Only those blocks which have pertinent properties to the software client (that is, read or read/write) are visible. If a block has only hidden properties then that block is hidden, as well.  There is also a global block which contains settings for the simulation, such as input frequency or sampling rate.\\ \\
 +See Figure 1 for a graphical representation.\\
 +{{ :resources:technical-guides:structure2.png?direct& |}}
 +<WRAP centeralign>//Figure 1. MOTIF Structure//</WRAP>\\
 +
 +
 +===== API =====
 +The API section is broken up into two subsections: Shared Library Interface and the Process Message Schema.  The Shared Library Interface section documents how to interface physically to MOTIF.dll on Windows and libMOTIF.so on Linux.  The Process Message Schema section documents how to interface logically to a model instance.  The simulator was designed this way to preserve generitivity and provide extensibility.\\
 +
 +==== Physical Interface ====
 +<code java>int ImportPMF(const char* filename);</code>
 +//Description://\\
 +<wrap indent>Takes the Product Model File (*.pmf) or ADC (*.adc) file addressed by filename to create a model instance into memory.</wrap>\\ \\
 +//Parameter(s)://\\
 +<wrap indent>''filename'' – string containing the PMF location.</wrap>\\ \\
 +//Returns://\\
 +<wrap indent>''key'' – reference to this model instance used in future functions.</wrap>\\
 +\\
 +<code java>int Reset(int key);</code>
 +//Description://\\
 +<wrap indent>Resets the simulation conditions for this model instance.</wrap>\\ \\
 +//Parameter(s)://\\
 +<wrap indent>''key'' – instance index for PMF returned from ''ImportPMF(…).''</wrap>\\ \\
 +//Returns://\\
 +<wrap indent>''success'' – execution status of the function call.</wrap>\\
 +\\
 +<code java>int RunSamples(double* in, double* out, long length, int key);</code>
 +//Description://\\
 +<wrap indent>Runs a multistep simulation on an array of input values for this model instance.</wrap>\\ \\
 +//Parameters://\\
 +<wrap indent>''in'' – pointer to the input value array.</wrap>\\ \\
 +<wrap indent>If the input data type is real, ''RunSamples(…)'' expects an array of doubles, which captures the following relationship:</wrap>\\
 +^ Value ^ Maps To ^
 +| ''in[0]'' | real<sub>0</sub> |
 +| ''in[1]'' | real<sub>1</sub> |
 +| … | … |
 +| ''in[length-1]'' | real<sub>''length-1''</sub> |
 +\\
 +<wrap indent>If the input data type is complex, ''RunSamples(…)'' expects an array of interleaved doubles, which captures the following relationship:</wrap>\\
 +^ Value ^ Maps To ^
 +| ''in[0]'' | real<sub>0</sub> |
 +| ''in[1]'' | imag<sub>0</sub> |
 +| ''in[2]'' | real<sub>1</sub> |
 +| ''in[3]'' | imag<sub>1</sub> |
 +| … | … |
 +| ''in[2*length-2]'' | real<sub>''length-1''</sub> |
 +| ''in[2*length-1]'' | imag<sub>''length-1''</sub> |
 +\\
 +<wrap indent>''out'' – pointer to the output value array.  It must be allocated by the client.</wrap>\\ \\
 +<wrap indent>If the input data type is real, ''RunSamples(…)'' expects space for an array of doubles, which captures the following relationship:</wrap>\\
 +^ Value ^ Maps To ^
 +| real<sub>0</sub> | ''out[0]'' |
 +| real<sub>1</sub> | ''out[1]'' |
 +| … | … |
 +| real<sub>''out_length-1''</sub> | ''out[out_length-1]'' |
 +\\
 +<wrap indent>If the input data type is complex, ''RunSamples(…)'' expects space for an array of interleaved doubles, which captures the following relationship:</wrap>\\
 +^ Value ^ Maps To ^
 +| real<sub>0</sub> | ''out[0]'' |
 +| imag<sub>0</sub> | ''out[1]'' |
 +| real<sub>1</sub> | ''out[2]'' |
 +| imag<sub>1</sub> | ''out[3]'' |
 +| … | … |
 +| real<sub>''out_length-1''</sub> | ''out[2*out_length-2]'' |
 +| imag<sub>''out_length-1''</sub> | ''out[2*out_length-1]'' |
 +\\
 +<wrap indent>where:</wrap>\\
 +<wrap indent><wrap indent>''out_length = ceil(length * (fout / fs)).''</wrap></wrap>\\ \\
 +<wrap indent><wrap indent>''fout'' and ''fs'' are retrieved via ''ProcessMessage(…)'' and
 +''ceil(…)'' returns the next highest inclusive integer.</wrap></wrap>\\ \\
 +<wrap indent>''length'' – contains the number of simulation iterations to run.</wrap>\\ \\
 +<wrap indent>''key'' – instance index for PMF returned from ''ImportPMF(…).''</wrap>\\ \\
 +//Returns://\\
 +<wrap indent>''success'' – execution status of the function call.</wrap>\\
 +\\
 +<code java>int RunSample(double* in, double* out, int key);</code>
 +//Description://\\
 +<wrap indent>Functionally equivalent to ''RunSamples(in, out, 1, key);''</wrap>\\
 +\\
 +<code java>int GetPortCount(int* count, int port_direction, int key);</code>
 +//Description://\\
 +<wrap indent>Gets the number of inputs/outputs for this model instance.</wrap>\\ \\
 +\\
 +//Parameter(s)://\\
 +<wrap indent>''port_direction'' – whether a port is an input or an output {0 : Input, 1: Output}.</wrap>\\ \\
 +<wrap indent>''key'' – instance index for PMF returned from ''ImportPMF(…).''</wrap>\\ \\
 +//Returns://\\
 +<wrap indent>''count'' – the port count.</wrap>\\ \\
 +<wrap indent>''success'' – execution status of the function call.</wrap>\\
 +\\
 +<code java>int QueryPort(double* f, bool* is_complex, int* domain, char** unit, int port_direction, int port_index, int key);</code>
 +//Description://\\
 +<wrap indent>Gets information about the desired port for this model instance.</wrap>\\ \\
 +\\
 +//Parameter(s)://\\
 +<wrap indent>''port_direction'' – whether a port is an input or an output {0 : Input, 1: Output}.</wrap>\\ \\
 +<wrap indent>''port_index'' – the port index.</wrap>\\ \\
 +<wrap indent>''key'' – instance index for PMF returned from ''ImportPMF(…).''</wrap>\\ \\
 +//Returns://\\
 +<wrap indent>''f'' – the port frequency.</wrap>\\ \\
 +<wrap indent>''is_complex'' – the port complexity.</wrap>\\ \\
 +<wrap indent>''domain'' – the port domain {0 : Unspecified, 1 : Analog, 2 : Digital}.</wrap>\\ \\
 +<wrap indent>''unit'' – the port unit (the string allocation is managed by MOTIF).</wrap>\\ \\
 +<wrap indent>''success'' – execution status of the function call.</wrap>\\
 +\\
 +<code java>void Destroy(int key);</code>
 +//Description://\\
 +<wrap indent>Deallocates model instance from memory.</wrap>\\ \\
 +//Parameter(s)://\\
 +<wrap indent>''key'' – instance index for PMF returned from ''ImportPMF(…).''</wrap>\\ \\
 +//Returns://\\
 +<wrap indent>Nothing.</wrap>\\
 +\\
 +<code java>void DestroyAll();</code>
 +//Description://\\
 +<wrap indent>Deallocates all model instances from memory.</wrap>\\ \\
 +//Parameter(s)://\\
 +<wrap indent>None.</wrap>\\ \\
 +//Returns://\\
 +<wrap indent>Nothing.</wrap>\\
 +\\
 +==== Logical Interface ====
 +The generative design of the simulator requires a generic interface.  Besides the above documented physical interface, there is a logical interface which is consistent across all models.  The logical interface is further subdivided into two categories: concepts and message passing.\\
 +
 +=== Concepts ===
 +All models support a logical Rate Dependency interface.  This means that every model will contain both a ''fin'' and ''fout'' property where:\\
 +<wrap indent>''fin'' – the rate of the incoming data</wrap>\\ \\
 +<wrap indent>''fout'' – the rate of the outgoing data</wrap>\\ \\
 +By computing the ratio ''r = fout / fin'', the user can determine the model’s total interpolation or decimation.  This should be performed every time a logical property is changed to ensure that the external harness knows how to appropriately allocate memory.  The exact mechanism for querying ''fin'' and ''fout'' is specified in the message passing section below.\\
 +\\
 +Based on the model’s queried interface, there will be some domain associated with both the input and the output.  Domains are restricted to either “analog” or “digital”.\\
 +If a model supports the “analog” domain, whether on the input, output, or both, it will always have a property ''dt''.\\
 +<wrap indent>''dt'' – the delta time between sampled analog values</wrap>\\ \\
 +If a model supports the “digital” domain, whether on the input, output, or both, it will always have a property ''fclk''.\\
 +<wrap indent>''fclk'' – the frequency of the digital clock</wrap>\\ \\
 +If a model supports both “analog” and “digital” (and ADC or a DAC), it will always have a property ''OSR''.\\
 +<wrap indent>''OSR'' – the oversampling ratio from the digital to the analog domain</wrap>\\ \\
 +Some models support an additional parameter ''tessitura'', which represents the expected mean frequency of the input data.  This parameter is only necessary when a model is unable to infer the input frequency from context.  The term is borrowed from music theory, where it refers to the center frequency at which a vocalist is most comfortable.\\
 +<wrap indent>''tessitura'' - the expected mean frequency of the input data</wrap>\\ \\
 +It is important to check the permission of the above property values for it may be that only one of them is mutable.  This is determined when a model is loaded, or when a mode is changed.\\
 +
 +A graphical representation of the logical model interface is shown in Figure 2 below:\\
 +
 +{{ :resources:technical-guides:logical_model_concept.png?direct |}}
 +<WRAP centeralign>//Figure 2: Logical Model Interface//</WRAP>
 +
 +=== Message Passing ===
 +A physical API command that enables logical message passing is provided through the following method:\\
 +<code java>int ProcessMessage(const char* msg, char** response, int key);</code>
 +//Description://\\
 +<wrap indent>Generic interface to inspect/modify model instance properties.</wrap>\\ \\
 +//Parameter(s)://\\
 +<wrap indent>''msg'' – message (in XML format) to send to the model instance.</wrap>\\ \\
 +<wrap indent>''response'' – Pointer to the internally allocated response message (in XML format).</wrap>\\ \\
 +<wrap indent>''key'' – instance index for PMF returned from ''ImportPMF(…).''</wrap>\\ \\
 +//Returns://\\
 +<wrap indent>''success'' – execution status of the function call.</wrap>\\
 +\\
 +All sent message content are children of the root element:\\
 +<code xml><motif>[command(s)]</motif></code>
 +All received message content are children of the root element:\\
 +<code xml><responses>[answers(s)]</responses></code>
 +Sent messages are composed of a series of atomic messages called commands. Commands perform a specific task understood by MOTIF.dll. Each sent message solicits a response that is called an answer.
 +=== Modes ===
 +<code xml><setmode>[mode]</setmode></code>
 +//Command element(s)://\\
 +<wrap indent>''[mode]'' – name of the mode you want to switch to.</wrap>\\ \\
 +//Answer://\\
 +<wrap indent>''<setmode s=”Success” />'' – if ''[mode]'' is valid.</wrap>\\ \\
 +<wrap indent>''<setmode s=”Error”>Cannot find mode: [mode]</setmode>'' – if ''[mode]'' is invalid.</wrap>\\
 +\\
 +<code xml><getmode /></code>
 +//Command element(s)://\\
 +<wrap indent>None.</wrap>\\ \\
 +//Answer://\\
 +<wrap indent>''<getmode mdn=”[mode display name]” mn=”[mode name]”/>''</wrap>\\ \\
 +<wrap indent>where:</wrap>\\
 +<wrap indent><wrap indent>''[mode display name]'' – display name of the current mode.</wrap></wrap>\\ \\
 +<wrap indent><wrap indent>''[mode name]'' – name of the current mode.</wrap></wrap>\\
 +\\
 +<code xml><querymodes /></code>
 +//Command element(s)://\\
 +<wrap indent>None.</wrap>\\ \\
 +//Answer://\\
 +<wrap indent>''<querymodes>''</wrap>\\
 +<wrap indent><wrap indent>''<mode mdn=”[mode display name1]” mn=”[mode name1]”/>''</wrap></wrap>\\
 +<wrap indent><wrap indent>''…''</wrap></wrap>\\
 +<wrap indent><wrap indent>''<mode mdn=”[mode display nameN]” mn=”[mode nameN]”/>''</wrap></wrap>\\
 +<wrap indent>''</querymodes>''</wrap>\\ \\
 +<wrap indent>where:</wrap>\\
 +<wrap indent><wrap indent>''[mode display name#]'' – display name of this mode.</wrap></wrap>\\ \\
 +<wrap indent><wrap indent>''[mode name#]'' – name of this mode.</wrap></wrap>\\
 +\\
 +=== Properties ===
 +<code xml><setprop bn=”[block name]” pn=”[property name]”>[value]</setprop></code>
 +//Command element(s)://\\
 +<wrap indent>''[block name]'' – name of the block to be indexed.</wrap>\\ \\
 +<wrap indent>''[property name]'' – name of the property to set.</wrap>\\ \\
 +<wrap indent>''[value]'' – value to assign to the property.</wrap>\\ \\
 +//Answer://\\
 +<wrap indent>''<setprop s=”Success” />'' - if ''[block name]'' is found, ''[property name]'' is found.</wrap>\\ \\
 +<wrap indent>''<setprop s=”Error”>Could not find block: [block name]</setprop>'' - if ''[block name]'' is not found.</wrap>\\ \\
 +<wrap indent>''<setprop s=”Error”>Could not find property: [property name]</setprop>'' - if ''[property name]'' is not found.</wrap>\\ \\
 +<wrap>Note: ''ProcessMessage(…)'' does not perform data validation through ''<setprop…>''.</wrap>\\
 +\\
 +<code xml><getprop bn=”[block name]” pn=”[property name]”/></code>
 +//Command element(s)://\\
 +<wrap indent>''[block name]'' – name of the block to be indexed.</wrap>\\ \\
 +<wrap indent>''[property name]'' – name of the property to get.</wrap>\\ \\
 +//Answer://\\
 +<wrap indent>''<getprop pdn=”[property display name]” l=”[limits]” p=”[permissions]” t=”[type]” u="[unit]" tt="[tooltip]">[value]</getprop>''</wrap>\\ \\
 +<wrap indent>if ''[block name]'' is found and ''[property name]'' is found:</wrap>\\
 +<wrap indent><wrap indent>''[property display name]'' – display name of this property.</wrap></wrap>\\ \\
 +<wrap indent><wrap indent>''[property name]'' – name of this property.</wrap></wrap>\\ \\
 +<wrap indent><wrap indent>''[limits]'' – limits of valid values associated with this property.</wrap></wrap>\\
 +<wrap indent><wrap indent><wrap indent>//{elem0,elem1,…,elemM}// – set of valid values.</wrap></wrap></wrap>\\
 +<wrap indent><wrap indent><wrap indent>//[m,n]// – closed interval specifying a range of valid values.</wrap></wrap></wrap>\\
 +<wrap indent><wrap indent><wrap indent>//[m,n)// – half-open interval specifying a range of valid values.</wrap></wrap></wrap>\\ \\
 +<wrap indent><wrap indent>''[permissions]'' – permission associated with this property.</wrap></wrap>\\
 +<wrap indent><wrap indent><wrap indent>//rw// – read/write.</wrap></wrap></wrap>\\
 +<wrap indent><wrap indent><wrap indent>//r// - read only.</wrap></wrap></wrap>\\ \\
 +<wrap indent><wrap indent>''[type]'' – type associated with this property.</wrap></wrap>\\
 +<wrap indent><wrap indent><wrap indent>//int// – integer.</wrap></wrap></wrap>\\
 +<wrap indent><wrap indent><wrap indent>//double// – double.</wrap></wrap></wrap>\\
 +<wrap indent><wrap indent><wrap indent>//int*// - integer array.</wrap></wrap></wrap>\\
 +<wrap indent><wrap indent><wrap indent>//double*// - double array.</wrap></wrap></wrap>\\
 +<wrap indent><wrap indent><wrap indent>//string// – string.</wrap></wrap></wrap>\\
 +<wrap indent><wrap indent><wrap indent>//bool// – Boolean //{false, true}//.</wrap></wrap></wrap>\\ \\
 +<wrap indent><wrap indent>''[unit]'' – unit associated with this property.  Will be SI, descriptive (//e.g. "Codes", "dB", etc.//), or possibly blank.</wrap></wrap>\\ \\
 +<wrap indent><wrap indent>''[tooltip]'' – tooltip associated with this property.</wrap></wrap>\\ \\
 +<wrap indent><wrap indent>''[value]'' – value of this property.</wrap></wrap>\\ \\
 +<wrap indent>else:</wrap>\\
 +<wrap indent>''<getprop s=”Error”>Could not find block: [block name]</getprop>'' - if ''[block name]'' is not found.</wrap>\\ \\
 +<wrap indent>''<getprop s=”Error”>Could not find property: [property name]</getprop>'' - if ''[property name]'' is not found.</wrap>\\
 +\\
 +<code xml><queryprops /></code>
 +//Command element(s)://\\
 +<wrap indent>None.</wrap>\\ \\
 +//Answer://\\
 +<wrap indent>''<queryprops>''</wrap>\\
 +<wrap indent><wrap indent>''<prop bdn=”[block display name1]” bn=”[block name1]” pdn=”[property display name1]” 
 +pn=”[property name1]” l=”[limits1]” p=”[permissions1]” t=”[type1]” u="[unit1]" tt="[tooltip1]">[value1]</prop>''</wrap></wrap>\\
 +<wrap indent><wrap indent>''…''</wrap></wrap>\\
 +<wrap indent><wrap indent>''<prop bdn=”[block display nameN]” bn=”[block nameN]” pdn=”[property display nameN]” 
 +pn=”[property nameN]” l=”[limitsN]” p=”[permissionsN]” t=”[typeN]” u="[unitN]" tt="[tooltipN]">[valueN]</prop>''</wrap></wrap>\\
 +<wrap indent>''</queryprops>''</wrap>\\ \\
 +<wrap indent>where:</wrap>\\
 +<wrap indent><wrap indent>''[block display name#]'' – display name of this block.</wrap></wrap>\\ \\
 +<wrap indent><wrap indent>''[block name#]'' – name of this block.</wrap></wrap>\\ \\
 +<wrap indent><wrap indent>''[property display name#]'' – display name of this property.</wrap></wrap>\\ \\
 +<wrap indent><wrap indent>''[property name#]'' – name of this property.</wrap></wrap>\\ \\
 +<wrap indent><wrap indent>''[limits#]'' – limits of valid values associated with this property.</wrap></wrap>\\
 +<wrap indent><wrap indent><wrap indent>//{elem0,elem1,…,elemM}// – a set of valid values.</wrap></wrap></wrap>\\
 +<wrap indent><wrap indent><wrap indent>//[m,n]// – closed interval specifying a range of valid values.</wrap></wrap></wrap>\\
 +<wrap indent><wrap indent><wrap indent>//[m,n)// – half-open interval specifying a range of valid values.</wrap></wrap></wrap>\\ \\
 +<wrap indent><wrap indent>''[permissions#]'' – permission associated with this property.</wrap></wrap>\\
 +<wrap indent><wrap indent><wrap indent>//rw// – read/write.</wrap></wrap></wrap>\\
 +<wrap indent><wrap indent><wrap indent>//r// - read only.</wrap></wrap></wrap>\\ \\
 +<wrap indent><wrap indent>''[type#]'' – type associated with this property.</wrap></wrap>\\
 +<wrap indent><wrap indent><wrap indent>//int// – integer.</wrap></wrap></wrap>\\
 +<wrap indent><wrap indent><wrap indent>//double// – double.</wrap></wrap></wrap>\\
 +<wrap indent><wrap indent><wrap indent>//int*// - integer array.</wrap></wrap></wrap>\\
 +<wrap indent><wrap indent><wrap indent>//double*// - double array.</wrap></wrap></wrap>\\
 +<wrap indent><wrap indent><wrap indent>//string// – string.</wrap></wrap></wrap>\\
 +<wrap indent><wrap indent><wrap indent>//bool// – Boolean //{false,true}//.</wrap></wrap></wrap>\\ \\
 +<wrap indent><wrap indent>''[unit#]'' – unit associated with this property.  Will be SI, descriptive (//e.g. "Codes", "dB", etc.//), or possibly blank.</wrap></wrap>\\ \\
 +<wrap indent><wrap indent>''[tooltip#]'' – tooltip associated with this property.</wrap></wrap>\\ \\
 +<wrap indent><wrap indent>''[value#]'' – value of this property.</wrap></wrap>\\ \\
 +=== Other ===
 +<code xml><queryinterface /></code>
 +//Command element(s)://\\
 +<wrap indent>None.</wrap>\\ \\
 +//Answer://\\
 +<wrap indent>''<queryinterface><in domain=”[input domain]” fin=”[input frequency]” is_complex=”[is input complex]” unit=”[input unit]”/><out domain=”[output domain]” fout=”[output frequency]” is_complex=”[is output complex]” unit=”[output unit]”/></queryinterface>''</wrap>\\ \\
 +<wrap indent>where:</wrap>\\
 +<wrap indent><wrap indent>''[input (output) domain]'' – //{analog, digital}// indicating the analog or digital nature of the input (output).</wrap></wrap>\\ \\
 +<wrap indent><wrap indent>''[input (output) frequency]'' – indicating the reciprocal of the time step between input (output) data points.</wrap></wrap>\\ \\
 +<wrap indent><wrap indent>''[is input (output) complex]'' – //{false, true}// indicating whether input (output) data are complex or real numbers.</wrap></wrap>\\ \\
 +<wrap indent><wrap indent>''[input (output) unit]'' – indicating the units associated with the input (output) data.</wrap></wrap>
 +\\
 +\\
 +<code xml><queryversion /></code>
 +//Command element(s)://\\
 +<wrap indent>None.</wrap>\\ \\
 +//Answer://\\
 +<wrap indent>''<queryversion dllversion=”[dll version]” pmfversion=”[pmf version]”/>''</wrap>\\ \\
 +<wrap indent>where:</wrap>\\
 +<wrap indent><wrap indent>''[dll version]'' – version of the MOTIF.dll.</wrap></wrap>\\ \\
 +<wrap indent><wrap indent>''[pmf version]'' – version of the Product Model file (model).</wrap></wrap>\\
  
resources/technical-guides/motifapi.txt · Last modified: 07 Oct 2014 22:07 by Tom MacLeod