sound: Separate implementations for SNDCTL_AUDIOINFO[_EX] and SNDCTL_ENGINEINFO

FreeBSD's implementation of SNDCTL_AUDIOINFO[_EX] and SNDCTL_ENGINEINFO
does not exactly work as intended. The problem is essentially that both
IOCTLs return the same information, while in fact the information
returned currently by dsp_oss_audioinfo() is what _only_
SNDCTL_ENGINEINFO is meant to return.

This behavior is also noted in the OSS manual [1] (see bold paragraph in
"Audio engines and device files" section), but since e8c0d15a64fa
("sound: Get rid of snd_clone and use DEVFS_CDEVPRIV(9)") we can
actually fix this, because we now expose only a single device for each
soundcard, and create the engines (channels) internally.
SNDCTL_ENGINEINFO will now report info about all channels in a given
device, and SNDCTL_AUDIOINFO[_EX] will only report information about
/dev/dspX.

To make this work, we also have to modify the SNDCTL_SYSINFO IOCTL to
report the number of audio devices and audio engines correctly.

While here, modernize the minimum and maximum channel counting in both
SNDCTL_AUDIOINFO[_EX] and SNDCTL_ENGINEINFO. Currently these IOCTLs will
report only up to 2 channels, which is no longer the case.

[1] http://manuals.opensound.com/developer/SNDCTL_AUDIOINFO.html

PR: 246231, 252761
Sponsored by: The FreeBSD Foundation
MFC after: 1 day
Reviewed by: dev_submerge.ch
Differential Revision: https://reviews.freebsd.org/D45164

sound: Retire unit.*

The unit.* code is largely obsolete and imposes limits that are no
longer needed nowadays.

- Capping the maximum allowed soundcards in a given machine. By default,
the limit is 512 (snd_max_u() in unit.c), and the maximum possible is
2048 (SND_UNIT_UMAX in unit.h). It can also be tuned through the
hw.snd.maxunit loader(8) tunable. Even though these limits are large
enough that they should never cause problems, there is no need for
this limit to exist in the first place.
- Capping the available device/channel types. By default, this is 32
(snd_max_d() in unit.c). However, these types are pre-defined in
pcm/sound.h (see SND_DEV_*), so the cap is unnecessary when we know
that their number is constant.
- Capping the number of channels per-device. By default, the limit 1024
(snd_max_c() in unit.c). This is probably the most problematic of the
limits mentioned, because this limit can never be reached, as the
maximum is hard-capped at either hw.snd.maxautovchans (16 by default),
or SND_MAXHWCHAN and SND_MAXVCHANS.

These limtits are encoded in masks (see SND_U_MASK, SND_D_MASK,
SND_C_MASK in unit.h) and are used to construct a bitfield of the form
[dsp_unit, type, channel_unit] in snd_mkunit() which is assigned to
pcm_channel->unit.

This patch gets rid of everything unit.*-related and makes a slightly
different use of the "unit" field to only contain the channel unit
number. The channel type is stored in a new pcm_channel->type field, and
the DSP unit number need not be stored at all, since we can fetch it
from device_get_unit(pcm_channel->dev). This change has the effect that
we no longer need to impose caps on the number of soundcards,
device/channel types and per-device channels. As a result the code is
noticeably simplified and more readable.

Apart from the fact that the hw.snd.maxunit loader(8) tunable is also
retired as a side-effect of this patch, sound(4)'s behavior remains the
same.

Sponsored by: The FreeBSD Foundation
MFC after: 1 week
Reviewed by: dev_submerge.ch
Differential Revision: https://reviews.freebsd.org/D44912

sound: Get rid of snd_clone and use DEVFS_CDEVPRIV(9)

Currently the snd_clone framework creates device nodes on-demand for
every channel, through the dsp_clone() callback, and is responsible for
routing audio to the appropriate channel(s). This patch gets rid of the
whole snd_clone framework (including any related sysctls) and instead
uses DEVFS_CDEVPRIV(9) to handle device opening, channel allocation and
audio routing. This results in a significant reduction in code size as
well as complexity.

Behavior that is preserved:

- hw.snd.basename_clone.
- Exclusive access of an audio device (i.e VCHANs disabled).
- Multiple processes can read from/write to the device.
- A device can only be opened as many times as the maximum allowed
channel number (see SND_MAXHWCHAN in pcm/sound.h).
- OSSv4 compatibility aliases are preserved.

