blob: 252b77a23fada3675732818356e078848e863eb6
1 | .. _submittingdrivers: |
2 | |
3 | Submitting Drivers For The Linux Kernel |
4 | ======================================= |
5 | |
6 | This document is intended to explain how to submit device drivers to the |
7 | various kernel trees. Note that if you are interested in video card drivers |
8 | you should probably talk to XFree86 (http://www.xfree86.org/) and/or X.Org |
9 | (http://x.org/) instead. |
10 | |
11 | Also read the Documentation/SubmittingPatches document. |
12 | |
13 | |
14 | Allocating Device Numbers |
15 | ------------------------- |
16 | |
17 | Major and minor numbers for block and character devices are allocated |
18 | by the Linux assigned name and number authority (currently this is |
19 | Torben Mathiasen). The site is http://www.lanana.org/. This |
20 | also deals with allocating numbers for devices that are not going to |
21 | be submitted to the mainstream kernel. |
22 | See Documentation/devices.txt for more information on this. |
23 | |
24 | If you don't use assigned numbers then when your device is submitted it will |
25 | be given an assigned number even if that is different from values you may |
26 | have shipped to customers before. |
27 | |
28 | Who To Submit Drivers To |
29 | ------------------------ |
30 | |
31 | Linux 2.0: |
32 | No new drivers are accepted for this kernel tree. |
33 | |
34 | Linux 2.2: |
35 | No new drivers are accepted for this kernel tree. |
36 | |
37 | Linux 2.4: |
38 | If the code area has a general maintainer then please submit it to |
39 | the maintainer listed in MAINTAINERS in the kernel file. If the |
40 | maintainer does not respond or you cannot find the appropriate |
41 | maintainer then please contact Willy Tarreau <w@1wt.eu>. |
42 | |
43 | Linux 2.6 and upper: |
44 | The same rules apply as 2.4 except that you should follow linux-kernel |
45 | to track changes in API's. The final contact point for Linux 2.6+ |
46 | submissions is Andrew Morton. |
47 | |
48 | What Criteria Determine Acceptance |
49 | ---------------------------------- |
50 | |
51 | Licensing: |
52 | The code must be released to us under the |
53 | GNU General Public License. We don't insist on any kind |
54 | of exclusive GPL licensing, and if you wish the driver |
55 | to be useful to other communities such as BSD you may well |
56 | wish to release under multiple licenses. |
57 | See accepted licenses at include/linux/module.h |
58 | |
59 | Copyright: |
60 | The copyright owner must agree to use of GPL. |
61 | It's best if the submitter and copyright owner |
62 | are the same person/entity. If not, the name of |
63 | the person/entity authorizing use of GPL should be |
64 | listed in case it's necessary to verify the will of |
65 | the copyright owner. |
66 | |
67 | Interfaces: |
68 | If your driver uses existing interfaces and behaves like |
69 | other drivers in the same class it will be much more likely |
70 | to be accepted than if it invents gratuitous new ones. |
71 | If you need to implement a common API over Linux and NT |
72 | drivers do it in userspace. |
73 | |
74 | Code: |
75 | Please use the Linux style of code formatting as documented |
76 | in :ref:`Documentation/CodingStyle <codingStyle>`. |
77 | If you have sections of code |
78 | that need to be in other formats, for example because they |
79 | are shared with a windows driver kit and you want to |
80 | maintain them just once separate them out nicely and note |
81 | this fact. |
82 | |
83 | Portability: |
84 | Pointers are not always 32bits, not all computers are little |
85 | endian, people do not all have floating point and you |
86 | shouldn't use inline x86 assembler in your driver without |
87 | careful thought. Pure x86 drivers generally are not popular. |
88 | If you only have x86 hardware it is hard to test portability |
89 | but it is easy to make sure the code can easily be made |
90 | portable. |
91 | |
92 | Clarity: |
93 | It helps if anyone can see how to fix the driver. It helps |
94 | you because you get patches not bug reports. If you submit a |
95 | driver that intentionally obfuscates how the hardware works |
96 | it will go in the bitbucket. |
97 | |
98 | PM support: |
99 | Since Linux is used on many portable and desktop systems, your |
100 | driver is likely to be used on such a system and therefore it |
101 | should support basic power management by implementing, if |
102 | necessary, the .suspend and .resume methods used during the |
103 | system-wide suspend and resume transitions. You should verify |
104 | that your driver correctly handles the suspend and resume, but |
105 | if you are unable to ensure that, please at least define the |
106 | .suspend method returning the -ENOSYS ("Function not |
107 | implemented") error. You should also try to make sure that your |
108 | driver uses as little power as possible when it's not doing |
109 | anything. For the driver testing instructions see |
110 | Documentation/power/drivers-testing.txt and for a relatively |
111 | complete overview of the power management issues related to |
112 | drivers see Documentation/power/devices.txt . |
113 | |
114 | Control: |
115 | In general if there is active maintenance of a driver by |
116 | the author then patches will be redirected to them unless |
117 | they are totally obvious and without need of checking. |
118 | If you want to be the contact and update point for the |
119 | driver it is a good idea to state this in the comments, |
120 | and include an entry in MAINTAINERS for your driver. |
121 | |
122 | What Criteria Do Not Determine Acceptance |
123 | ----------------------------------------- |
124 | |
125 | Vendor: |
126 | Being the hardware vendor and maintaining the driver is |
127 | often a good thing. If there is a stable working driver from |
128 | other people already in the tree don't expect 'we are the |
129 | vendor' to get your driver chosen. Ideally work with the |
130 | existing driver author to build a single perfect driver. |
131 | |
132 | Author: |
133 | It doesn't matter if a large Linux company wrote the driver, |
134 | or you did. Nobody has any special access to the kernel |
135 | tree. Anyone who tells you otherwise isn't telling the |
136 | whole story. |
137 | |
138 | |
139 | Resources |
140 | --------- |
141 | |
142 | Linux kernel master tree: |
143 | ftp.\ *country_code*\ .kernel.org:/pub/linux/kernel/... |
144 | |
145 | where *country_code* == your country code, such as |
146 | **us**, **uk**, **fr**, etc. |
147 | |
148 | http://git.kernel.org/?p=linux/kernel/git/torvalds/linux.git |
149 | |
150 | Linux kernel mailing list: |
151 | linux-kernel@vger.kernel.org |
152 | [mail majordomo@vger.kernel.org to subscribe] |
153 | |
154 | Linux Device Drivers, Third Edition (covers 2.6.10): |
155 | http://lwn.net/Kernel/LDD3/ (free version) |
156 | |
157 | LWN.net: |
158 | Weekly summary of kernel development activity - http://lwn.net/ |
159 | |
160 | 2.6 API changes: |
161 | |
162 | http://lwn.net/Articles/2.6-kernel-api/ |
163 | |
164 | Porting drivers from prior kernels to 2.6: |
165 | |
166 | http://lwn.net/Articles/driver-porting/ |
167 | |
168 | KernelNewbies: |
169 | Documentation and assistance for new kernel programmers |
170 | |
171 | http://kernelnewbies.org/ |
172 | |
173 | Linux USB project: |
174 | http://www.linux-usb.org/ |
175 | |
176 | How to NOT write kernel driver by Arjan van de Ven: |
177 | http://www.fenrus.org/how-to-not-write-a-device-driver-paper.pdf |
178 | |
179 | Kernel Janitor: |
180 | http://kernelnewbies.org/KernelJanitors |
181 | |
182 | GIT, Fast Version Control System: |
183 | http://git-scm.com/ |
184 |