MIDISupport
Functional Specification

( M1002/FS )

Issue 7
01 Mar 2003

Authors

Andy Pierson
David Lenthall

ESP Music

Introduction

The purpose of this module is summarised as follows :

  • Full implementation of MIDI Ports 0-3
  • Use of multiple cards allowing for > 16 channel MIDI
  • PC MIDI Input
  • Software MIDI devices e.g. ESP's MIDI Synthesizer
  • Faster data transfer
  • Built in software MIDI Thru
  • Advanced mapping facilities
  • Alternative hardware drivers such as a serial port driver for external sound modules
  • Data filters
  • MIDI Time Code support

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.

Mapping facilities are provided by both SWIs and Commands to allow pre-configuration of the MIDI drivers upon startup. In addition a mapping application !MidiMan is available that allows MIDI data routes to be selected, viewed and pre-configured.

Drivers

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.

Driver Flags

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

Bit 0 : Driver can send MIDI data
Bit 1 : Driver can receive MIDI data
Bit 2 : Driver requires MIDI Support to buffer receive data
Bit 3 : Driver can receive un-buffered MIDI data as a command

Related SWIs

Data Transfer

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

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

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.

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.

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.

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

Connect Maps

Each driver has a Connect Map 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.

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.

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.

The current driver limit (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.

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.

The current driver limit is also returned by the Install and Remove Wimp messages, 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.

Related SWIs

Data Format

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 &nnd2d1sc where :

&nn is the number of bytes in the command,
&d2 and &d1 are up to 2 data bytes (&d1 being the first), and
&sc is the status and channel value.

Hence, the lowest 1, 2 or 3 bytes are the MIDI data, and the top byte is the byte-count.

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.

An extension of the MIDI_TxCommand SWI is provided to allow applications to send System Exclusive data as a single SWI.

Use

This module is currently supported by the following products :

  • Acorn AKA16/12 MIDI Interface
  • Audio Dynamics DMI50
  • CC Eagle interface
  • CC MIDI Max interface
  • Morley MIDI interface
  • ESP Parallel Port MIDI
  • ESP Serial Port MIDI
  • ESP MIDI Synthesizer
  • !PC MIDI input/output
  • Acorn TimeCode
  • MelIDI sequencer

SWI Interface

MIDISupport_InstallDriver - &4EE80

This SWI is used to install a MIDI driver into the MIDI Support module.

A Wimp message is broadcast whenever this SWI is called.

On entry
R0 = Driver flags
R1 = Address of Driver Information call
R2 = Address of Driver Initialisation address
R3 = Address of Driver Receive call address
R4 = R12 value
On exit
If unsuccessful, V flag is set and R0 points to a SWI error block.
If successful, V flag is clear and
R0 = Driver number (starting from 1)
R1 = Address of MIDI Support Receive routine
R2 = Address of MIDI Support GiveData routine
R3 = MIDI Support R12 address
Interrupts
Interrupt status is undefined
Fast interrupts are enabled
Processor mode
Processor is in SVC mode
Re-entrancy
SWI is not re-entrant

Use

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.

DriverInformation

This is called to provide information for display by MIDI mapping applications.

On entry
None
On exit
R0 = Pointer to driver name
R1 = Driver version number
R2 = Pointer to driver data
Interrupts
Interrupt status is undefined
Fast interrupts are enabled
Processor mode
Processor is in SVC mode

DriverInitialisation

This is called to call the Driver to perform any initialisation on startup or reset.

On entry
None
On exit
None
Interrupts
Interrupt status is undefined
Fast interrupts are enabled
Processor mode
Processor is in SVC mode

DriverReceive

This call is used differently depending on the driver's flags.
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.
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.

On entry
For buffered data: none
For direct data: R0 = byte or command
On exit
None
Interrupts
Interrupts are disabled
Fast interrupts are enabled
Processor mode
Processor is in IRQ mode

MIDISupportReceive

This is called to pass data from the driver into the MIDI Support module.

On entry
R0 = Data as command or byte
R1 = Driver number
On exit
None
Interrupts
Interrupts are disabled
Fast interrupts are enabled
Processor mode
Processor is in SVC mode

MIDISupportGiveData

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.

On entry
R0 = Function code :
2 = Give command
1 = Give byte
0 = Reset
-1 = Give current buffer status
R1 = Driver number
On exit
R0 = Data   (=0, if no more data)
Interrupts
Interrupts are disabled
Fast interrupts are enabled
Processor mode
Processor is in IRQ mode

MIDISupport_RemoveDriver - &4EE81

This SWI is used to remove a specific driver.

A Wimp message is broadcast whenever this SWI is called.

On entry
R1 = Driver number
On exit
If unsuccessful, V flag is set and R0 points to a SWI error block.
Interrupts
Interrupt status is undefined
Fast interrupts are enabled
Processor mode
Processor is in SVC mode
Re-entrancy
SWI is not re-entrant

MIDISupport_DriverInfo - &4EE82

This SWI is used to provide information about a specific driver.

On entry
R1 = Driver number
On exit
If successful, V flag is clear and
R0 = Pointer to driver name
R1 = Driver version
R2 = Pointer to driver date
R3 = Driver flags
R4 = Pointer to driver Connect Map
R5 = Maximum driver limit

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

Interrupts
Interrupt status is undefined
Fast interrupts are enabled
Processor mode
Processor is in SVC mode
Re-entrancy
SWI is not re-entrant

Use

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.

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.

MIDISupport_CreateDriver - &4EE83

This is to enable simple software drivers to be created.

On entry
R0 = Driver flags
R1 = Name of driver
R2 = Version number for driver
R3 = Date for driver
On exit
R0 = Driver handle
R1 = Receive call address
R2 = Send address
R3 = MIDI Support R12
Interrupts
Interrupt status is undefined
Fast interrupts are enabled
Processor mode
Processor is in SVC mode
Re-entrancy
SWI is not re-entrant

Use

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 MIDISupport_Send SWI, and may be received by using the MIDISupport_Receive SWI.

MIDISupport_Send - &4EE84

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 MIDISupport_CreateDriver SWI. However, it can be used to transmit data from any driver.

On entry
R0 = Function code :
0 = Send a byte
1 = Send a command
2 = Send a block of data
R1 = Driver number
R2 = Data (or a pointer to data, if R0 = 2)
R3 = Length (number of bytes) of data (only required if R0 = 2)
On exit
None
Interrupts
Interrupt status is undefined
Fast interrupts are enabled
Processor mode
Processor is in SVC mode
Re-entrancy
SWI is not re-entrant

Use

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.

MIDISupport_Receive - &4EE85

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.

On entry
R0 = Function code :
0 = Return number of bytes available (not implemented)
1 = Receive a single byte or command
R1 = Driver number
R2 = Data type (if R0 = 1) : 1 = Byte, 2 = Command
On exit
R0 = Data   (=0, if no more data)
Interrupts
Interrupt status is undefined
Fast interrupts are enabled
Processor mode
Processor is in SVC mode
Re-entrancy
SWI is not re-entrant

Use

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

If the Data Type is 'Command' (ie R2=2), the data has the usual 32-bit word format : status byte in the lowest byte, two optional data bytes, and with the highest byte indicating the number of MIDI bytes (1 to 3).

MIDISupport_Connect - &4EE86

This is to connect the send of one driver to the receive of another.

A Wimp message is broadcast whenever this SWI is called.

On entry
R0 = Function code (0 = Read, 1 = Connect, 2 = Remove)
R1 = Source driver number
R2 = Destination driver number
On exit
R0 = Pointer to source driver Connect Map
Interrupts
Interrupt status is undefined
Fast interrupts are enabled
Processor mode
Processor is in SVC mode
Re-entrancy
SWI is not re-entrant

MIDISupport_ConnectName - &4EE87

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

A Wimp message is broadcast whenever this SWI is called.

On entry
R0 = Function code (0 = Read, 1 = Connect, 2 = Remove)
R1 = Name of source driver
R2 = Name of destination driver
On exit
R0 = Pointer to source driver Connect Map
Interrupts
Interrupt status is undefined
Fast interrupts are enabled
Processor mode
Processor is in SVC mode
Re-entrancy
SWI is not re-entrant

MIDISupport_GetAddress - &4EE88

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.

On entry
None
On exit
R1 = Receive call address
R2 = Send, give data address
R3 = MIDI Support R12
Interrupts
Interrupt status is undefined
Fast interrupts are enabled
Processor mode
Processor is in SVC mode
Re-entrancy
SWI is not re-entrant

Use

This is used by the MIDIPlay 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.

MIDISupport_Insert - &4EE89

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

On entry
R0 = Function code :
0 = Insert a byte
1 = Insert a command
2 = Insert a block of data
R1 = Driver number
R2 = Data (or a pointer to data, if R0 = 2)
R3 = Length (number of bytes) of data (only required if R0 = 2)
On exit
None
Interrupts
Interrupt status is undefined
Fast interrupts are enabled
Processor mode
Processor is in SVC mode
Re-entrancy
SWI is not re-entrant

Commands

The MIDI Support module provides the following commands :

MIDIMap

This displays the currently installed drivers and their connections.

MIDIConnect <driver name> <driver name>

This allows the send of one driver to be connected to the receive of another.

MIDIDisconnect <driver name> <driver name>

This allows the send of one driver to be disconnected from the receive of another.

Service Calls

The following service calls are issued by the MIDI Support module.

MIDI Support uses the Service_MIDI (&58) service number with the following sub reason codes :

Service_MIDISupportAlive – 4

On receipt of this service call a driver should issue a call back to install itself in the MIDI Support module.

Service_MIDISupportDying – 5

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.

WIMP Messages

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.

Install – &4EE80

This message is broadcast whenever the MIDISupport_InstallDriver SWI is called.

msgBlk!20 = Driver number
msgBlk!24 = Maximum driver limit

Remove – &4EE81

This message is broadcast whenever the MIDISupport_RemoveDriver SWI is called.

msgBlk!20 = Driver number
msgBlk!24 = Maximum driver limit

Connect – &4EE86

This message is broadcast whenever either of the MIDISupport_Connect or MIDISupport_ConnectName SWIs are called.

msgBlk!20 = Source driver number
msgBlk!24 = Destination driver number
Bits 30 and 31 give the Function code (1 = Connect, 2 = Remove)
msgBlk!28 = Pointer to source driver Connect Map