1 // SPDX-License-Identifier: GPL-2.0 2 3 // Copyright (C) 2023 FUJITA Tomonori <fujita.tomonori@gmail.com> 4 5 //! Network PHY device. 6 //! 7 //! C headers: [`include/linux/phy.h`](srctree/include/linux/phy.h). 8 9 use crate::{device_id::RawDeviceId, error::*, prelude::*, types::Opaque}; 10 use core::{marker::PhantomData, ptr::addr_of_mut}; 11 12 pub mod reg; 13 14 /// PHY state machine states. 15 /// 16 /// Corresponds to the kernel's [`enum phy_state`]. 17 /// 18 /// Some of PHY drivers access to the state of PHY's software state machine. 19 /// 20 /// [`enum phy_state`]: srctree/include/linux/phy.h 21 #[derive(PartialEq, Eq)] 22 pub enum DeviceState { 23 /// PHY device and driver are not ready for anything. 24 Down, 25 /// PHY is ready to send and receive packets. 26 Ready, 27 /// PHY is up, but no polling or interrupts are done. 28 Halted, 29 /// PHY is up, but is in an error state. 30 Error, 31 /// PHY and attached device are ready to do work. 32 Up, 33 /// PHY is currently running. 34 Running, 35 /// PHY is up, but not currently plugged in. 36 NoLink, 37 /// PHY is performing a cable test. 38 CableTest, 39 } 40 41 /// A mode of Ethernet communication. 42 /// 43 /// PHY drivers get duplex information from hardware and update the current state. 44 pub enum DuplexMode { 45 /// PHY is in full-duplex mode. 46 Full, 47 /// PHY is in half-duplex mode. 48 Half, 49 /// PHY is in unknown duplex mode. 50 Unknown, 51 } 52 53 /// An instance of a PHY device. 54 /// 55 /// Wraps the kernel's [`struct phy_device`]. 56 /// 57 /// A [`Device`] instance is created when a callback in [`Driver`] is executed. A PHY driver 58 /// executes [`Driver`]'s methods during the callback. 59 /// 60 /// # Invariants 61 /// 62 /// - Referencing a `phy_device` using this struct asserts that you are in 63 /// a context where all methods defined on this struct are safe to call. 64 /// - This struct always has a valid `self.0.mdio.dev`. 65 /// 66 /// [`struct phy_device`]: srctree/include/linux/phy.h 67 // During the calls to most functions in [`Driver`], the C side (`PHYLIB`) holds a lock that is 68 // unique for every instance of [`Device`]. `PHYLIB` uses a different serialization technique for 69 // [`Driver::resume`] and [`Driver::suspend`]: `PHYLIB` updates `phy_device`'s state with 70 // the lock held, thus guaranteeing that [`Driver::resume`] has exclusive access to the instance. 71 // [`Driver::resume`] and [`Driver::suspend`] also are called where only one thread can access 72 // to the instance. 73 #[repr(transparent)] 74 pub struct Device(Opaque<bindings::phy_device>); 75 76 impl Device { 77 /// Creates a new [`Device`] instance from a raw pointer. 78 /// 79 /// # Safety 80 /// 81 /// For the duration of `'a`, 82 /// - the pointer must point at a valid `phy_device`, and the caller 83 /// must be in a context where all methods defined on this struct 84 /// are safe to call. 85 /// - `(*ptr).mdio.dev` must be a valid. 86 unsafe fn from_raw<'a>(ptr: *mut bindings::phy_device) -> &'a mut Self { 87 // CAST: `Self` is a `repr(transparent)` wrapper around `bindings::phy_device`. 88 let ptr = ptr.cast::<Self>(); 89 // SAFETY: by the function requirements the pointer is valid and we have unique access for 90 // the duration of `'a`. 91 unsafe { &mut *ptr } 92 } 93 94 /// Gets the id of the PHY. 95 pub fn phy_id(&self) -> u32 { 96 let phydev = self.0.get(); 97 // SAFETY: The struct invariant ensures that we may access 98 // this field without additional synchronization. 99 unsafe { (*phydev).phy_id } 100 } 101 102 /// Gets the state of PHY state machine states. 103 pub fn state(&self) -> DeviceState { 104 let phydev = self.0.get(); 105 // SAFETY: The struct invariant ensures that we may access 106 // this field without additional synchronization. 107 let state = unsafe { (*phydev).state }; 108 // TODO: this conversion code will be replaced with automatically generated code by bindgen 109 // when it becomes possible. 110 match state { 111 bindings::phy_state_PHY_DOWN => DeviceState::Down, 112 bindings::phy_state_PHY_READY => DeviceState::Ready, 113 bindings::phy_state_PHY_HALTED => DeviceState::Halted, 114 bindings::phy_state_PHY_ERROR => DeviceState::Error, 115 bindings::phy_state_PHY_UP => DeviceState::Up, 116 bindings::phy_state_PHY_RUNNING => DeviceState::Running, 117 bindings::phy_state_PHY_NOLINK => DeviceState::NoLink, 118 bindings::phy_state_PHY_CABLETEST => DeviceState::CableTest, 119 _ => DeviceState::Error, 120 } 121 } 122 123 /// Gets the current link state. 124 /// 125 /// It returns true if the link is up. 126 pub fn is_link_up(&self) -> bool { 127 const LINK_IS_UP: u64 = 1; 128 // TODO: the code to access to the bit field will be replaced with automatically 129 // generated code by bindgen when it becomes possible. 130 // SAFETY: The struct invariant ensures that we may access 131 // this field without additional synchronization. 132 let bit_field = unsafe { &(*self.0.get())._bitfield_1 }; 133 bit_field.get(14, 1) == LINK_IS_UP 134 } 135 136 /// Gets the current auto-negotiation configuration. 137 /// 138 /// It returns true if auto-negotiation is enabled. 139 pub fn is_autoneg_enabled(&self) -> bool { 140 // TODO: the code to access to the bit field will be replaced with automatically 141 // generated code by bindgen when it becomes possible. 142 // SAFETY: The struct invariant ensures that we may access 143 // this field without additional synchronization. 144 let bit_field = unsafe { &(*self.0.get())._bitfield_1 }; 145 bit_field.get(13, 1) == bindings::AUTONEG_ENABLE as u64 146 } 147 148 /// Gets the current auto-negotiation state. 149 /// 150 /// It returns true if auto-negotiation is completed. 151 pub fn is_autoneg_completed(&self) -> bool { 152 const AUTONEG_COMPLETED: u64 = 1; 153 // TODO: the code to access to the bit field will be replaced with automatically 154 // generated code by bindgen when it becomes possible. 155 // SAFETY: The struct invariant ensures that we may access 156 // this field without additional synchronization. 157 let bit_field = unsafe { &(*self.0.get())._bitfield_1 }; 158 bit_field.get(15, 1) == AUTONEG_COMPLETED 159 } 160 161 /// Sets the speed of the PHY. 162 pub fn set_speed(&mut self, speed: u32) { 163 let phydev = self.0.get(); 164 // SAFETY: The struct invariant ensures that we may access 165 // this field without additional synchronization. 166 unsafe { (*phydev).speed = speed as i32 }; 167 } 168 169 /// Sets duplex mode. 170 pub fn set_duplex(&mut self, mode: DuplexMode) { 171 let phydev = self.0.get(); 172 let v = match mode { 173 DuplexMode::Full => bindings::DUPLEX_FULL as i32, 174 DuplexMode::Half => bindings::DUPLEX_HALF as i32, 175 DuplexMode::Unknown => bindings::DUPLEX_UNKNOWN as i32, 176 }; 177 // SAFETY: The struct invariant ensures that we may access 178 // this field without additional synchronization. 179 unsafe { (*phydev).duplex = v }; 180 } 181 182 /// Reads a PHY register. 183 // This function reads a hardware register and updates the stats so takes `&mut self`. 184 pub fn read<R: reg::Register>(&mut self, reg: R) -> Result<u16> { 185 reg.read(self) 186 } 187 188 /// Writes a PHY register. 189 pub fn write<R: reg::Register>(&mut self, reg: R, val: u16) -> Result { 190 reg.write(self, val) 191 } 192 193 /// Reads a paged register. 194 pub fn read_paged(&mut self, page: u16, regnum: u16) -> Result<u16> { 195 let phydev = self.0.get(); 196 // SAFETY: `phydev` is pointing to a valid object by the type invariant of `Self`. 197 // So it's just an FFI call. 198 let ret = unsafe { bindings::phy_read_paged(phydev, page.into(), regnum.into()) }; 199 if ret < 0 { 200 Err(Error::from_errno(ret)) 201 } else { 202 Ok(ret as u16) 203 } 204 } 205 206 /// Resolves the advertisements into PHY settings. 207 pub fn resolve_aneg_linkmode(&mut self) { 208 let phydev = self.0.get(); 209 // SAFETY: `phydev` is pointing to a valid object by the type invariant of `Self`. 210 // So it's just an FFI call. 211 unsafe { bindings::phy_resolve_aneg_linkmode(phydev) }; 212 } 213 214 /// Executes software reset the PHY via `BMCR_RESET` bit. 215 pub fn genphy_soft_reset(&mut self) -> Result { 216 let phydev = self.0.get(); 217 // SAFETY: `phydev` is pointing to a valid object by the type invariant of `Self`. 218 // So it's just an FFI call. 219 to_result(unsafe { bindings::genphy_soft_reset(phydev) }) 220 } 221 222 /// Initializes the PHY. 223 pub fn init_hw(&mut self) -> Result { 224 let phydev = self.0.get(); 225 // SAFETY: `phydev` is pointing to a valid object by the type invariant of `Self`. 226 // So it's just an FFI call. 227 to_result(unsafe { bindings::phy_init_hw(phydev) }) 228 } 229 230 /// Starts auto-negotiation. 231 pub fn start_aneg(&mut self) -> Result { 232 let phydev = self.0.get(); 233 // SAFETY: `phydev` is pointing to a valid object by the type invariant of `Self`. 234 // So it's just an FFI call. 235 to_result(unsafe { bindings::_phy_start_aneg(phydev) }) 236 } 237 238 /// Resumes the PHY via `BMCR_PDOWN` bit. 239 pub fn genphy_resume(&mut self) -> Result { 240 let phydev = self.0.get(); 241 // SAFETY: `phydev` is pointing to a valid object by the type invariant of `Self`. 242 // So it's just an FFI call. 243 to_result(unsafe { bindings::genphy_resume(phydev) }) 244 } 245 246 /// Suspends the PHY via `BMCR_PDOWN` bit. 247 pub fn genphy_suspend(&mut self) -> Result { 248 let phydev = self.0.get(); 249 // SAFETY: `phydev` is pointing to a valid object by the type invariant of `Self`. 250 // So it's just an FFI call. 251 to_result(unsafe { bindings::genphy_suspend(phydev) }) 252 } 253 254 /// Checks the link status and updates current link state. 255 pub fn genphy_read_status<R: reg::Register>(&mut self) -> Result<u16> { 256 R::read_status(self) 257 } 258 259 /// Updates the link status. 260 pub fn genphy_update_link(&mut self) -> Result { 261 let phydev = self.0.get(); 262 // SAFETY: `phydev` is pointing to a valid object by the type invariant of `Self`. 263 // So it's just an FFI call. 264 to_result(unsafe { bindings::genphy_update_link(phydev) }) 265 } 266 267 /// Reads link partner ability. 268 pub fn genphy_read_lpa(&mut self) -> Result { 269 let phydev = self.0.get(); 270 // SAFETY: `phydev` is pointing to a valid object by the type invariant of `Self`. 271 // So it's just an FFI call. 272 to_result(unsafe { bindings::genphy_read_lpa(phydev) }) 273 } 274 275 /// Reads PHY abilities. 276 pub fn genphy_read_abilities(&mut self) -> Result { 277 let phydev = self.0.get(); 278 // SAFETY: `phydev` is pointing to a valid object by the type invariant of `Self`. 279 // So it's just an FFI call. 280 to_result(unsafe { bindings::genphy_read_abilities(phydev) }) 281 } 282 } 283 284 impl AsRef<kernel::device::Device> for Device { 285 fn as_ref(&self) -> &kernel::device::Device { 286 let phydev = self.0.get(); 287 // SAFETY: The struct invariant ensures that `mdio.dev` is valid. 288 unsafe { kernel::device::Device::from_raw(addr_of_mut!((*phydev).mdio.dev)) } 289 } 290 } 291 292 /// Defines certain other features this PHY supports (like interrupts). 293 /// 294 /// These flag values are used in [`Driver::FLAGS`]. 295 pub mod flags { 296 /// PHY is internal. 297 pub const IS_INTERNAL: u32 = bindings::PHY_IS_INTERNAL; 298 /// PHY needs to be reset after the refclk is enabled. 299 pub const RST_AFTER_CLK_EN: u32 = bindings::PHY_RST_AFTER_CLK_EN; 300 /// Polling is used to detect PHY status changes. 301 pub const POLL_CABLE_TEST: u32 = bindings::PHY_POLL_CABLE_TEST; 302 /// Don't suspend. 303 pub const ALWAYS_CALL_SUSPEND: u32 = bindings::PHY_ALWAYS_CALL_SUSPEND; 304 } 305 306 /// An adapter for the registration of a PHY driver. 307 struct Adapter<T: Driver> { 308 _p: PhantomData<T>, 309 } 310 311 impl<T: Driver> Adapter<T> { 312 /// # Safety 313 /// 314 /// `phydev` must be passed by the corresponding callback in `phy_driver`. 315 unsafe extern "C" fn soft_reset_callback( 316 phydev: *mut bindings::phy_device, 317 ) -> crate::ffi::c_int { 318 from_result(|| { 319 // SAFETY: This callback is called only in contexts 320 // where we hold `phy_device->lock`, so the accessors on 321 // `Device` are okay to call. 322 let dev = unsafe { Device::from_raw(phydev) }; 323 T::soft_reset(dev)?; 324 Ok(0) 325 }) 326 } 327 328 /// # Safety 329 /// 330 /// `phydev` must be passed by the corresponding callback in `phy_driver`. 331 unsafe extern "C" fn probe_callback(phydev: *mut bindings::phy_device) -> crate::ffi::c_int { 332 from_result(|| { 333 // SAFETY: This callback is called only in contexts 334 // where we can exclusively access `phy_device` because 335 // it's not published yet, so the accessors on `Device` are okay 336 // to call. 337 let dev = unsafe { Device::from_raw(phydev) }; 338 T::probe(dev)?; 339 Ok(0) 340 }) 341 } 342 343 /// # Safety 344 /// 345 /// `phydev` must be passed by the corresponding callback in `phy_driver`. 346 unsafe extern "C" fn get_features_callback( 347 phydev: *mut bindings::phy_device, 348 ) -> crate::ffi::c_int { 349 from_result(|| { 350 // SAFETY: This callback is called only in contexts 351 // where we hold `phy_device->lock`, so the accessors on 352 // `Device` are okay to call. 353 let dev = unsafe { Device::from_raw(phydev) }; 354 T::get_features(dev)?; 355 Ok(0) 356 }) 357 } 358 359 /// # Safety 360 /// 361 /// `phydev` must be passed by the corresponding callback in `phy_driver`. 362 unsafe extern "C" fn suspend_callback(phydev: *mut bindings::phy_device) -> crate::ffi::c_int { 363 from_result(|| { 364 // SAFETY: The C core code ensures that the accessors on 365 // `Device` are okay to call even though `phy_device->lock` 366 // might not be held. 367 let dev = unsafe { Device::from_raw(phydev) }; 368 T::suspend(dev)?; 369 Ok(0) 370 }) 371 } 372 373 /// # Safety 374 /// 375 /// `phydev` must be passed by the corresponding callback in `phy_driver`. 376 unsafe extern "C" fn resume_callback(phydev: *mut bindings::phy_device) -> crate::ffi::c_int { 377 from_result(|| { 378 // SAFETY: The C core code ensures that the accessors on 379 // `Device` are okay to call even though `phy_device->lock` 380 // might not be held. 381 let dev = unsafe { Device::from_raw(phydev) }; 382 T::resume(dev)?; 383 Ok(0) 384 }) 385 } 386 387 /// # Safety 388 /// 389 /// `phydev` must be passed by the corresponding callback in `phy_driver`. 390 unsafe extern "C" fn config_aneg_callback( 391 phydev: *mut bindings::phy_device, 392 ) -> crate::ffi::c_int { 393 from_result(|| { 394 // SAFETY: This callback is called only in contexts 395 // where we hold `phy_device->lock`, so the accessors on 396 // `Device` are okay to call. 397 let dev = unsafe { Device::from_raw(phydev) }; 398 T::config_aneg(dev)?; 399 Ok(0) 400 }) 401 } 402 403 /// # Safety 404 /// 405 /// `phydev` must be passed by the corresponding callback in `phy_driver`. 406 unsafe extern "C" fn read_status_callback( 407 phydev: *mut bindings::phy_device, 408 ) -> crate::ffi::c_int { 409 from_result(|| { 410 // SAFETY: This callback is called only in contexts 411 // where we hold `phy_device->lock`, so the accessors on 412 // `Device` are okay to call. 413 let dev = unsafe { Device::from_raw(phydev) }; 414 T::read_status(dev)?; 415 Ok(0) 416 }) 417 } 418 419 /// # Safety 420 /// 421 /// `phydev` must be passed by the corresponding callback in `phy_driver`. 422 unsafe extern "C" fn match_phy_device_callback( 423 phydev: *mut bindings::phy_device, 424 _phydrv: *const bindings::phy_driver, 425 ) -> crate::ffi::c_int { 426 // SAFETY: This callback is called only in contexts 427 // where we hold `phy_device->lock`, so the accessors on 428 // `Device` are okay to call. 429 let dev = unsafe { Device::from_raw(phydev) }; 430 T::match_phy_device(dev) as i32 431 } 432 433 /// # Safety 434 /// 435 /// `phydev` must be passed by the corresponding callback in `phy_driver`. 436 unsafe extern "C" fn read_mmd_callback( 437 phydev: *mut bindings::phy_device, 438 devnum: i32, 439 regnum: u16, 440 ) -> i32 { 441 from_result(|| { 442 // SAFETY: This callback is called only in contexts 443 // where we hold `phy_device->lock`, so the accessors on 444 // `Device` are okay to call. 445 let dev = unsafe { Device::from_raw(phydev) }; 446 // CAST: the C side verifies devnum < 32. 447 let ret = T::read_mmd(dev, devnum as u8, regnum)?; 448 Ok(ret.into()) 449 }) 450 } 451 452 /// # Safety 453 /// 454 /// `phydev` must be passed by the corresponding callback in `phy_driver`. 455 unsafe extern "C" fn write_mmd_callback( 456 phydev: *mut bindings::phy_device, 457 devnum: i32, 458 regnum: u16, 459 val: u16, 460 ) -> i32 { 461 from_result(|| { 462 // SAFETY: This callback is called only in contexts 463 // where we hold `phy_device->lock`, so the accessors on 464 // `Device` are okay to call. 465 let dev = unsafe { Device::from_raw(phydev) }; 466 T::write_mmd(dev, devnum as u8, regnum, val)?; 467 Ok(0) 468 }) 469 } 470 471 /// # Safety 472 /// 473 /// `phydev` must be passed by the corresponding callback in `phy_driver`. 474 unsafe extern "C" fn link_change_notify_callback(phydev: *mut bindings::phy_device) { 475 // SAFETY: This callback is called only in contexts 476 // where we hold `phy_device->lock`, so the accessors on 477 // `Device` are okay to call. 478 let dev = unsafe { Device::from_raw(phydev) }; 479 T::link_change_notify(dev); 480 } 481 } 482 483 /// Driver structure for a particular PHY type. 484 /// 485 /// Wraps the kernel's [`struct phy_driver`]. 486 /// This is used to register a driver for a particular PHY type with the kernel. 487 /// 488 /// # Invariants 489 /// 490 /// `self.0` is always in a valid state. 491 /// 492 /// [`struct phy_driver`]: srctree/include/linux/phy.h 493 #[repr(transparent)] 494 pub struct DriverVTable(Opaque<bindings::phy_driver>); 495 496 // SAFETY: `DriverVTable` doesn't expose any &self method to access internal data, so it's safe to 497 // share `&DriverVTable` across execution context boundaries. 498 unsafe impl Sync for DriverVTable {} 499 500 /// Creates a [`DriverVTable`] instance from [`Driver`]. 501 /// 502 /// This is used by [`module_phy_driver`] macro to create a static array of `phy_driver`. 503 /// 504 /// [`module_phy_driver`]: crate::module_phy_driver 505 pub const fn create_phy_driver<T: Driver>() -> DriverVTable { 506 // INVARIANT: All the fields of `struct phy_driver` are initialized properly. 507 DriverVTable(Opaque::new(bindings::phy_driver { 508 name: T::NAME.as_char_ptr().cast_mut(), 509 flags: T::FLAGS, 510 phy_id: T::PHY_DEVICE_ID.id(), 511 phy_id_mask: T::PHY_DEVICE_ID.mask_as_int(), 512 soft_reset: if T::HAS_SOFT_RESET { 513 Some(Adapter::<T>::soft_reset_callback) 514 } else { 515 None 516 }, 517 probe: if T::HAS_PROBE { 518 Some(Adapter::<T>::probe_callback) 519 } else { 520 None 521 }, 522 get_features: if T::HAS_GET_FEATURES { 523 Some(Adapter::<T>::get_features_callback) 524 } else { 525 None 526 }, 527 match_phy_device: if T::HAS_MATCH_PHY_DEVICE { 528 Some(Adapter::<T>::match_phy_device_callback) 529 } else { 530 None 531 }, 532 suspend: if T::HAS_SUSPEND { 533 Some(Adapter::<T>::suspend_callback) 534 } else { 535 None 536 }, 537 resume: if T::HAS_RESUME { 538 Some(Adapter::<T>::resume_callback) 539 } else { 540 None 541 }, 542 config_aneg: if T::HAS_CONFIG_ANEG { 543 Some(Adapter::<T>::config_aneg_callback) 544 } else { 545 None 546 }, 547 read_status: if T::HAS_READ_STATUS { 548 Some(Adapter::<T>::read_status_callback) 549 } else { 550 None 551 }, 552 read_mmd: if T::HAS_READ_MMD { 553 Some(Adapter::<T>::read_mmd_callback) 554 } else { 555 None 556 }, 557 write_mmd: if T::HAS_WRITE_MMD { 558 Some(Adapter::<T>::write_mmd_callback) 559 } else { 560 None 561 }, 562 link_change_notify: if T::HAS_LINK_CHANGE_NOTIFY { 563 Some(Adapter::<T>::link_change_notify_callback) 564 } else { 565 None 566 }, 567 // SAFETY: The rest is zeroed out to initialize `struct phy_driver`, 568 // sets `Option<&F>` to be `None`. 569 ..unsafe { core::mem::MaybeUninit::<bindings::phy_driver>::zeroed().assume_init() } 570 })) 571 } 572 573 /// Driver implementation for a particular PHY type. 574 /// 575 /// This trait is used to create a [`DriverVTable`]. 576 #[vtable] 577 pub trait Driver { 578 /// Defines certain other features this PHY supports. 579 /// It is a combination of the flags in the [`flags`] module. 580 const FLAGS: u32 = 0; 581 582 /// The friendly name of this PHY type. 583 const NAME: &'static CStr; 584 585 /// This driver only works for PHYs with IDs which match this field. 586 /// The default id and mask are zero. 587 const PHY_DEVICE_ID: DeviceId = DeviceId::new_with_custom_mask(0, 0); 588 589 /// Issues a PHY software reset. 590 fn soft_reset(_dev: &mut Device) -> Result { 591 build_error!(VTABLE_DEFAULT_ERROR) 592 } 593 594 /// Sets up device-specific structures during discovery. 595 fn probe(_dev: &mut Device) -> Result { 596 build_error!(VTABLE_DEFAULT_ERROR) 597 } 598 599 /// Probes the hardware to determine what abilities it has. 600 fn get_features(_dev: &mut Device) -> Result { 601 build_error!(VTABLE_DEFAULT_ERROR) 602 } 603 604 /// Returns true if this is a suitable driver for the given phydev. 605 /// If not implemented, matching is based on [`Driver::PHY_DEVICE_ID`]. 606 fn match_phy_device(_dev: &Device) -> bool { 607 false 608 } 609 610 /// Configures the advertisement and resets auto-negotiation 611 /// if auto-negotiation is enabled. 612 fn config_aneg(_dev: &mut Device) -> Result { 613 build_error!(VTABLE_DEFAULT_ERROR) 614 } 615 616 /// Determines the negotiated speed and duplex. 617 fn read_status(_dev: &mut Device) -> Result<u16> { 618 build_error!(VTABLE_DEFAULT_ERROR) 619 } 620 621 /// Suspends the hardware, saving state if needed. 622 fn suspend(_dev: &mut Device) -> Result { 623 build_error!(VTABLE_DEFAULT_ERROR) 624 } 625 626 /// Resumes the hardware, restoring state if needed. 627 fn resume(_dev: &mut Device) -> Result { 628 build_error!(VTABLE_DEFAULT_ERROR) 629 } 630 631 /// Overrides the default MMD read function for reading a MMD register. 632 fn read_mmd(_dev: &mut Device, _devnum: u8, _regnum: u16) -> Result<u16> { 633 build_error!(VTABLE_DEFAULT_ERROR) 634 } 635 636 /// Overrides the default MMD write function for writing a MMD register. 637 fn write_mmd(_dev: &mut Device, _devnum: u8, _regnum: u16, _val: u16) -> Result { 638 build_error!(VTABLE_DEFAULT_ERROR) 639 } 640 641 /// Callback for notification of link change. 642 fn link_change_notify(_dev: &mut Device) {} 643 } 644 645 /// Registration structure for PHY drivers. 646 /// 647 /// Registers [`DriverVTable`] instances with the kernel. They will be unregistered when dropped. 648 /// 649 /// # Invariants 650 /// 651 /// The `drivers` slice are currently registered to the kernel via `phy_drivers_register`. 652 pub struct Registration { 653 drivers: Pin<&'static mut [DriverVTable]>, 654 } 655 656 // SAFETY: The only action allowed in a `Registration` instance is dropping it, which is safe to do 657 // from any thread because `phy_drivers_unregister` can be called from any thread context. 658 unsafe impl Send for Registration {} 659 660 impl Registration { 661 /// Registers a PHY driver. 662 pub fn register( 663 module: &'static crate::ThisModule, 664 drivers: Pin<&'static mut [DriverVTable]>, 665 ) -> Result<Self> { 666 if drivers.is_empty() { 667 return Err(code::EINVAL); 668 } 669 // SAFETY: The type invariants of [`DriverVTable`] ensure that all elements of 670 // the `drivers` slice are initialized properly. `drivers` will not be moved. 671 // So it's just an FFI call. 672 to_result(unsafe { 673 bindings::phy_drivers_register(drivers[0].0.get(), drivers.len().try_into()?, module.0) 674 })?; 675 // INVARIANT: The `drivers` slice is successfully registered to the kernel via `phy_drivers_register`. 676 Ok(Registration { drivers }) 677 } 678 } 679 680 impl Drop for Registration { 681 fn drop(&mut self) { 682 // SAFETY: The type invariants guarantee that `self.drivers` is valid. 683 // So it's just an FFI call. 684 unsafe { 685 bindings::phy_drivers_unregister(self.drivers[0].0.get(), self.drivers.len() as i32) 686 }; 687 } 688 } 689 690 /// An identifier for PHY devices on an MDIO/MII bus. 691 /// 692 /// Represents the kernel's `struct mdio_device_id`. This is used to find an appropriate 693 /// PHY driver. 694 #[repr(transparent)] 695 #[derive(Clone, Copy)] 696 pub struct DeviceId(bindings::mdio_device_id); 697 698 impl DeviceId { 699 /// Creates a new instance with the exact match mask. 700 pub const fn new_with_exact_mask(id: u32) -> Self { 701 Self(bindings::mdio_device_id { 702 phy_id: id, 703 phy_id_mask: DeviceMask::Exact.as_int(), 704 }) 705 } 706 707 /// Creates a new instance with the model match mask. 708 pub const fn new_with_model_mask(id: u32) -> Self { 709 Self(bindings::mdio_device_id { 710 phy_id: id, 711 phy_id_mask: DeviceMask::Model.as_int(), 712 }) 713 } 714 715 /// Creates a new instance with the vendor match mask. 716 pub const fn new_with_vendor_mask(id: u32) -> Self { 717 Self(bindings::mdio_device_id { 718 phy_id: id, 719 phy_id_mask: DeviceMask::Vendor.as_int(), 720 }) 721 } 722 723 /// Creates a new instance with a custom match mask. 724 pub const fn new_with_custom_mask(id: u32, mask: u32) -> Self { 725 Self(bindings::mdio_device_id { 726 phy_id: id, 727 phy_id_mask: DeviceMask::Custom(mask).as_int(), 728 }) 729 } 730 731 /// Creates a new instance from [`Driver`]. 732 pub const fn new_with_driver<T: Driver>() -> Self { 733 T::PHY_DEVICE_ID 734 } 735 736 /// Get the MDIO device's PHY ID. 737 pub const fn id(&self) -> u32 { 738 self.0.phy_id 739 } 740 741 /// Get the MDIO device's match mask. 742 pub const fn mask_as_int(&self) -> u32 { 743 self.0.phy_id_mask 744 } 745 746 // macro use only 747 #[doc(hidden)] 748 pub const fn mdio_device_id(&self) -> bindings::mdio_device_id { 749 self.0 750 } 751 } 752 753 // SAFETY: `DeviceId` is a `#[repr(transparent)]` wrapper of `struct mdio_device_id` 754 // and does not add additional invariants, so it's safe to transmute to `RawType`. 755 unsafe impl RawDeviceId for DeviceId { 756 type RawType = bindings::mdio_device_id; 757 } 758 759 enum DeviceMask { 760 Exact, 761 Model, 762 Vendor, 763 Custom(u32), 764 } 765 766 impl DeviceMask { 767 const MASK_EXACT: u32 = !0; 768 const MASK_MODEL: u32 = !0 << 4; 769 const MASK_VENDOR: u32 = !0 << 10; 770 771 const fn as_int(&self) -> u32 { 772 match self { 773 DeviceMask::Exact => Self::MASK_EXACT, 774 DeviceMask::Model => Self::MASK_MODEL, 775 DeviceMask::Vendor => Self::MASK_VENDOR, 776 DeviceMask::Custom(mask) => *mask, 777 } 778 } 779 } 780 781 /// Declares a kernel module for PHYs drivers. 782 /// 783 /// This creates a static array of kernel's `struct phy_driver` and registers it. 784 /// This also corresponds to the kernel's `MODULE_DEVICE_TABLE` macro, which embeds the information 785 /// for module loading into the module binary file. Every driver needs an entry in `device_table`. 786 /// 787 /// # Examples 788 /// 789 /// ``` 790 /// # mod module_phy_driver_sample { 791 /// use kernel::c_str; 792 /// use kernel::net::phy::{self, DeviceId}; 793 /// use kernel::prelude::*; 794 /// 795 /// kernel::module_phy_driver! { 796 /// drivers: [PhySample], 797 /// device_table: [ 798 /// DeviceId::new_with_driver::<PhySample>() 799 /// ], 800 /// name: "rust_sample_phy", 801 /// authors: ["Rust for Linux Contributors"], 802 /// description: "Rust sample PHYs driver", 803 /// license: "GPL", 804 /// } 805 /// 806 /// struct PhySample; 807 /// 808 /// #[vtable] 809 /// impl phy::Driver for PhySample { 810 /// const NAME: &'static CStr = c_str!("PhySample"); 811 /// const PHY_DEVICE_ID: phy::DeviceId = phy::DeviceId::new_with_exact_mask(0x00000001); 812 /// } 813 /// # } 814 /// ``` 815 /// 816 /// This expands to the following code: 817 /// 818 /// ```ignore 819 /// use kernel::c_str; 820 /// use kernel::net::phy::{self, DeviceId}; 821 /// use kernel::prelude::*; 822 /// 823 /// struct Module { 824 /// _reg: ::kernel::net::phy::Registration, 825 /// } 826 /// 827 /// module! { 828 /// type: Module, 829 /// name: "rust_sample_phy", 830 /// authors: ["Rust for Linux Contributors"], 831 /// description: "Rust sample PHYs driver", 832 /// license: "GPL", 833 /// } 834 /// 835 /// struct PhySample; 836 /// 837 /// #[vtable] 838 /// impl phy::Driver for PhySample { 839 /// const NAME: &'static CStr = c_str!("PhySample"); 840 /// const PHY_DEVICE_ID: phy::DeviceId = phy::DeviceId::new_with_exact_mask(0x00000001); 841 /// } 842 /// 843 /// const _: () = { 844 /// static mut DRIVERS: [::kernel::net::phy::DriverVTable; 1] = 845 /// [::kernel::net::phy::create_phy_driver::<PhySample>()]; 846 /// 847 /// impl ::kernel::Module for Module { 848 /// fn init(module: &'static ::kernel::ThisModule) -> Result<Self> { 849 /// let drivers = unsafe { &mut DRIVERS }; 850 /// let mut reg = ::kernel::net::phy::Registration::register( 851 /// module, 852 /// ::core::pin::Pin::static_mut(drivers), 853 /// )?; 854 /// Ok(Module { _reg: reg }) 855 /// } 856 /// } 857 /// }; 858 /// 859 /// const N: usize = 1; 860 /// 861 /// const TABLE: ::kernel::device_id::IdArray<::kernel::net::phy::DeviceId, (), N> = 862 /// ::kernel::device_id::IdArray::new_without_index([ 863 /// ::kernel::net::phy::DeviceId( 864 /// ::kernel::bindings::mdio_device_id { 865 /// phy_id: 0x00000001, 866 /// phy_id_mask: 0xffffffff, 867 /// }), 868 /// ]); 869 /// 870 /// ::kernel::module_device_table!("mdio", phydev, TABLE); 871 /// ``` 872 #[macro_export] 873 macro_rules! module_phy_driver { 874 (@replace_expr $_t:tt $sub:expr) => {$sub}; 875 876 (@count_devices $($x:expr),*) => { 877 0usize $(+ $crate::module_phy_driver!(@replace_expr $x 1usize))* 878 }; 879 880 (@device_table [$($dev:expr),+]) => { 881 const N: usize = $crate::module_phy_driver!(@count_devices $($dev),+); 882 883 const TABLE: $crate::device_id::IdArray<$crate::net::phy::DeviceId, (), N> = 884 $crate::device_id::IdArray::new_without_index([ $(($dev,())),+, ]); 885 886 $crate::module_device_table!("mdio", phydev, TABLE); 887 }; 888 889 (drivers: [$($driver:ident),+ $(,)?], device_table: [$($dev:expr),+ $(,)?], $($f:tt)*) => { 890 struct Module { 891 _reg: $crate::net::phy::Registration, 892 } 893 894 $crate::prelude::module! { 895 type: Module, 896 $($f)* 897 } 898 899 const _: () = { 900 static mut DRIVERS: [$crate::net::phy::DriverVTable; 901 $crate::module_phy_driver!(@count_devices $($driver),+)] = 902 [$($crate::net::phy::create_phy_driver::<$driver>()),+]; 903 904 impl $crate::Module for Module { 905 fn init(module: &'static $crate::ThisModule) -> Result<Self> { 906 // SAFETY: The anonymous constant guarantees that nobody else can access 907 // the `DRIVERS` static. The array is used only in the C side. 908 let drivers = unsafe { &mut DRIVERS }; 909 let mut reg = $crate::net::phy::Registration::register( 910 module, 911 ::core::pin::Pin::static_mut(drivers), 912 )?; 913 Ok(Module { _reg: reg }) 914 } 915 } 916 }; 917 918 $crate::module_phy_driver!(@device_table [$($dev),+]); 919 } 920 } 921