From 002a501b9f7d8c886e07e27b6cc4fbae51ea4b16 Mon Sep 17 00:00:00 2001 From: Alexandre Ratchov Date: Mon, 27 Jan 2014 13:16:23 +0100 Subject: [PATCH] cleanup tags, from schwarze@ --- libsndio/sio_open.3 | 149 +++++++++++++++++++++++--------------------- 1 file changed, 77 insertions(+), 72 deletions(-) diff --git a/libsndio/sio_open.3 b/libsndio/sio_open.3 index ea8b7be..ec9f324 100644 --- a/libsndio/sio_open.3 +++ b/libsndio/sio_open.3 @@ -87,33 +87,34 @@ First the application must call the .Fn sio_open function to obtain a handle to the device; later it will be passed as the -.Ar hdl +.Fa hdl argument of most other functions. The -.Ar name +.Fa name parameter gives the device string discussed in .Xr sndio 7 . -In most cases it should be set to SIO_DEVANY to allow -the user to select it using the +In most cases it should be set to +.Dv SIO_DEVANY +to allow the user to select it using the .Ev AUDIODEVICE environment variable. .Pp The following values of the -.Ar mode +.Fa mode parameter are supported: .Bl -tag -width "SIO_PLAY | SIO_REC" -.It SIO_PLAY +.It Dv SIO_PLAY Play-only mode: data written will be played by the device. -.It SIO_REC +.It Dv SIO_REC Record-only mode: samples are recorded by the device and must be read. -.It SIO_PLAY | SIO_REC +.It Dv SIO_PLAY | SIO_REC The device plays and records synchronously; this means that the n-th recorded sample was physically sampled exactly when the n-th played sample was actually played. .El .Pp If the -.Ar nbio_flag +.Fa nbio_flag argument is true (i.e. non-zero), then the .Fn sio_read and @@ -185,11 +186,11 @@ it's meaningful only if * 8. .It Va rchan The number of recorded channels; meaningful only if -.Va SIO_REC +.Dv SIO_REC mode was selected. .It Va pchan The number of played channels; meaningful only if -.Va SIO_PLAY +.Dv SIO_PLAY mode was selected. .It Va rate The sampling frequency in Hz. @@ -215,10 +216,10 @@ Applications can use this parameter to round their block size. The action when the client doesn't accept recorded data or doesn't provide data to play fast enough; it can be set to one of the -.Va SIO_IGNORE , -.Va SIO_SYNC +.Dv SIO_IGNORE , +.Dv SIO_SYNC , or -.Va SIO_ERROR +.Dv SIO_ERROR constants. .El .Pp @@ -226,7 +227,7 @@ The following approach is recommended to negotiate device parameters: .Bl -bullet .It Initialize a -.Va sio_par +.Vt sio_par structure using .Fn sio_initpar and fill it with @@ -235,7 +236,7 @@ Then call .Fn sio_setpar to request the device to use them. Parameters left unset in the -.Va sio_par +.Vt sio_par structure will be set to device-specific defaults. .It Call @@ -261,17 +262,17 @@ automatically be set up, and in this case any combination of rate, encoding and numbers of channels is supported. .Pp To ease filling the -.Va sio_par +.Vt sio_par structure, the following macros can be used: .Bl -tag -width "SIO_BPS(bits)" -.It "SIO_BPS(bits)" +.It Dv SIO_BPS Ns Pq Fa bits Return the smallest value for .Va bps that is a power of two and that is large enough to hold -.Va bits . -.It "SIO_LE_NATIVE" +.Fa bits . +.It Dv SIO_LE_NATIVE Can be used to set the .Va le parameter when native byte order is required. @@ -285,7 +286,7 @@ parameter combinations in advance can use the function. .Pp The -.Va sio_cap +.Vt sio_cap structure contains the list of parameter configurations. Each configuration contains multiple parameter sets. The application must examine all configurations, and @@ -319,40 +320,40 @@ struct sio_cap { .Pp The parameters are as follows: .Bl -tag -width "rchan[SIO_NCHAN]" -.It Va enc[SIO_NENC] +.It Va enc Ns Bq Dv SIO_NENC Array of supported encodings. The tuple of .Va bits , .Va bps , .Va sig , -.Va le +.Va le , and .Va msb parameters are usable in the corresponding parameters of the -.Va sio_par +.Vt sio_par structure. -.It Va rchan[SIO_NCHAN] +.It Va rchan Ns Bq Dv SIO_NCHAN Array of supported channel numbers for recording usable in the -.Va sio_par +.Vt sio_par structure. -.It Va pchan[SIO_NCHAN] +.It Va pchan Ns Bq Dv SIO_NCHAN Array of supported channel numbers for playback usable in the -.Va sio_par +.Vt sio_par structure. -.It Va rate[SIO_NRATE] +.It Va rate Ns Bq Dv SIO_NRATE Array of supported sample rates usable in the -.Va sio_par +.Vt sio_par structure. .It Va nconf Number of different configurations available, i.e. number of filled elements of the .Va confs[] array. -.It Va confs[SIO_NCONF] +.It Va confs Ns Bq Dv SIO_NCONF Array of available configurations. Each configuration contains bitmasks indicating which elements of the above parameter arrays are valid for the @@ -360,11 +361,11 @@ given configuration. For instance, if the second bit of .Va rate is set, in the -.Va sio_conf +.Vt sio_conf structure, then the second element of the -.Va rate[SIO_NRATE] +.Va rate Ns Bq Dv SIO_NRATE array of the -.Va sio_cap +.Vt sio_cap structure is valid for this configuration. .El .Ss Starting and stopping the device @@ -399,12 +400,12 @@ When record mode is selected, the function must be called to retrieve recorded data; it must be called often enough to ensure that internal buffers will not overrun. It will store at most -.Ar nbytes +.Fa nbytes bytes at the -.Ar addr +.Fa addr location and return the number of bytes stored. Unless the -.Ar nbio_flag +.Fa nbio_flag flag is set, it will block until data becomes available and will return zero only on error. .Pp @@ -412,13 +413,13 @@ Similarly, when play mode is selected, the .Fn sio_write function must be called to provide data to play. Unless the -.Ar nbio_flag +.Fa nbio_flag is set, .Fn sio_write will block until the requested amount of data is written. .Ss Non-blocking mode operation If the -.Ar nbio_flag +.Fa nbio_flag is set on .Fn sio_open , then the @@ -435,51 +436,52 @@ read from or written to the device. The .Fn sio_pollfd function fills the array -.Ar pfd +.Fa pfd of -.Va pollfd +.Vt pollfd structures, used by .Xr poll 2 , with -.Ar events ; +.Fa events ; the latter is a bit-mask of -.Va POLLIN +.Dv POLLIN and -.Va POLLOUT +.Dv POLLOUT constants; refer to .Xr poll 2 for more details. .Fn sio_pollfd returns the number of -.Va pollfd +.Vt pollfd structures filled. The .Fn sio_revents function returns the bit-mask set by .Xr poll 2 in the -.Va pfd +.Fa pfd array of -.Va pollfd +.Vt pollfd structures. If -.Va POLLIN +.Dv POLLIN is set, recorded samples are available in the device buffer and can be read with .Fn sio_read . If -.Va POLLOUT +.Dv POLLOUT is set, space is available in the device buffer and new samples to play can be submitted with .Fn sio_write . -POLLHUP may be set if an error occurs, even if +.Dv POLLHUP +may be set if an error occurs, even if it is not selected with .Fn sio_pollfd . .Pp The .Fn sio_nfds function returns the number of -.Va pollfd +.Vt pollfd structures the caller must preallocate in order to be sure that .Fn sio_pollfd @@ -493,30 +495,31 @@ position in the stream the hardware is processing. The .Fn sio_onmove function can be used to register the -.Va cb +.Fn cb callback function called at regular time intervals. The -.Va delta +.Fa delta argument contains the number of frames the hardware played and/or recorded since the last call of -.Va cb . +.Fn cb . It is called by -.Fn sio_read , sio_write , +.Fn sio_read , +.Fn sio_write , and .Fn sio_revents . When the first sample is played and/or recorded, right after the device starts, the callback is invoked with a zero -.Va delta +.Fa delta argument. The value of the -.Va arg +.Fa arg pointer is passed to the callback and can contain anything. .Pp If desired, the application can maintain the current position by starting from zero (when .Fn sio_start is called) and adding to the current position -.Va delta +.Fa delta every time .Fn cb is called. @@ -565,13 +568,13 @@ instead. Depending on the .Va xrun parameter of the -.Va sio_par +.Vt sio_par structure, the audio subsystem will behave as follows: .Bl -tag -width "SIO_IGNORE" -.It SIO_IGNORE +.It Dv SIO_IGNORE The devices pauses during overruns and underruns, thus the current position (obtained through -.Va sio_onmove ) +.Fn sio_onmove ) stops being incremented. Once the overrun and/or underrun condition is gone, the device resumes; play and record are always kept in sync. @@ -582,7 +585,7 @@ This mode is the default. It's suitable for applications, like audio players and telephony, where time is not important and overruns or underruns are not short. -.It SIO_SYNC +.It Dv SIO_SYNC If the play buffer underruns, then silence is played, but in order to reach the right position in time, the same amount of written samples will be @@ -591,7 +594,7 @@ Similarly, if the record buffer overruns, then samples are discarded, but the same amount of silence will be returned later. The current position (obtained through -.Va sio_onmove ) +.Fn sio_onmove ) is still incremented. When the play buffer underruns the play latency might become negative; when the record buffer overruns, the record latency might become @@ -601,7 +604,7 @@ larger than This mode is suitable for applications, like music production, where time is important and where underruns or overruns are short and rare. -.It SIO_ERROR +.It Dv SIO_ERROR With this mode, on the first play buffer underrun or record buffer overrun, playback and/or recording is terminated and no other function than @@ -615,7 +618,7 @@ The .Fn sio_setvol function can be used to set playback attenuation. The -.Va vol +.Fa vol parameter takes a value between 0 (maximum attenuation) and .Dv SIO_MAXVOL @@ -659,7 +662,7 @@ programming errors (e.g. call to .Fn sio_read on a play-only stream) are considered fatal. Once an error occurs, all functions taking a -.Va sio_hdl +.Fa sio_hdl argument, except .Fn sio_close and @@ -682,7 +685,7 @@ The .Fn sio_getcap , .Fn sio_start , .Fn sio_stop , -.Fn sio_pollfd +.Fn sio_pollfd , and .Fn sio_setvol functions return 1 on success and 0 on failure. @@ -696,8 +699,10 @@ functions return the number of bytes transferred. .It Ev AUDIODEVICE Device to use if .Fn sio_open -is called with SIO_DEVANY -.Va name +is called with +.Dv SIO_DEVANY +as the +.Fa name argument. .It Ev SNDIO_DEBUG The debug level: @@ -712,7 +717,7 @@ may be a value between 0 and 2. The .Xr audio 4 driver doesn't drain playback buffers, thus if -.Nm libsndio +.Lb libsndio is used to directly access an .Xr audio 4 device, @@ -725,7 +730,7 @@ If the application doesn't consume recorded data fast enough then from the .Xr sndiod 1 server are delayed and consequently -.Va sio_onmove +.Fn sio_onmove callback or volume changes may be delayed. .Pp The @@ -733,7 +738,7 @@ The .Fn sio_setpar , .Fn sio_getpar , .Fn sio_getcap , -.Fn sio_start +.Fn sio_start , and .Fn sio_stop functions may block for a very short period of time, thus they should