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