<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Somascape : RISC OS Matters - SWI details for ESP's MIDISupport module</title><link rel="stylesheet" type="text/css" href="6fc3a51c"></head><body>

<!-- BEGIN : Banner + MenuBar -->
<table border="0" width="94%" align="center" cellpadding="0" cellspacing="0"><tr><td width="116" height="100" rowspan="4" align="center"><a name="top" href="http://www.somascape.org/index.html" title="Somascape home page"><img src="6ffc6df4" width="72" height="88" border="0" alt="Somascape"></a></td>
 <td width="16" height="20"></td>
 <td height="20"></td>
</tr><tr><td></td>
 <td height="27"><span class="banner2"><a href="http://www.somascape.org/riscos/index.html">RISC OS Matters</a> &nbsp;&mdash;&nbsp; <a href="http://www.somascape.org/riscos/esp/index.html">ESP Audio &amp; MIDI SWIs</a></span></td>
</tr><tr><td></td>
 <td height="25"><span class="banner3"><span class="thispage">MIDISupport</span> &nbsp;&nbsp;
  <a href="http://www.somascape.org/riscos/esp/pwfs.html">PowerWAVE</a> &nbsp;&nbsp;
  <a href="http://www.somascape.org/riscos/esp/sdfs.html">SoundDriver</a></span></td>
</tr><tr><td colspan="2" valign="top"><img src="6fd23274" width="100%" height="24" alt="---"></td>
</tr></table><!-- END : Banner + MenuBar --><h1 align="center">
MIDIS<small>UPPORT</small><br>
F<small>UNCTIONAL</small> S<small>PECIFICATION</small>
</h1>

<div align="center">
<h2>( M1002/FS )</h2>

<!-- p>Issue 6<br>26 Mar 1999</p -->

<p>Issue 7<br>01 Mar 2003</p>

<h3>Authors</h3>

<p>Andy Pierson<br>David Lenthall</p>

<p><img src="6fbe8ba4" width="52" height="41" border="0" alt="ESP Music"></p>

<p><span class="copyright">&copy; ESP Music</span></p>
</div>


<p align="center">
<img src="6fd23274" width="94%" height="24" align="middle" alt="---"></p>


<!-- ***************************************************************** -->


<table border="0" width="90%" align="center" cellpadding="0" cellspacing="0"><tr><td>

<a name="contents"></a><h2>
Contents
</h2>

<ul class="index"><li><a href="http://www.somascape.org/riscos/esp/msfs.html#intro">     Introduction</a>
 </li><li><a href="http://www.somascape.org/riscos/esp/msfs.html#drivers">   Drivers</a>
 </li><li><a href="http://www.somascape.org/riscos/esp/msfs.html#flags">     Driver Flags</a>
 </li><li><a href="http://www.somascape.org/riscos/esp/msfs.html#datatrans"> Data Transfer</a>
 </li><li><a href="http://www.somascape.org/riscos/esp/msfs.html#connmaps">  Connect Maps</a>
 </li><li><a href="http://www.somascape.org/riscos/esp/msfs.html#dataform">  Data Format</a>
 </li><li><a href="http://www.somascape.org/riscos/esp/msfs.html#use">       Use</a>
 </li><li><a href="http://www.somascape.org/riscos/esp/msfs.html#swis">      SWI Interface</a>
 <ul><li><a href="http://www.somascape.org/riscos/esp/msfs.html#swi4EE80">  MIDISupport_InstallDriver</a>
  </li><li><a href="http://www.somascape.org/riscos/esp/msfs.html#swi4EE81">  MIDISupport_RemoveDriver</a>
  </li><li><a href="http://www.somascape.org/riscos/esp/msfs.html#swi4EE82">  MIDISupport_DriverInfo</a>
  </li><li><a href="http://www.somascape.org/riscos/esp/msfs.html#swi4EE83">  MIDISupport_CreateDriver</a>
  </li><li><a href="http://www.somascape.org/riscos/esp/msfs.html#swi4EE84">  MIDISupport_Send</a>
  </li><li><a href="http://www.somascape.org/riscos/esp/msfs.html#swi4EE85">  MIDISupport_Receive</a>
  </li><li><a href="http://www.somascape.org/riscos/esp/msfs.html#swi4EE86">  MIDISupport_Connect</a>
  </li><li><a href="http://www.somascape.org/riscos/esp/msfs.html#swi4EE87">  MIDISupport_ConnectName</a>
  </li><li><a href="http://www.somascape.org/riscos/esp/msfs.html#swi4EE88">  MIDISupport_GetAddress</a>
  </li><li><a href="http://www.somascape.org/riscos/esp/msfs.html#swi4EE89">  MIDISupport_Insert</a>
 </li></ul></li><li><a href="http://www.somascape.org/riscos/esp/msfs.html#cmds">      Commands</a>
 </li><li><a href="http://www.somascape.org/riscos/esp/msfs.html#serv">      Service Calls</a>
 </li><li><a href="http://www.somascape.org/riscos/esp/msfs.html#msgs">      WIMP Messages</a>
</li></ul></td></tr></table><table class="upline"><tr><td><img src="6fd9fd24" width="100%" height="12" alt="---"></td>
 <td width="52"><a href="http://www.somascape.org/riscos/esp/msfs.html#top" name="intro"><img src="6fda1404" border="0" align="middle" width="52" alt="Top"></a></td>
 <td><img src="6fd9fd24" width="100%" height="12" alt="---"></td>
</tr></table><!-- ***************************************************************** --><table border="0" width="90%" align="center" cellpadding="0" cellspacing="0"><tr><td>

<h2>
Introduction
</h2>

<p>The purpose of this module is summarised as follows :</p>

