In documentation, there're two ways relevant to the identifier of control
element. However, the case of combination has the lack of parameters.
This commit improves documentation in this point.
Fixes: f3c24de8c0 ("ctl: add an overview for design of ALSA control interface")
Signed-off-by: Takashi Sakamoto <o-takashi@sakamocchi.jp>
Signed-off-by: Jaroslav Kysela <perex@perex.cz>
In commit b906db19ef, the snd_dlopen()
implements the automatic lookup to the ALSA_PLUGIN_DIR directory.
It is not necessary to add the absolute paths in callers now.
The plugin names are also searched in ld.so.conf paths as the fallback now,
but it should not be a big problem.
BugLink: https://github.com/alsa-project/alsa-lib/issues/34
Signed-off-by: Jaroslav Kysela <perex@perex.cz>
The dimen fields of control element has been deprecated, and it's
finally dropped in kernel 5.6 ABI definition. Remove the
corresponding accesses in alsa-lib code.
As of this patch, it's disabled via ifdef, just to be sure. The
disabled code should be removed in a later stage as a cleanup.
Signed-off-by: Takashi Iwai <tiwai@suse.de>
A series of SNDRV_CTL_TLVO_XXX macro was introduced for position offset
of TLV data. This commit applies a code optimization.
Signed-off-by: Takashi Sakamoto <o-takashi@sakamocchi.jp>
Signed-off-by: Takashi Iwai <tiwai@suse.de>
In ALSA control interface in asound.h, 'struct snd_ctl_elem_info' has
'dimen' member to deliver information for multi-dimensional array, however
there's no common way to handle the member. As a result, drivers can
force userspace applications to handle the information by inconsistent
ways.
This issue was reported by a commit 51db452df07b ('Revert "ALSA: echoaudio:
purge contradictions between dimension matrix members and total number of
members"') to Linux kernel. As a result of discussion at Linux
miniconference 2017, usage of 'dimen' member of 'struct snd_ctl_elem_info'
is going to be deprecated for future removal.
A removal of kernel interface can cause regression issues. However no ALSA
driver in kernel land except for 'echoaudio' series utilizes this feature.
Actually it's reasonable to assume that 'echomixer' program is an unique
consumer of the interface in user land and the removal rarely brings any
impact to user land.
This commit deprecates some APIs corresponding to the kernel interface. The
kernel interface is kept till Linux kernel v4.20 at least, but actual
timing of removal is not fixed yet. After that, these APIs may also be
removed at a reasonable timing.
Signed-off-by: Takashi Sakamoto <o-takashi@sakamocchi.jp>
Signed-off-by: Takashi Iwai <tiwai@suse.de>
According POSIX[1] and linux manpage[2] the include is poll.h, not
sys/poll.h.
This fixes the he following compiler warning when build with musl libc:
/usr/include/sys/poll.h:1:2: warning: #warning redirecting incorrect #include <sys/poll.h> to <poll.h> [-Wcpp]
#warning redirecting incorrect #include <sys/poll.h> to <poll.h>
^~~~~~~
Signed-off-by: Natanael Copa <ncopa@alpinelinux.org>
Signed-off-by: Takashi Iwai <tiwai@suse.de>
From my misunderstanding, some explanations are wrong. This commit
corrects them.
Signed-off-by: Takashi Sakamoto <o-takashi@sakamocchi.jp>
Signed-off-by: Takashi Iwai <tiwai@suse.de>
The documentation gives no hints to users about format of TLV data.
This commit add hints to construct/parse the information.
Signed-off-by: Takashi Sakamoto <o-takashi@sakamocchi.jp>
Signed-off-by: Takashi Iwai <tiwai@suse.de>
A commit fe1b08803d ("ctl: improve API documentation for threshold level
operations") changes documentations for some TLV-related APIs with wrong
explanations.
This commit fix it with better explanations.
Fixes: fe1b08803d ("ctl: improve API documentation for threshold level operations")
Signed-off-by: Takashi Sakamoto <o-takashi@sakamocchi.jp>
Signed-off-by: Takashi Iwai <tiwai@suse.de>
Usage of assert() is not better practice of programming as shared library
APIs. They should return appropriate error code to promote applications to
handle error state.
This commit applies condition statements with return value of -EINVAL,
instead of assert(). As a backward compatibility for existent applications,
old APIs still call assert().
Signed-off-by: Takashi Sakamoto <o-takashi@sakamocchi.jp>
Signed-off-by: Takashi Iwai <tiwai@suse.de>
In this development period, some APIs have already been added. Most of
them are to add an element set, while their names are not so appropriate
against their feature. This is due to following to names of old APIs.
This commit renames them.
Signed-off-by: Takashi Sakamoto <o-takashi@sakamocchi.jp>
Signed-off-by: Takashi Iwai <tiwai@suse.de>
I forgot it when committing to the API.
Fixes: 16812b70daeb('ctl: add an API to set dimension levels to element information')
Signed-off-by: Takashi Sakamoto <o-takashi@sakamocchi.jp>
Signed-off-by: Takashi Iwai <tiwai@suse.de>
Currently, documentation of APIs to add an element set describes causes of
errors partly. But it gives an opinion to describe them thoroughly. This
is not good for users.
This commit changes the documentation so that it partly describes the
causes.
Signed-off-by: Takashi Sakamoto <o-takashi@sakamocchi.jp>
Signed-off-by: Takashi Iwai <tiwai@suse.de>
Linux 4.7 or former have no validator of dimension information. This can
causes an issue related to user-defined element set. For example, When
calculated total members in multi-dimensional matrix is larger than actual
capacity of snd_ctl_elem_value_t, processes to handle the element can
cause buffer-over-run.
For backward portability of this userspace library, this commit adds a
validator of dimension information. When userspace applications give
invalid dimension information to APIs to add element set, they receive
-EINVAL.
Signed-off-by: Takashi Sakamoto <o-takashi@sakamocchi.jp>
Signed-off-by: Takashi Iwai <tiwai@suse.de>
In a former commit, 'struct snd_ctl_elem_info' is used as a 'container' to
transfer extra fields of element information for APIs to add an element
set. The extra fields should be filled in advance of call of the APIs.
Currently, dimension level is in the extra fields and no APIs to set it.
This commit adds an API to set dimension level to the information
structure. This API is expected to be used in advance of usage of APIs
to add an element set, for nothing others. When the information structure
is extended in future, then the similar APIs shall be added for the new
feature.
Signed-off-by: Takashi Sakamoto <o-takashi@sakamocchi.jp>
Signed-off-by: Takashi Iwai <tiwai@suse.de>
In ALSA control feature, information of an element includes extra fields
to type-specific parameters; i.e. dimension. The fields can be extended in
future.
Meanwhile, current APIs to add user-defined element set can not support
such an extended fields. This may cause inconveniences in future.
This commit supports the fields, by changing APIs for element set.
Signed-off-by: Takashi Sakamoto <o-takashi@sakamocchi.jp>
Signed-off-by: Takashi Iwai <tiwai@suse.de>
Second argument of these functions has three different names in
documentation/header/code (obj/control/value). This easily causes users'
confusion.
This commit applies consistent names for the arguments.
Fixes: 90020c05f8 ('ctl: improve comments for handling element data')
Signed-off-by: Takashi Sakamoto <o-takashi@sakamocchi.jp>
Signed-off-by: Takashi Iwai <tiwai@suse.de>
Inner this library, layouts of all structures are public. At a compilation
time, each size of the structures can be calculated. It means that we can
use automatic variable instead of calling alloca(3) to program this
library because in both ways storages are kept on stack frame of process
VMA. Besides, the usage of automatic variables requires less instructions
than calls of alloca(3). Furthermore, alloca(3) is not described in any
C language standards.
This commit replaces calls of alloca(3) just for structures with automatic
variables, for control features.
Signed-off-by: Takashi Sakamoto <o-takashi@sakamocchi.jp>
Signed-off-by: Takashi Iwai <tiwai@suse.de>
In ALSA kernel/userspace interfaces, 'struct snd_ctl_elem_info' has a
'dimension' parameter. This parameter consists of an array with four
elements. Each element represents the number of members in corresponding
dimension level to construct matrix.
In current implementation, a get function, 'snd_ctl_elem_info_get_dimension()'
is hardcoded to return zero to level 4, against actual value. This commit fixes
the bug.
Signed-off-by: Takashi Sakamoto <o-takashi@sakamocchi.jp>
Signed-off-by: Takashi Iwai <tiwai@suse.de>
In alsa-lib, threshold level operations require an array of unsigned-int
members, while there's little explanation about how to fill it. To usual
developers such as me, they're quite hard to understand.
This commit adds a few comment for easy understanding about how to use
the APIs.
Signed-off-by: Takashi Sakamoto <o-takashi@sakamocchi.jp>
Signed-off-by: Takashi Iwai <tiwai@suse.de>
ALSA ctl feature includes threshold level feature. This is introduced in
2006, and there's little resources about it.
This commit adds a simple explanation about the feature.
Signed-off-by: Takashi Sakamoto <o-takashi@sakamocchi.jp>
Signed-off-by: Takashi Iwai <tiwai@suse.de>
In former commit, userspace library gets some APIs for element set. Some
existed functions can be simple wrappers of them.
This commit changes these APIs as wrapper functions. Additionally, this
commit also adds local variables for identical information of elements.
This modification is important to keep API consistency.
Some old APIs to add an element have id variables with const type
qualifier, while some new APIs to add element set changes the content of
given parameters. This comes from a change in Linux kernel 4.1.
In this commit [1], in-kernel implementation fills all fields of identical
data in userspace. As a result, when adding a new element set, userspace
applications can get an identical data for the first element in the set.
This lost the semantics of const type qualifier in userspace.
[1] http://git.kernel.org/cgit/linux/kernel/git/tiwai/sound.git/commit/sound/core?id=cab2ed7474bffafd2a68a885e03b85526194abcd
Signed-off-by: Takashi Sakamoto <o-takashi@sakamocchi.jp>
Signed-off-by: Takashi Iwai <tiwai@suse.de>
In ALSA control core, it's not allowed to an element set of IEC 958 type
to have several elements. Therefore, consecutive patchset doesn't touch an
API to add an element of IEC958 type. However, it's better to supplement
comments for the API.
This commit do it.
Signed-off-by: Takashi Sakamoto <o-takashi@sakamocchi.jp>
Signed-off-by: Takashi Iwai <tiwai@suse.de>
ALSA control core allows userspace applications to add an element set.
However, in ALSA userspace library, there's no APIs enough to utilize
the feature. The library has APIs just to add an element set with a single
element.
This commit adds functions to add an element set with several elements.
Signed-off-by: Takashi Sakamoto <o-takashi@sakamocchi.jp>
Signed-off-by: Takashi Iwai <tiwai@suse.de>
Some parts of control API documentation are described with core-developer
friendly explanations. To usual developer such as me, they're quite hard
to understand.
This commit improves such comments for a part of APIs to handle data of
each element.
Signed-off-by: Takashi Sakamoto <o-takashi@sakamocchi.jp>
Signed-off-by: Takashi Iwai <tiwai@suse.de>
This commit adds a description about the design of ALSA control interface
for developers to understand a few components of low level.
Signed-off-by: Takashi Sakamoto <o-takashi@sakamocchi.jp>
Signed-off-by: Takashi Iwai <tiwai@suse.de>
Most of open functions in alsa-lib have the call pattern:
snd_config_update();
return snd_xxx_open(x, snd_config, ...);
This means that the toplevel config gets updated, and passed to a
local open function. Although snd_config_update() itself has a
pthread mutex to be thread safe, the whole procedure above isn't
thread safe. Namely, the global snd_config tree may be deleted and
recreated at any time while the open function is being processed.
This may lead to a data corruption and crash of the program.
For avoiding the corruption, this patch introduces a refcount to
config tree object. A few new helper functions are introduced as
well:
- snd_config_update_ref() does update and take the refcount of the
toplevel tree. The obtained config tree has to be freed via
snd_config_unref() below.
- snd_config_ref() and snd_config_unref() manage the refcount of the
config object. The latter eventually deletes the object when all
references are gone.
Along with these additions, the caller of snd_config_update() and
snd_config global tree in alsa-lib are replaced with the new helpers.
Signed-off-by: Takashi Iwai <tiwai@suse.de>
In most codes for control APIs, assertions are used to check given
arguments from applications. If the arguments are not expected, the
application is forced to abort. When NDEBUG is defined in the beginning
of the codes, no checks are performed.
Although, in snd_ctl_elem_set_bytes(), assertion is used with condition
statement. There's an intention to check the arguments regardless of
NDEBUG. However, this is not the same fashion in the codes.
This commit applies the same fashion to the function, to keep consistent
usage of assertion.
Signed-off-by: Takashi Sakamoto <o-takashi@sakamocchi.jp>
Signed-off-by: Takashi Iwai <tiwai@suse.de>
In ALSA control core, there're two ways to identify elements. One is by
numid. Another is by name/index. The former way is lighter than the latter
way.
In control API, after adding elements by snd_ctl_elem_add_integer() and
snd_ctl_elem_add_integer64(), these functions initialize value of each
channel. When executing this operation, used ID information is still given
by applications. Although, in this time, the element can be identified
according to numid.
This commit uses the numid instead of name/index pair.
Signed-off-by: Takashi Sakamoto <o-takashi@sakamocchi.jp>
Signed-off-by: Takashi Iwai <tiwai@suse.de>
In UAPI of asound.h, there're 6 types of control element; boolean, integer,
enumerated, bytes, iec958 and integer64 (The none type seems to be added to
start the value at non-zero). Although, current description in alsa-lib
has a lack of integer64 type.
This commit fulfil the type.
Signed-off-by: Takashi Sakamoto <o-takashi@sakamocchi.jp>
Signed-off-by: Takashi Iwai <tiwai@suse.de>
When minus value is given as a parameter, the API returns whether
the caller has already subscribed or not.
This commit adds a comment about this so as better documentation.
Signed-off-by: Takashi Sakamoto <o-takashi@sakamocchi.jp>
Signed-off-by: Takashi Iwai <tiwai@suse.de>
Upon an interrupt, it is necessary to abort the wait loops with the EINTR
error code. Introduce snd_*_abort() functions to handle this case.
Signed-off-by: Jaroslav Kysela <perex@perex.cz>
This allows us to build in environments that don't provide stpcpy().
This makes it necessary to traverse the string twice, but should not be
noticeable in clients since this function is very unlikely to be part of
a performance-critical path.
[coding style fixed by tiwai]
Signed-off-by: Arun Raghavan <arun.raghavan@collabora.co.uk>
Signed-off-by: Takashi Iwai <tiwai@suse.de>
Handling of user control elements was implemented for all types except
BYTES and ENUMERATED. Enumerated user controls will be needed for the
device-specific mixers of upcoming FireWire drivers.
Signed-off-by: Clemens Ladisch <clemens@ladisch.de>
This patch adds new API functions, snd_ctl_open_fallback() and
snd_pcm_open_fallback(). These are just like snd_*_open_lconf() but
used to open a fallback PCM/control. The difference is that it replaces
the name string with the given original name, so that hctl and other
upper-layers will recognize it as an alias.
Signed-off-by: Takashi Iwai <tiwai@suse.de>
- changed logic to get/put blocks
- added mutex locking of the symbol list
- added reference counting (do not free used dl handles)
Signed-off-by: Jaroslav Kysela <perex@perex.cz>
Only restore the old value if it differs from the requested
value, because if it has changed restoring the old value
overrides the change. Take for example, a voice modem with
a .conf that sets preserve off-hook. Start playback (on-hook
to off-hook), start record (off-hook to off-hook), stop
playback (off-hook to restore on-hook), stop record (on-hook
to restore off-hook), Clearly you don't want to leave the
modem "on the phone" now that there isn't any playback or
recording active.
Signed-off-by: David Fries <david@fries.net>
Signed-off-by: Takashi Iwai <tiwai@suse.de>
