From 8dd3d7f449fa1f0ad43667b24350a24ea0c9f8e4 Mon Sep 17 00:00:00 2001 From: Jeff Johnson Date: Mon, 13 Feb 2023 20:13:07 -0800 Subject: [PATCH] qcacmn: Fix QDF time-related documentation The kernel-doc script identified documentation issues in the QDF time-related abstractions, so fix those issues. Change-Id: Ieffd4a5b2a38674da1b19735ad6f35844d355f09 CRs-Fixed: 3406200 --- qdf/inc/qdf_hrtimer.h | 14 +-- qdf/inc/qdf_pkt_add_timestamp.h | 20 ++-- qdf/inc/qdf_time.h | 199 +++++--------------------------- qdf/linux/src/i_qdf_hrtimer.h | 5 +- qdf/linux/src/i_qdf_time.h | 17 +-- 5 files changed, 56 insertions(+), 199 deletions(-) diff --git a/qdf/inc/qdf_hrtimer.h b/qdf/inc/qdf_hrtimer.h index 7715aa1ac3..7161bc3cf0 100644 --- a/qdf/inc/qdf_hrtimer.h +++ b/qdf/inc/qdf_hrtimer.h @@ -1,6 +1,6 @@ /* * Copyright (c) 2014-2018, 2021 The Linux Foundation. All rights reserved. - * Copyright (c) 2022 Qualcomm Innovation Center, Inc. All rights reserved. + * Copyright (c) 2022-2023 Qualcomm Innovation Center, Inc. All rights reserved. * * Permission to use, copy, modify, and/or distribute this software for * any purpose with or without fee is hereby granted, provided that the @@ -64,9 +64,9 @@ int qdf_hrtimer_cancel(qdf_hrtimer_data_t *timer); * qdf_hrtimer_init() - init hrtimer based on context * @timer: pointer to the qdf_hrtimer_data_t object * @callback: callback function to be fired - * @qdf_clock_id: clock type - * @qdf_hrtimer_mode: mode of qdf_hrtimer_data_t - * @qdf_context_mode: interrupt context mode + * @clock: clock type + * @mode: mode of qdf_hrtimer_data_t + * @ctx: interrupt context mode * * starts hrtimer in a context passed as per qdf_context_mode * @@ -201,9 +201,9 @@ int qdf_hrtimer_cancel(qdf_hrtimer_data_t *timer) * qdf_hrtimer_init() - init hrtimer based on context * @timer: pointer to the qdf_hrtimer_data_t object * @callback: callback function to be fired - * @qdf_clock_id: clock type - * @qdf_hrtimer_mode: mode of qdf_hrtimer_data_t - * @qdf_context_mode: interrupt context mode + * @clock: clock type + * @mode: mode of qdf_hrtimer_data_t + * @ctx: interrupt context mode * * starts hrtimer in a context passed as per qdf_context_mode * diff --git a/qdf/inc/qdf_pkt_add_timestamp.h b/qdf/inc/qdf_pkt_add_timestamp.h index cb7ae5f68c..f92c29cce3 100644 --- a/qdf/inc/qdf_pkt_add_timestamp.h +++ b/qdf/inc/qdf_pkt_add_timestamp.h @@ -1,5 +1,5 @@ /* - * Copyright (c) 2022 Qualcomm Innovation Center, Inc. All rights reserved. + * Copyright (c) 2022-2023 Qualcomm Innovation Center, Inc. All rights reserved. * * Permission to use, copy, modify, and/or distribute this software for * any purpose with or without fee is hereby granted, provided that the @@ -31,10 +31,10 @@ /** * enum qdf_pkt_supported_proto - supported protocol for timestamp - * @QDF_PKT_PROTO_INVAL - invalid - * @QDF_PKT_PROTO_TCP - tcp protocol - * @QDF_PKT_PROTO_UDP - udp protocol - * @QDF_PKT_PROTO_MAX - max, keep it at last + * @QDF_PKT_PROTO_INVAL: invalid + * @QDF_PKT_PROTO_TCP: tcp protocol + * @QDF_PKT_PROTO_UDP: udp protocol + * @QDF_PKT_PROTO_MAX: max, keep it at last */ enum qdf_pkt_supported_proto { QDF_PKT_PROTO_INVAL, @@ -45,11 +45,11 @@ enum qdf_pkt_supported_proto { /** * enum qdf_pkt_timestamp_index - index of different timestamp - * @QDF_PKT_TX_DRIVER_ENTRY - tx driver entry timestamp - * @QDF_PKT_TX_DRIVER_EXIT - tx driver exit timestamp - * @QDF_PKT_RX_DRIVER_ENTRY - rx driver entry timestamp - * @QDF_PKT_RX_DRIVER_EXIT - rx driver exit timestamp - * @QDF_PKT_TIMESTAMP_MAX - maximum index, keep it at last + * @QDF_PKT_TX_DRIVER_ENTRY: tx driver entry timestamp + * @QDF_PKT_TX_DRIVER_EXIT: tx driver exit timestamp + * @QDF_PKT_RX_DRIVER_ENTRY: rx driver entry timestamp + * @QDF_PKT_RX_DRIVER_EXIT: rx driver exit timestamp + * @QDF_PKT_TIMESTAMP_MAX: maximum index, keep it at last */ enum qdf_pkt_timestamp_index { QDF_PKT_TX_DRIVER_ENTRY, diff --git a/qdf/inc/qdf_time.h b/qdf/inc/qdf_time.h index 81cb76afc0..a291c78c21 100644 --- a/qdf/inc/qdf_time.h +++ b/qdf/inc/qdf_time.h @@ -36,7 +36,7 @@ typedef __qdf_work_struct_t qdf_work_struct_t; #ifdef ENHANCED_OS_ABSTRACTION /** - * qdf_ns_to_ktime - Converts nanoseconds to a qdf_ktime_t object + * qdf_ns_to_ktime() - Converts nanoseconds to a qdf_ktime_t object * @ns: time in nanoseconds * * Return: nanoseconds as qdf_ktime_t object @@ -44,7 +44,7 @@ typedef __qdf_work_struct_t qdf_work_struct_t; qdf_ktime_t qdf_ns_to_ktime(uint64_t ns); /** - * qdf_ktime_add - Adds two qdf_ktime_t objects and returns + * qdf_ktime_add() - Adds two qdf_ktime_t objects and returns * a qdf_ktime_t object * @ktime1: time as qdf_ktime_t object * @ktime2: time as qdf_ktime_t object @@ -54,21 +54,21 @@ qdf_ktime_t qdf_ns_to_ktime(uint64_t ns); qdf_ktime_t qdf_ktime_add(qdf_ktime_t ktime1, qdf_ktime_t ktime2); /** - * qdf_ktime_get - Gets the current time as qdf_ktime_t object + * qdf_ktime_get() - Gets the current time as qdf_ktime_t object * * Return: current time as qdf_ktime_t object */ qdf_ktime_t qdf_ktime_get(void); /** - * qdf_ktime_real_get - Gets the current wall clock as qdf_ktime_t object + * qdf_ktime_real_get() - Gets the current wall clock as qdf_ktime_t object * * Return: current wall clock as qdf_ktime_t object */ qdf_ktime_t qdf_ktime_real_get(void); /** - * qdf_ktime_add_ns - Adds qdf_ktime_t object and nanoseconds value and + * qdf_ktime_add_ns() - Adds qdf_ktime_t object and nanoseconds value and * returns the qdf_ktime_t object * @ktime: time as qdf_ktime_t object * @ns: time in nanoseconds @@ -78,7 +78,7 @@ qdf_ktime_t qdf_ktime_real_get(void); qdf_ktime_t qdf_ktime_add_ns(qdf_ktime_t ktime, int64_t ns); /** - * qdf_ktime_to_ms - Convert the qdf_ktime_t object into milliseconds + * qdf_ktime_to_ms() - Convert the qdf_ktime_t object into milliseconds * @ktime: time as qdf_ktime_t object * * Return: qdf_ktime_t in milliseconds @@ -86,7 +86,7 @@ qdf_ktime_t qdf_ktime_add_ns(qdf_ktime_t ktime, int64_t ns); int64_t qdf_ktime_to_ms(qdf_ktime_t ktime); /** - * qdf_ktime_to_us - Convert the qdf_ktime_t object into microseconds + * qdf_ktime_to_us() - Convert the qdf_ktime_t object into microseconds * @ktime: time as qdf_ktime_t object * * Return: qdf_ktime_t in microseconds @@ -94,7 +94,7 @@ int64_t qdf_ktime_to_ms(qdf_ktime_t ktime); int64_t qdf_ktime_to_us(qdf_ktime_t ktime); /** - * qdf_ktime_to_ns - Convert the qdf_ktime_t object into nanoseconds + * qdf_ktime_to_ns() - Convert the qdf_ktime_t object into nanoseconds * @ktime: time as qdf_ktime_t object * * Return: qdf_ktime_t in nanoseconds @@ -102,7 +102,7 @@ int64_t qdf_ktime_to_us(qdf_ktime_t ktime); int64_t qdf_ktime_to_ns(qdf_ktime_t ktime); /** - * qdf_system_ticks - Count the number of ticks elapsed from the time when + * qdf_system_ticks() - Count the number of ticks elapsed from the time when * the system booted * * Return: ticks @@ -112,7 +112,7 @@ qdf_time_t qdf_system_ticks(void); #define qdf_system_ticks_per_sec __qdf_system_ticks_per_sec /** - * qdf_system_ticks_to_msecs - convert ticks to milliseconds + * qdf_system_ticks_to_msecs() - convert ticks to milliseconds * @clock_ticks: Number of ticks * * Return: unsigned int Time in milliseconds @@ -120,7 +120,7 @@ qdf_time_t qdf_system_ticks(void); uint32_t qdf_system_ticks_to_msecs(unsigned long clock_ticks); /** - * qdf_system_ticks_to_nsecs - convert ticks to nanoseconds + * qdf_system_ticks_to_nsecs() - convert ticks to nanoseconds * @clock_ticks: Number of ticks * * Return: unsigned int Time in nanoseconds @@ -128,15 +128,15 @@ uint32_t qdf_system_ticks_to_msecs(unsigned long clock_ticks); uint32_t qdf_system_ticks_to_nsecs(unsigned long clock_ticks); /** - * qdf_system_msecs_to_ticks - convert milliseconds to ticks - * @msec: Time in milliseconds + * qdf_system_msecs_to_ticks() - convert milliseconds to ticks + * @msecs: Time in milliseconds * * Return: unsigned long number of ticks */ qdf_time_t qdf_system_msecs_to_ticks(uint32_t msecs); /** - * qdf_get_system_uptime - Return a monotonically increasing time + * qdf_get_system_uptime() - Return a monotonically increasing time * This increments once per HZ ticks * * Return: qdf_time_t system up time in ticks @@ -156,14 +156,14 @@ qdf_time_t qdf_get_system_uptime(void); uint64_t qdf_get_bootbased_boottime_ns(void); /** - * qdf_get_system_timestamp - Return current timestamp + * qdf_get_system_timestamp() - Return current timestamp * * Return: unsigned long timestamp in ms. */ unsigned long qdf_get_system_timestamp(void); /** - * qdf_udelay - delay in microseconds + * qdf_udelay() - delay in microseconds * @usecs: Number of microseconds to delay * * Return: none @@ -171,8 +171,8 @@ unsigned long qdf_get_system_timestamp(void); void qdf_udelay(int usecs); /** - * qdf_mdelay - Delay in milliseconds. - * @msec: Number of milliseconds to delay + * qdf_mdelay() - Delay in milliseconds. + * @msecs: Number of milliseconds to delay * * Return: none */ @@ -229,9 +229,12 @@ enum qdf_timestamp_unit { uint64_t qdf_log_timestamp_to_usecs(uint64_t time); /** - * qdf_get_log_timestamp_to_secs() - get time stamp for logging in seconds + * qdf_log_timestamp_to_secs() - get time stamp for logging in seconds + * @time: logging timestamp + * @secs: pointer to write seconds + * @usecs: pointer to write microseconds * - * Return: The current logging timestamp normalized to second precision + * Return: void. The normalized time is returned in @secs and @usecs */ void qdf_log_timestamp_to_secs(uint64_t time, uint64_t *secs, uint64_t *usecs); @@ -239,7 +242,7 @@ void qdf_log_timestamp_to_secs(uint64_t time, uint64_t *secs, uint64_t qdf_usecs_to_log_timestamp(uint64_t usecs); /** - * qdf_get_log_timestamp - get time stamp for logging + * qdf_get_log_timestamp() - get time stamp for logging * For adrastea this API returns QTIMER tick which is needed to synchronize * host and fw log timestamps * For ROME and other discrete solution this API returns system boot time stamp @@ -258,7 +261,7 @@ uint64_t qdf_get_log_timestamp(void); uint64_t qdf_get_log_timestamp_usecs(void); /** - * qdf_get_monotonic_boottime - get monotonic kernel boot time + * qdf_get_monotonic_boottime() - get monotonic kernel boot time * This API is similar to qdf_get_system_boottime but it includes * time spent in suspend. * @@ -275,116 +278,60 @@ uint64_t qdf_get_monotonic_boottime(void); void qdf_time_ktime_get_real_time(qdf_timespec_t *ts); /** - * qdf_time_sched_clock - scheduler clock + * qdf_time_sched_clock() - scheduler clock * * Return: current time in nanosec units. */ unsigned long long qdf_time_sched_clock(void); #else -/** - * qdf_ns_to_ktime - Converts nanoseconds to a qdf_ktime_t object - * @ns: time in nanoseconds - * - * Return: nanoseconds as qdf_ktime_t object - */ static inline qdf_ktime_t qdf_ns_to_ktime(uint64_t ns) { return __qdf_ns_to_ktime(ns); } -/** - * qdf_ktime_add - Adds two qdf_ktime_t objects and returns - * a qdf_ktime_t object - * @ktime1: time as qdf_ktime_t object - * @ktime2: time as qdf_ktime_t object - * - * Return: sum of both qdf_ktime_t as qdf_ktime_t object - */ static inline qdf_ktime_t qdf_ktime_add(qdf_ktime_t ktime1, qdf_ktime_t ktime2) { return __qdf_ktime_add(ktime1, ktime2); } -/** - * qdf_ktime_get - Gets the current time as qdf_ktime_t object - * - * Return: current time as qdf_ktime_t object - */ static inline qdf_ktime_t qdf_ktime_get(void) { return __qdf_ktime_get(); } -/** - * qdf_ktime_real_get - Gets the current wall clock as qdf_ktime_t object - * - * Return: current wall clock as qdf_ktime_t object - */ static inline qdf_ktime_t qdf_ktime_real_get(void) { return __qdf_ktime_real_get(); } -/** - * qdf_ktime_add_ns - Adds qdf_ktime_t object and nanoseconds value and - * returns the qdf_ktime_t object - * @ktime: time as qdf_ktime_t object - * @ns: time in nanoseconds - * - * Return: qdf_ktime_t object - */ static inline qdf_ktime_t qdf_ktime_add_ns(qdf_ktime_t ktime, int64_t ns) { return __qdf_ktime_add_ns(ktime, ns); } -/** - * qdf_ktime_to_ms - Convert the qdf_ktime_t object into milliseconds - * @ktime: time as qdf_ktime_t object - * - * Return: qdf_ktime_t in milliseconds - */ static inline int64_t qdf_ktime_to_ms(qdf_ktime_t ktime) { return __qdf_ktime_to_ms(ktime); } -/** - * qdf_ktime_to_us - Convert the qdf_ktime_t object into microseconds - * @ktime: time as qdf_ktime_t object - * - * Return: qdf_ktime_t in microseconds - */ static inline int64_t qdf_ktime_to_us(qdf_ktime_t ktime) { return __qdf_time_ktime_to_us(ktime); } -/** - * qdf_ktime_to_ns - Convert the qdf_ktime_t object into nanoseconds - * @ktime: time as qdf_ktime_t object - * - * Return: qdf_ktime_t in nanoseconds - */ static inline int64_t qdf_ktime_to_ns(qdf_ktime_t ktime) { return __qdf_ktime_to_ns(ktime); } -/** - * qdf_system_ticks - Count the number of ticks elapsed from the time when - * the system booted - * - * Return: ticks - */ static inline qdf_time_t qdf_system_ticks(void) { return __qdf_system_ticks(); @@ -392,122 +339,52 @@ static inline qdf_time_t qdf_system_ticks(void) #define qdf_system_ticks_per_sec __qdf_system_ticks_per_sec -/** - * qdf_system_ticks_to_msecs - convert ticks to milliseconds - * @clock_ticks: Number of ticks - * - * Return: unsigned int Time in milliseconds - */ static inline uint32_t qdf_system_ticks_to_msecs(unsigned long clock_ticks) { return __qdf_system_ticks_to_msecs(clock_ticks); } -/** - * qdf_system_msecs_to_ticks - convert milliseconds to ticks - * @msec: Time in milliseconds - * - * Return: unsigned long number of ticks - */ static inline qdf_time_t qdf_system_msecs_to_ticks(uint32_t msecs) { return __qdf_system_msecs_to_ticks(msecs); } -/** - * qdf_get_system_uptime - Return a monotonically increasing time - * This increments once per HZ ticks - * - * Return: qdf_time_t system up time in ticks - */ static inline qdf_time_t qdf_get_system_uptime(void) { return __qdf_get_system_uptime(); } -/** - * qdf_get_bootbased_boottime_ns() - Get the bootbased time in nanoseconds - * - * qdf_get_bootbased_boottime_ns() function returns the number of nanoseconds - * that have elapsed since the system was booted. It also includes the time when - * system was suspended. - * - * Return: - * The time since system booted in nanoseconds - */ static inline uint64_t qdf_get_bootbased_boottime_ns(void) { return __qdf_get_bootbased_boottime_ns(); } -/** - * qdf_get_system_timestamp - Return current timestamp - * - * Return: unsigned long timestamp in ms. - */ static inline unsigned long qdf_get_system_timestamp(void) { return __qdf_get_system_timestamp(); } -/** - * qdf_udelay - delay in microseconds - * @usecs: Number of microseconds to delay - * - * Return: none - */ static inline void qdf_udelay(int usecs) { __qdf_udelay(usecs); } -/** - * qdf_mdelay - Delay in milliseconds. - * @msec: Number of milliseconds to delay - * - * Return: none - */ static inline void qdf_mdelay(int msecs) { __qdf_mdelay(msecs); } -/** - * qdf_system_time_after() - Check if a is later than b - * @a: Time stamp value a - * @b: Time stamp value b - * - * Return: - * true if a < b else false - */ static inline bool qdf_system_time_after(qdf_time_t a, qdf_time_t b) { return __qdf_system_time_after(a, b); } -/** - * qdf_system_time_before() - Check if a is before b - * @a: Time stamp value a - * @b: Time stamp value b - * - * Return: - * true if a is before b else false - */ static inline bool qdf_system_time_before(qdf_time_t a, qdf_time_t b) { return __qdf_system_time_before(a, b); } -/** - * qdf_system_time_after_eq() - Check if a atleast as recent as b, if not - * later - * @a: Time stamp value a - * @b: Time stamp value b - * - * Return: - * true if a >= b else false - */ static inline bool qdf_system_time_after_eq(qdf_time_t a, qdf_time_t b) { return __qdf_system_time_after_eq(a, b); @@ -557,7 +434,7 @@ static inline uint64_t qdf_log_timestamp_to_usecs(uint64_t time) } /** - * qdf_get_log_timestamp_lightweight - get time stamp for logging + * qdf_get_log_timestamp_lightweight() - get time stamp for logging * For adrastea this API returns QTIMER tick which is needed to synchronize * host and fw log timestamps * For ROME and other discrete solution this API returns system boot time stamp @@ -609,38 +486,16 @@ static inline uint64_t qdf_usecs_to_log_timestamp(uint64_t usecs) return (usecs * QDF_LOG_TIMESTAMP_CYCLES_PER_10_US) / 10; } -/** - * qdf_get_log_timestamp - get time stamp for logging - * For adrastea this API returns QTIMER tick which is needed to synchronize - * host and fw log timestamps - * For ROME and other discrete solution this API returns system boot time stamp - * - * Return: - * QTIMER ticks(19.2MHz) for adrastea - * System tick for rome and other future discrete solutions - */ static inline uint64_t qdf_get_log_timestamp(void) { return __qdf_get_log_timestamp(); } -/** - * qdf_get_log_timestamp_usecs() - get time stamp for logging in microseconds - * - * Return: The current logging timestamp normalized to microsecond precision - */ static inline uint64_t qdf_get_log_timestamp_usecs(void) { return qdf_log_timestamp_to_usecs(qdf_get_log_timestamp()); } -/** - * qdf_get_monotonic_boottime - get monotonic kernel boot time - * This API is similar to qdf_get_system_boottime but it includes - * time spent in suspend. - * - * Return: Time in microseconds - */ static inline uint64_t qdf_get_monotonic_boottime(void) { return __qdf_get_monotonic_boottime(); diff --git a/qdf/linux/src/i_qdf_hrtimer.h b/qdf/linux/src/i_qdf_hrtimer.h index c02d836572..13672595cc 100644 --- a/qdf/linux/src/i_qdf_hrtimer.h +++ b/qdf/linux/src/i_qdf_hrtimer.h @@ -1,6 +1,6 @@ /* * Copyright (c) 2014-2019,2021 The Linux Foundation. All rights reserved. - * Copyright (c) 2022 Qualcomm Innovation Center, Inc. All rights reserved. + * Copyright (c) 2022-2023 Qualcomm Innovation Center, Inc. All rights reserved. * * Permission to use, copy, modify, and/or distribute this software for * any purpose with or without fee is hereby granted, provided that the @@ -139,7 +139,8 @@ static enum hrtimer_restart __qdf_hrtimer_cb(struct hrtimer *arg) * @timer: pointer to the hrtimer object * @cback: callback function to be fired * @clock: clock id - * @hrtimer_mode: mode of hrtimer + * @mode: mode of hrtimer + * @ctx: interrupt context mode * * starts hrtimer in a context passed as per the context * diff --git a/qdf/linux/src/i_qdf_time.h b/qdf/linux/src/i_qdf_time.h index df527cb215..d9db5e2fa1 100644 --- a/qdf/linux/src/i_qdf_time.h +++ b/qdf/linux/src/i_qdf_time.h @@ -73,8 +73,8 @@ static inline ktime_t __qdf_ns_to_ktime(uint64_t ns) /** * __qdf_ktime_add() - Adds two ktime objects and returns * a ktime object - * @time1: time as ktime object - * @time2: time as ktime object + * @ktime1: time as ktime object + * @ktime2: time as ktime object * * Return: sum of ktime objects as ktime object */ @@ -105,7 +105,9 @@ static inline ktime_t __qdf_ktime_real_get(void) /** * __qdf_ktime_add_ns() - Adds ktime object and nanoseconds value and - * returns the ktime object + * returns the ktime object + * @ktime: time as ktime object + * @ns: time in nanoseconds * * Return: ktime object */ @@ -117,7 +119,6 @@ static inline ktime_t __qdf_ktime_add_ns(ktime_t ktime, int64_t ns) /** * __qdf_ktime_to_ns() - convert ktime to nanoseconds * @ktime: time as ktime object - * @ns: time in nanoseconds * * Return: ktime in nanoseconds */ @@ -231,7 +232,7 @@ static inline void __qdf_udelay(uint32_t usecs) /** * __qdf_mdelay() - delay execution for given milliseconds - * @usecs: Milliseconds to delay + * @msecs: Milliseconds to delay * * Return: none */ @@ -281,7 +282,7 @@ static inline bool __qdf_system_time_after_eq(__qdf_time_t a, __qdf_time_t b) } /** - * qdf_sched_clock() - use light weight timer to get timestamp + * __qdf_sched_clock() - use light weight timer to get timestamp * * Return: timestamp in ns */ @@ -420,8 +421,8 @@ static inline unsigned long long __qdf_time_sched_clock(void) /** * __qdf_time_ktime_sub() - Subtract two ktime objects and returns * a ktime object - * @time1: time as ktime object - * @time2: time as ktime object + * @ktime1: time as ktime object + * @ktime2: time as ktime object * * Return: subtraction of ktime objects as ktime object */