X-Git-Url: https://sigrok.org/gitweb/?a=blobdiff_plain;f=HACKING;h=cf407c985d95fa3c4b8ef0992a8da1a7af99d39a;hb=d1056603a00b92d12170e6e7d3da33473147c5f5;hp=092be40e601fe2fd29f138e9d650e01fb78e363f;hpb=a2353f6051004634f67505987749d56edbfdfb41;p=libsigrok.git

diff --git a/HACKING b/HACKING
index 092be40e..cf407c98 100644
--- a/HACKING
+++ b/HACKING
@@ -24,6 +24,50 @@ Contributions
    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
 ------------
 
@@ -37,10 +81,10 @@ 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.
 
@@ -71,10 +115,58 @@ Random notes
    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
 -------------------