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