hjelmn@cs.unm.edu | 1eff220 | 2014-01-08 23:50:34 +0000 | [diff] [blame] | 1 | PORTING LIBUSB TO OTHER PLATFORMS |
Daniel Drake | 1298c51 | 2008-05-12 18:46:37 +0100 | [diff] [blame] | 2 | |
| 3 | Introduction |
| 4 | ============ |
| 5 | |
hjelmn@cs.unm.edu | 1eff220 | 2014-01-08 23:50:34 +0000 | [diff] [blame] | 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 |
Daniel Drake | 1298c51 | 2008-05-12 18:46:37 +0100 | [diff] [blame] | 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 |
hjelmn@cs.unm.edu | 1eff220 | 2014-01-08 23:50:34 +0000 | [diff] [blame] | 12 | libusb's internal "backend" API, which performs the appropriate operations on |
Daniel Drake | 1298c51 | 2008-05-12 18:46:37 +0100 | [diff] [blame] | 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 | |
hjelmn@cs.unm.edu | 1eff220 | 2014-01-08 23:50:34 +0000 | [diff] [blame] | 30 | For libusb to work, your event handling function obviously needs to be called |
Daniel Drake | 1298c51 | 2008-05-12 18:46:37 +0100 | [diff] [blame] | 31 | at various points in time. Your backend must provide a set of file descriptors |
hjelmn@cs.unm.edu | 1eff220 | 2014-01-08 23:50:34 +0000 | [diff] [blame] | 32 | which libusb and its users can pass to poll() or select() to determine when |
Daniel Drake | 1298c51 | 2008-05-12 18:46:37 +0100 | [diff] [blame] | 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 |
hjelmn@cs.unm.edu | 1eff220 | 2014-01-08 23:50:34 +0000 | [diff] [blame] | 39 | descriptor of the pipe can then be provided to libusb as an event source. |
Daniel Drake | 1298c51 | 2008-05-12 18:46:37 +0100 | [diff] [blame] | 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 |
hjelmn@cs.unm.edu | 1eff220 | 2014-01-08 23:50:34 +0000 | [diff] [blame] | 49 | libusb functions, prefixed with "usbi_". Documentation for these functions |
Daniel Drake | 1298c51 | 2008-05-12 18:46:37 +0100 | [diff] [blame] | 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 | |
hjelmn@cs.unm.edu | 1eff220 | 2014-01-08 23:50:34 +0000 | [diff] [blame] | 75 | 5. Send your implementation to libusb-devel mailing list. |
Daniel Drake | 1298c51 | 2008-05-12 18:46:37 +0100 | [diff] [blame] | 76 | |
| 77 | |
| 78 | Implementation difficulties? Questions? |
| 79 | ======================================= |
| 80 | |
hjelmn@cs.unm.edu | 1eff220 | 2014-01-08 23:50:34 +0000 | [diff] [blame] | 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 |
Daniel Drake | 1298c51 | 2008-05-12 18:46:37 +0100 | [diff] [blame] | 84 | platforms. |
| 85 | |
hjelmn@cs.unm.edu | 1eff220 | 2014-01-08 23:50:34 +0000 | [diff] [blame] | 86 | The libusb-devel mailing list is also a good place to ask questions and |
Daniel Drake | 1298c51 | 2008-05-12 18:46:37 +0100 | [diff] [blame] | 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. |