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::{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::as_ref(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 pub struct DeviceId { 687 id: u32, 688 mask: DeviceMask, 689 } 690 691 impl DeviceId { 692 /// Creates a new instance with the exact match mask. 693 pub const fn new_with_exact_mask(id: u32) -> Self { 694 DeviceId { 695 id, 696 mask: DeviceMask::Exact, 697 } 698 } 699 700 /// Creates a new instance with the model match mask. 701 pub const fn new_with_model_mask(id: u32) -> Self { 702 DeviceId { 703 id, 704 mask: DeviceMask::Model, 705 } 706 } 707 708 /// Creates a new instance with the vendor match mask. 709 pub const fn new_with_vendor_mask(id: u32) -> Self { 710 DeviceId { 711 id, 712 mask: DeviceMask::Vendor, 713 } 714 } 715 716 /// Creates a new instance with a custom match mask. 717 pub const fn new_with_custom_mask(id: u32, mask: u32) -> Self { 718 DeviceId { 719 id, 720 mask: DeviceMask::Custom(mask), 721 } 722 } 723 724 /// Creates a new instance from [`Driver`]. 725 pub const fn new_with_driver<T: Driver>() -> Self { 726 T::PHY_DEVICE_ID 727 } 728 729 /// Get a `mask` as u32. 730 pub const fn mask_as_int(&self) -> u32 { 731 self.mask.as_int() 732 } 733 734 // macro use only 735 #[doc(hidden)] 736 pub const fn mdio_device_id(&self) -> bindings::mdio_device_id { 737 bindings::mdio_device_id { 738 phy_id: self.id, 739 phy_id_mask: self.mask.as_int(), 740 } 741 } 742 } 743 744 enum DeviceMask { 745 Exact, 746 Model, 747 Vendor, 748 Custom(u32), 749 } 750 751 impl DeviceMask { 752 const MASK_EXACT: u32 = !0; 753 const MASK_MODEL: u32 = !0 << 4; 754 const MASK_VENDOR: u32 = !0 << 10; 755 756 const fn as_int(&self) -> u32 { 757 match self { 758 DeviceMask::Exact => Self::MASK_EXACT, 759 DeviceMask::Model => Self::MASK_MODEL, 760 DeviceMask::Vendor => Self::MASK_VENDOR, 761 DeviceMask::Custom(mask) => *mask, 762 } 763 } 764 } 765 766 /// Declares a kernel module for PHYs drivers. 767 /// 768 /// This creates a static array of kernel's `struct phy_driver` and registers it. 769 /// This also corresponds to the kernel's `MODULE_DEVICE_TABLE` macro, which embeds the information 770 /// for module loading into the module binary file. Every driver needs an entry in `device_table`. 771 /// 772 /// # Examples 773 /// 774 /// ``` 775 /// # mod module_phy_driver_sample { 776 /// use kernel::c_str; 777 /// use kernel::net::phy::{self, DeviceId}; 778 /// use kernel::prelude::*; 779 /// 780 /// kernel::module_phy_driver! { 781 /// drivers: [PhySample], 782 /// device_table: [ 783 /// DeviceId::new_with_driver::<PhySample>() 784 /// ], 785 /// name: "rust_sample_phy", 786 /// authors: ["Rust for Linux Contributors"], 787 /// description: "Rust sample PHYs driver", 788 /// license: "GPL", 789 /// } 790 /// 791 /// struct PhySample; 792 /// 793 /// #[vtable] 794 /// impl phy::Driver for PhySample { 795 /// const NAME: &'static CStr = c_str!("PhySample"); 796 /// const PHY_DEVICE_ID: phy::DeviceId = phy::DeviceId::new_with_exact_mask(0x00000001); 797 /// } 798 /// # } 799 /// ``` 800 /// 801 /// This expands to the following code: 802 /// 803 /// ```ignore 804 /// use kernel::c_str; 805 /// use kernel::net::phy::{self, DeviceId}; 806 /// use kernel::prelude::*; 807 /// 808 /// struct Module { 809 /// _reg: ::kernel::net::phy::Registration, 810 /// } 811 /// 812 /// module! { 813 /// type: Module, 814 /// name: "rust_sample_phy", 815 /// authors: ["Rust for Linux Contributors"], 816 /// description: "Rust sample PHYs driver", 817 /// license: "GPL", 818 /// } 819 /// 820 /// struct PhySample; 821 /// 822 /// #[vtable] 823 /// impl phy::Driver for PhySample { 824 /// const NAME: &'static CStr = c_str!("PhySample"); 825 /// const PHY_DEVICE_ID: phy::DeviceId = phy::DeviceId::new_with_exact_mask(0x00000001); 826 /// } 827 /// 828 /// const _: () = { 829 /// static mut DRIVERS: [::kernel::net::phy::DriverVTable; 1] = 830 /// [::kernel::net::phy::create_phy_driver::<PhySample>()]; 831 /// 832 /// impl ::kernel::Module for Module { 833 /// fn init(module: &'static ::kernel::ThisModule) -> Result<Self> { 834 /// let drivers = unsafe { &mut DRIVERS }; 835 /// let mut reg = ::kernel::net::phy::Registration::register( 836 /// module, 837 /// ::core::pin::Pin::static_mut(drivers), 838 /// )?; 839 /// Ok(Module { _reg: reg }) 840 /// } 841 /// } 842 /// }; 843 /// 844 /// const _DEVICE_TABLE: [::kernel::bindings::mdio_device_id; 2] = [ 845 /// ::kernel::bindings::mdio_device_id { 846 /// phy_id: 0x00000001, 847 /// phy_id_mask: 0xffffffff, 848 /// }, 849 /// ::kernel::bindings::mdio_device_id { 850 /// phy_id: 0, 851 /// phy_id_mask: 0, 852 /// }, 853 /// ]; 854 /// #[cfg(MODULE)] 855 /// #[no_mangle] 856 /// static __mod_device_table__mdio__phydev: [::kernel::bindings::mdio_device_id; 2] = _DEVICE_TABLE; 857 /// ``` 858 #[macro_export] 859 macro_rules! module_phy_driver { 860 (@replace_expr $_t:tt $sub:expr) => {$sub}; 861 862 (@count_devices $($x:expr),*) => { 863 0usize $(+ $crate::module_phy_driver!(@replace_expr $x 1usize))* 864 }; 865 866 (@device_table [$($dev:expr),+]) => { 867 // SAFETY: C will not read off the end of this constant since the last element is zero. 868 const _DEVICE_TABLE: [$crate::bindings::mdio_device_id; 869 $crate::module_phy_driver!(@count_devices $($dev),+) + 1] = [ 870 $($dev.mdio_device_id()),+, 871 $crate::bindings::mdio_device_id { 872 phy_id: 0, 873 phy_id_mask: 0 874 } 875 ]; 876 877 #[cfg(MODULE)] 878 #[no_mangle] 879 static __mod_device_table__mdio__phydev: [$crate::bindings::mdio_device_id; 880 $crate::module_phy_driver!(@count_devices $($dev),+) + 1] = _DEVICE_TABLE; 881 }; 882 883 (drivers: [$($driver:ident),+ $(,)?], device_table: [$($dev:expr),+ $(,)?], $($f:tt)*) => { 884 struct Module { 885 _reg: $crate::net::phy::Registration, 886 } 887 888 $crate::prelude::module! { 889 type: Module, 890 $($f)* 891 } 892 893 const _: () = { 894 static mut DRIVERS: [$crate::net::phy::DriverVTable; 895 $crate::module_phy_driver!(@count_devices $($driver),+)] = 896 [$($crate::net::phy::create_phy_driver::<$driver>()),+]; 897 898 impl $crate::Module for Module { 899 fn init(module: &'static $crate::ThisModule) -> Result<Self> { 900 // SAFETY: The anonymous constant guarantees that nobody else can access 901 // the `DRIVERS` static. The array is used only in the C side. 902 let drivers = unsafe { &mut DRIVERS }; 903 let mut reg = $crate::net::phy::Registration::register( 904 module, 905 ::core::pin::Pin::static_mut(drivers), 906 )?; 907 Ok(Module { _reg: reg }) 908 } 909 } 910 }; 911 912 $crate::module_phy_driver!(@device_table [$($dev),+]); 913 } 914 } 915