Wini2c-ddc Kernel Mode Driver For Mac

As discussed in the chapter Kernel Architecture Overview,OS X provides a kernel extension mechanism as a means of allowingdynamic loading of code into the kernel, without the need to recompileor relink. Because these kernel extensions (KEXTs) provide both modularityand dynamic loadability, they are a natural choice for any relatively self-containedservice that requires access to internal kernel interfaces.

Because KEXTs run in supervisor mode in the kernel’saddress space, they are also harder to write and debug than user-levelmodules, and must conform to strict guidelines. Further, kernelresources are wired(permanently resident in memory) and are thus more costly to usethan resources in a user-space task of equivalent functionality.

I am modifying a monitor controller for a prototype. It would be convenient to send commands to the prototype using DDC/CI. In Windows, I can't find an obvious way to send a DDC/CI command to a 'display dependent device'.

In addition, although memory protection keeps applicationsfrom crashing the system, no such safeguards are in place insidethe kernel. A badly behaved kernel extension in OS X can causeas much trouble as a badly behaved application or extension couldin Mac OS 9.

Kernel Extension Overview. As discussed in the chapter Kernel Architecture Overview, OS X provides a kernel extension mechanism as a means of allowing dynamic loading of code into the kernel, without the need to recompile or relink. Ei2c.sys is part of WINI2C-DDC and developed by Nicomsoft Ltd. According to the ei2c.sys version information. Ei2c.sys's description is ' WINI2C-DDC Kernel Mode Driver ' ei2c.sys is digitally signed by AOC International (Europe) GmbH.

Bugs in KEXTs can have far more severe consequences than bugsin user-level code. For example, a memory access error in a userapplication can, at worst, cause that application to crash. In contrast,a memory access error in a KEXT causes a kernel panic, crashingthe operating system.

Finally, for security reasons, some customersrestrict or don’t permit the use of third-party KEXTs. As a result,use of KEXTs is strongly discouraged in situations where user-level solutionsare feasible. OS X guarantees that threading in applications is just asefficient as threading inside the kernel, so efficiency should notbe an issue. Unless your application requires low-level access tokernel interfaces, you should use a higher level of abstraction whendeveloping code for OS X.

When you are trying to determine if a piece of code shouldbe a KEXT, the default answer is generally no.Even if your code was a system extension in Mac OS 9, that doesnot necessarily mean that it should be a kernel extension in OS X. There are only a few good reasons for a developer to writea kernel extension:

Your codeneeds to take a primary interrupt—that is, something in the (built-in) hardwareneeds to interrupt the CPU and execute a handler.
The primary client of your code is inside the kernel—forexample, a block device whose primary client is a file system.
Your code needs to access kernel interfaces that are not exportedto user space.
Your code has other special requirements that cannot be satisfiedin a user space application.

If your code does not meet any of the above criteria (andpossibly even if it does), you should consider developing it asa library or a user-level daemon, or using one of the user-levelplug-in architectures (such as QuickTimecomponents or the CoreGraphics framework) instead of writing a kernel extension.

If you are writing device drivers or code to support a newvolume format or networking protocol, however, KEXTs may be theonly feasible solution. Fortunately, while KEXTs may be more difficultto write than user-space code, several tools and procedures are availableto enhance the development and debugging process. See Debugging Your KEXT formore information.

This chapter provides a conceptual overview of KEXTs and howto create them. If you are interested in building a simple KEXT,see the Apple tutorials listed in the bibliography. These providestep-by-step instructions for creating a simple, generic KEXT ora basic I/O Kit driver.

Implementation of a KernelExtension (KEXT)

Kernel extensions are implemented asbundles,folders that the Finder treats as single files. See the chapterabout bundles in Mac Technology Overview for a discussion of bundles.The KEXTbundle can contain the following:

Informationproperty list—a text file that describes the contents,settings, and requirements of the KEXT. This file is required. AKEXT bundle need contain nothing more than this file, although mostKEXTs contain one or more kernel modules as well. See the chapterabout software configuration in Mac Technology Overview for further information about propertylists.
KEXT binary—a file in Mach-O format, containing the actualbinary code used by the KEXT. A KEXT binary (also known as a kernelmodule or KMOD)represents the minimum unit of code that can be loaded into thekernel. A KEXT usually contains one KEXT binary. If no KEXT binariesare included, the information property list file must contain areference to another KEXT and change its default settings.
Resources—for example, icons or localizationdictionaries. Resources are optional; they may be useful for a KEXTthat needs to display a dialog or menu. At present, no resourcesare explicitly defined for use with KEXTs.
KEXT bundles—a kext can contain otherKEXTs. This can be used for plug-ins that augment features of aKEXT.

Kernel Extension Dependencies

Any KEXT can declare that it is dependent upon any other KEXT. The developer lists these dependencies in the OSBundleLibraries dictionary in the module’s property list file.

