From: Takashi Sakamoto Date: Sat, 13 Jun 2020 01:20:47 +0000 (+0900) Subject: ctl: update documentation with system call information X-Git-Tag: v0.1.0~58 X-Git-Url: https://git.alsa-project.org/?a=commitdiff_plain;h=1307de8d4f8049cd2ca7137c2ddc4b2b79fefc9f;p=alsa-gobject.git ctl: update documentation with system call information Signed-off-by: Takashi Sakamoto --- diff --git a/src/ctl/card.c b/src/ctl/card.c index 353faaa..5324da1 100644 --- a/src/ctl/card.c +++ b/src/ctl/card.c @@ -132,8 +132,8 @@ static void alsactl_card_class_init(ALSACtlCardClass *klass) * * When the sound card is not available anymore due to unbinding driver or * hot unplugging, this signal is emit. The owner of this object should - * call g_object_free() as quickly as possible to release ALSA control - * character device. + * call g_object_unref() as quickly as possible to be going to release ALSA + * control character device. */ ctl_card_sigs[CTL_CARD_SIG_HANDLE_DISCONNECTION] = g_signal_new("handle-disconnection", @@ -170,6 +170,9 @@ ALSACtlCard *alsactl_card_new() * @error: A #GError. * * Open ALSA control character device for the sound card. + * + * The call of function executes open(2) system call for ALSA control character + * device. */ void alsactl_card_open(ALSACtlCard *self, guint card_id, gint open_flag, GError **error) @@ -202,6 +205,9 @@ void alsactl_card_open(ALSACtlCard *self, guint card_id, gint open_flag, * @error: A #GError. * * Get the information of sound card. + * + * The call of function executes ioctl(2) system call with + * SNDRV_CTL_IOCTL_CARD_INFO command for ALSA control character device. */ void alsactl_card_get_info(ALSACtlCard *self, ALSACtlCardInfo **card_info, GError **error) @@ -282,6 +288,9 @@ static inline void deallocate_elem_ids(struct snd_ctl_elem_list *list) * * Generate a list of ALSACtlElemId for ALSA control character device * associated to the sound card. + * + * The call of function executes several ioctl(2) system call with + * SNDRV_CTL_IOCTL_ELEM_LIST command for ALSA control character device. */ void alsactl_card_get_elem_id_list(ALSACtlCard *self, GList **entries, GError **error) @@ -314,6 +323,10 @@ void alsactl_card_get_elem_id_list(ALSACtlCard *self, GList **entries, * @error: A #GError. * * Lock/Unlock indicated element not to be written by the other processes. + * + * The call of function executes ioctl(2) system call with + * SNDRV_CTL_IOCTL_ELEM_LOCK and SNDRV_CTL_IOCTL_ELEM_UNLOCK commands for + * ALSA control character device.. */ void alsactl_card_lock_elem(ALSACtlCard *self, const ALSACtlElemId *elem_id, gboolean lock, GError **error) @@ -373,6 +386,11 @@ error: * @error: A #GError. * * Get information of element corresponding to given id. + * + * The call of function executes ioctl(2) system call with + * SNDRV_CTL_IOCTL_ELEM_INFO command for ALSA control character device. For + * enumerated element, it executes the system call for several times to + * retrieve all of enumeration labels. */ void alsactl_card_get_elem_info(ALSACtlCard *self, const ALSACtlElemId *elem_id, ALSACtlElemInfo **elem_info, GError **error) @@ -435,6 +453,9 @@ void alsactl_card_get_elem_info(ALSACtlCard *self, const ALSACtlElemId *elem_id, * * Write the given array of bytes as Type/Length/Value data for element pointed * by the identifier. + * + * The call of function executes ioctl(2) system call with + * SNDRV_CTL_IOCTL_TLV_WRITE command for ALSA control character device. */ void alsactl_card_write_elem_tlv(ALSACtlCard *self, const ALSACtlElemId *elem_id, @@ -483,6 +504,9 @@ void alsactl_card_write_elem_tlv(ALSACtlCard *self, * * Read Type/Length/Value data from element pointed by the identifier and fulfil * the given array of bytes with the data. + * + * The call of function executes ioctl(2) system call with + * SNDRV_CTL_IOCTL_TLV_READ command for ALSA control character device. */ void alsactl_card_read_elem_tlv(ALSACtlCard *self, const ALSACtlElemId *elem_id, gint32 *const *container, gsize *container_count, @@ -532,6 +556,9 @@ void alsactl_card_read_elem_tlv(ALSACtlCard *self, const ALSACtlElemId *elem_id, * * Command the given array of bytes as Type/Length/Value data for element * pointed by the identifier. + * + * The call of function executes ioctl(2) system call with + * SNDRV_CTL_IOCTL_TLV_COMMAND command for ALSA control character device. */ void alsactl_card_command_elem_tlv(ALSACtlCard *self, const ALSACtlElemId *elem_id, @@ -681,6 +708,9 @@ static void add_or_replace_elems(int fd, const ALSACtlElemId *elem_id, * @error: A #GError. * * Add the user-defined elements and return the list of their identifier. + * + * The call of function executes ioctl(2) system call with + * SNDRV_CTL_IOCTL_ELEM_ADD command for ALSA control character device. */ void alsactl_card_add_elems(ALSACtlCard *self, const ALSACtlElemId *elem_id, guint elem_count, ALSACtlElemInfo *elem_info, @@ -707,6 +737,9 @@ void alsactl_card_add_elems(ALSACtlCard *self, const ALSACtlElemId *elem_id, * @error: A #GError. * * Add user-defined elements to replace the existent ones. + * + * The call of function executes ioctl(2) system call with + * SNDRV_CTL_IOCTL_ELEM_REPLACE command for ALSA control character device. */ void alsactl_card_replace_elems(ALSACtlCard *self, const ALSACtlElemId *elem_id, guint elem_count, ALSACtlElemInfo *elem_info, @@ -730,6 +763,9 @@ void alsactl_card_replace_elems(ALSACtlCard *self, const ALSACtlElemId *elem_id, * @error: A #GError. * * Remove user-defined elements pointed by the identifier. + * + * The call of function executes ioctl(2) system call with + * SNDRV_CTL_IOCTL_ELEM_REMOVE command for ALSA control character device. */ void alsactl_card_remove_elems(ALSACtlCard *self, const ALSACtlElemId *elem_id, GError **error) @@ -752,6 +788,9 @@ void alsactl_card_remove_elems(ALSACtlCard *self, const ALSACtlElemId *elem_id, * @error: A #GError. * * Write given value to element indicated by given ID. + * + * The call of function executes ioctl(2) system call with + * SNDRV_CTL_IOCTL_ELEM_WRITE command for ALSA control character device. */ void alsactl_card_write_elem_value(ALSACtlCard *self, const ALSACtlElemId *elem_id, @@ -781,6 +820,9 @@ void alsactl_card_write_elem_value(ALSACtlCard *self, * @error: A #GError. * * Read given value from element indicated by given ID. + * + * The call of function executes ioctl(2) system call with + * SNDRV_CTL_IOCTL_ELEM_READ command for ALSA control character device. */ void alsactl_card_read_elem_value(ALSACtlCard *self, const ALSACtlElemId *elem_id, @@ -895,7 +937,9 @@ static void ctl_card_finalize_src(GSource *gsrc) * @error: A #GError. * * Allocate GSource structure to handle events from ALSA control character - * device. + * device. In each iteration of GManContext, the read(2) system call is + * executed to dispatch control event for 'handle-elem-event' signal, + * according to the result of poll(2) system call. */ void alsactl_card_create_source(ALSACtlCard *self, GSource **gsrc, GError **error) diff --git a/src/ctl/card.h b/src/ctl/card.h index c2247b2..08694d3 100644 --- a/src/ctl/card.h +++ b/src/ctl/card.h @@ -66,8 +66,8 @@ struct _ALSACtlCardClass { * * When the sound card is not available anymore due to unbinding driver or * hot unplugging, this signal is emit. The owner of this object should - * call g_object_free() as quickly as possible to release ALSA control - * character device. + * call g_object_free() as quickly as possible to be going to release ALSA + * control character device. */ void (*handle_disconnection)(ALSACtlCard *self); }; diff --git a/src/ctl/query.c b/src/ctl/query.c index c5eb24e..889d989 100644 --- a/src/ctl/query.c +++ b/src/ctl/query.c @@ -112,6 +112,8 @@ static int compare_guint(const void *l, const void *r) * @error: A #GError. * * Get the list of numerical ID for available sound cards. + * + * Nodes under sound subsystem in sysfs are used to gather the information. */ void alsactl_get_card_id_list(guint **entries, gsize *entry_count, GError **error) @@ -238,6 +240,8 @@ static bool check_existence(char *sysname, GError **error) * @error: A #GError. * * Allocate sysname for the sound card and return it when it exists. + * + * Nodes under sound subsystem in sysfs are used to gather the information. */ void alsactl_get_card_sysname(guint card_id, char **sysname, GError **error) { @@ -265,6 +269,8 @@ void alsactl_get_card_sysname(guint card_id, char **sysname, GError **error) * * Allocate sysname of control device for the sound card and return it when * it exists. + * + * Nodes under sound subsystem in sysfs are used to gather the information. */ void alsactl_get_control_sysname(guint card_id, char **sysname, GError **error) { @@ -292,6 +298,8 @@ void alsactl_get_control_sysname(guint card_id, char **sysname, GError **error) * * Allocate string of devnode for control device of the sound card and return it * if exists. + * + * Nodes under sound subsystem in sysfs are used to gather the information. */ void alsactl_get_control_devnode(guint card_id, char **devnode, GError **error) {