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