From f0374d7936df4f4927d3c20e2c0ed71b031617d8 Mon Sep 17 00:00:00 2001 From: Takashi Sakamoto Date: Sat, 13 Jun 2020 10:20:47 +0900 Subject: [PATCH] timer: update documentation for system call information Signed-off-by: Takashi Sakamoto --- src/timer/query.c | 24 +++++++++++++++++++++ src/timer/user-instance.c | 45 ++++++++++++++++++++++++++++++++++----- 2 files changed, 64 insertions(+), 5 deletions(-) diff --git a/src/timer/query.c b/src/timer/query.c index 4a64187..34ea729 100644 --- a/src/timer/query.c +++ b/src/timer/query.c @@ -62,6 +62,8 @@ static bool check_existence(char *sysname, GError **error) * @error: A #GError. * * Allocate sysname for ALSA Timer and return it when it exists. + * + * Nodes under sound subsystem in sysfs are used to gather the information. */ void alsatimer_get_sysname(char **sysname, GError **error) { @@ -89,6 +91,8 @@ void alsatimer_get_sysname(char **sysname, GError **error) * @error: A #GError. * * Allocate string of devnode for ALSA Timer and return it if exists. + * + * Nodes under sound subsystem in sysfs are used to gather the information. */ void alsatimer_get_devnode(char **devnode, GError **error) { @@ -128,6 +132,10 @@ void alsatimer_get_devnode(char **devnode, GError **error) * entries of ALSATimerId. * @error: A #GError. * + * Get the list of existent timer device. + * + * The call of function executes open(2), close(2), and ioctl(2) system call + * with SNDRV_TIMER_IOCTL_NEXT_DEVICE command for ALSA timer character device. */ void alsatimer_get_device_id_list(GList **entries, GError **error) { @@ -170,6 +178,11 @@ void alsatimer_get_device_id_list(GList **entries, GError **error) * @device_id: A #ALSATimerDeviceId to identify the timer device. * @device_info: (out): The information of timer device. * @error: A #GError. + * + * Get the information of timer device. + * + * The call of function executes open(2), close(2), and ioctl(2) system call + * with SNDRV_TIMER_IOCTL_GINFO command for ALSA timer character device. */ void alsatimer_get_device_info(ALSATimerDeviceId *device_id, ALSATimerDeviceInfo **device_info, @@ -209,6 +222,11 @@ void alsatimer_get_device_info(ALSATimerDeviceId *device_id, * @device_id: A #ALSATimerDeviceId to identify the timer device. * @device_status: (out): The status of timer device. * @error: A #GError. + * + * Get the status of timer device. + * + * The call of function executes open(2), close(2), and ioctl(2) system call + * with SNDRV_TIMER_IOCTL_GSTATUS command for ALSA timer character device. */ void alsatimer_get_device_status(ALSATimerDeviceId *device_id, ALSATimerDeviceStatus **device_status, @@ -250,6 +268,9 @@ void alsatimer_get_device_status(ALSATimerDeviceId *device_id, * @error: A #GError. * * Set the given parameters to the timer indicated by the identifier. + * + * The call of function executes open(2), close(2), and ioctl(2) system call + * with SNDRV_TIMER_IOCTL_GPARAMS command for ALSA timer character device. */ void alsatimer_set_device_params(ALSATimerDeviceId *device_id, const ALSATimerDeviceParams *device_params, @@ -329,6 +350,9 @@ end: * refer to it. * * 0 means CLOCK_REALTIME is used. 1 means CLOCK_MONOTONIC is used. + * + * The call of function executes open(2), read(2), close(2) system calls for + * the sysfs node corresponding to 'snd-timer' kernel module. */ void alsatimer_get_tstamp_source(int *clock_id, GError **error) { diff --git a/src/timer/user-instance.c b/src/timer/user-instance.c index 3d7db23..158d071 100644 --- a/src/timer/user-instance.c +++ b/src/timer/user-instance.c @@ -112,6 +112,9 @@ static void alsatimer_user_instance_init(ALSATimerUserInstance *self) * @error: A #GError. * * Open ALSA Timer character device to allocate queue. + * + * The call of function executes open(2) system call for ALSA timer character + * device. */ void alsatimer_user_instance_open(ALSATimerUserInstance *self, gint open_flag, GError **error) @@ -150,6 +153,9 @@ ALSATimerUserInstance *alsatimer_user_instance_new() * The call of function is successful just before the instance is not attached * yet. ALSATIMER_EVENT_DATA_TYPE_TICK is used as a default if the function is * not called for ALSATIMER_EVENT_DATA_TYPE_TSTAMP explicitly. + * + * The call of function executes ioctl(2) system call with + * SNDRV_TIMER_IOCTL_TREAD command for ALSA timer character device. */ void alsatimer_user_instance_choose_event_data_type(ALSATimerUserInstance *self, ALSATimerEventDataType event_data_type, @@ -176,6 +182,9 @@ void alsatimer_user_instance_choose_event_data_type(ALSATimerUserInstance *self, * * Attach the instance to the timer device. If the given device_id is for * absent timer device, the instance can be detached with error. + * + * The call of function executes ioctl(2) system call with + * SNDRV_TIMER_IOCTL_SELECT command for ALSA timer character device. */ void alsatimer_user_instance_attach(ALSATimerUserInstance *self, ALSATimerDeviceId *device_id, @@ -210,6 +219,9 @@ void alsatimer_user_instance_attach(ALSATimerUserInstance *self, * * Attach the instance to the timer device. If the given device_id is for * absent timer device, the instance can be detached with error. + * + * The call of function executes ioctl(2) system call with + * SNDRV_TIMER_IOCTL_SELECT command for ALSA timer character device. */ void alsatimer_user_instance_attach_as_slave(ALSATimerUserInstance *self, ALSATimerSlaveClass slave_class, @@ -236,6 +248,9 @@ void alsatimer_user_instance_attach_as_slave(ALSATimerUserInstance *self, * @error: A #GError. * * Return the information of device if attached to the instance. + * + * The call of function executes ioctl(2) system call with + * SNDRV_TIMER_IOCTL_INFO command for ALSA timer character device. */ void alsatimer_user_instance_get_info(ALSATimerUserInstance *self, ALSATimerInstanceInfo **instance_info, @@ -263,6 +278,9 @@ void alsatimer_user_instance_get_info(ALSATimerUserInstance *self, * @error: A #GError. * * Configure the instance with the parameters and return the latest parameters. + * + * The call of function executes ioctl(2) system call with + * SNDRV_TIMER_IOCTL_PARAMS command for ALSA timer character device. */ void alsatimer_user_instance_set_params(ALSATimerUserInstance *self, ALSATimerInstanceParams *const *instance_params, @@ -287,6 +305,9 @@ void alsatimer_user_instance_set_params(ALSATimerUserInstance *self, * @error: A #GError. * * Get the latest status of instance. + * + * The call of function executes ioctl(2) system call with + * SNDRV_TIMER_IOCTL_STATUS command for ALSA timer character device. */ void alsatimer_user_instance_get_status(ALSATimerUserInstance *self, ALSATimerInstanceStatus **instance_status, @@ -391,7 +412,9 @@ static void timer_user_instance_finalize_src(GSource *gsrc) * @error: A #GError. * * Allocate GSource structure to handle events from ALSA timer character - * device. + * device. In each iteration of GMainContext, the read(2) system call is + * executed to dispatch timer event for 'handle-event' signal, according to + * the result of poll(2) system call. */ void alsatimer_user_instance_create_source(ALSATimerUserInstance *self, GSource **gsrc, GError **error) @@ -438,7 +461,10 @@ void alsatimer_user_instance_create_source(ALSATimerUserInstance *self, * @self: A #ALSATimerUserInstance. * @error: A #GError. * - * Start event emission. + * Start timer event emission. + * + * The call of function executes ioctl(2) system call with + * SNDRV_TIMER_IOCTL_START command for ALSA timer character device. */ void alsatimer_user_instance_start(ALSATimerUserInstance *self, GError **error) { @@ -456,7 +482,10 @@ void alsatimer_user_instance_start(ALSATimerUserInstance *self, GError **error) * @self: A #ALSATimerUserInstance. * @error: A #GError. * - * Stop event emission. + * Stop timer event emission. + * + * The call of function executes ioctl(2) system call with + * SNDRV_TIMER_IOCTL_STOP command for ALSA timer character device. */ void alsatimer_user_instance_stop(ALSATimerUserInstance *self, GError **error) { @@ -474,7 +503,10 @@ void alsatimer_user_instance_stop(ALSATimerUserInstance *self, GError **error) * @self: A #ALSATimerUserInstance. * @error: A #GError. * - * Stop event emission. + * Pause timer event emission. + * + * The call of function executes ioctl(2) system call with + * SNDRV_TIMER_IOCTL_PAUSE command for ALSA timer character device. */ void alsatimer_user_instance_pause(ALSATimerUserInstance *self, GError **error) { @@ -492,7 +524,10 @@ void alsatimer_user_instance_pause(ALSATimerUserInstance *self, GError **error) * @self: A #ALSATimerUserInstance. * @error: A #GError. * - * Stop event emission. + * Continue timer event emission paused by alsatimer_user_instance_pause(). + * + * The call of function executes ioctl(2) system call with + * SNDRV_TIMER_IOCTL_CONTINUE command for ALSA timer character device. */ void alsatimer_user_instance_continue(ALSATimerUserInstance *self, GError **error) -- 2.47.3