com.apple.developer.driverkit.family.hid.virtual.device: documented, but no way to request it — superseded by CoreHID?

Question

Created 1w

Replies 3

Boosts 0

Participants 2

The entitlement documentation page for com.apple.developer.driverkit.family.hid.virtual.device says "To request this entitlement, fill out the request form." I can't find any way to actually request it.

In Certificates, Identifiers & Profiles there is no row for that key anywhere — not on an App ID's Capabilities tab, and not under Capability Requests. Capability Requests does list these, with the entitlement key shown in each info tooltip:

DriverKit Transport HID — com.apple.developer.driverkit.transport.hid
DriverKit Family HID Device — com.apple.developer.driverkit.family.hid.device
DriverKit HID EventService — com.apple.developer.driverkit.family.hid.eventservice
DriverKit UserClient Access — com.apple.developer.driverkit.userclient-access
HID Virtual Device — com.apple.developer.hid.virtual.device

So the only virtual-HID entry that exists in the portal is the CoreHID one.

What I've built: a DriverKit dext that publishes a software-only HID game controller (no physical bus), so a macOS app can synthesise gamepad input for games that require a real controller. It builds against the DriverKit SDK and is signed. Its entitlements are com.apple.developer.driverkit, .transport.hid and .family.hid.virtual.device. The host-to-dext control channel is a vendor Feature report rather than a custom IOUserClient, so it needs no userclient-access.

Questions:

Is com.apple.developer.driverkit.family.hid.virtual.device still grantable? If a dext can no longer declare it for distribution, I would rather rebuild on CoreHID's HIDVirtualDevice now than keep building against a key I can't ship.
If the DriverKit path is still supported for a virtual HID gamepad, what is the correct complete entitlement group? Karabiner-DriverKit-VirtualHIDDevice ships with com.apple.developer.driverkit + .transport.hid + .family.hid.device + .family.hid.eventservice + com.apple.developer.hid.virtual.device — i.e. a DriverKit dext holding the CoreHID virtual-device entitlement, and no .family.hid.virtual.device at all. Is that the supported shape?
If .family.hid.virtual.device has been retired, should its documentation page be updated? Happy to file a Feedback if that's the right route.

Not a status request: I do have a Virtual HID request queued and the portal shows it as Submitted, so I'm content to wait. I'd just rather find out now whether it's queued against the right key for what I've built.

Answer 1

DTS Engineer OP

Apple

1w

Is com.apple.developer.driverkit.family.hid.virtual.device still grantable?

That's a great question, as I'm not sure it's even functional, much less grantable. I'm still looking into this, but my initial read of our code is that this entitlement does absolutely nothing and that's been true for a significant period of time. I'm also confused because it's not clear to me how this would ever have worked, as the entitlement checks this implies would be very different than the standard DEXT set.

If .family.hid.virtual.device has been retired, should its documentation page be updated? Happy to file a Feedback if that's the right route.

Yes, please file a bug on this and then post the bug number back here.

What I've built: a DriverKit DEXT that publishes a software-only HID game controller (no physical bus), so a macOS app can synthesise gamepad input for games that require a real controller. It builds against the DriverKit SDK and is signed.

Signed how? If you're using the dev-only entitlements, have you tried removing ".family.hid.virtual.device" from your Entitlement.plist? I suspect you'll find that your DEXT continues to work fine, because you never actually needed it.

Related to that point:

DriverKit DEXT holding the CoreHID virtual-device entitlement

DEXTs should generally only include DriverKit specific entitlements. I don’t think including the CoreHID entitlement in a DEXT does anything.

If the DriverKit path is still supported for a virtual HID gamepad, what is the correct complete entitlement group?

I haven't spent as much time with the HID Family as I have with other families, but I think you'd just need the entitlements that correspond to your HID classes you use.

Having said that:

If a DEXT can no longer declare it for distribution, I would rather rebuild on CoreHID's HIDVirtualDevice now than keep building against a key I can't ship.

...I also have NO idea why anyone would choose to implement a virtual device using a DEXT. The basic architecture virtual devices use is:

A kernel component which creates HID devices.
A user client which is used to send commands into the kernel component.
A user-space process which uses #2 to control the behavior of #1.

...and CoreHID's virtual device implements 1 & 2, allowing you to only implement #3. It's entirely possible I'm overlooking some critical detail or complication, but as far as I can tell, building a DEXT for this simply means a lot of extra work with no meaningful benefit. My current assumption is that the reason DEXT-based implementations are relatively common is simply that they were written before the introduction of the CoreHID virtual device API.

__
Kevin Elliott
DTS Engineer, CoreOS/Hardware

Answer 2

MasonX OP

1w

Filed the documentation issue as FB24156089.

On signing: the prototype was code-signed with an Apple Development identity, but I have not runtime-activated the DEXT, so I can't establish that .family.hid.virtual.device is required. Based on your guidance, I’m dropping the DEXT path and will use CoreHID if we pursue a virtual HID device.

Thank you.

Answer 3

DTS Engineer OP

Apple

6d

Following up on a few things:

Filed the documentation issue as FB24156089.

Perfect, thank you.

I don't know when the documentation will be updated, but I can confirm that "com.apple.developer.driverkit.family.hid.virtual.device" is not a valid entitlement and has no useful role on our platform. It's not clear to me exactly how it happened, but my best guess is that it was added into the portal by accident, likely when all of the original DriverKit entitlements were introduced, and then overlooked until now. It does appear to have been granted to a few external developers (hence the case you found), but that appears to have been part of a general grant and not a specific "choice". Critically, it doesn't appear that it ever actually "done" anything.

That leads to here:

On signing: the prototype was code-signed with an Apple Development identity, but I have not runtime-activated the DEXT, so I can't establish that .family.hid.virtual.device is required.

The HID family has a large number of entitlements and a lack of clear documentation about exactly what each does, which has led some developers to just include whatever entitlements "seem" applicable and then ship whatever works. That doesn't cause any immediate issue, as the system just ignores any entitlements that aren't relevant, but it isn't a great practice. I'm working on a post that will clarify exactly how each entitlement should be used and I'll post a link here once it's done.

Based on your guidance, I’m dropping the DEXT path and will use CoreHID if we pursue a virtual HID device.

Yes, that would be my general suggestion. I actually asked the HID engineering lead about this yesterday:

...I also have NO idea why anyone would choose to implement a virtual device using a DEXT.

...and he doesn't know either. They activate differently but otherwise should provide identical capabilities. Indeed, the MAIN reason CoreHID implemented its virtual device APIs was that people didn't need to write DEXTs.

__
Kevin Elliott
DTS Engineer, CoreOS/Hardware