Skip to content

Commit 1b9b7cb

Browse files
committed
treewide: update/normalize comment style
Includes: capitalization, end of sentence/title periods, list marker and list indentation. Also included a fix for a spurious space and missing code quotes. No change in content intended otherwise. `alloc` is excluded since we try not to diverge from upstream. Signed-off-by: Miguel Ojeda <ojeda@kernel.org>
1 parent b5d158b commit 1b9b7cb

21 files changed

+58
-58
lines changed

Documentation/rust/coding-guidelines.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -72,7 +72,7 @@ This is how a well-documented Rust function may look like::
7272
match self {
7373
Some(val) => val,
7474

75-
// SAFETY: the safety contract must be upheld by the caller.
75+
// SAFETY: The safety contract must be upheld by the caller.
7676
None => unsafe { hint::unreachable_unchecked() },
7777
}
7878
}

rust/kernel/bindings.rs

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
// SPDX-License-Identifier: GPL-2.0
22

3-
//! Bindings
3+
//! Bindings.
44
//!
55
//! Imports the generated bindings by `bindgen`.
66

rust/kernel/chrdev.rs

Lines changed: 13 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -23,9 +23,9 @@ use crate::str::CStr;
2323
///
2424
/// # Invariants
2525
///
26-
/// - [`self.0`] is valid and non-null.
27-
/// - [`(*self.0).ops`] is valid, non-null and has static lifetime.
28-
/// - [`(*self.0).owner`] is valid and, if non-null, has module lifetime.
26+
/// - [`self.0`] is valid and non-null.
27+
/// - [`(*self.0).ops`] is valid, non-null and has static lifetime.
28+
/// - [`(*self.0).owner`] is valid and, if non-null, has module lifetime.
2929
struct Cdev(*mut bindings::cdev);
3030

3131
impl Cdev {
@@ -45,20 +45,20 @@ impl Cdev {
4545
(*cdev).owner = module.0;
4646
}
4747
// INVARIANTS:
48-
// - [`self.0`] is valid and non-null.
49-
// - [`(*self.0).ops`] is valid, non-null and has static lifetime,
50-
// because it was coerced from a reference with static lifetime.
51-
// - [`(*self.0).owner`] is valid and, if non-null, has module lifetime,
52-
// guaranteed by the [`ThisModule`] invariant.
48+
// - [`self.0`] is valid and non-null.
49+
// - [`(*self.0).ops`] is valid, non-null and has static lifetime,
50+
// because it was coerced from a reference with static lifetime.
51+
// - [`(*self.0).owner`] is valid and, if non-null, has module lifetime,
52+
// guaranteed by the [`ThisModule`] invariant.
5353
Ok(Self(cdev))
5454
}
5555

