ctl: update documentation with system call information

Signed-off-by: Takashi Sakamoto <o-takashi@sakamocchi.jp>

diff --git a/src/ctl/card.c b/src/ctl/card.c
index 353faaa426b02b1af54bc79be488abbdeae67898..5324da1467880a84f9604b18d67872d0ed6397f8 100644 (file)
--- 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 c2247b24eafa7804868c2e4952f406c882e2f77f..08694d303fc15515deb0347412e46663d93c0067 100644 (file)
--- 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 c5eb24ed30fb7441726f68f7a403d8430cbc0e3e..889d989bf2a3076d32e179e41136615eb9ab6f78 100644 (file)
--- 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)
 {