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}