From: Takashi Sakamoto Date: Sat, 13 Jun 2020 01:20:47 +0000 (+0900) Subject: seq: update documentation for system call information X-Git-Tag: v0.1.0~54 X-Git-Url: https://git.alsa-project.org/?a=commitdiff_plain;h=3976d8bc6c51f9c8176523fc75640c7cb286a6df;p=alsa-gobject.git seq: update documentation for system call information Signed-off-by: Takashi Sakamoto --- diff --git a/src/seq/query.c b/src/seq/query.c index 672687e..f81ae04 100644 --- a/src/seq/query.c +++ b/src/seq/query.c @@ -30,6 +30,8 @@ G_DEFINE_QUARK("alsaseq-error", alsaseq_error) * @error: A #GError. * * Allocate sysname string for ALSA sequencer and return it when exists. + * + * Nodes under sound subsystem in sysfs are used to gather the information. */ void alsaseq_get_seq_sysname(gchar **sysname, GError **error) { @@ -72,6 +74,8 @@ void alsaseq_get_seq_sysname(gchar **sysname, GError **error) * @error: A #GError. * * Allocate devnode string for ALSA Sequencer and return it when exists. + * + * Nodes under sound subsystem in sysfs are used to gather the information. */ void alsaseq_get_seq_devnode(gchar **devnode, GError **error) { @@ -114,6 +118,9 @@ void alsaseq_get_seq_devnode(gchar **devnode, GError **error) * @error: A #GError. * * Get information of ALSA Sequencer. + * + * The call of function executes open(2), close(2), and ioctl(2) system calls + * with SNDRV_SEQ_IOCTL_SYSTEM_INFO command for ALSA sequencer character device. */ void alsaseq_get_system_info(ALSASeqSystemInfo **system_info, GError **error) { @@ -159,6 +166,11 @@ void alsaseq_get_system_info(ALSASeqSystemInfo **system_info, GError **error) * @error: A #GError. * * Get the list of clients as the numerical ID. + * + * The call of function executes open(2), close(2), and ioctl(2) system calls + * with SNDRV_SEQ_IOCTL_CLIENT_ID, SNDRV_SEQ_IOCTL_SYSTEM_INFO, and + * SNDRV_SEQ_IOCTL_QUERY_NEXT_CLIENT command for ALSA sequencer character + * device. */ void alsaseq_get_client_id_list(guint **entries, gsize *entry_count, GError **error) @@ -242,6 +254,10 @@ void alsaseq_get_client_id_list(guint **entries, gsize *entry_count, * @error: A #GError. * * Get the information of client according to the numerical ID. + * + * The call of function executes open(2), close(2), and ioctl(2) system calls + * with SNDRV_SEQ_IOCTL_GET_CLIENT_INFO command for ALSA sequencer character + * device. */ void alsaseq_get_client_info(guint client_id, ALSASeqClientInfo **client_info, GError **error) @@ -288,6 +304,10 @@ void alsaseq_get_client_info(guint client_id, ALSASeqClientInfo **client_info, * @error: A #GError. * * Get the list of numerical IDs for port added by the client. + * + * The call of function executes open(2), close(2), and ioctl(2) system calls + * with SNDRV_SEQ_IOCTL_GET_CLIENT_INFO and SNDRV_SEQ_IOCTL_QUERY_NEXT_PORT + * commands for ALSA sequencer character device. */ void alsaseq_get_port_id_list(guint client_id, guint **entries, gsize *entry_count, GError **error) @@ -360,6 +380,10 @@ void alsaseq_get_port_id_list(guint client_id, guint **entries, * @error: A #GError. * * Get the information of port in client. + * + * The call of function executes open(2), close(2), and ioctl(2) system calls + * with SNDRV_SEQ_IOCTL_GET_PORT_INFO command for ALSA sequencer character + * device. */ void alsaseq_get_port_info(guint client_id, guint port_id, ALSASeqPortInfo **port_info, GError **error) @@ -404,6 +428,10 @@ void alsaseq_get_port_info(guint client_id, guint port_id, * @error: A #GError. * * Get statistical information of memory pool for the given client. + * + * The call of function executes open(2), close(2), and ioctl(2) system calls + * with SNDRV_SEQ_IOCTL_GET_CLIENT_POOL command for ALSA sequencer character + * device. */ void alsaseq_get_client_pool(gint client_id, ALSASeqClientPool **client_pool, GError **error) @@ -460,6 +488,9 @@ static void fill_data_with_result(struct snd_seq_port_subscribe *data, * @error: A #GError. * * Get the list of subscription for given address and query type. + * + * The call of function executes open(2), close(2), and ioctl(2) system calls + * with SNDRV_SEQ_IOCTL_QUERY_SUBS command for ALSA sequencer character device. */ void alsaseq_get_subscription_list(const ALSASeqAddr *addr, ALSASeqQuerySubscribeType query_type, @@ -531,6 +562,10 @@ void alsaseq_get_subscription_list(const ALSASeqAddr *addr, * @error: A #GError. * * Get the list of queue in ALSA Sequencer. + * + * The call of function executes open(2), close(2), and ioctl(2) system calls + * with SNDRV_SEQ_IOCTL_SYSTEM_INFO and SNDRV_SEQ_IOCTL_GET_QUEUE_INFO commands + * for ALSA sequencer character device. */ void alsaseq_get_queue_id_list(guint **entries, gsize *entry_count, GError **error) @@ -606,6 +641,10 @@ void alsaseq_get_queue_id_list(guint **entries, gsize *entry_count, * @error: A #GError. * * Get the information of queue, according to the numerical ID. + * + * The call of function executes open(2), close(2), and ioctl(2) system calls + * with SNDRV_SEQ_IOCTL_GET_QUEUE_INFO command for ALSA sequencer character + * device. */ void alsaseq_get_queue_info_by_id(guint queue_id, ALSASeqQueueInfo **queue_info, GError **error) @@ -646,6 +685,10 @@ void alsaseq_get_queue_info_by_id(guint queue_id, ALSASeqQueueInfo **queue_info, * @error: A #GError. * * Get the information of queue, according to the name string. + * + * The call of function executes open(2), close(2), and ioctl(2) system calls + * with SNDRV_SEQ_IOCTL_GET_NAMED_QUEUE command for ALSA sequencer character + * device. */ void alsaseq_get_queue_info_by_name(const gchar *name, ALSASeqQueueInfo **queue_info, @@ -688,6 +731,10 @@ void alsaseq_get_queue_info_by_name(const gchar *name, * @error: A #GError. * * Get current status of queue. + * + * The call of function executes open(2), close(2), and ioctl(2) system calls + * with SNDRV_SEQ_IOCTL_GET_QUEUE_STATUS command for ALSA sequencer character + * device. */ void alsaseq_get_queue_status(guint queue_id, ALSASeqQueueStatus **queue_status, GError **error) diff --git a/src/seq/user-client.c b/src/seq/user-client.c index 636f75a..dd3f877 100644 --- a/src/seq/user-client.c +++ b/src/seq/user-client.c @@ -145,6 +145,10 @@ ALSASeqUserClient *alsaseq_user_client_new() * @error: A #GError. * * Open ALSA sequencer character device. + * + * The call of function executes open(2) system call, then executes ioctl(2) + * system call with SNDRV_SEQ_IOCTL_CLIENT_ID command for ALSA sequencer + * character device. */ void alsaseq_user_client_open(ALSASeqUserClient *self, gint open_flag, GError **error) @@ -181,6 +185,9 @@ void alsaseq_user_client_open(ALSASeqUserClient *self, gint open_flag, * @error: A #GError. * * Get client information. + * + * The call of function executes ioctl(2) system call with + * SNDRV_SEQ_IOCTL_SET_CLIENT_INFO command for ALSA sequencer character device. */ void alsaseq_user_client_set_info(ALSASeqUserClient *self, ALSASeqClientInfo *client_info, @@ -207,6 +214,9 @@ void alsaseq_user_client_set_info(ALSASeqUserClient *self, * @error: A #GError. * * Set client information. + * + * The call of function executes ioctl(2) system call with + * SNDRV_SEQ_IOCTL_GET_CLIENT_INFO command for ALSA sequencer character device. */ void alsaseq_user_client_get_info(ALSASeqUserClient *self, ALSASeqClientInfo *const *client_info, @@ -234,6 +244,9 @@ void alsaseq_user_client_get_info(ALSASeqUserClient *self, * @error: A #GError. * * Create a port into the client. + * + * The call of function executes ioctl(2) system call with + * SNDRV_SEQ_IOCTL_CREATE_PORT command for ALSA sequencer character device. */ void alsaseq_user_client_create_port(ALSASeqUserClient *self, ALSASeqPortInfo *port_info, @@ -264,6 +277,10 @@ void alsaseq_user_client_create_port(ALSASeqUserClient *self, * @port_id: The numerical ID of port. * @error: A #GError. * + * Update port information. + * + * The call of function executes ioctl(2) system call with + * SNDRV_SEQ_IOCTL_SET_PORT_INFO command for ALSA sequencer character device. */ void alsaseq_user_client_update_port(ALSASeqUserClient *self, ALSASeqPortInfo *port_info, @@ -292,6 +309,9 @@ void alsaseq_user_client_update_port(ALSASeqUserClient *self, * @error: A #GError. * * Delete a port from the client. + * + * The call of function executes ioctl(2) system call with + * SNDRV_SEQ_IOCTL_DELETE_PORT command for ALSA sequencer character device. */ void alsaseq_user_client_delete_port(ALSASeqUserClient *self, guint8 port_id, GError **error) @@ -315,6 +335,9 @@ void alsaseq_user_client_delete_port(ALSASeqUserClient *self, * @error: A #GError. * * Configure memory pool in the client. + * + * The call of function executes ioctl(2) system call with + * SNDRV_SEQ_IOCTL_SET_CLIENT_POOL command for ALSA sequencer character device. */ void alsaseq_user_client_set_pool(ALSASeqUserClient *self, ALSASeqClientPool *client_pool, @@ -340,6 +363,9 @@ void alsaseq_user_client_set_pool(ALSASeqUserClient *self, * @error: A #GError. * * Get information of memory pool in the client. + * + * The call of function executes ioctl(2) system call with + * SNDRV_SEQ_IOCTL_GET_CLIENT_POOL command for ALSA sequencer character device. */ void alsaseq_user_client_get_pool(ALSASeqUserClient *self, ALSASeqClientPool *const *client_pool, @@ -367,6 +393,9 @@ void alsaseq_user_client_get_pool(ALSASeqUserClient *self, * @error: A #GError. * * Deliver the event immediately, or schedule it into memory pool of the client. + * + * The call of function executes write(2) system call for ALSA sequencer + * character device. */ void alsaseq_user_client_schedule_event(ALSASeqUserClient *self, ALSASeqEventCntr *ev_cntr, @@ -462,6 +491,9 @@ static void seq_user_client_finalize_src(GSource *gsrc) * @error: A #GError. * * Allocate GSource structure to handle events from ALSA seq character device. + * In each iteration of GMainContext, the read(2) system call is exected to + * dispatch sequencer event for 'handle-event' signal, according to the result + * of poll(2) system call. */ void alsaseq_user_client_create_source(ALSASeqUserClient *self, GSource **gsrc, GError **error) @@ -513,6 +545,10 @@ void alsaseq_user_client_create_source(ALSASeqUserClient *self, * @error: A #GError. * * Operate subscription between two ports pointed by the data. + * + * The call of function executes ioctl(2) system call with + * SNDRV_SEQ_IOCTL_SUBSCRIBE_PORT and SNDRV_SEQ_IOCTL_UNSUBSCRIBE_PORT commands + * for ALSA sequencer character device. */ void alsaseq_user_client_operate_subscription(ALSASeqUserClient *self, ALSASeqSubscribeData *subs_data, @@ -546,6 +582,9 @@ void alsaseq_user_client_operate_subscription(ALSASeqUserClient *self, * * Create a new queue owned by the client. The content of information is updated * if success. + * + * The call of function executes ioctl(2) system call with + * SNDRV_SEQ_IOCTL_CREATE_QUEUE command for ALSA sequencer character device. */ void alsaseq_user_client_create_queue(ALSASeqUserClient *self, ALSASeqQueueInfo *queue_info, GError **error) @@ -570,6 +609,9 @@ void alsaseq_user_client_create_queue(ALSASeqUserClient *self, * @error: A #GError. * * Delete the queue owned by the client. + * + * The call of function executes ioctl(2) system call with + * SNDRV_SEQ_IOCTL_DELETE_QUEUE command for ALSA sequencer character device. */ void alsaseq_user_client_delete_queue(ALSASeqUserClient *self, guint queue_id, GError **error) @@ -593,6 +635,9 @@ void alsaseq_user_client_delete_queue(ALSASeqUserClient *self, * @error: A #GError. * * Update owned queue according to the information. + * + * The call of function executes ioctl(2) system call with + * SNDRV_SEQ_IOCTL_SET_QUEUE_INFO command for ALSA sequencer character device. */ void alsaseq_user_client_update_queue(ALSASeqUserClient *self, ALSASeqQueueInfo *queue_info, @@ -620,6 +665,9 @@ void alsaseq_user_client_update_queue(ALSASeqUserClient *self, * @error: A #GError. * * Get usage of the queue by the client. + * + * The call of function executes ioctl(2) system call with + * SNDRV_SEQ_IOCTL_GET_QUEUE_CLIENT command for ALSA sequencer character device. */ void alsaseq_user_client_get_queue_usage(ALSASeqUserClient *self, guint queue_id, gboolean *use, @@ -649,6 +697,9 @@ void alsaseq_user_client_get_queue_usage(ALSASeqUserClient *self, * @error: A #GError. * * Start the queue to use or not. + * + * The call of function executes ioctl(2) system call with + * SNDRV_SEQ_IOCTL_SET_QUEUE_CLIENT command for ALSA sequencer character device. */ void alsaseq_user_client_set_queue_usage(ALSASeqUserClient *self, guint queue_id, gboolean use, @@ -676,8 +727,10 @@ void alsaseq_user_client_set_queue_usage(ALSASeqUserClient *self, * @queue_tempo: The data of tempo for queue. * @error: A #GError. * - * * Set the data of tempo to the queue. + * + * The call of function executes ioctl(2) system call with + * SNDRV_SEQ_IOCTL_SET_QUEUE_TEMPO command for ALSA sequencer character device. */ void alsaseq_user_client_set_queue_tempo(ALSASeqUserClient *self, guint queue_id, ALSASeqQueueTempo *queue_tempo, @@ -705,6 +758,9 @@ void alsaseq_user_client_set_queue_tempo(ALSASeqUserClient *self, * @error: A #GError. * * Get the data of tempo for the queue. + * + * The call of function executes ioctl(2) system call with + * SNDRV_SEQ_IOCTL_GET_QUEUE_TEMPO command for ALSA sequencer character device. */ void alsaseq_user_client_get_queue_tempo(ALSASeqUserClient *self, guint queue_id, ALSASeqQueueTempo **queue_tempo, @@ -736,6 +792,9 @@ void alsaseq_user_client_get_queue_tempo(ALSASeqUserClient *self, * @error: A #GError. * * Set the data of timer for the queue. + * + * The call of function executes ioctl(2) system call with + * SNDRV_SEQ_IOCTL_SET_QUEUE_TIMER command for ALSA sequencer character device. */ void alsaseq_user_client_set_queue_timer(ALSASeqUserClient *self, guint queue_id, @@ -775,6 +834,9 @@ void alsaseq_user_client_set_queue_timer(ALSASeqUserClient *self, * @error: A #GError. * * Get the data of timer for the queue. + * + * The call of function executes ioctl(2) system call with + * SNDRV_SEQ_IOCTL_GET_QUEUE_TIMER command for ALSA sequencer character device. */ void alsaseq_user_client_get_queue_timer(ALSASeqUserClient *self, guint queue_id, @@ -818,6 +880,9 @@ void alsaseq_user_client_get_queue_timer(ALSASeqUserClient *self, * @error: A #GError. * * Remove queued events according to the filter. + * + * The call of function executes ioctl(2) system call with + * SNDRV_SEQ_IOCTL_REMOVE_EVENTS command for ALSA sequencer character device. */ void alsaseq_user_client_remove_events(ALSASeqUserClient *self, ALSASeqRemoveFilter *filter,