control: Improve general control interface documentation.
PATCH 1/2 control: Improve general control interface documentation.
--- src/control/control.c | 72 +++++++++++++++++++++++++++++++++++++------ 1 file changed, 63 insertions(+), 9 deletions(-)
src/control/control.c +63 -9
@@ -31,7 +31,7 @@/*! \page control Control interface <P>Control interface is designed to access primitive controls. There is -also interface notifying about control and structure changes. +also an interface for notifying about control and structure changes. \section control_general_overview General overview
@@ -43,20 +43,74 @@ are managed according to below model. Some element sets can be added to a sound card by drivers in kernel and userspace applications. - element - - An element can be identified by userspace applications. Each element has - own identical information. + - A control element might be a master volume control, for example, or a + read-only indicator, such as a sync status. An element has a type (e.g. + INTEGER or BOOLEAN) and - depending on the type - min/max values, a step + size, a set of possible values (for enums), etc. - member - - An element includes some members to have a value. The value of each member - can be changed by both of userspace applications and drivers in kernel. -Each element can be identified by two ways; the numerical number (numid), or the -combination of interface, device, subdevice, name, and index. + - An element includes one or more member(s) to have a value. For + example, a stereo volume control element has two members (for + left/right). The members share the same properties (e.g. both + volume controls have the same min/max values). The value of each + member can be changed by both of userspace applications and + drivers in kernel. -The type of element set is one of integer, integerr64, boolean, enumerators, + +\section identifying_elements Identifying the Elements + +Each element has the following identifying properties: + + - The numid (a numeric identifier, assigned when the sound card is + detected, constant while the sound card is kept connected) + + - The interface type (e.g. MIXER, CARD or PCM) + - The device + - The subdevice + - Its name + - Its index + +An element can be identified either by its numid or by the tuple +(interface type, device, subdevice, name, index). This tuple is always +the same (driver updates can change it, but in practice this is +rare). The numid can change on each boot. In case of an USB sound +card, the numid can also change when it is reconnected. + + +\section element_lists Element Lists + +An element list can be used to obtain a list of all elements of the +sound card. The list contains generic information (e.g. how many +elements the card has), and the identifying properties of the elements +(numid, card, name, ...). See #snd_ctl_elem_list_t to learn more about +element lists. + + +\section working_with_elements Working with Elements + +It is possible to obtain information about an element using the +snd_ctl_elem_info_*() functions. For enums, the allowed values can be +obtained, for integers, the min/max values can be obtained, and so +on. In addition, these functions can report the identifying +properties. E.g. when the element is addressed using its numid, the +functions complements the name, index, etc. + +To access the values of a control, use the snd_ctl_elem_value*() +functions. These allow to get and set the actual values or +settings. It is also possible to get and set the ID values (such as +the numid or the name). + + +\section element_sets Element Sets + +The type of element set is one of integer, integer64, boolean, enumerators, bytes and IEC958 structure. This indicates the type of value for each member in elements included in the element set. -When the value of member is changed, corresponding events are transferred to + +\section events Events + +When the value of a member is changed, corresponding events are transferred to userspace applications. The applications should subscribe any events in advance. \section tlv_blob Supplemental data for elements in an element set
Signature · 1 line
2.17.1
PATCH 2/2 control: Add documentation for snd_ctl_elem_value_*.
--- include/control.h | 61 +++++- src/control/control.c | 454 ++++++++++++++++++++++++++++-------------- 2 files changed, 357 insertions(+), 158 deletions(-)
include/control.h +58 -3
@@ -130,7 +130,53 @@ typedef struct _snd_ctl_elem_list snd_ctl_elem_list_t;/** CTL element info container */ typedef struct _snd_ctl_elem_info snd_ctl_elem_info_t ; -/** CTL element value container */ +/** CTL element value container +* +* Contains the value(s) (i.e. members) of a single element. All +* values of a given element are of the same type. +* +* \par Memory management +* +* To access a value, a snd_ctl_elem_value_t must be allocated using +* snd_ctl_elem_value_alloca() or snd_ctl_elem_value_malloc(). When +* using the latter, it must be freed again using +* snd_ctl_elem_value_free(). +* +* \par Identifier +* +* Then, the ID must be filled. It is sufficient to fill only the +* numid, if known. Otherwise, interface type, device, subdevice, +* name, index must all be given. The following functions can be used +* to fill the ID: +* +* - snd_ctl_elem_value_set_id(): Set the ID. Requires an +* snd_ctl_elem_id_t object. +* - snd_ctl_elem_value_set_numid(): Set the numid. +* - Or use all of the following: +* +* - snd_ctl_elem_value_set_interface() +* - snd_ctl_elem_value_set_device() +* - snd_ctl_elem_value_set_subdevice() +* - snd_ctl_elem_value_set_name() +* - snd_ctl_elem_value_set_index() +* +* When communicating with the driver (snd_ctl_elem_read(), +* snd_ctl_elem_write()), and the numid was given, the interface, +* device, ... are filled (even if you set the before). When the numid +* is unset (i.e. it is 0), it is filled. +* +* \par Communicating with the driver +* +* After the value container was created and filled with the ID of the +* desired element, the value(s) can be fetched from the driver (and +* thus from the hardware) or written to the driver. +* +* To fetch a value, use snd_ctl_elem_read(). Thereafter, use the +* snd_ctl_elem_value_get_*() functions to obtain the actual value. +* +* To write a new value, first use a snd_ctl_elem_value_set_*() to set +* it, then call snd_ctl_elem_write() to write it to the driver. +*/ typedef struct _snd_ctl_elem_value snd_ctl_elem_value_t ;/** CTL event container */
@@ -529,11 +575,20 @@ int snd_ctl_elem_add_iec958(snd_ctl_t *ctl, const snd_ctl_elem_id_t *id);int snd_ctl_elem_remove (snd_ctl_t *ctl,snd_ctl_elem_id_t *id);size_t snd_ctl_elem_value_sizeof (void ); +/** \hideinitializer -* \brief allocate an invalid #snd_ctl_elem_value_t using standard alloca -* \param ptr returned pointer +* \brief Allocate an invalid #snd_ctl_elem_value_t on the stack. +* +* Allocate space for a value object on the stack. The allocated +* memory need not be freed, because is on the stack. +* +* See snd_ctl_elem_value_t for details. +* +* \param ptr Pointer to a snd_ctl_elem_value_t pointer. The address +* of the allocated space will returned here. */ #define snd_ctl_elem_value_alloca (ptr) __snd_alloca(ptr, snd_ctl_elem_value) +int snd_ctl_elem_value_malloc (snd_ctl_elem_value_t **ptr);void snd_ctl_elem_value_free (snd_ctl_elem_value_t *obj);void snd_ctl_elem_value_clear (snd_ctl_elem_value_t *obj);
src/control/control.c +299 -155
690 lines not on this page · raw message
Signature · 1 line
2.17.1
Takashi Iwai
AppliedRe: [PATCH 2/2] control: Add documentation for snd_ctl_elem_value_*.
Quoted 2 lines · Tanjeff-N. Moos
Signed-off-by Tanjeff-N. Moos <[email protected]>
Thanks, applied this one, too.
Takashi
Takashi Iwai
AppliedQuoted 2 lines · Tanjeff-N. Moos
Signed-off-by Tanjeff-N. Moos <[email protected]>
Thanks, applied now. The added / modified texts are excellent, but at the next time, please give some more description in the patch itself. An empty patch description is always a sign of a bad patch.
Takashi
Hi,
you are right, I should have added some description. I'm still learning.
Thanks for applying anyway, it's a great motivation for me.
Regards, Tanjeff
Quoted 12 lines · Takashi Iwai
Quoted 2 lines · Tanjeff-N. Moos
Signed-off-by Tanjeff-N. Moos <[email protected]>Thanks, applied now. The added / modified texts are excellent, but at the next time, please give some more description in the patch itself. An empty patch description is always a sign of a bad patch.
Takashi