libopencm3/HACKING

86 lines
3.4 KiB
Plaintext

------------------------------------------------------------------------------
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.