diff options
Diffstat (limited to 'static/netbsd/man4/midi.4')
| -rw-r--r-- | static/netbsd/man4/midi.4 | 771 |
1 files changed, 771 insertions, 0 deletions
diff --git a/static/netbsd/man4/midi.4 b/static/netbsd/man4/midi.4 new file mode 100644 index 00000000..3e33ae5f --- /dev/null +++ b/static/netbsd/man4/midi.4 @@ -0,0 +1,771 @@ +.\" $NetBSD: midi.4,v 1.32 2017/07/03 21:30:58 wiz Exp $ +.\" +.\" Copyright (c) 1999-2017 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Lennart Augustsson and Chapman Flack. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd April 28, 2017 +.Dt MIDI 4 +.Os +.Sh NAME +.Nm midi +.Nd device-independent MIDI driver layer +.Sh SYNOPSIS +.Cd "midi* at midibus?" +.Cd "midi* at pcppi?" +.Cd "pseudo-device sequencer" +.Pp +.In sys/types.h +.In sys/midiio.h +.Sh DESCRIPTION +The +.Nm +driver is the machine independent layer over anything that can +source or sink a +.Tn MIDI +data stream, whether a physical +.Tn "MIDI IN" +or +.Tn "MIDI OUT" +jack on a soundcard, cabled to some external synthesizer or input controller, +an on-board programmable tone generator, or a single jack, synthesizer, or +controller component within a complex +.Tn USB +or +.Tn IEEE1394 +.Tn MIDI +device that has several +such components and appears as several +.Tn MIDI +streams. +.Ss Concepts +One +.Tn MIDI +data stream is a unidirectional stream of +.Tn MIDI +messages, as could be carried over one +.Tn MIDI +cable in the +.Tn "MIDI 1.0" +specification. +Many +.Tn MIDI +messages +carry a four-bit channel number, creating up to 16 +.Tn MIDI +channels within a single +.Tn MIDI +stream. +There may be multiple consumers of a +.Tn MIDI +stream, each configured +to react only to messages on specific channels; the sets of channels different +consumers react to need not be disjoint. +Many modern devices such as multitimbral keyboards and tone generators +listen on all 16 channels, or may be viewed as collections of 16 +independent consumers each listening on one channel. +.Tn MIDI +defines some messages that take no channel number, and +apply to all consumers of the +stream on which they are sent. +For an inbound stream, +.Nm +is a promiscuous +receiver, capturing all messages regardless of channel number. +For an outbound stream, the writer can specify a channel number +per message; there is no notion of binding the stream to one +destination channel in advance. +.Pp +A single +.Nm +device instance is the endpoint of one outbound stream, one +inbound stream, or one of each. +In the third case, the write and read sides are independent +.Tn MIDI +streams. +For example, a soundcard driver may map its +.Tn "MIDI OUT" +and +.Tn "MIDI IN" +jacks to the write and read sides of a single device instance, but +those jacks can be cabled to completely different pieces of gear. +Information from +.Xr dmesg 8 , +and a diagram of any external +.Tn MIDI +cabling, will help clarify the mapping. +.Ss "Underlying drivers and MIDI protocol" +Drivers +.Nm +can attach include soundcard drivers, many of +which support a +.Tn UART +resembling Roland's +.Tn MPU401 +and handled by +.Xr mpu 4 , +.Tn "USB MIDI" +devices via +.Xr umidi 4 , +and on-board devices that can make sounds, +whether a lowly +.Tn PC +speaker or a Yamaha +.Tn OPL . +Serial port and +.Tn IEEE1394 +connections are currently science fiction. +.Pp +The +.Tn MIDI +protocol permits some forms of message compression such as running +status and hidden note-off. +Received messages on inbound streams are always canonicalized by +.Nm +before presentation to higher layers. +Messages for transmission are accepted by +.Nm +in any valid form. +.Ss "Device access" +Access to +.Nm +device instances can be through the raw device nodes, +.Pa /dev/rmidiN , +or through the sequencer, +.Pa /dev/music . +.Ss "Raw MIDI access" +A +.Pa /dev/rmidiN +device supports +.Xr read 2 , +.Xr write 2 , +.Xr ioctl 2 , +.Xr select 2 Ns / Ns +.Xr poll 2 +and the corresponding +.Xr kevent 2 +filters, +and may be opened +only when it is not already open. +It may be opened in +.Dv O_RDONLY , +.Dv O_WRONLY , +or +.Dv O_RDWR +mode, but a later +.Xr read 2 +or +.Xr write 2 +will return \-1 if the device has no associated +input or output stream, respectively. +.Pp +Bytes written are passed as quickly as possible to the underlying driver +as complete +.Tn MIDI +messages; a maximum of two bytes at the end of a +.Xr write 2 +may remain buffered if they do not complete a message, until +completed by a following +.Xr write 2 . +.Pp +A +.Xr read 2 +will not block or return +.Er EWOULDBLOCK +when it could immediately return any nonzero count, and +.Tn MIDI +messages received are available to +.Xr read 2 +as soon as they are complete, +with a maximum of two received bytes remaining buffered if they do not +complete a message. +.Pp +As all +.Tn MIDI +messages are three bytes or fewer except for System Exclusive, +which can have arbitrary length, these rules imply that System Exclusive +messages are the only ones of which some bytes can be delivered before +all are available. +.Pp +System Realtime messages are passed with minimum delay in either direction, +ahead of any possible buffered incomplete message. +As a result, they will never interrupt any +.Tn MIDI +message except possibly System Exclusive. +.Pp +A +.Xr read 2 +with a buffer large enough to accommodate the first complete +message available will be satisfied with as many complete messages as +will fit. +A buffer too small for the first complete +message will be filled to capacity. +Therefore, an application that reads from an +.Pa rmidi +device with buffers of three bytes or larger need never parse +across read boundaries to assemble a received message, except possibly in +the case of a System Exclusive message. +However, if the application reads through a buffering layer such as +.Xr fread 3 , +this property will not be preserved. +.Pp +The +.Nm +driver itself supports the +.Xr ioctl 2 +operations +.Dv FIOASYNC , +.Dv FIONBIO , +and +.Dv FIONREAD . +Underlying devices may support others. +The value returned for +.Dv FIONREAD +reflects the size in bytes of complete messages +(or System Exclusive chunks) ready to read. +If the +.Xr ioctl 2 +returns +.Va n +and a +.Xr read 2 +of size +.Va n +is issued, +.Va n +bytes will be read, but if a +.Xr read 2 +of +size +.Va m +< +.Va n +is issued, fewer than +.Va m +bytes may be read if +.Va m +does not fall +on a message/chunk boundary. +.Pp +Raw +.Tn MIDI +access can be used to receive bulk dumps from synthesizers, download +bulk data to them, and so on. +Simple patching of one device to another can be +done at the command line, as with +.Dl $ cat -u 0<>/dev/rmidi0 1>&0 +which will loop all messages received on the input stream of +.Pa rmidi0 +input stream back to its output +stream in real time. +However, an attempt to record and play back music with +.Dl $ cat /dev/rmidiN >foo; cat foo >/dev/rmidiN +will be disappointing. +The file +.Pa foo +will contain all of the notes that were played, but because +.Tn MIDI +messages carry +no explicit timing, the +.Sq "playback" +will reproduce them all at once, as fast as +they can be transmitted. +To preserve timing information, the sequencer device can be used. +.Ss "Active Sensing" +The +.Tn MIDI +protocol includes a keepalive function called Active Sensing. +In any receiver that has +.Em not +received at least one Active Sense +.Tn MIDI +message, the +feature is suppressed and no timeout applies. +If at least one such message has +been received, the lapse of any subsequent 300 ms interval without receipt of +any message reflects loss of communication, and the receiver should silence any +currently sounding notes and return to non-Active-Sensing behavior. +A sender using Active Sensing generally avoids 300 ms gaps in +transmission by sending Active Sense messages (which have no other +effect) as needed when there is no other traffic to send in the +interval. +This feature can be important for +.Tn MIDI , +which relies on separate Note On and Note Off messages, to avoid notes stuck on +indefinitely if communication is interrupted before a Note Off +message arrives. +.Pp +This protocol is supported in +.Nm . +An outbound stream will be kept alive +by sending Active Sense messages as needed, beginning after any real +traffic is sent on the stream, and continuing until the stream is closed. +On an inbound stream, if any Active Sense has been received, then a process +reading an +.Pa rmidi +device will see an end-of-file indication if the input timeout elapses. +The stream remains open, the driver reverts to enforcing no timeout, and the +process may continue to read for more input. +Subsequent receipt of an +Active Sense message will re-arm the timeout. +As received Active Sense messages are handled by +.Nm , +they are not included among messages read from the +.Pa /dev/rmidiN +device. +.Pp +These rules support end-to-end Active Sensing behavior in simple cases +without special action in an application. +For example, in +.Dl $ cat -u /dev/rmidi0 >/dev/rmidi1 +if the input stream to +.Pa rmidi0 +is lost, the +.Xr cat 1 +command exits; on the +.Xr close 2 +of +.Pa rmidi1 , +.Nm +ceases to send Active Sense messages, and the receiving +device will detect the loss and silence any outstanding notes. +.Ss "Access through the sequencer" +To play music using the raw +.Tn MIDI +.Tn API +would require an application to +issue many small writes with very precise timing. +The sequencer device, +.Pa /dev/music , +can manage the timing of +.Tn MIDI +data in the kernel, to avoid +such demanding real-time constraints on a user process. +.Pp +The +.Pa /dev/music +device can be opened only when it is not already open. +When opened, the sequencer internally opens all +.Tn MIDI +instances existing +in the system that are not already open at their raw nodes; any attempts +to open them at their raw nodes while the sequencer is open will fail. +All access to the corresponding +.Tn MIDI +streams will then be through the +sequencer. +.Pp +Reads and writes of +.Pa /dev/music +pass eight-byte event structures defined in +.In sys/midiio.h +(which see for their documentation and examples of use). +Some events correspond to +.Tn MIDI +messages, and carry an integer +.Va device +field to identify one of the +.Tn MIDI +devices opened by the sequencer. +Other events carry timing information interpreted or generated by the +sequencer itself. +.Pp +A message received on an input stream is wrapped in a sequencer event +along with the device index of the stream it arrived on, and queued for +the reader of +.Pa /dev/music . +If a measurable time interval passed since the +last preceding message, a timing event that represents a delay for that interval +is queued ahead of the received event. +The sequencer handles output events by +interpreting any timing event, and routing any +.Tn MIDI +message event at the proper time to +an underlying output stream according to its +.Va device +index. +Therefore +.Dl $ cat /dev/music >foo; cat foo >/dev/music +can be expected to capture and reproduce an input performance including +timing. +.Pp +The process of playing back a complex +.Tn MIDI +file is illustrated below. +The file may contain several tracks\(emfour, in this example\(emof +.Tn MIDI +events, each marked with a device index and a time stamp, that may +overlap in time. +In the example, +.Va a , +.Va b , +and +.Va c +are device indices of +the three output +.Tn MIDI +streams; the left-hand digit in each input event represents a +.Tn MIDI +channel on the selected stream, and the right-hand digit represents +a time for the event's occurrence. +As illustrated, the input tracks are not firmly associated with +output streams; any track may contain events for any stream. +.Bd -literal + | | a2|4 | + a0|3 | c1|3 c0|3 + | b0|2 b1|2 | + | b1|1 | c0|1 + a0|0 | b0|0 | + v v v v + +---------------------------+ + | merge to 1 ordered stream | + | user code, eg midiplay(1) | + +---------------------------+ + b1|2 + b0|2 + c0|1 + b1|1 + b0|0 + a0|0 + v + _______+-------------+_______user + | /dev/music | kernel + | (sequencer) | + +-------------+ + | 1 0 + +-----' | '-----. + 0 0 | + v v v + +-------+ +--------+ +---------+ + |midi(4)| |midi(4) | |midi(4) | + |rmidia | |rmidib | |rmidic | + +-------+ +--------+ +---------+ + | mpu(4)| |umidi(4)| |midisyn | + +-------+ +--------+ +---------+ + | HW | | | opl(4) | + | MIDI | U +---------+ + | UART | S | internal| + +-------+ B | tone | + | | |generator| + v | +---------+ + external v + MIDI device external + MIDI device +.Ed +.Pp +A user process must merge the tracks into a single stream of sequencer +.Tn MIDI +and timing events in order by desired timing. +The sequencer obeys the timing events and distributes the +.Tn MIDI +events to the three destinations, +in this case two external devices connected to a sound card +.Tn UART +and a +.Tn USB +interface, and an +.Tn OPL +tone generator on a sound card. +.Sh NOTES +Use of +.Xr select 2 Ns / Ns +.Xr poll 2 +with the sequencer is supported, however, there is no guarantee that a +.Xr write 2 +will not block or return +.Er EWOULDBLOCK +if it begins with a timer-wait event, even if +.Xr select 2 Ns / Ns +.Xr poll 2 +reported the sequencer writable. +.Pp +The delivery of a realtime message ahead of buffered bytes of an incomplete +message may cause the realtime message to seem, in a saved byte stream, to have +arrived up to 640 us earlier than it really did, at +.Tn MIDI +1.0 data rates. +Higher data rates make the effect less significant. +.Pp +Another sequencer device, +.Pa /dev/sequencer , +is provided only for backward +compatibility with an obsolete +.Tn OSS +interface in which some sequencer events +were four-byte records. +It is not further documented here, and the +.Pa /dev/music +.Tn API +should be used in new code. +The +.Pa /dev/sequencer +emulation is implemented only for writing, and that might not be complete. +.Sh IMPLEMENTATION NOTES +Some hardware devices supporting +.Nm +lack transmit-ready interrupts, and some have the capability in +hardware but currently lack driver support. +They can be recognized by the annotation +.Li "(CPU-intensive output)" +in +.Xr dmesg 8 . +While suitable for music playback, they may have an objectionable impact on +system responsiveness during bulk transmission such as patch downloads, and +are best avoided for that purpose if other suitable devices are present. +.Pp +Buffer space in +.Nm +itself is adequate for about 200 ms of traffic at +.Tn "MIDI 1.0" +data rates, per stream. +.Pp +Event counters record bytes and messages discarded because of protocol +errors or buffer overruns, and can be viewed with +.Li "vmstat -e" . +They can be useful in diagnosing flaky cables and other communication +problems. +.Pp +.\" These two paragraphs really belong not here but in a midi(9) man page, +.\" which should one day exist. +A raw sound generator uses the +.Sy midisyn +layer to present a +.Tn MIDI +message-driven interface attachable by +.Nm . +.Pp +While +.Nm +accepts messages for transmission in any valid mixture of compressed +or canonical form, they are always presented to an underlying driver +in the form it prefers. +Drivers for simple +.Tn UART Ns -like +devices +register their preference for a compressed byte stream, while those like +.Xr umidi 4 , +which uses a packet protocol, or +.Sy midisyn , +which interprets complete +messages, register for intact canonical messages. +This design eliminates the +need for compression and canonicalization logic from all layers above and below +.Nm +itself. +.Sh FILES +.Bl -tag -width /dev/sequencer -compact +.It Pa /dev/rmidiN +.It Pa /dev/music +.It Pa /dev/sequencer +.El +.Sh ERRORS +In addition to other errors documented for the +.Xr write 2 +family of system calls, +.Er EPROTO +can be returned if the bytes to be written on a raw +.Nm +device would violate +.Tn MIDI +protocol. +.Sh SEE ALSO +.Xr midiplay 1 , +.Xr midirecord 1 , +.Xr ioctl 2 , +.Xr ossaudio 3 , +.Xr audio 4 , +.Xr mpu 4 , +.Xr opl 4 , +.Xr umidi 4 +.Pp +For ports using the ISA bus: +.Xr cms 4 , +.Xr pcppi 4 , +.Xr sb 4 +.Pp +For ports using the PCI bus: +.Xr autri 4 , +.Xr clcs 4 , +.Xr eap 4 +.Sh HISTORY +The +.Nm +driver first appeared in +.Nx 1.4 . +It was overhauled and this manual page rewritten for +.Nx 4.0 . +.Sh BUGS +Some +.Tn OSS +sequencer events and +.Xr ioctl 2 +operations are unimplemented, as +.In sys/midiio.h +notes. +.Pp +.Tn OSS +source-compatible sequencer macros should be added to +.In sys/soundcard.h , +implemented with the +.Nx +ones in +.In sys/midiio.h , +so sources written for OSS can be easily compiled. +.Pp +The sequencer blocks (or returns +.Er EWOULDBLOCK ) +only when its buffer physically fills, which can represent an arbitrary +latency because of buffered timing events. +As a result, interrupting a process writing the sequencer may not +interrupt music playback for a considerable time. +The sequencer could enforce a reasonable latency bound +by examining timing events as they are enqueued and blocking appropriately. +.Pp +.Dv FIOASYNC +enables signal delivery to the calling process only; +.Dv FIOSETOWN +is not supported. +.Pp +The sequencer can only be a timing master, but does not send timing messages +to synchronize any slave device; it cannot be slaved to timing messages +received on any interface (which would presumably require a PLL algorithm +similar to NTP's, and expertise in that area to implement it). +The sequencer ignores timing messages received on any interface +and does not pass them along to the reading process, and the OSS +operations to change that behavior are unimplemented. +.Pp +The +.Dv SEQUENCER_TMR_TIMEBASE +.Xr ioctl 2 +will report successfully setting any +timebase up to ridiculously high resolutions, though the actual +resolution, and therefore jitter, is constrained by +.Xr hz 9 . +Comparable sequencer implementations typically allow a selection from available +sources of time interrupts that may be programmable. +.Pp +The device number in a sequencer event is treated on +.Xr write 2 +as index into +the array of +.Tn MIDI +devices the sequencer has opened, but on +.Xr read 2 +as the +unit number of the source +.Tn MIDI +device; these are usually the same if the +sequencer has opened all the +.Tn MIDI +devices (that is, none was already open +at its raw node when the sequencer was opened), but might not be the same +otherwise. +.Pp +There is at present no way to make reception nonpromiscuous, +should anyone have a reason to want to. +.Pp +There should be ways to override default Active Sense behavior. +As one obvious +case, if an application is seen to send Active Sense explicitly, +.Nm +should refrain +from adding its own. +On receive, there should be an option to pass Active Sense through +rather than interpreting it, for apps that wish to handle or ignore it +themselves and never see +.Dv EOF . +.Pp +When a +.Nm +stream is open by the sequencer, Active Sense messages received on the stream +are passed to the sequencer and not interpreted by +.Nm . +The sequencer at present neither does anything itself with Active Sense +messages received, nor supports the +.Tn OSS +.Tn API +for making them available to the user process. +.Pp +System Exclusive messages can be received by reading a raw device, but +not by reading the sequencer; they are discarded on receipt when the +stream is open by the sequencer, rather than being presented as the +OSS-defined sequencer events. +.Pp +.Sy midisyn +is too rudimentary at present to get satisfactory results from any +onboard synth. +It lacks the required special interpretation of the +General +.Tn MIDI +percussion channel in GM mode. +More devices should be supported; some sound cards with synthesis +capability have +.Nx +drivers that implement the +.Xr audio 4 +but not the +.Sy midisyn +interface. +Voice stealing algorithm does not follow the General +.Tn MIDI +Developer Guidelines. +.Pp +.Tn ALSA +sequencer compatibility is lacking, but becoming important to applications. +It would require the function of merging multiple tracks into a single ordered +stream to be moved from user space into the sequencer. +Assuming the sequencer driven by periodic interrupts, timing wheels +could be used as in +.Xr hardclock 9 +itself. +Similar functionality will be in OSS4; with the right infrastructure +it should be possible to support both. +When merging +.Tn MIDI +streams, a notion of transaction +is needed to group critical message sequences. +If +.Tn ALSA +or +.Tn OSS4 +have no such notion, it should be provided as an upward-compatible +extension. +.Pp +I would rather have +.Xr open 2 +itself return an error (by the POSIX description +.Er ENODEV +looks most appropriate) if a read or write mode +is requested that is not supported by the instance, rather than letting +.Xr open 2 +succeed and +.Xr read 2 +or +.Xr write 2 +return \-1, but so help me, the latter seems +the more common +.Ux +practice. |