docs: OpenBSD Man Pages Added

1 files changed, 272 insertions, 0 deletions

diff --git a/static/openbsd/man4/midi.4 b/static/openbsd/man4/midi.4
new file mode 100644
index 00000000..33fbc5d7
--- /dev/null
+++ b/static/openbsd/man4/midi.4
@@ -0,0 +1,272 @@
+.\" $OpenBSD: midi.4,v 1.31 2022/03/31 17:30:05 naddy Exp $
+.\"
+.\" Copyright (c) 2006 Alexandre Ratchov <alex@caoua.org>
+.\"
+.\" 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.
+.\"
+.\" 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 $Mdocdate: March 31 2022 $
+.Dt MIDI 4
+.Os
+.Sh NAME
+.Nm midi
+.Nd raw device independent interface to MIDI ports
+.Sh SYNOPSIS
+.Cd "midi* at autri?"
+.Cd "midi* at eap?"
+.Cd "midi* at envy?"
+.Cd "midi* at mpu?"
+.Cd "midi* at sb?"
+.Cd "midi* at umidi?"
+.Cd "midi* at ym?"
+.Sh DESCRIPTION
+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
+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,
+and then return immediately.
+.Pp
+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 ) ,
+then subsequent calls to
+.Xr read 2
+or
+.Xr write 2
+will never block.
+The
+.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 FILES
+.Bl -tag -width /dev/rmidim -compact
+.It Pa /dev/rmidi*
+.Nm
+devices
+.El
+.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 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) == -1)
+		errx(1, "poll");
+	if (ifd[0].revents & POLLIN) {
+		if ((iused = read(ifd[0].fd, ibuf, BUFSIZE)) == -1)
+			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)) == -1)
+			errx(1, "read");
+		for (i = 0; i < iused; i++)
+			if (ISCOMMON(ibuf[i]))
+				obuf[oused++] = ibuf[i];
+	}
+	if (write(ofd, obuf, oused) == -1)
+		errx(1, "write");
+}
+.Ed
+.Pp
+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 ERRORS
+If
+.Xr open 2 ,
+.Xr read 2 ,
+.Xr write 2 ,
+or
+.Xr poll 2
+fail then
+.Xr errno 2
+may be set to one 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
+The device is already open by another process.
+.El
+.Sh SEE ALSO
+.Xr autri 4 ,
+.Xr eap 4 ,
+.Xr envy 4 ,
+.Xr mpu 4 ,
+.Xr sb 4 ,
+.Xr umidi 4
+.Sh HISTORY
+The
+.Nm
+driver first appeared in
+.Ox 2.5 .
+.Sh AUTHORS
+.An -nosplit
+The
+.Nm
+driver was originally written by
+.An Lennart Augustsson
+and later largely rewritten by
+.An Alexandre Ratchov .
+.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
+is the time it takes for sound to propagate 1.75 meters).
+.Pp
+The
+.Ox
+.Nm
+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 many 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 a 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
+and
+.Xr mlockall 2 ) .
+.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.