mac_config(9)

📦 version 7.3.1, in nixpkgs unstable

💅 mac_config(9) — the kernel API glow-up guide 🎀

okay so bestie, welcome to mac_config(9), straight out of the Kernel API Manual. this is the function that configures the MAC for whatever mode and state you're rolling with, and yes you're gonna need to read all of it because the caveats are real 🫶

✨ SYNOPSIS ✨

void mac_config (struct phylink_config *config , unsigned int mode ,
       const struct phylink_link_state *state );

literally just three things in, nothing out. void, no cap.

🌸 ARGUMENTS 🌸

  • config — a pointer to a struct phylink_config. your config bestie 💖
  • mode — one of MLO_AN_FIXED, MLO_AN_PHY, MLO_AN_INBAND. pick your fighter ✨
  • state — a pointer to a struct phylink_link_state. this one's got lore (see below)

💀 DESCRIPTION 💀

⚠️ note note note: not all members of state are valid!! in particular, state->lp_advertising, state->link, and state->an_complete are never guaranteed to be correct. so any mac_config implementation must never reference these fields. like, ever. i'm so serious 😭

okay so this function will only be called to reconfigure the MAC for a "major" change, like in interface mode. it will not be called for changes in speed, duplex, or pause modes, and it will not be called to change the in-band advertisement. so don't come here asking for little tweaks 🎀

🦋 pause settings, explained

in all negotiation modes (as defined by mode), state->pause indicates the pause settings that should be applied, like this:

  • if MLO_PAUSE_AN is not set, MLO_PAUSE_TX and MLO_PAUSE_RX indicate whether the MAC should send pause frames and/or act on received pause frames, respectively.
  • otherwise, the results of in-band negotiation/status from the MAC PCS should be used to control the MAC pause mode settings. iykyk 💅

👑 the action depends on the currently selected mode

🌈 MLO_AN_FIXED, MLO_AN_PHY

configure for non-inband negotiation mode, where the link settings are completely communicated via mac_link_up. the physical link protocol from the MAC is specified by state->interface ⭐

state->advertising may be used, but is not required. (optional queen behavior)

older drivers (prior to the mac_link_up change) may use state->speed, state->duplex and state->pause to configure the MAC, but this is deprecated — such drivers should be converted to use mac_link_up. like, it's giving legacy, and not in a cute way 🙈

other members of state must be ignored.

  • valid state members: interface, advertising
  • deprecated state members: speed, duplex, pause

🧚 MLO_AN_INBAND

place the link in an inband negotiation mode (such as 802.3z 1000base-X or Cisco SGMII mode, depending on the state->interface mode). in both cases, link state management (whether the link is up or not) is performed by the MAC, and reported via the pcs_get_state callback. changes in link state must be made by calling phylink_mac_change 🔥

interface mode specific details are mentioned below 👇

if in 802.3z mode: the link speed is fixed, dependent on the state->interface. duplex and pause modes are negotiated via the in-band configuration word. advertised pause modes are set according to state->advertising. ⚠️ beware of MACs which only support full duplex at gigabit and higher speeds. beware!! fr fr

if in Cisco SGMII mode: the link speed and duplex mode are passed in the serial bitstream 16-bit configuration word, and the MAC should be configured to read these bits and acknowledge the configuration word. nothing is advertised by the MAC. the MAC is responsible for reading the configuration word and configuring itself accordingly. main character energy, honestly 👑

  • valid state members: interface, pause, advertising 💜

🍓 the update rule (this one matters)

implementations are expected to update the MAC to reflect the requested settings — i.o.w., if nothing has changed between two calls, no action is expected. if only flow control settings have changed, flow control should be updated without taking the link down. this "update" behaviour is critical to avoid bouncing the link up status. critical!!! do not bounce the link, bestie, that's so not slay 💀

🎀 SEE ALSO 🎀

and that's the whole page, bestie 🫶 this edition lives in ./include/linux and it's dated October 2026 — so go forth, configure your MAC, and remember: never touch state->lp_advertising, state->link, or state->an_complete. periodt. 💅✨

📦 where this page comes from