├── files ├── files-to-fix.txt ├── files_to_fix.odt ├── images ├── Kr_c_prog_lang.jpg ├── git_header.gif └── linux_kernel_in_a_nutshell_small.jpg ├── kernel_patch_tutorial.odp ├── kernel_patch_tutorial.pdf ├── lxf_article └── write_kernel_patch.txt └── walkthrough /files: -------------------------------------------------------------------------------- 1 | drivers/staging/csr/bh.c 2 | 3 | drivers/staging/csr/csr_framework_ext.c 4 | 5 | drivers/staging/csr/csr_framework_ext.h 6 | 7 | drivers/staging/csr/csr_framework_ext_types.h 8 | 9 | drivers/staging/csr/csr_lib.h 10 | 11 | drivers/staging/csr/csr_log_configure.h 12 | 13 | drivers/staging/csr/csr_log.h 14 | 15 | drivers/staging/csr/csr_log_text.h 16 | 17 | drivers/staging/csr/csr_macro.h 18 | 19 | drivers/staging/csr/csr_msgconv.c 20 | 21 | drivers/staging/csr/csr_msgconv.h 22 | 23 | drivers/staging/csr/csr_msg_transport.h 24 | 25 | drivers/staging/csr/csr_panic.c 26 | 27 | drivers/staging/csr/csr_panic.h 28 | 29 | drivers/staging/csr/csr_prim_defs.h 30 | 31 | drivers/staging/csr/csr_result.h 32 | 33 | drivers/staging/csr/csr_sched.h 34 | 35 | drivers/staging/csr/csr_sdio.h 36 | 37 | drivers/staging/csr/csr_serialize_primitive_types.c 38 | 39 | drivers/staging/csr/csr_time.c 40 | 41 | drivers/staging/csr/csr_time.h 42 | 43 | drivers/staging/csr/csr_util.c 44 | 45 | drivers/staging/csr/csr_wifi_common.h 46 | 47 | drivers/staging/csr/csr_wifi_fsm_event.h 48 | 49 | drivers/staging/csr/csr_wifi_fsm.h 50 | 51 | drivers/staging/csr/csr_wifi_fsm_types.h 52 | 53 | drivers/staging/csr/csr_wifi_hip_card.h 54 | 55 | drivers/staging/csr/csr_wifi_hip_card_sdio.c 56 | 57 | drivers/staging/csr/csr_wifi_hip_card_sdio.h 58 | 59 | drivers/staging/csr/csr_wifi_hip_card_sdio_intr.c 60 | 61 | drivers/staging/csr/csr_wifi_hip_card_sdio_mem.c 62 | 63 | drivers/staging/csr/csr_wifi_hip_chiphelper.c 64 | 65 | drivers/staging/csr/csr_wifi_hip_chiphelper.h 66 | 67 | drivers/staging/csr/csr_wifi_hip_chiphelper_private.h 68 | 69 | drivers/staging/csr/csr_wifi_hip_conversions.h 70 | 71 | drivers/staging/csr/csr_wifi_hip_download.c 72 | 73 | XXXX drivers/staging/csr/csr_wifi_hip_dump.c 74 | 75 | drivers/staging/csr/csr_wifi_hip_packing.c 76 | 77 | drivers/staging/csr/csr_wifi_hip_send.c 78 | 79 | drivers/staging/csr/csr_wifi_hip_signals.c 80 | 81 | drivers/staging/csr/csr_wifi_hip_signals.h 82 | 83 | drivers/staging/csr/csr_wifi_hip_sigs.h 84 | 85 | drivers/staging/csr/csr_wifi_hip_ta_sampling.c 86 | 87 | drivers/staging/csr/csr_wifi_hip_ta_sampling.h 88 | 89 | drivers/staging/csr/csr_wifi_hip_udi.c 90 | 91 | drivers/staging/csr/csr_wifi_hip_unifi.h 92 | 93 | drivers/staging/csr/csr_wifi_hip_unifihw.h 94 | 95 | drivers/staging/csr/csr_wifi_hip_unifi_signal_names.c 96 | 97 | drivers/staging/csr/csr_wifi_hip_unifi_udi.h 98 | 99 | drivers/staging/csr/csr_wifi_hip_unifiversion.h 100 | 101 | drivers/staging/csr/csr_wifi_hip_xbv.c 102 | 103 | drivers/staging/csr/csr_wifi_hip_xbv.h 104 | 105 | drivers/staging/csr/csr_wifi_hostio_prim.h 106 | 107 | drivers/staging/csr/csr_wifi_lib.h 108 | 109 | drivers/staging/csr/csr_wifi_msgconv.h 110 | 111 | drivers/staging/csr/csr_wifi_nme_ap_converter_init.c 112 | 113 | drivers/staging/csr/csr_wifi_nme_ap_converter_init.h 114 | 115 | drivers/staging/csr/csr_wifi_nme_ap_free_downstream_contents.c 116 | 117 | drivers/staging/csr/csr_wifi_nme_ap_free_upstream_contents.c 118 | 119 | drivers/staging/csr/csr_wifi_nme_ap_lib.h 120 | 121 | drivers/staging/csr/csr_wifi_nme_ap_prim.h 122 | 123 | drivers/staging/csr/csr_wifi_nme_ap_sef.c 124 | 125 | drivers/staging/csr/csr_wifi_nme_ap_sef.h 126 | 127 | drivers/staging/csr/csr_wifi_nme_ap_serialize.c 128 | 129 | drivers/staging/csr/csr_wifi_nme_ap_serialize.h 130 | 131 | drivers/staging/csr/csr_wifi_nme_converter_init.h 132 | 133 | drivers/staging/csr/csr_wifi_nme_lib.h 134 | 135 | drivers/staging/csr/csr_wifi_nme_prim.h 136 | 137 | drivers/staging/csr/csr_wifi_nme_serialize.h 138 | 139 | drivers/staging/csr/csr_wifi_nme_task.h 140 | 141 | drivers/staging/csr/csr_wifi_private_common.h 142 | 143 | drivers/staging/csr/csr_wifi_result.h 144 | 145 | drivers/staging/csr/csr_wifi_router_converter_init.c 146 | 147 | drivers/staging/csr/csr_wifi_router_converter_init.h 148 | 149 | drivers/staging/csr/csr_wifi_router_ctrl_converter_init.c 150 | 151 | drivers/staging/csr/csr_wifi_router_ctrl_converter_init.h 152 | 153 | drivers/staging/csr/csr_wifi_router_ctrl_free_downstream_contents.c 154 | 155 | drivers/staging/csr/csr_wifi_router_ctrl_free_upstream_contents.c 156 | 157 | drivers/staging/csr/csr_wifi_router_ctrl_lib.h 158 | 159 | drivers/staging/csr/csr_wifi_router_ctrl_prim.h 160 | 161 | drivers/staging/csr/csr_wifi_router_ctrl_sef.c 162 | 163 | drivers/staging/csr/csr_wifi_router_ctrl_sef.h 164 | 165 | drivers/staging/csr/csr_wifi_router_ctrl_serialize.c 166 | 167 | drivers/staging/csr/csr_wifi_router_ctrl_serialize.h 168 | 169 | drivers/staging/csr/csr_wifi_router_free_downstream_contents.c 170 | 171 | drivers/staging/csr/csr_wifi_router_free_upstream_contents.c 172 | 173 | drivers/staging/csr/csr_wifi_router_lib.h 174 | 175 | drivers/staging/csr/csr_wifi_router_prim.h 176 | 177 | drivers/staging/csr/csr_wifi_router_sef.c 178 | 179 | drivers/staging/csr/csr_wifi_router_sef.h 180 | 181 | drivers/staging/csr/csr_wifi_router_serialize.c 182 | 183 | drivers/staging/csr/csr_wifi_router_serialize.h 184 | 185 | drivers/staging/csr/csr_wifi_router_task.h 186 | 187 | drivers/staging/csr/csr_wifi_router_transport.c 188 | 189 | drivers/staging/csr/csr_wifi_serialize_primitive_types.c 190 | 191 | drivers/staging/csr/csr_wifi_sme_ap_lib.h 192 | 193 | drivers/staging/csr/csr_wifi_sme_ap_prim.h 194 | 195 | drivers/staging/csr/csr_wifi_sme_converter_init.c 196 | 197 | drivers/staging/csr/csr_wifi_sme_converter_init.h 198 | 199 | drivers/staging/csr/csr_wifi_sme_free_downstream_contents.c 200 | 201 | drivers/staging/csr/csr_wifi_sme_free_upstream_contents.c 202 | 203 | drivers/staging/csr/csr_wifi_sme_lib.h 204 | 205 | drivers/staging/csr/csr_wifi_sme_prim.h 206 | 207 | drivers/staging/csr/csr_wifi_sme_sef.c 208 | 209 | drivers/staging/csr/csr_wifi_sme_sef.h 210 | 211 | drivers/staging/csr/csr_wifi_sme_serialize.c 212 | 213 | drivers/staging/csr/csr_wifi_sme_serialize.h 214 | 215 | drivers/staging/csr/csr_wifi_sme_task.h 216 | 217 | drivers/staging/csr/csr_wifi_vif_utils.h 218 | 219 | XXXX drivers/staging/csr/data_tx.c 220 | 221 | drivers/staging/csr/drv.c 222 | 223 | drivers/staging/csr/firmware.c 224 | 225 | drivers/staging/csr/inet.c 226 | 227 | drivers/staging/csr/init_hw.c 228 | 229 | drivers/staging/csr/io.c 230 | 231 | drivers/staging/csr/Kconfig 232 | 233 | drivers/staging/csr/LICENSE.txt 234 | 235 | drivers/staging/csr/Makefile 236 | 237 | drivers/staging/csr/mlme.c 238 | 239 | drivers/staging/csr/monitor.c 240 | 241 | drivers/staging/csr/netdev.c 242 | 243 | drivers/staging/csr/os.c 244 | 245 | drivers/staging/csr/putest.c 246 | 247 | drivers/staging/csr/sdio_events.c 248 | 249 | drivers/staging/csr/sdio_mmc.c 250 | 251 | drivers/staging/csr/sdio_stubs.c 252 | 253 | drivers/staging/csr/sme_blocking.c 254 | 255 | drivers/staging/csr/sme_mgt.c 256 | 257 | drivers/staging/csr/sme_native.c 258 | 259 | drivers/staging/csr/sme_sys.c 260 | 261 | drivers/staging/csr/sme_userspace.c 262 | 263 | drivers/staging/csr/sme_userspace.h 264 | 265 | drivers/staging/csr/sme_wext.c 266 | 267 | drivers/staging/csr/ul_int.c 268 | 269 | drivers/staging/csr/unifi_clients.h 270 | 271 | drivers/staging/csr/unifi_config.h 272 | 273 | drivers/staging/csr/unifi_dbg.c 274 | 275 | drivers/staging/csr/unifi_event.c 276 | 277 | drivers/staging/csr/unifiio.h 278 | 279 | drivers/staging/csr/unifi_native.h 280 | 281 | drivers/staging/csr/unifi_os.h 282 | 283 | drivers/staging/csr/unifi_pdu_processing.c 284 | 285 | drivers/staging/csr/unifi_priv.h 286 | 287 | drivers/staging/csr/unifi_sme.c 288 | 289 | drivers/staging/csr/unifi_sme.h 290 | 291 | drivers/staging/csr/unifi_wext.h 292 | 293 | drivers/staging/csr/wext_events.c 294 | -------------------------------------------------------------------------------- /files-to-fix.txt: -------------------------------------------------------------------------------- 1 | drivers/staging/comedi/drivers/8253.h 2 | drivers/staging/comedi/drivers/8255.c 3 | drivers/staging/comedi/drivers/8255.h 4 | drivers/staging/comedi/drivers/acl7225b.c 5 | drivers/staging/comedi/drivers/adl_pci6208.c 6 | drivers/staging/comedi/drivers/adl_pci7296.c 7 | drivers/staging/comedi/drivers/adl_pci7432.c 8 | drivers/staging/comedi/drivers/adl_pci8164.c 9 | drivers/staging/comedi/drivers/adl_pci9111.c 10 | drivers/staging/comedi/drivers/adl_pci9118.c 11 | drivers/staging/comedi/drivers/adq12b.c 12 | drivers/staging/comedi/drivers/adv_pci1710.c 13 | drivers/staging/comedi/drivers/adv_pci1723.c 14 | drivers/staging/comedi/drivers/adv_pci_dio.c 15 | drivers/staging/comedi/drivers/aio_aio12_8.c 16 | drivers/staging/comedi/drivers/aio_iiro_16.c 17 | drivers/staging/comedi/drivers/am9513.h 18 | drivers/staging/comedi/drivers/amcc_s5933.h 19 | drivers/staging/comedi/drivers/amplc_dio200.c 20 | drivers/staging/comedi/drivers/amplc_pc236.c 21 | drivers/staging/comedi/drivers/amplc_pc263.c 22 | drivers/staging/comedi/drivers/amplc_pci224.c 23 | drivers/staging/comedi/drivers/amplc_pci230.c 24 | drivers/staging/comedi/drivers/c6xdigio.c 25 | drivers/staging/comedi/drivers/cb_das16_cs.c 26 | drivers/staging/comedi/drivers/cb_pcidas64.c 27 | drivers/staging/comedi/drivers/cb_pcidas.c 28 | drivers/staging/comedi/drivers/cb_pcidda.c 29 | drivers/staging/comedi/drivers/cb_pcidio.c 30 | drivers/staging/comedi/drivers/cb_pcimdas.c 31 | drivers/staging/comedi/drivers/cb_pcimdda.c 32 | drivers/staging/comedi/drivers/comedi_bond.c 33 | drivers/staging/comedi/drivers/comedi_fc.c 34 | drivers/staging/comedi/drivers/comedi_fc.h 35 | drivers/staging/comedi/drivers/comedi_parport.c 36 | drivers/staging/comedi/drivers/comedi_test.c 37 | drivers/staging/comedi/drivers/contec_pci_dio.c 38 | drivers/staging/comedi/drivers/daqboard2000.c 39 | drivers/staging/comedi/drivers/das08.c 40 | drivers/staging/comedi/drivers/das08_cs.c 41 | drivers/staging/comedi/drivers/das08.h 42 | drivers/staging/comedi/drivers/das16.c 43 | drivers/staging/comedi/drivers/das16m1.c 44 | drivers/staging/comedi/drivers/das1800.c 45 | drivers/staging/comedi/drivers/das6402.c 46 | drivers/staging/comedi/drivers/das800.c 47 | drivers/staging/comedi/drivers/dmm32at.c 48 | drivers/staging/comedi/drivers/dt2801.c 49 | drivers/staging/comedi/drivers/dt2811.c 50 | drivers/staging/comedi/drivers/dt2814.c 51 | drivers/staging/comedi/drivers/dt2815.c 52 | drivers/staging/comedi/drivers/dt2817.c 53 | drivers/staging/comedi/drivers/dt282x.c 54 | drivers/staging/comedi/drivers/dt3000.c 55 | drivers/staging/comedi/drivers/dt9812.c 56 | drivers/staging/comedi/drivers/fl512.c 57 | drivers/staging/comedi/drivers/gsc_hpdi.c 58 | drivers/staging/comedi/drivers/icp_multi.c 59 | drivers/staging/comedi/drivers/icp_multi.h 60 | drivers/staging/comedi/drivers/ii_pci20kc.c 61 | drivers/staging/comedi/drivers/jr3_pci.c 62 | drivers/staging/comedi/drivers/jr3_pci.h 63 | drivers/staging/comedi/drivers/ke_counter.c 64 | drivers/staging/comedi/drivers/me4000.c 65 | drivers/staging/comedi/drivers/me4000.h 66 | drivers/staging/comedi/drivers/mite.c 67 | drivers/staging/comedi/drivers/mpc624.c 68 | drivers/staging/comedi/drivers/mpc8260cpm.c 69 | drivers/staging/comedi/drivers/multiq3.c 70 | drivers/staging/comedi/drivers/ni_6527.c 71 | drivers/staging/comedi/drivers/ni_65xx.c 72 | drivers/staging/comedi/drivers/ni_660x.c 73 | drivers/staging/comedi/drivers/ni_670x.c 74 | drivers/staging/comedi/drivers/ni_at_a2150.c 75 | drivers/staging/comedi/drivers/ni_at_ao.c 76 | drivers/staging/comedi/drivers/ni_atmio16d.c 77 | drivers/staging/comedi/drivers/ni_atmio.c 78 | drivers/staging/comedi/drivers/ni_daq_700.c 79 | drivers/staging/comedi/drivers/ni_daq_dio24.c 80 | drivers/staging/comedi/drivers/ni_labpc.c 81 | drivers/staging/comedi/drivers/ni_labpc_cs.c 82 | drivers/staging/comedi/drivers/ni_labpc.h 83 | drivers/staging/comedi/drivers/ni_mio_common.c 84 | drivers/staging/comedi/drivers/ni_mio_cs.c 85 | drivers/staging/comedi/drivers/ni_pcidio.c 86 | drivers/staging/comedi/drivers/ni_pcimio.c 87 | drivers/staging/comedi/drivers/ni_stc.h 88 | drivers/staging/comedi/drivers/ni_tio.c 89 | drivers/staging/comedi/drivers/ni_tiocmd.c 90 | drivers/staging/comedi/drivers/ni_tio.h 91 | drivers/staging/comedi/drivers/ni_tio_internal.h 92 | drivers/staging/comedi/drivers/pcl711.c 93 | drivers/staging/comedi/drivers/pcl724.c 94 | drivers/staging/comedi/drivers/pcl725.c 95 | drivers/staging/comedi/drivers/pcl726.c 96 | drivers/staging/comedi/drivers/pcl730.c 97 | drivers/staging/comedi/drivers/pcl812.c 98 | drivers/staging/comedi/drivers/pcl816.c 99 | drivers/staging/comedi/drivers/pcl818.c 100 | drivers/staging/comedi/drivers/pcm3724.c 101 | drivers/staging/comedi/drivers/pcm3730.c 102 | drivers/staging/comedi/drivers/pcmad.c 103 | drivers/staging/comedi/drivers/pcm_common.c 104 | drivers/staging/comedi/drivers/pcmda12.c 105 | drivers/staging/comedi/drivers/pcmmio.c 106 | drivers/staging/comedi/drivers/pcmuio.c 107 | drivers/staging/comedi/drivers/plx9080.h 108 | drivers/staging/comedi/drivers/poc.c 109 | drivers/staging/comedi/drivers/quatech_daqp_cs.c 110 | drivers/staging/comedi/drivers/rtd520.c 111 | drivers/staging/comedi/drivers/rtd520.h 112 | drivers/staging/comedi/drivers/rti800.c 113 | drivers/staging/comedi/drivers/rti802.c 114 | drivers/staging/comedi/drivers/s526.c 115 | drivers/staging/comedi/drivers/s626.c 116 | drivers/staging/comedi/drivers/s626.h 117 | drivers/staging/comedi/drivers/serial2002.c 118 | drivers/staging/comedi/drivers/skel.c 119 | drivers/staging/comedi/drivers/ssv_dnp.c 120 | drivers/staging/comedi/drivers/unioxx5.c 121 | drivers/staging/comedi/drivers/usbdux.c 122 | drivers/staging/comedi/drivers/usbduxfast.c 123 | drivers/staging/comedi/drivers/vmk80xx.c 124 | -------------------------------------------------------------------------------- /files_to_fix.odt: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/gregkh/kernel-tutorial/cafb965f10a0b6fa48541788030e99781dce7c96/files_to_fix.odt -------------------------------------------------------------------------------- /images/Kr_c_prog_lang.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/gregkh/kernel-tutorial/cafb965f10a0b6fa48541788030e99781dce7c96/images/Kr_c_prog_lang.jpg -------------------------------------------------------------------------------- /images/git_header.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/gregkh/kernel-tutorial/cafb965f10a0b6fa48541788030e99781dce7c96/images/git_header.gif -------------------------------------------------------------------------------- /images/linux_kernel_in_a_nutshell_small.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/gregkh/kernel-tutorial/cafb965f10a0b6fa48541788030e99781dce7c96/images/linux_kernel_in_a_nutshell_small.jpg -------------------------------------------------------------------------------- /kernel_patch_tutorial.odp: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/gregkh/kernel-tutorial/cafb965f10a0b6fa48541788030e99781dce7c96/kernel_patch_tutorial.odp -------------------------------------------------------------------------------- /kernel_patch_tutorial.pdf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/gregkh/kernel-tutorial/cafb965f10a0b6fa48541788030e99781dce7c96/kernel_patch_tutorial.pdf -------------------------------------------------------------------------------- /lxf_article/write_kernel_patch.txt: -------------------------------------------------------------------------------- 1 | First up, some basics about the source code control tool that the Linux 2 | kernel uses, git. Git can be found in any Linux distro these days, and 3 | there are numerous good tutorials on how to use it and set it up 4 | available on the web. One good one comes within git itself, and can 5 | be read by running: 6 | $ man gittutorial 7 | after you have installed git on your machine. 8 | 9 | So run off and install git on your Linux system using the package 10 | manager you are comfortable with (personally, I use openSUSE, and a 11 | simple 'zypper install git' does everything that is needed.) 12 | 13 | Then start by cloning the main Linux kernel repository: 14 | 15 | $ mkdir ~/linux 16 | $ cd ~/linux 17 | $ git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux-2.6.git 18 | 19 | This will create the directory 'linux-2.6' within the linux/ directory. 20 | Everything we do from here out will be within that directory, so go into 21 | it to start with: 22 | $ cd ~/linux/linux-2.6 23 | 24 | Now that you have the raw source code, how do you build it and install 25 | it on your system? That is a much larger task, one that is beyond this 26 | article. Luckily a whole book has been written on this topic, "Linux 27 | Kernel in a Nutshell", and can be found free online at: 28 | http://www.kroah.com/lkn/ 29 | if you don't want to purchase it. 30 | 31 | So go and get your kernel configured and building, and then come back 32 | here to figure out what to do next. 33 | 34 | 35 | -- Git tips 36 | 37 | Here are a few tips to use with git when working with the kernel source 38 | tree. First off, never do your work on the same branch that Linus 39 | pushes to, called "master". Create your own branch, and use that 40 | instead. This ensures that any changes that are committed to Linus's 41 | branch upstream, will be able to be updated by you without any problems. 42 | 43 | To create a new branch called 'tutorial' and check it out, do the 44 | following: 45 | $ git branch tutorial 46 | $ git checkout tutorial 47 | That's it. You are now in the 'tutorial' branch of your kernel 48 | repository, as can be seen by the following command: 49 | $ git branch 50 | master 51 | * tutorial 52 | The '*' in front of the 'tutorial' name shows that you are on the 53 | correct branch. 54 | 55 | Now, let's go and make some changes to the kernel code. 56 | 57 | -- What to change 58 | 59 | Wait, you don't know what change you want to make to the Linux kernel 60 | source tree? Everything is working just fine for you? Well, don't 61 | despair, the Linux kernel developers need all the help they can get, and 62 | have plenty of code in the tree that is just waiting to get cleaned up. 63 | 64 | The code in the drivers/staging/ tree consists of a lot of drivers that 65 | do not meet the normal Linux kernel coding guidelines. The code is in 66 | that location so that other developers can help on cleaning it up, and 67 | getting it merged into the main portion of the Linux kernel tree. 68 | 69 | Every driver in the drivers/staging directory contains a TODO file that 70 | lists the things that need to be done on it in order for the code to be 71 | moved to the proper location in the kernel tree. The majority of the 72 | drivers all contain the following line in their TODO file: 73 | - fix checkpatch.pl issues 74 | 75 | Let's look into what this means and how you can help out with this task. 76 | 77 | -- Coding Style 78 | 79 | Every large body of code needs to have a set of coding style rules in 80 | order for it to be a viable project that a large number of developers 81 | can work on. Numerous research studies have been made on this topic, 82 | and they all conclude that having a common guideline makes a very large 83 | difference. 84 | 85 | It is not merely a matter of aesthetics that programs 86 | should be written in a particular style. Rather there 87 | is a psychological basis for writing programs in a 88 | conventional manner: programmers have strong expectations 89 | that other programmers will follow these discourse rules. 90 | If the rules are violated, then the utility afforded by 91 | the expectations that programmers have built up over time 92 | is effectively nullified.” 93 | – Soloway & Ehrlich 94 | 95 | What this means is that once programmers get used to a common style, the 96 | patterns of the code go away when it is looked at, and the meaning shows 97 | through very easily. 98 | 99 | The goal of any Linux kernel developer is to have other developers help 100 | find problems in their code, and by keeping all of the code in the same 101 | format, it makes it much easier for anyone else to pick it up, modify 102 | it, or notice bugs in it. As every line of kernel code is reviewed by 103 | at least 2 developers before it is accepted, having a common style 104 | guideline is a very important thing. 105 | 106 | The Linux kernel coding style can be found in the file 107 | Documentation/CodingStyle in the kernel source tree. The important 108 | thing to remember when reading it, is not that this style is somehow 109 | better than any other style, just that it is consistent. 110 | 111 | In order to help developers easily find coding style issues, the script 112 | scripts/checkpatch.pl in the kernel source tree has been developed. 113 | This script can point out problems very easily, and should always be run 114 | by a developer on their changes, instead of having a reviewer waste 115 | their time by pointing out problems later on. 116 | 117 | The drivers in the drivers/staging/ directory all usually have coding 118 | style issues as they were developed by people not familiar with the 119 | Linux kernel guidelines. One of the first things that needs to be done 120 | to the code, is to fix it up to follow the correct rules. 121 | 122 | And this is where you come in, by running the checkpatch.pl tool, you 123 | can find a large number of problems that need to be fixed. 124 | 125 | -- Specific rules 126 | 127 | Let us look at some of the common rules that are part of the kernel 128 | guidelines. 129 | 130 | --- Whitespace 131 | 132 | The first rule that everyone needs to follow is to use the 'tab' 133 | character, and not use spaces, to indent code. Also, the 'tab' 134 | character should represent 8 spaces. Following along with the 8 135 | character tab indentation, the code should not flow past the 80 136 | character line limit on the right side of the screen. 137 | 138 | Note, numerous developers have complained about the 80 character limit 139 | recently, and there are some places where it is acceptable to go beyond 140 | that limit. If you find that you are being forced to do strange 141 | line-wrapping formatting just to fit into the 80 character limit, with 142 | all of your code on the right hand side of the screen, it is better to 143 | refactor the logic to prevent this from happening in the first place. 144 | Forcing an 80 character limit, also forces developers to break their 145 | logic up into smaller, easier to understand chunks, which makes it 146 | easier to review and follow as well. 147 | 148 | So yes, there is a method to the madness of the 80 character limit. 149 | 150 | --- Braces 151 | 152 | Opening braces should be placed on the same line of the statement they 153 | are being used for, with one exception as show below. Closing braces 154 | should be placed back at the original indentation. This can be shown 155 | with the following example: 156 | 157 | if (error != -ENODEV) { 158 | foo(); 159 | bar(); 160 | } 161 | 162 | If you need to add an else statement to an if statement, put it on the 163 | same line as the closing brace, as shown here: 164 | 165 | if (error != -ENODEV) { 166 | foo(); 167 | bar(); 168 | } else { 169 | report_error(); 170 | goto exit; 171 | } 172 | 173 | If braces are not needed for a statement, do not put them in, as they 174 | are unnecessary: 175 | 176 | if (error != -ENODEV) 177 | foo(); 178 | else 179 | goto exit; 180 | 181 | The one exception for opening braces is for function declarations, 182 | those go on a new line as shown here: 183 | 184 | int function(int *baz) 185 | { 186 | do_something(baz); 187 | return 0; 188 | } 189 | 190 | -- checkpatch.pl 191 | 192 | With these simple whitespace and brace rules now understood, let us run 193 | the checkpatch.pl script on some code and see what it tells us: 194 | 195 | $ ./scripts/checkpatch.pl --help 196 | Usage: checkpatch.pl [OPTION]... [FILE]... 197 | Version: 0.30 198 | 199 | Options: 200 | -q, --quiet quiet 201 | --no-tree run without a kernel tree 202 | --no-signoff do not check for 'Signed-off-by' line 203 | --patch treat FILE as patchfile (default) 204 | --emacs emacs compile window format 205 | --terse one line per report 206 | -f, --file treat FILE as regular source file 207 | --subjective, --strict enable more subjective tests 208 | --root=PATH PATH to the kernel tree root 209 | --no-summary suppress the per-file summary 210 | --mailback only produce a report in case of warnings/errors 211 | --summary-file include the filename in summary 212 | --debug KEY=[0|1] turn on/off debugging of KEY, where KEY is one of 213 | 'values', 'possible', 'type', and 'attr' (default 214 | is all off) 215 | --test-only=WORD report only warnings/errors containing WORD 216 | literally 217 | -h, --help, --version display this help and exit 218 | 219 | When FILE is - read standard input. 220 | 221 | Some common options that we will be using is the --terse and --file 222 | options, as those allow us to see the problems in a much simpler report, 223 | and they work on an entire file, not just a single patch. 224 | 225 | So, let's pick a file in the kernel and see what checkpatch.pl tells us 226 | about it: 227 | 228 | $ ./scripts/checkpatch.pl --file --terse drivers/staging/comedi/drivers/ni_labpc.c 229 | drivers/staging/comedi/drivers/ni_labpc.c:4: WARNING: line over 80 characters 230 | ... 231 | drivers/staging/comedi/drivers/ni_labpc.c:486: WARNING: braces {} are not necessary for single statement blocks 232 | drivers/staging/comedi/drivers/ni_labpc.c:489: WARNING: braces {} are not necessary for single statement blocks 233 | ... 234 | drivers/staging/comedi/drivers/ni_labpc.c:587: WARNING: suspect code indent for conditional statements (8, 0) 235 | ... 236 | drivers/staging/comedi/drivers/ni_labpc.c:743: WARNING: printk() should include KERN_ facility level 237 | drivers/staging/comedi/drivers/ni_labpc.c:750: WARNING: kfree(NULL) is safe this check is probably not required 238 | ... 239 | drivers/staging/comedi/drivers/ni_labpc.c:2028: WARNING: EXPORT_SYMBOL(foo); should immediately follow its function/variable 240 | total: 0 errors, 76 warnings, 2028 lines checked 241 | 242 | 243 | I've removed a lot of the warnings from the above output, as there was a 244 | total of 76 of them, and they are all variants of the above ones. 245 | 246 | As can be seen, the checkpatch.pl tool points out where the code has 247 | gone beyond the 80 character limit, and where braces were used that they 248 | were not needed, as well as a few other things that should be cleaned up 249 | in the file. 250 | 251 | Now that we know what needs to be done, fire up your favorite editor, 252 | and let us fix something. How about the brace warning, that should be 253 | simple to resolve. 254 | 255 | Looking at the original code, lines 486-490 look like the following: 256 | 257 | if (irq) { 258 | printk(", irq %u", irq); 259 | } 260 | if (dma_chan) { 261 | printk(", dma %u", dma_chan); 262 | } 263 | 264 | A simple removal of those extra braces results in: 265 | if (irq) 266 | printk(", irq %u", irq); 267 | if (dma_chan) 268 | printk(", dma %u", dma_chan); 269 | 270 | Save the file, and run the checkpatch tool again to verify that the 271 | warning is gone: 272 | $ ./scripts/checkpatch.pl --file --terse drivers/staging/comedi/drivers/ni_labpc.c | grep 486 273 | $ 274 | 275 | And of course build the file to verify that you did not break anything: 276 | $ make drivers/staging/comedi/drivers/ni_labpc.o 277 | CHK include/linux/version.h 278 | CHK include/generated/utsrelease.h 279 | CALL scripts/checksyscalls.sh 280 | CC [M] drivers/staging/comedi/drivers/ni_labpc.o 281 | 282 | Yes, it still builds, so all is good. 283 | 284 | Great, you have now made your first kernel code fix! 285 | 286 | But, how do you take this change, and get it to the kernel developers in 287 | the format that they can apply it? 288 | 289 | -- More git fun 290 | 291 | As you edited this file within a git repository, your change to it is 292 | caught by git. This can be seen by running the 'git status' command: 293 | $ git status 294 | # On branch tutorial 295 | # Changed but not updated: 296 | # (use "git add ..." to update what will be committed) 297 | # (use "git checkout -- ..." to discard changes in working directory) 298 | # 299 | # modified: drivers/staging/comedi/drivers/ni_labpc.c 300 | # 301 | no changes added to commit (use "git add" and/or "git commit -a") 302 | 303 | This output shows that we are on the branch called 'tutorial', and that 304 | we have one file modified at the moment, the ni_labpc.c file. 305 | 306 | If we ask for git to show what we changed, we will see the actual lines: 307 | 308 | $ git diff 309 | diff --git a/drivers/staging/comedi/drivers/ni_labpc.c b/drivers/staging/comedi/drivers/ni_labpc.c 310 | index dc3f398..a01e35d 100644 311 | --- a/drivers/staging/comedi/drivers/ni_labpc.c 312 | +++ b/drivers/staging/comedi/drivers/ni_labpc.c 313 | @@ -483,12 +483,10 @@ int labpc_common_attach(struct comedi_device *dev, unsigned long iobase, 314 | 315 | printk("comedi%d: ni_labpc: %s, io 0x%lx", dev->minor, thisboard->name, 316 | iobase); 317 | - if (irq) { 318 | + if (irq) 319 | printk(", irq %u", irq); 320 | - } 321 | - if (dma_chan) { 322 | + if (dma_chan) 323 | printk(", dma %u", dma_chan); 324 | - } 325 | printk("\n"); 326 | 327 | if (iobase == 0) { 328 | 329 | This output is in the format that the tool 'patch' can use to apply a 330 | change to a body of code. The leading '-' and '+' on some lines show 331 | what lines are removed, and what lines are added. Reading these diff 332 | outputs soon becomes natural, and is the format in which you need to 333 | send to the kernel maintainer to get the change accepted. 334 | 335 | --- Description, description, description 336 | 337 | The raw diff output shows what code is changed, but for every kernel 338 | patch, more information needs to be provided in order for it to be 339 | accepted. This "metadata" is as important as the code changes, as it is 340 | used to show who made the change, why the change was made, and who 341 | reviewed the change. 342 | 343 | Here is a sample change that was accepted into the Linux kernel tree a 344 | while ago: 345 | 346 | USB: otg: Fix bug on remove path without transceiver 347 | 348 | In the case where a gadget driver is removed while no 349 | transceiver was found at probe time, a bug in 350 | otg_put_transceiver() will trigger. 351 | 352 | Signed-off-by: Robert Jarzmik 353 | Acked-by: David Brownell 354 | Signed-off-by: Greg Kroah-Hartman 355 | 356 | --- a/drivers/usb/otg/otg.c 357 | +++ b/drivers/usb/otg/otg.c 358 | @@ -43,7 +43,8 @@ EXPORT_SYMBOL(otg_get_transceiver); 359 | void otg_put_transceiver(struct otg_transceiver *x) 360 | { 361 | - put_device(x->dev); 362 | + if (x) 363 | + put_device(x->dev); 364 | } 365 | 366 | 367 | The first line of the change, is a one line summary of what part of the 368 | kernel the change is for, and very briefly, what it does: 369 | USB: otg: Fix bug on remove path without transceiver 370 | 371 | Then comes a more descriptive paragraph that explains why the change is 372 | needed: 373 | In the case where a gadget driver is removed while no 374 | transceiver was found at probe time, a bug in 375 | otg_put_transceiver() will trigger. 376 | 377 | After that, comes a few lines that show who made and reviewed the patch: 378 | Signed-off-by: Robert Jarzmik 379 | Acked-by: David Brownell 380 | Signed-off-by: Greg Kroah-Hartman 381 | 382 | The term "Signed-off-by:" refers to the ability for the developer to 383 | properly claim that they are allowed to make this change, and offer it 384 | up under the acceptable license to be able for it to be added to the 385 | Linux kernel source tree. This agreement is called the "Developer's 386 | Certificate of Origin" and can be found in full in the file, 387 | Documentation/SubmittingPatches in the Linux kernel source tree. 388 | 389 | A brief summary of what the Developer's Certificate of Origin consists 390 | of, is the following: 391 | 392 | (a) I created this change; or 393 | (b) Based this on a previous work with a 394 | compatible license; or 395 | (c) Provided to me by (a), (b), or (c) and not 396 | modified 397 | (d) This contribution is public. 398 | 399 | It is a very simple to understand agreement, and ensures that everyone 400 | involved knows that the change is legally acceptable. 401 | 402 | Every developer who the patch goes through, adds their "Signed-off-by:" 403 | to it as the patch flows through the developer and maintainer chain 404 | before it is accepted into the Linux kernel source tree. This ensures 405 | that every line of code in the Linux kernel, can be tracked back to the 406 | developer who created it, and the developers who reviewed it. 407 | 408 | 409 | -- Creating our patch 410 | 411 | Now that we know how a patch is structured, we can create ours. 412 | 413 | First, tell git to check in the change that we made: 414 | $ git commit drivers/staging/comedi/drivers/ni_labpc.c 415 | 416 | git will fire up your favorite editor and place you in it, with the 417 | following information already present: 418 | 419 | # Please enter the commit message for your changes. Lines starting 420 | # with '#' will be ignored, and an empty message aborts the commit. 421 | # Explicit paths specified without -i nor -o; assuming --only paths... 422 | # On branch tutorial 423 | # Changes to be committed: 424 | # (use "git reset HEAD ..." to unstage) 425 | # 426 | # modified: drivers/staging/comedi/drivers/ni_labpc.c 427 | 428 | Create a summary line for the patch: 429 | Staging: comedi: fix brace coding style issue in ni_labpc.c 430 | 431 | And then a more descriptive paragraph: 432 | 433 | This is a patch to the ni_labpc.c file that fixes up a brace 434 | warning found by the checkpatch.pl tool 435 | 436 | Then add your Signed-off-by: line: 437 | 438 | Signed-off-by: Greg Kroah-Hartman 439 | 440 | Then save the file and git will make the commit, printing out the 441 | following: 442 | [tutorial 60de825] Staging: comedi: fix brace coding style issue in ni_labpc.c 443 | 1 files changed, 2 insertions(+), 4 deletions(-) 444 | 445 | If you use the command 'git show HEAD' to see the most recent change, it 446 | will show you the full commit you made: 447 | $ git show HEAD 448 | 449 | commit 60de825964d99dee56108ce4c985a7cfc984e402 450 | Author: Greg Kroah-Hartman 451 | Date: Sat Jan 9 12:07:40 2010 -0800 452 | 453 | Staging: comedi: fix brace coding style issue in ni_labpc.c 454 | 455 | This is a patch to the ni_labpc.c file that fixes up a brace 456 | warning found by the checkpatch.pl tool 457 | 458 | Signed-off-by: My Name 459 | 460 | diff --git a/drivers/staging/comedi/drivers/ni_labpc.c b/drivers/staging/comedi/drivers/ni_labpc.c 461 | index dc3f398..a01e35d 100644 462 | --- a/drivers/staging/comedi/drivers/ni_labpc.c 463 | +++ b/drivers/staging/comedi/drivers/ni_labpc.c 464 | @@ -483,12 +483,10 @@ int labpc_common_attach(struct comedi_device *dev, unsigned long iobase, 465 | 466 | printk("comedi%d: ni_labpc: %s, io 0x%lx", dev->minor, thisboard->name, 467 | iobase); 468 | - if (irq) { 469 | + if (irq) 470 | printk(", irq %u", irq); 471 | - } 472 | - if (dma_chan) { 473 | + if (dma_chan) 474 | printk(", dma %u", dma_chan); 475 | - } 476 | printk("\n"); 477 | 478 | if (iobase == 0) { 479 | 480 | 481 | You are now finished creating your first kernel patch! 482 | 483 | -- Getting your change into the kernel tree 484 | 485 | Now that you have created the patch, how do you get it into the kernel 486 | tree? Linux kernel development primarily still happens through email, 487 | with patches being sent through email, and review happening that way. 488 | 489 | First off, let's export our patch in a format that we can use to email 490 | it to the maintainer who will be responsible for accepting our patch. 491 | 492 | To do that, once again, git has a command 'format-patch' that you can 493 | use: 494 | $ git format-patch master..tutorial 495 | 0001-Staging-comedi-fix-brace-coding-style-issue-in-ni_la.patch 496 | 497 | In this command, we are creating all patches that exist in the 498 | difference from the branch 'master' (which is Linus's branch, remember 499 | way back at the beginning?) and our private branch, called 'tutorial'. 500 | This consists of only one change, our patch. It is now in the file 501 | 0001-Staging-comedi-fix-brace-coding-style-issue-in-ni_la.patch in our 502 | directory in a format that we can send off. 503 | 504 | Before we attempt to send the patch off, we should verify that our patch 505 | is in the correct format, and does not add any errors to the kernel tree 506 | as far as coding style issues go. To do that, we use the checkpatch.pl 507 | script again: 508 | $ ./scripts/checkpatch.pl 0001-Staging-comedi-fix-brace-coding-style-issue-in-ni_la.patch 509 | total: 0 errors, 0 warnings, 14 lines checked 510 | 511 | 0001-Staging-comedi-fix-brace-coding-style-issue-in-ni_la.patch has no obvious style problems and is ready for submission. 512 | 513 | All is good, so it is safe to submit this change. 514 | 515 | But, who do we send it to? Once again, the kernel developers have made 516 | this very simple, with a script that will tell you who needs to be 517 | notified. This script is called, 'get_maintainer.pl', and is also in 518 | the scripts/ subdirectory in the kernel source tree. This script looks 519 | at the files you have modified in the patch, and matches it up with the 520 | information in the MAINTAINERS file in the kernel source tree that 521 | describes who is responsible for what portion of the kernel, as well as 522 | looking at the past history of the files being modified, in order to 523 | come up with the names and email addresses of the people, and mailing 524 | lists, that should be notified of this patch. 525 | 526 | Running this script on our patch, results in the following: 527 | $ ./scripts/get_maintainer.pl 0001-Staging-comedi-fix-brace-coding-style-issue-in-ni_la.patch 528 | Greg Kroah-Hartman 529 | Bill Pemberton 530 | devel@driverdev.osuosl.org 531 | linux-kernel@vger.kernel.org 532 | 533 | These are the addresses we need to send the patch to. 534 | 535 | -- Sending an email 536 | 537 | So, we should just bring up our favorite email client and send the patch 538 | off to the list of addresses that get_maintainer.pl told us about, 539 | right? 540 | 541 | Wait, not so fast. Almost all common email clients do nasty things with 542 | patch files, wrapping lines when they should not be wrapped, changing 543 | tabs into spaces, eating spaces when they shouldn't, and all sorts of 544 | other nasty things (can you say base64-encoded attachments?) Also, some 545 | email servers are known for mangling patches even if you happen to send 546 | the patch correctly. Exchange, Groupwise, and Lotus Notes have this 547 | problem, so much so that most Linux kernel development teams at 548 | companies that use these servers have been forced to set up a Linux 549 | email server somewhere just to get patches out to the community in the 550 | proper way. 551 | 552 | For details about all of these common problems, and how to properly 553 | configure a large number of email clients, take a look at the file, 554 | Documentation/email-clients.txt in the kernel source tree. It will help 555 | you out if you want to use your normal email client to send patches. 556 | 557 | If after reading the email-clients.txt file, your email client still 558 | does not work properly, git can again come to your rescue. 559 | 560 | Git has a way to send patches created with 'git format-patch' out 561 | through email to the developers who need it. The 'git send-email 562 | command handles this all for us: 563 | $ git send-email --to gregkh@suse.de --to wfp5p@virginia.edu \ 564 | --cc devel@driverdev.osuosl.org \ 565 | --cc linux-kernel@vger.kernel.org \ 566 | 0001-Staging-comedi-fix-brace-coding-style-issue-in-ni_la.patch 567 | will send the patch we created to the proper developers and CC: the 568 | proper mailing lists. 569 | 570 | For details on how to configure 'git send-email' to work with your SMTP 571 | server, or firewall, or anything else, see the man page: 572 | $ git send-email --help 573 | 574 | -- Now what? 575 | 576 | Now that you have successfully created a patch and sent it off, what 577 | next? The developer who you sent it to should respond by email in a few 578 | days with either a nice, "thanks for the patch, I have applied it." or 579 | possibly some comments for changes that you should make in order to get 580 | it accepted. If you have not heard anything within a week, send it 581 | again, don't be worried about being annoying, persistence is the key to 582 | getting a busy kernel subsystem maintainer's attention. 583 | 584 | So there you have it, the simple steps involved in creating, committing, 585 | and sending off a Linux kernel patch. Hopefully this means that 586 | everyone reading this article will soon send in their own kernel patch, 587 | and after having fun doing that, continuing to contribute to the largest 588 | software project in the history of computing. 589 | -------------------------------------------------------------------------------- /walkthrough: -------------------------------------------------------------------------------- 1 | HOWTO 2 | 3 | git 4 | 5 | clone linux-next 6 | create your own branch off of the HEAD 7 | work on that 8 | 9 | checkpatch 10 | ./scripts/checkpatch.pl (empty for help) 11 | --terse 12 | --file 13 | 14 | pick a file 15 | drivers/staging/ 16 | 17 | checkpatch comedi file 18 | 19 | show errors vs warnings 20 | 21 | coding style 22 | why? 23 | what is it? 24 | 80 columns 25 | tabs 26 | brace placement 27 | * placement 28 | Documentation/CodingStyle 29 | 30 | 31 | edit the file 32 | 33 | change the line, run checkpatch. 34 | 35 | git diff 36 | 37 | git commit 38 | 39 | Good changelog comment 40 | 41 | signed-off-by: 42 | what it is 43 | 44 | git show 45 | --pretty=email 46 | 47 | git format-patch 48 | 49 | git send-email 50 | --smtp-server /usr/bin/msmtp 51 | 52 | git config --global sendemail.smtpserver /usr/bin/msmtp 53 | 54 | --------------------------------------------------------------------------------