CGEM(4)

📦 in nixpkgs unstable

💖 cgem(4) — the Cadence GEM Gigabit Ethernet driver, explained by your local Unix bestie 💖

okay so this is a page from the Kernel Interfaces Manual, and it's all about cgem — literally the driver for the Cadence GEM, which stands for Gigabit Ethernet MAC. no cap, it's lowkey iconic. 🦋

✨ NAME ✨

cgem — the Cadence GEM Gigabit Ethernet driver. that's it, that's the name, slay. 👑

🌸 SYNOPSIS 🌸

so if you wanna compile this driver into the kernel (main character energy, no modules), you drop these lines into your kernel config file:

device ether
device miibus
device cgem

that's the whole vibe check. three lines. you got this. 🫶

🎀 DESCRIPTION 🎀

okay so the cgem driver is out here providing support for the Cadence GEM (Gigabit Ethernet MAC). and the Cadence GEM shows up in some SoC (System on a Chip) devices — specifically these icons:

  • the Xilinx Zynq-7000
  • the Xilinx Zynq UltraScale+
  • the SiFive HiFive Unleashed

the cgem driver supports the following media types, bestie:

  • autoselect — turns on autoselection of the media type and options. you can still manually override the autoselected mode using ifconfig(8), or by adding media options to rc.conf(5). yes, you're allowed to be a control freak about it. 💅
  • 10baseT/UTP — sets 10Mbps operation. the ifconfig(8) mediaopt option can also be used to select either full-duplex or half-duplex modes.
  • 100baseTX — sets 100Mbps (Fast Ethernet) operation. the ifconfig(8) mediaopt option can also be used to select either full-duplex or half-duplex modes.
  • 1000baseT — sets 1000Mbps (Gigabit Ethernet) operation over twisted pair. real talk though: the GEM supports 1000Mbps in full-duplex mode only. that's the rule, periodt.

and the cgem driver supports these media options too:

  • full-duplex — force full-duplex operation.
  • half-duplex — force half-duplex operation.

the driver also provides support for TCP/UDP/IP checksum offloading — although it's disabled by default, so don't come for me. 🙈 and the device + driver support 1536-byte frames for VLANs (vlanmtu). cute.

🔥 SYSCTL VARIABLES 🔥

the following variables are available as both sysctl(8) variables and loader(8) tunables. double duty, we stan:

  • dev.cgem.%d.rxbufs — the number of receive buffers allocated to the hardware. the default value is 256. the maximum value is 511. careful though, bestie: if you increase this number while the interface is UP, it will not take effect until the next packet is received. and if you decrease this number while the interface is UP, buffers will not be immediately removed from the receive buffer ring — but the number of buffers will decrease as packets are received until it reaches the new value. so it's giving "eventually", not "instantly". ⭐
  • dev.cgem.%d.rxhangwar — this tunable enables a work-around to recover from receive hangs. the default value is 1. set it to 0 to disable the work-around.

💜 the read-only girlies 💜

the following read-only variables are available as sysctl(8) variables:

  • dev.cgem.%d._rxoverruns — this variable counts the number of receive packet buffer overrun interrupts.
  • dev.cgem.%d._rxnobufs — this variable counts the number of interrupts due to the GEM buffer ring going empty.
  • dev.cgem.%d._rxdmamapfails — this variable is the number of times bus_dmamap_load_mbuf_sg(9) failed in the receive path.
  • dev.cgem.%d._txfull — the number of times the GEM's transmit ring was full.
  • dev.cgem.%d._txdmamapfails — this variable is the number of times bus_dmamap_load_mbuf_sg(9) failed in the transmit path.
  • dev.cgem.%d._txdefrags — this variable is the number of times the driver needed to call m_defrag(9) because a packet queued for transmit had too many DMA segments.
  • dev.cgem.%d._txdefragfails — this variable is the number of times m_defrag(9) failed.

🌈 dev.cgem.%d.stats.* — the hardware flex 🌈

the following variables are useful MAC counters supplied by the hardware. these are literally the receipts:

💫 transmit counters 💫

  • dev.cgem.%d.stats.tx_bytes — a 64-bit counter of the number of bytes transmitted in frames without error.
  • dev.cgem.%d.stats.tx_frames — counter of frames transmitted without error excluding pause frames.
  • dev.cgem.%d.stats.tx_frames_bcast — counter of broadcast frames transmitted without error excluding pause frames.
  • dev.cgem.%d.stats.tx_frames_multi — counter of multicast frames transmitted without error excluding pause frames.
  • dev.cgem.%d.stats.tx_frames_pause — counter of pause frames transmitted without error.
  • dev.cgem.%d.stats.tx_frames_64b — counter of 64 byte frames transmitted without error.
  • dev.cgem.%d.stats.tx_frames_65to127b — counter of 65 to 127 byte frames transmitted without error.
  • dev.cgem.%d.stats.tx_frames_128to255b — counter of 128 to 255 byte frames transmitted without error.
  • dev.cgem.%d.stats.tx_frames_256to511b — counter of 256 to 511 byte frames transmitted without error.
  • dev.cgem.%d.stats.tx_frames_512to1023b — counter of 512 to 1023 byte frames transmitted without error.
  • dev.cgem.%d.stats.tx_frames_1024to1536b — counter of 1024 to 1536 byte frames transmitted without error.
  • dev.cgem.%d.stats.tx_under_runs — counter of frames not transmitted due to a transmit underrun. 💀
  • dev.cgem.%d.stats.tx_single_collisn — counter of frames experiencing a single collision before being successfully transmitted.
  • dev.cgem.%d.stats.tx_multi_collisn — counter of frames experiencing between 2 and 15 collisions before being successfully transmitted.
  • dev.cgem.%d.stats.tx_excsv_collisn — counter of frames that failed to transmit because they experienced 16 collisions.
  • dev.cgem.%d.stats.tx_late_collisn — counter of frames that experienced a late collision.
  • dev.cgem.%d.stats.tx_deferred_frames — counter of frames experiencing deferral due to carrier sense being active on their first attempt at transmission.
  • dev.cgem.%d.stats.tx_carrier_sense_errs — counter of frames transmitted where carrier sense was not seen during transmission, or where carrier sense was deasserted after being asserted in a transmit frame without collision.

