Return-Path: Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1751924AbbDLMWG (ORCPT ); Sun, 12 Apr 2015 08:22:06 -0400 Received: from www.osadl.org ([62.245.132.105]:36016 "EHLO www.osadl.org" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1751337AbbDLMV5 (ORCPT ); Sun, 12 Apr 2015 08:21:57 -0400 From: Nicholas Mc Guire To: Michal Marek Cc: Masahiro Yamada , Sam Ravnborg , Thomas Gleixner , "H. Peter Alvin" , Joe Perches , John Stultz , Andrew Hunter , Paul Turner , Aaron Sierra , Brian Norris , linux-kernel@vger.kernel.org, Nicholas Mc Guire Subject: [PATCH 3/3 V2] time: update msecs_to_jiffies doc and move to kernel-doc Date: Sun, 12 Apr 2015 14:13:35 +0200 Message-Id: <1428840815-21974-4-git-send-email-hofrat@osadl.org> X-Mailer: git-send-email 1.7.10.4 In-Reply-To: <1428840815-21974-1-git-send-email-hofrat@osadl.org> References: <1428840815-21974-1-git-send-email-hofrat@osadl.org> Sender: linux-kernel-owner@vger.kernel.org List-ID: X-Mailing-List: linux-kernel@vger.kernel.org Content-Length: 4890 Lines: 134 update the documentation of msecs_to_jiffies and move to kernel-doc format Signed-off-by: Nicholas Mc Guire --- V2: reformatting of documentation for the Hz range dependent _msecs_to_jiffies() helpers Patch is against 4.0-rc7 (localversion-next is -next-20150410) include/linux/jiffies.h | 39 +++++++++++++++++++++++++++++++++++++++ kernel/time/time.c | 25 ++++++++++++++++--------- 2 files changed, 55 insertions(+), 9 deletions(-) diff --git a/include/linux/jiffies.h b/include/linux/jiffies.h index 273b093..bb8d0d7 100644 --- a/include/linux/jiffies.h +++ b/include/linux/jiffies.h @@ -291,11 +291,22 @@ static inline u64 jiffies_to_nsecs(const unsigned long j) extern unsigned long __msecs_to_jiffies(const unsigned int m); #if HZ <= MSEC_PER_SEC && !(MSEC_PER_SEC % HZ) +/* + * HZ is equal to or smaller than 1000, and 1000 is a nice round + * multiple of HZ, divide with the factor between them, but round + * upwards: + */ static inline unsigned long _msecs_to_jiffies(const unsigned int m) { return (m + (MSEC_PER_SEC / HZ) - 1) / (MSEC_PER_SEC / HZ); } #elif HZ > MSEC_PER_SEC && !(HZ % MSEC_PER_SEC) +/* + * HZ is larger than 1000, and HZ is a nice round multiple of 1000 - + * simply multiply with the factor between them. + * + * But first make sure the multiplication result cannot overflow: + */ static inline unsigned long _msecs_to_jiffies(const unsigned int m) { if (m > jiffies_to_msecs(MAX_JIFFY_OFFSET)) @@ -303,6 +314,10 @@ static inline unsigned long _msecs_to_jiffies(const unsigned int m) return m * (HZ / MSEC_PER_SEC); } #else +/* + * Generic case - multiply, round and divide. But first check that if + * we are doing a net multiplication, that we wouldn't overflow: + */ static inline unsigned long _msecs_to_jiffies(const unsigned int m) { if (HZ > MSEC_PER_SEC && m > jiffies_to_msecs(MAX_JIFFY_OFFSET)) @@ -312,6 +327,30 @@ static inline unsigned long _msecs_to_jiffies(const unsigned int m) >> MSEC_TO_HZ_SHR32; } #endif +/** + * msecs_to_jiffies: - convert milliseconds to jiffies + * @m: time in milliseconds + * + * conversion is done as follows: + * + * - negative values mean 'infinite timeout' (MAX_JIFFY_OFFSET) + * + * - 'too large' values [that would result in larger than + * MAX_JIFFY_OFFSET values] mean 'infinite timeout' too. + * + * - all other values are converted to jiffies by either multiplying + * the input value by a factor or dividing it with a factor and + * handling any 32-bit overflows. + * for the details see __msecs_to_jiffies() + * + * msecs_to_jiffies() checks for the passed in value being a constant + * via __builtin_constant_p() allowing gcc to eliminate most of the + * code, __msecs_to_jiffies() is called if the value passed does not + * allow constant folding and the actual conversion must be done at + * runtime. + * the HZ range specific helpers _msecs_to_jiffies() are used for both + * cases + */ static inline unsigned long msecs_to_jiffies(const unsigned int m) { if (__builtin_constant_p(m)) { diff --git a/kernel/time/time.c b/kernel/time/time.c index f5196aa..884bb8e 100644 --- a/kernel/time/time.c +++ b/kernel/time/time.c @@ -483,22 +483,29 @@ struct timespec64 ns_to_timespec64(const s64 nsec) } EXPORT_SYMBOL(ns_to_timespec64); #endif -/* - * When we convert to jiffies then we interpret incoming values - * the following way: +/** + * msecs_to_jiffies: - convert milliseconds to jiffies + * @m: time in milliseconds + * + * conversion is done as follows: * * - negative values mean 'infinite timeout' (MAX_JIFFY_OFFSET) - * negative values are handled in msecs_to_jiffies in - * include/linux/jiffies.h * * - 'too large' values [that would result in larger than * MAX_JIFFY_OFFSET values] mean 'infinite timeout' too. * * - all other values are converted to jiffies by either multiplying - * the input value by a factor or dividing it with a factor - * - * We must also be careful about 32-bit overflows. - * + * the input value by a factor or dividing it with a factor and + * handling any 32-bit overflows. + * for the details see __msecs_to_jiffies() + * + * msecs_to_jiffies() checks for the passed in value being a constant + * via __builtin_constant_p() allowing gcc to eliminate most of the + * code, __msecs_to_jiffies() is called if the value passed does not + * allow constant folding and the actual conversion must be done at + * runtime. + * the _msecs_to_jiffies helpers are the HZ dependent conversion + * routines found in include/linux/jiffies.h */ unsigned long __msecs_to_jiffies(const unsigned int m) { -- 1.7.10.4 -- To unsubscribe from this list: send the line "unsubscribe linux-kernel" in the body of a message to majordomo@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/