MIDI driver interface

This document describes how to make a midi-driver for the camd.library.

This is just a short explanation how things works right now. Everything might change in the future, I guess.

CAMD is designed in such a way that writing device drivers should be very easy. Looking at the source for the debug-driver placed in AROS/workbench/devs/midi should explain the most, but some additional and more detailed information comes here.

First, the new Camd.library will be described as AROS' Camd.library. However, this Camd.library also works for AmigaOS, and everything described here goes for the AmigaOS version of this Camd.library too. Beware that camd midi-device drivers made as described below will not work with the original Camd.library as the file-format is a bit changed. Luckily enough though, the new Camd.library is also able to use camd midi-device drivers designed for the old Camd.libraries driver-format (with the help of a dirty trick). (AROS' Camd.library does not handle the old format, only the AmigaOs/SASC - version).

Camd.library does as its first thing in the init-routine, search thru all files in Devs:Midi/ and load all possible midi-device drivers. Therefore, the drivers must of course be placed in the Devs:Midi directory.

The central point of a midi-device driver is the MidiDeviceData struct which you must put somewhere in your binary. Camd.library searches thru your file to find out where the structure is placed. So there are some rules you have to follow to let Camd.library recognize the driver as legal.

The structure looks like this (taken from Include/devs/camddevices.h):

struct MidiDeviceData
{
    ULONG Magic;
    char *Name;
    char *IDString;
    UWORD Version;
    UWORD Revision;

    BOOL (ASM *Init)(
        REG(a6) APTR SysBase
     );

    void (*Expunge)(void);

    struct MidiPortData *(ASM *OpenPort)(
        REG(a3) struct MidiDeviceData *data,
        REG(d0) LONG portnum,
        REG(a0) ULONG (* ASM transmitfunc)(APTR REG(a2) userdata),
        REG(a1) void (* ASM recievefunc)(UWORD REG(d0) input,APTR REG(a2) userdata),
        REG(a2) APTR userdata
    );

    void (ASM *ClosePort)(
        REG(a3) struct MidiDeviceData *data,
        REG(d0) LONG portnum
    );

    UBYTE NPorts;
    UBYTE Flags;
};

Magic

This one must contain the MDD_MAGIC constant, which is also found in Include/devs/midi/camddevices.h.

Name

Must contain the name of your file. Ie. if the name of the driver-file is "Pinnacle-Fiji", 'Name' must also be a pointer to a string containing "Pinnacle-Fiji". If 'Name' and the name of the file doesn't match, the driver will not be loaded. (However, this is not a requirement if 'Flags' is 0, more about that later).

IDString

A pointer to a string describing your driver.

Version

16 bit unsigned integer containing the version of the driver.

Revision

16 bit unsigned integer containing the revision of the driver.

Init

Must contain a pointer to a legal function. The function is called first after the driver is loaded into memory. The function is called with sysbase as the only argument and must return FALSE if you failed to do anything important. Else TRUE. If FALSE is returned, the 'Expunge'-function will not be called, so you better free any resources you have allocated before returning. The 'Init'-function is normally called from the Camd.libraries 'Init'-function, but due to some, hmm, bad design in AROS/Camd.library; you shouldn't be to sure the Forbid-state is not broken, so please call Forbid()/Permit() if that is needed.

In this function you may also set the 'Expunge', 'OpenPort', 'ClosePort' and 'NPorts' attributes if you want to. If they was not set before, you must set them now. This feature might be of use if you don't know how many ports are available before running. (As an example, if you want to make a drivers for Turtle Beachs pinnacle and fiji, instead of making two drivers, you just check if the device is pinnacle or fiji, and set 'NPorts' one or two higher than you would if it were a fiji, since pinnacle and fiji are very equal besides that pinnacle have a built-in midi-synth and a possibly add-on synth-card.)

Expunge

This function is called right before the driver is unloaded from memory. It is normally called from Camd.libraries Expunge-routine, but don't trust the Forbid()-state not to be broken.

OpenPort

Pointer to a function that is called from Camd.library first time applications wants to use a specified port in your driver. It provides the following arguments:

