From aff60aba6c44770fab8f2694ae81bafde6d22998 Mon Sep 17 00:00:00 2001 From: Sean Anderson Date: Wed, 7 Oct 2020 14:37:43 -0400 Subject: doc: Document timer API This adds kerneldocs for . I don't know who should maintain doc/api/timer.rst, since the timer subsystem seems to be maintained by SoC maintainers. MAINTAINERS is left un-updated for the moment. Signed-off-by: Sean Anderson Reviewed-by: Simon Glass --- include/timer.h | 46 ++++++++++++++++++++++++---------------------- 1 file changed, 24 insertions(+), 22 deletions(-) (limited to 'include/timer.h') diff --git a/include/timer.h b/include/timer.h index 8b9fa51c53..aa9d870619 100644 --- a/include/timer.h +++ b/include/timer.h @@ -6,12 +6,12 @@ #ifndef _TIMER_H_ #define _TIMER_H_ -/* - * dm_timer_init - initialize a timer for time keeping. On success +/** + * dm_timer_init() - initialize a timer for time keeping. On success * initializes gd->timer so that lib/timer can use it for future * referrence. * - * @return - 0 on success or error number + * Return: 0 on success or error number */ int dm_timer_init(void); @@ -30,49 +30,51 @@ int dm_timer_init(void); */ int timer_timebase_fallback(struct udevice *dev); -/* - * timer_conv_64 - convert 32-bit counter value to 64-bit - * +/** + * timer_conv_64() - convert 32-bit counter value to 64-bit * @count: 32-bit counter value - * @return: 64-bit counter value + * + * Return: 64-bit counter value */ u64 timer_conv_64(u32 count); -/* - * Get the current timer count - * +/** + * timer_get_count() - Get the current timer count * @dev: The timer device * @count: pointer that returns the current timer count - * @return: 0 if OK, -ve on error + * + * Return: 0 if OK, -ve on error */ int timer_get_count(struct udevice *dev, u64 *count); -/* - * Get the timer input clock frequency - * +/** + * timer_get_rate() - Get the timer input clock frequency * @dev: The timer device - * @return: the timer input clock frequency + * + * Return: the timer input clock frequency */ unsigned long timer_get_rate(struct udevice *dev); -/* +/** * struct timer_ops - Driver model timer operations * * The uclass interface is implemented by all timer devices which use * driver model. */ struct timer_ops { - /* - * Get the current timer count + /** + * @get_count: Get the current timer count * * @dev: The timer device + * * @count: pointer that returns the current 64-bit timer count - * @return: 0 if OK, -ve on error + * + * Return: 0 if OK, -ve on error */ int (*get_count)(struct udevice *dev, u64 *count); }; -/* +/** * struct timer_dev_priv - information about a device used by the uclass * * @clock_rate: the timer input clock frequency @@ -84,7 +86,7 @@ struct timer_dev_priv { /** * timer_early_get_count() - Implement timer_get_count() before driver model * - * If CONFIG_TIMER_EARLY is enabled, this function wil be called to return + * If ``CONFIG_TIMER_EARLY`` is enabled, this function wil be called to return * the current timer value before the proper driver model timer is ready. * It should be implemented by one of the timer values. This is mostly useful * for tracing. @@ -94,7 +96,7 @@ u64 timer_early_get_count(void); /** * timer_early_get_rate() - Get the timer rate before driver model * - * If CONFIG_TIMER_EARLY is enabled, this function wil be called to return + * If ``CONFIG_TIMER_EARLY`` is enabled, this function wil be called to return * the current timer rate in Hz before the proper driver model timer is ready. * It should be implemented by one of the timer values. This is mostly useful * for tracing. This corresponds to the clock_rate value in struct -- cgit From 8af7bb914f8b2238ea37faa8e59277ba4cb26d37 Mon Sep 17 00:00:00 2001 From: Sean Anderson Date: Wed, 7 Oct 2020 14:37:44 -0400 Subject: timer: Return count from timer_ops.get_count No timer drivers return an error from get_count. Instead of possibly returning an error, just return the count directly. Signed-off-by: Sean Anderson Reviewed-by: Claudiu Beznea Reviewed-by: Simon Glass --- include/timer.h | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) (limited to 'include/timer.h') diff --git a/include/timer.h b/include/timer.h index aa9d870619..a044cb034e 100644 --- a/include/timer.h +++ b/include/timer.h @@ -67,11 +67,14 @@ struct timer_ops { * * @dev: The timer device * - * @count: pointer that returns the current 64-bit timer count + * This function may be called at any time after the driver is probed. + * All necessary initialization must be completed by the time probe() + * returns. The count returned by this functions should be monotonic. + * This function must succeed. * - * Return: 0 if OK, -ve on error + * Return: The current 64-bit timer count */ - int (*get_count)(struct udevice *dev, u64 *count); + u64 (*get_count)(struct udevice *dev); }; /** -- cgit