Behavior changes:

Only one /dev/dspX device node is created (on attach) for each audio
device, as opposed to the current /dev/dspX.Y devices created by
snd_clone. According to the sound(4) man page, devices are not meant to
be opened through /dev/dspX.Y anyway, so it is best if we do not create
device nodes for them in the first place. As a result of this, modify
dsp_oss_audioinfo() to print /dev/dspX in the "ai->devnode", instead of
/dev/dspX.Y.

Sponsored by: The FreeBSD Foundation
MFC after: 2 months
Reviewed by: dev_submerge.ch, bapt, markj
Differential Revision: https://reviews.freebsd.org/D44411

Revert "sound: Get rid of snd_clone and use DEVFS_CDEVPRIV(9)"

This reverts commit dc831e93bad63f9faea09f1806a7733a40bff316.

After several reports in the mailing lists, this commit breaks
pulseaudio. Revert until the issue is resolved.

sound: Get rid of snd_clone and use DEVFS_CDEVPRIV(9)

Currently the snd_clone framework creates device nodes on-demand for
every channel, through the dsp_clone() callback, and is responsible for
routing audio to the appropriate channel(s). This patch gets rid of the
whole snd_clone framework (including any related sysctls) and instead
uses DEVFS_CDEVPRIV(9) to handle device opening, channel allocation and
audio routing. This results in a significant reduction in code size as
well as complexity.

Behavior that is preserved:

- hw.snd.basename_clone.
- Exclusive access of an audio device (i.e VCHANs disabled).
- Multiple processes can read from/write to the device.
- A device can only be opened as many times as the maximum allowed
channel number (see SND_MAXHWCHAN in pcm/sound.h).
- OSSv4 compatibility aliases are preserved.

Behavior changes:

Only one /dev/dspX device node is created (on attach) for each audio
device, as opposed to the current /dev/dspX.Y devices created by
snd_clone. According to the sound(4) man page, devices are not meant to
be opened through /dev/dspX.Y anyway, so it is best if we do not create
device nodes for them in the first place. As a result of this, modify
dsp_oss_audioinfo() to print /dev/dspX in the "ai->devnode", instead of
/dev/dspX.Y.

Sponsored by: The FreeBSD Foundation
MFC after: 2 months
Reviewed by: dev_submerge.ch, markj
Differential Revision: https://reviews.freebsd.org/D44411

sys: Remove $FreeBSD$: two-line .h pattern

Remove /^\s*\*\n \*\s+\$FreeBSD\$$\n/

spdx: The BSD-2-Clause-FreeBSD identifier is obsolete, drop -FreeBSD

The SPDX folks have obsoleted the BSD-2-Clause-FreeBSD identifier. Catch
up to that fact and revert to their recommended match of BSD-2-Clause.

Discussed with: pfg
MFC After: 3 days
Sponsored by: Netflix

sys/dev: further adoption of SPDX licensing ID tags.

Mainly focus on files that use BSD 2-Clause license, however the tool I
was using misidentified many licenses so this was mostly a manual - error
prone - task.

The Software Package Data Exchange (SPDX) group provides a specification
to make it easier for automated tools to detect and summarize well known
opensource licenses. We are gradually adopting the specification, noting
that the tags are considered only advisory and do not, in any way,
superceed or replace the license texts.

A new jail(8) with a configuration file, to replace the work currently done
by /etc/rc.d/jail.

Sound Mega-commit. Expect further cleanup until code freeze.

For a slightly thorough explaination, please refer to
[1] http://people.freebsd.org/~ariff/SOUND_4.TXT.html .

Summary of changes includes:

1 Volume Per-Channel (vpc). Provides private / standalone volume control
unique per-stream pcm channel without touching master volume / pcm.
Applications can directly use SNDCTL_DSP_[GET|SET][PLAY|REC]VOL, or for
backwards compatibility, SOUND_MIXER_PCM through the opened dsp device
instead of /dev/mixer. Special "bypass" mode is enabled through
/dev/mixer which will automatically detect if the adjustment is made
through /dev/mixer and forward its request to this private volume
controller. Changes to this volume object will not interfere with
other channels.

Requirements:
- SNDCTL_DSP_[GET|SET][PLAY|REC]_VOL are newer ioctls (OSSv4) which
require specific application modifications (preferred).
- No modifications required for using bypass mode, so applications
like mplayer or xmms should work out of the box.