Before a KEXT is loaded, all of its requirements are checked.Those required extensions (and their requirements) are loaded first,iterating back through the lists until there are no more requiredextensions to load. Only after all requirements are met, is therequested KEXT loaded as well.

For example, device drivers (a type of KEXT) are dependentupon (require) certain families (another type of KEXT). When a driveris loaded, its required families are also loaded to provide necessary,common functionality. To ensure that all requirements are met, each devicedriver should list all of its requirements (families and other drivers)in its property list. See the chapter I/O Kit Overview, for an explanationof drivers and families.

It is important to list all dependencies for each KEXT. Ifyour KEXT fails to do so, your KEXT may not load due to unrecognizedsymbols, thus rendering the KEXT useless. Dependencies in KEXTscan be considered analogous to required header files or libraries incode development; in fact, the Kernel Extension Manageruses the standard linker to resolve KEXT requirements.

Building and Testing Your Extension

After creating the necessary property list and C or C++ source files, you use Project Builder tobuild your KEXT. Any errors in the source code are brought to yourattention during the build and you are given the chance to edityour source files and try again.

To test your KEXT, however, you need to leave Project Builderand work in the Terminal application(or in console mode).In console mode, all system messages are written directly to yourscreen, as well as to a log file (/var/log/system.log).If you work in the Terminal application, you must view system messagesin the log file or in the Console application.You also need to login to the root account (or use the su or sudo command), sinceonly the root account can load kernel extensions.

When testing your KEXT, you can load and unload it manually,as well as check the load status. You can use the kextload commandto load any KEXT. A manual page for kextload isincluded in OS X. (On OS X prior to 10.2, you must use the kmodload command instead.)

Note that this command is useful only when developing a KEXT.Eventually, after it has been tested and debugged, you install yourKEXT in one of the standard places (see Installed KEXTs for details).Then, it will be loaded and unloaded automatically at system startupand shutdown or whenever it is needed (such as when a new deviceis detected).

Debugging Your KEXT

KEXT debuggingcan be complicated. Before you can debug a KEXT, you must firstenable kernel debugging, as OS X is not normally configuredto permit debugging the kernel. Only the root account can enablekernel debugging, and you need to reboot OS X for the changesto take effect. (You can use sudo to gainroot privileges if you don’t want to enable a root password.)

Kernel debugging is performed using two OS X computers,called the development or debug host and the debug target. Thesecomputers must be connected over a reliable network connection onthe same subnet (or within a single local network). Specifically, theremust not be any intervening IP routers or other devices that couldmake hardware-based Ethernet addressing impossible.

The KEXT is registered (and loaded and run) on the target.The debugger is launched and run on the debug host. You can alsorebuild your KEXT on the debug host, after you fix any errors youfind.

Debugging must be performed in this fashion because you musttemporarily halt the kernel on the target in order to use the debugger.When you halt the kernel, all other processes on that computer stop.However, a debugger running remotely can continue to run and cancontinue to examine (or modify) the kernel on the target.

Note that bugs in KEXTs may cause the target kernel to freezeor panic. If this happens, you may not be able to continue debugging,even over a remote connection; you have to reboot the target andstart over, setting a breakpoint just before the code where theKEXT crashed and working very carefully up to the crash point.

Developers generally debug KEXTs using gdb,a source-level debugger with a command-line interface. You willneed to work in the Terminal application to run gdb.For detailed information about using gdb,see the documentation included with OS X. You can also use the help commandfrom within gdb.

Some features of gdb areunavailable when debugging KEXTs because of implementation limitations.For example:

You can’tuse gdb to call a functionor method in a KEXT.
You should not use gdb todebug interrupt routines.

The former is largely a barrier introduced by the C++ language.The latter may work in some cases but is not recommended due tothe potential for gdb to interrupt something uponwhich kdp (the kernel shim used by gdb)depends in order to function properly.

Use care that you do not halt the kernel for too long whenyou are debugging (for example, when you set breakpoints). In ashort time, internal inconsistencies can appear that cause the targetkernel to panic or freeze, forcing you to reboot the target.

Additional information about debugging can be found in When Things Go Wrong: Debugging the Kernel.

Installed KEXTs

The Kernel Extension Manager (KEXT Manager) is responsiblefor loading and unloading all installed KEXTs (commands such as kextload areused only during development). Installed KEXTs are dynamically addedto the running OS X kernel as part of the kernel’s addressspace. An installed and enabled KEXT is invoked as needed.

Important: Note that KEXTs are only wrappers (bundles) arounda property list, KEXT binaries (or references to other KEXTs), andoptional resources. The KEXT describes what is to be loaded; itis the KEXT binaries that are actually loaded.

