| Guenter Roeck | c3a2f0a | 2011-04-02 08:26:34 -0700 | [diff] [blame] | 1 | How to Get Your Patch Accepted Into the Hwmon Subsystem |
| 2 | ------------------------------------------------------- |
| 3 | |
| 4 | This text is is a collection of suggestions for people writing patches or |
| 5 | drivers for the hwmon subsystem. Following these suggestions will greatly |
| 6 | increase the chances of your change being accepted. |
| 7 | |
| 8 | |
| 9 | 1. General |
| 10 | ---------- |
| 11 | |
| 12 | * It should be unnecessary to mention, but please read and follow |
| 13 | Documentation/SubmitChecklist |
| 14 | Documentation/SubmittingDrivers |
| 15 | Documentation/SubmittingPatches |
| 16 | Documentation/CodingStyle |
| 17 | |
| 18 | * If your patch generates checkpatch warnings, please refrain from explanations |
| 19 | such as "I don't like that coding style". Keep in mind that each unnecessary |
| 20 | warning helps hiding a real problem. If you don't like the kernel coding |
| 21 | style, don't write kernel drivers. |
| 22 | |
| 23 | * Please test your patch thoroughly. We are not your test group. |
| 24 | Sometimes a patch can not or not completely be tested because of missing |
| 25 | hardware. In such cases, you should test-build the code on at least one |
| 26 | architecture. If run-time testing was not achieved, it should be written |
| 27 | explicitly below the patch header. |
| 28 | |
| 29 | * If your patch (or the driver) is affected by configuration options such as |
| 30 | CONFIG_SMP or CONFIG_HOTPLUG, make sure it compiles for all configuration |
| 31 | variants. |
| 32 | |
| 33 | |
| 34 | 2. Adding functionality to existing drivers |
| 35 | ------------------------------------------- |
| 36 | |
| 37 | * Make sure the documentation in Documentation/hwmon/<driver_name> is up to |
| 38 | date. |
| 39 | |
| 40 | * Make sure the information in Kconfig is up to date. |
| 41 | |
| 42 | * If the added functionality requires some cleanup or structural changes, split |
| 43 | your patch into a cleanup part and the actual addition. This makes it easier |
| 44 | to review your changes, and to bisect any resulting problems. |
| 45 | |
| 46 | * Never mix bug fixes, cleanup, and functional enhancements in a single patch. |
| 47 | |
| 48 | |
| 49 | 3. New drivers |
| 50 | -------------- |
| 51 | |
| 52 | * Running your patch or driver file(s) through checkpatch does not mean its |
| 53 | formatting is clean. If unsure about formatting in your new driver, run it |
| 54 | through Lindent. Lindent is not perfect, and you may have to do some minor |
| 55 | cleanup, but it is a good start. |
| 56 | |
| 57 | * Consider adding yourself to MAINTAINERS. |
| 58 | |
| 59 | * Document the driver in Documentation/hwmon/<driver_name>. |
| 60 | |
| 61 | * Add the driver to Kconfig and Makefile in alphabetical order. |
| 62 | |
| 63 | * Make sure that all dependencies are listed in Kconfig. For new drivers, it |
| 64 | is most likely prudent to add a dependency on EXPERIMENTAL. |
| 65 | |
| 66 | * Avoid forward declarations if you can. Rearrange the code if necessary. |
| 67 | |
| 68 | * Avoid calculations in macros and macro-generated functions. While such macros |
| 69 | may save a line or so in the source, it obfuscates the code and makes code |
| 70 | review more difficult. It may also result in code which is more complicated |
| 71 | than necessary. Use inline functions or just regular functions instead. |
| 72 | |
| 73 | * If the driver has a detect function, make sure it is silent. Debug messages |
| 74 | and messages printed after a successful detection are acceptable, but it |
| 75 | must not print messages such as "Chip XXX not found/supported". |
| 76 | |
| 77 | Keep in mind that the detect function will run for all drivers supporting an |
| 78 | address if a chip is detected on that address. Unnecessary messages will just |
| 79 | pollute the kernel log and not provide any value. |
| 80 | |
| 81 | * Provide a detect function if and only if a chip can be detected reliably. |
| 82 | |
| 83 | * Avoid writing to chip registers in the detect function. If you have to write, |
| 84 | only do it after you have already gathered enough data to be certain that the |
| 85 | detection is going to be successful. |
| 86 | |
| 87 | Keep in mind that the chip might not be what your driver believes it is, and |
| 88 | writing to it might cause a bad misconfiguration. |
| 89 | |
| 90 | * Make sure there are no race conditions in the probe function. Specifically, |
| 91 | completely initialize your chip first, then create sysfs entries and register |
| 92 | with the hwmon subsystem. |
| 93 | |
| 94 | * Do not provide support for deprecated sysfs attributes. |
| 95 | |
| 96 | * Do not create non-standard attributes unless really needed. If you have to use |
| 97 | non-standard attributes, or you believe you do, discuss it on the mailing list |
| 98 | first. Either case, provide a detailed explanation why you need the |
| 99 | non-standard attribute(s). |
| 100 | Standard attributes are specified in Documentation/hwmon/sysfs-interface. |
| 101 | |
| 102 | * When deciding which sysfs attributes to support, look at the chip's |
| 103 | capabilities. While we do not expect your driver to support everything the |
| 104 | chip may offer, it should at least support all limits and alarms. |
| 105 | |
| 106 | * Last but not least, please check if a driver for your chip already exists |
| 107 | before starting to write a new driver. Especially for temperature sensors, |
| 108 | new chips are often variants of previously released chips. In some cases, |
| 109 | a presumably new chip may simply have been relabeled. |