rawmidi: update documentation for system call information

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

diff --git a/src/rawmidi/query.c b/src/rawmidi/query.c
index e578322283e5b0d727d937db6ea7adf8241c8cd1..385dc123d10a3cfd140eb524357675df335e50d7 100644 (file)
--- a/src/rawmidi/query.c
+++ b/src/rawmidi/query.c
@@ -132,6 +132,8 @@ static unsigned int calculate_digits(unsigned int number)
  * @error: A #GError.
  *
  * Get the list of numerical ID for available rawmidi devices of sound card.
+ *
+ * Nodes under sound subsystem in sysfs are used to gather the information.
  */
 void alsarawmidi_get_device_id_list(guint card_id, guint **entries,
                                     gsize *entry_count, GError **error)
@@ -218,6 +220,8 @@ end:
  * @error: A #GError.
  *
  * Allocate sysname for rawmidi device and return it when it exists.
+ *
+ * Nodes under sound subsystem in sysfs are used to gather the information.
  */
 void alsarawmidi_get_rawmidi_sysname(guint card_id, guint device_id,
                                      char **sysname, GError **error)
@@ -263,6 +267,8 @@ void alsarawmidi_get_rawmidi_sysname(guint card_id, guint device_id,
  * @error: A #GError.
  *
  * Allocate devnode string for rawmidi device and return it when exists.
+ *
+ * Nodes under sound subsystem in sysfs are used to gather the information.
  */
 void alsarawmidi_get_rawmidi_devnode(guint card_id, guint device_id,
                                      char **devnode, GError **error)
@@ -373,6 +379,12 @@ err_sysname:
  * @entries: (array length=entry_count)(out): The list of card.
  * @entry_count: The number of entries.
  * @error: A #GError.
+ *
+ * Get the list of numerical IDs for subdevices belongs to the numerical ID of
+ * card, device, and the direction.
+ *
+ * The call of function executes open(2), close(2), and ioctl(2) system call
+ * with SNDRV_CTL_IOCTL_RAWMIDI_INFO command for ALSA control character device.
  */
 void alsarawmidi_get_subdevice_id_list(guint card, guint device,
                                        ALSARawmidiStreamDirection direction,
@@ -413,6 +425,12 @@ void alsarawmidi_get_subdevice_id_list(guint card, guint device,
  * @subdevice_id: The numerical value of subdevice in rawmidi device.
  * @substream_info: (out): The information of substream for the subdevice.
  * @error: A #GError.
+ *
+ * Get the information of substream pointed by the numerical ID of card, device,
+ * subdevice, and the direction.
+ *
+ * The call of function executes open(2), close(2), and ioctl(2) system call
+ * with SNDRV_CTL_IOCTL_RAWMIDI_INFO command for ALSA control character device.
  */
 void alsarawmidi_get_substream_info(guint card_id, guint device_id,
                                     ALSARawmidiStreamDirection direction,

diff --git a/src/rawmidi/stream-pair.c b/src/rawmidi/stream-pair.c
index 2036a0bc9109ed37fbee4fd97c066a7bb1e451b9..584b24ea340b1d4be977a7b6cd4fd6de4512e836 100644 (file)
--- a/src/rawmidi/stream-pair.c
+++ b/src/rawmidi/stream-pair.c
@@ -171,6 +171,9 @@ ALSARawmidiStreamPair *alsarawmidi_stream_pair_new()
  *
  * Open file descriptor for a pair of streams to attach input/output substreams
  * corresponding to the given subdevice.
+ *
+ * The call of function executes open(2) system call for ALSA rawmidi character
+ * device.
  */
 void alsarawmidi_stream_pair_open(ALSARawmidiStreamPair *self, guint card_id,
                                   guint device_id, guint subdevice_id,
@@ -230,6 +233,9 @@ void alsarawmidi_stream_pair_open(ALSARawmidiStreamPair *self, guint card_id,
  * @error: A #GError.
  *
  * Get information of substream attached to the stream pair.
+ *
+ * The call of function executes ioctl(2) system call with
+ * SNDRV_RAWMIDI_IOCTL_INFO command for ALSA rawmidi character device.
  */
 void alsarawmidi_stream_pair_get_substream_info(ALSARawmidiStreamPair *self,
                                 ALSARawmidiStreamDirection direction,
@@ -262,6 +268,9 @@ void alsarawmidi_stream_pair_get_substream_info(ALSARawmidiStreamPair *self,
  *
  * Set parameters of substream for given direction, which is attached to the
  * pair of streams.
+ *
+ * The call of function executes ioctl(2) system call with
+ * SNDRV_RAWMIDI_IOCTL_PARAMS command for ALSA rawmidi character device.
  */
 void alsarawmidi_stream_pair_set_substream_params(ALSARawmidiStreamPair *self,
                                 ALSARawmidiStreamDirection direction,
@@ -290,6 +299,9 @@ void alsarawmidi_stream_pair_set_substream_params(ALSARawmidiStreamPair *self,
  *
  * Retrieve status of substream for given direction, which is attached to the
  * pair of streams.
+ *
+ * The call of function executes ioctl(2) system call with
+ * SNDRV_RAWMIDI_IOCTL_STATUS command for ALSA rawmidi character device.
  */
 void alsarawmidi_stream_pair_get_substream_status(ALSARawmidiStreamPair *self,
                             ALSARawmidiStreamDirection direction,
@@ -321,6 +333,9 @@ void alsarawmidi_stream_pair_get_substream_status(ALSARawmidiStreamPair *self,
  * the pair of streams. In a case that the instance is opened without
  * O_NONBLOCK flag and the intermediate buffer has no data, call of the API
  * is blocked till any data is available.
+ *
+ * The call of function executes read(2) system for ALSA rawmidi character
+ * device.
  */
 void alsarawmidi_stream_pair_read_from_substream(ALSARawmidiStreamPair *self,
                                         guint8 *const *buf, gsize *buf_size,
@@ -352,6 +367,9 @@ void alsarawmidi_stream_pair_read_from_substream(ALSARawmidiStreamPair *self,
  * the pair of streams. In a case that the instance is opened without
  * O_NONBLOCK flag and the intermediate buffer is full, call of the API is
  * blocked till the buffer has space for the data.
+ *
+ * The call of function executes write(2) system for ALSA rawmidi character
+ * device.
  */
 void alsarawmidi_stream_pair_write_to_substream(ALSARawmidiStreamPair *self,
                                         const guint8 *buf, gsize buf_size,
@@ -380,6 +398,9 @@ void alsarawmidi_stream_pair_write_to_substream(ALSARawmidiStreamPair *self,
  * of streams. In a case that the instance is opened without O_NONBLOCK and the
  * call is for output substream and any data is in the intermediate buffer, the
  * call is blocked till no data is in the intermediate buffer.
+ *
+ * The call of function executes ioctl(2) system with
+ * SNDRV_RAWMIDI_IOCTL_DRAIN command for ALSA rawmidi character device.
  */
 void alsarawmidi_stream_pair_drain_substream(ALSARawmidiStreamPair *self,
                                         ALSARawmidiStreamDirection direction,
@@ -403,6 +424,9 @@ void alsarawmidi_stream_pair_drain_substream(ALSARawmidiStreamPair *self,
  * Drop queued data in intermediate buffer immediately for substream attached
  * to the pair of streams. In implementation of ALSA rawmidi core, the
  * direction should be for output substream.
+ *
+ * The call of function executes ioctl(2) system with
+ * SNDRV_RAWMIDI_IOCTL_DROP command for ALSA rawmidi character device.
  */
 void alsarawmidi_stream_pair_drop_substream(ALSARawmidiStreamPair *self,
                                         ALSARawmidiStreamDirection direction,
@@ -472,7 +496,9 @@ static void rawmidi_stream_pair_finalize_src(GSource *gsrc)
  * @error: A #GError.
  *
  * Allocate GSource structure to handle events from ALSA rawmidi character
- * device for input substream.
+ * device for input substream. In each iteration of GManContext, the read(2)
+ * system call is executed to dispatch control event for 'handle-message'
+ * signal, according to the result of poll(2) system call.
  */
 void alsarawmidi_stream_pair_create_source(ALSARawmidiStreamPair *self,
                                            GSource **gsrc, GError **error)