🌸 receive counters 🌸

  • dev.cgem.%d.stats.rx_bytes — a 64-bit counter of bytes received without error excluding pause frames.
  • dev.cgem.%d.stats.rx_frames — counter of frames received without error excluding pause frames.
  • dev.cgem.%d.stats.rx_frames_bcast — counter of broadcast frames receive without error excluding pause frames.
  • dev.cgem.%d.stats.rx_frames_multi — counter of multicast frames receive without error excluding pause frames.
  • dev.cgem.%d.stats.rx_frames_pause — counter of pause frames received without error.
  • dev.cgem.%d.stats.rx_frames_64b — counter of 64-byte frames received without error.
  • dev.cgem.%d.stats.rx_frames_65to127b — counter of 65 to 127 byte frames received without error.
  • dev.cgem.%d.stats.rx_frames_128to255b — counter of 128 to 255 byte frames received without error.
  • dev.cgem.%d.stats.rx_frames_256to511b — counter of 256 to 511 byte frames received without error.
  • dev.cgem.%d.stats.rx_frames_512to1023b — counter of 512 to 1023 byte frames received without error.
  • dev.cgem.%d.stats.rx_frames_1024to1536b — counter of 1024 to 1536 byte frames received without error.
  • dev.cgem.%d.stats.rx_frames_undersize — counter of frames received less than 64 bytes in length that do not also have either a CRC error or an alignment error.
  • dev.cgem.%d.stats.rx_frames_oversize — counter of frames received exceeding 1536 bytes and do not also have either a CRC error or an alignment error.
  • dev.cgem.%d.stats.rx_frames_jabber — counter of frames received exceeding 1536 bytes and also have either a CRC error, an alignment error, or a receive symbol error.
  • dev.cgem.%d.stats.rx_frames_fcs_errs — counter of frames received with a bad CRC and are between 64 and 1536 bytes.
  • dev.cgem.%d.stats.rx_frames_length_errs — counter of frames received that are shorter than that extracted from the length field.
  • dev.cgem.%d.stats.rx_symbol_errs — counter of receive symbol errors.
  • dev.cgem.%d.stats.rx_align_errs — counter of received frames that are not an integral number of bytes.
  • dev.cgem.%d.stats.rx_resource_errs — counter of frames successfully receive by the MAC but could not be copied to memory because no receive buffer was available. 😭
  • dev.cgem.%d.stats.rx_overrun_errs — counter of frames that are address recognized but were not copied to memory due to a receive overrun.
  • dev.cgem.%d.stats.rx_frames_ip_hdr_csum_errs — counter of frames discarded due to an incorrect IP header checksum when checksum offloading is enabled.
  • dev.cgem.%d.stats.rx_frames_tcp_csum_errs — counter of frames discarded due to an incorrect TCP checksum when checksum offloading is enabled.
  • dev.cgem.%d.stats.rx_frames_udp_csum_errs — counter of frames discarded due to an incorrect UDP checksum when checksum offloading is enabled.

🦋 SEE ALSO 🦋

and also this absolute tome, iykyk:

Zynq-7000 SoC Technical Reference Manual (Xilinx doc UG585), http://www.xilinx.com/support/documentation/user_guides/ug585-Zynq-7000-TRM.pdf.

⭐ HISTORY ⭐

the cgem device driver first appeared in FreeBSD 10.0. a whole era. 🎀

💅 AUTHORS 💅

the cgem driver and this manual page was written by Thomas Skibo <thomasskibo@yahoo.com>. give him his flowers. 👑

💀 BUGS 💀

okay so this is the part where we're real with each other, bestie. buckle up.

the GEM can perform TCP/UDP/IP checksum offloading. however — and this is the big however — when transmit checksum offloading is enabled, the GEM generates and replaces checksums for all packets it transmits. in a system that is forwarding packets, the device could potentially correct the checksum of packet that was corrupted in transit. that's literally not the vibe. for this reason, checksum offloading is disabled by default but can be enabled using ifconfig(8). so like, think before you toggle. 🙈

when receive checksum offloading is enabled, the device will discard packets with bad TCP/UDP/IP checksums. and plot twist: the bad packets will not be counted in any netstat(1) statistics. there are sysctl(8) variables that count packets discarded by the hardware — see below, they've got you covered. 🔥

and here's the lore: the GEM used in the Zynq-7000 has a bug such that the receiver can potentially freeze up under a high load. the issue is described in sec. 16.7 "Known Issues" of the Zynq-7000 SoC Technical Reference Manual (Xilinx UG585 v1.7). the cgem driver implements the work-around suggested in the manual. it is believed that the bug does not exist in the Zynq UltraScale+ and SiFive SoCs, so the work-around is disabled in those instances and enabled in all others. and if you really wanna turn it off yourself, you can — by setting the dev.cgem.%d.rxhangwar sysctl(8) variable to 0. you do you. 💜

okay that's the whole page, go touch grass and then go configure your NIC 🧚 this was the Debian build, dated January 10, 2021 — mwah, love u, bye! 💖✨🍓

📦 where this page comes from
  • nixpkgs unstable: source
  • Copyright (c) 2014 Thomas Skibo <thomasskibo@yahoo.com>
  • 💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on : a language model's rewrite of the original, under its terms