$ 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.
+You can now edit the files in src/hardware/tondaj-sl-814 as needed
+and implement your driver based on the skeleton files there. That means your
+patch submission later will consist of at least two patches: the initial one
+adding the skeleton driver, and one or more additional patches that actually
+implement the respective driver code.
The manual way:
(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
+ - Makefile.am: Add HW_TONDAJ_SL_814 and add to libsigrok_la_SOURCES.
+ - configure.ac: Add a DRIVER() and DRIVER2() call.
+ - src/drivers.c: Add a tondaj_sl_814_driver_info entry in two places.
+ - src/hardware/tondaj-sl-814/ directory: Add api.c, protocol.c, protocol.h.
See existing drivers or the 'new-driver' output for the details.
Random notes
------------
- - Consistently use g_try_malloc() / g_try_malloc0(). Do not use standard
+ - Don't do variable declarations in compound statements, only at the
+ beginning of a function.
+
+ - Generally avoid assigning values to variables at declaration time,
+ especially so for complex and/or run-time dependent values.
+
+ - Consistently use g_*malloc() / g_*malloc0(). Do not use standard
malloc()/calloc() if it can be avoided (sometimes other libs such
as libftdi can return malloc()'d memory, for example).
- Always properly match allocations with the proper *free() functions. If
- glib's g_try_malloc()/g_try_malloc0() was used, use g_free() to free the
+ glib's g_*malloc()/g_*malloc0() was used, use g_free() to free the
memory. Otherwise use standard free(). Never use the wrong function!
- - 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 libraries.
- Use g_try_malloc()/g_try_malloc0() instead and check the return value.
+ - We assume that "small" memory allocations (< 1MB) will always succeed.
+ Thus, it's fine to use g_malloc() or g_malloc0() for allocations of
+ simple/small structs and such (instead of using g_try_malloc()), and
+ there's no need to check the return value.
+
+ Do use g_try_malloc() or g_try_malloc0() for large (>= 1MB) allocations
+ and check the return value.
- You should never print any messages (neither to stdout nor stderr nor
elsewhere) "manually" via e.g. printf() or g_log() or similar functions.
- Consistently use the same naming convention for #include guards in headers:
<PROJECTNAME>_<PATH_TO_FILE>_<FILE>
This ensures that all #include guards are always unique and consistent.
- Examples: LIBSIGROK_LIBSIGROK_H, LIBSIGROK_HARDWARE_ASIX_SIGMA_ASIX_SIGMA_H
+ Example: LIBSIGROK_HARDWARE_MIC_985XX_PROTOCOL_H
- Consistently use the same naming convention for API functions:
<libprefix>_<groupname>_<action>().
/** @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 (e.g. "@since 0.1.0").
+
+ If the function has existed before, but its API changed later, the @since
+ tag should mention only the release when the API last changed.
+
+ Example: The sr_foo() call was added in 0.1.0, but the API changed in
+ the later 0.2.0 release. The docs should read "@since 0.2.0" in that case.
+
+ 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.
+
Testsuite
---------