<ul><li>Full implementation of MIDI Ports 0-3
 </li><li>Use of multiple cards allowing for &gt; 16 channel MIDI
 </li><li>PC MIDI Input
 </li><li>Software MIDI devices e.g. ESP's MIDI Synthesizer
 </li><li>Faster data transfer
 </li><li>Built in software MIDI Thru
 </li><li>Advanced mapping facilities
 </li><li>Alternative hardware drivers such as a serial port driver for external sound modules
 </li><li>Data filters
 </li><li>MIDI Time Code support
</li></ul><p>The module is designed to provide full driver support for MIDI hardware
and software devices and thus improve the transfer of MIDI data throughout
the system.  All MIDI data transfers will be possible via the MIDI Support
module, however, full support is also provided for the original Acorn MIDI
module Tx and Rx SWIs. This is achieved by registering the Acorn MIDI Tx
and Rx ports as drivers into the MIDI Support mechanism.</p>

<p>Mapping facilities are provided by both SWIs and Commands to allow
pre-configuration of the MIDI drivers upon startup.  In addition a mapping
application <a href="http://www.somascape.org/riscos/midi/mm.html">!MidiMan</a> is available that
allows MIDI data routes to be selected, viewed and pre-configured.</p>

</td></tr></table><table class="upline"><tr><td><img src="6fd9fd24" width="100%" height="12" alt="---"></td>
 <td width="52"><a href="http://www.somascape.org/riscos/esp/msfs.html#contents" name="drivers"><img src="6fda1404" border="0" align="middle" width="52" alt="Contents"></a></td>
 <td><img src="6fd9fd24" width="100%" height="12" alt="---"></td>
</tr></table><!-- ***************************************************************** --><table border="0" width="90%" align="center" cellpadding="0" cellspacing="0"><tr><td>

<h2>
Drivers
</h2>

<p>A MIDI Support driver can be either a hardware device such as a MIDI
interface or a software application.  Either type can generate MIDI data
coming in or process MIDI data going out and do so in a number of
different ways.</p>

</td></tr></table><table class="upline"><tr><td><img src="6fd9fd24" width="100%" height="12" alt="---"></td>
 <td width="52"><a href="http://www.somascape.org/riscos/esp/msfs.html#contents" name="flags"><img src="6fda1404" border="0" align="middle" width="52" alt="Contents"></a></td>
 <td><img src="6fd9fd24" width="100%" height="12" alt="---"></td>
</tr></table><!-- ***************************************************************** --><table border="0" width="90%" align="center" cellpadding="0" cellspacing="0"><tr><td>

<h2>
Driver Flags
</h2>

<p>To distinguish the capabilities of different drivers, a set of flags is
associated with each driver.  The following flags are defined :</p>

<dl><dd>Bit 0 : Driver can send MIDI data
	</dd><dd>Bit 1 : Driver can receive MIDI data
	</dd><dd>Bit 2 : Driver requires MIDI Support to buffer receive data
	</dd><dd>Bit 3 : Driver can receive un-buffered MIDI data as a command
</dd></dl><p><b>Related SWIs :</b></p>

<dl><dd><a href="http://www.somascape.org/riscos/esp/msfs.html#swi4EE80">MIDISupport_InstallDriver - &amp;4EE80</a>
	</dd><dd><a href="http://www.somascape.org/riscos/esp/msfs.html#swi4EE82">MIDISupport_DriverInfo - &amp;4EE82</a>
	</dd><dd><a href="http://www.somascape.org/riscos/esp/msfs.html#swi4EE83">MIDISupport_CreateDriver - &amp;4EE83</a>
</dd></dl></td></tr></table><table class="upline"><tr><td><img src="6fd9fd24" width="100%" height="12" alt="---"></td>
 <td width="52"><a href="http://www.somascape.org/riscos/esp/msfs.html#contents" name="datatrans"><img src="6fda1404" border="0" align="middle" width="52" alt="Contents"></a></td>
 <td><img src="6fd9fd24" width="100%" height="12" alt="---"></td>
</tr></table><!-- ***************************************************************** --><table border="0" width="90%" align="center" cellpadding="0" cellspacing="0"><tr><td>

<h2>
Data Transfer
</h2>

<p>MIDI Support refers to the word '<b>Send</b>' to mean that a driver can
send incoming data to the MIDI Support module and '<b>Receive</b>' to mean
that the driver can receive data from the MIDI Support module for possible
output.</p>

<p>A hardware device would be likely to have both <b>send</b> and
<b>receive</b> functionality whereas the Software Synth, for example, can
only <b>receive</b> from MIDI Support.</p>

<p>Various call addresses are provided by MIDI Support and can be provided
by a driver to allow MIDI data to be passed through the system.  MIDI
Support provides a facility to connect the Send from one driver to the
Receive of another so that when a driver generates data it is passed
directly to the Receive of any connected drivers.  Buffering and filtering
is carried out during this process as necessary.</p>

<p>A driver can choose to receive data directly as either a byte or
command or ask for it to be buffered.  A hardware device will typically
require the data to be buffered and to call MIDI Support to give the data
a byte at a time to pass on to the hardware.  A software device might be
able to receive and process the data immediately, a command at a time.</p>

<p>Data is transmitted with interrupts disabled and so any receiving
device must return as quickly as possible and set up a Call Back to
process the data if necessary.</p>

<p>Software MIDI Thru is achieved by connecting the Send of a driver to
the Receive of the same driver.</p>

</td></tr></table><table class="upline"><tr><td><img src="6fd9fd24" width="100%" height="12" alt="---"></td>
 <td width="52"><a href="http://www.somascape.org/riscos/esp/msfs.html#contents" name="connmaps"><img src="6fda1404" border="0" align="middle" width="52" alt="Contents"></a></td>
 <td><img src="6fd9fd24" width="100%" height="12" alt="---"></td>
