DriverKit VLAN offload: IOUserNetworkPacket::getVlanTag() always returns false, kFeatureHardwareVlan undocumented

Question

Created 3w

Replies 2

Boosts 2

Participants 2

I've built an open-source DriverKit + NetworkingDriverKit (IOUserNetworkEthernet/Skywalk) driver for a USB 5GbE adapter (AQTION AQC111U chipset). As far as I can tell this is the first public one for real third-party hardware:

github.com/jquirke/AQC111Driver

It's a fully functional driver at this point: RX/TX hardware checksum offload, jumbo frame/MTU control up to 16KB, runtime-controllable diagnostics via a custom IOUserClient, and most recently working 802.1Q VLAN support via macOS's vlan(4) software path.

While attempting to implement hardware offload VLAN support, I ran into what looks like a gap between documentation and the public SDK, and I'd appreciate expert opinion either way before filing Feedback.

The issue:

IOUserNetworkPacket::getVlanTag()/setVlanTag() (DriverKit 24.0+) have a doc comment stating: "Get the Vlan Tag from the packet, where the driver has enabled the kFeatureHardwareVlan capability; for the case that feature is not enabled, this method will return false."

kFeatureHardwareVlan does not appear anywhere in the public NetworkingDriverKit.framework/Headers/ tree confirmed via exhaustive grep, including the full hwAssist/feature-flag enum in IOUserNetworkTypes.h.

I tested every plausible related mechanism exhaustively, with a real device reattach for each combination, to rule out attach-time-only behaviour:

  +------------------------+--------------------------+--------------+-----------+
  | HWAssist bit declared?  | SetSoftwareVlanSupport()| getVlanTag()  | vlan0 MTU |
  +------------------------+--------------------------+--------------+-----------+
  | Yes                                   | true                                     | always false    | 1500      |
  | Yes                                   | false                                    | always false    | 1500      |
  | No                                    | not called                            | always false    | 1496      |
  | No                                    | false                                    | always false     | 1496      |
  +------------------------+--------------------------+--------------+-----------+

none of these combinations gates real 802.1q tag-delivery/demux behavior at all; it seems Vlan support is completely implemented in software on the MacOS side and I have to explicitly program my hardware registers to disable VLAN tagging.

Question: is hardware VLAN tag insert/strip (via getVlanTag()/setVlanTag()) currently reachable from a third-party DriverKit USB Ethernet driver at all? If kFeatureHardwareVlan is real but intentionally withheld from public headers, is there a documented path (entitlement, different NDK version, etc.) to enable it or is this confirmed unreachable without Apple's direct involvement (Feedback/DTS)?

Can share full test logs/methodology if useful.

Answer 1

DTS Engineer OP

Apple

3w

kFeatureHardwareVlan does not appear anywhere in the public NetworkingDriverKit.framework/Headers/ tree, confirmed via exhaustive grep, including the full hwAssist/feature-flag enum in IOUserNetworkTypes.h.

Please file a bug on this and then post the bug number back here once it's filed. I'm not sure what the actual intentions here were, but there are obviously issues with the header doc and implementation.

Question: is hardware VLAN tag insert/strip (via getVlanTag()/setVlanTag()) currently reachable from a third-party DriverKit USB Ethernet driver at all?

No, I don't think so. As far as I can tell, get / setHardwareAssists() were never set up to "filter" their inputs/outputs so that they'll only set or return one of the defined "kIOUserNetworkHWAssist..." bit field values. I don't know why hardware vlan was left out of that set, but I don't think you could set the value even if I told you what the constant itself was.

FYI, if you wanted to try it yourself, the DriverKit headers were somewhat "leaky":

DriverKit Header:

kIOUserNetworkHWAssistSoftwareVlan      = 0x00020000, /* IFNET_VLAN_MTU */

XNU Definition of IFNET_VLAN_MTU:

/* VLAN support */
#define IF_HWASSIST_VLAN_TAGGING        0x00010000      /* supports VLAN tagging, IFNET_VLAN_TAGGING */
#define IF_HWASSIST_VLAN_MTU            0x00020000      /* supports VLAN MTU-sized packet (for software VLAN), IFNET_VLAN_MTU */

...but I think you'll find that we strip the value.

If kFeatureHardwareVlan is real but intentionally withheld from public headers, is there a documented path (entitlement, different NDK version, etc.) to enable it or is this confirmed unreachable without Apple's direct involvement (Feedback/DTS)?

There definitely isn't any special/secret "trick" that will make it work. FYI, if you specifically want us to add support for this, make sure you include the details of why you specifically need "hardware" level support. I don't really know why it was left out, but my guess is that it was basically considered to be more trouble than it was "worth".

__
Kevin Elliott
DTS Engineer, CoreOS/Hardware

Answer 2

jquirke1 OP

1w

Cheers kevin, filed 2 bugs

documentation: FB23530504 the header/doc inconsistency: kFeatureHardwareVlan is referenced in the getVlanTag()/setVlanTag() doc comments in IOUserNetworkPacket.iig but defined nowhere in the public SDK (exhaustive grep: 4 hits, all doc comments).

suggestion: FB23562845, the enhancement request for a public hardware VLAN capability, with the usecase detail you asked for included.

I also ran the experiment you suggested, declaring IF_HWASSIST_VLAN_TAGGING (0x00010000) via getFeatureFlags() on macOS 26.3.1, with live tagged traffic on a vlan(4) interface over the driver:

Alongside kIOUserNetworkHWAssistSoftwareVlan: no behavioral change. getVlanTag() never returns true; tags remain inline in both directions.
Alone: also ignored and the vlan(4) child clamps to MTU 1496, i.e. the unpublished bit doesn't even receive the VLAN-MTU accounting the published bit provides. It's discarded wholesale, not partially honoured.
One refinement to "I think you'll find that we strip the value": in our testing neither SetHardwareAssists (NDK_21) nor the mask-based setHardwareAssists (NDK_22) was ever invoked by the system in any configuration, so nothing gets stripped in a setter; whatever consumes the getFeatureFlags() output simply ignores unknown bits

Empirically our results match your hyptohesis.

On "why hardware-level support": to be clear, software VLAN works and is what we ship and it works. However, our request is about parity and efficiency, not functionality.

This chip does VLAN offload in its RX/Tx descriptors used by both its previous macOS kext (which advertised the iokit equivalent of kIONetworkFeatureHardwareVlan) and the linux driver.

Under D/kit, every tagged frame has the 802.1Q header inline through the data path and the hardware's VLAN filter/strip engine must stay disabled.

since the dataplane API (get/setVlanTag) already shipped, publishing the control-plane capability would let IOKit-era drivers migrate without losing it.

anyway, appreciate your response on this. enjoy your weekend.