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