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