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

Question

Created 1w

Replies 1

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

5d

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