sio_open.3: massive macro cleanup from schwarze@

basic macro cleanup: .Fo for long .Fn lines, .Fa for struct fields,
avoid \*(Gt and \*(Lt, .Dv NULL, .Cm for pledge promises
This commit is contained in:
Alexandre Ratchov 2020-06-28 07:50:09 +02:00
parent f96882d62d
commit d391925214
1 changed files with 55 additions and 49 deletions

View File

@ -57,7 +57,11 @@
.Ft "size_t" .Ft "size_t"
.Fn sio_write "struct sio_hdl *hdl" "const void *addr" "size_t nbytes" .Fn sio_write "struct sio_hdl *hdl" "const void *addr" "size_t nbytes"
.Ft "void" .Ft "void"
.Fn sio_onmove "struct sio_hdl *hdl" "void (*cb)(void *arg, int delta)" "void *arg" .Fo sio_onmove
.Fa "struct sio_hdl *hdl"
.Fa "void (*cb)(void *arg, int delta)"
.Fa "void *arg"
.Fc
.Ft "int" .Ft "int"
.Fn sio_nfds "struct sio_hdl *hdl" .Fn sio_nfds "struct sio_hdl *hdl"
.Ft "int" .Ft "int"
@ -69,7 +73,11 @@
.Ft "int" .Ft "int"
.Fn sio_setvol "struct sio_hdl *hdl" "unsigned int vol" .Fn sio_setvol "struct sio_hdl *hdl" "unsigned int vol"
.Ft "int" .Ft "int"
.Fn sio_onvol "struct sio_hdl *hdl" "void (*cb)(void *arg, unsigned int vol)" "void *arg" .Fo sio_onvol
.Fa "struct sio_hdl *hdl"
.Fa "void (*cb)(void *arg, unsigned int vol)"
.Fa "void *arg"
.Fc
.Ft "void" .Ft "void"
.Fn sio_initpar "struct sio_par *par" .Fn sio_initpar "struct sio_par *par"
.\"Fd #define SIO_BPS(bits) .\"Fd #define SIO_BPS(bits)
@ -159,47 +167,43 @@ struct sio_par {
.Pp .Pp
The parameters are as follows: The parameters are as follows:
.Bl -tag -width "appbufsz" .Bl -tag -width "appbufsz"
.It Va bits .It Fa bits
Number of bits per sample: must be between 1 and 32. Number of bits per sample: must be between 1 and 32.
.It Va bps .It Fa bps
Bytes per samples; if specified, it must be large enough to hold all bits. Bytes per samples; if specified, it must be large enough to hold all bits.
By default it's set to the smallest power of two large enough to hold By default it's set to the smallest power of two large enough to hold
.Va bits . .Fa bits .
.It Va sig .It Fa sig
If set (i.e. non-zero) then the samples are signed, else unsigned. If set (i.e. non-zero) then the samples are signed, else unsigned.
.It Va le .It Fa le
If set, then the byte order is little endian, else big endian; If set, then the byte order is little endian, else big endian;
it's meaningful only if it's meaningful only if
.Va bps .Fa bps No > 1 .
\*(Gt 1. .It Fa msb
.It Va msb
If set, then the If set, then the
.Va bits .Fa bits
are aligned in the packet to the most significant bit are aligned in the packet to the most significant bit
(i.e. lower bits are padded), (i.e. lower bits are padded),
else to the least significant bit else to the least significant bit
(i.e. higher bits are padded); (i.e. higher bits are padded);
it's meaningful only if it's meaningful only if
.Va bits .Fa bits No < Fa bps No * 8 .
\*(Lt .It Fa rchan
.Va bps
* 8.
.It Va rchan
The number of recorded channels; meaningful only if The number of recorded channels; meaningful only if
.Dv SIO_REC .Dv SIO_REC
mode was selected. mode was selected.
.It Va pchan .It Fa pchan
The number of played channels; meaningful only if The number of played channels; meaningful only if
.Dv SIO_PLAY .Dv SIO_PLAY
mode was selected. mode was selected.
.It Va rate .It Fa rate
The sampling frequency in Hz. The sampling frequency in Hz.
.It Va bufsz .It Fa bufsz
The maximum number of frames that may be buffered. The maximum number of frames that may be buffered.
This parameter takes into account any buffers, and This parameter takes into account any buffers, and
can be used for latency calculations. can be used for latency calculations.
It is read-only. It is read-only.
.It Va appbufsz .It Fa appbufsz
Size of the buffer in frames the application must maintain non-empty Size of the buffer in frames the application must maintain non-empty
(on the play end) or non-full (on the record end) by calling (on the play end) or non-full (on the record end) by calling
.Fn sio_write .Fn sio_write
@ -208,11 +212,11 @@ or
fast enough to avoid overrun or underrun conditions. fast enough to avoid overrun or underrun conditions.
The audio subsystem may use additional buffering, thus this The audio subsystem may use additional buffering, thus this
parameter cannot be used for latency calculations. parameter cannot be used for latency calculations.
.It Va round .It Fa round
Optimal number of frames that the application buffers Optimal number of frames that the application buffers
should be a multiple of, to get best performance. should be a multiple of, to get best performance.
Applications can use this parameter to round their block size. Applications can use this parameter to round their block size.
.It Va xrun .It Fa xrun
The action when the client doesn't accept The action when the client doesn't accept
recorded data or doesn't provide data to play fast enough; recorded data or doesn't provide data to play fast enough;
it can be set to one of the it can be set to one of the
@ -268,13 +272,13 @@ following macros can be used:
.Bl -tag -width "SIO_BPS(bits)" .Bl -tag -width "SIO_BPS(bits)"
.It Dv SIO_BPS Ns Pq Fa bits .It Dv SIO_BPS Ns Pq Fa bits
Return the smallest value for Return the smallest value for
.Va bps .Fa bps
that is a power of two and that is large enough to that is a power of two and that is large enough to
hold hold
.Fa bits . .Fa bits .
.It Dv SIO_LE_NATIVE .It Dv SIO_LE_NATIVE
Can be used to set the Can be used to set the
.Va le .Fa le
parameter when native byte order is required. parameter when native byte order is required.
.El .El
.Ss Getting device capabilities .Ss Getting device capabilities
@ -325,50 +329,50 @@ struct sio_cap {
.Pp .Pp
The parameters are as follows: The parameters are as follows:
.Bl -tag -width "rchan[SIO_NCHAN]" .Bl -tag -width "rchan[SIO_NCHAN]"
.It Va enc Ns Bq Dv SIO_NENC .It Fa enc Ns Bq Dv SIO_NENC
Array of supported encodings. Array of supported encodings.
The tuple of The tuple of
.Va bits , .Fa bits ,
.Va bps , .Fa bps ,
.Va sig , .Fa sig ,
.Va le , .Fa le ,
and and
.Va msb .Fa msb
parameters are usable in the corresponding parameters parameters are usable in the corresponding parameters
of the of the
.Vt sio_par .Vt sio_par
structure. structure.
.It Va rchan Ns Bq Dv SIO_NCHAN .It Fa rchan Ns Bq Dv SIO_NCHAN
Array of supported channel numbers for recording usable Array of supported channel numbers for recording usable
in the in the
.Vt sio_par .Vt sio_par
structure. structure.
.It Va pchan Ns Bq Dv SIO_NCHAN .It Fa pchan Ns Bq Dv SIO_NCHAN
Array of supported channel numbers for playback usable Array of supported channel numbers for playback usable
in the in the
.Vt sio_par .Vt sio_par
structure. structure.
.It Va rate Ns Bq Dv SIO_NRATE .It Fa rate Ns Bq Dv SIO_NRATE
Array of supported sample rates usable Array of supported sample rates usable
in the in the
.Vt sio_par .Vt sio_par
structure. structure.
.It Va nconf .It Fa nconf
Number of different configurations available, i.e. number Number of different configurations available, i.e. number
of filled elements of the of filled elements of the
.Va confs[] .Fa confs Ns Bq
array. array.
.It Va confs Ns Bq Dv SIO_NCONF .It Fa confs Ns Bq Dv SIO_NCONF
Array of available configurations. Array of available configurations.
Each configuration contains bitmasks indicating which Each configuration contains bitmasks indicating which
elements of the above parameter arrays are valid for the elements of the above parameter arrays are valid for the
given configuration. given configuration.
For instance, if the second bit of For instance, if the second bit of
.Va rate .Fa rate
is set, in the is set, in the
.Vt sio_conf .Vt sio_conf
structure, then the second element of the structure, then the second element of the
.Va rate Ns Bq Dv SIO_NRATE .Fa rate Ns Bq Dv SIO_NRATE
array of the array of the
.Vt sio_cap .Vt sio_cap
structure is valid for this configuration. structure is valid for this configuration.
@ -485,7 +489,7 @@ it is not selected with
.Fn sio_pollfd . .Fn sio_pollfd .
.Pp .Pp
The size of the The size of the
.Ar pfd .Fa pfd
array, which the caller must pre-allocate, is provided by the array, which the caller must pre-allocate, is provided by the
.Fn sio_nfds .Fn sio_nfds
function. function.
@ -534,7 +538,7 @@ latency can be obtained by subtracting the current position
from the number of frames written. from the number of frames written.
Once playback is actually started (first sample audible) Once playback is actually started (first sample audible)
the latency will never exceed the the latency will never exceed the
.Va bufsz .Fa bufsz
parameter (see the sections above). parameter (see the sections above).
There's a phase during which There's a phase during which
.Fn sio_write .Fn sio_write
@ -543,7 +547,7 @@ once there's enough data, actual playback starts.
During this phase talking about latency is meaningless. During this phase talking about latency is meaningless.
.Pp .Pp
In any cases, at most In any cases, at most
.Va bufsz .Fa bufsz
frames are buffered. frames are buffered.
This value takes into account all buffers. This value takes into account all buffers.
The number of frames stored is equal to the number of frames The number of frames stored is equal to the number of frames
@ -563,13 +567,13 @@ for this.
.Ss Handling buffer overruns and underruns .Ss Handling buffer overruns and underruns
When the application cannot accept recorded data fast enough, When the application cannot accept recorded data fast enough,
the record buffer (of size the record buffer (of size
.Va appbufsz ) .Fa appbufsz )
might overrun; in this case recorded data is lost. might overrun; in this case recorded data is lost.
Similarly if the application cannot provide data to play Similarly if the application cannot provide data to play
fast enough, the play buffer underruns and silence is played fast enough, the play buffer underruns and silence is played
instead. instead.
Depending on the Depending on the
.Va xrun .Fa xrun
parameter of the parameter of the
.Vt sio_par .Vt sio_par
structure, the audio subsystem will behave as follows: structure, the audio subsystem will behave as follows:
@ -602,7 +606,7 @@ is still incremented.
When the play buffer underruns the play latency might become negative; When the play buffer underruns the play latency might become negative;
when the record buffer overruns, the record latency might become when the record buffer overruns, the record latency might become
larger than larger than
.Va bufsz . .Fa bufsz .
.Pp .Pp
This mode is suitable for applications, like music production, This mode is suitable for applications, like music production,
where time is important and where underruns or overruns are where time is important and where underruns or overruns are
@ -656,8 +660,9 @@ are ignored.
.Pp .Pp
The The
.Fn sio_onvol .Fn sio_onvol
function can be called with a NULL argument to check whether function can be called with a
a volume knob is available. .Dv NULL
argument to check whether a volume knob is available.
.Ss Error handling .Ss Error handling
Errors related to the audio subsystem Errors related to the audio subsystem
(like hardware errors, dropped connections) and (like hardware errors, dropped connections) and
@ -677,7 +682,8 @@ function can be used at any stage.
.Sh RETURN VALUES .Sh RETURN VALUES
The The
.Fn sio_open .Fn sio_open
function returns the newly created handle on success or NULL function returns the newly created handle on success or
.Dv NULL
on failure. on failure.
.Pp .Pp
The The
@ -693,12 +699,12 @@ functions return 1 on success and 0 on failure.
The The
.Fn sio_pollfd .Fn sio_pollfd
function returns the number of function returns the number of
.Va pollfd .Vt pollfd
structures filled. structures filled.
The The
.Fn sio_nfds .Fn sio_nfds
function returns the number of function returns the number of
.Va pollfd .Vt pollfd
structures the caller must preallocate in order to be sure structures the caller must preallocate in order to be sure
that that
.Fn sio_pollfd .Fn sio_pollfd