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