Commit a24b18aa authored by Alice Ryhl's avatar Alice Ryhl Committed by Greg Kroah-Hartman
Browse files

samples: rust_misc_device: fix markup in top-level docs 



The meaning of /// is to document the thing that comes after it, so
currently the example is documentation for the `use core::pin::Pin;`
statement. To write top-level docs (and have them rendered as such in
the html by rustdoc), use //! instead.

This does not change the contents of the docs at all. The only change is
changing /// to //!.

Signed-off-by: default avatarAlice Ryhl <aliceryhl@google.com>
Fixes: 8d9b095b ("samples: rust_misc_device: Provide an example C program to exercise functionality")
Reviewed-by: default avatarBenno Lossin <benno.lossin@proton.me>
Reviewed-by: default avatarChristian Schrefl <chrisi.schrefl@gmail.com>
Link: https://lore.kernel.org/r/20250313-rust_misc_device_tld-v1-1-a519bced9a6d@google.com


Signed-off-by: default avatarGreg Kroah-Hartman <gregkh@linuxfoundation.org>
parent 64612eb9

samples/rust/rust_misc_device.rs

+91 −90
Original line number Diff line number Diff line
@@ -3,97 +3,98 @@ 
// Copyright (C) 2024 Google LLC.



//! Rust misc device sample.

//!

//! Below is an example userspace C program that exercises this sample's functionality.

//!

//! ```c

//! #include <stdio.h>

//! #include <stdlib.h>

//! #include <errno.h>

//! #include <fcntl.h>

//! #include <unistd.h>

//! #include <sys/ioctl.h>

//!

//! #define RUST_MISC_DEV_FAIL _IO('|', 0)

//! #define RUST_MISC_DEV_HELLO _IO('|', 0x80)

//! #define RUST_MISC_DEV_GET_VALUE _IOR('|', 0x81, int)

//! #define RUST_MISC_DEV_SET_VALUE _IOW('|', 0x82, int)

//!

//! int main() {

//!   int value, new_value;

//!   int fd, ret;

//!

//!   // Open the device file

//!   printf("Opening /dev/rust-misc-device for reading and writing\n");

//!   fd = open("/dev/rust-misc-device", O_RDWR);

//!   if (fd < 0) {

//!     perror("open");

//!     return errno;

//!   }

//!

//!   // Make call into driver to say "hello"

//!   printf("Calling Hello\n");

//!   ret = ioctl(fd, RUST_MISC_DEV_HELLO, NULL);

//!   if (ret < 0) {

//!     perror("ioctl: Failed to call into Hello");

//!     close(fd);

//!     return errno;

//!   }

//!

//!   // Get initial value

//!   printf("Fetching initial value\n");

//!   ret = ioctl(fd, RUST_MISC_DEV_GET_VALUE, &value);

//!   if (ret < 0) {

//!     perror("ioctl: Failed to fetch the initial value");

//!     close(fd);

//!     return errno;

//!   }

//!

//!   value++;

//!

//!   // Set value to something different

//!   printf("Submitting new value (%d)\n", value);

//!   ret = ioctl(fd, RUST_MISC_DEV_SET_VALUE, &value);

//!   if (ret < 0) {

//!     perror("ioctl: Failed to submit new value");

//!     close(fd);

//!     return errno;

//!   }

//!

//!   // Ensure new value was applied

//!   printf("Fetching new value\n");

//!   ret = ioctl(fd, RUST_MISC_DEV_GET_VALUE, &new_value);

//!   if (ret < 0) {

//!     perror("ioctl: Failed to fetch the new value");

//!     close(fd);

//!     return errno;

//!   }

//!

//!   if (value != new_value) {

//!     printf("Failed: Committed and retrieved values are different (%d - %d)\n", value, new_value);

//!     close(fd);

//!     return -1;

//!   }

//!

//!   // Call the unsuccessful ioctl

//!   printf("Attempting to call in to an non-existent IOCTL\n");

//!   ret = ioctl(fd, RUST_MISC_DEV_FAIL, NULL);

//!   if (ret < 0) {

//!     perror("ioctl: Succeeded to fail - this was expected");

//!   } else {

//!     printf("ioctl: Failed to fail\n");

//!     close(fd);

//!     return -1;

//!   }

//!

//!   // Close the device file

//!   printf("Closing /dev/rust-misc-device\n");

//!   close(fd);

//!

//!   printf("Success\n");

//!   return 0;

//! }

//! ```



/// Below is an example userspace C program that exercises this sample's functionality.

///

/// ```c

/// #include <stdio.h>

/// #include <stdlib.h>

/// #include <errno.h>

/// #include <fcntl.h>

/// #include <unistd.h>

/// #include <sys/ioctl.h>

///

/// #define RUST_MISC_DEV_FAIL _IO('|', 0)

/// #define RUST_MISC_DEV_HELLO _IO('|', 0x80)

/// #define RUST_MISC_DEV_GET_VALUE _IOR('|', 0x81, int)

/// #define RUST_MISC_DEV_SET_VALUE _IOW('|', 0x82, int)

///

/// int main() {

///   int value, new_value;

///   int fd, ret;

///

///   // Open the device file

///   printf("Opening /dev/rust-misc-device for reading and writing\n");

///   fd = open("/dev/rust-misc-device", O_RDWR);

///   if (fd < 0) {

///     perror("open");

///     return errno;

///   }

///

///   // Make call into driver to say "hello"

///   printf("Calling Hello\n");

///   ret = ioctl(fd, RUST_MISC_DEV_HELLO, NULL);

///   if (ret < 0) {

///     perror("ioctl: Failed to call into Hello");

///     close(fd);

///     return errno;

///   }

///

///   // Get initial value

///   printf("Fetching initial value\n");

///   ret = ioctl(fd, RUST_MISC_DEV_GET_VALUE, &value);

///   if (ret < 0) {

///     perror("ioctl: Failed to fetch the initial value");

///     close(fd);

///     return errno;

///   }

///

///   value++;

///

///   // Set value to something different

///   printf("Submitting new value (%d)\n", value);

///   ret = ioctl(fd, RUST_MISC_DEV_SET_VALUE, &value);

///   if (ret < 0) {

///     perror("ioctl: Failed to submit new value");

///     close(fd);

///     return errno;

///   }

///

///   // Ensure new value was applied

///   printf("Fetching new value\n");

///   ret = ioctl(fd, RUST_MISC_DEV_GET_VALUE, &new_value);

///   if (ret < 0) {

///     perror("ioctl: Failed to fetch the new value");

///     close(fd);

///     return errno;

///   }

///

///   if (value != new_value) {

///     printf("Failed: Committed and retrieved values are different (%d - %d)\n", value, new_value);

///     close(fd);

///     return -1;

///   }

///

///   // Call the unsuccessful ioctl

///   printf("Attempting to call in to an non-existent IOCTL\n");

///   ret = ioctl(fd, RUST_MISC_DEV_FAIL, NULL);

///   if (ret < 0) {

///     perror("ioctl: Succeeded to fail - this was expected");

///   } else {

///     printf("ioctl: Failed to fail\n");

///     close(fd);

///     return -1;

///   }

///

///   // Close the device file

///   printf("Closing /dev/rust-misc-device\n");

///   close(fd);

///

///   printf("Success\n");

///   return 0;

/// }

/// ```

use core::pin::Pin;



use kernel::{