Kernel hints:
- hint.pcm.%d.vpc (0 = disable vpc).

Kernel sysctls:
- hw.snd.vpc_mixer_bypass (default: 1). Enable or disable /dev/mixer
bypass mode.
- hw.snd.vpc_autoreset (default: 1). By default, closing/opening
/dev/dsp will reset the volume back to 0 db gain/attenuation.
Setting this to 0 will preserve its settings across device
closing/opening.
- hw.snd.vpc_reset (default: 0). Panic/reset button to reset all
volume settings back to 0 db.
- hw.snd.vpc_0db (default: 45). 0 db relative to linear mixer value.

2 High quality fixed-point Bandlimited SINC sampling rate converter,
based on Julius O'Smith's Digital Audio Resampling -
http://ccrma.stanford.edu/~jos/resample/. It includes a filter design
script written in awk (the clumsiest joke I've ever written)
- 100% 32bit fixed-point, 64bit accumulator.
- Possibly among the fastest (if not fastest) of its kind.
- Resampling quality is tunable, either runtime or during kernel
compilation (FEEDER_RATE_PRESETS).
- Quality can be further customized during kernel compilation by
defining FEEDER_RATE_PRESETS in /etc/make.conf.

Kernel sysctls:
- hw.snd.feeder_rate_quality.
0 - Zero-order Hold (ZOH). Fastest, bad quality.
1 - Linear Interpolation (LINEAR). Slightly slower than ZOH,
better quality but still does not eliminate aliasing.
2 - (and above) - Sinc Interpolation(SINC). Best quality. SINC
quality always start from 2 and above.

Rough quality comparisons:
- http://people.freebsd.org/~ariff/z_comparison/

3 Bit-perfect mode. Bypasses all feeder/dsp effects. Pure sound will be
directly fed into the hardware.

4 Parametric (compile time) Software Equalizer (Bass/Treble mixer). Can
be customized by defining FEEDER_EQ_PRESETS in /etc/make.conf.

5 Transparent/Adaptive Virtual Channel. Now you don't have to disable
vchans in order to make digital format pass through. It also makes
vchans more dynamic by choosing a better format/rate among all the
concurrent streams, which means that dev.pcm.X.play.vchanformat/rate
becomes sort of optional.

6 Exclusive Stream, with special open() mode O_EXCL. This will "mute"
other concurrent vchan streams and only allow a single channel with
O_EXCL set to keep producing sound.

Other Changes:
* most feeder_* stuffs are compilable in userland. Let's not
speculate whether we should go all out for it (save that for
FreeBSD 16.0-RELEASE).
* kobj signature fixups, thanks to Andriy Gapon <avg@freebsd.org>
* pull out channel mixing logic out of vchan.c and create its own
feeder_mixer for world justice.
* various refactoring here and there, for good or bad.
* activation of few more OSSv4 ioctls() (see [1] above).
* opt_snd.h for possible compile time configuration:
(mostly for debugging purposes, don't try these at home)
SND_DEBUG
SND_DIAGNOSTIC
SND_FEEDER_MULTIFORMAT
SND_FEEDER_FULL_MULTIFORMAT
SND_FEEDER_RATE_HP
SND_PCM_64
SND_OLDSTEREO

Manual page updates are on the way.

Tested by: joel, Olivier SMEDTS <olivier at gid0 d org>, too many
unsung / unnamed heroes.

- Import the HEAD csup code which is the basis for the cvsmode work.

Last (again ?!?) major commit for RELENG_7, featuring total Giant
eradication in/from userland path, countless locking fixes, etc.

- General sleep call through msleep(9) has been converted to condvar(9)
with better consistencies.
- Heavily guard every possible "slow path" entries (open(), close(),
few ioctl()s, sysctls), but once it entering "fast path" (io, interrupt
started), they are free to fly on their own.
- Rearrange locking sequences, resulting better concurrency and
serialization. Large part doesn't even need locking at all, and will be
removed in future. Less clutter, except in few places due to lock
ordering.
- Anonymous mixer object creation/deletion to simplify mixer handling
beyond typical mixer ioctls.
Submitted by: chibis (with modifications)
- Add few mix_[get|set|..] functions to avoid calling mixer_ioctl()
directly using cryptic arguments.
- Locking fixes to avoid possible deadlock with (still under Giant) USB.
- Better simplex/duplex device handling.
- Recover mmap() functionality for recording, which has been lost
since 2.2.x - 3.x (the introduction of newpcm). Full-duplex mmap still
doesn't work (due to VM/page design), but people still can mmap
both by opening each direction separately. mmaped playback is guarantee
to work either way.
- New sysctl: "hw.snd.compat_linux_mmap" to allow PROT_EXEC page
mapping, due to recent changes in linux compatibility layer which
require it. All linux applications that using sound + mmap() (mostly games)
require this to be enabled. Disabled by default.
- Other goodies.. too many, that will increase releng7 shareholder value
and make users of releng6 (and below) cry ;)

* This commit should be atomic. If anything goes wrong (not counting problem
originated from elsewhere), I will not hesitate to revert everything back
within 12 hours. This substantial changes itself not a rocket science
and the process has begun for almost 2 years, and lots of incremental
changes are already in place during that period of time.
* Some issues does occur in snd_emu10kx (note the 'x') due to various
internal locking issues and it is currently being worked on by chibis.

Tested by: chibis (Yuriy Tsibizov), joel, Alexandre Vieira,
many innocent souls...

Last major commit and updates for RELENG_7:

- Rework the entire pcm_channel structure:
* Remove rarely used link placeholder, instead, make each pcm_channel
as head/link of each own/each other. Unlock - Lock sequence due to
sleep malloc has been reduced.
* Implement "busy" queue which will contain list of busy/active
channels. This greatly reduce locking contention for example while
servicing interrupt for hardware with many channels or when virtual
channels reach its 256 peak channels.

- So I heard you like v chan ... O RLY?
Welcome to Virtual **Record** Channels (vrec, rec vchans, vchans for
recording, Rec-Chan, you decide), the ultimate solutions for your
nagging O_RDWR full-duplex wannabe (note: flash plugins) monopolizing
single record channel causing EBUSY. Vrec works exactly like Vchans
(or, should I rename it to "Vplay" :) , except that it operates on the
opposite direction (recording). Up to 256 vrecs (like vchans) are
possible.

Notes:
* Relocate dev.pcm.%d.{vchans,vchanformat,vchanrate} to each of its
respective node/direction:
dev.pcm.%d.play.* for "play" (cdev = dsp%d.vp%d)
dev.pcm.%d.rec.* for "record" (cdev = dsp%d.vr%d)
* Don't expect that it will magically give you ability to split
"recording source" (eg: 1 channel for cdrom, 1 channel for mic,
etc). Just admit that you only have a *single* recording source /
channel. Please bug your hardware vendor instead :)