5656
fn add(&mut self, dev: bindings::dev_t, count: c_types::c_uint) -> Result {
57-
// SAFETY: according to the type invariants:
58-
// - [`self.0`] can be safely passed to [`bindings::cdev_add`].
59-
// - [`(*self.0).ops`] will live at least as long as [`self.0`].
60-
// - [`(*self.0).owner`] will live at least as long as the
61-
// module, which is an implicit requirement.
57+
// SAFETY: According to the type invariants:
58+
// - [`self.0`] can be safely passed to [`bindings::cdev_add`].
59+
// - [`(*self.0).ops`] will live at least as long as [`self.0`].
60+
// - [`(*self.0).owner`] will live at least as long as the
61+
// module, which is an implicit requirement.
6262
let rc = unsafe { bindings::cdev_add(self.0, dev, count) };
6363
if rc != 0 {
6464
return Err(Error::from_kernel_errno(rc));

rust/kernel/clk.rs

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -26,23 +26,23 @@ impl Clk {
2626

2727
/// Returns value of the rate field of `struct clk`.
2828
pub fn get_rate(&self) -> usize {
29-
// SAFETY: the pointer is valid by the type invariant.
29+
// SAFETY: The pointer is valid by the type invariant.
3030
unsafe { bindings::clk_get_rate(self.0) as usize }
3131
}
3232

3333
/// Prepares and enables the underlying hardware clock.
3434
///
3535
/// This function should not be called in atomic context.
3636
pub fn prepare_enable(self) -> Result<EnabledClk> {
37-
// SAFETY: the pointer is valid by the type invariant.
37+
// SAFETY: The pointer is valid by the type invariant.
3838
to_result(|| unsafe { bindings::clk_prepare_enable(self.0) })?;
3939
Ok(EnabledClk(self))
4040
}
4141
}
4242

4343
impl Drop for Clk {
4444
fn drop(&mut self) {
45-
// SAFETY: the pointer is valid by the type invariant.
45+
// SAFETY: The pointer is valid by the type invariant.
4646
unsafe { bindings::clk_put(self.0) };
4747
}
4848
}
@@ -61,15 +61,15 @@ impl EnabledClk {
6161
/// This function should not be called in atomic context.
6262
pub fn disable_unprepare(self) -> Clk {
6363
let mut clk = ManuallyDrop::new(self);
64-
// SAFETY: the pointer is valid by the type invariant.
64+
// SAFETY: The pointer is valid by the type invariant.
6565
unsafe { bindings::clk_disable_unprepare(clk.0 .0) };
6666
core::mem::replace(&mut clk.0, Clk(core::ptr::null_mut()))
6767
}
6868
}
6969

7070
impl Drop for EnabledClk {
7171
fn drop(&mut self) {
72-
// SAFETY: the pointer is valid by the type invariant.
72+
// SAFETY: The pointer is valid by the type invariant.
7373
unsafe { bindings::clk_disable_unprepare(self.0 .0) };
7474
}
7575
}

rust/kernel/device.rs

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -61,11 +61,11 @@ pub unsafe trait RawDevice {
6161
None => core::ptr::null(),
6262
};
6363

64-
// SAFETY: id_ptr is optional and may be either a valid pointer
64+
// SAFETY: `id_ptr` is optional and may be either a valid pointer
6565
// from the type invariant or NULL otherwise.
6666
let clk_ptr = unsafe { from_kernel_err_ptr(bindings::clk_get(self.raw_device(), id_ptr)) }?;
6767

68-
// SAFETY: clock is initialized with valid pointer returned from `bindings::clk_get` call.
68+
// SAFETY: Clock is initialized with valid pointer returned from `bindings::clk_get` call.
6969
unsafe { Ok(Clk::new(clk_ptr)) }
7070
}
7171

@@ -222,10 +222,10 @@ impl Drop for Device {
222222
/// some device state must be freed and not used anymore, while others must remain accessible.
223223
///
224224
/// This struct separates the device data into three categories:
225-
/// 1. Registrations: are destroyed when the device is removed, but before the io resources
226-
/// become inaccessible.
227-
/// 2. Io resources: are available until the device is removed.
228-
/// 3. General data: remain available as long as the ref count is nonzero.
225+
/// 1. Registrations: are destroyed when the device is removed, but before the io resources
226+
/// become inaccessible.
227+
/// 2. Io resources: are available until the device is removed.
228+
/// 3. General data: remain available as long as the ref count is nonzero.
229229
///
230230
/// This struct implements the `DeviceRemoval` trait so that it can clean resources up even if not
231231
/// explicitly called by the device drivers.

rust/kernel/driver.rs

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -116,8 +116,8 @@ impl<T: DriverOps> Drop for Registration<T> {
116116
/// # Safety
117117
///
118118
/// Implementers must ensure that:
119-
/// * [`RawDeviceId::ZERO`] is actually a zeroed-out version of the raw device id.
120-
/// * [`RawDeviceId::to_rawid`] stores `offset` in the context/data field of the raw device id so
119+
/// - [`RawDeviceId::ZERO`] is actually a zeroed-out version of the raw device id.
120+
/// - [`RawDeviceId::to_rawid`] stores `offset` in the context/data field of the raw device id so
121121
/// that buses can recover the pointer to the data.
122122
pub unsafe trait RawDeviceId {
123123
/// The raw type that holds the device id.

rust/kernel/error.rs

Lines changed: 9 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -324,15 +324,15 @@ impl Error {
324324
/// be returned in such a case.
325325
pub(crate) fn from_kernel_errno(errno: c_types::c_int) -> Error {
326326
if errno < -(bindings::MAX_ERRNO as i32) || errno >= 0 {
327-
// TODO: make it a `WARN_ONCE` once available.
327+
// TODO: Make it a `WARN_ONCE` once available.
328328
crate::pr_warn!(
329329
"attempted to create `Error` with out of range `errno`: {}",
330330
errno
331331
);
332332
return Error::EINVAL;
333333
}
334334

335-
// INVARIANT: the check above ensures the type invariant
335+
// INVARIANT: The check above ensures the type invariant
336336
// will hold.
337337
Error(errno)
338338
}
@@ -343,7 +343,7 @@ impl Error {
343343
///
344344
/// `errno` must be within error code range (i.e. `>= -MAX_ERRNO && < 0`).
345345
pub(crate) unsafe fn from_kernel_errno_unchecked(errno: c_types::c_int) -> Error {
346-
// INVARIANT: the contract ensures the type invariant
346+
// INVARIANT: The contract ensures the type invariant
347347
// will hold.
348348
Error(errno)
349349
}
@@ -507,24 +507,24 @@ pub(crate) use from_kernel_result;
507507
/// }
508508
/// }
509509
/// ```
510-
// TODO: remove `dead_code` marker once an in-kernel client is available.
510+
// TODO: Remove `dead_code` marker once an in-kernel client is available.
511511
#[allow(dead_code)]
512512
pub(crate) fn from_kernel_err_ptr<T>(ptr: *mut T) -> Result<*mut T> {
513-
// CAST: casting a pointer to `*const c_types::c_void` is always valid.
513+
// CAST: Casting a pointer to `*const c_types::c_void` is always valid.
514514
let const_ptr: *const c_types::c_void = ptr.cast();
515-
// SAFETY: the FFI function does not deref the pointer.
515+
// SAFETY: The FFI function does not deref the pointer.
516516
if unsafe { bindings::IS_ERR(const_ptr) } {
517-
// SAFETY: the FFI function does not deref the pointer.
517+
// SAFETY: The FFI function does not deref the pointer.
518518
let err = unsafe { bindings::PTR_ERR(const_ptr) };
519-
// CAST: if `IS_ERR()` returns `true`,
519+
// CAST: If `IS_ERR()` returns `true`,
520520
// then `PTR_ERR()` is guaranteed to return a
521521
// negative value greater-or-equal to `-bindings::MAX_ERRNO`,
522522
// which always fits in an `i16`, as per the invariant above.
523523
// And an `i16` always fits in an `i32`. So casting `err` to
524524
// an `i32` can never overflow, and is always valid.
525525
//
526526
// SAFETY: `IS_ERR()` ensures `err` is a
527-
// negative value greater-or-equal to `-bindings::MAX_ERRNO`
527+
// negative value greater-or-equal to `-bindings::MAX_ERRNO`.
528528
return Err(unsafe { Error::from_kernel_errno_unchecked(err as i32) });
529529
}
530530
Ok(ptr)

rust/kernel/file_operations.rs

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -711,7 +711,7 @@ pub trait FileOperations {
711711
/// Maps areas of the caller's virtual memory with device/file memory.
712712
///
713713
/// Corresponds to the `mmap` function pointer in `struct file_operations`.
714-
/// TODO: wrap `vm_area_struct` so that we don't have to expose it.
714+
/// TODO: Wrap `vm_area_struct` so that we don't have to expose it.
715715
fn mmap(
716716
_this: <Self::Wrapper as PointerWrapper>::Borrowed<'_>,
717717
_file: &File,

rust/kernel/miscdev.rs

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -194,7 +194,7 @@ impl<T: FileOperations> FileOpenAdapter<T::OpenData> for Registration<T> {
194194
_inode: *mut bindings::inode,
195195
file: *mut bindings::file,
196196
) -> *const T::OpenData {
197-
// SAFETY: the caller must guarantee that `file` is valid.
197+
// SAFETY: The caller must guarantee that `file` is valid.
198198
let reg = crate::container_of!(unsafe { (*file).private_data }, Self, mdev);
199199

200200
// SAFETY: This function is only called while the misc device is still registered, so the

rust/kernel/rbtree.rs

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -322,7 +322,7 @@ impl<K, V> RBTree<K, V> {
322322
where
323323
K: Ord,
324324
{
325-
// SAFETY: the `find` return value is a node in the tree, so it is valid.
325+
// SAFETY: The `find` return value is a node in the tree, so it is valid.
326326
self.find(key)
327327
.map(|mut node| unsafe { &mut node.as_mut().value })
328328
}
@@ -336,13 +336,13 @@ impl<K, V> RBTree<K, V> {
336336
{
337337
let mut node = self.find(key)?;
338338

339-
// SAFETY: the `find` return value is a node in the tree, so it is valid.
339+
// SAFETY: The `find` return value is a node in the tree, so it is valid.
340340
unsafe { bindings::rb_erase(&mut node.as_mut().links, &mut self.root) };
341341

342342
// INVARIANT: The node is being returned and the caller may free it, however, it was
343343
// removed from the tree. So the invariants still hold.
344344
Some(RBTreeNode {
345-
// SAFETY: the `find` return value was a node in the tree, so it is valid.
345+
// SAFETY: The `find` return value was a node in the tree, so it is valid.
346346
node: unsafe { Box::from_raw(node.as_ptr()) },
347347
})
348348
}

0 commit comments

Comments
 (0)