</tr></table><!-- ***************************************************************** --><table border="0" width="90%" align="center" cellpadding="0" cellspacing="0"><tr><td>

<h2>
Connect Maps
</h2>

<p>Each driver has a <b>Connect Map</b> associated with it.  This is a
block of one or more 32-bit words, used to indicate which drivers any
particular driver is connected to.</p>

<p>The driver connection information is bit mapped.  Bit 0 of the first
word corresponds to driver 1, and if set would imply that the Send of the
driver in question is connected to the Receive of driver 1.  Similarly, if
bit 31 was set, it would mean that this driver was connected to driver 32. 
Bit 0 of the second word (if present) would refer to driver 33, and so
on.</p>

<p>One word provides the information required to show the connections from
this driver to up to 32 other drivers.  Hence the number of words
comprising a Connect Map is determined by the number of currently
installed drivers.</p>

<p>The current <b>driver limit</b> (which is always a multiple of 32) can
be determined by calling the MIDISupport_DriverInfo SWI.  This value,
divided by 32, gives the current size (in words) of the Connect Map.</p>

<p>The programmer needs to be aware that the size of the Connect Map can
thus change, whenever the number of installed drivers crosses a 32-33,
64-65, (etc) threshold.  Other applications, external to your own, may be
installing / removing drivers.</p>

<p>The current driver limit is also returned by the <b>Install</b> and
<b>Remove</b> <a href="http://www.somascape.org/riscos/esp/msfs.html#msgs">Wimp messages</a>, as these are the two
events which can potentially bring about a change in the driver limit, and
thus the size of the Connect Map.</p>

<p><b>Related SWIs :</b></p>

<dl><dd><a href="http://www.somascape.org/riscos/esp/msfs.html#swi4EE82">MIDISupport_DriverInfo - &amp;4EE82</a>
	</dd><dd><a href="http://www.somascape.org/riscos/esp/msfs.html#swi4EE86">MIDISupport_Connect - &amp;4EE86</a>
	</dd><dd><a href="http://www.somascape.org/riscos/esp/msfs.html#swi4EE87">MIDISupport_ConnectName - &amp;4EE87</a>
</dd></dl></td></tr></table><table class="upline"><tr><td><img src="6fd9fd24" width="100%" height="12" alt="---"></td>
 <td width="52"><a href="http://www.somascape.org/riscos/esp/msfs.html#contents" name="dataform"><img src="6fda1404" border="0" align="middle" width="52" alt="Contents"></a></td>
 <td><img src="6fd9fd24" width="100%" height="12" alt="---"></td>
</tr></table><!-- ***************************************************************** --><table border="0" width="90%" align="center" cellpadding="0" cellspacing="0"><tr><td>

<h2>
Data Format
</h2>

<p>MIDI Support stores data internally as a series of commands each stored
in 32-bit words.  This provides the facility for data merging and speeds
up the transfer of data to and from applications.  The word is of the form
<tt>&amp;nnd2d1sc</tt> where :</p>

<dl><dd><tt>&amp;nn</tt> is the number of bytes in the command,
	</dd><dd><tt>&amp;d2</tt> and <tt>&amp;d1</tt> are up to 2 data bytes
	(<tt>&amp;d1</tt> being the first), and
	</dd><dd><tt>&amp;sc</tt> is the status and channel value.
</dd></dl><p>Hence, the lowest 1, 2 or 3 bytes are the MIDI data, and the top byte
is the byte-count.</p>

<p>All MIDI commands (with the exception of System Exclusive commands) can
fit into this structure, ie the status byte plus 0, 1 or 2 data bytes.  To
accomodate the larger System Exclusive messages, the top bit is set to
indicate that it is (part of) a System Exclusive command and that more
data follows.</p>

<p>An extension of the <b>MIDI_TxCommand</b> SWI is provided to allow
applications to send System Exclusive data as a single SWI.</p>

</td></tr></table><table class="upline"><tr><td><img src="6fd9fd24" width="100%" height="12" alt="---"></td>
 <td width="52"><a href="http://www.somascape.org/riscos/esp/msfs.html#contents" name="use"><img src="6fda1404" border="0" align="middle" width="52" alt="Contents"></a></td>
 <td><img src="6fd9fd24" width="100%" height="12" alt="---"></td>
</tr></table><!-- ***************************************************************** --><table border="0" width="90%" align="center" cellpadding="0" cellspacing="0"><tr><td>

<h2>
Use
</h2>

<p>This module is currently supported by the following products :</p>

<ul><li>Acorn AKA16/12 MIDI Interface
 </li><li>Audio Dynamics DMI50
 </li><li>CC Eagle interface
 </li><li>CC MIDI Max interface
 </li><li>Morley MIDI interface
 </li><li>ESP Parallel Port MIDI
 </li><li>ESP Serial Port MIDI
 </li><li>ESP MIDI Synthesizer
 </li><li>!PC MIDI input/output
 </li><li>Acorn TimeCode
 </li><li>MelIDI sequencer
</li></ul></td></tr></table><table class="upline"><tr><td><img src="6fd9fd24" width="100%" height="12" alt="---"></td>
 <td width="52"><a href="http://www.somascape.org/riscos/esp/msfs.html#contents" name="swis"><img src="6fda1404" border="0" align="middle" width="52" alt="Contents"></a></td>
 <td><img src="6fd9fd24" width="100%" height="12" alt="---"></td>
</tr></table><!-- ***************************************************************** --><table border="0" width="90%" align="center" cellpadding="0" cellspacing="0"><tr><td>

