audio.4: Document how the "delta" affects setting mixer levels.

Explicitly say that "delta" is optional and may be zero. While this
hasn't previously been specified anywhere (to my knowledge), the best
de-facto specification we have (sb and mixerctl source code) points
towards the historical practice being there.

audio.4: fix grammar and style in places

No change to technical content.

Remove an old description.
This behavior was modified in sys/dev/audio/audio.c rev 1.65 (Mar. 2020).

Remove trailing whitespace.

Add description about channel limitation introduced in audio.c 1.43.
PR kern/54973.

Revert 1.96, 1.97 and 1.100. (no response from nia@)
These changes are not correct nor notable unresolvable problem.
If you find any problems, please send a report before changing manpage.

audio.4: 1-12 channels are only universally supported for playback.

When a mono recording device is set to use 1 channel, the kernel will
correct the number of channels back down to 1. This information can be
obtained with AUDIO_GETINFO...

audio.4: Mention the blk_ms sysctl

Sort sections.

audio.4: O_NONBLOCK isn't the actual problem

audio.4: Remove reference to using O_NONBLOCK

It doesn't work properly, but this turns out to not be a problem in most
code (code where it is generally uses threads)...

Don't provide misleading information about using it, or programmers
might start wondering why their code doesn't work.

Noted by Yorick Hardy on current-users

Sort SEE ALSO.

Replace mention of azalia with hdaudio

Add some audio drivers in SEE ALSO.

Remove self-reference

Update list of audio drivers in SEE ALSO.

Based on audioplay(1) man page, where I'll remove them shortly.

branches: 1.90.2;
Bump date.

Fix some typos, improve wording and formatting.

Update manpages respond to isaki-audio2 branch.

Two minor fixes.
- Add missing AUDIO_PERROR (since 1996!)
- Sort AUDIO_GETFD.

branches: 1.86.2;
Move the audio specification to section 9 under audio_system.

Ok wiz@

Add the audio mixer specification to section 7 of the manual.
See posting on tech-kern - "NetBSD Audio Specification 2018."

branches: 1.84.2;
Use .Ar to mark up the variable parts of sysctl nodes.

Drive-by markup improvements.

Bump date for previous. Remove superfluous Pp.

Document the hw.driverN.latency sysctl variable.

Remove workaround for ancient HTML generation code.

branches: 1.79.2;
Audio mmap now works with all devices as hw->mappage is no longer used.
Audio ring buffers are now uvm objects.

This was made possibile with help from christos@ and much help and mmap
functions written by riastradh@.

branches: 1.78.2;
Improved mixing function - more expensive in cycles though.
hw.driverN.saturate is no longer needed and has been removed.

Mixing function thanks to jmcneill@.

hw.driverN.saturate bool->integer (default 16).

This means for a greater number than 16 (or user set value) the saturate
function is turned off. Results in better listening if a large number of
channels are in use.

Renane ioctl AUDIO_SETPROC to AUDIO_SETCHAN.

Add an ioctl to return channel number (AUDIO_GETCHAN). This can be used
on audio/sound/audioctl devices.

Return EIO in read/write/ioctl/poll/stat if fp has been closed or is
invalid.

Update audio.4, audioio.h and audioctl(1) to reflect these changes.

Sort sections.

Audio now uses fdclone, there is no longer a limitation of one audio
instance per process. Virtual channels are placed in a queue, so there is
no longer a compile time limit of VAUDIOCHANS.

A new sysctl has been added to control multiple user access.
Mixer labels on virtual channels are now prefixed by vchan.

audiobell.c and audioctl have been updated to reflect these changes.

Use of fdclone was posted to tech-kern@ and improvements made.
Multiuser access control changes and the use of a queue were suggessted by
pgoyette@

branches: 1.73.2;
Update audio man page with regard to audio changes.
OK wiz@

branches: 1.72.24;
Document AUDIO_ENCODING_AC3

AUDIO_WSEEK uses a u_long, not a int.

branches: 1.70.2;
Add support for playback- or capture-only devices by adding
AUDIO_PROP_PLAYBACK and AUDIO_PROP_CAPTURE properties.

From jmcneill@.

Fixes PR#42050

remove siisata and esl. (KIYOHARA Takashi)

branches: 1.68.4; 1.68.8;
Convert TNF licenses to new 2 clause variant

branches: 1.67.10; 1.67.12;
Whitespace nits.

Add a new ioctl AUDIO_GETBUFINFO. It works like AUDIO_GETINFO, but
doesn't obtain the ports, gain and balance related parameters.
Those generally require reading from the hardware and therefore are much
more expensive to obtain. Modify OSS emulation to use the new ioctl
where possible.

This reduces CPU usage of mplayer during mp3 playback with my Thinkpad
from 20% to < 1% and from 50% to 20% during Xvid playback.

Review and comments from jmcneill@

branches: 1.65.6; 1.65.8;
Bump date for previous.

Make <sys/audioio.h> include prerequisite headers; audio(4) was incomplete
with regard to required headers, and besides that it also matches Solaris.

add references to auixp(4) and azalia(4)

Also remove references to sp(4) (same as pss(4)).

Remove references to removed pss(4).

Add auacer.

Various fixes from Sergey Svishchev svs at ropnet ru in private mail.
Some additional "new sentence, new line" changes while I was there.

