Improved MIDI manpages from Alexandre Ratchov.

3 files changed, 319 insertions, 88 deletions

diff --git a/share/man/man4/Makefile b/share/man/man4/Makefile
index 2bdea8f685d..87644515e04 100644
--- a/share/man/man4/Makefile
+++ b/share/man/man4/Makefile
@@ -1,4 +1,4 @@
-#	$OpenBSD: Makefile,v 1.348 2006/03/26 20:19:54 grange Exp $
+#	$OpenBSD: Makefile,v 1.349 2006/04/07 22:53:21 jsg Exp $
 
 MAN=	aac.4 ac97.4 acphy.4 acpi.4 acpihpet.4 acpitimer.4 \
 	adc.4 addcom.4 admcts.4 admlc.4 admtemp.4 \
@@ -33,8 +33,8 @@ MAN=	aac.4 ac97.4 acphy.4 acpi.4 acpihpet.4 acpitimer.4 \
 	pms.4 ppb.4 ppp.4 pppoe.4 pty.4 puc.4 qsphy.4 radio.4 raid.4 ral.4 \
 	random.4 ray.4 rd.4 re.4 rgephy.4 rl.4 rln.4 rlphy.4 route.4 rt.4 \
 	rtfps.4 rtii.4 rtw.4 safe.4 safte.4 san.4 sbus.4 scsi.4 sd.4 ses.4 \
-	sf.4 sf2r.4 sfr.4 siop.4 sis.4 sk.4 sl.4 sm.4 speaker.4 sppp.4 \
-	sqphy.4 ss.4 st.4 ste.4 stge.4 sti.4 stp.4 sv.4 \
+	sequencer.4 sf.4 sf2r.4 sfr.4 siop.4 sis.4 sk.4 sl.4 sm.4 \
+	speaker.4 sppp.4 sqphy.4 ss.4 st.4 ste.4 stge.4 sti.4 stp.4 sv.4 \
 	systrace.4 tb.4 tcic.4 tcp.4 termios.4 ti.4 tl.4 \
 	tlphy.4 tqphy.4 trm.4 trunk.4 tsl.4 tty.4 tun.4 twe.4 txp.4 \
 	txphy.4 uaudio.4 ubsa.4 ubsec.4 ubt.4 ucom.4 udav.4 udp.4 udsbr.4 \
@@ -66,6 +66,7 @@ MLINKS+=random.4 arandom.4
 MLINKS+=random.4 srandom.4 random.4 urandom.4 random.4 prandom.4
 MLINKS+=scsi.4 scsibus.4
 MLINKS+=sk.4 skc.4
+MLINKS+=sequencer.4 music.4
 MLINKS+=speaker.4 spkr.4
 MLINKS+=tty.4 cua.4
 MLINKS+=usb.4 uhub.4
diff --git a/share/man/man4/midi.4 b/share/man/man4/midi.4
index 3a6c84dd785..704c8f6f98a 100644
--- a/share/man/man4/midi.4
+++ b/share/man/man4/midi.4
@@ -1,43 +1,25 @@
-.\" $OpenBSD: midi.4,v 1.19 2004/12/24 10:10:47 jsg Exp $
-.\" $NetBSD: midi.4,v 1.4 1998/08/22 14:45:35 augustss Exp $
+.\" $OpenBSD: midi.4,v 1.20 2006/04/07 22:53:21 jsg Exp $
 .\"
-.\" Copyright (c) 1997 The NetBSD Foundation, Inc.
-.\" All rights reserved.
+.\" Copyright (c) 2006 Alexandre Ratchov <alex@caoua.org>
 .\"
-.\" 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.
-.\" 3. All advertising materials mentioning features or use of this software
-.\"    must display the following acknowledgement:
-.\"        This product includes software developed by the NetBSD
-.\"        Foundation, Inc. and its contributors.
-.\" 4. Neither the name of The NetBSD Foundation nor the names of its
-.\"    contributors may be used to endorse or promote products derived
-.\"    from this software without specific prior written permission.
+.\" Permission to use, copy, modify, and distribute this software for any
+.\" purpose with or without fee is hereby granted, provided that the above
+.\" copyright notice and this permission notice appear in all copies.
 .\"