<h2>
SWI Interface
</h2>

<a name="swi4EE80"></a><h3>
MIDISupport_InstallDriver - &amp;4EE80
</h3>

<p>This SWI is used to install a MIDI driver into the MIDI Support
module.</p>

<p>A <a href="http://www.somascape.org/riscos/esp/msfs.html#msgs">Wimp message</a> is broadcast whenever this SWI is
called.</p>

<dl><dd><dl><dt><b>On entry</b>

	</dt><dd><p>R0 = Driver <a href="http://www.somascape.org/riscos/esp/msfs.html#flags">flags</a><br>
	R1 = Address of Driver Information call<br>
	R2 = Address of Driver Initialisation address<br>
	R3 = Address of Driver Receive call address<br>
	R4 = R12 value</p>

</dd><dt><b>On exit</b>

	</dt><dd><p>If unsuccessful, V flag is set and R0 points to a SWI error block.<br>
	If successful, V flag is clear and</p>

	<dl><dd><p>R0 = Driver number (starting from 1)<br>
		R1 = Address of MIDI Support Receive routine<br>
		R2 = Address of MIDI Support GiveData routine<br>
		R3 = MIDI Support R12 address</p>
	</dd></dl></dd><dt><b>Interrupts</b>

	</dt><dd><p>Interrupt status is undefined<br>
	Fast interrupts are enabled</p>

</dd><dt><b>Processor mode</b>

	</dt><dd><p>Processor is in SVC mode</p>

</dd><dt><b>Re-entrancy</b>

	</dt><dd><p>SWI is not re-entrant</p>

</dd></dl></dd></dl><h4>
Use
</h4>

<p>A driver can provide up to three call addresses which must be in
non-application space.  MIDI Support can call these as required.  On
installation call addresses in MIDI Support are provided for the driver to
call to send and receive data.  The call parameters for these addresses
are as follows.</p>

<h4>DriverInformation</h4>

<dl><dd><p>This is called to provide information for display by MIDI mapping applications.</p>

	<dl><dt><b>On entry</b>

		</dt><dd><p>None</p>

	</dd><dt><b>On exit</b>

		</dt><dd><p>R0 = Pointer to driver name<br>
		R1 = Driver version number<br>
		R2 = Pointer to driver data</p>

	</dd><dt><b>Interrupts</b>

		</dt><dd><p>Interrupt status is undefined<br>
		Fast interrupts are enabled</p>

	</dd><dt><b>Processor mode</b>

		</dt><dd><p>Processor is in SVC mode</p>

	<!-- dt><p><b>Re-entrancy</b></p></dt -->

	</dd></dl></dd></dl><h4>DriverInitialisation</h4>

<dl><dd><p>This is called to call the Driver to perform any initialisation on startup or reset.</p>

	<dl><dt><b>On entry</b>

		</dt><dd><p>None</p>

	</dd><dt><b>On exit</b>

		</dt><dd><p>None</p>

	</dd><dt><b>Interrupts</b>

		</dt><dd><p>Interrupt status is undefined<br>
		Fast interrupts are enabled</p>

	</dd><dt><b>Processor mode</b>

		</dt><dd><p>Processor is in SVC mode</p>

	<!-- dt><p><b>Re-entrancy</b></p></dt -->

	</dd></dl></dd></dl><h4>DriverReceive</h4>

<dl><dd><p>This call is used differently depending on the driver's <a href="http://www.somascape.org/riscos/esp/msfs.html#flags">flags</a>.<br>
	If the driver can receive unbuffered data then this address is called with the data that has 
	been received.  If the driver command flag is set then the data is received as a command 
	otherwise it is received as a byte.<br>
	If the driver requires the data to be buffered then this call simply acts as a trigger to tell 
	the driver that there is data in the buffer that needs to be retrieved.  This is typically how 
	a hardware device will work as this call will be used to start an interrupt process which in 
	turn will retrieve bytes from the buffer with each hardware interrupt until the buffer is 
	emptied.</p>

	<dl><dt><b>On entry</b>

		</dt><dd><p>For buffered data: none<br>
		For direct data: R0 = byte or command</p>

	</dd><dt><b>On exit</b>

		</dt><dd><p>None</p>

	</dd><dt><b>Interrupts</b>

		</dt><dd><p>Interrupts are disabled<br>
		Fast interrupts are enabled</p>

	</dd><dt><b>Processor mode</b>

		</dt><dd><p>Processor is in IRQ mode</p>

	<!-- dt><b>Re-entrancy</b></dt -->

	</dd></dl></dd></dl><h4>MIDISupportReceive</h4>

<dl><dd><p>This is called to pass data from the driver into the MIDI Support module.</p>

	<dl><dt><b>On entry</b>

		</dt><dd><p>R0 = Data as command or byte<br>
		R1 = Driver number</p>

	</dd><dt><b>On exit</b>

		</dt><dd><p>None</p>

	</dd><dt><b>Interrupts</b>

		</dt><dd><p>Interrupts are disabled<br>
		Fast interrupts are enabled</p>

	</dd><dt><b>Processor mode</b>

		</dt><dd><p>Processor is in SVC mode</p>

	<!-- dt><p><b>Re-entrancy</b></p></dt -->

	</dd></dl></dd></dl><h4>MIDISupportGiveData</h4>

