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