Backend documentation for porting efforts

Hopefully comprehensive enough for people to get started.

1 files changed, 95 insertions, 0 deletions

diff --git a/PORTING b/PORTING
new file mode 100644
index 0000000..7070784
--- /dev/null
+++ b/PORTING
@@ -0,0 +1,95 @@
+PORTING LIBUSB TO OTHER PLATFORMS
+
+Introduction
+============
+
+This document is aimed at developers wishing to port libusb to unsupported
+platforms. I believe the libusb API is OS-independent, so by supporting
+multiple operating systems we pave the way for cross-platform USB device
+drivers.
+
+Implementation-wise, the basic idea is that you provide an interface to
+libusb's internal "backend" API, which performs the appropriate operations on
+your target platform.
+
+In terms of USB I/O, your backend provides functionality to submit
+asynchronous transfers (synchronous transfers are implemented in the higher
+layers, based on the async interface). Your backend must also provide
+functionality to cancel those transfers.
+
+Your backend must also provide an event handling function to "reap" ongoing
+transfers and process their results.
+
+The backend must also provide standard functions for other USB operations,
+e.g. setting configuration, obtaining descriptors, etc.
+
+
+File descriptors for I/O polling
+================================
+
+For libusb to work, your event handling function obviously needs to be called
+at various points in time. Your backend must provide a set of file descriptors
+which libusb and its users can pass to poll() or select() to determine when
+it is time to call the event handling function.
+
+On Linux, this is easy: the usbfs kernel interface exposes a file descriptor
+which can be passed to poll(). If something similar is not true for your
+platform, you can emulate this using an internal library thread to reap I/O as
+necessary, and a pipe() with the main library to raise events. The file
+descriptor of the pipe can then be provided to libusb as an event source.
+
+
+Interface semantics and documentation
+=====================================
+
+Documentation of the backend interface can be found in libusbi.h inside the
+usbi_os_backend structure definition.
+
+Your implementations of these functions will need to call various internal
+libusb functions, prefixed with "usbi_". Documentation for these functions
+can be found in the .c files where they are implemented.
+
+You probably want to skim over *all* the documentation before starting your
+implementation. For example, you probably need to allocate and store private
+OS-specific data for device handles, but the documentation for the mechanism
+for doing so is probably not the first thing you will see.
+
+The Linux backend acts as a good example - view it as a reference
+implementation which you should try to match the behaviour of.
+
+
+Getting started
+===============
+
+1. Modify configure.ac to detect your platform appropriately (see the OS_LINUX
+stuff for an example).
+
+2. Implement your backend in the libusb/os/ directory, modifying
+libusb/os/Makefile.am appropriately.
+
+3. Add preprocessor logic to the top of libusb/core.c to statically assign the
+right usbi_backend for your platform.
+
+4. Produce and test your implementation.
+
+5. Send your implementation to libusb-devel mailing list.
+
+
+Implementation difficulties? Questions?
+=======================================
+
+If you encounter difficulties porting libusb to your platform, please raise
+these issues on the libusb-devel mailing list. Where possible and sensible, I
+am interested in solving problems preventing libusb from operating on other
+platforms.
+
+The libusb-devel mailing list is also a good place to ask questions and
+make suggestions about the internal API. Hopefully we can produce some
+better documentation based on your questions and other input.
+
+You are encouraged to get involved in the process; if the library needs
+some infrastructure additions/modifications to better support your platform,
+you are encouraged to make such changes (in cleanly distinct patch
+submissions). Even if you do not make such changes yourself, please do raise
+the issues on the mailing list at the very minimum.
+