<dl><dd><p>This is called by drivers that require MIDI Support to buffer data.  Bytes or 
	commands can be retrieved from MIDI Support until R0 = 0 to indicate that there is 
	no more data.</p>

	<dl><dt><b>On entry</b>

		</dt><dd><p>R0 = Function code :</p>
		<dl><dd><p>2 = Give command<br>
			1 = Give byte<br>
			0 = Reset<br>
			-1 = Give current buffer status</p>
		</dd></dl></dd><dd><p>R1 = Driver number</p>

	</dd><dt><b>On exit</b>

		</dt><dd><p>R0 = Data &nbsp; (=0, if no more data)</p>

	</dd><dt><b>Interrupts</b>

		</dt><dd><p>Interrupts are disabled<br>
		Fast interrupts are enabled</p>

	</dd><dt><b>Processor mode</b>

		</dt><dd><p>Processor is in IRQ mode</p>

	<!-- dt><p><b>Re-entrancy</b></p></dt -->

	</dd></dl></dd></dl></td></tr></table><table class="upline"><tr><td><img src="6fd9fd24" width="100%" height="12" alt="---"></td>
 <td width="52"><a href="http://www.somascape.org/riscos/esp/msfs.html#contents" name="swi4EE81"><img src="6fda1404" border="0" align="middle" width="52" alt="Contents"></a></td>
 <td><img src="6fd9fd24" width="100%" height="12" alt="---"></td>
</tr></table><!-- ***************************************************************** --><table border="0" width="90%" align="center" cellpadding="0" cellspacing="0"><tr><td>

<h3>
MIDISupport_RemoveDriver - &amp;4EE81
</h3>

<p>This SWI is used to remove a specific driver.</p>

<p>A <a href="http://www.somascape.org/riscos/esp/msfs.html#msgs">Wimp message</a> is broadcast whenever this SWI is
called.</p>

<dl><dd><dl><dt><b>On entry</b>

	</dt><dd><p>R1 = Driver number</p>

</dd><dt><b>On exit</b>

	</dt><dd><p>If unsuccessful, V flag is set and R0 points to a SWI error block.</p>

</dd><dt><b>Interrupts</b>

	</dt><dd><p>Interrupt status is undefined<br>
	Fast interrupts are enabled</p>

</dd><dt><b>Processor mode</b>

	</dt><dd><p>Processor is in SVC mode</p>

</dd><dt><b>Re-entrancy</b>

	</dt><dd><p>SWI is not re-entrant</p>

</dd></dl></dd></dl></td></tr></table><table class="upline"><tr><td><img src="6fd9fd24" width="100%" height="12" alt="---"></td>
 <td width="52"><a href="http://www.somascape.org/riscos/esp/msfs.html#contents" name="swi4EE82"><img src="6fda1404" border="0" align="middle" width="52" alt="Contents"></a></td>
 <td><img src="6fd9fd24" width="100%" height="12" alt="---"></td>
</tr></table><!-- ***************************************************************** --><table border="0" width="90%" align="center" cellpadding="0" cellspacing="0"><tr><td>

<h3>
MIDISupport_DriverInfo - &amp;4EE82
</h3>

<p>This SWI is used to provide information about a specific driver.</p>

<dl><dd><dl><dt><b>On entry</b>

	</dt><dd><p>R1 = Driver number</p>

</dd><dt><b>On exit</b>

	</dt><dd><p>If successful, V flag is clear and<br>
	R0 = Pointer to driver name<br>
	R1 = Driver version<br>
	R2 = Pointer to driver date<br>
	R3 = Driver <a href="http://www.somascape.org/riscos/esp/msfs.html#flags">flags</a><br>
	R4 = Pointer to driver <a href="http://www.somascape.org/riscos/esp/msfs.html#connmaps">Connect Map</a><br>
	R5 = Maximum driver limit</p>

	<p>If unsuccessful, V flag is set and R0 points to a SWI error block.</p>

</dd><dt><b>Interrupts</b>

	</dt><dd><p>Interrupt status is undefined<br>
	Fast interrupts are enabled</p>

</dd><dt><b>Processor mode</b>

	</dt><dd><p>Processor is in SVC mode</p>

</dd><dt><b>Re-entrancy</b>

	</dt><dd><p>SWI is not re-entrant</p>

</dd></dl></dd></dl><h4>
Use
</h4>

<p>The information given applies to the driver number given in R1.  MIDI
Support creates drivers in banks of 32 so the maximum driver limit
returned in R5 will be a multiple of 32.</p>

<p>The Connect Map pointer is a pointer to one or more words depending on
the maximum limit.  The connection information is bit mapped, so one word
is sufficient to show the connections from this driver to any of up to 32
other drivers.  If the current maximum limit is 64 then two words are
available, and so on.</p>

</td></tr></table><table class="upline"><tr><td><img src="6fd9fd24" width="100%" height="12" alt="---"></td>
 <td width="52"><a href="http://www.somascape.org/riscos/esp/msfs.html#contents" name="swi4EE83"><img src="6fda1404" border="0" align="middle" width="52" alt="Contents"></a></td>
 <td><img src="6fd9fd24" width="100%" height="12" alt="---"></td>
</tr></table><!-- ***************************************************************** --><table border="0" width="90%" align="center" cellpadding="0" cellspacing="0"><tr><td>

<h3>
MIDISupport_CreateDriver - &amp;4EE83
</h3>

<p>This is to enable simple software drivers to be created.</p>

<dl><dd><dl><dt><b>On entry</b>

	</dt><dd><p>R0 = Driver <a href="http://www.somascape.org/riscos/esp/msfs.html#flags">flags</a><br>
	R1 = Name of driver<br>
	R2 = Version number for driver<br>
	R3 = Date for driver</p>

</dd><dt><b>On exit</b>

	</dt><dd><p>R0 = Driver handle<br>
	R1 = Receive call address<br>
	R2 = Send address<br>
	R3 = MIDI Support R12</p>

