From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from mail-pj1-f52.google.com (mail-pj1-f52.google.com [209.85.216.52]) (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 3A0041DF748 for ; Sun, 12 Jul 2026 15:30:38 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=209.85.216.52 ARC-Seal:i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1783870239; cv=none; b=sCTYUSTf/b3FU8kAsfGCAbv+VimZE8jX2Hzwd0Wg0Vi+I3IK5uwac72/RHVYKf8Xb20e9MxdiIIlJTu5ha/BdCGXxlVs2ZkrUcOrCWQScqFcWPthA34uq3Ws0ne/8a12zpj5qrwKVloqr/pRrwg69eJQFpO+qikCWRSt9Yl1uEM= ARC-Message-Signature:i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1783870239; c=relaxed/simple; bh=bSRx8gzU1P9HLkyXSFQmZ4ZPmUgPAb6Mx7i2pO169ho=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=NJhgnFBL1YLC1NL46MAOXhdJurEqwWL7OTL89+4H7BHBxjJul1RakEBZ9YIc23eDdU4QsD2PPH2kJ+7y30MUD1TyIGyYcm3jSzuEFOliT1u6Ier5U4OHKF/zIsBQW2n0tR9RGGCqeUWsEigIAFHN3egNz5YagE/yzo+nZX8o+cM= ARC-Authentication-Results:i=1; smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=gmail.com; spf=pass smtp.mailfrom=gmail.com; dkim=pass (2048-bit key) header.d=gmail.com header.i=@gmail.com header.b=P9ifNJG0; arc=none smtp.client-ip=209.85.216.52 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=gmail.com Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=gmail.com Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=gmail.com header.i=@gmail.com header.b="P9ifNJG0" Received: by mail-pj1-f52.google.com with SMTP id 98e67ed59e1d1-385ea3ce80dso2646709a91.2 for ; Sun, 12 Jul 2026 08:30:38 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20251104; t=1783870238; x=1784475038; 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:content-type; bh=ZxTi4ddCQW6xW5dWZpbLnP7mAc018/mNCKwB9sEIer8=; b=P9ifNJG0tcne4VON8xpe/Zw58f0q/WRtTkO4VhB+38CPQ0RCutwbLeTQ6pXbqCD4x8 o1Q8Veuh0hug13wAY0hNwgQP/Fs1acgCGdrp6uAhhuLdHQ4Vm5vLlhcc2Vkl/KedzAM2 at0wn4UNtl/puh47Xv4st6OZT8jWRrSw5Smc/nxhA7IBrVngsneFR9ifgtNd4lRYubRU sGPws6ZuAwxfEkfWTmeJmeVmrYGuDiMoWU9FzMte1NXwN/02yJwJrAlf+tCCszJ1O+Y4 Kc9v8xZbNopEFlkI3+EPeewAcNgsTk57et6Tf4AEzk3bjxpDKNX90szch07JomCOJPyi qEKg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20251104; t=1783870238; x=1784475038; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:x-gm-gg:x-gm-message-state:from :to:cc:subject:date:message-id:reply-to:content-type; bh=ZxTi4ddCQW6xW5dWZpbLnP7mAc018/mNCKwB9sEIer8=; b=TLtZ9jE3huHdWBUMeAefdJGH+aJSmSBB3I0VxAp2ONud/PbCamSAhdMrNG5Eop/hkI Z3y0oxtGI8JX3dz+kO7p875ptEfjvvkIaA8y6QRYAjNZ+KTWemqqpk1aMXzGCfMje6Zj 9SViGtQIkasgaSZs5J4vISj4T5PTcssXd0znyOxBTLO+PyneCVPz7p25rfK+E/Y7FtZ1 UwMCUKitiatMdjfYn31WUv2SUFYns3XgZqQGnhOula8U/IVS6fbtl3viqSbd05kPsVfp 2dPHRaSl0MgzGvKAG7hoQEGBLjPyabzpKOEt9UHWIIweljBZGjNY5Ha+hdJMwZPbhgoK 8/HA== X-Forwarded-Encrypted: i=1; AHgh+RrsTEtnHq+eqKZ+HT5JFox9AJbqggpJGGfltEN/07VFL6tvIwSrwiWg67pKJwUbSUBECl0wx/ryrxLcfys=@vger.kernel.org X-Gm-Message-State: AOJu0Yzud/pYDdJCji2CF1woCqNnwYtl/bL3zunLSKxnhaI97PwbZ3C1 GI/FFiXsnSWi5O/6nYFTBIs1ftwfktu4wXkDUKtTyUG2nJBeF1xoHaj5aFlSd3O/PpM= X-Gm-Gg: AfdE7cn08+oem2W0Q1DPVppIkq4IvnhaiyBMS1+EOxbZ8b5V+dy3UrZKLUktnAc8ZkJ d7EfmtEcHBR0xp3rxxkXBQvhICf5jJMUNzYnh3n+pakolz5/0zTR6MJaqukITaBC7hKe8ezU4pL 3VUz5HJsGN+BxX04U5CEmaWWEU3Ows8jp1XevN16OZWCvvwB9aaQiOYmdMkUgulE1gOQFhDYUsX vWc8Nr8uc9AjbRiBz/z9XQ+UeJcAMa9WVxKltJapLpZqu0HLTB6L6daHH5QGx72B5il72Eggr8k UO9nuPlsqXhyXHCjGfzNmlL3HuZWvxVkKX5VoEpLXs4jeKGVD8HVDHenXEHL6HkF0YWnYlTfIfN x9LUNCEdNquRu+CT8aXEu0cZ9r/R78RWtB0opzH8dYab3ylaICDyXTyiYUgfKvlg2p5LUYtXB04 oHhZ0ANztLzL9BZiUgK6vd1uwUbOp9nnv7tg4= X-Received: by 2002:a17:90b:3805:b0:380:83fc:4315 with SMTP id 98e67ed59e1d1-38dc77ee67cmr6442019a91.21.1783870237512; Sun, 12 Jul 2026 08:30:37 -0700 (PDT) Received: from Excalibur ([117.254.186.114]) by smtp.gmail.com with ESMTPSA id 5a478bee46e88-311935fd091sm41468147eec.24.2026.07.12.08.30.31 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Sun, 12 Jul 2026 08:30:36 -0700 (PDT) From: christopherjoshy To: ojeda@kernel.org Cc: boqun@kernel.org, gary@garyguo.net, aliceryhl@google.com, lyude@redhat.com, daniel.almeida@collabora.com, work@onurozkan.dev, bjorn3_gh@protonmail.com, lossin@kernel.org, a.hindborg@kernel.org, tmgross@umich.edu, dakr@kernel.org, tamird@nvidia.com, acourbot@nvidia.com, linux-kernel@vger.kernel.org, rust-for-linux@vger.kernel.org, Christopher Joshy Subject: [PATCH v2] rust: kernel: add SAFETY comments in aref doc example Date: Sun, 12 Jul 2026 21:00:27 +0530 Message-ID: <20260712153028.896-1-christopherjoshy4@gmail.com> X-Mailer: git-send-email 2.55.0.windows.2 In-Reply-To: <20260712123517.392-1-christopherjoshy4@gmail.com> References: <20260712123517.392-1-christopherjoshy4@gmail.com> Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Transfer-Encoding: 8bit From: Christopher Joshy Add the missing `// SAFETY` comments in the `ARef::into_raw` doc example, replacing the `TODO` placeholders from issue #351. For the `unsafe impl AlwaysRefCounted`, explain that `Empty` has no data and its `inc_ref`/`dec_ref` are no-ops, so the liveness contract is trivially satisfied. For the `ARef::from_raw` call, explain that `ptr` is derived from a valid reference (so it is valid) and that the required refcount increment is trivially owned because `Empty`'s `AlwaysRefCounted` manages no actual refcount. Link: https://github.com/Rust-for-Linux/linux/issues/351 Suggested-by: Miguel Ojeda Signed-off-by: Christopher Joshy --- rust/kernel/sync/aref.rs | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) diff --git a/rust/kernel/sync/aref.rs b/rust/kernel/sync/aref.rs index b721b2e00..5e8b8476b 100644 --- a/rust/kernel/sync/aref.rs +++ b/rust/kernel/sync/aref.rs @@ -124,7 +124,11 @@ pub unsafe fn from_raw(ptr: NonNull) -> Self { /// /// struct Empty {} /// - /// # // SAFETY: TODO. + /// // SAFETY: `Empty` has no data and its `inc_ref`/`dec_ref` are no-ops, so the + /// // `AlwaysRefCounted` contract holds: `inc_ref` need not keep anything alive (the + /// // zero-sized object lives on the stack while `data` is in scope) and `dec_ref` frees + /// // nothing. The caller ensures `data` outlives any `ARef` (here `data` is a + /// // local that outlives `data_ref`). /// unsafe impl AlwaysRefCounted for Empty { /// fn inc_ref(&self) {} /// unsafe fn dec_ref(_obj: NonNull) {} @@ -132,7 +136,10 @@ pub unsafe fn from_raw(ptr: NonNull) -> Self { /// /// let mut data = Empty {}; /// let ptr = NonNull::::new(&mut data).unwrap(); - /// # // SAFETY: TODO. + /// // SAFETY: `ptr` comes from a valid `&mut data` reference, hence it is non-null, + /// // aligned and points to a valid `Empty`. `ARef::from_raw` also requires owning a + /// // refcount increment; this is trivially met because `Empty`'s `AlwaysRefCounted` uses + /// // no-op `inc_ref`/`dec_ref` and so manages no actual refcount. /// let data_ref: ARef = unsafe { ARef::from_raw(ptr) }; /// let raw_ptr: NonNull = ARef::into_raw(data_ref); /// -- 2.43.0