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