</dd><dt><b>Interrupts</b>

	</dt><dd><p>Interrupt status is undefined<br>
	Fast interrupts are enabled</p>

</dd><dt><b>Processor mode</b>

	</dt><dd><p>Processor is in SVC mode</p>

</dd><dt><b>Re-entrancy</b>

	</dt><dd><p>SWI is not re-entrant</p>

</dd></dl></dd></dl><h4>
Use
</h4>

<p>Once called, the named driver will be installed into the MIDI Support
driver list.  Connections to and from this driver can be made in the usual
way.  Data can be sent from this driver by using the
<a href="http://www.somascape.org/riscos/esp/msfs.html#swi4EE84">MIDISupport_Send</a> SWI, and may be received by using
the <a href="http://www.somascape.org/riscos/esp/msfs.html#swi4EE85">MIDISupport_Receive</a> SWI.</p>

</td></tr></table><table class="upline"><tr><td><img src="6fd9fd24" width="100%" height="12" alt="---"></td>
 <td width="52"><a href="http://www.somascape.org/riscos/esp/msfs.html#contents" name="swi4EE84"><img src="6fda1404" border="0" align="middle" width="52" alt="Contents"></a></td>
 <td><img src="6fd9fd24" width="100%" height="12" alt="---"></td>
</tr></table><!-- ***************************************************************** --><table border="0" width="90%" align="center" cellpadding="0" cellspacing="0"><tr><td>

<h3>
MIDISupport_Send - &amp;4EE84
</h3>

<p>This is to enable data to be sent from a given driver to the
connections set up in MIDI Support.  It is primarily for use with the soft
drivers created with the <a href="http://www.somascape.org/riscos/esp/msfs.html#swi4EE83">MIDISupport_CreateDriver</a>
SWI.  However, it can be used to transmit data from any driver.</p>

<dl><dd><dl><dt><b>On entry</b>

	</dt><dd><p>R0 = Function code :</p>
	<dl><dd><p>0 = Send a byte<br>
		1 = Send a command<br>
		2 = Send a block of data</p>
	</dd></dl></dd><dd><p>R1 = Driver number<br>
	R2 = Data (or a pointer to data, if R0 = 2)<br>
	R3 = Length (number of bytes) of data (only required if R0 = 2)</p>

</dd><dt><b>On exit</b>

	</dt><dd><p>None</p>

</dd><dt><b>Interrupts</b>

	</dt><dd><p>Interrupt status is undefined<br>
	Fast interrupts are enabled</p>

</dd><dt><b>Processor mode</b>

	</dt><dd><p>Processor is in SVC mode</p>

</dd><dt><b>Re-entrancy</b>

	</dt><dd><p>SWI is not re-entrant</p>

</dd></dl></dd></dl><h4>
Use
</h4>

<p>This is used to transmit data from a driver whose number is given in
R1.  The data in R2 will depend on the function code used.  If the data is
in a block then R2 will contain a pointer to the data and R3 the length of
data to be transmitted.</p>

</td></tr></table><table class="upline"><tr><td><img src="6fd9fd24" width="100%" height="12" alt="---"></td>
 <td width="52"><a href="http://www.somascape.org/riscos/esp/msfs.html#contents" name="swi4EE85"><img src="6fda1404" border="0" align="middle" width="52" alt="Contents"></a></td>
 <td><img src="6fd9fd24" width="100%" height="12" alt="---"></td>
</tr></table><!-- ***************************************************************** --><table border="0" width="90%" align="center" cellpadding="0" cellspacing="0"><tr><td>

<h3>
MIDISupport_Receive - &amp;4EE85
</h3>

<p>This is to enable data to be received from a driver to an application. 
Drivers must have bits 1 and 2 of the driver flags set to indicate that
they are buffered receive drivers.</p>

<dl><dd><dl><dt><b>On entry</b>

	</dt><dd><p>R0 = Function code :</p>
	<dl><dd><p>0 = Return number of bytes available (not implemented)<br>
		1 = Receive a single byte or command</p>
	</dd></dl></dd><dd><p>R1 = Driver number<br>
	R2 = Data type (if R0 = 1) : 1 = Byte, 2 = Command</p>

</dd><dt><b>On exit</b>

	</dt><dd><p>R0 = Data &nbsp; (=0, if no more data)</p>

</dd><dt><b>Interrupts</b>

	</dt><dd><p>Interrupt status is undefined<br>
	Fast interrupts are enabled</p>

</dd><dt><b>Processor mode</b>

	</dt><dd><p>Processor is in SVC mode</p>

</dd><dt><b>Re-entrancy</b>

	</dt><dd><p>SWI is not re-entrant</p>

</dd></dl></dd></dl><h4>
Use
</h4>

<p>This is used to receive data from a driver whose number is given in R1. 
Only function code 1 is currently implemented.</p>

<p>If the Data Type is 'Command' (ie R2=2), the data has the usual <a href="http://www.somascape.org/riscos/esp/msfs.html#dataform">32-bit word format</a> : status byte in the lowest byte,
two optional data bytes, and with the highest byte indicating the number
of MIDI bytes (1 to 3).</p>

</td></tr></table><table class="upline"><tr><td><img src="6fd9fd24" width="100%" height="12" alt="---"></td>
 <td width="52"><a href="http://www.somascape.org/riscos/esp/msfs.html#contents" name="swi4EE86"><img src="6fda1404" border="0" align="middle" width="52" alt="Contents"></a></td>
 <td><img src="6fd9fd24" width="100%" height="12" alt="---"></td>
</tr></table><!-- ***************************************************************** --><table border="0" width="90%" align="center" cellpadding="0" cellspacing="0"><tr><td>

