root/lm-sensors/trunk/doc/developers/new_drivers

These are the steps you should follow to write a new driver and
submit it to us so that it will be applied cleanly to our package.
See at the bottom for adding new chip support to an existing driver.

Don't be intimidated by the list, it's just here so we don't
forget anything.
We are more than happy to help you with any part of the process.

There are two types of drivers, chip and bus.
Steps which apply to only one type of driver are noted.

These instructions are for 2.4-kernel-compatible drivers.
If you wish to write a driver for 2.6 only, not all of the following
steps apply.

---------------------------------------------------------------------

* Check our "New Drivers" page for status!!

* Contact us.
  You are of course free to write your own drivers, but it is smart to
  check first nobody else is already working on it, in case the
  New Drivers page is out of date.
  Tell us it's OK to put your name on the "New Drivers" page.

* Consider subscribing to the mailing list.

* Check out our latest code from SVN.
  You should use this as a base for your development.
  See instructions on our download page.

* Write the new driver.
  If you write a driver for a device that is similar to one we already
  support, use the other device driver as a template. If you don't know
  which one to use, either ask us or use the following defaults.
  For a chip driver, use lm78.c as template. For an SMBus-only adapter, 
  use i2c-piix4.c. Use i2c-via.c for an I2C-level adapter ('bit banger').
  Usually, we make all prefixes start with the driver name. This is not
  really necessary, as these symbols will not be exported anyway. But by
  doing this, you are sure you do not shadow any global kernel names.

* A quick note about conversions. The conversions which are specified
  in the sensor chip datasheet and which *cannot* vary from one board to
  the next are performed by the driver. If other conversions are
  necessary, they are performed in user-space.

* Meet Kernel coding standards.
  See Documentation/CodingStyle in the kernel source.
  Be sure and use 8 column tabs.
  Also, please do not use // comments.
  Also, please do not go past column 80.
  Also, please use C99 struct initializers {.foo = blat}
  Please do this _before_ you check in your driver.

* Meet /proc naming standards in the ctl_table (for chip drivers only).
  See doc/developers/proc for information. Please do not deviate from
  this without discussion.

* Add the driver to the Module.mk (the makefile).
  Usually, you can just add it to KERNEL{CHIPS,DRIVERS}TARGETS in the
  Module.mk file in the directory itself. Put it at the beginning,
  where the comment says to put drivers NOT included in mkpatch.

* Make sure it compiles cleanly.
  Check compilation with 'make DEBUG=1' if you use debugging
  information. Remember, things put between #ifdef DEBUG #endif may never
  stop the driver from functioning; they should just output additional
  information.

* Check for external symbols.
  'nm --extern --defined' should only output symbols starting with __module,
  cleanup_module, init_module and some kernel versioning symbols. Mark all
  other symbols as static in your source file.

* Test the module.
  Test with a recent 2.4 kernel.
  For bus drivers, use i2cdetect and i2cdump. For i2cdump, test all supported
  bus access modes (see i2cdump man page).
  For chip drivers, cat all files in applicable /proc or /sys directory
  and check for problems. Write all supported settings.
  Check ALARM indications.

* Add detection information to prog/detect/sensors-detect.
  This is a perl script that automatically detects what chips and adapters
  are present. Contact us if you need help.

* Add chip information to lib/chips.{c,h} (for chip drivers only).
  Until you have done this, the chip will be invisible for user-level
  programs which use libsensors. Use standard names in lib/chips.c;
  see also the comments in etc/sensors.conf.eg for help.
  Contact us if you need more assistance.

* Be sure that SYSCTL and ALARM definitions in the driver are bracketed
  by the special comments so that the kernel/include/sensors.h
  file, which is generated automatically, contains your definitions.
  (for chip drivers only)

* Add a procedure to prog/sensors/chips.[ch] (for chip drivers only).
  This is a function specific for your driver that
  makes the included 'sensors' program pretty-print your chip information.

* Add an line for the procedure in the matches[] table in
  prog/sensors/main.c (for chip drivers only).
  This tells sensors to call your new procedure when the chip name matches.

* Add entries to etc/sensors.conf.eg (for chip drivers only).
  If needed, you can set defaults here.

* Test the userspace apps (sensors-detect and sensors).
  Test setting limits with sensors -s.

* Add the name of the device to the README file.

* Add your name to the CONTRIBUTORS file.

* Add entries to the CHANGES file. Please keep in alphabetical order.

* Write a doc/chips/xxx or doc/busses/xxx file.

* Add entry to doc/chips/SUMMARY (for chip drivers only).

* Clearly specify licensing and copyright.
  Make sure the GPL boilerplate and your name
  (or if applicable your company's name) is at the top of the
  new driver so we know you are giving it to us under the GPL.

* Submit the changes to us.
  Do a 'svn update' to get in sync (things will have changed since
  you started), then submit the changes to us as a patch against SVN.

* If you want to have your driver integrated to Linux 2.6, you have to
  port your driver to the new sysfs interface. Once done and preferably
  after testing, submit a patch to our mailing list: see
  http://www.lm-sensors.org/wiki/AuthorsAndContributors
  Make sure to check the current status for your driver first:
  http://www.lm-sensors.org/wiki/Kernel2.6
  http://www.lm-sensors.org/wiki/Devices

---------------------------------------------------------------------
Checklist for us to do on the webpage:

* Add entry to 'supported drivers' page

* Update entry on 'new drivers' page

---------------------------------------------------------------------
Checklist for mkpatch support, after the driver is tested and stable:

* Add .c file to mkpatch/FILES.

* Add makefile entry in mkpatch/mkpatch.pl (2 places - old and new formats).
  (don't bother with old format, obsolete)

* Add config help to mkpatch/mkpatch.pl.

* Add config entry to mkpatch/Config.in (chip drivers only)

* Add config entry in mkpatch/mkpatch.pl (bus drivers only)

* Move .o reference in kernel/[chips,busses]/Module.mk
  from first to second section.


---------------------------------------------------------------------
Checklist for _adding_ support for a chip to an _existing_ driver:

* Make the changes to the driver itself.

* Add detection information to prog/detect/sensors-detect.

* Add a strncmp() call for the new prefix in prog/sensors/main.c
  (chip drivers only).

* Add entries for the new prefix to etc/sensors.conf.eg (chip drivers only).

* Update config help in mkpatch/mkpatch.pl.

* Update config entry in mkpatch/Config.in (chip drivers only)

* Update config entry in mkpatch/mkpatch.pl (bus drivers only)

* Update doc/[chips,busses]/xxx file

* Update doc/chips/SUMMARY file (chip drivers only)

* Update list in README

* Submit the changes as a patch or check them in

* Update entry on 'new drivers' page