[libsigrokdecode.git] / HACKING

-------------------------------------------------------------------------------
HACKING
-------------------------------------------------------------------------------

Coding style
------------

This project is programmed using the Linux kernel coding style:

  https://www.kernel.org/doc/html/latest/process/coding-style.html

Please use the same style for any code contributions, thanks!

The Python decoders should follow the usual Python conventions and use
Python idioms as far as it makes sense. The coding style should mostly follow
the Python PEP-8, which includes the convention of 4 spaces for indentation:

  http://www.python.org/dev/peps/pep-0008/

Exceptions:

 - All strings should use single quotes ('foo' instead of "foo").

 - No double-newlines between methods (or anywhere else).


Contributions
-------------

 - In order to contribute you should ideally clone the git repository and
   let us know (preferably via IRC, or via the mailing list) from where to
   pull/review your changes. You can use github.com, or any other public git
   hosting site.

 - Alternatively, patches can be sent to the development mailinglist at
   sigrok-devel@lists.sourceforge.net (please subscribe to the list first).

   https://lists.sourceforge.net/lists/listinfo/sigrok-devel


Random notes
------------

 - 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_*malloc()/g_*malloc0() was used, use g_free() to free the
   memory. Otherwise use standard free(). Never use the wrong function!

 - 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.
   Only srd_err()/srd_warn()/srd_info()/srd_dbg()/srd_spew() should be used.

 - Use glib's gboolean / TRUE / FALSE for boolean types consistently.
   Do not use <stdbool.h> and its true / false, and do not invent private
   definitions for this either.

 - 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.
   Example: LIBSIGROKDECODE_LIBSIGROKDECODE_INTERNAL_H

 - Consistently use the same naming convention for API functions:
   <libprefix>_<groupname>_<action>().

   Examples:
     srd_log_loglevel_set(), srd_log_loglevel_get(), srd_log_handler_set(),
     srd_log_handler_set_default(), and so on.

   Getter/setter function names should usually end with "_get" or "_set".
   Functions creating new "objects" should end with "_new".
   Functions destroying "objects" should end with "_destroy".
   Functions adding or removing items (e.g. from lists) should end with
   either "_add" or "_remove".
   Functions operating on all items from a list (not on only one of them),
   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 (SRD_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 (SRD_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 srd_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 SRD_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.


Protocol decoder guidelines
---------------------------

 - The 'desc' metadata field for a protocol decoder, which contains a
   short, one-line description of the protocol/bus, should be at most 55
   characters long, and end with a full stop. This short description can be
   displayed on the command-line using "sigrok-cli -V -l 3", or in various
   different places in GUIs.

 - Longer, multi-line descriptions should be placed in the protocol
   decoder's __init__.py file as docstring. It can be viewed (for a specific
   protocol decoder, e.g., UART) via "sigrok-cli -P uart --show", or in various
   other places in GUIs.

 - Generally use strings for states (of the PD state machine), not integers.
   This avoids having to keep a list of state definitions at the top of file.
   The performance overhead for this is negligible in practice.

   Recommended:
     self.state = 'IDLE'
     self.state = 'GET STOP BIT'
   Not recommended:
     self.state = IDLE
     self.state = GET_STOP_BIT
     (where IDLE = 0 and GET_STOP_BIT = 1, for example)

 - Generally use strings for commands/IDs in generated protocol packets.
   This avoids having to know magic numbers of the PD in higher-level PDs.
   The performance overhead for this is negligible in practice.

   Recommended:
     self.put(x, y, p, ['STOPBIT', 0, 0])
     self.put(x, y, p, ['ADDRESS READ', 0x51])
   Not recommended:
     self.put(x, y, p, [STOPBIT, 0, 0])
     self.put(x, y, p, [ADDRESS_READ, 0x51])
     (with STOPBIT = 3 and ADDRESS_READ = 7, for example)

 - Use ALL-CAPS names for PD states and protocol packet commands/ID.
   Words should be separated by spaces (not underscores or the like).

   Recommended:
     'FIND ADDRESS', 'GET TEMPERATURE', 'START'
   Not recommended:
     'FIND_ADDRESS', 'Get Temperature', 'start'

 - Protocol decoder tags:

   - Every decoder must have a "tags" list (>= 1 items, alphabetically sorted).

   - All tag names start with a capital letter. Subsequent words of the name
     are not capitalized, e.g. "Retro computing", "Debug/trace".

   - All tag names should use singular form ("Sensor", not "Sensors").

   Common tags:

   - Analog/digital: Decoders related A/D conversion, e.g. ADCs and DACs.
   - Audio: Decoders related to audio protocols, e.g. I²S, S/PDIF.
   - Automotive: Decoders related to automotive protocols, e.g. CAN, FlexRay.
   - Clock/timing: Decoders related to time keeping, timing, and clocks/RTCs.
   - Debug/trace: Decoders related to microcontroller/CPU debugging, tracing,
     programming/flashing protocols, e.g. SWD, JTAG, AVR ISP, ARM ETMv3.
   - Display: Decoders related to display technologies, e.g. DVI, HDMI,
     TFT, OLED, LCD, HD44780, EDID, and various LED protocols.
   - Embedded/industrial: Decoders related to protocols used in embedded
     systems, industrial systems, or automation (e.g. SPI, Modbus, Profibus).
   - Encoding: Decoders related to generic encoding / line coding systems,
     e.g. Manchester, Miller, Gray code, OOK, and similar.
   - IC: Decoders for specific (families of) ICs (i.e. not IC-independent,
     generic protocols like UART, SPI, CAN, or USB).
   - IR: Decoders related to infrared (e.g. remote control) protocols.
   - Lighting: Decoders related to lighting technologies, e.g. DALI, DMX512.
   - Memory: Decoders related to memories (e.g. NOR/NAND flash, EEPROM,
     SDRAM, SRAM, various other volatile or non-volatile memories).
   - Networking: Decoders related to (wired) networking technologies.
   - PC: Decoders related to protocols used in personal computers (desktop,
     workstation, laptop, server). This is not meant to be restricted to
     "IBM PC" or "x86/Intel", Apple/Commodore/Atari/SPARC etc. are fine too.
   - RFID: Decoders related to RFID protocols, e.g. EM4100, T55xx.
   - Retro computing: Decoders related to retro computing, e.g. MCS-48, Z80.
   - Security/crypto: Decoders related to security or cryptography.
   - Sensor: Decoders for sensors or all kinds, e.g. temperature or humidity.
   - Util: Random utility/helper decoders.
   - Wireless/RF: Decoders related to various wireless/RF technologies, e.g.
     Bluetooth, BLE, Wifi, or 2.4GHz/433MHz custom protocols.


Testsuite
---------

You can run the libsigrokdecode testsuite using:

 $ make check


Protocol decoder test framework
-------------------------------

Please see the sigrok-test repository for a protocol decoder test suite that
checks the decoded data of various PDs against known-good reference data.


Release engineering
-------------------

See

 http://sigrok.org/wiki/Developers/Release_process

for a list of items that need to be done when releasing a new tarball.
Commit	Line	Data
1859c480 UH	1	-------------------------------------------------------------------------------
	2	HACKING
	3	-------------------------------------------------------------------------------
	4
	5	Coding style
	6	------------
	7
fb83ab34 UH	8	This project is programmed using the Linux kernel coding style:
	9
	10	https://www.kernel.org/doc/html/latest/process/coding-style.html
1859c480 UH	11
	12	Please use the same style for any code contributions, thanks!
	13
	14	The Python decoders should follow the usual Python conventions and use
	15	Python idioms as far as it makes sense. The coding style should mostly follow
fb83ab34 UH	16	the Python PEP-8, which includes the convention of 4 spaces for indentation:
	17
	18	http://www.python.org/dev/peps/pep-0008/
1859c480	19
b7d7e990 UH	20	Exceptions:
	21
	22	- All strings should use single quotes ('foo' instead of "foo").
	23
	24	- No double-newlines between methods (or anywhere else).
	25
1859c480 UH	26
	27	Contributions
	28	-------------
	29
c1495906 UH	30	- In order to contribute you should ideally clone the git repository and
	31	let us know (preferably via IRC, or via the mailing list) from where to
	32	pull/review your changes. You can use github.com, or any other public git
	33	hosting site.
	34
	35	- Alternatively, patches can be sent to the development mailinglist at
1859c480 UH	36	sigrok-devel@lists.sourceforge.net (please subscribe to the list first).
	37
	38	https://lists.sourceforge.net/lists/listinfo/sigrok-devel
	39
1859c480 UH	40
	41	Random notes
	42	------------
	43
0672779d UH	44	- Don't do variable declarations in compound statements, only at the
	45	beginning of a function.
	46
	47	- Generally avoid assigning values to variables at declaration time,
	48	especially so for complex and/or run-time dependent values.
	49
077fa8ac	50	- Consistently use g_malloc() / g_malloc0(). Do not use standard
1859c480 UH	51	malloc()/calloc() if it can be avoided (sometimes other libs such
	52	as libftdi can return malloc()'d memory, for example).
	53
	54	- Always properly match allocations with the proper *free() functions. If
077fa8ac	55	glib's g_malloc()/g_malloc0() was used, use g_free() to free the
1859c480 UH	56	memory. Otherwise use standard free(). Never use the wrong function!
1859c480 UH	57
077fa8ac UH	58	- We assume that "small" memory allocations (< 1MB) will always succeed.
	59	Thus, it's fine to use g_malloc() or g_malloc0() for allocations of
	60	simple/small structs and such (instead of using g_try_malloc()), and
	61	there's no need to check the return value.
	62
	63	Do use g_try_malloc() or g_try_malloc0() for large (>= 1MB) allocations
	64	and check the return value.
1859c480 UH	65
	66	- You should never print any messages (neither to stdout nor stderr nor
	67	elsewhere) "manually" via e.g. printf() or g_log() or similar functions.
	68	Only srd_err()/srd_warn()/srd_info()/srd_dbg()/srd_spew() should be used.
	69
	70	- Use glib's gboolean / TRUE / FALSE for boolean types consistently.
	71	Do not use <stdbool.h> and its true / false, and do not invent private
	72	definitions for this either.
	73
	74	- Consistently use the same naming convention for #include guards in headers:
	75	<PROJECTNAME>_<PATH_TO_FILE>_<FILE>
	76	This ensures that all #include guards are always unique and consistent.
0672779d	77	Example: LIBSIGROKDECODE_LIBSIGROKDECODE_INTERNAL_H
1859c480 UH	78
	79	- Consistently use the same naming convention for API functions:
	80	<libprefix>_<groupname>_<action>().
	81
	82	Examples:
	83	srd_log_loglevel_set(), srd_log_loglevel_get(), srd_log_handler_set(),
	84	srd_log_handler_set_default(), and so on.
	85
	86	Getter/setter function names should usually end with "_get" or "_set".
	87	Functions creating new "objects" should end with "_new".
	88	Functions destroying "objects" should end with "_destroy".
	89	Functions adding or removing items (e.g. from lists) should end with
	90	either "_add" or "_remove".
	91	Functions operating on all items from a list (not on only one of them),
	92	should end with "_all", e.g. "_remove_all", "_get_all", and so on.
	93	Use "_remove_all" in favor of "_clear" for consistency.
	94
0672779d UH	95	- All enums should generally use an explicit start number of 10000.
	96	If there are multiple "categories" in the enum entries, each category
	97	should be 10000 entries apart from the next one. The start of categories
	98	are thus 10000, 20000, 30000, and so on.
	99
	100	Adding items to an enum MUST always append to a "category", never add
	101	items in the middle of a category. The order of items MUST NOT be changed.
	102	Any of the above would break the ABI.
	103
	104	The enum item 0 is special and is used as terminator in some lists, thus
	105	enums should not use this for "valid" entries (and start at 10000 instead).
	106
31e615a5 UH	107
	108	Doxygen
	109	-------
	110
1859c480 UH	111	- In Doxygen comments, put an empty line between the block of @param lines
	112	and the final @return line. The @param lines themselves (if there is more
	113	than one) are not separated by empty lines.
	114
31e615a5 UH	115	- Mark private functions (SRD_PRIV) with /** @private */, so that Doxygen
	116	doesn't include them in the output. Functions that are "static" anyway
	117	don't need to be marked like this.
	118
	119	- Mark private variables/#defines with /** @cond PRIVATE */ and
	120	/** @endcond */, so that Doxygen doesn't include them in the output.
	121	Variables that are "static" don't need to be marked like this.
	122
f11e9498	123	- Mark all public API functions (SRD_API) with a @since tag which indicates
0672779d UH	124	in which release the respective function was added (e.g. "@since 0.1.0").
	125
	126	If the function has existed before, but its API changed later, the @since
	127	tag should mention only the release when the API last changed.
	128
	129	Example: The srd_foo() call was added in 0.1.0, but the API changed in
	130	the later 0.2.0 release. The docs should read "@since 0.2.0" in that case.
f11e9498 UH	131
	132	Non-public functions (static ones, and those marked SRD_PRIV) don't need
	133	to have @since markers.
	134
	135	The @since tag should be the last one, i.e. it should come after @param,
	136	@return, @see, and so on.
	137
1859c480 UH	138
	139	Protocol decoder guidelines
	140	---------------------------
	141
	142	- The 'desc' metadata field for a protocol decoder, which contains a
	143	short, one-line description of the protocol/bus, should be at most 55
	144	characters long, and end with a full stop. This short description can be
	145	displayed on the command-line using "sigrok-cli -V -l 3", or in various
	146	different places in GUIs.
	147
	148	- Longer, multi-line descriptions should be placed in the protocol
	149	decoder's __init__.py file as docstring. It can be viewed (for a specific
b7d7e990	150	protocol decoder, e.g., UART) via "sigrok-cli -P uart --show", or in various
1859c480 UH	151	other places in GUIs.
	152
	153	- Generally use strings for states (of the PD state machine), not integers.
	154	This avoids having to keep a list of state definitions at the top of file.
	155	The performance overhead for this is negligible in practice.
	156
	157	Recommended:
	158	self.state = 'IDLE'
	159	self.state = 'GET STOP BIT'
	160	Not recommended:
	161	self.state = IDLE
	162	self.state = GET_STOP_BIT
	163	(where IDLE = 0 and GET_STOP_BIT = 1, for example)
	164
	165	- Generally use strings for commands/IDs in generated protocol packets.
	166	This avoids having to know magic numbers of the PD in higher-level PDs.
	167	The performance overhead for this is negligible in practice.
	168
	169	Recommended:
	170	self.put(x, y, p, ['STOPBIT', 0, 0])
	171	self.put(x, y, p, ['ADDRESS READ', 0x51])
	172	Not recommended:
	173	self.put(x, y, p, [STOPBIT, 0, 0])
	174	self.put(x, y, p, [ADDRESS_READ, 0x51])
	175	(with STOPBIT = 3 and ADDRESS_READ = 7, for example)
	176
	177	- Use ALL-CAPS names for PD states and protocol packet commands/ID.
	178	Words should be separated by spaces (not underscores or the like).
	179
	180	Recommended:
	181	'FIND ADDRESS', 'GET TEMPERATURE', 'START'
	182	Not recommended:
	183	'FIND_ADDRESS', 'Get Temperature', 'start'
	184
2b46b01c UH	185	- Protocol decoder tags:
	186
	187	- Every decoder must have a "tags" list (>= 1 items, alphabetically sorted).
	188
	189	- All tag names start with a capital letter. Subsequent words of the name
	190	are not capitalized, e.g. "Retro computing", "Debug/trace".
	191
	192	- All tag names should use singular form ("Sensor", not "Sensors").
	193
	194	Common tags:
	195
	196	- Analog/digital: Decoders related A/D conversion, e.g. ADCs and DACs.
	197	- Audio: Decoders related to audio protocols, e.g. I²S, S/PDIF.
	198	- Automotive: Decoders related to automotive protocols, e.g. CAN, FlexRay.
	199	- Clock/timing: Decoders related to time keeping, timing, and clocks/RTCs.
	200	- Debug/trace: Decoders related to microcontroller/CPU debugging, tracing,
	201	programming/flashing protocols, e.g. SWD, JTAG, AVR ISP, ARM ETMv3.
	202	- Display: Decoders related to display technologies, e.g. DVI, HDMI,
	203	TFT, OLED, LCD, HD44780, EDID, and various LED protocols.
	204	- Embedded/industrial: Decoders related to protocols used in embedded
	205	systems, industrial systems, or automation (e.g. SPI, Modbus, Profibus).
	206	- Encoding: Decoders related to generic encoding / line coding systems,
	207	e.g. Manchester, Miller, Gray code, OOK, and similar.
	208	- IC: Decoders for specific (families of) ICs (i.e. not IC-independent,
	209	generic protocols like UART, SPI, CAN, or USB).
	210	- IR: Decoders related to infrared (e.g. remote control) protocols.
	211	- Lighting: Decoders related to lighting technologies, e.g. DALI, DMX512.
	212	- Memory: Decoders related to memories (e.g. NOR/NAND flash, EEPROM,
	213	SDRAM, SRAM, various other volatile or non-volatile memories).
	214	- Networking: Decoders related to (wired) networking technologies.
	215	- PC: Decoders related to protocols used in personal computers (desktop,
	216	workstation, laptop, server). This is not meant to be restricted to
	217	"IBM PC" or "x86/Intel", Apple/Commodore/Atari/SPARC etc. are fine too.
	218	- RFID: Decoders related to RFID protocols, e.g. EM4100, T55xx.
	219	- Retro computing: Decoders related to retro computing, e.g. MCS-48, Z80.
	220	- Security/crypto: Decoders related to security or cryptography.
	221	- Sensor: Decoders for sensors or all kinds, e.g. temperature or humidity.
	222	- Util: Random utility/helper decoders.
	223	- Wireless/RF: Decoders related to various wireless/RF technologies, e.g.
	224	Bluetooth, BLE, Wifi, or 2.4GHz/433MHz custom protocols.
	225
1859c480	226
0672779d UH	227	Testsuite
	228	---------
	229
	230	You can run the libsigrokdecode testsuite using:
	231
	232	$ make check
	233
	234
	235	Protocol decoder test framework
	236	-------------------------------
	237
c414f199 UH	238	Please see the sigrok-test repository for a protocol decoder test suite that
c414f199 UH	239	checks the decoded data of various PDs against known-good reference data.
0672779d UH	240
0672779d UH	241
1859c480 UH	242	Release engineering
	243	-------------------
	244
	245	See
	246
	247	http://sigrok.org/wiki/Developers/Release_process
	248
	249	for a list of items that need to be done when releasing a new tarball.
	250