'data' I guess you want to use this one if you don't want to have any global datas in your driver. It points to your MidiDeviceData struct.

'portnum' The number of the port that wants to be used.

'transmitfunc' A pointer to a function you call when there is midi-data waiting to be sent thru the port. Important note: 'transmitfunc' is a bit single-threaded, ie. having two visitors simultaneously with the same 'userdata' will not work. But I guess thats pretty obvious... Interrupts may be disabled when calling this one. More about the 'transmitfunc' below.

'receiverfunc' A pointer to a function you call when there is midi-data coming from the port you want to distribute to Camd.library. 'receiverfunc' is a bit single-threaded too, so no more than one visitor at the time with the same 'userdata' (shouldn't be necesarry to point out though). Interrupts can not be disabled when calling because it signals a task. The 'input'-argument is the midi-byte you want to send to camd. It is not a message, just a single byte. If bit 8 is set, you tell Camd.library that there is overflow on the port. If your midi-device uses running status to lower the data-stream (which is almost always the case), you don't have to worry about that, since the receiverfunc in Camd.library handles running status.

'userdata' Pointer to unique data for this port that must be provided when calling the functions pointed to by 'transmitfunc' and 'receiverfunc'.

About the 'transmitfunc' and 'receiverfunc' arguments. They always points to the same functions, and could just as well have been provided with the Init-function. However, this is how Camd.library was designed from the start, and will probably not be changed. But it is safe to keep just two pointers in your driver containing 'transmitfunc' and 'receiverfunc'. See the debug-driver-source for example. And, most important, they are both legal to be called from interrupts.

ClosePort

A pointer to a function that is called when the last application that is using your port tells Camd.library that it doesn't need the port anymore.

NPorts

Number of ports the driver provides. May be set directly at compiling-time, or in the Init-function. If bit 0 in 'Flags' is not set, 'NPorts' must be set directly at compiling-time. (bit 0 in 'Flags' are only for the old driver-format, and you probably don't want to use that when reading this doc-file.)

Flags

Only one flag is used for now, and that is bit 0. Don't set any other flags. If bit 0 is NOT set, camd.library then knows that this is a driver of the old type. However, that mode is not very fit for the new camd.library, so please set this flag.

'OpenPort' should return a pointer to a MidiPortData struct. If the port could not be opened, you return NULL.

The MidiPortData struct looks like this:

struct MidiPortData
{
    void (* ASM ActivateXmit)(ULONG REG(d0) portnum);
};

'ActivateXmit' contains a pointer to a function in your driver that is called from Camd.library whenever Camd.library has some midi-data it wants to be distributed. In other words, when Camd.library calls this function, it is time for you to as soon as possible call the 'transmit'-function to get mididata. Here is an example how you can do that:

while((data=(transmitfunc)(UserData[portnum-1])!=0x100)
    SendDataToPort(portnum-1,data);

('UserData' is here an array of 'usedata's. 'userdata' is provided when 'OpenPort' is called)

As you see, there might be more than one byte that is waiting to be picked up (that is actually the common case), and when there is no more data to be picked up, 'transmitfunc' returns 0x100.

Unlike the original driver-format, its no harm calling 'transmitfunc' even though there are no more data waiting to be picked up. (Thats the most important change between the old and the new driver-format: How on earth are you able to know there aren't any more datas to be picked up for all possible situations?)

Also beware that 'ActivateXmit' might be called even if there are no more datas to be picked up, and also while you are currently picking up data with another task or interrupt. But luckily, 'ActivateXmit' will not be called again until you return, so its single-threaded per port.

Note that 'transmitfunc' returns data that is optimized with running status, so if you are not sending data that is going to be directly transmitted via a midi-cable, or the place you are sending the data is in some way not able to handle running-status, you have to manually keep track of running status. But if this is the case, its probably better if you write a normal Camd.library application that makes a new cluster and you receive datas via a hook, which you again distributes to wherever you want them. Then you'll get all status-bytes. (Applications using Camd.library don't see any difference between a normal driver and the driver-technique described here)