kernel/device/
manager.rs

1//! # Device Manager Module
2//!
3//! This module provides functionality for managing hardware devices in the kernel.
4//!
5//! ## Overview
6//!
7//! The device manager is responsible for:
8//! - Registering and managing serial devices
9//! - Tracking available device drivers
10//! - Device discovery and initialization
11//! - Managing device information
12//!
13//! ## Key Components
14//!
15//! - `BasicDeviceManager`: Manages fundamental I/O devices like serial ports
16//! - `DeviceManager`: The main device management system that handles all devices and drivers
17//!
18//! ## Device Discovery
19//!
20//! Devices are discovered through the Flattened Device Tree (FDT). The manager:
21//! 1. Parses the device tree
22//! 2. Matches compatible devices with registered drivers
23//! 3. Probes devices with appropriate drivers
24//!
25//! ## Usage
26//!
27//! The device manager is implemented as a global singleton that can be accessed via:
28//! - `DeviceManager::get_manager()` - Immutable access
29//! - `DeviceManager::get_mut_manager()` - Mutable access
30//!
31//! ### Example: Registering a serial device
32//!
33//! ```
34//! use crate::device::manager::register_serial;
35//! 
36//! // Create a new serial device
37//! let my_serial = Box::new(MySerialImplementation::new());
38//! 
39//! // Register with the device manager
40//! register_serial(my_serial);
41//! ```
42
43extern crate alloc;
44
45use alloc::collections::btree_map::BTreeMap;
46use alloc::sync::Arc;
47use alloc::vec::Vec;
48use alloc::boxed::Box;
49use spin::mutex::Mutex;
50use spin::rwlock::RwLock;
51
52use crate::device::platform::resource::PlatformDeviceResource;
53use crate::device::platform::resource::PlatformDeviceResourceType;
54use crate::device::platform::PlatformDeviceInfo;
55use crate::println;
56
57use crate::traits::serial::Serial;
58
59use super::fdt::FdtManager;
60use super::Device;
61use super::DeviceDriver;
62use super::DeviceInfo;
63use super::DeviceType;
64
65/// BasicDeviceManager
66///
67/// This struct manages basic I/O devices, such as serial ports.
68/// It provides methods to register, borrow, and manage serial devices.
69/// It is a part of the DeviceManager, which handles all devices and drivers.
70///
71/// # Fields
72/// - `serials`: A vector of serial devices managed by this manager.
73/// 
74pub struct BasicDeviceManager {
75    /* Basic I/O */
76    serials: Vec<Box<dyn Serial>>,
77}
78
79impl BasicDeviceManager {
80    pub fn register_serial(&mut self, serial: Box<dyn Serial>) {
81        self.serials.push(serial);
82        println!("Registered serial device");
83    }
84
85    pub fn register_serials(&mut self, serias: Vec<Box<dyn Serial>>) {
86        let len = serias.len();
87        for serial in serias {
88            self.serials.push(serial);
89        }
90        println!("Registered serial devices: {}", len);
91    }
92
93    pub fn borrow_serial(&self, idx: usize) -> Option<&Box<dyn Serial>> {
94        self.serials.get(idx)
95    }
96
97    pub fn borrow_mut_serial(&mut self, idx: usize) -> Option<&mut Box<dyn Serial>> {
98        self.serials.get_mut(idx)
99    }
100
101    pub fn borrow_serials(&self) -> &Vec<Box<dyn Serial>> {
102        &self.serials
103    }
104
105    pub fn borrow_mut_serials(&mut self) -> &mut Vec<Box<dyn Serial>> {
106        &mut self.serials
107    }
108}
109
110#[derive(Debug, PartialEq, Eq, Hash, Clone, Copy)]
111pub enum DeviceState {
112    Available,
113    InUse,
114    InUseExclusive,
115}
116
117pub struct DeviceHandle {
118    device: Arc<RwLock<Box<dyn Device>>>,
119    state: RwLock<DeviceState>,
120    borrow_count: RwLock<usize>,
121}
122
123impl DeviceHandle {
124    pub fn new(device: Arc<RwLock<Box<dyn Device>>>) -> Self {
125        Self {
126            device,
127            state: RwLock::new(DeviceState::Available),
128            borrow_count: RwLock::new(0),
129        }
130    }
131
132    pub fn is_in_use(&self) -> bool {
133        *self.state.read() == DeviceState::InUse || *self.state.read() == DeviceState::InUseExclusive
134    }
135
136    pub fn is_in_use_exclusive(&self) -> bool {
137        *self.state.read() == DeviceState::InUseExclusive
138    }
139
140    fn set_in_use(&self) {
141        let mut state = self.state.write();
142        *state = DeviceState::InUse;
143    }
144
145    fn set_available(&self) {
146        let mut state = self.state.write();
147        *state = DeviceState::Available;
148    }
149
150    fn set_in_use_exclusive(&self) {
151        let mut state = self.state.write();
152        *state = DeviceState::InUseExclusive;
153    }
154
155    fn increment_borrow_count(&self) {
156        let mut count = self.borrow_count.write();
157        *count += 1;
158    }
159
160    fn decrement_borrow_count(&self) {
161        let mut count = self.borrow_count.write();
162        if *count > 0 {
163            *count -= 1;
164        }
165    }
166
167    pub fn get_borrow_count(&self) -> usize {
168        *self.borrow_count.read()
169    }
170}
171
172pub type BorrowedDevice = Arc<RwLock<Box<dyn Device>>>;
173
174pub struct BorrowedDeviceGuard {
175    handle: Arc<DeviceHandle>,
176}
177
178impl BorrowedDeviceGuard {
179    pub fn new(handle: Arc<DeviceHandle>) -> Self {
180        Self { handle }
181    }
182}
183
184impl BorrowedDeviceGuard {
185    pub fn device(&self) -> BorrowedDevice {
186        Arc::clone(&self.handle.device)
187    }
188}
189
190impl Drop for BorrowedDeviceGuard {
191    fn drop(&mut self) {
192        self.handle.decrement_borrow_count();
193        if self.handle.get_borrow_count() == 0 {
194            if self.handle.is_in_use_exclusive() {
195                self.handle.set_available();
196            } else {
197                self.handle.set_available();
198            }
199        }
200    }
201}
202
203static mut MANAGER: DeviceManager = DeviceManager::new();
204
205/// DeviceManager
206/// 
207/// This struct is the main device management system.
208/// It handles all devices and drivers, including basic I/O devices.
209/// It provides methods to register devices, populate devices from the FDT,
210/// and manage device drivers.
211/// 
212/// # Fields
213/// - `basic`: An instance of `BasicDeviceManager` for managing basic I/O devices.
214/// - `devices`: A mutex-protected vector of all registered devices.
215/// - `drivers`: A mutex-protected vector of all registered device drivers.
216pub struct DeviceManager {
217    /* Manager for basic devices */
218    pub basic: BasicDeviceManager,
219    /* Other devices */
220    devices: Mutex<Vec<Arc<DeviceHandle>>>,
221    /* Device drivers */
222    drivers: Mutex<Vec<Box<dyn DeviceDriver>>>,
223}
224
225impl DeviceManager {
226    const fn new() -> Self {
227        DeviceManager {
228            basic: BasicDeviceManager {
229                serials: Vec::new(),
230            },
231            devices: Mutex::new(Vec::new()),
232            drivers: Mutex::new(Vec::new()),
233        }
234    }
235
236    #[allow(static_mut_refs)]
237    pub fn get_manager() -> &'static DeviceManager {
238        unsafe { &MANAGER }
239    }
240
241    #[allow(static_mut_refs)]
242    pub fn get_mut_manager() -> &'static mut DeviceManager {
243        unsafe { &mut MANAGER }
244    }
245
246    /// Register a device with the manager
247    /// 
248    /// # Arguments
249    /// * `device`: The device to register.
250    /// 
251    /// # Returns
252    ///  * The id of the registered device.
253    /// 
254    /// # Example
255    /// 
256    /// ```rust
257    /// let device = Box::new(MyDevice::new());
258    /// let id = DeviceManager::get_mut_manager().register_device(device);
259    /// ```
260    /// 
261    pub fn register_device(&self, device: Box<dyn Device>) -> usize {
262        let mut devices = self.devices.lock();
263        let device = Arc::new(RwLock::new(device));
264        let handle = DeviceHandle::new(device).into();
265        let id = devices.len();
266        devices.push(handle);
267        id
268    }
269
270    /// Borrow a device by type and index
271    /// 
272    /// # Arguments
273    /// 
274    /// * `id`: The id of the device to borrow.
275    /// 
276    /// # Returns
277    /// 
278    /// A result containing a reference to the borrowed device, or an error if the device type is not found or the index is out of bounds.
279    /// 
280    pub fn borrow_device(&self, id: usize) -> Result<BorrowedDeviceGuard, &'static str> {
281        let devices = self.devices.lock();    
282        if id < devices.len() {
283            let device = &devices[id];
284            if device.is_in_use_exclusive() {
285                return Err("Device is already in use exclusively");
286            }
287            device.increment_borrow_count(); // Increment borrow count
288            device.set_in_use(); // Mark the device as in use
289            return Ok(BorrowedDeviceGuard::new(Arc::clone(device)));
290        } else {
291            return Err("Index out of bounds");
292        }
293    }
294
295    /// Borrow an exclusive device by type and index
296    /// 
297    /// # Arguments
298    /// 
299    /// * `id`: The id of the device to borrow.
300    /// 
301    /// # Returns
302    /// 
303    /// A result containing a reference to the borrowed device, or an error if the device type is not found or the index is out of bounds.
304    /// 
305    pub fn borrow_exclusive_device(&self, id: usize) -> Result<BorrowedDeviceGuard, &'static str> {
306    let devices = self.devices.lock();
307        if id < devices.len() {
308            let handle = &devices[id];
309            if handle.is_in_use() {
310                return Err("Device is already in use");
311            }
312            handle.increment_borrow_count(); // Increment borrow count
313            handle.set_in_use_exclusive(); // Mark the device as in use
314            return Ok(BorrowedDeviceGuard::new(Arc::clone(handle)));
315        } else {
316            return Err("Index out of bounds");
317        }
318    }
319
320
321
322
323    /// Get the number of devices of a specific type
324    /// 
325    /// # Returns
326    /// 
327    /// The number of devices of the specified type.
328    /// 
329    pub fn get_devices_count(&self) -> usize {
330        let devices = self.devices.lock();
331        devices.len()
332    }
333
334    pub fn borrow_drivers(&self) -> &Mutex<Vec<Box<dyn DeviceDriver>>> {
335        &self.drivers
336    }
337
338    /// Populates devices from the FDT (Flattened Device Tree).
339    /// 
340    /// This function searches for the `/soc` node in the FDT and iterates through its children.
341    /// For each child node, it checks if there is a compatible driver registered.
342    /// If a matching driver is found, it probes the device using the driver's `probe` method.
343    /// If the probe is successful, the device is registered with the driver.
344    pub fn populate_devices(&mut self) {
345        let fdt_manager = unsafe { FdtManager::get_mut_manager() };
346        let fdt = fdt_manager.get_fdt();
347        if fdt.is_none() {
348            println!("FDT not initialized");
349            return;
350        }
351        let fdt = fdt.unwrap();
352        println!("Populating devices from FDT...");
353
354        let soc = fdt.find_node("/soc");
355        if soc.is_none() {
356            println!("No /soc node found");
357            return;
358        }
359
360        let soc = soc.unwrap();
361        let mut idx = 0;
362        for child in soc.children() {
363            let compatible = child.compatible();
364            if compatible.is_none() {
365                continue;
366            }
367            let compatible = compatible.unwrap().all().collect::<Vec<_>>();
368            
369            for driver in self.drivers.lock().iter() {
370                if driver.match_table().iter().any(|&c| compatible.contains(&c)) {
371                    let mut resources = Vec::new();
372                    
373                    // Memory regions
374                    if let Some(regions) = child.reg() {
375                        for region in regions {
376                            let res = PlatformDeviceResource {
377                                res_type: PlatformDeviceResourceType::MEM,
378                                start: region.starting_address as usize,
379                                end: region.starting_address as usize + region.size.unwrap() - 1,
380                            };
381                            resources.push(res);
382                        }
383                    }
384
385                    // IRQs
386                    if let Some(irqs) = child.interrupts() {
387                        for irq in irqs {
388                            let res = PlatformDeviceResource {
389                                res_type: PlatformDeviceResourceType::IRQ,
390                                start: irq,
391                                end: irq,
392                            };
393                            resources.push(res);
394                        }
395                    }
396
397                    let device: Box<dyn DeviceInfo> = Box::new(PlatformDeviceInfo::new(
398                        child.name,
399                        idx,
400                        compatible.clone(),
401                        resources,
402                    ));
403                    if let Err(e) = driver.probe(&*device) {
404                        println!("Failed to probe device {}: {}", device.name(), e);
405                    } else {
406                        idx += 1;
407                    }
408                }
409            }
410        }
411    }
412
413    /// Registers a device driver with the device manager.
414    /// 
415    /// This function takes a boxed device driver and adds it to the list of registered drivers.
416    /// It is used to register drivers that can be used to probe and manage devices.
417    /// 
418    /// # Arguments
419    /// 
420    /// * `driver` - A boxed device driver that implements the `DeviceDriver` trait.
421    /// 
422    /// # Example
423    /// 
424    /// ```rust
425    /// let driver = Box::new(MyDeviceDriver::new());
426    /// DeviceManager::get_mut_manager().register_driver(driver);
427    /// ```
428    pub fn register_driver(&mut self, driver: Box<dyn DeviceDriver>) {
429        self.drivers.lock().push(driver);
430    }
431}
432
433/// Registers a serial device with the device manager.
434/// 
435/// This function takes a boxed serial device and adds it to the list of registered serial devices.
436/// It is used to register serial devices that can be used for I/O operations.
437/// 
438/// # Arguments
439/// 
440/// * `serial` - A boxed serial device that implements the `Serial` trait.
441/// 
442/// # Example
443/// 
444/// ```rust
445/// let serial = Box::new(MySerialDevice::new());
446/// register_serial(serial);
447/// ```
448pub fn register_serial(serial: Box<dyn Serial>) {
449    let manager = DeviceManager::get_mut_manager();
450    manager.basic.register_serial(serial);
451}
452
453#[cfg(test)]
454mod tests {
455    use alloc::vec;
456    use super::*;
457    use crate::device::{platform::*, GenericDevice};
458
459    #[test_case]
460    fn test_populate_driver() {
461        static mut TEST_RESULT: bool = false;
462        fn probe_fn(_device: &PlatformDeviceInfo) -> Result<(), &'static str> {      
463            unsafe {
464                TEST_RESULT = true;
465            }  
466            Ok(())
467        }
468
469        let driver = Box::new(PlatformDeviceDriver::new(
470            "test",
471            probe_fn,
472            |_device| Ok(()),
473            vec!["sifive,test0"]
474        ));
475        DeviceManager::get_mut_manager().register_driver(driver);
476
477        DeviceManager::get_mut_manager().populate_devices();
478        let result = unsafe { TEST_RESULT };
479        assert_eq!(result, true);
480    }
481
482    #[test_case]
483    fn test_borrow_device_from_manager() {
484        let device = Box::new(GenericDevice::new(
485            "test",
486            1,
487        ));
488        let manager = DeviceManager::get_mut_manager();
489        let id = manager.register_device(device);
490        let borrowed_device = manager.borrow_device(id);
491        assert!(borrowed_device.is_ok());
492        let borrowed_device = borrowed_device.unwrap();
493        let device = borrowed_device.device();
494        assert_eq!(device.read().name(), "test");
495    }
496
497    #[test_case]
498    fn test_borrow_exclusive_device_from_manager() {
499        let device = Box::new(GenericDevice::new(
500            "test",
501            1,
502        ));
503        let manager = DeviceManager::get_mut_manager();
504        let id = manager.register_device(device);
505        let borrowed_device = manager.borrow_exclusive_device(id);
506        assert!(borrowed_device.is_ok());
507        let borrowed_device = borrowed_device.unwrap();
508        let device = borrowed_device.device();
509        assert_eq!(device.read().name(), "test");
510    }
511
512    #[test_case]
513    fn test_borrow_exclusive_device_from_manager_fail() {
514        let device = Box::new(GenericDevice::new(
515            "test",
516            1,
517        ));
518        let manager = DeviceManager::get_mut_manager();
519        let id = manager.register_device(device);
520        let borrowed_device = manager.borrow_exclusive_device(id);
521        assert!(borrowed_device.is_ok());
522        let borrowed_device = borrowed_device.unwrap();
523        let device = borrowed_device.device();
524        assert_eq!(device.read().name(), "test");
525        let borrowed_device2 = manager.borrow_exclusive_device(id);
526        assert!(borrowed_device2.is_err());
527    }
528
529    #[test_case]
530    fn test_drop_borrowed_device() {
531        let device = Box::new(GenericDevice::new(
532            "test",
533            1,
534        ));
535        let manager = DeviceManager::get_mut_manager();
536        let id = manager.register_device(device);
537        {
538            let borrowed_device = manager.borrow_device(id);
539            assert!(borrowed_device.is_ok());
540            let borrowed_device = borrowed_device.unwrap();
541            let device = borrowed_device.device();
542            assert_eq!(device.read().name(), "test");
543            // The device should be in use now
544            assert!(borrowed_device.handle.is_in_use());
545            assert_eq!(borrowed_device.handle.get_borrow_count(), 1);
546        }
547        // After the borrowed device goes out of scope, we should be able to borrow it again
548        let borrowed_device = manager.borrow_exclusive_device(id);
549        assert!(borrowed_device.is_ok());
550    }
551
552    #[test_case]
553    fn test_drop_multiple_borrowed_device() {
554        let device = Box::new(GenericDevice::new(
555            "test",
556            1,
557        ));
558        let manager = DeviceManager::get_mut_manager();
559        let id = manager.register_device(device);
560        {
561            let borrowed_device = manager.borrow_device(id);
562            assert!(borrowed_device.is_ok());
563            let borrowed_device = borrowed_device.unwrap();
564            let device = borrowed_device.device();
565            assert_eq!(device.read().name(), "test");
566            // The device should be in use now
567            assert!(borrowed_device.handle.is_in_use());
568            assert_eq!(borrowed_device.handle.get_borrow_count(), 1);
569            
570            {
571                // Second borrow
572                let borrowed_device = manager.borrow_device(id).unwrap();
573                let device = borrowed_device.device();
574                assert_eq!(device.read().name(), "test");
575                // The device should still be in use
576                assert!(borrowed_device.handle.is_in_use());
577                assert_eq!(borrowed_device.handle.get_borrow_count(), 2);
578                // Drop the second borrow
579            }
580            // The device should still be in use
581            assert!(borrowed_device.handle.is_in_use());
582            // The borrow count should be 1
583            assert_eq!(borrowed_device.handle.get_borrow_count(), 1);
584        }
585        // After the borrowed device goes out of scope, we should be able to borrow it again
586        let borrowed_device = manager.borrow_exclusive_device(id);
587        assert!(borrowed_device.is_ok());
588    }
589
590    #[test_case]
591    fn test_borrow_out_of_bounds() {
592        let manager = DeviceManager::get_manager();
593        let borrowed_device = manager.borrow_device(999);
594        assert!(borrowed_device.is_err());
595    }
596
597    #[test_case]
598    fn test_borrow_while_exclusive() {
599        let device = Box::new(GenericDevice::new("test", 1));
600        let manager = DeviceManager::get_mut_manager();
601        let id = manager.register_device(device);
602
603        let borrowed_device = manager.borrow_exclusive_device(id);
604        assert!(borrowed_device.is_ok());
605
606        let borrowed_device2 = manager.borrow_device(id);
607        assert!(borrowed_device2.is_err());
608    }
609}
kernel/device/manager.rs

kernel/device/
manager.rs
