X-Git-Url: https://sigrok.org/gitweb/?p=libsigrok.git;a=blobdiff_plain;f=HACKING;h=aa408ffb6cad15c90ca5ecc0250475886b94a9e4;hp=9c422a328bce348a1832b9223ea838a85d94cb4d;hb=2d31e8bcbd98f0dee9047749324baedfcdd2be62;hpb=2bba3dd3a836f4a6d497709d321557a48e6425a3 diff --git a/HACKING b/HACKING index 9c422a32..aa408ffb 100644 --- a/HACKING +++ b/HACKING @@ -45,7 +45,11 @@ 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. +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: @@ -55,15 +59,10 @@ 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 + - 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. @@ -71,18 +70,27 @@ 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. @@ -95,7 +103,7 @@ Random notes - Consistently use the same naming convention for #include guards in headers: __ 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: __(). @@ -115,6 +123,18 @@ 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 ------- @@ -131,6 +151,29 @@ Doxygen /** @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 +--------- + +You can run the libsigrok testsuite using: + + $ make check + Release engineering -------------------