-.\" 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.
+.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"
-.Dd August 6, 1998
+.Dd April 6, 2006
 .Dt MIDI 4
 .Os
 .Sh NAME
 .Nm midi
-.Nd device-independent MIDI driver layer
+.Nd raw device independent interface to MIDI ports
 .Sh SYNOPSIS
 .Cd "midi* at autri?"
 .Cd "midi* at eap?"
@@ -45,77 +27,238 @@
 .Cd "midi* at opl?"
 .Cd "midi* at pcppi?"
 .Cd "midi* at sb?"
-.Cd "midi* at wss?"
+.Cd "midi* at umidi?"
 .Cd "midi* at ym?"
-.Pp
-.Cd "pseudo-device sequencer" Op Ar count
-.Pp
-.Fd #include <sys/types.h>
-.Fd #include <sys/midiio.h>
 .Sh DESCRIPTION
-The
+The 
+.Nm
+driver makes MIDI ports available to user applications.
+A 
+.Nm
+device corresponds to 2 MIDI ports: one input port and one
+output port.
+Data received on the input port is not interpreted and is passed
+to the user program as-is.
+Similarly, data issued by the user program is sent as-is to the
+output port.
+.Pp
+Only one process may hold open a 
 .Nm
-driver provides support for various MIDI peripherals.
-It provides a uniform programming interface layer above different
-underlying MIDI hardware drivers.
-The MIDI hardware can be of many different kinds, e.g., an external
-synthesizer on a MIDI port (or a serial port), the PC speaker, an
-internal FM synth, or a wavetable synth.
+device at a given time, although file descriptors may be shared
+between processes once the first open completes.
+If it is opened read-only (write-only) only the input (output)
+MIDI port is available.
+.Ss Writing to the device
+A process can send raw MIDI data to the output port by using the
+.Xr write 2
+system call.
+Data is queued and the system call returns immediately; the data
+is sent as fast as possible to the output MIDI port.
+However, if the in-kernel buffer is full or the requested amount
+is too large, then
+.Xr write 2 
+may block.
+The current size of the in-kernel buffer is 1024 bytes, which
+ensures that 
+.Xr write 2
+isn't blocking in most situations.
+.Ss Reading from the device
+Data received from the input MIDI port is stored into the
+in-kernel buffer.
+A process can retrieve its contents by using
+the 
+.Xr read 2
+system call.
+If there is less data than the amount requested for reading, then
+a shorter amount is returned.
+If no data is available, then the
+.Xr read 2
+system call will block until data is received, then it will
+returned immediately.
 .Pp
