[PATCH 1/2] control: Improve general control interface documentation.
Signed-off-by: Tanjeff-N. Moos tanjeff@cccmz.de --- src/control/control.c | 72 +++++++++++++++++++++++++++++++++++++------ 1 file changed, 63 insertions(+), 9 deletions(-)
diff --git a/src/control/control.c b/src/control/control.c index 1bcf1ab2..497a5399 100644 --- a/src/control/control.c +++ b/src/control/control.c @@ -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
Signed-off-by: Tanjeff-N. Moos tanjeff@cccmz.de --- include/control.h | 61 +++++- src/control/control.c | 454 ++++++++++++++++++++++++++++-------------- 2 files changed, 357 insertions(+), 158 deletions(-)
diff --git a/include/control.h b/include/control.h index 9deec6f3..8766f440 100644 --- a/include/control.h +++ b/include/control.h @@ -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); diff --git a/src/control/control.c b/src/control/control.c index 497a5399..08058c06 100644 --- a/src/control/control.c +++ b/src/control/control.c @@ -38,32 +38,39 @@ also an interface for notifying about control and structure changes. In ALSA control feature, each sound card can have control elements. The elements are managed according to below model.
- - element set + - Element set + - A set of elements with the same attribute (i.e. name, get/put operations). Some element sets can be added to a sound card by drivers in kernel and userspace applications. - - element + + - Element + - 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 + SNDRV_CTL_ELEM_TYPE_INTEGER or SNDRV_CTL_ELEM_TYPE_BOOLEAN) and - depending + on the type - min/max values, a step size, a set of possible values (for + enums), etc. + + - Member
- - 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. + - An element usually includes one or more member(s) to have a value. For + example, a stereo volume control element has two members (for left/right), + while a mono volume has only one member. The member count can be obtained + using snd_ctl_elem_info_get_count(). Elements of type + "SNDRV_CTL_ELEM_TYPE_BYTES" or "SNDRV_CTL_ELEM_TYPE_IEC958" have no members + at all (and thus no member count), they have just a single value. The + members share the same properties (e.g. both volume control members have + the same min/max values). The value of each member can be changed by both + of userspace applications and drivers in kernel.
-\section identifying_elements Identifying the Elements +\section identifying_elements Identifying 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 @@ -95,10 +102,10 @@ 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). +To access the members (i.e. 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 @@ -931,10 +938,19 @@ int snd_ctl_elem_remove(snd_ctl_t *ctl, snd_ctl_elem_id_t *id) }
/** - * \brief Get CTL element value - * \param ctl CTL handle - * \param data Data of an element. - * \return 0 on success otherwise a negative error code + * \brief Get CTL element value. + * + * Read information from sound card. You must set the ID of the + * element before calling this function. + * + * See snd_ctl_elem_value_t for details. + * + * \param ctl CTL handle. + * \param data The element value. The ID must be set before calling + * the function, and the actual value will be returned + * here. + * + * \return 0 on success otherwise a negative error code. */ int snd_ctl_elem_read(snd_ctl_t *ctl, snd_ctl_elem_value_t *data) { @@ -943,9 +959,16 @@ int snd_ctl_elem_read(snd_ctl_t *ctl, snd_ctl_elem_value_t *data) }
/** - * \brief Set CTL element value - * \param ctl CTL handle - * \param data Data of an element. + * \brief Set CTL element value. + * + * Write new value(s) to the sound card. You must set the ID and the + * value of the element before calling this function. + * + * See snd_ctl_elem_value_t for details. + * + * \param ctl CTL handle. + * \param data The new value. + * * \retval 0 on success * \retval >0 on success when value was changed * \retval <0 a negative error code @@ -2877,9 +2900,16 @@ size_t snd_ctl_elem_value_sizeof() }
/** - * \brief Allocate an invalid #snd_ctl_elem_value_t using standard malloc(3). - * \param ptr Returned pointer for data of an element. - * \return 0 on success otherwise negative error code. + * \brief Allocate an invalid #snd_ctl_elem_value_t on the heap. + * + * Allocate space for a value object on the head. The allocated memory + * must be freed using snd_ctl_elem_value_free(). + * + * 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 be returned here. + * \return 0 on success, otherwise a negative error code. */ int snd_ctl_elem_value_malloc(snd_ctl_elem_value_t **ptr) { @@ -2891,8 +2921,10 @@ int snd_ctl_elem_value_malloc(snd_ctl_elem_value_t **ptr) }
/** - * \brief Frees a previously allocated data of an element. - * \param obj Data of an element. + * \brief Free an #snd_ctl_elem_value_t previously allocated using + * snd_ctl_elem_value_malloc(). + * + * \param obj Pointer to the snd_ctl_elem_value_t. */ void snd_ctl_elem_value_free(snd_ctl_elem_value_t *obj) { @@ -2901,6 +2933,9 @@ void snd_ctl_elem_value_free(snd_ctl_elem_value_t *obj)
/** * \brief Clear given data of an element. + * + * See snd_ctl_elem_value_t for details. + * * \param obj Data of an element. */ void snd_ctl_elem_value_clear(snd_ctl_elem_value_t *obj) @@ -2909,7 +2944,7 @@ void snd_ctl_elem_value_clear(snd_ctl_elem_value_t *obj) }
/** - * \brief Copy two data of elements. + * \brief Bitwise copy of a snd_ctl_elem_value_t value. * \param dst Pointer to destination. * \param src Pointer to source. */ @@ -2921,9 +2956,10 @@ void snd_ctl_elem_value_copy(snd_ctl_elem_value_t *dst, }
/** - * \brief Compare one data of an element to the other. - * \param left Pointer to first data. - * \param right Pointer to second data. + * \brief Compare two snd_ctl_elem_value_t values, bytewise. + * + * \param left First value. + * \param right Second value. * \return 0 on match, less than or greater than otherwise, see memcmp(3). */ int snd_ctl_elem_value_compare(snd_ctl_elem_value_t *left, @@ -2934,9 +2970,13 @@ int snd_ctl_elem_value_compare(snd_ctl_elem_value_t *left, }
/** - * \brief Get element identifier from given data of an element. - * \param obj Data of an element. - * \param ptr Pointer for element identifier. + * \brief Get the element identifier from the given element value. + * + * See snd_ctl_elem_value_t for more details. + * + * \param obj The element value. + * \param ptr Pointer to an identifier object. The identifier is + * stored there. */ void snd_ctl_elem_value_get_id(const snd_ctl_elem_value_t *obj, snd_ctl_elem_id_t *ptr) { @@ -2945,9 +2985,12 @@ void snd_ctl_elem_value_get_id(const snd_ctl_elem_value_t *obj, snd_ctl_elem_id_ }
/** - * \brief Get element numeric identifier from given data of an element. - * \param obj Data of an element. - * \return Element numeric identifier. + * \brief Get the identifiers 'numid' part from the given element value. + * + * See snd_ctl_elem_value_t for more details. + * + * \param obj The element value. + * \return The numid. */ unsigned int snd_ctl_elem_value_get_numid(const snd_ctl_elem_value_t *obj) { @@ -2956,10 +2999,12 @@ unsigned int snd_ctl_elem_value_get_numid(const snd_ctl_elem_value_t *obj) }
/** - * \brief Get interface part of element identifier from given data of an - * element. - * \param obj Data of an element. - * \return Interface part of element identifier. + * \brief Get the identifiers 'interface' part from the given element value. + * + * See snd_ctl_elem_value_t for more details. + * + * \param obj The element value. + * \return The interface part of element identifier. */ snd_ctl_elem_iface_t snd_ctl_elem_value_get_interface(const snd_ctl_elem_value_t *obj) { @@ -2968,9 +3013,12 @@ snd_ctl_elem_iface_t snd_ctl_elem_value_get_interface(const snd_ctl_elem_value_t }
/** - * \brief Get device part of element identifier from given data of an element. - * \param obj Data of an element. - * \return Device part of element identifier. + * \brief Get the identifiers 'device' part from the given element value. + * + * See snd_ctl_elem_value_t for more details. + * + * \param obj The element value. + * \return The device part of element identifier. */ unsigned int snd_ctl_elem_value_get_device(const snd_ctl_elem_value_t *obj) { @@ -2979,10 +3027,12 @@ unsigned int snd_ctl_elem_value_get_device(const snd_ctl_elem_value_t *obj) }
/** - * \brief Get subdevice part of element identifier from given data of an - * element. - * \param obj Data of an element. - * \return Subdevice part of element identifier. + * \brief Get the identifiers 'subdevice' part from the given element value. + * + * See snd_ctl_elem_value_t for more details. + * + * \param obj The element value. + * \return The subdevice part of element identifier. */ unsigned int snd_ctl_elem_value_get_subdevice(const snd_ctl_elem_value_t *obj) { @@ -2991,9 +3041,12 @@ unsigned int snd_ctl_elem_value_get_subdevice(const snd_ctl_elem_value_t *obj) }
/** - * \brief Get name part of element identifier from given data of an element. - * \param obj Data of an element. - * \return Name part of element identifier. + * \brief Get the identifiers 'name' part from the given element value. + * + * See snd_ctl_elem_value_t for more details. + * + * \param obj The element value. + * \return The "name" part of element identifier. */ const char *snd_ctl_elem_value_get_name(const snd_ctl_elem_value_t *obj) { @@ -3002,9 +3055,12 @@ const char *snd_ctl_elem_value_get_name(const snd_ctl_elem_value_t *obj) }
/** - * \brief Get index part of element identifier from given data of an element. - * \param obj Data of an element. - * \return Index part of element identifier. + * \brief Get the identifiers 'index' part from the given element value. + * + * See snd_ctl_elem_value_t for more details. + * + * \param obj The element value. + * \return The index part of element identifier. */ unsigned int snd_ctl_elem_value_get_index(const snd_ctl_elem_value_t *obj) { @@ -3012,10 +3068,14 @@ unsigned int snd_ctl_elem_value_get_index(const snd_ctl_elem_value_t *obj) return obj->id.index; }
+ /** - * \brief Set element identifier to given data of an element. - * \param obj Data of an element. - * \param ptr Pointer to an element identifier. + * \brief Set the element identifier within the given element value. + * + * See snd_ctl_elem_value_t for more details. + * + * \param obj The element value. + * \param ptr The new identifier. */ void snd_ctl_elem_value_set_id(snd_ctl_elem_value_t *obj, const snd_ctl_elem_id_t *ptr) { @@ -3024,9 +3084,12 @@ void snd_ctl_elem_value_set_id(snd_ctl_elem_value_t *obj, const snd_ctl_elem_id_ }
/** - * \brief Set numeric identifier to given data of an element. - * \param obj Data of an element. - * \param val Value for numeric identifier. + * \brief Set the identifiers 'numid' part within the given element value. + * + * See snd_ctl_elem_value_t for more details. + * + * \param obj The element value. + * \param val The new numid. */ void snd_ctl_elem_value_set_numid(snd_ctl_elem_value_t *obj, unsigned int val) { @@ -3035,9 +3098,12 @@ void snd_ctl_elem_value_set_numid(snd_ctl_elem_value_t *obj, unsigned int val) }
/** - * \brief Set interface part of element identifier to given data of an element. - * \param obj Data of an element. - * \param val Value for interface part of element identifier. + * \brief Set the identifiers 'interface' part within the given element value. + * + * See snd_ctl_elem_value_t for more details. + * + * \param obj The element value. + * \param val The new interface. */ void snd_ctl_elem_value_set_interface(snd_ctl_elem_value_t *obj, snd_ctl_elem_iface_t val) { @@ -3046,9 +3112,12 @@ void snd_ctl_elem_value_set_interface(snd_ctl_elem_value_t *obj, snd_ctl_elem_if }
/** - * \brief Set device part of element identifier to given data of an element. - * \param obj Data of an element. - * \param val Value for device part of element identifier. + * \brief Set the identifiers 'device' part within the given element value. + * + * See snd_ctl_elem_value_t for more details. + * + * \param obj The element value. + * \param val The new device. */ void snd_ctl_elem_value_set_device(snd_ctl_elem_value_t *obj, unsigned int val) { @@ -3057,9 +3126,12 @@ void snd_ctl_elem_value_set_device(snd_ctl_elem_value_t *obj, unsigned int val) }
/** - * \brief Set subdevice part of element identifier to given data of an element. - * \param obj Data of an element. - * \param val Value for subdevice part of element identifier. + * \brief Set the identifiers 'subdevice' part within the given element value. + * + * See snd_ctl_elem_value_t for more details. + * + * \param obj The element value. + * \param val The new subdevice. */ void snd_ctl_elem_value_set_subdevice(snd_ctl_elem_value_t *obj, unsigned int val) { @@ -3068,9 +3140,12 @@ void snd_ctl_elem_value_set_subdevice(snd_ctl_elem_value_t *obj, unsigned int va }
/** - * \brief Set name part of element identifier to given data of an element. - * \param obj Data of an element. - * \param val Value for name part of element identifier, + * \brief Set the identifiers 'name' part within the given element value. + * + * See snd_ctl_elem_value_t for more details. + * + * \param obj The element value. + * \param val The new name. */ void snd_ctl_elem_value_set_name(snd_ctl_elem_value_t *obj, const char *val) { @@ -3079,9 +3154,12 @@ void snd_ctl_elem_value_set_name(snd_ctl_elem_value_t *obj, const char *val) }
/** - * \brief Set index part of element identifier to given data of an element. - * \param obj Data of an element. - * \param val Value for index part of element identifier. + * \brief Set the identifiers 'index' part within the given element value. + * + * See snd_ctl_elem_value_t for more details. + * + * \param obj The element value. + * \param val The new index. */ void snd_ctl_elem_value_set_index(snd_ctl_elem_value_t *obj, unsigned int val) { @@ -3090,12 +3168,16 @@ void snd_ctl_elem_value_set_index(snd_ctl_elem_value_t *obj, unsigned int val) }
/** - * \brief Get value of a specified member from given data as an element of - * boolean type. - * \param obj Data of an element. - * \param idx Index of member in the element. - * \return Value for the member. - */ + * \brief Get an element members value. + * + * Use this function if the element is of type SNDRV_CTL_ELEM_TYPE_BOOLEAN. It + * returns the value of one member. See \ref snd_ctl_elem_value_t and \ref + * control for more details. + * + * \param obj The element value object + * \param idx The index of the member. + * \return The members value. + */ int snd_ctl_elem_value_get_boolean(const snd_ctl_elem_value_t *obj, unsigned int idx) { assert(obj); @@ -3104,12 +3186,16 @@ int snd_ctl_elem_value_get_boolean(const snd_ctl_elem_value_t *obj, unsigned int }
/** - * \brief Get value of a specified member from given data as an element of - * integer type. - * \param obj Data of an element. - * \param idx Index of member in the element. - * \return Value for the member. - */ + * \brief Get an element members value. + * + * Use this function if the element is of type SNDRV_CTL_ELEM_TYPE_INTEGER. It + * returns the value of one member. See \ref snd_ctl_elem_value_t and \ref + * control for more details. + * + * \param obj The element value object. + * \param idx The index of the member. + * \return The members value. + */ long snd_ctl_elem_value_get_integer(const snd_ctl_elem_value_t *obj, unsigned int idx) { assert(obj); @@ -3118,12 +3204,16 @@ long snd_ctl_elem_value_get_integer(const snd_ctl_elem_value_t *obj, unsigned in }
/** - * \brief Get value of a specified member from given data as an element of - * integer64 type. - * \param obj Data of an element. - * \param idx Index of member in the element. - * \return Value for the member. - */ + * \brief Get an element members value. + * + * Use this function if the element is of type SNDRV_CTL_ELEM_TYPE_INTEGER64. It + * returns the value of one member. See \ref snd_ctl_elem_value_t and \ref + * control for more details. + * + * \param obj The element value object. + * \param idx The index of the member. + * \return The members value. + */ long long snd_ctl_elem_value_get_integer64(const snd_ctl_elem_value_t *obj, unsigned int idx) { assert(obj); @@ -3132,12 +3222,16 @@ long long snd_ctl_elem_value_get_integer64(const snd_ctl_elem_value_t *obj, unsi }
/** - * \brief Get value of a specified member from given data as an element of - * enumerated type. - * \param obj Data of an element. - * \param idx Index of member in the element. - * \return Value for the member. This is an index of name set in the element. - */ + * \brief Get an element members value. + * + * Use this function if the element is of type + * SNDRV_CTL_ELEM_TYPE_ENUMERATED. It returns the index of the active item. See + * \ref snd_ctl_elem_value_t and \ref control for more details. + * + * \param obj The element value object. + * \param idx The index of the requested member. + * \return The index of the active item. + */ unsigned int snd_ctl_elem_value_get_enumerated(const snd_ctl_elem_value_t *obj, unsigned int idx) { assert(obj); @@ -3146,12 +3240,16 @@ unsigned int snd_ctl_elem_value_get_enumerated(const snd_ctl_elem_value_t *obj, }
/** - * \brief Get value of a specified member from given data as an element of - * bytes type. - * \param obj Data of an element. - * \param idx Index of member in the element. - * \return Value for the member. - */ + * \brief Get an element members value. + * + * Use this function if the element is of type SNDRV_CTL_ELEM_TYPE_BYTE. It + * returns the value of one member. See \ref snd_ctl_elem_value_t and \ref + * control for more details. + * + * \param obj The element value object. + * \param idx The index of the member. + * \return The members value. + */ unsigned char snd_ctl_elem_value_get_byte(const snd_ctl_elem_value_t *obj, unsigned int idx) { assert(obj); @@ -3160,12 +3258,16 @@ unsigned char snd_ctl_elem_value_get_byte(const snd_ctl_elem_value_t *obj, unsig }
/** - * \brief Set value of a specified member to given data as an element of - * boolean type. - * \param obj Data of an element. - * \param idx Index of member in the element. - * \param val Value for the member. - */ + * \brief Set an element members value. + * + * Use this function if the element is of type SNDRV_CTL_ELEM_TYPE_BOOLEAN. It + * sets the value of one member. See \ref snd_ctl_elem_value_t and \ref control + * for more details. + * + * \param obj The element value object. + * \param idx The index of the member. + * \param val The new value. + */ void snd_ctl_elem_value_set_boolean(snd_ctl_elem_value_t *obj, unsigned int idx, long val) { assert(obj); @@ -3174,12 +3276,16 @@ void snd_ctl_elem_value_set_boolean(snd_ctl_elem_value_t *obj, unsigned int idx, }
/** - * \brief Set value of a specified member to given data as an element of - * integer type. - * \param obj Data of an element. - * \param idx Index of member in the element. - * \param val Value for the member. - */ + * \brief Set an element members value. + * + * Use this function if the element is of type SNDRV_CTL_ELEM_TYPE_INTEGER. It + * sets the value of one member. See \ref snd_ctl_elem_value_t and \ref control + * for more details. + * + * \param obj The element value object. + * \param idx The index of the member. + * \param val The new value. + */ void snd_ctl_elem_value_set_integer(snd_ctl_elem_value_t *obj, unsigned int idx, long val) { assert(obj); @@ -3188,12 +3294,16 @@ void snd_ctl_elem_value_set_integer(snd_ctl_elem_value_t *obj, unsigned int idx, }
/** - * \brief Set value of a specified member to given data as an element of - * integer64 type. - * \param obj Data of an element. - * \param idx Index of member in the element. - * \param val Value for the member. - */ + * \brief Set an element members value. + * + * Use this function if the element is of type SNDRV_CTL_ELEM_TYPE_INTEGER64. It + * sets the value of one member. See \ref snd_ctl_elem_value_t and \ref control + * for more details. + * + * \param obj The element value object. + * \param idx The index of the member. + * \param val The new value. + */ void snd_ctl_elem_value_set_integer64(snd_ctl_elem_value_t *obj, unsigned int idx, long long val) { assert(obj); @@ -3202,12 +3312,16 @@ void snd_ctl_elem_value_set_integer64(snd_ctl_elem_value_t *obj, unsigned int id }
/** - * \brief Set value of a specified member to given data as an element of - * enumerated type. - * \param obj Data of an element. - * \param idx Index of member in the element. - * \param val Value for the member. - */ + * \brief Set an element members value. + * + * Use this function if the element is of type + * SNDRV_CTL_ELEM_TYPE_ENUMERATED. It activates the specified item. See \ref + * snd_ctl_elem_value_t and \ref control for more details. + * + * \param obj The element value object. + * \param idx The index of the requested member. + * \param val The new index of the item to be activated. + */ void snd_ctl_elem_value_set_enumerated(snd_ctl_elem_value_t *obj, unsigned int idx, unsigned int val) { assert(obj); @@ -3216,12 +3330,16 @@ void snd_ctl_elem_value_set_enumerated(snd_ctl_elem_value_t *obj, unsigned int i }
/** - * \brief Set value for a specified member to given data as an element of byte - * type. - * \param obj Data of an element. - * \param idx Index of member in the element. - * \param val Value for the member. - */ + * \brief Set an element members value. + * + * Use this function if the element is of type SNDRV_CTL_ELEM_TYPE_BYTE. It + * sets the value of one member. See \ref snd_ctl_elem_value_t and \ref control + * for more details. + * + * \param obj The element value object. + * \param idx The index of the member. + * \param val The new value. + */ void snd_ctl_elem_value_set_byte(snd_ctl_elem_value_t *obj, unsigned int idx, unsigned char val) { assert(obj); @@ -3230,10 +3348,17 @@ void snd_ctl_elem_value_set_byte(snd_ctl_elem_value_t *obj, unsigned int idx, un }
/** - * \brief Set values to given data as an element of bytes type. - * \param obj Data of an element. - * \param data Pointer for byte array. - * \param size The number of bytes included in the memory block. + * \brief Replace the data stored within the element. + * + * Use this function if the element is of type SNDRV_CTL_ELEM_TYPE_BYTES. It + * replaces the data stored in the element. Note that "bytes" elements don't + * have members. They have only one single block of data. + * + * See \ref snd_ctl_elem_value_t and \ref control for more details. + * + * \param obj The element value object. + * \param data Pointer to the new data. + * \param size The size of the new data, in bytes. */ void snd_ctl_elem_set_bytes(snd_ctl_elem_value_t *obj, void *data, size_t size) { @@ -3243,10 +3368,17 @@ void snd_ctl_elem_set_bytes(snd_ctl_elem_value_t *obj, void *data, size_t size) }
/** - * \brief Get memory block from given data as an element of bytes type. - * \param obj Data of an element. - * \return Pointer for byte array. - */ + * \brief Get the data stored within the element. + * + * Use this function if the element is of type SNDRV_CTL_ELEM_TYPE_BYTES. It + * returns the data stored in the element. Note that "bytes" elements don't have + * members. They have only one single block of data. + * + * See \ref snd_ctl_elem_value_t and \ref control for more details. + * + * \param obj The element value object. + * \return Pointer to the elements data. + */ const void * snd_ctl_elem_value_get_bytes(const snd_ctl_elem_value_t *obj) { assert(obj); @@ -3254,11 +3386,17 @@ const void * snd_ctl_elem_value_get_bytes(const snd_ctl_elem_value_t *obj) }
/** - * \brief Get value from given data to given pointer as an element of IEC958 - * type. - * \param obj Data of an element. - * \param ptr Pointer to IEC958 data. - */ + * \brief Get an elements IEC958 data. + * + * Use this function if the element is of type SNDRV_CTL_ELEM_TYPE_IEC958. Note that + * "IEC958" elements don't have members. They have only one single + * IEC958 information block. + * + * See \ref snd_ctl_elem_value_t and \ref control for more details. + * + * \param obj The element value object. + * \param ptr Pointer to an IEC958 structure. The data is stored there. + */ void snd_ctl_elem_value_get_iec958(const snd_ctl_elem_value_t *obj, snd_aes_iec958_t *ptr) { assert(obj && ptr); @@ -3266,11 +3404,17 @@ void snd_ctl_elem_value_get_iec958(const snd_ctl_elem_value_t *obj, snd_aes_iec9 }
/** - * \brief Set value from given pointer to given data as an element of IEC958 - * type. - * \param obj Data of an element. - * \param ptr Pointer to IEC958 data. - */ + * \brief Set an elements IEC958 data. + * + * Use this function if the element is of type SNDRV_CTL_ELEM_TYPE_IEC958. Note + * that "IEC958" elements don't have members. They have only one single IEC958 + * information block. + * + * See \ref snd_ctl_elem_value_t and \ref control for more details. + * + * \param obj The element value object. + * \param ptr Pointer to the new IEC958 data. + */ void snd_ctl_elem_value_set_iec958(snd_ctl_elem_value_t *obj, const snd_aes_iec958_t *ptr) { assert(obj && ptr);
On Wed, 02 Sep 2020 11:27:27 +0200, Tanjeff-N. Moos wrote:
Signed-off-by: Tanjeff-N. Moos tanjeff@cccmz.de
Thanks, applied this one, too.
Takashi
On Wed, 02 Sep 2020 11:27:26 +0200, Tanjeff-N. Moos wrote:
Signed-off-by: Tanjeff-N. Moos tanjeff@cccmz.de
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
On 03/09/2020 09:15, Takashi Iwai wrote:
On Wed, 02 Sep 2020 11:27:26 +0200, Tanjeff-N. Moos wrote:
Signed-off-by: Tanjeff-N. Moos tanjeff@cccmz.de
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
participants (3)
-
Takashi Iwai -
Tanjeff Moos -
Tanjeff-N. Moos