Bump date for previous.

Fix a couple of long-standing bugs in the volume control(s) part of the
audio device interface:

1) When attempting to match the appropriate mixer control, we weren't
checking the class label, but only the second level label, so for
devices that had both an "inputs.cd" and a "record.cd", for example,
we could never do the right thing except by chance. For this reason,
evidently, all the record masters were labeled (by the underlying
drivers) either "record.record" or "record.volume", to distinguish
from "outputs.master". We'll now accept "record.master", and document
that as the the new preferred way.

2) More importantly, the model was deficient. Selecting a port on many
chips completely disables most of the level controls, which doesn't play
nice with other applications which are trying to use the interface. Now,
selecting a port simply sets which mixer input control shall be changed,
setting state in the audio layer. In other words, the "mixerout" port
is really selected all the time, enabling the final stage mixer, and
setting "gain" sets the level of the appropriate input. It should be
possible for separate applications to each control the mic, dac, and cd
inputs at the same time using this interface, simply by reiterating their
port selections with each change, but applications that don't bother to
do that aren't any worse off than they were before.

The user is expected to set the master output with another application,
dedicated to that task. Though it is now meaningful to select "no port"
with the audio device interface, to manipulate the master output, there's
no particular reason for an audio device consumer to do that. (I added
the capability in order to restore the initial state of the audio device,
for testing purposes. It might also be useful to users of broken binary-
only applications.)

Observe that the mixer device interface (and so, "mixerctl") still
retains all capabilities, including the ability to set the actual input
port on the chip, overriding the level controls. No change is being made
to the mixer device interface. The mixer device simply presents all the
controls on the chip, with no attempt at abstraction, so there are no
bugs there.

The upshot is, that applications that have been trying to use the audio
device interface to change the volume, such as mplayer, now "just work".

I've tested these changes extensively with "eso" and "eap" since first
proposing them on tech-kern last January, and somewhat with "esm" and a
few others. This closes both PR kern/10221, and PR kern/17159.

Complete typedef of struct audio_info to audio_info_t.
From Jared Yanovich via jmc@openbsd.

There is no als(4).

.Li Dv -> .Dv.

Update the SEE ALSO list with drivers that have been added since
1997 (when this man page was updated?). Change an ugly .br hack
into .Ss macros. Add paragraph breaks in a few places to improve
readability.

Use
.In header.h
instead of
.Fd #include \*[Lt]header.h\*[Gt]
Much easier to read and write, and supported by groff for ages.
Okayed by ross.

Respect the law: Use A-law and mu-law as spellings as far as easily possible.
Inspired by Igor Sobrado in PR 19680.

Use .Dv for AudioN* and AudioC*

Fix capitalization error, noted by uwe.
Minor mandoc improvements while I'm here.

Fix typo.

Generate <>& symbolically. I'm avoiding .../dist/... directories for now.

Drop trailing whitespace.

A number of small fixes from Sergey Svishchev.

Add a cross reference to esa(4).

Xref.

Remove a 'the'.

Xref esl(4).

Whitespace&punctuation fixes, sort SEE ALSO, sort sections, drop .Pp's,
swap empty lines for .Pp's.

Typos/whitespace.

Manual page for Yamaha YMF724/740/744/754 PCI audio driver.

Add clct(4) man page.

Add reference to esm(4)

branches: 1.35.4;
Fix formatting glitches.

Fix typo.

Xref cmpci(4).

Man page for auvia(4). Also xref fms(4) from audio(4).

Fix doubled 'the's.

Xref clcs(4).

Add missing "that" in WSEEK description. By wiz@danbala.ifoer.tuwien.ac.at
in PR 8684.

branches: 1.28.2;
Mention uaudio(4).

Fix typo noted by "Wiz" in PR misc/8061.

Xref eso(4).

Pasto.

branches: 1.24.2;
More and more of .Os cleanups. .Os is defined in the tmac.doc-common file,
so we shouldn't override it with versions in the manpages. Many more to
come.

Fix minor formatting error.

Minor touchup and add sv man page.

Add a midi(4) man page.

Add info about mixer_level_t which has been missing for all these years.

Cross reference audioctl(1) and mixerctl(1).

Marathon man page editing session to fix broken .Xr's, add important
references, add a little white space here & there for readability,
clean up some mdoc(7) macro usage and so on. Whew!

Minor editorial changes.

Update for SunOS compatibility.

Cross reference ossaudio(3).

Fix tipo inherited from old version of TNF copyright form.
s/REGENTS/FOUNDATION/.

Man page for guspnp driver.

Make sure audio device starts in half-duplex mode and document the fact.

Document some minor changes in the audio interface.

Document how setting the blocksize works now.

Document /dev/audioctl.

Document how setting the blocksize works.

Update man pages a little.

Update man pages for new audio features.

Return audio buffer size in audio_info_t with ioctl() AUDIO_GETINFO.
Use the buffer size to implement one more OSS ioctl().

update to match reality a bit more closely. some parts are from John
Hawkinson (PR kern/2523) and Lennart Augustsson (PR misc/3303), rest
is by me.

Copyright assigned to the NetBSD Foundation

Fix typo, from John Kohl. Closes PR 2066.

audio(4) man page from John Kohl (submitted in PR#1752).