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 c_int }; 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, 174 DuplexMode::Half => bindings::DUPLEX_HALF, 175 DuplexMode::Unknown => bindings::DUPLEX_UNKNOWN, 176 }; 177 // SAFETY: The struct invariant ensures that we may access 178 // this field without additional synchronization. 179 unsafe { (*phydev).duplex = v as c_int }; 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(phydev: *mut bindings::phy_device) -> c_int { 316 from_result(|| { 317 // SAFETY: This callback is called only in contexts 318 // where we hold `phy_device->lock`, so the accessors on 319 // `Device` are okay to call. 320 let dev = unsafe { Device::from_raw(phydev) }; 321 T::soft_reset(dev)?; 322 Ok(0) 323 }) 324 } 325 326 /// # Safety 327 /// 328 /// `phydev` must be passed by the corresponding callback in `phy_driver`. 329 unsafe extern "C" fn probe_callback(phydev: *mut bindings::phy_device) -> c_int { 330 from_result(|| { 331 // SAFETY: This callback is called only in contexts 332 // where we can exclusively access `phy_device` because 333 // it's not published yet, so the accessors on `Device` are okay 334 // to call. 335 let dev = unsafe { Device::from_raw(phydev) }; 336 T::probe(dev)?; 337 Ok(0) 338 }) 339 } 340 341 /// # Safety 342 /// 343 /// `phydev` must be passed by the corresponding callback in `phy_driver`. 344 unsafe extern "C" fn get_features_callback(phydev: *mut bindings::phy_device) -> c_int { 345 from_result(|| { 346 // SAFETY: This callback is called only in contexts 347 // where we hold `phy_device->lock`, so the accessors on 348 // `Device` are okay to call. 349 let dev = unsafe { Device::from_raw(phydev) }; 350 T::get_features(dev)?; 351 Ok(0) 352 }) 353 } 354 355 /// # Safety 356 /// 357 /// `phydev` must be passed by the corresponding callback in `phy_driver`. 358 unsafe extern "C" fn suspend_callback(phydev: *mut bindings::phy_device) -> c_int { 359 from_result(|| { 360 // SAFETY: The C core code ensures that the accessors on 361 // `Device` are okay to call even though `phy_device->lock` 362 // might not be held. 363 let dev = unsafe { Device::from_raw(phydev) }; 364 T::suspend(dev)?; 365 Ok(0) 366 }) 367 } 368 369 /// # Safety 370 /// 371 /// `phydev` must be passed by the corresponding callback in `phy_driver`. 372 unsafe extern "C" fn resume_callback(phydev: *mut bindings::phy_device) -> c_int { 373 from_result(|| { 374 // SAFETY: The C core code ensures that the accessors on 375 // `Device` are okay to call even though `phy_device->lock` 376 // might not be held. 377 let dev = unsafe { Device::from_raw(phydev) }; 378 T::resume(dev)?; 379 Ok(0) 380 }) 381 } 382 383 /// # Safety 384 /// 385 /// `phydev` must be passed by the corresponding callback in `phy_driver`. 386 unsafe extern "C" fn config_aneg_callback(phydev: *mut bindings::phy_device) -> c_int { 387 from_result(|| { 388 // SAFETY: This callback is called only in contexts 389 // where we hold `phy_device->lock`, so the accessors on 390 // `Device` are okay to call. 391 let dev = unsafe { Device::from_raw(phydev) }; 392 T::config_aneg(dev)?; 393 Ok(0) 394 }) 395 } 396 397 /// # Safety 398 /// 399 /// `phydev` must be passed by the corresponding callback in `phy_driver`. 400 unsafe extern "C" fn read_status_callback(phydev: *mut bindings::phy_device) -> c_int { 401 from_result(|| { 402 // SAFETY: This callback is called only in contexts 403 // where we hold `phy_device->lock`, so the accessors on 404 // `Device` are okay to call. 405 let dev = unsafe { Device::from_raw(phydev) }; 406 T::read_status(dev)?; 407 Ok(0) 408 }) 409 } 410 411 /// # Safety 412 /// 413 /// `phydev` must be passed by the corresponding callback in `phy_driver`. 414 unsafe extern "C" fn match_phy_device_callback( 415 phydev: *mut bindings::phy_device, 416 _phydrv: *const bindings::phy_driver, 417 ) -> c_int { 418 // SAFETY: This callback is called only in contexts 419 // where we hold `phy_device->lock`, so the accessors on 420 // `Device` are okay to call. 421 let dev = unsafe { Device::from_raw(phydev) }; 422 T::match_phy_device(dev) as i32 423 } 424 425 /// # Safety 426 /// 427 /// `phydev` must be passed by the corresponding callback in `phy_driver`. 428 unsafe extern "C" fn read_mmd_callback( 429 phydev: *mut bindings::phy_device, 430 devnum: i32, 431 regnum: u16, 432 ) -> i32 { 433 from_result(|| { 434 // SAFETY: This callback is called only in contexts 435 // where we hold `phy_device->lock`, so the accessors on 436 // `Device` are okay to call. 437 let dev = unsafe { Device::from_raw(phydev) }; 438 // CAST: the C side verifies devnum < 32. 439 let ret = T::read_mmd(dev, devnum as u8, regnum)?; 440 Ok(ret.into()) 441 }) 442 } 443 444 /// # Safety 445 /// 446 /// `phydev` must be passed by the corresponding callback in `phy_driver`. 447 unsafe extern "C" fn write_mmd_callback( 448 phydev: *mut bindings::phy_device, 449 devnum: i32, 450 regnum: u16, 451 val: u16, 452 ) -> i32 { 453 from_result(|| { 454 // SAFETY: This callback is called only in contexts 455 // where we hold `phy_device->lock`, so the accessors on 456 // `Device` are okay to call. 457 let dev = unsafe { Device::from_raw(phydev) }; 458 T::write_mmd(dev, devnum as u8, regnum, val)?; 459 Ok(0) 460 }) 461 } 462 463 /// # Safety 464 /// 465 /// `phydev` must be passed by the corresponding callback in `phy_driver`. 466 unsafe extern "C" fn link_change_notify_callback(phydev: *mut bindings::phy_device) { 467 // SAFETY: This callback is called only in contexts 468 // where we hold `phy_device->lock`, so the accessors on 469 // `Device` are okay to call. 470 let dev = unsafe { Device::from_raw(phydev) }; 471 T::link_change_notify(dev); 472 } 473 } 474 475 /// Driver structure for a particular PHY type. 476 /// 477 /// Wraps the kernel's [`struct phy_driver`]. 478 /// This is used to register a driver for a particular PHY type with the kernel. 479 /// 480 /// # Invariants 481 /// 482 /// `self.0` is always in a valid state. 483 /// 484 /// [`struct phy_driver`]: srctree/include/linux/phy.h 485 #[repr(transparent)] 486 pub struct DriverVTable(Opaque<bindings::phy_driver>); 487 488 // SAFETY: `DriverVTable` doesn't expose any &self method to access internal data, so it's safe to 489 // share `&DriverVTable` across execution context boundaries. 490 unsafe impl Sync for DriverVTable {} 491 492 /// Creates a [`DriverVTable`] instance from [`Driver`]. 493 /// 494 /// This is used by [`module_phy_driver`] macro to create a static array of `phy_driver`. 495 /// 496 /// [`module_phy_driver`]: crate::module_phy_driver 497 pub const fn create_phy_driver<T: Driver>() -> DriverVTable { 498 // INVARIANT: All the fields of `struct phy_driver` are initialized properly. 499 DriverVTable(Opaque::new(bindings::phy_driver { 500 name: T::NAME.as_char_ptr().cast_mut(), 501 flags: T::FLAGS, 502 phy_id: T::PHY_DEVICE_ID.id(), 503 phy_id_mask: T::PHY_DEVICE_ID.mask_as_int(), 504 soft_reset: if T::HAS_SOFT_RESET { 505 Some(Adapter::<T>::soft_reset_callback) 506 } else { 507 None 508 }, 509 probe: if T::HAS_PROBE { 510 Some(Adapter::<T>::probe_callback) 511 } else { 512 None 513 }, 514 get_features: if T::HAS_GET_FEATURES { 515 Some(Adapter::<T>::get_features_callback) 516 } else { 517 None 518 }, 519 match_phy_device: if T::HAS_MATCH_PHY_DEVICE { 520 Some(Adapter::<T>::match_phy_device_callback) 521 } else { 522 None 523 }, 524 suspend: if T::HAS_SUSPEND { 525 Some(Adapter::<T>::suspend_callback) 526 } else { 527 None 528 }, 529 resume: if T::HAS_RESUME { 530 Some(Adapter::<T>::resume_callback) 531 } else { 532 None 533 }, 534 config_aneg: if T::HAS_CONFIG_ANEG { 535 Some(Adapter::<T>::config_aneg_callback) 536 } else { 537 None 538 }, 539 read_status: if T::HAS_READ_STATUS { 540 Some(Adapter::<T>::read_status_callback) 541 } else { 542 None 543 }, 544 read_mmd: if T::HAS_READ_MMD { 545 Some(Adapter::<T>::read_mmd_callback) 546 } else { 547 None 548 }, 549 write_mmd: if T::HAS_WRITE_MMD { 550 Some(Adapter::<T>::write_mmd_callback) 551 } else { 552 None 553 }, 554 link_change_notify: if T::HAS_LINK_CHANGE_NOTIFY { 555 Some(Adapter::<T>::link_change_notify_callback) 556 } else { 557 None 558 }, 559 // SAFETY: The rest is zeroed out to initialize `struct phy_driver`, 560 // sets `Option<&F>` to be `None`. 561 ..unsafe { core::mem::MaybeUninit::<bindings::phy_driver>::zeroed().assume_init() } 562 })) 563 } 564 565 /// Driver implementation for a particular PHY type. 566 /// 567 /// This trait is used to create a [`DriverVTable`]. 568 #[vtable] 569 pub trait Driver { 570 /// Defines certain other features this PHY supports. 571 /// It is a combination of the flags in the [`flags`] module. 572 const FLAGS: u32 = 0; 573 574 /// The friendly name of this PHY type. 575 const NAME: &'static CStr; 576 577 /// This driver only works for PHYs with IDs which match this field. 578 /// The default id and mask are zero. 579 const PHY_DEVICE_ID: DeviceId = DeviceId::new_with_custom_mask(0, 0); 580 581 /// Issues a PHY software reset. 582 fn soft_reset(_dev: &mut Device) -> Result { 583 build_error!(VTABLE_DEFAULT_ERROR) 584 } 585 586 /// Sets up device-specific structures during discovery. 587 fn probe(_dev: &mut Device) -> Result { 588 build_error!(VTABLE_DEFAULT_ERROR) 589 } 590 591 /// Probes the hardware to determine what abilities it has. 592 fn get_features(_dev: &mut Device) -> Result { 593 build_error!(VTABLE_DEFAULT_ERROR) 594 } 595 596 /// Returns true if this is a suitable driver for the given phydev. 597 /// If not implemented, matching is based on [`Driver::PHY_DEVICE_ID`]. 598 fn match_phy_device(_dev: &Device) -> bool { 599 false 600 } 601 602 /// Configures the advertisement and resets auto-negotiation 603 /// if auto-negotiation is enabled. 604 fn config_aneg(_dev: &mut Device) -> Result { 605 build_error!(VTABLE_DEFAULT_ERROR) 606 } 607 608 /// Determines the negotiated speed and duplex. 609 fn read_status(_dev: &mut Device) -> Result<u16> { 610 build_error!(VTABLE_DEFAULT_ERROR) 611 } 612 613 /// Suspends the hardware, saving state if needed. 614 fn suspend(_dev: &mut Device) -> Result { 615 build_error!(VTABLE_DEFAULT_ERROR) 616 } 617 618 /// Resumes the hardware, restoring state if needed. 619 fn resume(_dev: &mut Device) -> Result { 620 build_error!(VTABLE_DEFAULT_ERROR) 621 } 622 623 /// Overrides the default MMD read function for reading a MMD register. 624 fn read_mmd(_dev: &mut Device, _devnum: u8, _regnum: u16) -> Result<u16> { 625 build_error!(VTABLE_DEFAULT_ERROR) 626 } 627 628 /// Overrides the default MMD write function for writing a MMD register. 629 fn write_mmd(_dev: &mut Device, _devnum: u8, _regnum: u16, _val: u16) -> Result { 630 build_error!(VTABLE_DEFAULT_ERROR) 631 } 632 633 /// Callback for notification of link change. 634 fn link_change_notify(_dev: &mut Device) {} 635 } 636 637 /// Registration structure for PHY drivers. 638 /// 639 /// Registers [`DriverVTable`] instances with the kernel. They will be unregistered when dropped. 640 /// 641 /// # Invariants 642 /// 643 /// The `drivers` slice are currently registered to the kernel via `phy_drivers_register`. 644 pub struct Registration { 645 drivers: Pin<&'static mut [DriverVTable]>, 646 } 647 648 // SAFETY: The only action allowed in a `Registration` instance is dropping it, which is safe to do 649 // from any thread because `phy_drivers_unregister` can be called from any thread context. 650 unsafe impl Send for Registration {} 651 652 impl Registration { 653 /// Registers a PHY driver. 654 pub fn register( 655 module: &'static crate::ThisModule, 656 drivers: Pin<&'static mut [DriverVTable]>, 657 ) -> Result<Self> { 658 if drivers.is_empty() { 659 return Err(code::EINVAL); 660 } 661 // SAFETY: The type invariants of [`DriverVTable`] ensure that all elements of 662 // the `drivers` slice are initialized properly. `drivers` will not be moved. 663 // So it's just an FFI call. 664 to_result(unsafe { 665 bindings::phy_drivers_register(drivers[0].0.get(), drivers.len().try_into()?, module.0) 666 })?; 667 // INVARIANT: The `drivers` slice is successfully registered to the kernel via `phy_drivers_register`. 668 Ok(Registration { drivers }) 669 } 670 } 671 672 impl Drop for Registration { 673 fn drop(&mut self) { 674 // SAFETY: The type invariants guarantee that `self.drivers` is valid. 675 // So it's just an FFI call. 676 unsafe { 677 bindings::phy_drivers_unregister(self.drivers[0].0.get(), self.drivers.len() as i32) 678 }; 679 } 680 } 681 682 /// An identifier for PHY devices on an MDIO/MII bus. 683 /// 684 /// Represents the kernel's `struct mdio_device_id`. This is used to find an appropriate 685 /// PHY driver. 686 #[repr(transparent)] 687 #[derive(Clone, Copy)] 688 pub struct DeviceId(bindings::mdio_device_id); 689 690 impl DeviceId { 691 /// Creates a new instance with the exact match mask. 692 pub const fn new_with_exact_mask(id: u32) -> Self { 693 Self(bindings::mdio_device_id { 694 phy_id: id, 695 phy_id_mask: DeviceMask::Exact.as_int(), 696 }) 697 } 698 699 /// Creates a new instance with the model match mask. 700 pub const fn new_with_model_mask(id: u32) -> Self { 701 Self(bindings::mdio_device_id { 702 phy_id: id, 703 phy_id_mask: DeviceMask::Model.as_int(), 704 }) 705 } 706 707 /// Creates a new instance with the vendor match mask. 708 pub const fn new_with_vendor_mask(id: u32) -> Self { 709 Self(bindings::mdio_device_id { 710 phy_id: id, 711 phy_id_mask: DeviceMask::Vendor.as_int(), 712 }) 713 } 714 715 /// Creates a new instance with a custom match mask. 716 pub const fn new_with_custom_mask(id: u32, mask: u32) -> Self { 717 Self(bindings::mdio_device_id { 718 phy_id: id, 719 phy_id_mask: DeviceMask::Custom(mask).as_int(), 720 }) 721 } 722 723 /// Creates a new instance from [`Driver`]. 724 pub const fn new_with_driver<T: Driver>() -> Self { 725 T::PHY_DEVICE_ID 726 } 727 728 /// Get the MDIO device's PHY ID. 729 pub const fn id(&self) -> u32 { 730 self.0.phy_id 731 } 732 733 /// Get the MDIO device's match mask. 734 pub const fn mask_as_int(&self) -> u32 { 735 self.0.phy_id_mask 736 } 737 738 // macro use only 739 #[doc(hidden)] 740 pub const fn mdio_device_id(&self) -> bindings::mdio_device_id { 741 self.0 742 } 743 } 744 745 // SAFETY: `DeviceId` is a `#[repr(transparent)]` wrapper of `struct mdio_device_id` 746 // and does not add additional invariants, so it's safe to transmute to `RawType`. 747 unsafe impl RawDeviceId for DeviceId { 748 type RawType = bindings::mdio_device_id; 749 } 750 751 enum DeviceMask { 752 Exact, 753 Model, 754 Vendor, 755 Custom(u32), 756 } 757 758 impl DeviceMask { 759 const MASK_EXACT: u32 = !0; 760 const MASK_MODEL: u32 = !0 << 4; 761 const MASK_VENDOR: u32 = !0 << 10; 762 763 const fn as_int(&self) -> u32 { 764 match self { 765 DeviceMask::Exact => Self::MASK_EXACT, 766 DeviceMask::Model => Self::MASK_MODEL, 767 DeviceMask::Vendor => Self::MASK_VENDOR, 768 DeviceMask::Custom(mask) => *mask, 769 } 770 } 771 } 772 773 /// Declares a kernel module for PHYs drivers. 774 /// 775 /// This creates a static array of kernel's `struct phy_driver` and registers it. 776 /// This also corresponds to the kernel's `MODULE_DEVICE_TABLE` macro, which embeds the information 777 /// for module loading into the module binary file. Every driver needs an entry in `device_table`. 778 /// 779 /// # Examples 780 /// 781 /// ``` 782 /// # mod module_phy_driver_sample { 783 /// use kernel::c_str; 784 /// use kernel::net::phy::{self, DeviceId}; 785 /// use kernel::prelude::*; 786 /// 787 /// kernel::module_phy_driver! { 788 /// drivers: [PhySample], 789 /// device_table: [ 790 /// DeviceId::new_with_driver::<PhySample>() 791 /// ], 792 /// name: "rust_sample_phy", 793 /// authors: ["Rust for Linux Contributors"], 794 /// description: "Rust sample PHYs driver", 795 /// license: "GPL", 796 /// } 797 /// 798 /// struct PhySample; 799 /// 800 /// #[vtable] 801 /// impl phy::Driver for PhySample { 802 /// const NAME: &'static CStr = c_str!("PhySample"); 803 /// const PHY_DEVICE_ID: phy::DeviceId = phy::DeviceId::new_with_exact_mask(0x00000001); 804 /// } 805 /// # } 806 /// ``` 807 /// 808 /// This expands to the following code: 809 /// 810 /// ```ignore 811 /// use kernel::c_str; 812 /// use kernel::net::phy::{self, DeviceId}; 813 /// use kernel::prelude::*; 814 /// 815 /// struct Module { 816 /// _reg: ::kernel::net::phy::Registration, 817 /// } 818 /// 819 /// module! { 820 /// type: Module, 821 /// name: "rust_sample_phy", 822 /// authors: ["Rust for Linux Contributors"], 823 /// description: "Rust sample PHYs driver", 824 /// license: "GPL", 825 /// } 826 /// 827 /// struct PhySample; 828 /// 829 /// #[vtable] 830 /// impl phy::Driver for PhySample { 831 /// const NAME: &'static CStr = c_str!("PhySample"); 832 /// const PHY_DEVICE_ID: phy::DeviceId = phy::DeviceId::new_with_exact_mask(0x00000001); 833 /// } 834 /// 835 /// const _: () = { 836 /// static mut DRIVERS: [::kernel::net::phy::DriverVTable; 1] = 837 /// [::kernel::net::phy::create_phy_driver::<PhySample>()]; 838 /// 839 /// impl ::kernel::Module for Module { 840 /// fn init(module: &'static ::kernel::ThisModule) -> Result<Self> { 841 /// let drivers = unsafe { &mut DRIVERS }; 842 /// let mut reg = ::kernel::net::phy::Registration::register( 843 /// module, 844 /// ::core::pin::Pin::static_mut(drivers), 845 /// )?; 846 /// Ok(Module { _reg: reg }) 847 /// } 848 /// } 849 /// }; 850 /// 851 /// const N: usize = 1; 852 /// 853 /// const TABLE: ::kernel::device_id::IdArray<::kernel::net::phy::DeviceId, (), N> = 854 /// ::kernel::device_id::IdArray::new_without_index([ 855 /// ::kernel::net::phy::DeviceId( 856 /// ::kernel::bindings::mdio_device_id { 857 /// phy_id: 0x00000001, 858 /// phy_id_mask: 0xffffffff, 859 /// }), 860 /// ]); 861 /// 862 /// ::kernel::module_device_table!("mdio", phydev, TABLE); 863 /// ``` 864 #[macro_export] 865 macro_rules! module_phy_driver { 866 (@replace_expr $_t:tt $sub:expr) => {$sub}; 867 868 (@count_devices $($x:expr),*) => { 869 0usize $(+ $crate::module_phy_driver!(@replace_expr $x 1usize))* 870 }; 871 872 (@device_table [$($dev:expr),+]) => { 873 const N: usize = $crate::module_phy_driver!(@count_devices $($dev),+); 874 875 const TABLE: $crate::device_id::IdArray<$crate::net::phy::DeviceId, (), N> = 876 $crate::device_id::IdArray::new_without_index([ $(($dev,())),+, ]); 877 878 $crate::module_device_table!("mdio", phydev, TABLE); 879 }; 880 881 (drivers: [$($driver:ident),+ $(,)?], device_table: [$($dev:expr),+ $(,)?], $($f:tt)*) => { 882 struct Module { 883 _reg: $crate::net::phy::Registration, 884 } 885 886 $crate::prelude::module! { 887 type: Module, 888 $($f)* 889 } 890 891 const _: () = { 892 static mut DRIVERS: [$crate::net::phy::DriverVTable; 893 $crate::module_phy_driver!(@count_devices $($driver),+)] = 894 [$($crate::net::phy::create_phy_driver::<$driver>()),+]; 895 896 impl $crate::Module for Module { 897 fn init(module: &'static $crate::ThisModule) -> Result<Self> { 898 // SAFETY: The anonymous constant guarantees that nobody else can access 899 // the `DRIVERS` static. The array is used only in the C side. 900 let drivers = unsafe { &mut DRIVERS }; 901 let mut reg = $crate::net::phy::Registration::register( 902 module, 903 ::core::pin::Pin::static_mut(drivers), 904 )?; 905 Ok(Module { _reg: reg }) 906 } 907 } 908 }; 909 910 $crate::module_phy_driver!(@device_table [$($dev),+]); 911 } 912 } 913