Eric Lee / linux-smarc-t335x-v3.2

Commit c3a2f0ad4917c678fcd828f16102518c33d8393c

Authored by Guenter Roeck 2011-04-02 23:26:34 +0800

Exists in master and in 4 other branches

hwmon: Add submitting-patches checklist to documentation

When writing hardware monitoring drivers, there are some common pitfalls which
keep coming up in code reviews. This patch provides a document describing all
those pitfalls and how to avoid them.

Signed-off-by: Guenter Roeck <guenter.roeck@ericsson.com>
Acked-by: Jean Delvare <khali@linux-fr.org>

Showing 1 changed file with 109 additions and 0 deletions Side-by-side Diff

Documentation/hwmon/submitting-patches

Documentation/hwmon/submitting-patches

Diff comments View file @ c3a2f0a

	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.