kernel/net/
phy.rs

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
9use crate::{error::*, prelude::*, types::Opaque};
10use core::{marker::PhantomData, ptr::addr_of_mut};
11
12pub 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)]
22pub 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.
44pub 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)]
74pub struct Device(Opaque<bindings::phy_device>);
75
76impl 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) == u64::from(bindings::AUTONEG_ENABLE)
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
284impl 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`].
295pub 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.
307struct Adapter<T: Driver> {
308    _p: PhantomData<T>,
309}
310
311impl<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).into()
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)]
486pub 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.
490unsafe 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
497pub 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]
569pub 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`.
644pub 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.
650unsafe impl Send for Registration {}
651
652impl 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
672impl 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.
686pub struct DeviceId {
687    id: u32,
688    mask: DeviceMask,
689}
690
691impl 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
744enum DeviceMask {
745    Exact,
746    Model,
747    Vendor,
748    Custom(u32),
749}
750
751impl 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]
859macro_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}