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 1B61314B973 for ; Mon, 10 Jun 2024 18:03:37 +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=1718042618; cv=none; b=W6NQkrKA0LS3xIOD3LjwV2sNI6JAho/9ofJi1BJXejqBeYdfo8Lp9CkPdde1Y27uCgAv//1CsobyCr8qIFugJCjusfHT6ZPvoNqP11485tfcXFMmVq72myGLuxDSC8xdoXwiS8Htv1ui6HXNNskbvkITmwnkK/yLmT5UPwcabEM= ARC-Message-Signature:i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1718042618; c=relaxed/simple; bh=uo7uJNZ3epcfm6pUCaHZJk3wrGW8HkLdKy1yzy9H64k=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=kalBiw7bfGtsj9Jkq9gVp4Bcgx7yCbHeOvvP5QsOdY0eZgDFmE7jBuMAzGoipmgVHQz9xdoXqGuWJ5p7cco7f7HCFkaocsafjMXX7OLuYRRYv9mrl33fyWOlvbY/MMv/T/tuUbKNhCAmxNn4sCICDlAHhCAZtZRGdpeUuMPBjiA= ARC-Authentication-Results:i=1; smtp.subspace.kernel.org; dmarc=pass (p=none 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=F5LgH3Uy; arc=none smtp.client-ip=170.10.129.124 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=none 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="F5LgH3Uy" DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1718042616; 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: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=Ko/751Ih42xdNXKctrEpP8bOTHpEg6/LHScfPoHYDW4=; b=F5LgH3UyfsYrLkOFDjX2O7vELo01wof83OfUM4jkWxzXd+NgScGbJ9ylonutU1UMnEYoMF IJatR802QWZ+S7KZhckMtlKP0JznbEimv0GbJwhgUzeY8vi89xblAZsDh74VDg4RcB+0/c WZCxXoZC4++hzCSpN9JQpHqF3DYeY/I= Received: from mail-wr1-f70.google.com (mail-wr1-f70.google.com [209.85.221.70]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-479-mlLj4HmTNv2CrPazeg4kvw-1; Mon, 10 Jun 2024 14:03:34 -0400 X-MC-Unique: mlLj4HmTNv2CrPazeg4kvw-1 Received: by mail-wr1-f70.google.com with SMTP id ffacd0b85a97d-35f0b9c5bd4so104584f8f.2 for ; Mon, 10 Jun 2024 11:03:34 -0700 (PDT) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1718042614; x=1718647414; 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=Ko/751Ih42xdNXKctrEpP8bOTHpEg6/LHScfPoHYDW4=; b=pOiS5vHwsg4bVy+9v1F4orY41UPahhudUs1p2I8Bcxvcl92dQ91nMmWAwHHUDqxPfn plLkKVqfNUx4UKnEYmhkLtW0IbOMoSqlvLUgihaqSFLM3G0BrCPzCKWW7pmrBWLCuago 95N4/myF7/yWkCpZ1FrJHuiXZfQdB4ZV43q+ATGcAVXLgC81crkIQf6OJnm+Tf1SHTxZ c2Tg4yfhTlMmotPySkIJ+zwcxsqh3Y4HiEuuxTfAPyeP5+vz6W9PsrSo9QLS2IpxAlz4 u0Y+rzt280A5WQeRzNmAHdZc+Q1/FiZQRhRbA1I099yYDPbrGbAn+z0XFtahlYKos/RN cvEw== X-Gm-Message-State: AOJu0Yzg9LoRvl2Mg4MO+4j/X6kH3nrUvlZL1uvKaqPgBwDi6or3qP/P c9ELva8y4Nf5sC7CZpvDtlk67FGX1C5qSI9ZJALMRzawGrDJuTh6ADVmnxmcjW6HuVJ/FG1kaYL Q4s7Hj5z2CShSs2NNlgP6it5atULSUB/pAXO2ryfuAVTocLQAXuZqPdaCq4j8aRqM X-Received: by 2002:a05:6000:2c2:b0:35f:1835:3a62 with SMTP id ffacd0b85a97d-35f18353c74mr5628305f8f.35.1718042613651; Mon, 10 Jun 2024 11:03:33 -0700 (PDT) X-Google-Smtp-Source: AGHT+IGRjRL00cNynGjzhv5Ncbfra3TprBtbnWt4hfvsVgE5SGzuiZzJ0gnNTax6xVQ+ug9rSsbqwA== X-Received: by 2002:a05:6000:2c2:b0:35f:1835:3a62 with SMTP id ffacd0b85a97d-35f18353c74mr5628275f8f.35.1718042613322; Mon, 10 Jun 2024 11:03:33 -0700 (PDT) Received: from cassiopeiae.. ([2a02:810d:4b3f:ee94:642:1aff:fe31:a19f]) by smtp.gmail.com with ESMTPSA id ffacd0b85a97d-35f1aed74cesm6273814f8f.112.2024.06.10.11.03.31 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 10 Jun 2024 11:03:32 -0700 (PDT) From: Danilo Krummrich To: gregkh@linuxfoundation.org, rafael@kernel.org, mcgrof@kernel.org, russell.h.weight@intel.com, ojeda@kernel.org, alex.gaynor@gmail.com, wedsonaf@gmail.com, boqun.feng@gmail.com, gary@garyguo.net, bjorn3_gh@protonmail.com, benno.lossin@proton.me, a.hindborg@samsung.com, aliceryhl@google.com, airlied@gmail.com, fujita.tomonori@gmail.com, pstanner@redhat.com, ajanulgu@redhat.com, lyude@redhat.com Cc: rust-for-linux@vger.kernel.org, linux-kernel@vger.kernel.org, Danilo Krummrich Subject: [PATCH v2 2/2] rust: add firmware abstractions Date: Mon, 10 Jun 2024 20:02:28 +0200 Message-ID: <20240610180318.72152-3-dakr@redhat.com> X-Mailer: git-send-email 2.45.1 In-Reply-To: <20240610180318.72152-1-dakr@redhat.com> References: <20240610180318.72152-1-dakr@redhat.com> Precedence: bulk X-Mailing-List: rust-for-linux@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Content-Transfer-Encoding: 8bit Content-Type: text/plain; charset="US-ASCII"; x-default=true Add an abstraction around the kernels firmware API to request firmware images. The abstraction provides functions to access the firmware's size and backing buffer. The firmware is released once the abstraction instance is dropped. Signed-off-by: Danilo Krummrich --- rust/bindings/bindings_helper.h | 1 + rust/kernel/firmware.rs | 107 ++++++++++++++++++++++++++++++++ rust/kernel/lib.rs | 1 + 3 files changed, 109 insertions(+) create mode 100644 rust/kernel/firmware.rs diff --git a/rust/bindings/bindings_helper.h b/rust/bindings/bindings_helper.h index ddb5644d4fd9..18a3f05115cb 100644 --- a/rust/bindings/bindings_helper.h +++ b/rust/bindings/bindings_helper.h @@ -9,6 +9,7 @@ #include #include #include +#include #include #include #include diff --git a/rust/kernel/firmware.rs b/rust/kernel/firmware.rs new file mode 100644 index 000000000000..7ff4c325f670 --- /dev/null +++ b/rust/kernel/firmware.rs @@ -0,0 +1,107 @@ +// SPDX-License-Identifier: GPL-2.0 + +//! Firmware abstraction +//! +//! C header: [`include/linux/firmware.h`](srctree/include/linux/firmware.h") + +use crate::{bindings, device::Device, error::Error, error::Result, str::CStr}; +use core::ptr::NonNull; + +// One of the following: `bindings::request_firmware`, `bindings::firmware_request_nowarn`, +// `firmware_request_platform`, `bindings::request_firmware_direct` +type FwFunc = + unsafe extern "C" fn(*mut *const bindings::firmware, *const i8, *mut bindings::device) -> i32; + +/// Abstraction around a C `struct firmware`. +/// +/// This is a simple abstraction around the C firmware API. Just like with the C API, firmware can +/// be requested. Once requested the abstraction provides direct access to the firmware buffer as +/// `&[u8]`. The firmware is released once [`Firmware`] is dropped. +/// +/// # Invariants +/// +/// The pointer is valid, and has ownership over the instance of `struct firmware`. +/// +/// # Examples +/// +/// ``` +/// use kernel::firmware::Firmware; +/// +/// let fw = Firmware::request("path/to/firmware.bin", dev.as_ref())?; +/// driver_load_firmware(fw.data()); +/// ``` +pub struct Firmware(NonNull); + +impl Firmware { + fn request_internal(name: &CStr, dev: &Device, func: FwFunc) -> Result { + let mut fw: *mut bindings::firmware = core::ptr::null_mut(); + let pfw: *mut *mut bindings::firmware = &mut fw; + + // SAFETY: `pfw` is a valid pointer to a NULL initialized `bindings::firmware` pointer. + // `name` and `dev` are valid as by their type invariants. + let ret = unsafe { func(pfw as _, name.as_char_ptr(), dev.as_raw()) }; + if ret != 0 { + return Err(Error::from_errno(ret)); + } + + // SAFETY: `func` not bailing out with a non-zero error code, guarantees that `fw` is a + // valid pointer to `bindings::firmware`. + Ok(Firmware(unsafe { NonNull::new_unchecked(fw) })) + } + + /// Send a firmware request and wait for it. See also `bindings::request_firmware`. + pub fn request(name: &CStr, dev: &Device) -> Result { + Self::request_internal(name, dev, bindings::request_firmware) + } + + /// Send a request for an optional firmware module. See also + /// `bindings::firmware_request_nowarn`. + pub fn request_nowarn(name: &CStr, dev: &Device) -> Result { + Self::request_internal(name, dev, bindings::firmware_request_nowarn) + } + + /// Send a request for a firmware with platform-fw fallback. See also + /// `bindings::firmware_request_platform`. + pub fn request_platform(name: &CStr, dev: &Device) -> Result { + Self::request_internal(name, dev, bindings::firmware_request_platform) + } + + /// Send a request for a firmware directly without usermode helper. See also + /// `bindings::request_firmware_direct`. + pub fn request_direct(name: &CStr, dev: &Device) -> Result { + Self::request_internal(name, dev, bindings::request_firmware_direct) + } + + fn as_raw(&self) -> *mut bindings::firmware { + self.0.as_ptr() + } + + /// Returns the size of the requested firmware in bytes. + pub fn size(&self) -> usize { + // SAFETY: Safe as by the type invariant. + unsafe { (*self.as_raw()).size } + } + + /// Returns the requested firmware as `&[u8]`. + pub fn data(&self) -> &[u8] { + // SAFETY: Safe as by the type invariant. Additionally, `bindings::firmware` guarantees, if + // sucessfully requested, that `bindings::firmware::data` has a size of + // `bindings::firmware::size` bytes. + unsafe { core::slice::from_raw_parts((*self.as_raw()).data, self.size()) } + } +} + +impl Drop for Firmware { + fn drop(&mut self) { + // SAFETY: Safe as by the type invariant. + unsafe { bindings::release_firmware(self.as_raw()) }; + } +} + +// SAFETY: `Firmware` only holds a pointer to a C `struct firmware`, which is safe to be used from +// any thread. +unsafe impl Send for Firmware {} + +// SAFETY: `Firmware` only holds a pointer to a C `struct firmware`, references to which are safe to +// be used from any thread. +unsafe impl Sync for Firmware {} diff --git a/rust/kernel/lib.rs b/rust/kernel/lib.rs index dd1207f1a873..5307aa45bb8d 100644 --- a/rust/kernel/lib.rs +++ b/rust/kernel/lib.rs @@ -30,6 +30,7 @@ mod build_assert; pub mod device; pub mod error; +pub mod firmware; pub mod init; pub mod ioctl; #[cfg(CONFIG_KUNIT)] -- 2.45.1