Skip to content

Commit a24b18a

Browse files
Darksonngregkh
Darksonn
authored and
gregkh
committed
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: 8d9b095 ("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>
1 parent 64612eb commit a24b18a

File tree

1 file changed

+91
-90
lines changed

1 file changed

+91
-90
lines changed

‎samples/rust/rust_misc_device.rs‎

Lines changed: 91 additions & 90 deletions
Original file line numberDiff line numberDiff line change
@@ -3,97 +3,98 @@
33
// Copyright (C) 2024 Google LLC.
44

55
//! Rust misc device sample.
6+
//!
7+
//! Below is an example userspace C program that exercises this sample's functionality.
8+
//!
9+
//! ```c
10+
//! #include <stdio.h>
11+
//! #include <stdlib.h>
12+
//! #include <errno.h>
13+
//! #include <fcntl.h>
14+
//! #include <unistd.h>
15+
//! #include <sys/ioctl.h>
16+
//!
17+
//! #define RUST_MISC_DEV_FAIL _IO('|', 0)
18+
//! #define RUST_MISC_DEV_HELLO _IO('|', 0x80)
19+
//! #define RUST_MISC_DEV_GET_VALUE _IOR('|', 0x81, int)
20+
//! #define RUST_MISC_DEV_SET_VALUE _IOW('|', 0x82, int)
21+
//!
22+
//! int main() {
23+
//! int value, new_value;
24+
//! int fd, ret;
25+
//!
26+
//! // Open the device file
27+
//! printf("Opening /dev/rust-misc-device for reading and writing\n");
28+
//! fd = open("/dev/rust-misc-device", O_RDWR);
29+
//! if (fd < 0) {
30+
//! perror("open");
31+
//! return errno;
32+
//! }
33+
//!
34+
//! // Make call into driver to say "hello"
35+
//! printf("Calling Hello\n");
36+
//! ret = ioctl(fd, RUST_MISC_DEV_HELLO, NULL);
37+
//! if (ret < 0) {
38+
//! perror("ioctl: Failed to call into Hello");
39+
//! close(fd);
40+
//! return errno;
41+
//! }
42+
//!
43+
//! // Get initial value
44+
//! printf("Fetching initial value\n");
45+
//! ret = ioctl(fd, RUST_MISC_DEV_GET_VALUE, &value);
46+
//! if (ret < 0) {
47+
//! perror("ioctl: Failed to fetch the initial value");
48+
//! close(fd);
49+
//! return errno;
50+
//! }
51+
//!
52+
//! value++;
53+
//!
54+
//! // Set value to something different
55+
//! printf("Submitting new value (%d)\n", value);
56+
//! ret = ioctl(fd, RUST_MISC_DEV_SET_VALUE, &value);
57+
//! if (ret < 0) {
58+
//! perror("ioctl: Failed to submit new value");
59+
//! close(fd);
60+
//! return errno;
61+
//! }
62+
//!
63+
//! // Ensure new value was applied
64+
//! printf("Fetching new value\n");
65+
//! ret = ioctl(fd, RUST_MISC_DEV_GET_VALUE, &new_value);
66+
//! if (ret < 0) {
67+
//! perror("ioctl: Failed to fetch the new value");
68+
//! close(fd);
69+
//! return errno;
70+
//! }
71+
//!
72+
//! if (value != new_value) {
73+
//! printf("Failed: Committed and retrieved values are different (%d - %d)\n", value, new_value);
74+
//! close(fd);
75+
//! return -1;
76+
//! }
77+
//!
78+
//! // Call the unsuccessful ioctl
79+
//! printf("Attempting to call in to an non-existent IOCTL\n");
80+
//! ret = ioctl(fd, RUST_MISC_DEV_FAIL, NULL);
81+
//! if (ret < 0) {
82+
//! perror("ioctl: Succeeded to fail - this was expected");
83+
//! } else {
84+
//! printf("ioctl: Failed to fail\n");
85+
//! close(fd);
86+
//! return -1;
87+
//! }
88+
//!
89+
//! // Close the device file
90+
//! printf("Closing /dev/rust-misc-device\n");
91+
//! close(fd);
92+
//!
93+
//! printf("Success\n");
94+
//! return 0;
95+
//! }
96+
//! ```
697
7-
/// Below is an example userspace C program that exercises this sample's functionality.
8-
///
9-
/// ```c
10-
/// #include <stdio.h>
11-
/// #include <stdlib.h>
12-
/// #include <errno.h>
13-
/// #include <fcntl.h>
14-
/// #include <unistd.h>
15-
/// #include <sys/ioctl.h>
16-
///
17-
/// #define RUST_MISC_DEV_FAIL _IO('|', 0)
18-
/// #define RUST_MISC_DEV_HELLO _IO('|', 0x80)
19-
/// #define RUST_MISC_DEV_GET_VALUE _IOR('|', 0x81, int)
20-
/// #define RUST_MISC_DEV_SET_VALUE _IOW('|', 0x82, int)
21-
///
22-
/// int main() {
23-
/// int value, new_value;
24-
/// int fd, ret;
25-
///
26-
/// // Open the device file
27-
/// printf("Opening /dev/rust-misc-device for reading and writing\n");
28-
/// fd = open("/dev/rust-misc-device", O_RDWR);
29-
/// if (fd < 0) {
30-
/// perror("open");
31-
/// return errno;
32-
/// }
33-
///
34-
/// // Make call into driver to say "hello"
35-
/// printf("Calling Hello\n");
36-
/// ret = ioctl(fd, RUST_MISC_DEV_HELLO, NULL);
37-
/// if (ret < 0) {
38-
/// perror("ioctl: Failed to call into Hello");
39-
/// close(fd);
40-
/// return errno;
41-
/// }
42-
///
43-
/// // Get initial value
44-
/// printf("Fetching initial value\n");
45-
/// ret = ioctl(fd, RUST_MISC_DEV_GET_VALUE, &value);
46-
/// if (ret < 0) {
47-
/// perror("ioctl: Failed to fetch the initial value");
48-
/// close(fd);
49-
/// return errno;
50-
/// }
51-
///
52-
/// value++;
53-
///
54-
/// // Set value to something different
55-
/// printf("Submitting new value (%d)\n", value);
56-
/// ret = ioctl(fd, RUST_MISC_DEV_SET_VALUE, &value);
57-
/// if (ret < 0) {
58-
/// perror("ioctl: Failed to submit new value");
59-
/// close(fd);
60-
/// return errno;
61-
/// }
62-
///
63-
/// // Ensure new value was applied
64-
/// printf("Fetching new value\n");
65-
/// ret = ioctl(fd, RUST_MISC_DEV_GET_VALUE, &new_value);
66-
/// if (ret < 0) {
67-
/// perror("ioctl: Failed to fetch the new value");
68-
/// close(fd);
69-
/// return errno;
70-
/// }
71-
///
72-
/// if (value != new_value) {
73-
/// printf("Failed: Committed and retrieved values are different (%d - %d)\n", value, new_value);
74-
/// close(fd);
75-
/// return -1;
76-
/// }
77-
///
78-
/// // Call the unsuccessful ioctl
79-
/// printf("Attempting to call in to an non-existent IOCTL\n");
80-
/// ret = ioctl(fd, RUST_MISC_DEV_FAIL, NULL);
81-
/// if (ret < 0) {
82-
/// perror("ioctl: Succeeded to fail - this was expected");
83-
/// } else {
84-
/// printf("ioctl: Failed to fail\n");
85-
/// close(fd);
86-
/// return -1;
87-
/// }
88-
///
89-
/// // Close the device file
90-
/// printf("Closing /dev/rust-misc-device\n");
91-
/// close(fd);
92-
///
93-
/// printf("Success\n");
94-
/// return 0;
95-
/// }
96-
/// ```
9798
use core::pin::Pin;
9899

99100
use kernel::{

0 commit comments

Comments
 (0)