From patchwork Tue Mar 18 05:57:14 2025 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Viresh Kumar X-Patchwork-Id: 14020340 Received: from mail-pl1-f182.google.com (mail-pl1-f182.google.com [209.85.214.182]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 8CE121C4A10 for ; Tue, 18 Mar 2025 05:57:35 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=209.85.214.182 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1742277457; cv=none; b=t/Qg0tYsJfLQn10Jp3O/2LD1kWs5gFzp+nGMrDmnr5OP5QekttkH/FAWviHGAu2k9/MHhKSC3INoJ9sQfFEOIxjscboEMaJJEAyGbeTiwJT2OAGKHiKVfyIBEydCnQagflwdAQILnGbg2RKfypVPco6JdTzVTDPshhkFmZgbyGo= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1742277457; c=relaxed/simple; bh=VNorIlJrBMTZi3vbOgZiolGqGyUVBlGTnWAqVyyJeWM=; h=From:To:Cc:Subject:Date:Message-Id:In-Reply-To:References: MIME-Version; b=sCgfF/rbQ3Zlhcy7KcBH6wYP0gWfMsKYcaHeQCtqeYTRIel1+B9SEHfah1p6BmdY7X5JmBTYMb5mrPTVZpjGSBeHIdN78WjcshSae5CiOeRBibKzH9pFMvrlzjyYp5ewn14Ohcd6Ssh5+LuituailCQpmRnmPgqZrTTYQuW9fxw= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=linaro.org; spf=pass smtp.mailfrom=linaro.org; dkim=pass (2048-bit key) header.d=linaro.org header.i=@linaro.org header.b=qOrrjkQh; arc=none smtp.client-ip=209.85.214.182 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=linaro.org Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=linaro.org Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=linaro.org header.i=@linaro.org header.b="qOrrjkQh" Received: by mail-pl1-f182.google.com with SMTP id d9443c01a7336-22401f4d35aso97221985ad.2 for ; Mon, 17 Mar 2025 22:57:35 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; t=1742277455; x=1742882255; darn=vger.kernel.org; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:from:to:cc:subject:date :message-id:reply-to; bh=llikhmZ0VyhG0hV+3+6urJ6KvAwqIcQWJl1kQJnPD9w=; b=qOrrjkQhTc4G/uGlq2p6r1GAeOflf6jTccwVXpwIwBftALn+KJccgUE1MM/pukUb/V z7sRhZSx4y1MYjp1bOSql+MEQPkZD8g8M/oiu/zweLnEAMBZkfR6TyYF8SJuTFHLseOR H2L1rCwoAcvw2XtmqfnoFFxAqxlKNWdkGC5FWMrxkdwF5ZGyLp1xQehi3+VqcVTdbpTS cbSbdFJshq00D7sa0YW7Jn2jGaWAtEWZVtljwNQ2WpL3bhp1cgJdr4vEpF2/MnPFVohr 1BsAlq2G1w/wFXukiTZj4uOiV/d0Tm40Tehc+iAwRm5jAPC/rnQDgR4xo2VgyE6yVgrh 92kQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1742277455; x=1742882255; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=llikhmZ0VyhG0hV+3+6urJ6KvAwqIcQWJl1kQJnPD9w=; b=OX+S/oKoI+x1y8VZCt27GI4kLPpicNhR3UIrYlZ1OwmpdALcD19bUes+uJiolNpsYJ 3KAm0247Xt7UGsA3pIXTJ8XSPoORiiKhVLacLvBJafFIUVFrH9unwibyyldlscKiZ1P6 2pfQuEQVAyDeSWo+CK5Qm7dtGjKVb/ZOZ8sWt9stT7ciLoqb/kgOhb6gd01Zz4nbH267 s+KwG7CNvKWZQWB5IsvqxUgU4uPIFmPx67ZwulOQyRHBllZk2sgMuUPrlaRdZ1XSe6f9 nvwah685kIEUMqcW2xqi3S6tGJapj+bCn93cnIu/op2gzfTxfh1sVauJVkZiFTLaMs7W ID5Q== X-Forwarded-Encrypted: i=1; AJvYcCXXByo4vzQ1F6Qaa7dbJoI2Zt/ZIV89NhzYziioRkeJzfSZfYkdgwE+D7x+XPx0Ytxe4nR/elb4C58=@vger.kernel.org X-Gm-Message-State: AOJu0Yw3KDy1pjxWNRQ7jwB5LQvPF2irLgZ5Ign7zIfdhG7hakQcjMEE nxJQ7443qMnn5VU6bM2UwbUf4SON/X1Vb4BJ4iawVbtecaBspnOtoe2Ddbp30Dc= X-Gm-Gg: ASbGncsRSv5+uAxa+V08A7lD9xqBMfIDMBx8T4osYWBpFmpVCGdqwsOg5AQx4f3hgb+ Ka5/JbZ+R1ybUJI5/pF376dJHvav25/CglTyZZiVmwWnKPbiBtEI3mQT+iM6NPV362Ctroz5fhK lHd7i43gbVV98kCeTf31UuN9BbpZnM4NqW1sxspeS64IO3WNW9wBOTlw7fWk0Rl4BVOIaj2xMX4 sI2Uj583D4heqKaT6T4CmGUlXxTb2IvWtbna96a5burJJDZ7SR/Mqy1zUWCyL4zIkNtjNAptazk gtLE7MDKxLJApYRdrsSA7nYzxIkT3pOyu9nO9EqtBiJuqg== X-Google-Smtp-Source: AGHT+IHt4dP/2ZCotnLRvPmF95XeDbGWHGlcVUF0swIV4HUIiEJWdVoagzWLCHWRlpu/tKYoi70Y7g== X-Received: by 2002:a17:902:ced0:b0:220:e156:63e0 with SMTP id d9443c01a7336-2262c51bc95mr19693135ad.8.1742277454770; Mon, 17 Mar 2025 22:57:34 -0700 (PDT) Received: from localhost ([122.172.84.15]) by smtp.gmail.com with ESMTPSA id d9443c01a7336-225c68887bfsm85715745ad.34.2025.03.17.22.57.33 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 17 Mar 2025 22:57:34 -0700 (PDT) From: Viresh Kumar To: Miguel Ojeda , Alex Gaynor , Boqun Feng , Gary Guo , =?utf-8?q?B?= =?utf-8?q?j=C3=B6rn_Roy_Baron?= , Benno Lossin , Andreas Hindborg , Alice Ryhl , Trevor Gross , Michael Turquette , Stephen Boyd Cc: Viresh Kumar , Russell King , linux-clk@vger.kernel.org, linux-kernel@vger.kernel.org, rust-for-linux@vger.kernel.org, Vincent Guittot , Daniel Almeida Subject: [PATCH V4 1/2] rust: Add clk helpers Date: Tue, 18 Mar 2025 11:27:14 +0530 Message-Id: <171b6cd811ff4e913880ab33bc11e634f7cdeecb.1742276963.git.viresh.kumar@linaro.org> X-Mailer: git-send-email 2.31.1.272.g89b43f80a514 In-Reply-To: References: Precedence: bulk X-Mailing-List: linux-clk@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Non-trivial C macros and inlined C functions cannot be used directly in the Rust code and are used via functions ("helpers") that wrap those so that they can be called from Rust. In order to prepare for adding Rust abstractions for the clock APIs, add clock helpers required by the Rust implementation. Reviewed-by: Daniel Almeida Signed-off-by: Viresh Kumar --- MAINTAINERS | 1 + rust/bindings/bindings_helper.h | 1 + rust/helpers/clk.c | 66 +++++++++++++++++++++++++++++++++ rust/helpers/helpers.c | 1 + 4 files changed, 69 insertions(+) create mode 100644 rust/helpers/clk.c diff --git a/MAINTAINERS b/MAINTAINERS index 25c86f47353d..726110d3c988 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -5778,6 +5778,7 @@ F: include/dt-bindings/clock/ F: include/linux/clk-pr* F: include/linux/clk/ F: include/linux/of_clk.h +F: rust/helpers/clk.c X: drivers/clk/clkdev.c COMMON INTERNET FILE SYSTEM CLIENT (CIFS and SMB3) diff --git a/rust/bindings/bindings_helper.h b/rust/bindings/bindings_helper.h index 55354e4dec14..4e4e16c3b479 100644 --- a/rust/bindings/bindings_helper.h +++ b/rust/bindings/bindings_helper.h @@ -10,6 +10,7 @@ #include #include #include +#include #include #include #include diff --git a/rust/helpers/clk.c b/rust/helpers/clk.c new file mode 100644 index 000000000000..6d04372c9f3b --- /dev/null +++ b/rust/helpers/clk.c @@ -0,0 +1,66 @@ +// SPDX-License-Identifier: GPL-2.0 + +#include + +/* + * The "inline" implementation of below helpers are only available when + * CONFIG_HAVE_CLK or CONFIG_HAVE_CLK_PREPARE aren't set. + */ +#ifndef CONFIG_HAVE_CLK +struct clk *rust_helper_clk_get(struct device *dev, const char *id) +{ + return clk_get(dev, id); +} + +void rust_helper_clk_put(struct clk *clk) +{ + clk_put(clk); +} + +int rust_helper_clk_enable(struct clk *clk) +{ + return clk_enable(clk); +} + +void rust_helper_clk_disable(struct clk *clk) +{ + clk_disable(clk); +} + +unsigned long rust_helper_clk_get_rate(struct clk *clk) +{ + return clk_get_rate(clk); +} + +int rust_helper_clk_set_rate(struct clk *clk, unsigned long rate) +{ + return clk_set_rate(clk, rate); +} +#endif + +#ifndef CONFIG_HAVE_CLK_PREPARE +int rust_helper_clk_prepare(struct clk *clk) +{ + return clk_prepare(clk); +} + +void rust_helper_clk_unprepare(struct clk *clk) +{ + clk_unprepare(clk); +} +#endif + +struct clk *rust_helper_clk_get_optional(struct device *dev, const char *id) +{ + return clk_get_optional(dev, id); +} + +int rust_helper_clk_prepare_enable(struct clk *clk) +{ + return clk_prepare_enable(clk); +} + +void rust_helper_clk_disable_unprepare(struct clk *clk) +{ + clk_disable_unprepare(clk); +} diff --git a/rust/helpers/helpers.c b/rust/helpers/helpers.c index 0640b7e115be..4700ee7aaf85 100644 --- a/rust/helpers/helpers.c +++ b/rust/helpers/helpers.c @@ -11,6 +11,7 @@ #include "bug.c" #include "build_assert.c" #include "build_bug.c" +#include "clk.c" #include "cred.c" #include "device.c" #include "err.c" From patchwork Tue Mar 18 05:57:15 2025 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Viresh Kumar X-Patchwork-Id: 14020341 Received: from mail-pj1-f45.google.com (mail-pj1-f45.google.com [209.85.216.45]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 642F21A316D for ; Tue, 18 Mar 2025 05:57:39 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=209.85.216.45 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1742277461; cv=none; b=lCPkXVUuu1yzrMi6CYAHhidHb8IuXhm78OAD0837fK47ArVdD4O5Q3Eqn9nxrGgSlNQES1YmCWBLBxtvEtIJIWO8FTCeatizg24/u3v80O6MfZ9VGPwo9+OPQRXGPvPcVnoEHwU9NP/EC2Ej3libRuNkn7CgEOZdu9v0vrn83Ns= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1742277461; c=relaxed/simple; bh=QrGYM+L5VRLkQ+j1KGvIl8l8Rqjv58DYzTHE+ZFQouQ=; h=From:To:Cc:Subject:Date:Message-Id:In-Reply-To:References: MIME-Version; b=egnKNHvNo/6bPRfINUO+H366nYpPmrssvDKQPaty7dqlFawGiykfVq7B4K4THv3Pez1VPZG7WV0MEhkNaWwUSCF4Tr4G4zY4n0HAiukNEsgTq2tbrenI8cNMeXDlE36r2YIdjXIqpfxf8efKxW71g9iK2B5q7t6UFj5o7Sv5NBo= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=linaro.org; spf=pass smtp.mailfrom=linaro.org; dkim=pass (2048-bit key) header.d=linaro.org header.i=@linaro.org header.b=G1ee/kBb; arc=none smtp.client-ip=209.85.216.45 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=linaro.org Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=linaro.org Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=linaro.org header.i=@linaro.org header.b="G1ee/kBb" Received: by mail-pj1-f45.google.com with SMTP id 98e67ed59e1d1-2ff85fec403so4887235a91.1 for ; Mon, 17 Mar 2025 22:57:39 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; t=1742277459; x=1742882259; darn=vger.kernel.org; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:from:to:cc:subject:date :message-id:reply-to; bh=FmL7pIbMMiy2GAmVDsrXc2GJuQ5W4DvWNxcEMGurfl8=; b=G1ee/kBbq1SIrCaojDUxMjNg6RkPWqL6M6yzpM7MErxovrLQZInhDFNjYqq9zL2pq5 4q5Ulgo6V93E+Ud3ZkY6ebhidI6jFGR7MoriFt78by1SB1Q0NT45v3+3AkRRI0Wx4yr0 sC+o68R069uSe0wTgszoqcI/c0CMyVXar2glXI/V2uhX71vSNXAzKlJSyoh6s1Tbcfrg avke2fthjFfGyJAMyLowJMsT2SZHs+p5yr9Bmsfo5qeh9st4B6RnuvR+sn0SivTLt5qv /qdqUWFLv84fe4QL7ECjRVxKRe0gOPUGUIjAVbc7RROw4i3fREYcMWMeoEF2jsacn1XA 54XQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1742277459; x=1742882259; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=FmL7pIbMMiy2GAmVDsrXc2GJuQ5W4DvWNxcEMGurfl8=; b=cYNf91LLLE89rQOl0XBbLaNRoCCtmC4WwdxBRhKJK4BYGRUgt8CkFbS56WX6bcPGp+ L5do5RoToV32tGk+d4UlUGRd1EqMptUsfsEnRCDy5InnQu9h74XCfmJGINWwnCe17A9A jJuKc8uv4TkM+BVraK/J+XxQFYvI/rj75ChTCC6UgPdf7PwqzFW82zn0EdSy0qnYEJl5 5baN+RS545mqSNKq0CxkSt9iqEFk0jo1GXUkKodnYR3ve/oRpnebG0V7+A4K1qdav47W 0AlIXtJBqAxPpwh2vSIMfU+pcFhkj56mwmcsJEYDC5JX3s8D5cES+u9m1UqIveVyfrQl hLIw== X-Forwarded-Encrypted: i=1; AJvYcCUDtXom1wX93V3/UaMU3PCW5QNdMrJ/7S56fs0PQZ7AHWA/ZKq8uGGIg68d20s1CxEFzLYQaU5XxZc=@vger.kernel.org X-Gm-Message-State: AOJu0YxZ3dJuzArQd8P5Wbfbl4hXPg2/qNHLj/crzu3mUikhVpdaAbKn xZyRLhmIMNe2Wa48hUTjdtiKwKQk2bnkDFxKOIrOmWnDxrOWtjo1hKQstU3GeKs= X-Gm-Gg: ASbGnctuXWFxoOjqNPulzIW3cP1z/x12ryb0QfM+EN7IobUaatxZ1/pUtjzhweIY96K nhsjHTfanIgYpBLZXc7FuDZmY1Z0fz7NL+zQwAHBDO8g+DSsbsSFU5QmutIPOF0zuzeMLxE9H3o RQYFEyY7bEArKc7eaQQRDloKzR8jV6r1HdF52+QlLYLUgLv39ZaC/PbJruwCqj6U5MIxSPPqZ2g X6YjSgff3IuLZH1nYr8HAVE1CK8wtEKFLipYC9G3RGDDpDkgPzBDDYMOw3woErB0x3DVY5RACFv qzKLPXtZQa7DJfJKl9ryRwsFzSnoRqHWRrOkI70suKA2hIZKaISv27zQ X-Google-Smtp-Source: AGHT+IEC9NQ2yOrdmt0PgOHi4oRZiAiPgFCOCuR5B8vjjUWh8gMnxLOSMLr7K9VwHEsHj9N1k+70sg== X-Received: by 2002:a05:6a21:1f8d:b0:1ee:b5f4:b1d7 with SMTP id adf61e73a8af0-1fa4f9540cbmr3373331637.7.1742277458694; Mon, 17 Mar 2025 22:57:38 -0700 (PDT) Received: from localhost ([122.172.84.15]) by smtp.gmail.com with ESMTPSA id d2e1a72fcca58-73711695b88sm8631623b3a.152.2025.03.17.22.57.37 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 17 Mar 2025 22:57:38 -0700 (PDT) From: Viresh Kumar To: Michael Turquette , Stephen Boyd , Miguel Ojeda , Alex Gaynor , Boqun Feng , Gary Guo , =?utf-8?q?Bj=C3=B6rn_Roy_Baron?= , Benno Lossin , Andreas Hindborg , Alice Ryhl , Trevor Gross Cc: Viresh Kumar , Russell King , linux-clk@vger.kernel.org, linux-kernel@vger.kernel.org, rust-for-linux@vger.kernel.org, Vincent Guittot , Daniel Almeida Subject: [PATCH V4 2/2] rust: Add initial clk abstractions Date: Tue, 18 Mar 2025 11:27:15 +0530 Message-Id: <0ca7d18d792a6108cb82a3d32e0172f8e945c144.1742276963.git.viresh.kumar@linaro.org> X-Mailer: git-send-email 2.31.1.272.g89b43f80a514 In-Reply-To: References: Precedence: bulk X-Mailing-List: linux-clk@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Add initial abstractions for the clk APIs. These provide the minimal functionality needed for common use cases, making them straightforward to introduce in the first iteration. These will be used by Rust based cpufreq / OPP layers to begin with. Tested-by: Daniel Almeida Reviewed-by: Daniel Almeida Signed-off-by: Viresh Kumar --- MAINTAINERS | 1 + rust/kernel/clk.rs | 304 +++++++++++++++++++++++++++++++++++++++++++++ rust/kernel/lib.rs | 2 + 3 files changed, 307 insertions(+) create mode 100644 rust/kernel/clk.rs diff --git a/MAINTAINERS b/MAINTAINERS index 726110d3c988..96e2574f41c0 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -5779,6 +5779,7 @@ F: include/linux/clk-pr* F: include/linux/clk/ F: include/linux/of_clk.h F: rust/helpers/clk.c +F: rust/kernel/clk.rs X: drivers/clk/clkdev.c COMMON INTERNET FILE SYSTEM CLIENT (CIFS and SMB3) diff --git a/rust/kernel/clk.rs b/rust/kernel/clk.rs new file mode 100644 index 000000000000..52dbd6b5a050 --- /dev/null +++ b/rust/kernel/clk.rs @@ -0,0 +1,304 @@ +// SPDX-License-Identifier: GPL-2.0 + +//! Clock abstractions. +//! +//! C header: [`include/linux/clk.h`](srctree/include/linux/clk.h) +//! +//! Reference: + +use crate::{ + bindings, + device::Device, + error::{from_err_ptr, to_result, Result}, + ffi::c_ulong, + prelude::*, +}; + +use core::{ops::Deref, ptr}; + +/// The frequency unit. +/// +/// Represents a frequency in hertz, wrapping a [`c_ulong`] value. +/// +/// ## Examples +/// +/// ``` +/// use kernel::clk::Hertz; +/// +/// let hz = 1_000_000_000; +/// let rate = Hertz(hz); +/// +/// assert_eq!(rate.as_hz(), hz); +/// assert_eq!(rate, Hertz(hz)); +/// assert_eq!(rate, Hertz::from_khz(hz / 1_000)); +/// assert_eq!(rate, Hertz::from_mhz(hz / 1_000_000)); +/// assert_eq!(rate, Hertz::from_ghz(hz / 1_000_000_000)); +/// ``` +#[derive(Copy, Clone, PartialEq, Eq, Debug)] +pub struct Hertz(pub c_ulong); + +impl Hertz { + /// Create a new instance from kilohertz (kHz) + pub fn from_khz(khz: c_ulong) -> Self { + Self(khz * 1_000) + } + + /// Create a new instance from megahertz (MHz) + pub fn from_mhz(mhz: c_ulong) -> Self { + Self(mhz * 1_000_000) + } + + /// Create a new instance from gigahertz (GHz) + pub fn from_ghz(ghz: c_ulong) -> Self { + Self(ghz * 1_000_000_000) + } + + /// Get the frequency in hertz + pub fn as_hz(&self) -> c_ulong { + self.0 + } +} + +impl From for c_ulong { + fn from(freq: Hertz) -> Self { + freq.0 + } +} + +/// A reference-counted clock. +/// +/// This represents the Rust abstraction for the C [`struct clk`]. +/// +/// # Invariants +/// +/// A [`Clk`] instance holds either a pointer to a valid [`struct clk`] created by the C portion of +/// the kernel or a NULL pointer. +/// +/// Instances of this type are reference-counted. Calling [`Clk::get`] ensures that the allocation +/// remains valid for the lifetime of the [`Clk`]. +/// +/// ## Examples +/// +/// The following example demonstrates how to obtain and configure a clock for a device. +/// +/// ``` +/// use kernel::c_str; +/// use kernel::clk::{Clk, Hertz}; +/// use kernel::device::Device; +/// use kernel::error::Result; +/// +/// fn configure_clk(dev: &Device) -> Result { +/// let clk = Clk::get(dev, Some(c_str!("apb_clk")))?; +/// +/// clk.prepare_enable()?; +/// +/// let expected_rate = Hertz::from_ghz(1); +/// +/// if clk.rate() != expected_rate { +/// clk.set_rate(expected_rate)?; +/// } +/// +/// clk.disable_unprepare(); +/// Ok(()) +/// } +/// ``` +/// +/// [`struct clk`]: https://docs.kernel.org/driver-api/clk.html +#[repr(transparent)] +pub struct Clk(*mut bindings::clk); + +impl Clk { + /// Gets [`Clk`] corresponding to a [`Device`] and a connection id. + /// + /// Equivalent to the kernel's [`clk_get`] API. + /// + /// [`clk_get`]: https://docs.kernel.org/core-api/kernel-api.html#c.clk_get + pub fn get(dev: &Device, name: Option<&CStr>) -> Result { + let con_id = if let Some(name) = name { + name.as_ptr() as *const _ + } else { + ptr::null() + }; + + // SAFETY: It is safe to call [`clk_get`] for a valid device pointer. + // + // INVARIANT: The reference-count is decremented when [`Clk`] goes out of scope. + Ok(Self(from_err_ptr(unsafe { + bindings::clk_get(dev.as_raw(), con_id) + })?)) + } + + /// Obtain the raw [`struct clk`] pointer. + #[inline] + pub fn as_raw(&self) -> *mut bindings::clk { + self.0 + } + + /// Enable the clock. + /// + /// Equivalent to the kernel's [`clk_enable`] API. + /// + /// [`clk_enable`]: https://docs.kernel.org/core-api/kernel-api.html#c.clk_enable + #[inline] + pub fn enable(&self) -> Result { + // SAFETY: By the type invariants, self.as_raw() is a valid argument for [`clk_enable`]. + to_result(unsafe { bindings::clk_enable(self.as_raw()) }) + } + + /// Disable the clock. + /// + /// Equivalent to the kernel's [`clk_disable`] API. + /// + /// [`clk_disable`]: https://docs.kernel.org/core-api/kernel-api.html#c.clk_disable + #[inline] + pub fn disable(&self) { + // SAFETY: By the type invariants, self.as_raw() is a valid argument for [`clk_disable`]. + unsafe { bindings::clk_disable(self.as_raw()) }; + } + + /// Prepare the clock. + /// + /// Equivalent to the kernel's [`clk_prepare`] API. + /// + /// [`clk_prepare`]: https://docs.kernel.org/core-api/kernel-api.html#c.clk_prepare + #[inline] + pub fn prepare(&self) -> Result { + // SAFETY: By the type invariants, self.as_raw() is a valid argument for [`clk_prepare`]. + to_result(unsafe { bindings::clk_prepare(self.as_raw()) }) + } + + /// Unprepare the clock. + /// + /// Equivalent to the kernel's [`clk_unprepare`] API. + /// + /// [`clk_unprepare`]: https://docs.kernel.org/core-api/kernel-api.html#c.clk_unprepare + #[inline] + pub fn unprepare(&self) { + // SAFETY: By the type invariants, self.as_raw() is a valid argument for [`clk_unprepare`]. + unsafe { bindings::clk_unprepare(self.as_raw()) }; + } + + /// Prepare and enable the clock. + /// + /// Equivalent to calling [`Clk::prepare`] followed by [`Clk::enable`]. + #[inline] + pub fn prepare_enable(&self) -> Result { + // SAFETY: By the type invariants, self.as_raw() is a valid argument for + // [`clk_prepare_enable`]. + to_result(unsafe { bindings::clk_prepare_enable(self.as_raw()) }) + } + + /// Disable and unprepare the clock. + /// + /// Equivalent to calling [`Clk::disable`] followed by [`Clk::unprepare`]. + #[inline] + pub fn disable_unprepare(&self) { + // SAFETY: By the type invariants, self.as_raw() is a valid argument for + // [`clk_disable_unprepare`]. + unsafe { bindings::clk_disable_unprepare(self.as_raw()) }; + } + + /// Get clock's rate. + /// + /// Equivalent to the kernel's [`clk_get_rate`] API. + /// + /// [`clk_get_rate`]: https://docs.kernel.org/core-api/kernel-api.html#c.clk_get_rate + #[inline] + pub fn rate(&self) -> Hertz { + // SAFETY: By the type invariants, self.as_raw() is a valid argument for [`clk_get_rate`]. + Hertz(unsafe { bindings::clk_get_rate(self.as_raw()) }) + } + + /// Set clock's rate. + /// + /// Equivalent to the kernel's [`clk_set_rate`] API. + /// + /// [`clk_set_rate`]: https://docs.kernel.org/core-api/kernel-api.html#c.clk_set_rate + #[inline] + pub fn set_rate(&self, rate: Hertz) -> Result { + // SAFETY: By the type invariants, self.as_raw() is a valid argument for [`clk_set_rate`]. + to_result(unsafe { bindings::clk_set_rate(self.as_raw(), rate.as_hz()) }) + } +} + +impl Drop for Clk { + fn drop(&mut self) { + // SAFETY: By the type invariants, self.as_raw() is a valid argument for [`clk_put`]. + unsafe { bindings::clk_put(self.as_raw()) }; + } +} + +/// A reference-counted optional clock. +/// +/// A lightweight wrapper around an optional [`Clk`]. An [`OptionalClk`] represents a [`Clk`] that +/// a driver can function without but may improve performance or enable additional features when +/// available. +/// +/// # Invariants +/// +/// An [`OptionalClk`] instance encapsulates a [`Clk`] with either a valid [`struct clk`] or `NULL` +/// pointer. +/// +/// Instances of this type are reference-counted. Calling [`OptionalClk::get`] ensures that the +/// allocation remains valid for the lifetime of the [`OptionalClk`]. +/// +/// ## Examples +/// +/// The following example demonstrates how to obtain and configure an optional clock for a device. +/// The code functions correctly whether or not the clock is available. +/// +/// ``` +/// use kernel::c_str; +/// use kernel::clk::{OptionalClk, Hertz}; +/// use kernel::device::Device; +/// use kernel::error::Result; +/// +/// fn configure_clk(dev: &Device) -> Result { +/// let clk = OptionalClk::get(dev, Some(c_str!("apb_clk")))?; +/// +/// clk.prepare_enable()?; +/// +/// let expected_rate = Hertz::from_ghz(1); +/// +/// if clk.rate() != expected_rate { +/// clk.set_rate(expected_rate)?; +/// } +/// +/// clk.disable_unprepare(); +/// Ok(()) +/// } +/// ``` +/// +/// [`struct clk`]: https://docs.kernel.org/driver-api/clk.html +pub struct OptionalClk(Clk); + +impl OptionalClk { + /// Gets [`OptionalClk`] corresponding to a [`Device`] and a connection id. + /// + /// Equivalent to the kernel's [`clk_get_optional`] API. + /// + /// [`clk_get_optional`]: https://docs.kernel.org/core-api/kernel-api.html#c.clk_get_optional + pub fn get(dev: &Device, name: Option<&CStr>) -> Result { + let con_id = if let Some(name) = name { + name.as_ptr() as *const _ + } else { + ptr::null() + }; + + // SAFETY: It is safe to call [`clk_get_optional`] for a valid device pointer. + // + // INVARIANT: The reference-count is decremented when [`OptionalClk`] goes out of scope. + Ok(Self(Clk(from_err_ptr(unsafe { + bindings::clk_get_optional(dev.as_raw(), con_id) + })?))) + } +} + +// Make [`OptionalClk`] behave like [`Clk`]. +impl Deref for OptionalClk { + type Target = Clk; + + fn deref(&self) -> &Clk { + &self.0 + } +} diff --git a/rust/kernel/lib.rs b/rust/kernel/lib.rs index 496ed32b0911..3748f954d71f 100644 --- a/rust/kernel/lib.rs +++ b/rust/kernel/lib.rs @@ -40,6 +40,8 @@ pub mod block; #[doc(hidden)] pub mod build_assert; +#[cfg(CONFIG_COMMON_CLK)] +pub mod clk; pub mod cred; pub mod device; pub mod device_id;