Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
1// SPDX-License-Identifier: GPL-2.0
2
3// Copyright (C) 2024 Google LLC.
4
5//! 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//! ```
97
98use kernel::{
99 device::Device,
100 fs::{File, Kiocb},
101 ioctl::{_IO, _IOC_SIZE, _IOR, _IOW},
102 iov::{IovIterDest, IovIterSource},
103 miscdevice::{MiscDevice, MiscDeviceOptions, MiscDeviceRegistration},
104 new_mutex,
105 prelude::*,
106 sync::{aref::ARef, Mutex},
107 uaccess::{UserSlice, UserSliceReader, UserSliceWriter},
108};
109
110const RUST_MISC_DEV_HELLO: u32 = _IO('|' as u32, 0x80);
111const RUST_MISC_DEV_GET_VALUE: u32 = _IOR::<i32>('|' as u32, 0x81);
112const RUST_MISC_DEV_SET_VALUE: u32 = _IOW::<i32>('|' as u32, 0x82);
113
114module! {
115 type: RustMiscDeviceModule,
116 name: "rust_misc_device",
117 authors: ["Lee Jones"],
118 description: "Rust misc device sample",
119 license: "GPL",
120}
121
122#[pin_data]
123struct RustMiscDeviceModule {
124 #[pin]
125 _miscdev: MiscDeviceRegistration<RustMiscDevice>,
126}
127
128impl kernel::InPlaceModule for RustMiscDeviceModule {
129 fn init(_module: &'static ThisModule) -> impl PinInit<Self, Error> {
130 pr_info!("Initialising Rust Misc Device Sample\n");
131
132 let options = MiscDeviceOptions {
133 name: c"rust-misc-device",
134 };
135
136 try_pin_init!(Self {
137 _miscdev <- MiscDeviceRegistration::register(options),
138 })
139 }
140}
141
142struct Inner {
143 value: i32,
144 buffer: KVVec<u8>,
145}
146
147#[pin_data(PinnedDrop)]
148struct RustMiscDevice {
149 #[pin]
150 inner: Mutex<Inner>,
151 dev: ARef<Device>,
152}
153
154#[vtable]
155impl MiscDevice for RustMiscDevice {
156 type Ptr = Pin<KBox<Self>>;
157
158 fn open(_file: &File, misc: &MiscDeviceRegistration<Self>) -> Result<Pin<KBox<Self>>> {
159 let dev = ARef::from(misc.device());
160
161 dev_info!(dev, "Opening Rust Misc Device Sample\n");
162
163 KBox::try_pin_init(
164 try_pin_init! {
165 RustMiscDevice {
166 inner <- new_mutex!(Inner {
167 value: 0_i32,
168 buffer: KVVec::new(),
169 }),
170 dev: dev,
171 }
172 },
173 GFP_KERNEL,
174 )
175 }
176
177 fn read_iter(mut kiocb: Kiocb<'_, Self::Ptr>, iov: &mut IovIterDest<'_>) -> Result<usize> {
178 let me = kiocb.file();
179 dev_info!(me.dev, "Reading from Rust Misc Device Sample\n");
180
181 let inner = me.inner.lock();
182 // Read the buffer contents, taking the file position into account.
183 let read = iov.simple_read_from_buffer(kiocb.ki_pos_mut(), &inner.buffer)?;
184
185 Ok(read)
186 }
187
188 fn write_iter(mut kiocb: Kiocb<'_, Self::Ptr>, iov: &mut IovIterSource<'_>) -> Result<usize> {
189 let me = kiocb.file();
190 dev_info!(me.dev, "Writing to Rust Misc Device Sample\n");
191
192 let mut inner = me.inner.lock();
193
194 // Replace buffer contents.
195 inner.buffer.clear();
196 let len = iov.copy_from_iter_vec(&mut inner.buffer, GFP_KERNEL)?;
197
198 // Set position to zero so that future `read` calls will see the new contents.
199 *kiocb.ki_pos_mut() = 0;
200
201 Ok(len)
202 }
203
204 fn ioctl(me: Pin<&RustMiscDevice>, _file: &File, cmd: u32, arg: usize) -> Result<isize> {
205 dev_info!(me.dev, "IOCTLing Rust Misc Device Sample\n");
206
207 // Treat the ioctl argument as a user pointer.
208 let arg = UserPtr::from_addr(arg);
209 let size = _IOC_SIZE(cmd);
210
211 match cmd {
212 RUST_MISC_DEV_GET_VALUE => me.get_value(UserSlice::new(arg, size).writer())?,
213 RUST_MISC_DEV_SET_VALUE => me.set_value(UserSlice::new(arg, size).reader())?,
214 RUST_MISC_DEV_HELLO => me.hello()?,
215 _ => {
216 dev_err!(me.dev, "-> IOCTL not recognised: {}\n", cmd);
217 return Err(ENOTTY);
218 }
219 };
220
221 Ok(0)
222 }
223}
224
225#[pinned_drop]
226impl PinnedDrop for RustMiscDevice {
227 fn drop(self: Pin<&mut Self>) {
228 dev_info!(self.dev, "Exiting the Rust Misc Device Sample\n");
229 }
230}
231
232impl RustMiscDevice {
233 fn set_value(&self, mut reader: UserSliceReader) -> Result<isize> {
234 let new_value = reader.read::<i32>()?;
235 let mut guard = self.inner.lock();
236
237 dev_info!(
238 self.dev,
239 "-> Copying data from userspace (value: {})\n",
240 new_value
241 );
242
243 guard.value = new_value;
244 Ok(0)
245 }
246
247 fn get_value(&self, mut writer: UserSliceWriter) -> Result<isize> {
248 let guard = self.inner.lock();
249 let value = guard.value;
250
251 // Free-up the lock and use our locally cached instance from here
252 drop(guard);
253
254 dev_info!(
255 self.dev,
256 "-> Copying data to userspace (value: {})\n",
257 &value
258 );
259
260 writer.write::<i32>(&value)?;
261 Ok(0)
262 }
263
264 fn hello(&self) -> Result<isize> {
265 dev_info!(self.dev, "-> Hello from the Rust Misc Device\n");
266
267 Ok(0)
268 }
269}