libopencm3/HACKING

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

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

The whole library is programmed using the Linux kernel coding style, see
https://www.kernel.org/doc/html/latest/process/coding-style.html for details.

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

Amendments to the Linux kernel coding style
-------------------------------------------

1) We use the stdint types. The linux kernel accepts the abbreviated types (u8,
   s8, u16 and so on) for legacy reasons. We should in general not introduce
   things like types ourselves as long as they are not necessary to make our
   job possible of refining the hardware and make it easier to be used. stdint
   is a standard and it is not in the scope of our project to introduce a new
   type standard.

2) Based on the same logic as in (1) we do not use __packed and __aligned
   definitions, it is not our job to add compiler extensions. If we need to
   deal with compiler incompatibility we will do that the same way we are
   dealing with the deprecated attribute by introducing a normal macro that is
   not in the compiler reserved keyword space.

3) We accept to write an empty body busy waiting while loop like this:
	while (1);
   there is no need to put the colon on the next line as per linux kernel
   style.

4) We always add brackets around bodies of if, while and for statements, even
   if the body contains only one expression. It is dangerous to not have them
   as it easily happens that one adds a second expression and is hunting for
   hours why the code is not working just because of a missing bracket pair.

Development guidelines
----------------------

 - Every new file added must have the usual license header, see the
   existing files for examples.

 - In general, please try to keep the register and bit naming as close
   as possible to the official vendor datasheets. Among other reasons, this
   makes it easier for users to find what they're looking for in the
   datasheets, programming manuals, and application notes.

 - All register definitions should follow the following naming conventions:

   - The #define names should be all-caps, parts are separated by
     an underscore.

   - The name should be of the form SUBSYSTEM_REGISTER_BIT, e.g.
     ADC_CR2_DMA, where ADC is the subsystem name, CR2 is the register NAME,
     and DMA is the name of the bit in the register that is defined.

 - All subsystem-specific function names should be prefixed with the
   subsystem name. For example, gpio_set_mode() or rcc_osc_on().

 - Please consistently use the stdint types.

 - Variables that are used to store register values read from registers or
   to be stored in a register should be named reg8, reg16, reg32 etc.

 - For examples on using libopencm3 see the libopencm3-examples repository.

 - Doxygen is used to generate API docs, please follow that style for function
   and definition commentary where possible.

Tips and tricks
---------------

SublimeText users:

 - The project contains a sublime project description file with some basic
   settings provided to make hacking on libopencm3 easier.

 - Recommended SublimeText plugins when hacking on libopencm3:

   - TrailingSpaces: Show and trim trailing line spaces.

   - SublimeLinter: Run checkpatch.pl in the background while you write your
     code and indicate possible coding style issues on the fly.