From: Takashi Sakamoto Date: Sat, 13 Jun 2020 01:20:47 +0000 (+0900) Subject: rawmidi: update documentation for system call information X-Git-Tag: v0.1.0~55 X-Git-Url: https://git.alsa-project.org/?a=commitdiff_plain;h=4e9e2fee59a8cc7a37bff9fb5cb0c6e8c18935a1;p=alsa-gobject.git rawmidi: update documentation for system call information Signed-off-by: Takashi Sakamoto --- diff --git a/src/rawmidi/query.c b/src/rawmidi/query.c index e578322..385dc12 100644 --- 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 2036a0b..584b24e 100644 --- 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)