1 PORTING LIBUSB TO OTHER PLATFORMS 2 3 Introduction 4 ============ 5 6 This document is aimed at developers wishing to port libusb to unsupported 7 platforms. I believe the libusb API is OS-independent, so by supporting 8 multiple operating systems we pave the way for cross-platform USB device 9 drivers. 10 11 Implementation-wise, the basic idea is that you provide an interface to 12 libusb's internal "backend" API, which performs the appropriate operations on 13 your target platform. 14 15 In terms of USB I/O, your backend provides functionality to submit 16 asynchronous transfers (synchronous transfers are implemented in the higher 17 layers, based on the async interface). Your backend must also provide 18 functionality to cancel those transfers. 19 20 Your backend must also provide an event handling function to "reap" ongoing 21 transfers and process their results. 22 23 The backend must also provide standard functions for other USB operations, 24 e.g. setting configuration, obtaining descriptors, etc. 25 26 27 File descriptors for I/O polling 28 ================================ 29 30 For libusb to work, your event handling function obviously needs to be called 31 at various points in time. Your backend must provide a set of file descriptors 32 which libusb and its users can pass to poll() or select() to determine when 33 it is time to call the event handling function. 34 35 On Linux, this is easy: the usbfs kernel interface exposes a file descriptor 36 which can be passed to poll(). If something similar is not true for your 37 platform, you can emulate this using an internal library thread to reap I/O as 38 necessary, and a pipe() with the main library to raise events. The file 39 descriptor of the pipe can then be provided to libusb as an event source. 40 41 42 Interface semantics and documentation 43 ===================================== 44 45 Documentation of the backend interface can be found in libusbi.h inside the 46 usbi_os_backend structure definition. 47 48 Your implementations of these functions will need to call various internal 49 libusb functions, prefixed with "usbi_". Documentation for these functions 50 can be found in the .c files where they are implemented. 51 52 You probably want to skim over *all* the documentation before starting your 53 implementation. For example, you probably need to allocate and store private 54 OS-specific data for device handles, but the documentation for the mechanism 55 for doing so is probably not the first thing you will see. 56 57 The Linux backend acts as a good example - view it as a reference 58 implementation which you should try to match the behaviour of. 59 60 61 Getting started 62 =============== 63 64 1. Modify configure.ac to detect your platform appropriately (see the OS_LINUX 65 stuff for an example). 66 67 2. Implement your backend in the libusb/os/ directory, modifying 68 libusb/os/Makefile.am appropriately. 69 70 3. Add preprocessor logic to the top of libusb/core.c to statically assign the 71 right usbi_backend for your platform. 72 73 4. Produce and test your implementation. 74 75 5. Send your implementation to libusb-devel mailing list. 76 77 78 Implementation difficulties? Questions? 79 ======================================= 80 81 If you encounter difficulties porting libusb to your platform, please raise 82 these issues on the libusb-devel mailing list. Where possible and sensible, I 83 am interested in solving problems preventing libusb from operating on other 84 platforms. 85 86 The libusb-devel mailing list is also a good place to ask questions and 87 make suggestions about the internal API. Hopefully we can produce some 88 better documentation based on your questions and other input. 89 90 You are encouraged to get involved in the process; if the library needs 91 some infrastructure additions/modifications to better support your platform, 92 you are encouraged to make such changes (in cleanly distinct patch 93 submissions). Even if you do not make such changes yourself, please do raise 94 the issues on the mailing list at the very minimum. 95
