simplify manual, remove -x option

sndiod/sndiod.1

@@ -40,7 +40,6 @@
 .Op Fl U Ar unit
 .Op Fl v Ar volume
 .Op Fl w Ar flag
-.Op Fl x Ar policy
 .Op Fl z Ar nframes
 .Ek
 .Sh DESCRIPTION
@@ -102,14 +101,11 @@ The user selects the configuration a given program will use
 by selecting the sub-device the program uses.
 .Pp
 .Nm
-can expose a MIDI port that can be used as a MIDI thru box
+exposes MIDI thru boxes (aka a
-(aka a
+.Dq hubs
-.Dq hub
 for MIDI messages),
-allowing any program to send MIDI messages to
+allowing programs to send MIDI messages to each other
-MIDI hardware or to another program in a uniform way.
+or to hardware MIDI ports in a uniform way.
-Hardware ports can be subscribed to such MIDI thru boxes,
-allowing multiple programs to share the MIDI port.
 .Pp
 Finally,
 .Nm
@@ -163,8 +159,32 @@ Increase log verbosity.
 logs on
 .Em stderr .
 .It Fl e Ar enc
-Audio device encoding (see below).
+Attempt to configure the device to use this encoding.
-The default is signed, 16-bit, native byte order.
+The default is
+.Va s16 .
+Encoding names use the follwing scheme: signedness
+.Po
+.Va s
+or
+.Va u
+.Pc
+followed
+by the precision in bits, the byte-order
+.Po
+.Va le
+or
+.Va be
+.Pc ,
+the number of
+bytes per sample, and the alignement
+.Po 
+.Va msb
+or
+.Va lsb
+.Pc .
+Only the signedness and the precision are mandatory.
+Examples:
+.Va u8 , s16le , s24le3 , s24le4lsb.
 .It Fl f Ar device
 Add this
 .Xr sndio 7
@@ -227,12 +247,9 @@ The default is
 (i.e. full-duplex).
 .It Fl q Ar port
 Expose the given MIDI port.
-This allows multiple programs
+This allows multiple programs to share the port.
-.Nm
-instead of the given physical MIDI port which can be used
-by only one program.
 .It Fl r Ar rate
-Audio device sample rate in Hertz of the stream.
+Attempt to force the device to use this sample rate in Hertz.
 The default is 48000.
 .It Fl s Ar name
 Add
@@ -265,7 +282,7 @@ additionally, the server clock is exposed as MIDI Time Code (MTC)
 messages allowing MTC-capable software or hardware to be synchronized
 to audio programs.
 .It Fl U Ar unit
-Unit number to use when running in server mode.
+Unit number.
 Each
 .Nm
 server instance has an unique unit number,
@@ -280,7 +297,7 @@ is used.
 Software volume attenuation of playback.
 The value must be between 1 and 127,
 corresponding to \-42dB and \-0dB attenuation in 1/3dB steps.
-In server mode, clients inherit this parameter.
+Clients inherit this parameter.
 Reducing the volume in advance allows a client's volume to stay independent
 from the number of clients as long as their number is small enough.
 18 volume units (i.e. \-6dB attenuation) allows the number
@@ -302,31 +319,6 @@ Using
 makes sense in the rare situation where all programs lower their volumes.
 The default is
 .Va on .
-.It Fl x Ar policy
-Action when the program cannot accept
-recorded data fast enough or cannot provide data to play fast enough.
-If the policy is
-.Dq ignore
-(the default) then samples that cannot be written are discarded
-and samples that cannot be read are replaced by silence.
-If the policy is
-.Dq sync
-then recorded samples are discarded,
-but the same amount of silence will be written
-once the program is unblocked, in order to reach the right position in time.
-Similarly silence is played, but the same amount of samples will be discarded
-once the program is unblocked.
-If the policy is
-.Dq error
-then the program is disconnected.
-.Pp
-If a sub-device is created with the
-.Fl t
-option,
-the
-.Dq ignore
-action is disabled for any program connected to it
-to ensure proper synchronization.
 .It Fl z Ar nframes
 The audio device block size in frames.
 This is the number of frames between audio clock ticks,
@@ -363,11 +355,9 @@ If no audio devices
 are specified,
 settings are applied as if
 the default device is specified.
-If no
+If no sub-devices
-.Nm
-sub-devices
 .Pq Fl s
-are specified for a device, a default server sub-device is
+are specified for a device, a default sub-device is
 created attached to it.
 If a device
 .Pq Fl f
@@ -395,80 +385,18 @@ or
 .Dv SIGTERM ,
 it terminates.
 .Pp
-Encodings are specified using the
+By default, when the program cannot accept
-.Fl e
+recorded data fast enough or cannot provide data to play fast enough,
-option.
+the program is paused, i.e. samples that cannot be written are discarded
-The following encodings are supported:
+and samples that cannot be read are replaced by silence.
-.Pp
+If a sub-device is created with the
-.Bl -tag -width s32lexxx -offset indent -compact
+.Fl t
-.It s8
+option, then recorded samples are discarded,
-signed 8-bit
+but the same amount of silence will be written
-.It u8
+once the program is unblocked, in order to reach the right position in time.
-unsigned 8-bit
+Similarly silence is played, but the same amount of samples will be discarded
-.It s16le
+once the program is unblocked.
-signed 16-bit, little endian
+This ensures proper synchronization between programs.
-.It u16le
-unsigned 16-bit, little endian
-.It s16be
-signed 16-bit, big endian
-.It u16be
-unsigned 16-bit, big endian
-.It s24le
-signed 24-bit, stored in 4 bytes, little endian
-.It u24le
-unsigned 24-bit, stored in 4 bytes, little endian
-.It s24be
-signed 24-bit, stored in 4 bytes, big endian
-.It u24be
-unsigned 24-bit, stored in 4 bytes, big endian
-.It s32le
-signed 32-bit, little endian
-.It u32le
-unsigned 32-bit, little endian
-.It s32be
-signed 32-bit, big endian
-.It u32be
-unsigned 32-bit, big endian
-.It s24le3
-signed 24-bit, packed in 3 bytes, little endian
-.It u24le3
-unsigned 24-bit, packed in 3 bytes, big endian
-.It s24be3
-signed 24-bit, packed in 3 bytes, little endian
-.It u24be3
-unsigned 24-bit, packed in 3 bytes, big endian
-.It s20le3
-signed 20-bit, packed in 3 bytes, little endian
-.It u20le3
-unsigned 20-bit, packed in 3 bytes, big endian
-.It s20be3
-signed 20-bit, packed in 3 bytes, little endian
-.It u20be3
-unsigned 20-bit, packed in 3 bytes, big endian
-.It s18le3
-signed 18-bit, packed in 3 bytes, little endian
-.It u18le3
-unsigned 18-bit, packed in 3 bytes, big endian
-.It s18be3
-signed 18-bit, packed in 3 bytes, little endian
-.It u18be3
-unsigned 18-bit, packed in 3 bytes, big endian
-.El
-.Sh SERVER MODE
-.Nm
-can be used
-to overcome hardware limitations and allow applications
-to run on fixed sample rate devices or on devices
-supporting only unusual encodings.
-.Pp
-Certain applications, such as synthesis software,
-require a low latency audio setup.
-To reduce the probability of buffer underruns or overruns, especially
-on busy machines, the server can be started by the super-user, in which
-case it will run with higher priority.
-Any user will still be able to connect to it,
-but for privacy reasons only one user may have
-connections to it at a given time.
 .Sh MIDI CONTROL
 .Nm
 creates a MIDI port with the same name as the exposed audio
@@ -602,6 +530,7 @@ when recording.
 Processing is done using 16-bit arithmetic,
 thus samples with more than 16 bits are rounded.
 16 bits (i.e. 97dB dynamic) are largely enough for most applications though.
+Processing precision can be increased to 24-bit at compilation time though.
 .Pp
 If
 .Fl a Ar off
@@ -613,11 +542,5 @@ Technically, this allows
 .Nm
 to attempt to use one of the sub-devices it exposes as an audio device,
 creating a deadlock.
-To avoid this,
+There's nothing to prevent the user
-.Fl a Ar off
+from shooting himself in the foot by creating such a deadlock.
-is disabled for the default audio device, but nothing prevents the user
-from shooting himself in the foot by creating a similar deadlock.
-.Pp
-The ability to merge multiple inputs is provided to allow multiple
-applications producing MIDI data to keep their connection open while
-idling; it does not replace a fully featured MIDI merger.

sndiod/sndiod.c

@@ -87,8 +87,7 @@ volatile sig_atomic_t quit_flag = 0;
 char usagestr[] = "usage: sndiod [-d] [-a flag] [-b nframes] "
     "[-C min:max] [-c min:max] [-e enc]\n\t"
     "[-f device] [-j flag] [-L addr] [-m mode] [-q port] [-r rate]\n\t"
-    "[-s name] [-t mode] [-U unit] [-v volume] [-w flag] [-x policy]\n\t"
+    "[-s name] [-t mode] [-U unit] [-v volume] [-w flag] [-z nframes]\n";
-    "[-z nframes]\n";
 
 /*
  * SIGINT handler, it raises the quit flag. If the flag is already set,
@@ -155,18 +154,6 @@ opt_onoff(void)
 	errx(1, "%s: on/off expected", optarg);
 }
 
-int
-opt_xrun(void)
-{
-	if (strcmp("ignore", optarg) == 0)
-		return XRUN_IGNORE;
-	if (strcmp("sync", optarg) == 0)
-		return XRUN_SYNC;
-	if (strcmp("error", optarg) == 0)
-		return XRUN_ERROR;
-	errx(1, "%s: bad underrun/overrun policy", optarg);
-}
-
 unsigned int
 opt_mode(void)
 {
@@ -317,7 +304,7 @@ main(int argc, char **argv)
 	int c, background, unit;
 	int pmin, pmax, rmin, rmax;
 	char base[PATH_MAX], path[PATH_MAX];
-	unsigned int mode, xrun, dup, mmc, vol;
+	unsigned int mode, dup, mmc, vol;
 	unsigned int hold, autovol, bufsz, round, rate;
 	const char *str;
 	struct aparams par;
@@ -330,7 +317,6 @@ main(int argc, char **argv)
 	/*
 	 * global options defaults
 	 */
-	xrun = XRUN_IGNORE;
 	vol = MIDI_MAXCTL;
 	dup = 1;
 	mmc = 0;