github.com, or any other public git hosting site.
+Adding a new hardware driver
+----------------------------
+
+The simple, scripted way (recommended):
+---------------------------------------
+
+Use the 'new-driver' script from the sigrok-util repo:
+
+ $ git clone git://sigrok.org/sigrok-util
+ $ cd sigrok-util/source
+ $ ./new-driver "Tondaj SL-814"
+
+The example above generates a patch file against the current libsigrok
+development git tree which adds a simple "stub" driver for your device
+(the Tondaj SL-814 sound level meter in this case).
+
+You can apply it like this:
+
+ $ cd libsigrok
+ $ git am 0001-tondaj-sl-814-Initial-driver-skeleton.patch
+
+You can now edit the files in the hardware/tondaj-sl-814 directory as needed.
+
+
+The manual way:
+---------------
+
+This is a rough overview of what you need to do in order to add a new driver
+(using the Tondaj SL-814 device as example). It's basically what the
+'new-driver' script (see above) does for you:
+
+ - configure.ac:
+ - Add an --enable-tondaj-sl-814 option.
+ - Add "hardware/tondaj-sl-814/Makefile" to the AC_CONFIG_FILES list.
+ - Add and entry for the device in the "Enabled hardware drivers" list
+ at the bottom of the file.
+ - hardware/Makefile.am: Add "tondaj-sl-814" to the SUBDIRS variable.
+ - hwdriver.c: Add a tondaj_sl_814_driver_info entry in two places.
+ - hardware/tondaj-sl-814/ directory: Add the following files:
+ Makefile.am, api.c, protocol.c, protocol.h
+
+See existing drivers or the 'new-driver' output for the details.
+
+
Random notes
------------
- Never use g_malloc() or g_malloc0(). These functions do not return NULL
if not enough memory is available but rather lead to an exit() or segfault
- instead. This behaviour is not acceptable for libsigrok.
+ instead. This behaviour is not acceptable for libraries.
Use g_try_malloc()/g_try_malloc0() instead and check the return value.
- - libsigrok should never print any messages (neither to stdout nor stderr nor
+ - You should never print any messages (neither to stdout nor stderr nor
elsewhere) "manually" via e.g. printf() or g_log() or similar functions.
Only sr_err()/sr_warn()/sr_info()/sr_dbg()/sr_spew() should be used.
should end with "_all", e.g. "_remove_all", "_get_all", and so on.
Use "_remove_all" in favor of "_clear" for consistency.
+ - All enums should generally use an explicit start number of 10000.
+ If there are multiple "categories" in the enum entries, each category
+ should be 10000 entries apart from the next one. The start of categories
+ are thus 10000, 20000, 30000, and so on.
+
+ Adding items to an enum MUST always append to a "category", never add
+ items in the middle of a category. The order of items MUST NOT be changed.
+ Any of the above would break the ABI.
+
+ The enum item 0 is special and is used as terminator in some lists, thus
+ enums should not use this for "valid" entries (and start at 10000 instead).
+
+
+Doxygen
+-------
+
- In Doxygen comments, put an empty line between the block of @param lines
and the final @return line. The @param lines themselves (if there is more
than one) are not separated by empty lines.
+ - Mark private functions (SR_PRIV) with /** @private */, so that Doxygen
+ doesn't include them in the output. Functions that are "static" anyway
+ don't need to be marked like this.
+
+ - Mark private variables/#defines with /** @cond PRIVATE */ and
+ /** @endcond */, so that Doxygen doesn't include them in the output.
+ Variables that are "static" don't need to be marked like this.
+
+ - Mark all public API functions (SR_API) with a @since tag which indicates
+ in which release the respective function was added. If the function has
+ existed before, but its API changed later, document this as well.
+
+ Non-public functions (static ones, and those marked SR_PRIV) don't need
+ to have @since markers.
+
+ The @since tag should be the last one, i.e. it should come after @param,
+ @return, @see, and so on.
+
+ Examples:
+
+ @since 0.1.0
+
+ @since 0.1.1 (but the API changed in 0.2.0)
+
+
+Testsuite
+---------
+
+You can run the libsigrok testsuite using:
+
+ $ make check
+
Release engineering
-------------------