<h3>
MIDISupport_Connect - &amp;4EE86
</h3>

<p>This is to connect the send of one driver to the receive of
another.</p>

<p>A <a href="http://www.somascape.org/riscos/esp/msfs.html#msgs">Wimp message</a> is broadcast whenever this SWI is
called.</p>

<dl><dd><dl><dt><b>On entry</b>

	</dt><dd><p>R0 = Function code (0 = Read, 1 = Connect, 2 = Remove)<br>
	R1 = Source driver number<br>
	R2 = Destination driver number</p>

</dd><dt><b>On exit</b>

	</dt><dd><p>R0 = Pointer to source driver <a href="http://www.somascape.org/riscos/esp/msfs.html#connmaps">Connect Map</a></p>

</dd><dt><b>Interrupts</b>

	</dt><dd><p>Interrupt status is undefined<br>
	Fast interrupts are enabled</p>

</dd><dt><b>Processor mode</b>

	</dt><dd><p>Processor is in SVC mode</p>

</dd><dt><b>Re-entrancy</b>

	</dt><dd><p>SWI is not re-entrant</p>

</dd></dl></dd></dl></td></tr></table><table class="upline"><tr><td><img src="6fd9fd24" width="100%" height="12" alt="---"></td>
 <td width="52"><a href="http://www.somascape.org/riscos/esp/msfs.html#contents" name="swi4EE87"><img src="6fda1404" border="0" align="middle" width="52" alt="Contents"></a></td>
 <td><img src="6fd9fd24" width="100%" height="12" alt="---"></td>
</tr></table><!-- ***************************************************************** --><table border="0" width="90%" align="center" cellpadding="0" cellspacing="0"><tr><td>

<h3>
MIDISupport_ConnectName - &amp;4EE87
</h3>

<p>This is to connect the send of one driver to the receive of another. 
It performs the same functions as <b>MIDISupport_Connect</b> but with the
use of driver names rather than numbers.</p>

<p>A <a href="http://www.somascape.org/riscos/esp/msfs.html#msgs">Wimp message</a> is broadcast whenever this SWI is
called.</p>

<dl><dd><dl><dt><b>On entry</b>

	</dt><dd><p>R0 = Function code (0 = Read, 1 = Connect, 2 = Remove)<br>
	R1 = Name of source driver<br>
	R2 = Name of destination driver</p>

</dd><dt><b>On exit</b>

	</dt><dd><p>R0 = Pointer to source driver <a href="http://www.somascape.org/riscos/esp/msfs.html#connmaps">Connect Map</a></p>

</dd><dt><b>Interrupts</b>

	</dt><dd><p>Interrupt status is undefined<br>
	Fast interrupts are enabled</p>

</dd><dt><b>Processor mode</b>

	</dt><dd><p>Processor is in SVC mode</p>

</dd><dt><b>Re-entrancy</b>

	</dt><dd><p>SWI is not re-entrant</p>

</dd></dl></dd></dl></td></tr></table><table class="upline"><tr><td><img src="6fd9fd24" width="100%" height="12" alt="---"></td>
 <td width="52"><a href="http://www.somascape.org/riscos/esp/msfs.html#contents" name="swi4EE88"><img src="6fda1404" border="0" align="middle" width="52" alt="Contents"></a></td>
 <td><img src="6fd9fd24" width="100%" height="12" alt="---"></td>
</tr></table><!-- ***************************************************************** --><table border="0" width="90%" align="center" cellpadding="0" cellspacing="0"><tr><td>

<h3>
MIDISupport_GetAddress - &amp;4EE88
</h3>

<p>This is to obtain the send and receive address and the R12 value for
MIDI Support.  This call is not itself driver specific - the driver number
is passed in the required register when the code is subsequently
called.</p>

<dl><dd><dl><dt><b>On entry</b>

	</dt><dd><p>None</p>

</dd><dt><b>On exit</b>

	</dt><dd><p>R1 = Receive call address<br>
	R2 = Send, give data address<br>
	R3 = MIDI Support R12</p>

</dd><dt><b>Interrupts</b>

	</dt><dd><p>Interrupt status is undefined<br>
	Fast interrupts are enabled</p>

</dd><dt><b>Processor mode</b>

	</dt><dd><p>Processor is in SVC mode</p>

</dd><dt><b>Re-entrancy</b>

	</dt><dd><p>SWI is not re-entrant</p>

</dd></dl></dd></dl><h4>
Use
</h4>

<p>This is used by the <b>MIDIPlay</b> module to enable it to send data to
a driver which it knows by number.  In other words, data can be sent or
received by routines other than by the driver itself.</p>

</td></tr></table><table class="upline"><tr><td><img src="6fd9fd24" width="100%" height="12" alt="---"></td>
 <td width="52"><a href="http://www.somascape.org/riscos/esp/msfs.html#contents" name="swi4EE89"><img src="6fda1404" border="0" align="middle" width="52" alt="Contents"></a></td>
 <td><img src="6fd9fd24" width="100%" height="12" alt="---"></td>
</tr></table><!-- ***************************************************************** --><table border="0" width="90%" align="center" cellpadding="0" cellspacing="0"><tr><td>

<h3>
MIDISupport_Insert - &amp;4EE89
</h3>

<p>This allows data to be inserted directly into a driver's receive
buffer, without having to create a driver to send it from.</p>

<dl><dd><dl><dt><b>On entry</b>

	</dt><dd><p>R0 = Function code :</p>
	<dl><dd><p>0 = Insert a byte<br>
		1 = Insert a command<br>
		2 = Insert a block of data</p>
	</dd></dl></dd><dd><p>R1 = Driver number<br>
	R2 = Data (or a pointer to data, if R0 = 2)<br>
	R3 = Length (number of bytes) of data (only required if R0 = 2)</p>

