9.5. How to contribute to the kernel

9.5. How to contribute to the kernel

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

9.5.1.1. Exceptions

PLOOC - The Protected Low-overhead Object Oriented Programming
__instruction_def.h - simplify the management of VM instructions in coding.

9.5.2. Kernel development environment

9.5.2.1. Option 1 Development under docker (recommended)

get start -> get start with docker

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

9.5.3. Object-Oriented Programming with ANSI-C

9.5.3.1. Overview

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

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

9.5.3.3. Rules of using PLOOC inside PikaScript

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.