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