- Bump maxautovchans from 4 to 16. For a full-fledged multimedia
desktop/workstation with too many soundservers installed (esound,
artsd, jackd, pulse/polypaudio, ding-dong pling plong mudkip fuh fuh,
etc), 4 seems inadequate. There will be no memory penalty here, since
virtual channels are allocate only by demand.

- Nuke/Rework the entire statically created cdev entries. Everything is
clonable through snd own clone manager which designed to withstand many
kind of abusive devfs droids such as:
* while : ; do /bin/test -e /dev/dsp ; done
* jot 16777216 0 | while read x ; do ls /dev/dsp0.$x ; done
* hundreds (could be thousands) concurrent threads/process opening
"/dev/dsp" (previously, this might result EBUSY even with just
3 contesting threads/procs).
o Reusable clone objects (instead of creating new one like there's no
tomorrow) after certain expiration deadline. The clone allocator will
decide whether to reuse, share, or creating new clone.
o Automatic garbage collector.

- Dynamic unit magic allocator. Maximum attached soundcards can be tuned
using tunable "hw.snd.maxunit" (Default to 512). Minimum is 16, and
maximum is 2048.

- ..other fixes, mostly related to concurrency issues.

joel@ will do the manpage updates on sound(4).

Have fun.

Put #ifndef... after the license.

Approved by: ariff

MFp4 the sound Google Summer of Code project:

The goal was to sync with the OSSv4 API 4Front Technologies uses in their
proprietary OSS driver. This was successful as far as possible. The part
of the API which is stable is implemented, for the rest there are some
stubs already.

