10.5. How to contribute to the kernel
10.5.1. Development Conventions
| Rule | Note | |
|---|---|---|
| C Language Standard | C99 without GNU extensions | |
| Macros for constant value | Allowed | |
| Function-like macros | Avoid in principle | |
| Macro Switches | Use with cautions | |
| Macro Splicing | Avoid in principle | |
| Naming rules for variables | words separated by underscores | Linux Style |
| Naming rules for functions | words separated by underscores | Linux Style |
| Naming rules for properties (for classes) | Small-Camel |
Note: For items listed as Avoid-in-principle, if they are really required, each use-case need to be discussed separately.
10.5.1.1. Exceptions
PLOOC - The Protected Low-overhead Object Oriented Programming
__instruction_def.h - simplify the management of VM instructions in coding.
10.5.2. Kernel development environment
10.5.2.1. Option 1 Development under docker (recommended)
10.5.2.2. Option 2 pico real machine development
Prepare a copy of the Raspberry Pi pico development board, then clone the complete repository and use the bsp/pico-dev project in the repository.
10.5.3. Object-Oriented Programming with ANSI-C
10.5.3.1. Overview
PikaPython employs the popular Object-Oriented Programming with ANSI-C, a.ka. OOPC methodology in the design and uses an open-source OOPC template, i.e. PLOOC in the kernel. In addition to the normal structure based class definition, PLOOC introduced a so-called masked-structures. With this trick, members of a class can not only be marked as private, protected and public, but also actually protected as private/protected as other native OO languages do, such as C++, C# etc.
For example, in the dataMemory.h, it defines a class Pool:
#if defined(__DATA_MEMORY_CLASS_IMPLEMENT__)
#define __PLOOC_CLASS_IMPLEMENT__
#elif defined(__DATA_MEMORY_CLASS_INHERIT__)
#define __PLOOC_CLASS_INHERIT__
#endif
#include "__pika_ooc.h"
...
struct Pool{
private_member(
BitMap bitmap;
uint8_t* mem;
uint8_t aline;
uint32_t size;
uint32_t first_free_block;
uint32_t purl_free_block_start;
)
};
Here, all members are embraced with private_member(), that means outside the class scope, people cannot see/access those private members, as shown below:
While, in the dataMemory.h, a macro __DATA_MEMORY_CLASS_IMPLEMENT__ is added before any includings:
#define __DATA_MEMORY_CLASS_IMPLEMENT__
#include "dataMemory.h"
#include "PikaPlatform.h"
...
hence, inside those method functions of the class Pool, we can see/access all members listed as private:
This is because macro __DATA_MEMORY_CLASS_IMPLEMENT__ marks the whole dataMemory.c as it is inside the Pool class scope.
10.5.3.2. Visibility Control
PLOOC is a tool to force a visibility control in the c programming. There are plenty of ways to remove those visibility control in different scales, as shown in the Table 3-1:
Table 3-1 Summary of visibility controls in PLOOC
| Token (Macro) | Scope | Usage | Description |
|---|---|---|---|
| __OOC_DEBUG__ | Global | Define it in the project configuration | Disable protection for private and protected members. We only use this feature for debugging purpose. |
| __OOC_CPP__ | Global | Define it in the project configuration | When you including PLOOC enabled header files in any CPP source files, please define this macro to avoid compilation errors. |
| __\<class_name>_CLASS_IMPLEMENT__ | Local | Define it at the very beginning of the target c source file | It marks current c source file as if it is inside the scope of the target class. You can access all class members. |
| __\<class_name>_CLASS_INHERIT__ | Local | Define it at the very beginning of the target c source file | It marks current c source file as if it is inside the scope of a derived class of the target class (base class). You can access the protected and public members of the base class. |
NOTE: Please use these Tokens carefully and following the OO design principles.
10.5.3.3. Rules of using PLOOC inside PikaPython
We only use PLOOC inside kernel in principle
Contributors are NOT forced to use PLOOC even contribute to the kernel.
Unless otherwise state, we assume that you agree that the maintainer are authorized to modify your code for adding PLOOC.