UDBP(4)

📦 version 12.2, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble, ubuntu questing, ubuntu resolute, ubuntu stonking

💖 UDBP — USB Double Bulk Pipe driver 💖

okay bestie, sit down, hydrate, because we're about to talk about udbp, a lil driver from the Kernel Interfaces Manual section (that's section 4, iykyk). it's the thing that makes two computers hold hands over a USB cable and go "hi bestie" to each other. no cap. 🫶

✨ NAME ✨

udbp — the USB Double Bulk Pipe driver. that's it, that's the name, it's giving exactly what it says on the tin. 💅

🎀 SYNOPSIS 🎀

so like, you want this driver in your kernel? two ways, babe. either you bake it in at compile time by putting this line in your kernel configuration file:

device udbp

or — my personal fave — you load it as a module at boot time by putting this line in loader.conf(5):

udbp_load="YES"

pick your fighter. both slay. ✨

🌸 DESCRIPTION 🌸

okay so the udbp driver is what you use for host-to-host cables — the ones that contain at least two bulk pipes, one for each direction, because healthy communication goes both ways obviously 💖. typically this covers cables that are branded for use with Windows USB Easy Transfer, plus a whole bunch of cables built on the Prolific PL2xx1 series of USB bridge chips. and if you want the full tea on which cables actually work, there's a useful (but like, non-comprehensive, she's not claiming to be the whole list) rundown of compatible USB host cables down in the “SEE ALSO” section below. 👀

⚠️ important bestie: it requires netgraph(4) to be available. you can do that either by adding options NETGRAPH to your kernel configuration file, or by loading netgraph(4) as a module — either from /boot/loader.conf or straight from the command line — and you gotta do it before the udbp module. order matters, she's not flexible about this one. 😭

🌈 EXAMPLES 🌈

here's the actual group-chat receipts, copy-paste away:

options NETGRAPH
device udbp

this one adds the udbp driver to the kernel. classic. 💅

kldload netgraph
kldload udbp

this one loads the netgraph(4) module and then the udbp driver. see how netgraph goes first? told you. 🫶

ngctl mkpeer udbp0: eiface data ether
ifconfig ngeth0 ether aa:dd:xx:xx:xx
ifconfig ngeth0 inet 169.254.x.x/16

this creates a new Ethernet network interface node and connects its ether hook to the data hook of the udbp driver. it's giving networking, it's giving main character energy. ✨

and the why? this enables FreeBSD to communicate with a Linux peer (like, e.g. using the plusb driver). the Linux node should be configured to prefer link-local IPv4 addresses — e.g. using Network Manager in Debian and Red Hat derived distributions. so cute when the two of them get along. 🥹

ngl tho, here's the fine print: whilst both FreeBSD and Linux are able to interoperate by loosely following CDC EEM 1.0 in their behaviour, neither implementation has been expressly designed to follow its specification. it's vibes-based compliance, bestie. 💀

🦋 SEE ALSO 🦋

and the actual academic reading list, because we cite our sources in this house:

🧚 CAVEATS 🧚

okay so let's have the talk. 🫶

the point-to-point nature and the extra latency of USB host-host links makes them unsuitable as a "drop-in" replacement for an Ethernet LAN. like, she's not that girl and she's not pretending to be. for a USB 3.0 SuperSpeed cable, latency is comparable to 100BaseTX Ethernet — but often worse 😭 — with throughput comparable to 2.5GBASE-T.

but wait, don't count her out!! 💖 their energy efficiency makes them genuinely attractive for embedded applications. a Plugable PL27A1 cable claims 24mA of USB3 bus power, compared to 150mA for a typical USB 3.0 to Gigabit Ethernet interface. that's a glow-up fr fr. ⭐

💜 HISTORY 💜

the udbp driver first appeared in FreeBSD 5.0. she's been iconic since day one, no notes. 👑

💀 BUGS 💀

bestie, we keep it real here: the udbp driver does not support the special packets described in section 5.1 of the CDC EEM specification. that's the whole bug. that's the tea. 🙈

🍓 AUTHORS 🍓

the udbp driver was written by:

  • Doug Ambrisko <ambrisko@whistle.com>
  • Julian Elischer <julian@FreeBSD.org>
  • Nick Hibma <n_hibma@FreeBSD.org>

and this manual page was written by Nick Hibma <n_hibma@FreeBSD.org> and updated by Bruce Simpson <bms@FreeBSD.org>. give them their flowers, they earned them. 💐

okay that's the whole page, mwah 💋 — this beauty came out of the Debian side of the world, dated October 20, 2017. go forth and connect your lil computers. you're gonna do great. 🫶✨

📦 where this page comes from