KEXTs are usually installed in the folder /System/Libraries/Extensions.The Kernel Extension Manager (in the form of a daemon, kextd),always checks here. KEXTs can also be installed in ROM or insidean application bundle.

Installing KEXTs in an application bundle allows an applicationto register those KEXTs without the need to install them permanentlyelsewhere within the system hierarchy. This may be more convenientand allows the KEXT to be associated with a specific, running application.When it starts, the application can register the KEXT and, if desired,unregister it on exit.

For example, a network packet sniffer application might employa Network Kernel Extension (NKE). A tape backup application wouldrequire that a tape driver be loaded during the duration of thebackup process. When the application exits, the kernel extension isno longer needed and can be unloaded.

Note that, although the application is responsible for registeringthe KEXT, this is no guarantee that the corresponding KEXTs areactually ever loaded. It is still up to a kernel component, suchas the I/O Kit, to determine a need, such as matching a piece ofhardware to a desired driver, thus causing the appropriate KEXTs(and their dependencies) to be loaded.

Frequently Asked Questions
- Licensing
- Getting help
- Running libusb
- Platform Support

libusb.org, libusbx.org and libusb.info

libusb.org was the original home for libusb project. Now it still exists but the information and code are quite outdated.

libusb.info is the current home page for libusb project.

libusbx was a fork of libusb and libusbx.org is its website. As of 2014.01.26, libusbx project has been fully merged back into libusb and is being discontinued. libusbx.org is no longer related to libusb project.

libusb-win32, libusbK and libusb project

Take note libusb-win32 and libusbK projects are separate projects and both of them use libusb-win32 mailing list for technical support. Unlike libusb which is a cross-platform project, libusb-win32 and libusbK project are both Windows only project.

libusb-win32 project includes libusb0.sys (Windows WDM kernel driver in device driver mode or filter driver mode) and libusb0.dll (libusb-win32 API, library). libusb-win32 API is a superset of the libusb-0.1 API supported by libusb-compat. libusb0.dll supports device using libusb0.sys and libusbK.sys.

libusbK projects includes libusbk.sys (Windows KMDF kernel driver) and libusbK.dll (libusbK API, library). libusbK API is Windows only and libusbk.dll supports device using libusbK.sys, libusb0.sys and WinUSB.

libusb Windows backend can support device using libusbK.sys (and libusb0.sys driver -- not recommended due to issues) through libusbk.dll provided by libusbK project. If libusbk.dll is present, it will use libusbK.dll as the intermediate library to support device using WinUSB driver. If libusbK.dll is not present, then it will directly talk to device using WinUSB using WinUSB API. libusb Windows also supports device using generic HID driver or usbdk driver.

What about usbdk?

usbdk is another open-source generic USB driver. usbdk is a new backend added in libusb-1.0.21 release. The major benefit is that you can keep the existing driver. It supports isochronous transfer as well.

Licensing

What is the libusb license?

libusb is released under version 2.1 of the GNU Lesser General Public License (LGPL).

Can I use libusb in a proprietary application?

You can, as long as you don't modify its source code.
If you modify the source, then you must make any changes you applied to libusb public, and grant others the right to use these changes in their own applications, under the LGPL v2.1 license terms.

Getting help

How can I get help? What is the best practice to describe my issues?

Please read the libusb Troubleshooting page and use the mailing list for support.

I tried to post to the libusb mailing list but it failed. Why?

You have to subscribe to the mailing list in order to post.

Running libusb

Can I run libusb applications on Linux without root privilege?

Yes.
The standard solution is to use udev rules. Here are some links to udev related websites.

How can I run libusb applications under Mac OS X if there is already a kernel extension installed for the device?

If there is no existing kernel extension installed for the device, libusb will run out of the box, you do not even need to have root privilege and there is no need to set up udev rules like Linux. However, if there is an existing kernel extension installed for the device, then it is more troublesome. There are ways to get libusb working and they all require some interventions as root.

1) You can use kextunload to unload the kernel extension. You need to run the command as root. Take note this may not be possible for drivers like USB HID since it may be used by other USB HID device. Take note that the kextunload command will lose its effect in the next boot.

The above command will unload the Apple provided FTDI driver (Mac OS X Mavericks or later).

The above command will unload the FTDI provided VCP driver.

2) You can use a codeless kext to prevent the kernel driver from attaching to the device. Take note that OS X Mavericks and later require that the kext be signed using a special Developer ID.

Please read the following two Apple technical notes for more details about writing a codeless kext.

3) In certain cases, you can manually edit the Info.plist configuration file of a kernel extension to prevent it from loading for certain VID/PID combination.

For example, in the case of Apple provided FTDI driver, you can edit the following file to comment outthe key/dict sections of the desired VID/PID combination.

Once you finish the editing, you can issue the following two commands and everything should work after that.

Reference:

How to use libusb under Windows?

