Gh0st
/
linux
mirror of https://github.com/torvalds/linux.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

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: Alice Ryhl <aliceryhl@google.com>
Fixes: 8d9b095b8f ("samples: rust_misc_device: Provide an example C program to exercise functionality")
Reviewed-by: Benno Lossin <benno.lossin@proton.me>
Reviewed-by: Christian Schrefl <chrisi.schrefl@gmail.com>
Link: https://lore.kernel.org/r/20250313-rust_misc_device_tld-v1-1-a519bced9a6d@google.com
Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
This commit is contained in:
Alice Ryhl 2025-03-13 08:52:44 +00:00 committed by Greg Kroah-Hartman
parent 64612eb92d
commit a24b18aa4f
1 changed files with 91 additions and 90 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

181
samples/rust/rust_misc_device.rs
View File

@ -3,97 +3,98 @@
// Copyright (C) 2024 Google LLC. // Copyright (C) 2024 Google LLC.
//! Rust misc device sample. //! 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 core::pin::Pin;
use kernel::{ use kernel::{