From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [170.10.129.124]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 25BC63ED109 for ; Fri, 27 Mar 2026 13:30:55 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=170.10.129.124 ARC-Seal:i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1774618257; cv=none; b=qGCt20Rb4FKAk9GYA7/Spjl6BdMf8bxICVKyeb40SMy05hVTReVFhRyvEbFQm4mH6h6OciOfDNfRwNCSUqf3NdVTX8rQL2kW93sfQFq3qbzg1Ru+5zoIRtmYsX868X5lIrkk4Gu8cOexpqa7eDcNF9LvFUZ6/bZ9Xm8A+InZYXk= ARC-Message-Signature:i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1774618257; c=relaxed/simple; bh=sghX4PphvCW7X0zgsIy5ejmBRZP/ntzeJagmmu1/j2g=; h=Date:From:To:Cc:Subject:Message-ID:References:MIME-Version: Content-Type:Content-Disposition:In-Reply-To; b=nQofoiasKYgcxVco/fyJEaMjD6K6VtsNXiTn5EFekqSa5yWMTJ3ek1s3PCeHExZnGOo1U0BS4yyYifrewU2raqC87V9cNKEMHFoVyhpfl5bv7N4pzlBFACkpAQuUIt9Uw5waZxTLpu6wv3offHyZDD2eag5uqneh/d2Vp0ki9/U= ARC-Authentication-Results:i=1; smtp.subspace.kernel.org; dmarc=pass (p=quarantine dis=none) header.from=redhat.com; spf=pass smtp.mailfrom=redhat.com; dkim=pass (1024-bit key) header.d=redhat.com header.i=@redhat.com header.b=Km18bzjg; dkim=pass (2048-bit key) header.d=redhat.com header.i=@redhat.com header.b=m1zuoVUQ; arc=none smtp.client-ip=170.10.129.124 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=quarantine dis=none) header.from=redhat.com Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=redhat.com Authentication-Results: smtp.subspace.kernel.org; dkim=pass (1024-bit key) header.d=redhat.com header.i=@redhat.com header.b="Km18bzjg"; dkim=pass (2048-bit key) header.d=redhat.com header.i=@redhat.com header.b="m1zuoVUQ" DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1774618255; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: in-reply-to:in-reply-to:references:references; bh=wp4gmpeShrxSfN4R+47KecY7fqn2WEuVtUlQVVvdg1Y=; b=Km18bzjg4TCWAlj/Wk3AnmtgVjoo/O+TKL75/fudpwqOGv/NAYZ776ISQzQzzh4D4RbTvn f4WhsFoY16F/eR1BU7cK2wip3x+S9aKJlPFX/QsiKIJeX2q/sOydS2NiTVdxmEaBWyo5YI WE8XdOSqJhfXltnV6ufyD/qk7VBhQsQ= Received: from mail-qk1-f197.google.com (mail-qk1-f197.google.com [209.85.222.197]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-567--PSXvmZiOXeD76JkCMcfYw-1; Fri, 27 Mar 2026 09:30:52 -0400 X-MC-Unique: -PSXvmZiOXeD76JkCMcfYw-1 X-Mimecast-MFC-AGG-ID: -PSXvmZiOXeD76JkCMcfYw_1774618251 Received: by mail-qk1-f197.google.com with SMTP id af79cd13be357-8cb52a9c0eeso748559685a.2 for ; Fri, 27 Mar 2026 06:30:51 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=google; t=1774618251; x=1775223051; darn=vger.kernel.org; h=user-agent:in-reply-to:content-disposition:mime-version:references :message-id:subject:cc:to:from:date:from:to:cc:subject:date :message-id:reply-to; bh=wp4gmpeShrxSfN4R+47KecY7fqn2WEuVtUlQVVvdg1Y=; b=m1zuoVUQTQEbtgHXErYPLubyfOS7lDcl9FCpxOHSvqpUPAZmRZZPUB50j/E3/FVVwh wBYIqlKnIhwm5vEluJw3OrWmRgjcTpMEA8s1NfAj5McAoePs0y8GsR3bhq9PYm2WhRR+ gFG8jq0qzGbiC6BTxajqBuLDsBBg3Og9Py38ZbvwidZdvdFWV9UJNTYrHqURrh/tnqTq gj2OThnlQ3AVBVsUsSMQRE9WdAxcTNlRHl48i8socNitTq4HPP/RL7czoi3PJns9EGJl hfDP00ftfi2/wFbnPM+7Whmn+Tcs4u5qsBMmahTlKvFg9DQao0JW/evRQQC9zjllTPn+ cCog== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20251104; t=1774618251; x=1775223051; h=user-agent:in-reply-to:content-disposition:mime-version:references :message-id:subject:cc:to:from:date:x-gm-gg:x-gm-message-state:from :to:cc:subject:date:message-id:reply-to; bh=wp4gmpeShrxSfN4R+47KecY7fqn2WEuVtUlQVVvdg1Y=; b=WETBxyw/Fj70Id3GeH68HsAAWcupDUt6Z1fD6zwYgJikVxIteSbgM3j/loGrUO+R2x Qr9liTgENyZn4UXj643ZW0v7Vp0BSMSN4VpItTbAI0Z+50KiJ3XcnQ6tdXAL2N6FVPia lz5c32hk9AaRolLulQgxIt1CKTVWhlG5xGX3VT0GdatodAWwRmM2nB9dZmMlde11ChgY OWekMN4aQNAYgSfF9p3qi+uwyTyRC6WYRNSysjEjaqtun4Kwmo1OE+CYxEXCB4OlTycW YOAQmPtvZKmvgPXcA8fJDHoa8iiXbF+r4FQ9yMcOOF/+/XEZPaJcygTNkLIv0XGPHE49 hWXA== X-Forwarded-Encrypted: i=1; AJvYcCUZ/OJAa2UG4ZeCGJuAsD7xP+cLWg+Ng/cGkUZEfcWDN1AEqSowXG3JZV9JJ4jsp4t6SxrYjyw1MU35/98=@vger.kernel.org X-Gm-Message-State: AOJu0YycMnEYJAwVNg5hiNR4nDIzeeIjoegnDviEENwqSL8RxjdQGAqr rc/2bnaNiHDhsajN2LGjwe12uxg3OuGk45f6pOUenLwzCe4LKVgOQ+1CBGMgg3wGEXY3aqEGz47 pM9Duwc+he34d/pDv4wa+u2tWy9W6Nbrd5kl3HWNVNmYNHx7XoevG9u76c1IuZGGF3w== X-Gm-Gg: ATEYQzyFf1SSu64FqsAUDMB33OMAce7PN0LiIUgJzm8eZ/JA5s647QC4Id6cBxcaIMV RsoR0b3kQKecBlSqPspE2c56tyZ3NxXBTerdSV+cgP+XkskZk3dsC4fsRCy2IK1MmV7l1fFkCw6 Z0Si2U/G0tPg7bm7Qq1gdifz45PMxqsKUmgEikbADzBqYqoHuOgy58ZJx2qKgATIYdKGuW4gUR8 NDh9A/sDdMv8nTjONvdIeMWgJLaXOAqtJy8a+dCfIWaqNQo+1SB6ZiHk1oQpl340fAnLU262Hv8 w2QHMCTEp7Z99AeZGPIcfp9olRqDMIOkyPCApYgOXjQ1o47D/mMZOv/UIliyPnWFy9WcVvj+h2C yNBTtPkHUxoB4zc36FtCiHTvzu99FIUz/DjwUkFZbxWnssiM9HKsaZTKo X-Received: by 2002:a05:620a:468c:b0:8cd:a76d:6305 with SMTP id af79cd13be357-8d01c7bd635mr314485485a.49.1774618244666; Fri, 27 Mar 2026 06:30:44 -0700 (PDT) X-Received: by 2002:a05:620a:468c:b0:8cd:a76d:6305 with SMTP id af79cd13be357-8d01c7bd635mr314431985a.49.1774618239539; Fri, 27 Mar 2026 06:30:39 -0700 (PDT) Received: from redhat.com (c-73-183-52-120.hsd1.pa.comcast.net. [73.183.52.120]) by smtp.gmail.com with ESMTPSA id af79cd13be357-8d00e4cf112sm500417285a.23.2026.03.27.06.30.38 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Fri, 27 Mar 2026 06:30:38 -0700 (PDT) Date: Fri, 27 Mar 2026 09:30:37 -0400 From: Brian Masney To: Michael Turquette , Stephen Boyd , Maxime Ripard , Jonathan Corbet , Shuah Khan Cc: linux-clk@vger.kernel.org, linux-kernel@vger.kernel.org, linux-doc@vger.kernel.org Subject: Re: [PATCH v2 1/4] clk: move core flags into a new enum for kernel docs Message-ID: References: <20260325-clk-docs-v2-0-bcf660e1ceb5@redhat.com> <20260325-clk-docs-v2-1-bcf660e1ceb5@redhat.com> Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <20260325-clk-docs-v2-1-bcf660e1ceb5@redhat.com> User-Agent: Mutt/2.3.0 (2026-01-25) Hi Stephen, On Wed, Mar 25, 2026 at 07:52:10PM -0400, Brian Masney wrote: > Let's move all of the existing clk flags into a new enum so that all of > the flags can be easily referenced in the kernel documentation. Note > that I went with name clk_core_flags for the enum since the name > clk_flags is already in use in clk.c for the debugfs interface. > > Note: The comment about "Please update clk_flags..." is included as a > separate comment so it doesn't show up in the generated documents. > > Signed-off-by: Brian Masney > --- > include/linux/clk-provider.h | 55 +++++++++++++++++++++++++++----------------- > 1 file changed, 34 insertions(+), 21 deletions(-) > > diff --git a/include/linux/clk-provider.h b/include/linux/clk-provider.h > index 630705a47129453c241f1b1755f2c2f2a7ed8f77..cb167c17c4f79cf438a26bb113b4968d0f223468 100644 > --- a/include/linux/clk-provider.h > +++ b/include/linux/clk-provider.h > @@ -9,29 +9,42 @@ > #include > #include > > -/* > - * flags used across common struct clk. these flags should only affect the > - * top-level framework. custom flags for dealing with hardware specifics > - * belong in struct clk_foo > +/* Please update clk_flags[] in drivers/clk/clk.c when making changes here! */ > +/** > + * enum clk_core_flags - framework-level clock flags > * > - * Please update clk_flags[] in drivers/clk/clk.c when making changes here! > + * These flags should only affect the top-level framework. Custom flags for > + * dealing with hardware specifics belong in struct clk_foo. > + * > + * @CLK_SET_RATE_GATE: must be gated across rate change > + * @CLK_SET_PARENT_GATE: must be gated across re-parent > + * @CLK_SET_RATE_PARENT: propagate rate change up one level > + * @CLK_IGNORE_UNUSED: do not gate even if unused > + * @CLK_GET_RATE_NOCACHE: do not use the cached clk rate > + * @CLK_SET_RATE_NO_REPARENT: don't re-parent on rate change > + * @CLK_GET_ACCURACY_NOCACHE: do not use the cached clk accuracy > + * @CLK_RECALC_NEW_RATES: recalc rates after notifications > + * @CLK_SET_RATE_UNGATE: clock needs to run to set rate > + * @CLK_IS_CRITICAL: do not gate, ever > + * @CLK_OPS_PARENT_ENABLE: parents need enable during gate/ungate, set rate and re-parent > + * @CLK_DUTY_CYCLE_PARENT: duty cycle call may be forwarded to the parent clock > */ > -#define CLK_SET_RATE_GATE BIT(0) /* must be gated across rate change */ > -#define CLK_SET_PARENT_GATE BIT(1) /* must be gated across re-parent */ > -#define CLK_SET_RATE_PARENT BIT(2) /* propagate rate change up one level */ > -#define CLK_IGNORE_UNUSED BIT(3) /* do not gate even if unused */ > - /* unused */ > - /* unused */ > -#define CLK_GET_RATE_NOCACHE BIT(6) /* do not use the cached clk rate */ > -#define CLK_SET_RATE_NO_REPARENT BIT(7) /* don't re-parent on rate change */ > -#define CLK_GET_ACCURACY_NOCACHE BIT(8) /* do not use the cached clk accuracy */ > -#define CLK_RECALC_NEW_RATES BIT(9) /* recalc rates after notifications */ > -#define CLK_SET_RATE_UNGATE BIT(10) /* clock needs to run to set rate */ > -#define CLK_IS_CRITICAL BIT(11) /* do not gate, ever */ > -/* parents need enable during gate/ungate, set rate and re-parent */ > -#define CLK_OPS_PARENT_ENABLE BIT(12) > -/* duty cycle call may be forwarded to the parent clock */ > -#define CLK_DUTY_CYCLE_PARENT BIT(13) > +enum clk_core_flags { > + CLK_SET_RATE_GATE = BIT(0), > + CLK_SET_PARENT_GATE = BIT(1), > + CLK_SET_RATE_PARENT = BIT(2), > + CLK_IGNORE_UNUSED = BIT(3), > + /* unused */ > + /* unused */ > + CLK_GET_RATE_NOCACHE = BIT(6), > + CLK_SET_RATE_NO_REPARENT = BIT(7), > + CLK_GET_ACCURACY_NOCACHE = BIT(8), > + CLK_RECALC_NEW_RATES = BIT(9), > + CLK_SET_RATE_UNGATE = BIT(10), > + CLK_IS_CRITICAL = BIT(11), > + CLK_OPS_PARENT_ENABLE = BIT(12), > + CLK_DUTY_CYCLE_PARENT = BIT(13), > +}; I just checked Sashiko [1] for this series and it has this comment: Could converting these unsigned long bitmasks to an enum create a silent type-safety trap if flags ever reach BIT(31)? The flags fields in the clock framework are explicitly designed to be 64-bit on 64-bit architectures (unsigned long). The BIT() macro evaluates to an unsigned long. When defined as macros, operations like clearing flags produce a 64-bit inverted mask, perfectly preserving the upper 32 bits. By moving these flags into an enum, their types are implicitly downgraded to int, since the current maximum flag BIT(13) fits in a 32-bit signed integer. If the flags ever grow to include BIT(31), the enumerator value will overflow a signed 32-bit int, causing the compiler to type it as an unsigned int. Applying a bitwise NOT to this unsigned int will produce an unsigned int. When this is bitwise ANDed with the 64-bit unsigned long flags variable, the unsigned mask will zero-extend to 64 bits, silently clearing all upper 32 bits (bits 32-63) of the flags field. Would it be safer to keep them as #define macros and use a DOC: block to properly document the flags using kernel-doc without breaking type safety? It's up to you how we should proceed with this. [1] https://sashiko.dev/#/patchset/20260325-clk-docs-v2-0-bcf660e1ceb5%40redhat.com Brian