New system ioctls:
- SNDCTL_SYSINFO - obtain audio system info (version, # of audio/midi/
mixer devices, etc.)
- SNDCTL_AUDIOINFO - fetch details about a specific audio device
- SNDCTL_MIXERINFO - fetch details about a specific mixer device

New audio ioctls:
- Sync groups (SNDCTL_DSP_SYNCGROUP/SNDCTL_DSP_SYNCSTART) which allow
triggered playback/recording on multiple devices (even across processes
simultaneously).
- Peak meters (SNDCTL_DSP_GETIPEAKS/SNDCTL_DSP_GETOPEAKS) - can query
audio drivers for peak levels (needs driver support, disabled for now).
- Per channel playback/recording levels -
SNDCTL_DSP_{GET,SET}{PLAY,REC}VOL. Note that these are still in name
only, just wrapping around the AC97-style mixer at the moment. The next
step is to push them down to the drivers.

Audio ioctls still under development by 4Front (for which stubs may exist
in this commit):
- SNDCTL_GETNAME, SNDCTL_{GET,SET}{SONG,LABEL}
- SNDCTL_DSP_{GET,SET}_CHNORDER
- SNDCTL_MIX_ENUMINFO, SNDCTL_MIX_EXTINFO - (might be documented enough in
the OSS releases to work on this. These ioctls cover the cool "twiddle
any knob on your card" features.)

Missing:
- SNDCTL_DSP_COOKEDMODE -- this ioctl is used to give applications direct
access to a card's buffers, bypassing the feeder architecture. It's
a toughy -- "someone" needs to decide :
(a) if this is desireable, and (b) if it's reasonably feasible.

Updates for driver writers:
So far, only two routines to the channel class (in channel_if.m) are added.
One is for fetching a list of discrete supported playback/recording rates
of a channel, and the other is for fetching peak level info (useful for
drawing peak meters). Interested parties may want to help pushing down
SNDCTL_DSP_{GET,SET}{PLAY,REC}VOL into the drivers.

To use the new stuff you need to rebuild the sound drivers or your kernel
(depending on if you use modules or not) and to install soundcard.h (a
buildworld/installworld handles this).

Sponsored by: Google SoC 2006
Submitted by: ryanb
Many thanks to: 4Front Technologies for their cooperation, explanations
and the nice license of their soundcard.h.

Start each of the license/copyright comments with /*-, minor shuffle of lines

Fix a panic when kldloading a sound driver. Do this by replacing the
link-list of dev_t's with named variables. Remove used code.

Approved by: tanimura (mentor)

update my email address.

add a method for recording of specific channels for devices with more than
one hardware record channel. new devices, /dev/dsprX.Y where X is unit
number and Y is channel index.

use a global devclass for all drivers - i'm not entirely sure why this
worked before.

mixer, dsp and sndstat are seperate devices - give them their own cdevsws
instead of demuxing requests sent to a single cdevsw.

use the si_drv1/si_drv2 fields in dev_t structures for holding information
specific to an open instance of mixer/dsp.

nuke /dev/{dsp,dspW,audio}[0-9]* links - this functionality is now provided
using cloning.

various locking fixes.

beginnings of virtual playback channel support

instead of using two malloced arrays for storing channel lists, use an
slist. convert the sndstat device to use sbufs and optionally provide more
detail about channel state.

vchans are software mixed playback channels. they are not enabled by this
commit. they use the feeder infrastructure to emulate normal playback
channels in a manner transparent to applications, whilst providing as many
channels are desired, especially suitable for devices with only one hardware
playback channel. in the future they will provide additional features.

those wishing to test this functionality will need to add vchan.c to
sys/conf/files and use 'sysctl -w hw.snd.pcm0.vchans' to enable it.

blocksize and auto-rate selection are not yet supported.

mega-commit.

this introduces a new buffering mechanism which results in dramatic
simplification of the channel manager.

as several structures have changed, we take the opportunity to move their
definitions into the source files where they are used, make them private and
de-typedef them.

the sound drivers are updated to use snd_setup_intr instead of
bus_setup_intr, and to comply with the de-typedefed structures.

the ac97, mixer and channel layers have been updated with finegrained
locking, as have some drivers- not all though. the rest will follow soon.

$Id$ -> $FreeBSD$

say hello to newpcm. it is not yet enabled, requiring new pnp code from dfr
to compile successfully. further details will be provided in the commit
enabling newpcm.