-There are two device file types available for MIDI operation:
-.Pa /dev/rmidiN ,
-and
-.Pa /dev/music .
+The MIDI protocol has been designed for real-time performance and
+doesn't support flow control.
+An application must be able to read the incoming data fast enough
+(the MIDI standard's maximum rate is 3125 bytes per second).
+The kernel can buffer up to 1024 bytes; once the buffer is full
+input will be silently discarded.
+.Ss Polling the device
+A process can use the 
+.Xr poll 2
+system call to poll for the following events:
+.Bl -tag -width POLLOUT
+.It Dv POLLIN
+The in-kernel input buffer isn't empty, i.e. at least one byte is
+available for reading.
+A subsequent call to
+.Xr read 2
+will not be blocking
+.It Dv POLLOUT
+The in-kernel output buffer is empty, thus a subsequent call to 
+.Xr write 2
+will not be blocking if a reasonable amount of data is written
+(currently less that 1024 bytes)
+.El
+.Pp
+Using the 
+.Xr poll 2
+system call is the recommended way to handle multiple 
+.Nm
+devices in a real-time MIDI application.
+.Ss Non-blocking I/O
+If the 
+.Nm
+device is opened with the O_NONBLOCK flag (see
+.Xr open 2 
+manual page), then subsequent calls to 
+.Xr read 2
+or 
+.Xr write 2
+will never block.
 The
-.Pa /dev/rmidiN
-devices provides raw access to a MIDI device.
-Data written is sent to the physical device as fast as possible and
-is uninterpreted.
-Reading from the device returns data as soon as it becomes available.
-A moderate amount of buffering is available both for reading and writing.
-The raw MIDI devices are mostly useful for non realtime operations, such as
-downloading patches to a device, since it is hard to get the accurate timing
-needed for quality music from a user program.
-But the devices can act as a simple patchboard for MIDI devices.
-For example, a MIDI keyboard could be connected to a synthesizer by
-the command
+.Xr write 2
+system call may write less bytes than requested, or may return
+EAGAIN if no data could be sent or queued.
+Similarly, the 
+.Xr read 2
+system call may return EAGAIN if no input is available.
+.Pp
+Note that even if non-blocking I/O is not selected,
+.Xr read 2
+and 
+.Xr write 2
+system calls are non-blocking when the kernel buffers permit it.
+.Sh EXAMPLES
+The following command could record the memory dump of a
+synthesizer in a file:
+.Pp
+.Dl $ cat -u /dev/rmidi2 >dumpfile
+.Pp
+A MIDI keyboard could be connected to a synthesizer by the
+command:
 .Pp
 .Dl $ cat -u /dev/rmidi1 >/dev/rmidi2
 .Pp
-The
-.Pa /dev/music
-device is a MIDI sequencer device.
-Data sent to and from this device not only contains the information sent to the
-MIDI device, but also timing information.
-The kernel will make sure that data is sent to the physical device at the
-indicated time.
-The sequencer device uses the
-.Pa /dev/midiN
-devices internally and they are unavailable when used by the sequencer.
+The input port could be connected to the output port by the
+command:
+.Pp
+.Dl $ cat -u <>/dev/rmidi1 >&0
+.Pp
+The following example reads MIDI timing events from an input
+device, MIDI common and voice events from another input device and
+sends the result to a third (output) device.
+.Bd -literal -offset indent
+#define BUFSIZE		0x100
+#define ISTIMING(c)	((c) == 0xf8 || (c) == 0xfa || (c) == 0xfc)
+#define ISCOMMON(c)	((c) < 0xf8)
+
+int ofd;
+struct pollfd ifd[2];
+unsigned char ibuf[BUFSIZE], obuf[2 * BUFSIZE];
+ssize_t iused, oused, i;
+
+ifd[0].events = ifd[1].events = POLLIN;
+for (;;) {
+	oused = 0;
+	if (poll(ifd, 2, -1) < 0)
+		errx(1, "poll");
+	if (ifd[0].revents & POLLIN) {
+		if ((iused = read(ifd[0].fd, ibuf, BUFSIZE)) < 0)
+			errx(1, "read");
+		for (i = 0; i < iused; i++)
+			if (ISTIMING(ibuf[i])) 
+				obuf[oused++] = ibuf[i];
+	}
+	if (ifd[1].revents & POLLIN) {
+		if ((iused = read(ifd[1].fd, ibuf, BUFSIZE)) < 0)
+			errx(1, "read");
+		for (i = 0; i < iused; i++)
+			if (ISCOMMON(ibuf[i]))
+				obuf[oused++] = ibuf[i];
+	}
+	if (write(ofd, obuf, oused) < 0)
+		errx(1, "write");
+}
+.Ed
 .Pp
-The API for the sequencer device is binary compatible with the OSS sequencer
-interface.
+In the above example, unless kernel buffers are full, processing
+is done in real-time without any noticeable latency; as expected,
+the only blocking system call is 
+.Xr poll 2 .
 .Sh FILES
-.Bl -tag -width /dev/sequencer -compact
-.It Pa /dev/rmidiN
-.It Pa /dev/music
-.It Pa /dev/sequencer
+.Bl -tag -width /dev/rmidim -compact
+.It Pa /dev/rmidi*
+.Nm
+devices
+.El
+.Sh ERRORS
+If 
+.Xr open 2 ,
+.Xr read 2 ,
+.Xr write 2 
+or
+.Xr poll 2
+fail then 
+.Xr errno 2
+may be set to on of:
+.Bl -tag -width Er
+.It Bq Er ENXIO
+the device is opened read-only (write-only) but
+.Xr write 2
+.Pf ( Xr read 2 )
+was called
+.It Bq Er EIO
+the device is being detached while a process has been trying to
+read or write (for instance an 
+.Xr umidi 4
+device has been unplugged)
+.It Bq Er EAGAIN
+Non-blocking I/O was selected and the output buffer is full (on
+writing) or the input buffer is empty (on reading).
+.It Bq Er EBUSY
+Device is already open by another process
 .El
 .Sh SEE ALSO
-.Xr midiplay 1 ,
-.Xr ioctl 2 ,
-.Xr ossaudio 3 ,
-.Xr audio 4 ,
 .Xr autri 4 ,
 .Xr eap 4 ,
 .Xr mpu 4 ,
 .Xr opl 4 ,
 .Xr pcppi 4 ,
 .Xr sb 4 ,
-.Xr wss 4 ,
+.Xr sequencer 4 ,
+.Xr umidi 4 ,
 .Xr ym 4
-.Sh HISTORY
+.Sh CAVEATS
+MIDI hardware was designed for real time performance and software
+using such hardware must be able to process MIDI events without
+any noticeable latency (typically no more than 5ms, which
+corresponds to the time it takes to the sound to propagate 1.75
+meters).
+.Pp
 The
+.Ox
 .Nm
-driver first appeared in
-.Nx 1.4 .
+driver processes data fast enough, however if a MIDI application
+tries to write data faster than the hardware is able to process it
+(typically 3125 bytes per second), then kernel buffers may become
+full and the application may be blocked.
+.Pp
+The other common reason for MIDI data being delayed is the system
+load.
+Processes cannot be preempted while running in kernel mode.
+If there are too much processes running concurrently (especially
+if they are running a lot of expensive system calls) then the
+scheduling of a real-time MIDI application may be delayed.
+Even on low-end machines this delay hardly reaches few
+milliseconds provided that the system load is reasonable.
+.Pp
+A real-time MIDI application can avoid being swapped by locking
+its memory (see 
+.Xr mlock 2 ,
+.Xr mlockall 2
+manual pages).
+.Sh BUGS
+For a given device, even if the physical MIDI input and output
+ports are independent, there is no way for one process to use the
+input MIDI port and for another process to use the output MIDI
+port at the same time.
diff --git a/share/man/man4/sequencer.4 b/share/man/man4/sequencer.4
new file mode 100644
index 00000000000..0a8df823862
--- /dev/null
+++ b/share/man/man4/sequencer.4
@@ -0,0 +1,87 @@
+.\" $OpenBSD: sequencer.4,v 1.1 2006/04/07 22:53:21 jsg Exp $
+.\" $NetBSD: midi.4,v 1.4 1998/08/22 14:45:35 augustss Exp $
+.\"
+.\" Copyright (c) 1997 The NetBSD Foundation, Inc.
+.\" All rights reserved.
+.\"
+.\" 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.
+.\" 3. All advertising materials mentioning features or use of this software
+.\"    must display the following acknowledgement:
+.\"        This product includes software developed by the NetBSD
+.\"        Foundation, Inc. and its contributors.
+.\" 4. Neither the name of The NetBSD Foundation nor the names of its
+.\"    contributors may be used to endorse or promote products derived
+.\"    from this software without specific prior written permission.
+.\"
+.\" 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 6, 2006
+.Dt SEQUENCER 4
+.Os
+.Sh NAME
+.Nm sequencer 
+.Nd OSS-compatible MIDI sequencer device
+.Sh SYNOPSIS
+.Cd "pseudo-device sequencer" Op Ar count
+.Pp
+.Fd #include <sys/types.h>
+.Fd #include <sys/midiio.h>
+.Sh DESCRIPTION
+The
+.Nm
+device provides event-orientated interface simultaneously 
+to all MIDI ports.
+Events sent to or received from this device not only contain the
+actual MIDI events, but also timing information.
+The kernel will make sure that data is sent to the physical 
+device at the indicated time.
+The 
+.Nm
+device uses the
+.Xr midi 4
+devices internally and they are unavailable when used by the 
+.Nm
+device.
+.Pp
+The API for the 
+.Nm
+device is binary compatible with the OSS sequencer
+interface.
+.Sh FILES
+.Bl -tag -width /dev/sequencer -compact
+.It Pa /dev/music
+new 
+.Nm
+device using 8-byte events
+.It Pa /dev/sequencer
+old
+.Nm
+device using 4-byte events
+.El
+.Sh SEE ALSO
+.Xr midiplay 1 ,
+.Xr ioctl 2 ,
+.Xr ossaudio 3 ,
+.Xr midi 4
+.Sh HISTORY
+The
+.Nm
+driver first appeared in
+.Nx 1.4 .