</dd><dt><b>On exit</b>

	</dt><dd><p>None</p>

</dd><dt><b>Interrupts</b>

	</dt><dd><p>Interrupt status is undefined<br>
	Fast interrupts are enabled</p>

</dd><dt><b>Processor mode</b>

	</dt><dd><p>Processor is in SVC mode</p>

</dd><dt><b>Re-entrancy</b>

	</dt><dd><p>SWI is not re-entrant</p>

</dd></dl></dd></dl></td></tr></table><table class="upline"><tr><td><img src="6fd9fd24" width="100%" height="12" alt="---"></td>
 <td width="52"><a href="http://www.somascape.org/riscos/esp/msfs.html#contents" name="cmds"><img src="6fda1404" border="0" align="middle" width="52" alt="Contents"></a></td>
 <td><img src="6fd9fd24" width="100%" height="12" alt="---"></td>
</tr></table><!-- ***************************************************************** --><table border="0" width="90%" align="center" cellpadding="0" cellspacing="0"><tr><td>

<h2>
Commands
</h2>

<p>The MIDI Support module provides the following commands :</p>

<h4>MIDIMap</h4>

<dl><dd><p>This displays the currently installed drivers and their connections.</p>
</dd></dl><h4>MIDIConnect &lt;driver name&gt; &lt;driver name&gt;</h4>

<dl><dd><p>This allows the send of one driver to be connected to the receive of another.</p>
</dd></dl><h4>MIDIDisconnect &lt;driver name&gt; &lt;driver name&gt;</h4>

<dl><dd><p>This allows the send of one driver to be disconnected from the receive of another.</p>
</dd></dl></td></tr></table><table class="upline"><tr><td><img src="6fd9fd24" width="100%" height="12" alt="---"></td>
 <td width="52"><a href="http://www.somascape.org/riscos/esp/msfs.html#contents" name="serv"><img src="6fda1404" border="0" align="middle" width="52" alt="Contents"></a></td>
 <td><img src="6fd9fd24" width="100%" height="12" alt="---"></td>
</tr></table><!-- ***************************************************************** --><table border="0" width="90%" align="center" cellpadding="0" cellspacing="0"><tr><td>

<h2>
Service Calls
</h2>

<p>The following service calls are issued by the MIDI Support module.</p>

<p>MIDI Support uses the <b>Service_MIDI</b> (&amp;58) service number with
the following sub reason codes :</p>

<h4>Service_MIDISupportAlive &ndash; 4</h4>

<dl><dd><p>On receipt of this service call a driver should issue a call back to
	install itself in the MIDI Support module.</p>
</dd></dl><h4>Service_MIDISupportDying &ndash; 5</h4>

<dl><dd><p>On receipt of this service call a driver should shut down any interrupt
	activity and in particular stop any calls to the MIDI Support module.</p>
</dd></dl></td></tr></table><table class="upline"><tr><td><img src="6fd9fd24" width="100%" height="12" alt="---"></td>
 <td width="52"><a href="http://www.somascape.org/riscos/esp/msfs.html#contents" name="msgs"><img src="6fda1404" border="0" align="middle" width="52" alt="Contents"></a></td>
 <td><img src="6fd9fd24" width="100%" height="12" alt="---"></td>
</tr></table><!-- ***************************************************************** --><table border="0" width="90%" align="center" cellpadding="0" cellspacing="0"><tr><td>

<h2>
WIMP Messages
</h2>

<p>The following Wimp messages are broadcast to all active tasks in
response to the associated SWI being called, thus providing a mechanism
for applications to keep in sync with the state of the MIDI Support
system.</p>

<h4>Install &ndash; &amp;4EE80</h4>

<p>This message is broadcast whenever the <a href="http://www.somascape.org/riscos/esp/msfs.html#swi4EE80">MIDISupport_InstallDriver</a>
SWI is called.</p>

<dl><dd><p>msgBlk!20 = Driver number<br>
	msgBlk!24 = Maximum driver limit</p>
</dd></dl><h4>Remove &ndash; &amp;4EE81</h4>

<p>This message is broadcast whenever the <a href="http://www.somascape.org/riscos/esp/msfs.html#swi4EE81">MIDISupport_RemoveDriver</a>
SWI is called.</p>

<dl><dd><p>msgBlk!20 = Driver number<br>
	msgBlk!24 = Maximum driver limit</p>
</dd></dl><h4>Connect &ndash; &amp;4EE86</h4>

<p>This message is broadcast whenever either of the <a href="http://www.somascape.org/riscos/esp/msfs.html#swi4EE86">MIDISupport_Connect</a>
or <a href="http://www.somascape.org/riscos/esp/msfs.html#swi4EE87">MIDISupport_ConnectName</a> SWIs are called.</p>

<dl><dd><p>msgBlk!20 = Source driver number<br>
	msgBlk!24 = Destination driver number</p>
	<dl><dd><p>Bits 30 and 31 give the Function code (1 = Connect, 2 = Remove)</p>
	</dd></dl></dd><dd><p>msgBlk!28 = Pointer to source driver <a href="http://www.somascape.org/riscos/esp/msfs.html#connmaps">Connect Map</a></p>
</dd></dl></td></tr></table><table class="upline"><tr><td><img src="6fd9fd24" width="100%" height="12" alt="---"></td>
 <td width="52"><a href="http://www.somascape.org/riscos/esp/msfs.html#top"><img src="6fda1404" border="0" align="middle" width="52" alt="Top"></a></td>
 <td><img src="6fd9fd24" width="100%" height="12" alt="---"></td>
</tr></table></body></html>
