CONTRIBUTING.md

Contributing to libusbp

Development Tools

The following tools are used to help build, test, debug, and document this library:

• USB Test Device A: This is a custom USB device that is used for testing this library. You must have a device like this plugged in if you want to run the full test suite. The test/firmware/wixel folder contains firmware that can turn a Pololu Wixel into a USB Test Device A, and it should be possible to implement it on other USB-capable boards as well.
• cmake
• catch
• Doxygen
• Development environments:
  • Windows: MSYS2
  • macOS: Homebrew
• Memory leak checkers:
  • Windows: Install Dr. Memory and run drmemory -leaks_only ./run_test.exe
  • Linux: Install Valgrind and run valgrind ./run_test
  • macOS: Run MallocStackLogging=1 ./run_test -p, wait for the tests to finish, press Ctrl+Z, run leaks run_test, then finally run fg to go back to the stopped test process and end it.

Underlying API documentation

This section attempts to organize the documentation and information about the underlying APIs used by libusbp, which should be useful to anyone reviewing or editing the code.

Windows APIs

• WinUSB
• SetupAPI
• PnP Configuration Manager Reference
• Standard USB Identifiers
• What characters or bytes are valid in a USB serial number?
• INFO: Windows Rundll and Rundll32 Interface
• MSI Custom Action Type 17

Linux APIs

• udev
  • libudev Reference Manual
  • Kernel documentation of sysfs-bus-usb
  • sysfs.c
  • libudev and Sysfs Tutorial
• USB device node
  • USB documentation folder in the kernel tree
    • USB error code documentation
  • usbdevice_fs.h
  • devio.c
  • Linux USB Drivers presentation
  • USB Drivers chapter from a book
  • linux_usbfs.c from libusb
• Error numbers
  • errno.h
  • errno-base.h

macOS APIs

• I/O Kit Framework Reference
• IOKitLib.h Reference
• Accessing Hardware From Applications
• USB Device Interface Guide
• IOUSBInterfaceClass.cpp
• IOUSBInterfaceUserClient.cpp
• darwin_usb.c from libusb
• Mach messaging interface (mach ports)

Future development

Here are some things we might want to work on in future versions of the library:

• Serial port support. (Even just listing the serial ports of a USB device would be useful.)
• Human interface device (HID) support.
• Hotplug support: detect when new devices are added and detect when a specific device is removed.
• Stronger guarantees about thread safety. (This might not require code changes.)
• More options for asynchronous transfers.
• Perhaps use asynchronous operations to implement the synchronous ones, like libusb does. This would fix some quirks on various platforms: it would allow us to have timeouts for interrupt endpoints on Mac OS X and it would probably allow long synchronous operations on Linux to be interrupted with Ctrl+C. The main drawback is that it would add complexity.
• Sending data on OUT pipes.
• A device library template to help people who want to make a cross-platform C or C++ library for a USB device based on libusbp.