Source-Changes-HG archive
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index][Old Index]
[src/trunk]: src Update manpages respond to isaki-audio2 branch.
details: https://anonhg.NetBSD.org/src/rev/475fd2777afb
branches: trunk
changeset: 451172:475fd2777afb
user: isaki <isaki%NetBSD.org@localhost>
date: Wed May 08 14:25:38 2019 +0000
description:
Update manpages respond to isaki-audio2 branch.
diffstat:
distrib/sets/lists/comp/mi | 8 +-
share/man/man4/audio.4 | 352 ++++++++++++++++++-----------------------
share/man/man9/Makefile | 4 +-
share/man/man9/audio.9 | 310 ++++++++++++++++++++----------------
share/man/man9/audio_system.9 | 307 ------------------------------------
share/man/man9/intro.9 | 7 +-
6 files changed, 340 insertions(+), 648 deletions(-)
diffs (truncated from 1435 to 300 lines):
diff -r 4ae100ce0010 -r 475fd2777afb distrib/sets/lists/comp/mi
--- a/distrib/sets/lists/comp/mi Wed May 08 14:10:42 2019 +0000
+++ b/distrib/sets/lists/comp/mi Wed May 08 14:25:38 2019 +0000
@@ -1,4 +1,4 @@
-# $NetBSD: mi,v 1.2272 2019/04/27 23:04:31 kamil Exp $
+# $NetBSD: mi,v 1.2273 2019/05/08 14:25:38 isaki Exp $
#
# Note: don't delete entries from here - mark them as "obsolete" instead.
./etc/mtree/set.comp comp-sys-root
@@ -10654,7 +10654,7 @@
./usr/share/man/cat9/arpresolve.0 comp-sys-catman .cat
./usr/share/man/cat9/atop.0 comp-sys-catman .cat
./usr/share/man/cat9/audio.0 comp-sys-catman .cat
-./usr/share/man/cat9/audio_system.0 comp-sys-catman .cat
+./usr/share/man/cat9/audio_system.0 comp-sys-catman obsolete
./usr/share/man/cat9/autoconf.0 comp-sys-catman .cat
./usr/share/man/cat9/bawrite.0 comp-sys-catman .cat
./usr/share/man/cat9/bcdtobin.0 comp-sys-catman .cat
@@ -18591,7 +18591,7 @@
./usr/share/man/html9/arpresolve.html comp-sys-htmlman html
./usr/share/man/html9/atop.html comp-sys-htmlman html
./usr/share/man/html9/audio.html comp-sys-htmlman html
-./usr/share/man/html9/audio_system.html comp-sys-htmlman html
+./usr/share/man/html9/audio_system.html comp-sys-htmlman obsolete
./usr/share/man/html9/autoconf.html comp-sys-htmlman html
./usr/share/man/html9/bawrite.html comp-sys-htmlman html
./usr/share/man/html9/bcdtobin.html comp-sys-htmlman html
@@ -26631,7 +26631,7 @@
./usr/share/man/man9/arpresolve.9 comp-sys-man .man
./usr/share/man/man9/atop.9 comp-sys-man .man
./usr/share/man/man9/audio.9 comp-sys-man .man
-./usr/share/man/man9/audio_system.9 comp-sys-man .man
+./usr/share/man/man9/audio_system.9 comp-sys-man obsolete
./usr/share/man/man9/autoconf.9 comp-sys-man .man
./usr/share/man/man9/bawrite.9 comp-sys-man .man
./usr/share/man/man9/bcdtobin.9 comp-sys-man .man
diff -r 4ae100ce0010 -r 475fd2777afb share/man/man4/audio.4
--- a/share/man/man4/audio.4 Wed May 08 14:10:42 2019 +0000
+++ b/share/man/man4/audio.4 Wed May 08 14:25:38 2019 +0000
@@ -1,4 +1,4 @@
-.\" $NetBSD: audio.4,v 1.87 2019/02/16 06:50:14 isaki Exp $
+.\" $NetBSD: audio.4,v 1.88 2019/05/08 14:25:39 isaki Exp $
.\"
.\" Copyright (c) 1996 The NetBSD Foundation, Inc.
.\" All rights reserved.
@@ -66,137 +66,40 @@
operations as
.Pa /dev/sound ,
but no other operations.
+It can be opened at any time and can be used to manipulate the
+audio device while it is in use.
.Pp
-.Pa /dev/sound
-and
-.Pa /dev/audio
-can be opened at
-.Em any
-time and audio sources of different precision and playback
-parameters i.e frequency will be mixed and played back simultaneously.
-.Pp
-.Pa /dev/audioctl
-can be used to manipulate the audio device
-while it is in use.
.Sh SAMPLING DEVICES
When
.Pa /dev/audio
-is opened, it automatically directs the underlying driver to manipulate
-monaural 8-bit mu-law samples.
-In addition, if it is opened read-only
-(write-only) the device is set to half-duplex record (play) mode with
-recording (playing) unpaused and playing (recording) paused.
+is opened, it automatically sets the track to manipulate
+monaural 8-bit mu-law 8000Hz.
When
.Pa /dev/sound
-is opened, it maintains the previous audio sample mode and
-record/playback mode most recently set on
-.Pa /dev/sound
-by any open channel.
+is opened, it maintains the audio format and pause/unpause
+state of the most recently opened track.
In all other respects
.Pa /dev/audio
and
.Pa /dev/sound
are identical.
-.Sh VIRTUAL CHANNELS
-Any process may open a sampling device at a given time.
-Any number of devices per process and file descriptors may be shared between
-processes.
.Pp
-Virtual channels are converted to a common format, signed linear encoding,
-frequency channels and precision.
-These can be modified to taste by the following
-.Xr sysctl 8
-variables:
-.Bl -tag -width "hw.driverN.precision" -compact -offset indent
-.It Li hw. Ns Ar driverN Ns Li .precision
-.It Li hw. Ns Ar driverN Ns Li .frequency
-.It Li hw. Ns Ar driverN Ns Li .channels
-.It Li hw. Ns Ar driverN Ns Li .latency
-.It Li hw. Ns Ar driverN Ns Li .multiuser
-.El
-.Pp
-Where
-.Ar driverN
-corresponds to the underlying audio device driver and device number.
-E.g. in the case of an
-.\" XXX: there's no hdafg(4) to xref to
-.Xr hdaudio 4
-supported device the variables would be:
-.Li hw.hdafg0.channels ,
-.Li hw.hdafg0.precision ,
-.Li hw.hdafg0.frequency .
-.Pp
-For best results, values close to the underlying hardware should be chosen.
-These variables may only be changed when the sampling device is not in use.
-.Pp
-The
-.Li hw. Ns Ar driverN Ns Li .latency
-.Xr sysctl 8
-variable controls the latency of the in-kernel mixer by varying the hardware
-blocksize.
-It accepts a value in milliseconds(ms), fractional values are not allowed.
-A value of zero will default to 150ms.
-.Pp
-If a static blocksize is enforced by the underlying hardware driver this value
-cannot be changed.
-.Pp
-For audio applications that do not specify a preferred blocksize when configuring
-the audio device, this will be the latency these applications have.
+On a full-duplex device, reads and writes may operate concurrently
+without interference.
+If a full-duplex capable audio device is opened for both reading and writing
+it will start in play mode but not start in record mode.
.Pp
-For audio applications that
-.Xr mmap 2
-the audio device for play back the resultant latency is a third (1/3) of the value
-of the
-.Li hw. Ns Ar driverN Ns Li .latency
-variable.
-.Pp
-The
-.Li hw. Ns Ar driverN Ns Li .multiuser
-.Xr sysctl 8
-variable determines if multiple users are allowed to access the sampling
-device.
-.Pp
-By default it is set to false.
-This means that the sampling device may be only used by
-.Em one
-user at a time.
-Other users (except root) attempting to open the sampling device will be
-denied.
-.Pp
-If set to true, all users may access the sampling device at any time.
+On a half-duplex device, if there are any recording descriptors already,
+opening with write mode will fail.
+Similarly, if there are any playback descriptors already,
+opening with read mode will fail.
+If both playback and recording are requested on a half-duplex device,
+it will be treated as playback mode.
.Pp
-Each virtual channel has a corresponding mixer:
-.Bl -tag -width "vchan.dacN" -compact -offset indent
-.It Li vchan.dac Ns Ar N
-Output volume
-.It Li vchan.mic Ns Ar N
-Recording volume
-.El
+On either type of device, opening with write mode will start in playback mode,
+opening with read mode will start in recording mode.
.Pp
-Where
-.Ar N
-is the virtual channel number.
-E.g.\&
-.Li vchan.dac0
-controlling playback volume and
-.Li vchan.mic0
-controlling recording volume for the first virtual channel.
-.Pp
-On a half-duplex device, writes while recording is in progress will be
-immediately discarded.
-Similarly, reads while playback is in progress
-will be filled with silence but delayed to return at the current
-sampling rate.
-If both playback and recording are requested on a half-duplex
-device, playback mode takes precedence and recordings will get silence.
-.Pp
-On a full-duplex device, reads and writes may operate
-concurrently without interference.
-If a full-duplex capable audio device is opened for both reading and writing
-it will start in half-duplex play mode; full-duplex mode has to be set
-explicitly.
-.Pp
-On either type of device, if the playback mode is paused then silence is
+If the playback mode is paused then silence is
played instead of the provided samples, and if recording is paused then
the process blocks in
.Xr read 2
@@ -206,46 +109,55 @@
.Xr write 2
frequently enough to provide samples at the pace the hardware
consumes them silence is inserted.
-If the
-.Dv AUMODE_PLAY_ALL
-mode is not set the writing process must
-provide enough data via
-subsequent write calls to
-.Dq catch up
-in time to the current audio
-block before any more process-provided samples will be played.
If a reading process does not call
.Xr read 2
frequently enough, it will simply miss samples.
.Pp
+The audio driver supports track multiplexing.
+All sampling devices can be opened at any time without interference.
+For playback, all tracks opened simultaneously are mixed,
+even if thier specified format is different.
+For recording, recorded data is distributed to all opened tracks,
+even if thier specified format is different.
+To achieve this, the audio driver has an small efficient encoding converter,
+a channel mixer, and a frequency conveter.
+The frequency conversion adapts the simplest way
+(interpolation method for upward, and simple thinning method for downward)
+due to restriction in kernel resources and processing time.
+It will work well in most case but don't expect excessively for its quality.
+.Pp
The audio device is normally accessed with
.Xr read 2
or
.Xr write 2
calls, but it can also be mapped into user memory with
-.Xr mmap 2
+.Xr mmap 2 .
Once the device has been mapped it can no longer be accessed
by read or write; all access is by reading and writing to
the mapped memory.
-The device appears as a block of memory
-of size
+The mmap'ped buffer appears as a block of memory of size
.Va buffersize
(as available via
.Dv AUDIO_GETINFO
or
.Dv AUDIO_GETBUFINFO ) .
-The device driver will continuously move data from this buffer
-from/to the audio hardware, wrapping around at the end of the buffer.
+The audio driver will continuously move data from this buffer
+from/to the mixing buffer, wrapping around at the end of the buffer.
To find out where the hardware is currently accessing data in the buffer the
.Dv AUDIO_GETIOFFS
and
.Dv AUDIO_GETOOFFS
calls can be used.
-The playing and recording buffers are distinct and must be
-mapped separately if both are to be used.
-Only encodings that are not emulated (i.e. where
+Note that
+.Xr mmap 2
+no longer maps hardware buffer directly.
+Now it is achieved by emulation so don't expect any improvements excessively
+rather than normal
+.Xr write 2 .
+For historical reasons, only encodings that are not set
.Dv AUDIO_ENCODINGFLAG_EMULATED
-is not set) work properly for a mapped device.
+is able to
+.Xr mmap 2 .
.Pp
The audio device, like most devices, can be used in
.Xr select 2 ,
@@ -262,26 +174,23 @@
.Xr ioctl 2
commands are supported on the sample devices:
.Bl -tag -width indent
-.It Dv AUDIO_GETCHAN (int)
-This command will return the audio channel in use.
-.It Dv AUDIO_SETCHAN (int)
-This command will select the audio channel for subsequent ioctl calls.
.It Dv AUDIO_FLUSH
This command stops all playback and recording, clears all queued
-buffers, resets error counters, and restarts recording and playback as
+buffers, resets error counters on this track,
+and restarts recording and playback as
appropriate for the current sampling mode.
.It Dv AUDIO_PERROR (int)
.It Dv AUDIO_RERROR (int)
This command fetches the count of dropped output (input)
-samples into its integer argument.
+bytes into its integer argument.
There is no information regarding when in the sample stream
they were dropped.
.It Dv AUDIO_WSEEK (u_long)
-This command fetches the count of samples that are queued ahead of the
+This command fetches the count of bytes that are queued ahead of the
first sample in the most recent sample block written into its integer argument.
Home |
Main Index |
Thread Index |
Old Index