├── .gitignore ├── 0.Overview.rst ├── 1.Warm-up.rst ├── 2.First-patch.rst ├── 3.First-patch-set.rst ├── LICENSE ├── README.rst ├── SUBMIT.rst ├── apply-and-build.sh ├── cpt.sh ├── git-am-dir.sh ├── mailing-list-etiqutte.rst ├── quotes.rst ├── slabinfo-simple.c ├── tutorial ├── README.rst ├── cheat-sheet.rst ├── prerequisite.rst ├── shell-utils.sh ├── track-one.rst ├── track-two.rst └── trouble-shoot.rst └── workshop ├── README.rst ├── checkpatch.rst ├── config ├── email-from-dan ├── further-tools.rst ├── patch-series.rst ├── probe-and-release.rst └── setup.rst /.gitignore: -------------------------------------------------------------------------------- 1 | # Object files 2 | *.o 3 | *.ko 4 | *.obj 5 | *.elf 6 | 7 | # Precompiled Headers 8 | *.gch 9 | *.pch 10 | 11 | # Libraries 12 | *.lib 13 | *.a 14 | *.la 15 | *.lo 16 | 17 | # Shared objects (inc. Windows DLLs) 18 | *.dll 19 | *.so 20 | *.so.* 21 | *.dylib 22 | 23 | # Executables 24 | *.exe 25 | *.out 26 | *.app 27 | *.i*86 28 | *.x86_64 29 | *.hex 30 | 31 | # Debug files 32 | *.dSYM/ 33 | *.su 34 | -------------------------------------------------------------------------------- /0.Overview.rst: -------------------------------------------------------------------------------- 1 | Overview 2 | ======== 3 | 4 | Aim 5 | --- 6 | 7 | The aim of this series of documents is to outline *one* way of getting 8 | started with Linux kernel programming. It is by no means the only way 9 | and it is quite possibly not even the *best* way. 10 | 11 | Good luck. 12 | 13 | Assumptions 14 | ----------- 15 | 16 | 1. You are inherently interested in how the Linux kernel works. 17 | 2. You know the C programming language *well*. 18 | 3. You know how to use git. 19 | 20 | 21 | File listing 22 | ------------ 23 | 24 | * 0.Overview.rst - This file. 25 | 26 | * 1.Warm-up.rst - Warm up tasks to get started playing with the kernel. 27 | 28 | * 2.First-patch.rst - Steps to get your first patch merged into the kernel. 29 | 30 | * 3.First-patch-set.rst - Steps to submit your first multi-patch series. 31 | 32 | 33 | For blog posts of a similar nature see `http://tobin.cc/blog `_ 34 | -------------------------------------------------------------------------------- /1.Warm-up.rst: -------------------------------------------------------------------------------- 1 | Warm up Task - Build the Mainline 2 | ================================== 3 | 4 | 1. Clone 5 | -------- 6 | 7 | Clone Linus' tree 8 | 9 | 10 | .. code:: bash 11 | 12 | git clone --depth=1 git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git 13 | 14 | 2. Config 15 | --------- 16 | 17 | Get current running kernel configuration. 18 | 19 | .. code:: bash 20 | 21 | zcat /proc/config.gz > $KERNEL_TREE/.config 22 | 23 | 3. Build 24 | -------- 25 | 26 | Build and install the kernel as applicable for your distribution. 27 | 28 | - build kernel 29 | - build modules 30 | - install kernel 31 | - install modules 32 | 33 | Pro Tip: Do not get bogged down configuring the kernel at this stage, for *guaranteed* build use a 34 | running config as the basis. For quicker build use `make localmodconfig`. 35 | 36 | 4. Boot 37 | ------- 38 | 39 | Configure boot loader and boot new kernel. 40 | 41 | -------------------------------------------------------------------------------- /2.First-patch.rst: -------------------------------------------------------------------------------- 1 | First Patch 2 | =========== 3 | 4 | This includes steps to getting your first patch merged into the mainline kernel. 5 | 6 | NOTE: Do not submit patches to any part of the kernel outside of drivers/staging whilst getting 7 | started with kernel development. 8 | 9 | Pro Tip: Limit scope to the following directories; 10 | 11 | - Documentation/process/ 12 | - drivers/staging/ 13 | - include/linux/ 14 | - include/uapi/ 15 | 16 | 1. Tools 17 | -------- 18 | 19 | Set up your tools 20 | 21 | - **Editor:** The kernel uses a specific coding style, you may like to configure your editor to support this. 22 | 23 | - **Email:** All kernel development is done in the open, this means via mailing lists. All patches are 24 | sent inline, this means no attachments. 25 | - **Git:** Configure git with your email address and name. All kernel changes must contain a tag 26 | 27 | .. code:: bash 28 | 29 | Signed-off-by: Joe Developer 30 | 31 | You may wish to add to your git config 32 | 33 | .. code:: bash 34 | 35 | [format] 36 | signOff = true 37 | 38 | 39 | You may also need 40 | 41 | .. code:: bash 42 | 43 | [user] 44 | email = joe@email.com 45 | name = Joe Developer 46 | 47 | 48 | Pro Tip: If you already have git configured with your GitHub username 49 | then add the real name configuration lines to the git config file 50 | within your kernel development tree (see task 3 below). 51 | 52 | 2. Mailing Lists 53 | ---------------- 54 | 55 | Subscribe to the following mailing lists 56 | 57 | - kernel newbies kernelnewbies@kernelnewbies.org 58 | - device drivers driverdev-devel@linuxdriverproject.org 59 | 60 | Pro Tip: Do not bother subscribing to LKML at this stage. 61 | 62 | At this stage you may like to sort emails from mailing lists into 63 | separate mail boxes. Example regex for sorting; 64 | 65 | .. code:: bash 66 | 67 | ^List-ID:.*$ 68 | 69 | Pro Tip: Always maintain the complete CC list when responding to mails 70 | on a kernel mailing list. 71 | 72 | 3. Tree 73 | ------- 74 | 75 | Set up development tree. 76 | 77 | - Clone Greg Kroah-Hartman's tree 78 | 79 | `https://git.kernel.org/pub/scm/linux/kernel/git/gregkh/staging.git/` 80 | 81 | - Set up tracking branch on staging-next (or staging-testing) 82 | 83 | Pro Tip: Work off of staging-next but make sure your patches apply to staging-testing before you 84 | submit them to the driver dev mailing list. 85 | 86 | 4. Checkpatch 87 | ------------- 88 | 89 | Run `checkpatch.pl` against drivers in staging until you find a warning that you feel you can fix. 90 | 91 | .. code:: bash 92 | 93 | scripts/checkpatch.pl -f drivers/staging/FOO/*.c 94 | 95 | Pro Tip: Do not fix line over 80 warnings. 96 | 97 | 5. Code 98 | ------- 99 | 100 | Fix **all** instances of the warning within the driver you have chosen. While not essential, if a 101 | job is worth doing it is worth doing properly. 102 | 103 | 6. Commit 104 | --------- 105 | 106 | Commit your changes as a single commit. Write a *correct* git log for the commit. Read 107 | 108 | `Documentation/process/submitting-patches.rst` 109 | 110 | Commit log messages must be of a specific format and content. At 111 | first they are difficult and time consuming to write. You may even 112 | find you spend more time writing git logs at first than code. Keep 113 | at it, you will learn a lot from doing it thoroughly. If you want 114 | to be taken seriously you need to apply effort to learning the 115 | development process and display that you have done so. 116 | 117 | 7. Submit 118 | --------- 119 | 120 | Create and send patch using git 121 | 122 | .. code:: bash 123 | 124 | git format-patch HEAD~ 125 | 126 | .. code:: bash 127 | 128 | git send-email --to='Joe Developer ' 0001-xxx-xxx.patch 129 | 130 | Check the TODO file for whom to send the patch to, or use 131 | 132 | .. code:: bash 133 | 134 | scripts/get_maintainer.pl 135 | 136 | 8. Respond 137 | ---------- 138 | 139 | Respond to feedback you receive from maintainers and/or reviewers. 140 | 141 | If asked to do so, fix your patch and re-submit. 142 | 143 | Pro Tip: Wait at least two weeks before following up on any email sent to a kernel mailing list. 144 | 145 | Final 146 | ----- 147 | 148 | At this stage, if all went successfully, you should get an email from 149 | Greg Kroah-Hartman saying that your patch was merged into 150 | staging-testing. From here your patch will automatically transition to 151 | staging-next then, when the next merge window opens, will by merged into 152 | Linus' mainline. 153 | -------------------------------------------------------------------------------- /3.First-patch-set.rst: -------------------------------------------------------------------------------- 1 | First Patch Set 2 | =============== 3 | 4 | This includes crafting a multi patch series. For the first series ('series' and 'set' used 5 | interchangeably) the code changes will be as simple as possible. The aim is to familiarize ones self 6 | with the Linux kernel development process. 7 | 8 | It is assumed you have had your first patch merged into the kernel. 9 | 10 | - We will be working on Greg Kroah-Hartman's staging tree, more specifically, the 'staging-next' 11 | branch. If you have not got this set up, you may like to refer to `2.First-patch.rst` in this 12 | directory. 13 | 14 | 1. Finding something to work on 15 | ------------------------------- 16 | 17 | Finding something to work on is often one the hurdles to cross when beginning contributing to any 18 | open source project. The Linux kernel is no different, and realistically is no more difficult than 19 | any other large open source project. There is no real answer to this question because developers are 20 | all different, we are all motivated by different things. We hack open source because it amuses us so 21 | to find something to work on we must find something that suits us personally. 22 | 23 | Some tips; 24 | 25 | - Hacking is more fun when we have small continuous successes. Pick a driver that requires work that 26 | you feel you can manage. Run checkpatch on any/all the drivers in staging and pick one that 27 | looks doable. 28 | 29 | - Learning is a good motivator. Pick a driver that belongs to a subsystem you are interested in. 30 | The Kconfig file for each driver usually contains enough information to see if the driver sparks 31 | your interest. Otherwise a quick web search will often reveal more information. For example 32 | 33 | - dgnc/ - Multi-port Serial PCI card. 34 | - vme/devices - Various VME devices. 35 | - comedi/ - A collection of drivers for a variety of common data acquisition plug-in boards. 36 | - fbtft/ - The fbtft kernel module is a layer between the driver and the framebuffer subsystem. 37 | - rtl8*/ - Various RealTek wireless LAN cards. 38 | 39 | Either you have found a drive that throws a tonne of checkpatch warnings (some of which you are feel 40 | you can tackle) or you have picked a driver that inspires you, maybe the code looks nice (or maybe 41 | the code looks horrible so you are inspired to clean it), maybe the driver is part of a subsystem 42 | you would like to learn more about. You now have something to work on. 43 | 44 | 2. Implement some changes 45 | ------------------------- 46 | 47 | - If you have not already done so, run checkpatch on 'your' driver. 48 | 49 | .. code:: bash 50 | 51 | checkpatch --terse --strict --show-types drivers/staging/FOO/*.{ch} 52 | 53 | - Pick three warning types that you can manage. 'warning' refers to any CHECK/WARNING/ERROR. 54 | 55 | - Fix all instances of a single warning type as a single commit (patch). 56 | 57 | At this stage it is probably asking too much of yourself to understand the whole driver. One of 58 | the obstacles to kernel hacking is getting overwhelmed by the complexity. You may like to 59 | concentrate on understanding the code block surrounding the source of the warning. Next you can 60 | consider understanding the whole function. Still, at this stage there will be a lot of function 61 | calls and macros that you are unfamiliar with. Grepping the kernel can be difficult because the 62 | code base is so large, you may also like to use 63 | 64 | http://elixir.free-electrons.com/linux/latest/source 65 | 66 | for online kernel identifier searches. 67 | 68 | Don't get bogged down. Remember we are trying to learn the process not the whole kernel. You do 69 | not need to understand everything to make useful minor contributions and to learn the development 70 | process. 71 | 72 | - Make sure you commit log is written correctly and thoroughly. By now you should have read 73 | 74 | Documentation/process/submitting-patches.rst 75 | 76 | You may like to reread Section *2 Describe your changes*. Writing commit logs is hard at 77 | first. They are an integral part of the kernel development process, they require concerted effort 78 | and thorough consideration. 79 | 80 | 3. Check your code 81 | ------------------ 82 | 83 | As you know, all kernel development is done in the open. Submitting kernel patches with obvious 84 | errors is both embarrassing and a waste of resources (developer/maintainer time and effort). 85 | 86 | By now you should have three commits in your git index. Each fixing a specific checkpatch warning. 87 | 88 | - Check you patches. Maintainers typically review patches from within their email clients by reading 89 | the patch (unified diff format). All patches are submitted to kernel mailing lists inline. You can 90 | review your patches using the following `git` command 91 | 92 | .. code:: bash 93 | 94 | git log --color=always --patch --reverse HEAD~~~.. | less 95 | 96 | - If you need to make changes to previous commit, including the commit log, you can use 97 | 98 | .. code:: bash 99 | 100 | git rebase -i HEAD~~~ 101 | 102 | If you have never rebased commits before then it can take some getting used to. git does a good 103 | job holding your hand during rebase (if you read the output). 104 | 105 | WARNING: After rebaseing be sure to check your diffs (as above) closely. It is easy to mix 106 | changes up into consecutive commits when rebaseing. 107 | 108 | - Verify that each commit applies and builds cleanly on top of `staging-next`. All kernel patches 109 | must build cleanly and leave the kernel in a sane state. You may like to use a script to do this 110 | `apply-and-build.sh`. 111 | 112 | 113 | On One Change Per Commit 114 | ------------------------ 115 | 116 | Patches to the Linux kernel must fix one thing and one thing only. However, a diff that includes 117 | obvious errors will not get merged. If you are working on a line of code and the following line has 118 | a blatant error often you should fix it also. For example, say you are fixing checkpatch warning xxx 119 | and in doing so you touch a line that calls function foo(). The call to function foo also has the 120 | parenthesis in the wrong place. You should consider breaking this into a separate patch 'refactor 121 | call to foo' and fix the call site completely (including the fix of warning xxx). 122 | 123 | This way all the diffs will be clean. Always consider the maintainer. The Linux kernel is not short 124 | on developers, it is short on maintainers, anything you as a developer can do to minimize the effort 125 | of the maintainer should be done even if it requires 'unnecessary' extra effort on the part of the 126 | developer. The whole process is optimized for the maintainer. 127 | 128 | 4. Output and send patch set 129 | ---------------------------- 130 | 131 | At this stage you have in your git index three commits, each does one thing and one thing only, each 132 | applies on top of staging-next, and each builds cleanly. 133 | 134 | - Output a linked patch set ready for sending using git 135 | 136 | .. code:: bash 137 | 138 | git format-patch -3 -o path/to/patch/dir --cover-letter 139 | 140 | - Write the cover letter. For a simple series like this a brief sentence describing the series will 141 | suffice. 142 | 143 | - You may, at this stage, like to email the patch set to your self. This is a useful step when 144 | getting started so you can verify that everything looks good. 145 | 146 | - Ascertain the correct recipient of the patch series. You can do this by looking in the TODO file 147 | for the driver. Also you can run the `get_maintainers` script. The output of this script can be 148 | verbose. The Linux kernel community errs on the side of sending patches to too many people, a 149 | simple series like this however need only be sent to the device driver mailing list, Greg 150 | Kroah-Hartman, and any other maintainers listed by the script (unless directed otherwise by the 151 | TODO file). 152 | 153 | .. code:: bash 154 | 155 | scripts/get_maintainer.pl path/to/patch/dir/*.patch 156 | 157 | - You can send the series using git. If you add the `To:` and `Cc:` headers to the cover letter then 158 | the following command does what you need 159 | 160 | .. code:: bash 161 | 162 | git send-email --to-cover --cc-cover path/to/patch/dir/*.patch 163 | 164 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | GNU GENERAL PUBLIC LICENSE 2 | Version 2, June 1991 3 | 4 | Copyright (C) 1989, 1991 Free Software Foundation, Inc., 5 | 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA 6 | Everyone is permitted to copy and distribute verbatim copies 7 | of this license document, but changing it is not allowed. 8 | 9 | Preamble 10 | 11 | The licenses for most software are designed to take away your 12 | freedom to share and change it. By contrast, the GNU General Public 13 | License is intended to guarantee your freedom to share and change free 14 | software--to make sure the software is free for all its users. This 15 | General Public License applies to most of the Free Software 16 | Foundation's software and to any other program whose authors commit to 17 | using it. (Some other Free Software Foundation software is covered by 18 | the GNU Lesser General Public License instead.) You can apply it to 19 | your programs, too. 20 | 21 | When we speak of free software, we are referring to freedom, not 22 | price. Our General Public Licenses are designed to make sure that you 23 | have the freedom to distribute copies of free software (and charge for 24 | this service if you wish), that you receive source code or can get it 25 | if you want it, that you can change the software or use pieces of it 26 | in new free programs; and that you know you can do these things. 27 | 28 | To protect your rights, we need to make restrictions that forbid 29 | anyone to deny you these rights or to ask you to surrender the rights. 30 | These restrictions translate to certain responsibilities for you if you 31 | distribute copies of the software, or if you modify it. 32 | 33 | For example, if you distribute copies of such a program, whether 34 | gratis or for a fee, you must give the recipients all the rights that 35 | you have. You must make sure that they, too, receive or can get the 36 | source code. And you must show them these terms so they know their 37 | rights. 38 | 39 | We protect your rights with two steps: (1) copyright the software, and 40 | (2) offer you this license which gives you legal permission to copy, 41 | distribute and/or modify the software. 42 | 43 | Also, for each author's protection and ours, we want to make certain 44 | that everyone understands that there is no warranty for this free 45 | software. If the software is modified by someone else and passed on, we 46 | want its recipients to know that what they have is not the original, so 47 | that any problems introduced by others will not reflect on the original 48 | authors' reputations. 49 | 50 | Finally, any free program is threatened constantly by software 51 | patents. We wish to avoid the danger that redistributors of a free 52 | program will individually obtain patent licenses, in effect making the 53 | program proprietary. To prevent this, we have made it clear that any 54 | patent must be licensed for everyone's free use or not licensed at all. 55 | 56 | The precise terms and conditions for copying, distribution and 57 | modification follow. 58 | 59 | GNU GENERAL PUBLIC LICENSE 60 | TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION 61 | 62 | 0. This License applies to any program or other work which contains 63 | a notice placed by the copyright holder saying it may be distributed 64 | under the terms of this General Public License. The "Program", below, 65 | refers to any such program or work, and a "work based on the Program" 66 | means either the Program or any derivative work under copyright law: 67 | that is to say, a work containing the Program or a portion of it, 68 | either verbatim or with modifications and/or translated into another 69 | language. (Hereinafter, translation is included without limitation in 70 | the term "modification".) Each licensee is addressed as "you". 71 | 72 | Activities other than copying, distribution and modification are not 73 | covered by this License; they are outside its scope. The act of 74 | running the Program is not restricted, and the output from the Program 75 | is covered only if its contents constitute a work based on the 76 | Program (independent of having been made by running the Program). 77 | Whether that is true depends on what the Program does. 78 | 79 | 1. You may copy and distribute verbatim copies of the Program's 80 | source code as you receive it, in any medium, provided that you 81 | conspicuously and appropriately publish on each copy an appropriate 82 | copyright notice and disclaimer of warranty; keep intact all the 83 | notices that refer to this License and to the absence of any warranty; 84 | and give any other recipients of the Program a copy of this License 85 | along with the Program. 86 | 87 | You may charge a fee for the physical act of transferring a copy, and 88 | you may at your option offer warranty protection in exchange for a fee. 89 | 90 | 2. You may modify your copy or copies of the Program or any portion 91 | of it, thus forming a work based on the Program, and copy and 92 | distribute such modifications or work under the terms of Section 1 93 | above, provided that you also meet all of these conditions: 94 | 95 | a) You must cause the modified files to carry prominent notices 96 | stating that you changed the files and the date of any change. 97 | 98 | b) You must cause any work that you distribute or publish, that in 99 | whole or in part contains or is derived from the Program or any 100 | part thereof, to be licensed as a whole at no charge to all third 101 | parties under the terms of this License. 102 | 103 | c) If the modified program normally reads commands interactively 104 | when run, you must cause it, when started running for such 105 | interactive use in the most ordinary way, to print or display an 106 | announcement including an appropriate copyright notice and a 107 | notice that there is no warranty (or else, saying that you provide 108 | a warranty) and that users may redistribute the program under 109 | these conditions, and telling the user how to view a copy of this 110 | License. (Exception: if the Program itself is interactive but 111 | does not normally print such an announcement, your work based on 112 | the Program is not required to print an announcement.) 113 | 114 | These requirements apply to the modified work as a whole. If 115 | identifiable sections of that work are not derived from the Program, 116 | and can be reasonably considered independent and separate works in 117 | themselves, then this License, and its terms, do not apply to those 118 | sections when you distribute them as separate works. But when you 119 | distribute the same sections as part of a whole which is a work based 120 | on the Program, the distribution of the whole must be on the terms of 121 | this License, whose permissions for other licensees extend to the 122 | entire whole, and thus to each and every part regardless of who wrote it. 123 | 124 | Thus, it is not the intent of this section to claim rights or contest 125 | your rights to work written entirely by you; rather, the intent is to 126 | exercise the right to control the distribution of derivative or 127 | collective works based on the Program. 128 | 129 | In addition, mere aggregation of another work not based on the Program 130 | with the Program (or with a work based on the Program) on a volume of 131 | a storage or distribution medium does not bring the other work under 132 | the scope of this License. 133 | 134 | 3. You may copy and distribute the Program (or a work based on it, 135 | under Section 2) in object code or executable form under the terms of 136 | Sections 1 and 2 above provided that you also do one of the following: 137 | 138 | a) Accompany it with the complete corresponding machine-readable 139 | source code, which must be distributed under the terms of Sections 140 | 1 and 2 above on a medium customarily used for software interchange; or, 141 | 142 | b) Accompany it with a written offer, valid for at least three 143 | years, to give any third party, for a charge no more than your 144 | cost of physically performing source distribution, a complete 145 | machine-readable copy of the corresponding source code, to be 146 | distributed under the terms of Sections 1 and 2 above on a medium 147 | customarily used for software interchange; or, 148 | 149 | c) Accompany it with the information you received as to the offer 150 | to distribute corresponding source code. (This alternative is 151 | allowed only for noncommercial distribution and only if you 152 | received the program in object code or executable form with such 153 | an offer, in accord with Subsection b above.) 154 | 155 | The source code for a work means the preferred form of the work for 156 | making modifications to it. For an executable work, complete source 157 | code means all the source code for all modules it contains, plus any 158 | associated interface definition files, plus the scripts used to 159 | control compilation and installation of the executable. However, as a 160 | special exception, the source code distributed need not include 161 | anything that is normally distributed (in either source or binary 162 | form) with the major components (compiler, kernel, and so on) of the 163 | operating system on which the executable runs, unless that component 164 | itself accompanies the executable. 165 | 166 | If distribution of executable or object code is made by offering 167 | access to copy from a designated place, then offering equivalent 168 | access to copy the source code from the same place counts as 169 | distribution of the source code, even though third parties are not 170 | compelled to copy the source along with the object code. 171 | 172 | 4. You may not copy, modify, sublicense, or distribute the Program 173 | except as expressly provided under this License. Any attempt 174 | otherwise to copy, modify, sublicense or distribute the Program is 175 | void, and will automatically terminate your rights under this License. 176 | However, parties who have received copies, or rights, from you under 177 | this License will not have their licenses terminated so long as such 178 | parties remain in full compliance. 179 | 180 | 5. You are not required to accept this License, since you have not 181 | signed it. However, nothing else grants you permission to modify or 182 | distribute the Program or its derivative works. These actions are 183 | prohibited by law if you do not accept this License. Therefore, by 184 | modifying or distributing the Program (or any work based on the 185 | Program), you indicate your acceptance of this License to do so, and 186 | all its terms and conditions for copying, distributing or modifying 187 | the Program or works based on it. 188 | 189 | 6. Each time you redistribute the Program (or any work based on the 190 | Program), the recipient automatically receives a license from the 191 | original licensor to copy, distribute or modify the Program subject to 192 | these terms and conditions. You may not impose any further 193 | restrictions on the recipients' exercise of the rights granted herein. 194 | You are not responsible for enforcing compliance by third parties to 195 | this License. 196 | 197 | 7. If, as a consequence of a court judgment or allegation of patent 198 | infringement or for any other reason (not limited to patent issues), 199 | conditions are imposed on you (whether by court order, agreement or 200 | otherwise) that contradict the conditions of this License, they do not 201 | excuse you from the conditions of this License. If you cannot 202 | distribute so as to satisfy simultaneously your obligations under this 203 | License and any other pertinent obligations, then as a consequence you 204 | may not distribute the Program at all. For example, if a patent 205 | license would not permit royalty-free redistribution of the Program by 206 | all those who receive copies directly or indirectly through you, then 207 | the only way you could satisfy both it and this License would be to 208 | refrain entirely from distribution of the Program. 209 | 210 | If any portion of this section is held invalid or unenforceable under 211 | any particular circumstance, the balance of the section is intended to 212 | apply and the section as a whole is intended to apply in other 213 | circumstances. 214 | 215 | It is not the purpose of this section to induce you to infringe any 216 | patents or other property right claims or to contest validity of any 217 | such claims; this section has the sole purpose of protecting the 218 | integrity of the free software distribution system, which is 219 | implemented by public license practices. Many people have made 220 | generous contributions to the wide range of software distributed 221 | through that system in reliance on consistent application of that 222 | system; it is up to the author/donor to decide if he or she is willing 223 | to distribute software through any other system and a licensee cannot 224 | impose that choice. 225 | 226 | This section is intended to make thoroughly clear what is believed to 227 | be a consequence of the rest of this License. 228 | 229 | 8. If the distribution and/or use of the Program is restricted in 230 | certain countries either by patents or by copyrighted interfaces, the 231 | original copyright holder who places the Program under this License 232 | may add an explicit geographical distribution limitation excluding 233 | those countries, so that distribution is permitted only in or among 234 | countries not thus excluded. In such case, this License incorporates 235 | the limitation as if written in the body of this License. 236 | 237 | 9. The Free Software Foundation may publish revised and/or new versions 238 | of the General Public License from time to time. Such new versions will 239 | be similar in spirit to the present version, but may differ in detail to 240 | address new problems or concerns. 241 | 242 | Each version is given a distinguishing version number. If the Program 243 | specifies a version number of this License which applies to it and "any 244 | later version", you have the option of following the terms and conditions 245 | either of that version or of any later version published by the Free 246 | Software Foundation. If the Program does not specify a version number of 247 | this License, you may choose any version ever published by the Free Software 248 | Foundation. 249 | 250 | 10. If you wish to incorporate parts of the Program into other free 251 | programs whose distribution conditions are different, write to the author 252 | to ask for permission. For software which is copyrighted by the Free 253 | Software Foundation, write to the Free Software Foundation; we sometimes 254 | make exceptions for this. Our decision will be guided by the two goals 255 | of preserving the free status of all derivatives of our free software and 256 | of promoting the sharing and reuse of software generally. 257 | 258 | NO WARRANTY 259 | 260 | 11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY 261 | FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN 262 | OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES 263 | PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED 264 | OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF 265 | MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS 266 | TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE 267 | PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, 268 | REPAIR OR CORRECTION. 269 | 270 | 12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING 271 | WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR 272 | REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, 273 | INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING 274 | OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED 275 | TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY 276 | YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER 277 | PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE 278 | POSSIBILITY OF SUCH DAMAGES. 279 | 280 | END OF TERMS AND CONDITIONS 281 | 282 | How to Apply These Terms to Your New Programs 283 | 284 | If you develop a new program, and you want it to be of the greatest 285 | possible use to the public, the best way to achieve this is to make it 286 | free software which everyone can redistribute and change under these terms. 287 | 288 | To do so, attach the following notices to the program. It is safest 289 | to attach them to the start of each source file to most effectively 290 | convey the exclusion of warranty; and each file should have at least 291 | the "copyright" line and a pointer to where the full notice is found. 292 | 293 | {description} 294 | Copyright (C) {year} {fullname} 295 | 296 | This program is free software; you can redistribute it and/or modify 297 | it under the terms of the GNU General Public License as published by 298 | the Free Software Foundation; either version 2 of the License, or 299 | (at your option) any later version. 300 | 301 | This program is distributed in the hope that it will be useful, 302 | but WITHOUT ANY WARRANTY; without even the implied warranty of 303 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 304 | GNU General Public License for more details. 305 | 306 | You should have received a copy of the GNU General Public License along 307 | with this program; if not, write to the Free Software Foundation, Inc., 308 | 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. 309 | 310 | Also add information on how to contact you by electronic and paper mail. 311 | 312 | If the program is interactive, make it output a short notice like this 313 | when it starts in an interactive mode: 314 | 315 | Gnomovision version 69, Copyright (C) year name of author 316 | Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'. 317 | This is free software, and you are welcome to redistribute it 318 | under certain conditions; type `show c' for details. 319 | 320 | The hypothetical commands `show w' and `show c' should show the appropriate 321 | parts of the General Public License. Of course, the commands you use may 322 | be called something other than `show w' and `show c'; they could even be 323 | mouse-clicks or menu items--whatever suits your program. 324 | 325 | You should also get your employer (if you work as a programmer) or your 326 | school, if any, to sign a "copyright disclaimer" for the program, if 327 | necessary. Here is a sample; alter the names: 328 | 329 | Yoyodyne, Inc., hereby disclaims all copyright interest in the program 330 | `Gnomovision' (which makes passes at compilers) written by James Hacker. 331 | 332 | {signature of Ty Coon}, 1 April 1989 333 | Ty Coon, President of Vice 334 | 335 | This General Public License does not permit incorporating your program into 336 | proprietary programs. If your program is a subroutine library, you may 337 | consider it more useful to permit linking proprietary applications with the 338 | library. If this is what you want to do, use the GNU Lesser General 339 | Public License instead of this License. 340 | -------------------------------------------------------------------------------- /README.rst: -------------------------------------------------------------------------------- 1 | Linux Kernel 2 | ============ 3 | 4 | This repository contains various scripts that I have found useful while doing Linux kernel 5 | development. 6 | 7 | Also included is introductory material on kernel development written by me. 8 | 9 | Directory listing: 10 | 11 | - ``tutorial/`` - Presentation for Open Source Summit in Los Angeles, 2017 12 | - ``workshop/`` - Presentation for Open Source Summit in San Diego, 2019 13 | -------------------------------------------------------------------------------- /SUBMIT.rst: -------------------------------------------------------------------------------- 1 | Patch Submission 2 | ================ 3 | 4 | Customized for development on drivers/staging/ 5 | 6 | Before submitting patches we need to: 7 | 8 | 1. Each Patch: 9 | - does one thing only (no unnecessary code churn) 10 | - builds 11 | 12 | 2. Check headers: `make headers_check` 13 | 14 | 3. Check with checkpatch.pl: `checkpatch --strict --terse` 15 | 16 | 4. Check files touched with Smatch: `kchecker drivers/staging/modified.c` 17 | 18 | 5. Check with Sparse: `make -j9 C=2 M=drivers/staging/foo 2> sparse.out` 19 | 20 | 6. Apply and build on clean branch `apply-and-build.sh /path/to/patchset/` 21 | 22 | 7. Repeat step 6 on a different architecture (or cross-compile). 23 | 24 | 25 | * Is this a fix for another patch? If so add a tag. 26 | 27 | .. code:: bash 28 | 29 | Fixes: 7676b72428e8 ("staging: ks7010: move comparison to right hand side") 30 | 31 | You can generate the string by doing 32 | 33 | .. code:: bash 34 | 35 | git show -s --abbrev-commit --abbrev=12 --pretty=format:"%h (\"%s\")%n" 7676b72 36 | -------------------------------------------------------------------------------- /apply-and-build.sh: -------------------------------------------------------------------------------- 1 | #!/bin/bash 2 | # 3 | # apply-and-build.sh - apply patches and build kernel 4 | 5 | # Author: Tobin Harding 6 | # Copyright (c) 2017 Tobin Harding 7 | 8 | # The skeleton for this script and all the standard 9 | # utilities are taken from The Rust Project 10 | 11 | # Copyright (c) 2015 The Rust Project Developers 12 | 13 | # Permission is hereby granted, free of charge, to any 14 | # person obtaining a copy of this software and associated 15 | # documentation files (the "Software"), to deal in the 16 | # Software without restriction, including without 17 | # limitation the rights to use, copy, modify, merge, 18 | # publish, distribute, sublicense, and/or sell copies of 19 | # the Software, and to permit persons to whom the Software 20 | # is furnished to do so, subject to the following 21 | # conditions: 22 | 23 | # The above copyright notice and this permission notice 24 | # shall be included in all copies or substantial portions 25 | # of the Software. 26 | 27 | # THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF 28 | # ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED 29 | # TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A 30 | # PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT 31 | # SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY 32 | # CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION 33 | # OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR 34 | # IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER 35 | # DEALINGS IN THE SOFTWARE. 36 | 37 | 38 | set -u # Undefined variables are errors 39 | 40 | main() { 41 | assert_cmds 42 | set_globals 43 | handle_command_line_args "$@" 44 | apply_and_build 45 | } 46 | 47 | set_globals() { 48 | # Environment sanity checks 49 | assert_nz "$HOME" "\$HOME is undefined" 50 | assert_nz "$0" "\$0 is undefined" 51 | 52 | script=${0##*/} # script name 53 | nthreads=9 54 | patch_dir="" 55 | } 56 | 57 | handle_command_line_args () { 58 | if (( $# < 1 )) 59 | then 60 | echo "Usage: $0 " 61 | exit 1 62 | fi 63 | 64 | patch_dir=$1 65 | } 66 | 67 | apply_and_build () { 68 | # check we are in a git repo 69 | ensure ls '.git' > /dev/null 70 | 71 | # check we are on staging-next branch 72 | ensure git branch | grep staging-next > /dev/null 73 | 74 | # update tree 75 | ensure git pull 76 | 77 | # save current HEAD 78 | _head=$(git log -1 --pretty=oneline --abbrev-commit | awk '{print $1}') 79 | 80 | # apply and build each patch 81 | for file in $(ls $patch_dir) 82 | do 83 | # check file is not a cover letter 84 | [ ${file:0:4} == "0000" ] && continue 85 | 86 | # check for directories (holding previous versions) 87 | [ -d $file ] && continue 88 | 89 | _patch="$patch_dir/$file" 90 | ensure git apply --check $_patch 91 | 92 | ensure git am -3 < $_patch 93 | 94 | ensure make -j$nthreads EXTRA-CFLAGS=-W >/dev/null 95 | done 96 | 97 | # clean up 98 | git reset --hard $_head 99 | 100 | echo "" 101 | echo "All patches applied and built successfully!" 102 | } 103 | 104 | assert_success() { 105 | err_msg="$1" 106 | 107 | if (( $? != 0 )) 108 | then 109 | echo $err_msg 110 | exit 1 111 | fi 112 | } 113 | 114 | # Standard utilities 115 | # 116 | # Taken from: https://github.com/rust-lang/rustup.sh 117 | 118 | say() { 119 | echo "$script: $1" 120 | } 121 | 122 | say_err() { 123 | say "$1" >&2 124 | } 125 | 126 | verbose_say() { 127 | if [ "$flag_verbose" = true ]; then 128 | say "$1" 129 | fi 130 | } 131 | 132 | err() { 133 | say "$1" >&2 134 | exit 1 135 | } 136 | 137 | need_cmd() { 138 | if ! command -v "$1" > /dev/null 2>&1 139 | then err "need '$1' (command not found)" 140 | fi 141 | } 142 | 143 | need_ok() { 144 | if [ $? != 0 ]; then err "$1"; fi 145 | } 146 | 147 | assert_nz() { 148 | if [ -z "$1" ]; then err "assert_nz $2"; fi 149 | } 150 | 151 | # Run a command that should never fail. If the command fails execution 152 | # will immediately terminate with an error showing the failing 153 | # command. 154 | ensure() { 155 | "$@" 156 | need_ok "command failed: $*" 157 | } 158 | 159 | # This is just for indicating that commands' results are being 160 | # intentionally ignored. Usually, because it's being executed 161 | # as part of error handling. 162 | ignore() { 163 | run "$@" 164 | } 165 | 166 | # Runs a command and prints it to stderr if it fails. 167 | run() { 168 | "$@" 169 | local _retval=$? 170 | if [ $_retval != 0 ]; then 171 | say_err "command failed: $*" 172 | fi 173 | return $_retval 174 | } 175 | 176 | # Prints the absolute path of a directory to stdout 177 | abs_path() { 178 | local _path="$1" 179 | # Unset CDPATH because it causes havok: it makes the destination unpredictable 180 | # and triggers 'cd' to print the path to stdout. Route `cd`'s output to /dev/null 181 | # for good measure. 182 | (unset CDPATH && cd "$_path" > /dev/null && pwd) 183 | } 184 | 185 | assert_cmds() { 186 | need_cmd ls 187 | need_cmd git 188 | need_cmd make 189 | } 190 | 191 | # 192 | # Run main 193 | # 194 | 195 | main "$@" 196 | 197 | -------------------------------------------------------------------------------- /cpt.sh: -------------------------------------------------------------------------------- 1 | #!/bin/bash 2 | # 3 | # Run checkpatch over a directory of patches 4 | # Exclude the cover-letter 5 | 6 | base="/home/tobin/build/kdev/patches" 7 | checkpatch='/home/tobin/build/kdev/linux/scripts/checkpatch.pl' 8 | 9 | main() { 10 | local dir=$1 11 | local path="$base/$dir" 12 | 13 | if [ ! -d $path ]; then 14 | echo "dir not found: $path" 15 | exit 1 16 | fi 17 | 18 | for patch in $(ls $path); do 19 | # Skip archives, apply, and old versions. 20 | if [ -d "$path/$patch" ]; then 21 | continue 22 | fi 23 | 24 | sub=${patch:0:4} # 0000-foo-bar.patch 25 | subv=${patch:3:4} # v4-0000-foo-bar.patch 26 | if [ $sub == "0000" ] || [ $subv == "0000" ]; then 27 | # echo "found cover-letter: $patch" 28 | continue 29 | fi 30 | $checkpatch --terse --strict $path/$patch 31 | done 32 | } 33 | 34 | # 35 | # main script 36 | # 37 | 38 | if [[ $# < 1 ]]; then 39 | echo "" 40 | echo "Usage: cpt-dir " 41 | echo "" 42 | echo " Expects to be in $base" 43 | echo "" 44 | exit 1 45 | fi 46 | 47 | main $@ 48 | -------------------------------------------------------------------------------- /git-am-dir.sh: -------------------------------------------------------------------------------- 1 | #!/bin/bash 2 | # 3 | # git-am-dir.sh - apply patches 4 | 5 | # Author: Tobin Harding 6 | # Copyright (c) 2017 Tobin Harding 7 | 8 | # The skeleton for this script and all the standard 9 | # utilities are taken from The Rust Project 10 | 11 | # Copyright (c) 2015 The Rust Project Developers 12 | 13 | # Permission is hereby granted, free of charge, to any 14 | # person obtaining a copy of this software and associated 15 | # documentation files (the "Software"), to deal in the 16 | # Software without restriction, including without 17 | # limitation the rights to use, copy, modify, merge, 18 | # publish, distribute, sublicense, and/or sell copies of 19 | # the Software, and to permit persons to whom the Software 20 | # is furnished to do so, subject to the following 21 | # conditions: 22 | 23 | # The above copyright notice and this permission notice 24 | # shall be included in all copies or substantial portions 25 | # of the Software. 26 | 27 | # THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF 28 | # ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED 29 | # TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A 30 | # PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT 31 | # SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY 32 | # CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION 33 | # OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR 34 | # IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER 35 | # DEALINGS IN THE SOFTWARE. 36 | 37 | 38 | set -u # Undefined variables are errors 39 | 40 | main() { 41 | assert_cmds 42 | set_globals 43 | handle_command_line_args "$@" 44 | apply 45 | } 46 | 47 | set_globals() { 48 | # Environment sanity checks 49 | assert_nz "$HOME" "\$HOME is undefined" 50 | assert_nz "$0" "\$0 is undefined" 51 | 52 | script=${0##*/} # script name 53 | nthreads=9 54 | patch_dir="" 55 | } 56 | 57 | handle_command_line_args () { 58 | if (( $# < 1 )) 59 | then 60 | echo "Usage: $0 " 61 | exit 1 62 | fi 63 | 64 | patch_dir=$1 65 | } 66 | 67 | apply () { 68 | # check we are in a git repo 69 | ensure ls '.git' > /dev/null 70 | 71 | # apply each patches 72 | for file in $(ls $patch_dir) 73 | do 74 | # Skip archives, apply, and old versions. 75 | if [ -d "$patch_dir/$file" ]; then 76 | continue 77 | fi 78 | 79 | sub=${file:0:4} # 0000-foo-bar.patch 80 | subv=${file:3:4} # v4-0000-foo-bar.patch 81 | if [ $sub == "0000" ] || [ $subv == "0000" ]; then 82 | # echo "found cover-letter: $patch" 83 | continue 84 | fi 85 | 86 | _patch="$patch_dir/$file" 87 | ensure git apply --check $_patch 88 | 89 | ensure git am -3 < $_patch 90 | done 91 | 92 | echo "" 93 | echo "All patches applied and built successfully!" 94 | } 95 | 96 | assert_success() { 97 | err_msg="$1" 98 | 99 | if (( $? != 0 )) 100 | then 101 | echo $err_msg 102 | exit 1 103 | fi 104 | } 105 | 106 | # Standard utilities 107 | # 108 | # Taken from: https://github.com/rust-lang/rustup.sh 109 | 110 | say() { 111 | echo "$script: $1" 112 | } 113 | 114 | say_err() { 115 | say "$1" >&2 116 | } 117 | 118 | verbose_say() { 119 | if [ "$flag_verbose" = true ]; then 120 | say "$1" 121 | fi 122 | } 123 | 124 | err() { 125 | say "$1" >&2 126 | exit 1 127 | } 128 | 129 | need_cmd() { 130 | if ! command -v "$1" > /dev/null 2>&1 131 | then err "need '$1' (command not found)" 132 | fi 133 | } 134 | 135 | need_ok() { 136 | if [ $? != 0 ]; then err "$1"; fi 137 | } 138 | 139 | assert_nz() { 140 | if [ -z "$1" ]; then err "assert_nz $2"; fi 141 | } 142 | 143 | # Run a command that should never fail. If the command fails execution 144 | # will immediately terminate with an error showing the failing 145 | # command. 146 | ensure() { 147 | "$@" 148 | need_ok "command failed: $*" 149 | } 150 | 151 | # This is just for indicating that commands' results are being 152 | # intentionally ignored. Usually, because it's being executed 153 | # as part of error handling. 154 | ignore() { 155 | run "$@" 156 | } 157 | 158 | # Runs a command and prints it to stderr if it fails. 159 | run() { 160 | "$@" 161 | local _retval=$? 162 | if [ $_retval != 0 ]; then 163 | say_err "command failed: $*" 164 | fi 165 | return $_retval 166 | } 167 | 168 | # Prints the absolute path of a directory to stdout 169 | abs_path() { 170 | local _path="$1" 171 | # Unset CDPATH because it causes havok: it makes the destination unpredictable 172 | # and triggers 'cd' to print the path to stdout. Route `cd`'s output to /dev/null 173 | # for good measure. 174 | (unset CDPATH && cd "$_path" > /dev/null && pwd) 175 | } 176 | 177 | assert_cmds() { 178 | need_cmd ls 179 | need_cmd git 180 | need_cmd make 181 | } 182 | 183 | # 184 | # Run main 185 | # 186 | 187 | main "$@" 188 | 189 | -------------------------------------------------------------------------------- /mailing-list-etiqutte.rst: -------------------------------------------------------------------------------- 1 | Linux Kernel Mailing List Etiquette 2 | =================================== 3 | 4 | Kernel developers are on email *all* day. They have developed a set of 5 | procedures that facilitate this with ease. Here are some things you 6 | may find useful. 7 | 8 | - Miscellaneous newbie questions go to kernelnewbies mailing 9 | list. Specific *intelligent* questions relating to a kernel subsystem 10 | go to the subsystem mailing list. If you are new you almost certainly 11 | do not want to post to LKML. 12 | 13 | - All kernel development is done in the open, this means via 14 | mailing lists. Always maintain the complete CC list when responding 15 | to mailing list mail. Never email a kernel developer [about kernel 16 | development] 'in private' i.e without CC'ing a mailing list. 17 | 18 | - You will make mistakes, doing so is very hard on the ego, you are 19 | going to have to deal with it. 20 | 21 | - Never top post, see https://daringfireball.net/2007/07/on_top 22 | 23 | - Be polite. Please, thank you etc. No one *has* to respond to you, if 24 | they do so acknowledge their response. 25 | 26 | - Wait at least two weeks before following up on a previous email/patch. 27 | 28 | - State your position clearly in as well a thought out, and researched 29 | manner as possible. 30 | 31 | - Always use correct grammar, spelling and punctuation to the best of 32 | your ability. If English is your first language then make the effort 33 | to write it correctly. 34 | 35 | - Do not argue with reviewers. This cannot be overstated. Sure, 36 | reviewers make mistakes but if you are new to kernel development 37 | then you are almost certainly wrong. 38 | 39 | - Try to learn the first time someone tells you something. If you 40 | really cannot understand, by all means ask for clarification. If you 41 | still don't get it, go away and read up, people are usually happy 42 | to point you towards further reading on the topic. No one likes 43 | saying the same thing three times. 44 | 45 | -------------------------------------------------------------------------------- /quotes.rst: -------------------------------------------------------------------------------- 1 | 2 | Amusing Kernel Quotes 3 | ===================== 4 | 5 | - Fire up your editor and come join us; you will be more than welcome. 6 | 7 | - Printf should not be used for chit-chat 8 | 9 | - If I could give you one piece of advice: never sleep with anyone crazier than 10 | yourself. But if I had to give you advice on locking: keep it simple. 11 | 12 | - Deadlocks are problematic, but not as bad as data corruption. Code which grabs 13 | a read lock, searches a list, fails to find what it wants, drops the read 14 | lock, grabs a write lock and inserts the object has a race condition. 15 | 16 | If you don't see why, please stay the fuck away from my code. 17 | 18 | (Linus) 19 | 20 | - This conversation is unreal. Just remove the misguided assert and 21 | you're good. After that, please have someone explain basic reference 22 | counting to you. 23 | 24 | (Andreas) 25 | 26 | 27 | 28 | -------------------------------------------------------------------------------- /slabinfo-simple.c: -------------------------------------------------------------------------------- 1 | #include 2 | #include 3 | #include 4 | #include 5 | #include 6 | #include 7 | #include 8 | #include 9 | #include 10 | #include 11 | #include 12 | #include 13 | #include 14 | 15 | #define MAX_SLABS 10 16 | 17 | struct slabinfo { 18 | char *name; 19 | int aliases; 20 | unsigned long partial; 21 | unsigned int object_size; 22 | }slabinfo[MAX_SLABS]; 23 | 24 | int show_alias; 25 | int slabs; 26 | 27 | char buffer[4096]; 28 | 29 | static void fatal(const char *x, ...) 30 | { 31 | va_list ap; 32 | 33 | va_start(ap, x); 34 | vfprintf(stderr, x, ap); 35 | va_end(ap); 36 | exit(EXIT_FAILURE); 37 | } 38 | 39 | static unsigned long read_obj(const char *name) 40 | { 41 | FILE *f = fopen(name, "r"); 42 | 43 | if (!f) 44 | buffer[0] = 0; 45 | else { 46 | if (!fgets(buffer, sizeof(buffer), f)) 47 | buffer[0] = 0; 48 | fclose(f); 49 | if (buffer[strlen(buffer)] == '\n') 50 | buffer[strlen(buffer)] = 0; 51 | } 52 | return strlen(buffer); 53 | } 54 | 55 | static void slabcache(struct slabinfo *s) 56 | { 57 | if (strcmp(s->name, "*") == 0) 58 | return; 59 | 60 | printf("%-21s %8d", s->name, s->aliases); 61 | 62 | } 63 | 64 | static void output_slabs(void) 65 | { 66 | struct slabinfo *slab; 67 | 68 | for (slab = slabinfo; (slab < slabinfo + slabs); slab++) { 69 | slabcache(slab); 70 | } 71 | } 72 | 73 | struct option opts[] = { 74 | { "aliases", no_argument, NULL, 'a' }, 75 | { NULL, 0, NULL, 0 } 76 | }; 77 | 78 | int main(int argc, char *argv[]) 79 | { 80 | int c; 81 | 82 | while ((c = getopt_long(argc, argv, "a", opts, NULL)) != -1) 83 | switch (c) { 84 | case 'a': 85 | show_alias = 1; 86 | break; 87 | default: 88 | fatal("%s: Invalid option '%c'\n", argv[0], optopt); 89 | 90 | } 91 | 92 | output_slabs(); 93 | 94 | return 0; 95 | } 96 | -------------------------------------------------------------------------------- /tutorial/README.rst: -------------------------------------------------------------------------------- 1 | =========================================================== 2 | Hacking Device Drivers - How to get into kernel development 3 | =========================================================== 4 | 5 | This tutorial is presented as two tracks. This was done in order to cater to differing levels of 6 | ability and experience. Please feel free to choose whichever track appeals to you as most enjoyable. 7 | 8 | Prerequisites 9 | ------------- 10 | 11 | This tutorial assumes that you have submitted a single kernel patch to the Linux kernel device 12 | driver mailing list. If you have not done this you may find it useful to work through the process of 13 | doing so. Here is a quick list of what you need; 14 | 15 | - To have cloned Greg Kroah-Hartman's staging tree. 16 | - To have configured the kernel to build staging drivers. 17 | - Have a kernel development environment set up (editor, mail client, git). 18 | - Have subscribed to the Linux kernel device driver mailing list. 19 | 20 | These steps are briefly outlined here_ and more thoroughly in this blog_ post and 21 | on kernelnewbies_. 22 | 23 | .. _here: ../2.First-patch.rst 24 | .. _blog: http://tobin.cc/blog/kernel-dev-1 25 | .. _kernelnewbies: https://kernelnewbies.org/FirstKernelPatch 26 | 27 | Track One_ 28 | --------- 29 | 30 | .. _One: track-one.rst 31 | 32 | This track builds on the prerequisites and aims to be easily achievable within the two hour time 33 | slot. If you are most interested in the process of kernel development without being bothered, at this 34 | stage, in exactly what you are working on then choose this track. This is also the easier of the two. 35 | 36 | - More structured, easier. 37 | - Based on an old kernel version (v4.9). 38 | - Work on ks7010 Wi-Fi driver. 39 | - Should easily complete within 2 hours. 40 | 41 | Track Two_ 42 | --------- 43 | 44 | .. _Two: track-two.rst 45 | 46 | This track has less hand holding, you do actual real work that can be submitted to the 47 | kernel. Choose this track if you like to explore more, you are more experienced or you don't mind 48 | whether you finish in 2 hours or not. 49 | 50 | - Less structured. 51 | - Harder (more to figure out for yourself). 52 | - Based on the current staging tree. 53 | - Work on which ever driver you please. 54 | - May or may not complete within the two hours. 55 | 56 | 57 | **If you choose Track One you can always complete Track Two later if it amuses you.** 58 | 59 | -------------------------------------------------------------------------------- /tutorial/cheat-sheet.rst: -------------------------------------------------------------------------------- 1 | Cheat Sheet 2 | =========== 3 | 4 | - Supply default answer for all prompted `make oldconfig` questions 5 | 6 | .. code:: bash 7 | 8 | yes "" | make oldconfig 9 | 10 | - Kernel build command, N = Number of cores (or hypethreads) + 1 11 | 12 | .. code:: bash 13 | 14 | make -jN EXTRA-CFLAGS=-W >/dev/null 15 | 16 | - Build the FOO module only 17 | 18 | .. code:: bash 19 | 20 | make -jN EXTRA-CFLAGS=-W M=drivers/staging/FOO >/dev/null 21 | 22 | - Checkpatch 23 | 24 | .. code:: bash 25 | 26 | scripts/checkpatch.pl --terse --strict --show-types drivers/staging/FOO/*.{ch} 27 | 28 | - Git view commits in patch format 29 | 30 | .. code:: bash 31 | 32 | git log --color=always --patch --reverse HEAD~~~.. | less 33 | 34 | - Git format patch 35 | 36 | .. code:: bash 37 | 38 | git format-patch -3 -o path/to/patch/dir --cover-letter 39 | 40 | - Git send email 41 | 42 | .. code:: bash 43 | 44 | git send-email --to='me@gmail.com' path/to/patch/dir/*.patch 45 | git send-email --to-cover --cc-cover path/to/patch/dir/*.patch 46 | 47 | -------------------------------------------------------------------------------- /tutorial/prerequisite.rst: -------------------------------------------------------------------------------- 1 | Tutorial Prerequisites 2 | ====================== 3 | 4 | 1. Clone Greg Kroah-Hartman's staging tree 5 | 6 | .. code:: bash 7 | 8 | git clone git://git.kernel.org/pub/scm/linux/kernel/git/gregkh/staging.git 9 | 10 | 2. Build the staging kernel 11 | 12 | NOTE: The tutorial is presented as two tracks of differing difficulty. If you don't want to wait 13 | for the kernel to build during the tutorial and you think you will attempt the easier of the two 14 | tracks then you should checkout the 4.9 kernel and build it. 15 | 16 | .. code:: bash 17 | 18 | git checkout -b tutorial 69973b8 19 | 20 | 21 | -------------------------------------------------------------------------------- /tutorial/shell-utils.sh: -------------------------------------------------------------------------------- 1 | # 2 | # Miscellaneous kernel shell functions and aliases. 3 | # 4 | 5 | # View git index (see below for function). 6 | alias l=git-log-abbrev 7 | 8 | # Patch of working directory changes. 9 | alias wp=git diff --color=always | less 10 | 11 | # Patch of previous commits (see below for function). 12 | alias lp=git-log-patch 13 | 14 | # Set -jN flag for your machine. N = num cores (or hypethreads) + 1 15 | alias k-build=make -j9 EXTRA-CFLAGS=-W >/dev/null 16 | 17 | # Build ks7010 device driver, must be run from kernel tree root dir. 18 | function build-ks7010() { 19 | local dir='drivers/staging/ks7010' 20 | 21 | rm -f $dir/*.o 22 | rm -f $dir/*.ko 23 | rm -f $dir/*.mod.c 24 | 25 | make -j9 EXTRA-CFLAGS=-W M=$dir 26 | } 27 | 28 | 29 | # Clean up kernel build files. 30 | function k-clean() { 31 | rm *.o 32 | rm *.ko 33 | rm *.mod.c 34 | clean-dir 35 | } 36 | 37 | # Clean directory of autosaves (emacs users). 38 | function clean-dir { 39 | ls *~ 2> /dev/null 40 | if (( $? == 0 )) 41 | then 42 | rm -f *~ 2> /dev/null 43 | fi 44 | ls \#*\# 2> /dev/null 45 | if (( $? == 0 )) 46 | then 47 | rm -f \#*\# 2> /dev/null 48 | fi 49 | 50 | return 0 51 | } 52 | 53 | # git log 54 | function git-log-abbrev () { 55 | # number of commits from index to view, default 1 56 | local N=${1:-20} 57 | 58 | git log -$N --pretty=oneline --abbrev-commit --reverse 59 | } 60 | 61 | # git patch view 62 | function git-log-patch() { 63 | local commit 64 | 65 | if (( $# < 1 )) 66 | then 67 | commit="HEAD~" # default to last commit 68 | else 69 | commit="$1" 70 | fi 71 | 72 | git log --color=always --patch --reverse "${commit}".. | less 73 | } 74 | -------------------------------------------------------------------------------- /tutorial/track-one.rst: -------------------------------------------------------------------------------- 1 | ========= 2 | Track One 3 | ========= 4 | 5 | In this track we will be working on an old kernel. The patch series you create here will not be able 6 | to be submitted to the kernel. The process, however, to do a real patch set is the same. See Track 7 | Two if you would like to jump straight into doing a series that can be submitted to the kernel. 8 | 9 | 1. Tree 10 | ------- 11 | 12 | .. code:: bash 13 | 14 | KERNEL=path/to/gregKH/staging/ 15 | 16 | - Check out the 4.9 kernel 17 | 18 | .. code:: bash 19 | 20 | git checkout -b tutorial 69973b8 21 | 22 | - Verify the following config options are enabled (grep $KERNEL/.config) 23 | 24 | .. code:: bash 25 | 26 | CONFIG_STAGING=y 27 | CONFIG_KS7010=m 28 | 29 | - Build the kernel (you may like to go on to step 2 while you build) 30 | 31 | .. code:: bash 32 | 33 | make -j9 EXTRA-CFLAGS=-W >/dev/null 34 | 35 | - Verify ks7010 module built 36 | 37 | .. code:: bash 38 | 39 | ls drivers/staging/ks7010 | grep '\.ko' 40 | 41 | 2. Checkpatch 42 | ------------- 43 | 44 | - You may like to define a shell alias 45 | 46 | .. code:: bash 47 | 48 | alias checkpatch="$KERNEL/scripts/checkpatch.pl -f" 49 | 50 | - Run `checkpatch` on the C source [and/or header] files in the ks7010 driver 51 | 52 | .. code:: bash 53 | 54 | checkpatch --terse --strict --show-types drivers/staging/ks7010/*.c 55 | 56 | - Pick 3 types of warnings to fix 57 | 58 | *All checkpatch output types CHECK, WARNING, and ERROR herein referred to as warnings.* 59 | 60 | Go on, be brave, don't just do white space fixes :) You may like to save the output from 61 | checkpatch to a file. 62 | 63 | - Fix a single warning type 64 | 65 | Typically you would fix all instances of a warning type in a single patch. For the sake of 66 | brevity you may prefer to just fix a few of them. Verify that your change fixes the warning. 67 | 68 | Once you have done fixing a single warning type commit your changes (see next bullet point). 69 | 70 | You may like to run `checkpatch` again after you have made your change to ensure you have not 71 | introduced any new warnings. Alternatively, `diff` the checkpatch output against the original 72 | output that you saved to confirm you have cleared the warning. 73 | 74 | - Write a thorough, descriptive commit log 75 | 76 | You may like to read (specifically Section 2 - Describe your changes) 77 | 78 | .. code:: 79 | 80 | Documentation/process/submitting-patches.rst 81 | 82 | 83 | Here is an example git log for a simple checkpatch fix. 84 | 85 | .. code:: bash 86 | 87 | staging: ks7010: remove unnecessary parenthesis 88 | 89 | Checkpatch emits CHECK: Unnecessary parentheses. 90 | 91 | Remove unnecessary parentheses. 92 | 93 | - Build the module 94 | 95 | All patches to the kernel must build cleanly. This means every patch within a 96 | series must build cleanly, not just the last one. 97 | 98 | .. code:: bash 99 | 100 | make -j9 M=drivers/staging/ks7010 >/dev/null 101 | 102 | - Repeat for the other two warning types you picked 103 | 104 | 3. Patch Set 105 | ------------ 106 | 107 | By this stage you should have three commits in your git index, each fixing a specific 'warning' 108 | type. Each commit is described fully in the commit log and each commit builds cleanly. 109 | 110 | - Read through the diff of all three commits checking for any mistakes. 111 | 112 | .. code:: bash 113 | 114 | git log --color=always --patch --reverse HEAD~~~.. | less 115 | 116 | - Now use git to output a patch series 117 | 118 | .. code:: bash 119 | 120 | git format-patch -3 -o path/to/patch/dir --cover-letter 121 | 122 | - Write the cover letter. 123 | 124 | For a simple series like this a brief sentence describing the series will suffice. 125 | 126 | - Email the patch set to your self. 127 | 128 | This is a useful step when getting started so you can verify that everything looks good. 129 | 130 | .. code:: bash 131 | 132 | git send-email --to='me@mail.com' path/to/patch/dir/*.patch 133 | 134 | Final 135 | ----- 136 | 137 | Now, in real life, you would email this patch set to the device driver mailing list. Well done. Now 138 | (or later) you can repeat this process on top of the current staging-next branch and submit your 139 | first patch set to the Linux kernel. 140 | 141 | -------------------------------------------------------------------------------- /tutorial/track-two.rst: -------------------------------------------------------------------------------- 1 | ========= 2 | Track Two 3 | ========= 4 | 5 | In this track we will craft a small patch series that may be submitted to the kernel. This track is 6 | purposefully open and is meant to be a guide only. If you would prefer a more concrete task see 7 | Track One. 8 | 9 | - Base your series off of the staging-next branch of GregKH's staging tree. 10 | 11 | - Pick a driver to work on from `drivers/staging/` (see ../3.First-patch-set.rst for tips). 12 | 13 | - Run checkpatch on 'your' driver 14 | 15 | .. code:: bash 16 | 17 | scripts/checkpatch.pl --terse --strict --show-types drivers/staging/FOO/*.{ch} 18 | 19 | If you'd like something more challenging you may like to try `Sparse` errors. 20 | 21 | .. code:: bash 22 | 23 | make C=2 M=drivers/staging/FOO 24 | 25 | - Pick three warnings that you feel you can fix. You should be sure to understand fully the code 26 | changes you are making. Don't bother with 'line over 80' warnings. If you are going to do 27 | white space fixes be sure to get it correct, look at other code and rerun checkpatch on your 28 | changes to verify you cleared the warning. Remember however that `checkpatch.pl` is just a dumb 29 | script, understand the reason you are getting the warning before you fix it. 30 | 31 | - Fix each warning type (or Sparse error) in a single patch. Fix all instances of the warning type 32 | within the driver. Each commit will need a thorough commit log. See section 2 of 33 | 34 | .. code:: 35 | 36 | Documentation/process/submitting-patches.rst 37 | 38 | The importance of a correct and thorough commit log cannot be overstated. The kernel git log has 39 | it's own style. It takes a bit of getting used to, kernel commit logs are one of those things that 40 | you can refine for a very long time. Putting in the effort to learn how to write a good commit log 41 | is essential if you wish to progress further as a kernel developer. 42 | 43 | - Once you have three commits in your index, verify your changes are correct. 44 | 45 | .. code:: bash 46 | 47 | git log --color=always --patch --reverse HEAD~~~.. | less 48 | 49 | If you need to fix something up you can rebase 50 | 51 | .. code:: bash 52 | 53 | git rebase -i HEAD~~~ 54 | 55 | - Verify your patches **all** apply and build cleanly on top of the `staging-next` branch. You can do 56 | this manually, you can hack a quick shell script to do it, or you can use `../apply-and-build.sh`. 57 | 58 | - Output a correctly linked patch set ready for submission 59 | 60 | .. code:: bash 61 | 62 | git format-patch -3 -o path/to/patch/dir --cover-letter 63 | 64 | - Ascertain the recipients of your patch set (check the TODO within the driver if present) 65 | 66 | .. code:: bash 67 | 68 | scripts/get_maintainer.pl path/to/patch/dir/*.patch 69 | 70 | - Write the cover letter. This can be anything from an exhaustive explanation of what the series 71 | does to a brief few line sentence. For a simple series like this, you may like to lean towards the 72 | latter. 73 | 74 | - [Email the series to yourself] 75 | 76 | .. code:: bash 77 | 78 | git send-email --to='me@gmail.com' path/to/patch/dir/*.patch 79 | 80 | - Submit the series for real. If you add the `To:` and `Cc:` headers to the cover letter then 81 | the following command does what you need 82 | 83 | .. code:: bash 84 | 85 | git send-email --to-cover --cc-cover path/to/patch/dir/*.patch 86 | 87 | 88 | **Profit!** 89 | -------------------------------------------------------------------------------- /tutorial/trouble-shoot.rst: -------------------------------------------------------------------------------- 1 | Trouble shooting 2 | ================ 3 | 4 | Kernel Build Errors 5 | ------------------- 6 | 7 | - If you get build errors referring to ssl, you may need to install the ssl development library. 8 | 9 | .. code:: bash 10 | 11 | libssl-dev 12 | 13 | - On Debian based distro's, if you get a build error containing 14 | 15 | .. code:: bash 16 | 17 | needed by 'certs/x509_certificate_list' 18 | 19 | You may need to set your config to 20 | 21 | .. code:: bash 22 | 23 | CONFIG_SYSTEM_TRUSTED_KEYRING=n 24 | # CONFIG_SYSTEM_TRUSTED_KEYS="" 25 | 26 | - Make error 27 | 28 | .. code:: bash 29 | 30 | make[2]: *** [silentoldconfig] Error 1 31 | make[1]: *** [silentoldconfig] Error 2 32 | make: *** No rule to make target 'include/config/auto.conf', needed by 'include/config/kernel.release'. Stop. 33 | make: *** Waiting for unfinished jobs.... 34 | 35 | Can be resolved by running 36 | 37 | .. code:: bash 38 | 39 | yes "" | make oldconfig 40 | 41 | - If you want to start the build process fresh 42 | 43 | 1. Run `make mrproper` (this removes .config) 44 | 2. Create .config (either from a backup or from a running config) 45 | 3. Run `make yes "" | make oldconfig` 46 | 4. Run `make` 47 | 48 | Git 49 | --- 50 | 51 | - If you get an error when using `git send-email` you may need to install the `git-email` package. See 52 | 53 | https://burzalodowa.wordpress.com/2013/10/05/how-to-send-patches-with-git-send-email/ 54 | 55 | -------------------------------------------------------------------------------- /workshop/README.rst: -------------------------------------------------------------------------------- 1 | =========================================================== 2 | Hacking Device Drivers - How to get into kernel development 3 | =========================================================== 4 | 5 | Workshop - Open Source Summit North America 2019 6 | 7 | Presented by: Tobin C. Harding 8 | 9 | Welcome to the workshop, thank you for giving up your time to come here. For 10 | the workshop we will be hacking on staging drivers within the kernel tree. 11 | 12 | The hoped outcome of the workshop is to get everyone to submit a three patch 13 | series to LKML. Like all good projects the workshop should be challenging but 14 | achievable. In order to achieve this there are multiple projects. Please pick 15 | the one that looks the most enjoyable to you. Please consider working in a 16 | group of two or three, pair programming is fun and you will almost certainly 17 | learn something from each other. 18 | 19 | All projects require the same set up to get started, please see setup_. 20 | 21 | Once you have a kernel built (or building) please select from one of the 22 | following (listed in order of complexity). 23 | 24 | The aim of this workshop is to fill the current knowledge gap I ran into between 25 | creating your first kernel patch and being a 'real' kernel developer. For me at 26 | least, the next step after my first patch was to *really* learn the kernel 27 | development process. With this experience I feel that patching 28 | ``drivers/staging`` a **lot** is a good method for learning this process and 29 | getting comfortable patching the kernel. As such, I would expect most people to 30 | work on project one. The others were really added just in case project one 31 | was too easy. 32 | 33 | 1. Checkpatch your way to glory: checkpatch_ 34 | 35 | 2. Probe and release: probe-and-release_ 36 | 37 | 3. Sparse, spatch, and Coccinelle: further-tools_ 38 | 39 | 40 | Other material 41 | -------------- 42 | 43 | This workshop is a re-write of the tutorial I gave in LA for OSS in 2017. Some 44 | of the material from that may bu useful, specifically 45 | 46 | - tutorial/cheat-sheet_ 47 | - tutorial/trouble-shoot_ 48 | 49 | .. _cheat-sheet: ../tutorial/cheat-sheet.rst 50 | .. _trouble-shoot: ../tutorial/trouble-shoot.rst 51 | 52 | 53 | Thanks, 54 | Tobin. 55 | 56 | .. _setup: ./setup.rst 57 | .. _checkpatch: ./checkpatch.rst 58 | .. _probe-and-release: ./probe-and-release.rst 59 | .. _further-tools: ./further-tools.rst 60 | -------------------------------------------------------------------------------- /workshop/checkpatch.rst: -------------------------------------------------------------------------------- 1 | ============================ 2 | Checkpatch your way to glory 3 | ============================ 4 | 5 | This project will use one of the kernel's intree tools to find a few things to 6 | work on. ``scripts/checkpatch.pl`` is a static analysis tool useful for finding 7 | code that may need patching. It is not the only intree tool, it is not even the 8 | only intree static analysis tool. It is however very useful and if you plan on 9 | sending any patches to LKML you should be very familiar with it. By *very* I 10 | mean you should be running it on every patch you send to LKML. Trust me on this 11 | one, it will save you a lot of embarrassment. 12 | 13 | The aim of this project is, like all the others, to get a three patch series 14 | together so we can submit it to LKML. Here we will be focusing on the 15 | development process required to patch the kernel more than the exact changes. 16 | By design, we are not trying to do complex changes, just some small simple 17 | patches to get your feet wet. 18 | 19 | First off, you may like to define a shell alias. Then run checkpatch against 20 | various directories in ``drivers/staging`` until you find one that looks 21 | interesting i.e., achievable. 22 | 23 | .. code:: bash 24 | 25 | export KTREE=/path/to/staging 26 | alias checkpatch="$KTREE/scripts/checkpatch.pl" 27 | cd $KTREE/drivers/staging 28 | checkpatch --terse --strict --show-types --file foo/*.[ch] 29 | 30 | 31 | What are we fixing 32 | ================== 33 | 34 | The aim is to put together three patches i.e., do three commits that can then be 35 | tied together as a series. The kernel mantra is 'fix one thing per patch' so we 36 | can fix one type of checkpatch warning/error/check per patch. Typically you 37 | will do *all* of the errors of a single type in the same patch. If this seems 38 | like too much work you *could* just do one of them or you could find a driver 39 | with a manageable number of errors. 40 | 41 | So, for example 42 | 43 | .. code:: bash 44 | 45 | checkpatch --terse --strict --show-types --file most/*.[ch] 46 | most/core.c:55: CHECK:UNCOMMENTED_DEFINITION: struct mutex definition without comment 47 | most/core.c:63: CHECK:UNCOMMENTED_DEFINITION: spinlock_t definition without comment 48 | most/core.c:306: WARNING:LONG_LINE: line over 80 characters 49 | most/core.c:345: CHECK:UNNECESSARY_PARENTHESES: Unnecessary parentheses around 'c->iface->interface != ITYPE_MEDIALB_DIM2' 50 | ... 51 | 52 | We could look at all the lines indicated by CHECK:UNNECESSARY_PARENTHESES and 53 | check if the parentheses are really unnecessary. By the way, this check 54 | requires some knowledge of kernel coding style, in this case the typical rule is 55 | to **not** make the code harder to understand. As Dan Carpenter explains in 56 | email-from-dan_ doing code changes just to quieten a tool is not what you 57 | want to do, we want to make sure we are improving the code as well as clearing 58 | the warning. 59 | 60 | The kernel coding style is documented in ``$KTREE/Documentation/process/coding-style.rst``. 61 | 62 | Go ahead, find some code with bad smells and see if you can clean it up. Make 63 | sure you run checkpatch again after you make a change to see if the warning is cleared. 64 | 65 | You probably want to create a new branch to work on. 66 | 67 | When committing each change please follow the guidelines in Section 2 'Describe 68 | your changes' of ``$KTREE/Documentation/process/submitting-patches.rst``. 69 | 70 | Once you have three commits on your branch you are ready to create and submit 71 | the series. Please see patch-series_. 72 | 73 | .. _patch-series: ./patch-series.rst 74 | .. _email-from-dan: ./email-from-dan -------------------------------------------------------------------------------- /workshop/email-from-dan: -------------------------------------------------------------------------------- 1 | Date: Fri, 19 Jul 2019 12:36:58 +0300 2 | From: Dan Carpenter 3 | To: "Tobin C. Harding" 4 | Cc: Kernelnewbies , 5 | Greg Kroah-Hartman , 6 | driverdev-devel@linuxdriverproject.org 7 | Subject: Re: [OSSNA] Intro to kernel hacking tutorial 8 | 9 | On Fri, Jul 05, 2019 at 12:50:55PM +1000, Tobin C. Harding wrote: 10 | > Outcome will (hopefully) be a small patch set into drivers/staging/. 11 | > (Don't worry Greg only one group got to this stage last time, you 12 | > won't get flooded with patches :) 13 | 14 | We're good at reviewing floods of patches. Send away. 15 | 16 | In the end what we want is people who will take over a driver and 17 | understand it completely and become the maintainer. We've had a few 18 | people that did appointed themselves to become the maintainer of a 19 | random driver and move it out of staging. But even if people don't make 20 | it all the way to become a maintainer, it's nice when they start down 21 | that path by focusing on one driver and trying to understand it as much 22 | as possible. 23 | 24 | Most of the time when you look at a new staging driver, then you do want 25 | to clean up the white space just because it's hard to look at 26 | non-standard code. So that's the first step. But then maybe start at 27 | the probe and release functions and clean it up. Keep your eyes open 28 | to any other mistakes or bugs you see. Write them down. Then the 29 | ioctls. Etc. Look at the TODO too. 30 | 31 | The other thing I wish people knew was about the relationship with 32 | maintainers. When you start out, you're virtually anonymous for the 33 | first couple patchsets. We get so many and they blend together so we 34 | don't remember your name. So don't think that we mean anything 35 | personally if we don't apply your patch. We have forgotten about the 36 | patch as soon as we reply to it. Don't panic and resend quickly. You 37 | will be too stressed. Wait until the next day. 38 | 39 | In staging we really want to apply patches (unless it's in staging 40 | because we're going to remove the code). I get annoyed with other 41 | staging reviewers who NAK patches because "I don't like churn" or 42 | whatever. 43 | 44 | On the other hand, patches just "silencing checkpatch.pl" is not a valid 45 | justification for sending a patch. Patches should make the code more 46 | readable. 47 | 48 | Anyway, maintainers are not monsters. Very few people have made me 49 | annoyed to the point where I refuse to review their code. And everyone 50 | else is in my good books so that's fine. 51 | 52 | regards, 53 | dan carpenter 54 | 55 | -------------------------------------------------------------------------------- /workshop/further-tools.rst: -------------------------------------------------------------------------------- 1 | ============= 2 | Further Tools 3 | ============= 4 | 5 | The kernel tree contains a number other tools for checking C code. Of interest 6 | when trying to find things to work on are the following 7 | 8 | - Sparse - semantic checker for C programs. 9 | - Coccinelle - a tool for pattern matching and text transformation. 10 | - Spatch - a static analysis tool, now part of the Coccinelle project. 11 | 12 | Documentation can be found in ``Documentation/dev-tools``. 13 | 14 | If checkpatch.pl is way too easy for you you may enjoy playing with these tools 15 | and running them against code in ``drivers/staging`` to see if you can locate code 16 | that could be improved. 17 | 18 | Until you have done a decent number of patches to the kernel please do confine 19 | yourself to ``drivers/staging``. Not all developers appreciate newbies messing 20 | around with code they maintain. ``drivers/staging`` is *the* place to learn the 21 | basics of kernel development, people will be very patient and welcoming of you 22 | there. 23 | 24 | Once you have a few patches queued up see patch-series_ if you need to. 25 | 26 | .. _patch-series: ./patch-series.rst 27 | -------------------------------------------------------------------------------- /workshop/patch-series.rst: -------------------------------------------------------------------------------- 1 | ======================= 2 | Creating a patch series 3 | ======================= 4 | 5 | Once you have three (or more) commits on a branch (that was created off of 6 | Greg's staging-next branch) you are ready to create a patch set. 7 | 8 | When submitting patches to LKML it is expected that each patch in a series is 9 | complete. What this means is that with each patch applied (on top of the 10 | previous one) the kernel builds and any testing you did passes. A maintainer 11 | may decide to take just the first [few] patches of your series. 12 | 13 | Create a patch set with 14 | 15 | .. code:: bash 16 | 17 | mkdir /tmp/patches 18 | git format-patch -o /tmp/patches -X --cover-letter 19 | 20 | where ``X`` is the number of commits you want to include. 21 | 22 | Re-check 23 | ======== 24 | 25 | Re-check that you did not make any mistakes by running checkpatch against your 26 | patches (you won't need the ``--file`` option this time). (Please note; 27 | checkpatch does not like parsing the cover-letter.) Also make sure you build 28 | the kernel for each patch of the series i.e., after each commit make sure the 29 | kernel builds. You may like to save the output from checkpatch without your 30 | commits then diff against the output with the whole series applied, that way you 31 | can verify you are not introducing any new errors. 32 | 33 | 34 | Cover letter 35 | ============ 36 | 37 | Next you need to write a cover letter. You cover letter is, as the name 38 | suggests, an overview of the series. It should briefly say whats in the series 39 | and if there is anything unusual in the series. Also outline any testing you 40 | did, if you did not do any testing (assuming you didn't bring any hardware with 41 | you that runs staging drivers) state this in the cover letter. If this is your 42 | first series to LKML you could explicitly state something like 'no testing done, 43 | all patches build and checkpatch cleanly'. Please make sure any claims you make 44 | are true. 45 | 46 | Optionally, at this stage, you can just set the To header to point to your own 47 | email address then send the series to yourself as a test run using the command 48 | below. If it all looks good you can then continue. 49 | 50 | In the cover letter set the To, and CC headers appropriately. One way I like to 51 | address a patch is to send it to the maintainer[s] and CC everyone else 52 | including mailing lists. Using this method, and since we patched 53 | drivers/staging/, the patches go 'To' Greg (and any other maintainer) and 'Cc' 54 | to the driver development mailing list. To find out who else should be included 55 | run ``scripts/get_maintainer.pl`` on either the file you patched or the patch 56 | itself. You don't need to include everyone returned by that command but you 57 | should at a minimum include the maintainers (sometimes listed as 'supporter') 58 | and one mailing list. It is nice to also CC a developer if they have a high 59 | percentage of commits signed. The kernel policy is to err on the side of CC'ing 60 | too many people. All kernel patches **must** be sent to a mailing list, 61 | typically a subsystem mailing list. CC'ing LKML main mailing list is common 62 | practice but optional. 63 | 64 | Feel free to CC me, Tobin C. Harding if you want. 65 | 66 | Send 67 | ==== 68 | 69 | Ok, so now you have a bunch of patches and a cover letter. Each patch 70 | checkpatches cleanly and the kernel builds with each patch applied in series. 71 | Well done, this is no small feat. Open each patch in your editor and double 72 | check that no mistakes have crept in, remember 'one thing per patch'. The 73 | kernel community is very strict on this and for good reason - reviewing is time 74 | consuming, having random changes in a patch makes it harder to review. Even 75 | random whitespace changes should be put in their own patch not mixed into 76 | another patch. 77 | 78 | You can now send you patch series using ``git send-email --to-cover --cc-cover /tmp/patches/*.patch`` 79 | 80 | If you have not done so already then now is a good time to read the email from 81 | Dan Carpenter email-from-dan_. Along with Greg, Dan is a very active 82 | reviewer of staging patches. Both these reviewers are extremely welcoming to 83 | new comers and particularly patient. They are happy to see you learn. Please 84 | be respectful of their time by being diligent and heeding any advice they 85 | offer. I learned a **lot** from the reviews by these two hackers and you can 86 | too. 87 | 88 | Congratulations, you have succeeded in completing the workshop. Thank you once 89 | again for attending, time is precious and I appreciate you choosing to spend 90 | yours here. 91 | 92 | 93 | Happy hacking! 94 | 95 | .. _email-from-dan: ./email-from-dan 96 | -------------------------------------------------------------------------------- /workshop/probe-and-release.rst: -------------------------------------------------------------------------------- 1 | ================= 2 | Probe and Release 3 | ================= 4 | 5 | This project is based on an email I received from Dan Carpenter on LKML. You 6 | can read the full email in email-from-dan_ and here is the paragraph that 7 | inspired this project: 8 | 9 | Most of the time when you look at a new staging driver, then you do want 10 | to clean up the white space just because it's hard to look at 11 | non-standard code. So that's the first step. But then maybe start at 12 | the probe and release functions and clean it up. Keep your eyes open 13 | to any other mistakes or bugs you see. Write them down. Then the 14 | ioctls. Etc. Look at the TODO too. 15 | 16 | 17 | The output of this project is the same as the others, 3 or so patches that 18 | we can submit to LKML as a patch series. Since we are going to be messing with 19 | more than just superficial changes in this project typically you would have 20 | access to the hardware running the driver. Clearly this is not feasible at the 21 | conference but it is something to keep in mind. 22 | 23 | The steps involved, as suggested above are 24 | 25 | - Pick a driver in ``drivers/staging`` that you like the look of. 26 | - Give it a quick look over for glaring style issues. Like Dan says, this is 27 | mainly because reading code that has crazy style issues can be cumbersome. 28 | Fix stlye/whitespace issues first. 29 | - Have a look at the probe/release functions in more detail. 30 | 31 | - You could checkpatch these functions fully. 32 | - Refactor these functions. 33 | - Ensure they do everything that is expected of a probe/release function for this type of driver. 34 | 35 | 36 | That's it. Pretty simple to describe, harder to do. See if you can put 37 | together a few patches that clearly improve the driver. This is a good first 38 | step in understanding the driver and going on to working on it more extensively. 39 | 40 | Once you have a few patches queued up see patch-series_ if you need to. 41 | 42 | .. _patch-series: ./patch-series.rst 43 | .. _email-from-dan: ./email-from-dan 44 | -------------------------------------------------------------------------------- /workshop/setup.rst: -------------------------------------------------------------------------------- 1 | =============== 2 | Workshop set up 3 | =============== 4 | 5 | Getting started 6 | =============== 7 | 8 | We will be working off of Greg Kroah-Hartman's staging tree, specifically the 9 | ``staging-next`` branch. 10 | 11 | If you already know how to checkout the ``staging-next`` branch of Greg's staging 12 | tree feel free to skip ahead. 13 | 14 | You will need a local copy of the Linux kernel tree. If you have one already 15 | you can jump down to 'Using a remote' below. 16 | 17 | 18 | Cloning the tree 19 | ---------------- 20 | 21 | There is a git server running locally so we do not overload the conference Wi-Fi. 22 | 23 | If you have not got a copy of the Linux kernel tree on your local machine then 24 | you may clone it from the NUC attached to hotspot ``oss-kdev``. If the whole room 25 | does this then the NUC is going to choke so please consider just cloning with 26 | ``--depth=1``. Also when testing I was only getting 4.7 MiB/s during clone (and 27 | the whole tree is over 2 Gigabytes so please be patient. 28 | 29 | - SSID: oss-kdev 30 | - passphrase: oss-kdev-pass 31 | 32 | .. code:: bash 33 | 34 | git clone --depth=1 git://192.168.8.6/staging 35 | 36 | This will clone Greg's tree with ``staging-next`` branch already checked out. If 37 | you cloned the tree some other way you can check out the branch with 38 | 39 | .. code:: bash 40 | 41 | git checkout -b staging-next --track origin/staging-next 42 | 43 | Using a remote 44 | -------------- 45 | 46 | If you have already have a local copy of the kernel tree on you can add the 47 | following to your git config file 48 | 49 | .. code:: bash 50 | 51 | # Greg's staging tree 52 | [remote "staging"] 53 | url = git://git.kernel.org/pub/scm/linux/kernel/git/gregkh/staging.git 54 | fetch = +refs/heads/*:refs/remotes/staging/* 55 | pushurl = no_push 56 | 57 | Fetch and then checkout the ``staging-next`` branch 58 | 59 | .. code:: bash 60 | 61 | git fetch staging 62 | git checkout -b staging-next --track staging/staging-next 63 | 64 | 65 | Building the staging drivers 66 | ============================ 67 | 68 | We will be working on staging drivers so you can go ahead and set the kernel 69 | building now so as to save time. Create a config file by doing the following 70 | 71 | .. code:: bash 72 | 73 | make defconfig 74 | make localmodconfig 75 | make menuconfig 76 | 77 | Then select *all* staging drivers under 78 | 79 | Device Drivecs --> Staging 80 | 81 | (If you already know which driver you want to hack on just select it.) 82 | 83 | Set the kernel building now to save time later ``make -j9``. Once the build 84 | completes you can verify that staging drivers were built by ``cd``ing into 85 | ``drivers/staging`` and running 86 | 87 | .. code:: bash 88 | 89 | find . -name *.o | wc -l 90 | 318 91 | 92 | 93 | You have now completed the setup, well done - let's have some fun. Head back 94 | over to the readme_ to continue. 95 | 96 | .. _readme: ./README.rst 97 | 98 | --------------------------------------------------------------------------------