Please refer to the following Wiki page:
https://github.com/libusb/libusb/wiki/Windows#How_to_use_libusb_on_Windows

Basically you will need to install a supported driver.

If your device is a generic HID device, no extra driver is needed since it is supported. But HIDAPI is recommended for HID device than libusb Windows.
If your device uses WinUSB driver, no extra driver is needed since it is supported natively.
If your device uses libusbK driver, you should be set as well (libusbK.dll should have been installed).
If your device uses libusb-win32 (libusb0.sys) device driver, please switch to libusbK driver.
If your device uses libusb-win32 filter driver, please uninstall the filter driver and try usbdk instead.
If your device uses other driver, and you do want to keep using the existing driver, then try usbdk.
If your device uses other driver and you are okay with switching drivers, then switch to WinUSB (preferred) or libusbK driver.

Can libusb be used on the USB device side, e.g. Linux Gadget Device?

No.
libusb only provides an API for writing software on the host. Of course, if the device also acts as a USB host then libusb could still be useful, but only for the host part of the device.

Can I use libusb to open a file on an USB storage device?

Yes.
libusb can be used for low-level communication with USB Mass Storage Class devices. But in order to access a file on such a device you must first implement Mass Storage Class, SCSI and the particular file system used on the device, most commonly FAT32.

However, libusb will not do this part for you. In a word, do not use libusb for USB mass storage device.

But you can find a limited example of how to read a data block through Mass Storage using libusb in the mass_storage test from the xusb.c sample of the the libusb distribution.

Does libusb support USB 3.0?

Yes (as long as the underlying OS supports USB 3.0 too).

My device works when plugged on an USB 2.0 port but not on an USB 3.0 one

If you encounter such an issue, you should report it to the libusb mailing-list.

But please note that USB 3.0 is fairly new, so some Operating Systems are still catching up.

For instance, USB 3.0 support for Windows 7 and earlier is very dependent on individual drivers, which are provided by the USB controller manufacturer, and not Microsoft. Some of these have been known to have bugs. Only Windows 8/8.1/10 and later have an official USB 3.0 stack that originates from Microsoft.

For Linux, the xHCI driver may also not be as mature as the other host controller driver. As of now (27-Dec-2016), things should be much better. Please try to upgrade to later version of the kernel whenever possible to have better support.

For Mac OS X, xHCI support has only been introduced recently with Mac OS X Mountain Lion, so USB 3.0 support may not be that mature either. Things should be better now (27-Dec-2016). Whenever possible, please upgrade to later version of Mac OS X for better support.

Kernel Mode Driver Download

We will try to help you sort issues related to USB 3.0 usage where possible. But before you contact us, if on Windows 7, please make sure you test with the latest USB 3.0 drivers available from your xHCI provider, or, if on Linux, please make sure you test with the latest kernel, as the xHCI driver is regularly being updated there.

Does libusb support USB HID devices?

If your application will revolve around HID access, you are strongly encouraged to try to use the HIDAPI library by Signal 11 Software, which is also cross-platform. It uses native HID API under Windows and Mac OS X. It use either hidraw or libusb as the backend under Linux.

libusb was widely used to access USB HID device under Linux for historical reasons so there may be use cases to use libusb for HID device due to existing code base or for platforms without HIDAPI support. However, the level of support as well as the ease of access of HID devices, depends on the platform you will be running libusb on.

On Linux, you must detach the kernel HID driver for libusb to communicate with the device, but the libusb API can do this for you. If you have a relevant udev rule, you should also be able to perform that operation without requiring root privileges. Still HIDAPI is recommended for new development.

On Mac OS X, you must install a codeless kext kernel driver and then reboot, before you will be able communicate with the device. This may not be easy with the release of later Mac OS X versions. So it is not recommended. HIDAPI should be the library of choices if you need Mac OS X support.

On Windows, the native Windows HID driver is supported by libusb, but there are some limitations, such as not being able to access HID mice and keyboards since they are system reserved, as well as getting a direct read of HID report descriptors.

Under NetBSD/OpenBSD, you may have to rebuild the kernel in order to use libusb with the HID device. Please refer to the apcupsd page.

In general, you may find HIDAPI a better library for HID device.

Platform Support

Does libusb support Windows RT?

No.
Windows RT is locked by Microsoft, which means that users cannot install the applications or library of their choice. As such, libusb has no plans to support Windows RT.

Does libusb support Apple iOS device?

No.

Does libusb support Windows CE based device?

Yes.

Please refer to the Windows CE related information in the following file.
https://github.com/libusb/libusb/blob/master/INSTALL_WIN.txt

Does libusb support Android

Nvidia Windows Kernel Mode Driver

Yes.However, this will only work if your device has USB host support (also known as USB On-The-Go) and if you have sufficient privileges to run in host mode (which usually requires a 'rooted' device).Please check the android directory for more info.