|newpage|

MIDI
====

The MIDI thread implements a 31250 baud UART (8-N-1) for both input and output.
It uses a single dedicated thread which performs multiple functions:

    - UART transmit (tx) peripheral.
    - UART transmit FIFO of 1024 bytes (may be configured by the user).
    - Decoding of USB MIDI message to bytes.
    - UART receive (rx) peripheral.
    - Packing of received MIDI bytes into USB MIDI messages/events.

It is connected via a channel to the Endpoint Buffer thread meaning that it can be placed on any
`xcore` tile in the system subject to resource availability.

The Endpoint Buffer thread implements the two Bulk endpoints (one In and one Out) as well as interacting with small, shared-memory, FIFOs for each endpoint.

On receiving 32-bit USB MIDI events from the Endpoint Buffer thread over the channel, the MIDI thread parses these and translates them to 8-bit MIDI messages which are sent
out over the UART. Up to 1024 bytes may be buffered by the MIDI task for outgoing messages in the default configuration. If the outgoing buffer is full then it will cause the USB endpoint to be NACKed which provides flow control in the case that the host application sends messages faster than the UART can transmit them. This is important because the USB bandwidth far exceeds the MIDI UART bandwidth by many orders of magnitude. The combination of buffering and flow control ensures outgoing messages are not dropped during normal operation.

Incoming 8-bit MIDI messages from the UART receiver are packed into 32-bit USB MIDI events and passed on to the Endpoint Buffer thread. Since the rate of ingress
to the MIDI port is tiny in comparison to the host USB bandwidth, no buffering is required in the MIDI thread and the MIDI events are always forwarded on directly to USB immediately.

All MIDI message types are supported including `Sysex` (MIDI System Exclusive) strings allowing custom function such as bank updates and patches, backup and device firmware upgrade (DFU) where supported by the MIDI device.

The MIDI thread is implemented in the file ``usb_midi.xc`` and the USB buffering is handled in the file ``ep_buffer.xc``.

