linux-toradex.git/include/sound/core.h, branch v5.18

ALSA: core: Add snd_card_free_on_error() helper

2022-04-12T09:47:57+00:00

This is a small helper function to handle the error path more easily
when an error happens during the probe for the device with the
device-managed card.  Since devres releases in the reverser order of
the creations, usually snd_card_free() gets called at the last in the
probe error path unless it already reached snd_card_register() calls.
Due to this nature, when a driver expects the resource releases in
card->private_free, this might be called too lately.

As a workaround, one should call the probe like:

 static int __some_probe(...) { // do real probe.... }

 static int some_probe(...)
 {
	return snd_card_free_on_error(dev, __some_probe(dev, ...));
 }

so that the snd_card_free() is called explicitly at the beginning of
the error path from the probe.

This function will be used in the upcoming fixes to address the
regressions by devres usages.

Fixes: e8ad415b7a55 ("ALSA: core: Add managed card creation")
Cc: 
Link: https://lore.kernel.org/r/20220412093141.8008-2-tiwai@suse.de
Signed-off-by: Takashi Iwai

ALSA: core: Add device-managed request_dma()

2021-07-19T14:16:34+00:00

This patch adds a devres-supported helper for requesting an ISA DMA
channel that will be automatically freed at the device unbinding.
It'll be used by quite a few ISA sound drivers.

Link: https://lore.kernel.org/r/20210715075941.23332-4-tiwai@suse.de
Signed-off-by: Takashi Iwai

ALSA: core: Add managed card creation

2021-07-19T14:16:33+00:00

As a second step for preliminary to widen the devres usages among
sound drivers, this patch adds a new ALSA core API function,
snd_devm_card_new(), to create a snd_card object via devres.
When a card object is created by this new function, snd_card_free() is
called automatically and the card object resource gets released at the
device unbinding time.

However, the story isn't that simple.  A caveat is that we have to
call snd_card_free() at the very first of the whole resource release
procedure, in order to assure that the all exposed devices on
user-space are deleted and sync with processes accessing those devices
before releasing resources.

For achieving it, snd_card_register() adds a new devres action to
trigger snd_card_free() automatically when the given card object is a
"managed" one.  Since usually snd_card_register() is the last step of
the initialization, this should work in most cases.

With all these tricks, some drivers can get rid of the whole driver
remove callback code.

About a bit of implementation details: the patch adds two new flags to
snd_card object: managed and releasing.  The former indicates that the
object was created via snd_devm_card_new(), and the latter is used for
avoiding the double-free of snd_card_free() calls.  Both flags are
fairly internal and likely uninteresting to normal users.

Link: https://lore.kernel.org/r/20210715075941.23332-3-tiwai@suse.de
Signed-off-by: Takashi Iwai

ALSA: Drop superfluous argument from snd_power_wait()

2021-05-25T06:49:39+00:00

The power_state argument of snd_power_wait() is superfluous, receiving
only SNDRV_POWER_STATE_D0.  Let's drop it in all callers for
simplicity.

Reviewed-by: Jaroslav Kysela 
Acked-by: Mark Brown 
Link: https://lore.kernel.org/r/20210523090920.15345-6-tiwai@suse.de
Signed-off-by: Takashi Iwai

ALSA: control: Track in-flight control read/write/tlv accesses

2021-05-25T06:48:28+00:00

Although the power state check is performed in various places (e.g. at
the entrance of quite a few ioctls), there can be still some pending
tasks that already went into the ioctl handler or other ops, and those
may access the hardware even after the power state check.  For
example, kcontrol access ioctl paths that call info/get/put callbacks
may update the hardware registers.  If a system wants to assure the
free from such hw access (like the case of PCI rescan feature we're
going to implement in future), this situation must be avoided, and we
have to sync such in-flight tasks finishing beforehand.

For that purpose, this patch introduces a few new things in core code:
- A refcount, power_ref, and a wait queue, power_ref_sleep, to the
  card object
- A few new helpers, snd_power_ref(), snd_power_unref(),
  snd_power_ref_and_wait(), and snd_power_sync_ref()

In the code paths that call kctl info/read/write/tlv ops, we check the
power state with the newly introduced snd_power_ref_and_wait().  This
function also takes the card.power_ref refcount for tracking this
in-flight task.  Once after the access finishes, snd_power_unref() is
called to released the refcount in return.  So the driver can sync via
snd_power_sync_ref() assuring that all in-flight tasks have been
finished.

As of this patch, snd_power_sync_ref() is called only at
snd_card_disconnect(), but it'll be used in other places in future.

Note that atomic_t is used for power_ref intentionally instead of
refcount_t.  It's because of the design of refcount_t type; refcount_t
cannot be zero-based, and it cannot do dec_and_test() call for
multiple times, hence it's not suitable for our purpose.

Also, this patch changes snd_power_wait() to accept only
SNDRV_CTL_POWER_D0, which is the only value that makes sense.
In later patch, the snd_power_wait() calls will be cleaned up.

Reviewed-by: Jaroslav Kysela 
Link: https://lore.kernel.org/r/20210523090920.15345-3-tiwai@suse.de
Signed-off-by: Takashi Iwai

ALSA: core: Use READ_ONCE() / WRITE_ONCE() for power state change

2021-05-25T06:48:03+00:00

We need proper barriers to handle the power state change of the card
from different CPUs.

Reviewed-by: Jaroslav Kysela 
Link: https://lore.kernel.org/r/20210523090920.15345-2-tiwai@suse.de
Signed-off-by: Takashi Iwai

ALSA: control: Add memory consumption limit to user controls

2021-04-08T11:31:03+00:00

ALSA control interface allows users to add arbitrary control elements
(called "user controls" or "user elements"), and its resource usage is
limited just by the max number of control sets (currently 32).  This
limit, however, is quite loose: each allocation of control set may
have 1028 elements, and each element may have up to 512 bytes (ILP32) or
1024 bytes (LP64) of value data. Moreover, each control set may contain
the enum strings and TLV data, which can be up to 64kB and 128kB,
respectively.  Totally, the whole memory consumption may go over 38MB --
it's quite large, and we'd rather like to reduce the size.

OTOH, there have been other requests even to increase the max number
of user elements; e.g. ALSA firewire stack require the more user
controls, hence we want to raise the bar, too.

For satisfying both requirements, this patch changes the management of
user controls: instead of setting the upper limit of the number of
user controls, we check the actual memory allocation size and set the
upper limit of the total allocation in bytes.  As long as the memory
consumption stays below the limit, more user controls are allowed than
the current limit 32. At the same time, we set the lower limit (8MB)
as default than the current theoretical limit, in order to lower the
risk of DoS.

As a compromise for lowering the default limit, now the actual memory
limit is defined as a module option, 'max_user_ctl_alloc_size', so that
user can increase/decrease the limit if really needed, too.

Link: https://lore.kernel.org/r/s5htur3zl5e.wl-tiwai@suse.de
Co-developed-by: Takashi Iwai 
Reviewed-by: Takashi Sakamoto 
Tested-by: Takashi Sakamoto 
Signed-off-by: Takashi Sakamoto 
Link: https://lore.kernel.org/r/20210408103149.40357-1-o-takashi@sakamocchi.jp
Signed-off-by: Takashi Iwai

ALSA: jack: implement software jack injection via debugfs

2021-02-02T09:37:07+00:00

This change adds audio jack injection feature through debugfs, with
this feature, we could validate alsa userspace changes by injecting
plugin or plugout events to the non-phantom audio jacks.

With this change, the sound core will build the folders
$debugfs_mount_dir/sound/cardN if SND_DEBUG and DEBUG_FS are enabled.
And if users also enable the SND_JACK_INJECTION_DEBUG, the jack
injection nodes will be built in the folder cardN like below:

$tree $debugfs_mount_dir/sound
$debugfs_mount_dir/sound
├── card0
│   ├── HDMI_DP_pcm_10_Jack
│   │   ├── jackin_inject
│   │   ├── kctl_id
│   │   ├── mask_bits
│   │   ├── status
│   │   ├── sw_inject_enable
│   │   └── type
...
│   └── HDMI_DP_pcm_9_Jack
│       ├── jackin_inject
│       ├── kctl_id
│       ├── mask_bits
│       ├── status
│       ├── sw_inject_enable
│       └── type
└── card1
    ├── HDMI_DP_pcm_5_Jack
    │   ├── jackin_inject
    │   ├── kctl_id
    │   ├── mask_bits
    │   ├── status
    │   ├── sw_inject_enable
    │   └── type
    ...
    ├── Headphone_Jack
    │   ├── jackin_inject
    │   ├── kctl_id
    │   ├── mask_bits
    │   ├── status
    │   ├── sw_inject_enable
    │   └── type
    └── Headset_Mic_Jack
        ├── jackin_inject
        ├── kctl_id
        ├── mask_bits
        ├── status
        ├── sw_inject_enable
        └── type

The nodes kctl_id, mask_bits, status and type are read-only, users
could check jack or jack_kctl's information through them.

The nodes sw_inject_enable and jackin_inject are directly used for
injection. The sw_inject_enable is read-write, users could check if
software injection is enabled or not on this jack, and users could
echo 1 or 0 to enable or disable software injection on this jack. Once
the injection is enabled, the jack will not change by hardware events
anymore, once the injection is disabled, the jack will restore the
last reported hardware events to the jack. The jackin_inject is
write-only, if the injection is enabled, users could echo 1 or 0 to
this node to inject plugin or plugout events to this jack.

For the detailed usage information on these nodes, please refer to
Documentation/sound/designs/jack-injection.rst.

Reviewed-by: Takashi Iwai 
Reviewed-by: Jaroslav Kysela 
Reviewed-by: Kai Vehmanen 
Signed-off-by: Hui Wang 
Link: https://lore.kernel.org/r/20210127085639.74954-2-hui.wang@canonical.com
Signed-off-by: Takashi Iwai

ALSA: fix kernel-doc markups

2020-10-26T14:26:31+00:00

Kernel-doc markups should use this format:
        identifier - description

There is a common comment marked, instead, with kernel-doc
notation.

Some identifiers have different names between their prototypes
and the kernel-doc markup.

Signed-off-by: Mauro Carvalho Chehab 
Acked-by: Mark Brown 
Link: https://lore.kernel.org/r/535182d6f55d7a7de293dda9676df68f5f60afc6.1603469755.git.mchehab+huawei@kernel.org
Signed-off-by: Takashi Iwai

ALSA: core: Add snd_device_get_state() helper

2020-03-23T17:09:19+00:00

A new small helper to get the current state of the device registration
for the given object.  It'll be used for USB-audio driver to check the
delayed device registrations.

Link: https://lore.kernel.org/r/20200323170643.19181-1-tiwai@suse.de
Signed-off-by: Takashi Iwai