Chromium Code Reviews
chromiumcodereview-hr@appspot.gserviceaccount.com (chromiumcodereview-hr) | Please choose your nickname with Settings | Help | Chromium Project | Gerrit Changes | Sign out
(255)

Side by Side Diff: third_party/libusb/src/PORTING

Issue 19713005: Update libusb 1.0.9 to libusbx 1.0.16 (Closed) Base URL: svn://svn.chromium.org/chrome/trunk/src
Patch Set: Created 7 years, 5 months ago
Use n/p to move between diff chunks; N/P to move between comments. Draft comments are only viewable by you.
Jump to:
View unified diff | Download patch | Annotate | Revision Log
OLDNEW
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
OLDNEW

Powered by Google App Engine
This is Rietveld 408576698