OpenHarmony aims to build an open, distributed OS framework for smart IoT devices in the full-scenario, full-connectivity, and full-intelligence era. It has the following technical features: hardware collaboration for resource sharing, one-time development for multi-device deployment, and a unified OS for flexible deployment.
OpenHarmony supports the following system types:
1. Mini system: a device oriented to devices that have MCU processors such as ARM Cortex-M and 32-bit RISC-V. These devices have limited hardware resources. The minimum device memory is 128 KiB.
2. Small system: a device oriented to devices that have application processors such as 64-bit ARM Cortex-A. The minimum device memory is 1 MiB.
3. Standard system: a device oriented to devices that have application processors such as 64-bit ARM Cortex-A. The minimum device memory is 128 MiB.
OpenHarmony code can run on 32- and 64-bit devices. For easier code portability, clear coding specifications are necessary. This document stipulates the specifications on code porting and 64-bit coding, helping you improve code standardization and portability.
### Application Scope
C and C++ code for the user space and kernel space, without distinguishing the programming language standards.
### Differences Between 32-Bit OS and 64-Bit OS
#### Data Type Differences
Most 32-bit OSs use ILP32, which defines int, long, and pointer as 32 bits. Most 64-bit OSs use LP64, which defines long, long long, and pointer as 64 bits. The Windows OS uses LLP64, which defines long long and pointer as 64 bits. The table below lists the length of each primitive data type.
##### Alignment of the data structure that contains a pointer
```c
typedefstructtagFoo{
void*p;
uint32_ti;
}Foo;
```
On a 32-bit OS, the pointer length is 4, **Foo** is 4-byte aligned, and **sizeof(Foo)** is 8. On a 64-bit OS, the pointer length is 8, **Foo** is 8-byte aligned, and **sizeof(Foo)** is 16.
##### Alignment of the data structure that contains a 64-bit integer
```c
typedefstructtagFoo{
uint64_tp;
uint32_ti;
}Foo;
```
Although uint64\_t has a fixed length, **sizeof(Foo)** is different due to alignment. On a 32-bit OS, **Foo** is 4-byte aligned, and **sizeof(Foo)** is 12. On a 64-bit OS, **Foo** is 8-byte aligned, and **sizeof(Foo)** is 16. The preceding statement is also true when uint64\_t is replaced by double.
### Conventions
**Rule**: Conventions that must be complied with during programming.
**Rec**: Conventions that should be complied with during programming.
## Coding Guide
### General Principles
#### [Rule] Follow this coding guide to write code that is applicable to both 32- and 64-bit OSs.
[Description] OpenHarmony will run in both 32- and 64-bit environments for a long time. To ensure code consistency, you must consider code portability during coding.
### Data Type Definition and Formatting
#### [Rule] Use the defined data types to define variables, and avoid custom basic data types without special meanings or requirements.
[Description] Data types with variable lengths may cause incompatibility issues on 32- and 64-bit OSs. Unified and clear data types are required. OpenHarmony defines the following primitive data types:
| size_t/pthread_t | **4** | **8** | %zu | Unsigned, variable-length type. It is used only for compatibility of calling library functions (for example, size_t is used in an underlying API).|
The preceding types are defined in the **stddef.h** (C) and **cstdint** (C++) standard libraries. When `#define` is used to redefine related types, the source must be one of these types.
Do not use non-standard types unless otherwise specified. Do not define common basic types unless they have special meanings. For primitive data types used in third-party interfaces and API calling, refer to their respective rules.
[Example] Do not customize primitive data types unless necessary.
```c
// Do not use the following code to redefine a data type.
typedefunsignedintUINT32;// This definition is forbidden.
// The preceding definition can be replaced by uint32_t. However, you can define a type that has a specific meaning.
typedefuint32_tDB_TABLE_ID;// This definition can be retained.
```
[Example] Do not use the following two types, because their lengths are different from the common sense.
| float_t | **12** | **4** | - | Improper length. Do not use it.|
| double_t | **12** | **8** | - | Improper length. Do not use it.|
#### [Rec] Do not use custom variable-length variables. A clear description is required if they are used to adapt to platforms or third-party interfaces.
[Description] The native types such as long, int, short, and size_t have different lengths in the 32- and 64-bit environments. This may cause code risks. If these types are used for external storage or communication, system incompatibility may occur. Therefore, do not use them unless otherwise specified.
[Exception] Due to platform, third-party interface, or library function reasons, they can be used with a clear description.
[Example]
```c
longvar;
// This data type is 4-byte long on a 32-bit OS and 8-byte long on a 64-bit OS. You are advised to use uint32_t or uint64_t instead.
```
#### [Rule] Do not use uchar to define variables.
[Description] It is not standard to use uchar or unsigned char to define strings. Instead, use char for strings or uint8_t for unsigned integers.
For non-ANSI character sequences involving 8-bit encoding, char is recommended. In C++, wchar can be used.
#### [Rule] Define an integer variable that is used to store a pointer as uintptr_t.
[Description] The uintptr_t type is used to store data of the pointer length. The length can be automatically adjusted in the 32- and 64-bits environments.
[Example]
```c
uintptr_tsessionPtr;
// When the pointer is stored as a variable, both the forced type conversion and left value should be defined as uintptr_t to adapt to the length changes in different scenarios.
sessionPtr=(uintptr_t)GetMemAddress();
```
#### [Rec] When the type defined by the input parameter or return value of a function does not match the variable type, exercise caution to ensure that the result is correct after conversion following the value assignment and type conversion rules.
[Description] If type inconsistency is inevitable, convert the type with caution to ensure that the final result meets the application requirements.
[Example]
```c
longfunction(longl);
intmain(){
inti=-2;
unsignedintk=1U;
longn=function(i+k);
}
```
Note: The preceding code will fail to be executed on a 64-bit OS because the expression (i + k) is an unsigned 32-bit expression. When it is converted to the long type, the symbols are not extended. The result of the input parameter is incorrect. The solution is to forcibly convert one of the operands to a 64-bit type.
#### [Rule] Use 64-bit compatible macros, such as %PRId64, %PRIu64, and %PRIx64, to print 64-bit integers. Incompatible macros, such as %d, %ld, %zd, %x, and %lx, are not allowed.
[Description] If the data to be formatted is of the 64-bit type (defined as uint64_t), format the output as follows:
```c
#include <stdio.h>
#include <stdint.h>
#include <inttypes.h>
intmain()
{
uint64_ta=0x1234567fffffff;
printf("a = %"PRIx64"\n",a);
return0;
}
```
The preceding code can output 64-bit numbers in both 32- and 64-bit environments. If other formatting methods are used, compatibility issues may occur, as listed in the following table.
| %lx | Type mismatch alarm| Incorrect| No alarm| Correct| Incompatible|
| %zx | Type mismatch alarm| Incorrect| No alarm| Correct| Incompatible|
| %llx | No alarm| Correct| Type mismatch alarm| Correct| Incompatible|
| %p | Type mismatch alarm| Incorrect| Type mismatch alarm| Correct| Incompatible|
| %PRIx64 | No alarm| Correct| No alarm| Correct| Compatible|
[Example]The following is an example of the type mismatch alarm information:
```bash
# Build on a 32-bit OS
format '%lx' expects argument of type'long unsigned int', but argument 2 has type'uint64_t {aka long long unsigned int}'
format '%zx' expects argument of type'size_t', but argument 2 has type'uint64_t {aka long long unsigned int}'
format '%p' expects argument of type'void *', but argument 2 has type'uint64_t {aka long long unsigned int}'
# Build on a 64-bit OS
format '%llx' expects argument of type'long long unsigned int', but argument 2 has type'uint64_t {aka long unsigned int}'
format '%p' expects argument of type'void *', but argument 2 has type'uint64_t {aka long unsigned int}'
```
#### [Rule] When printing type-variable data, consider the data length and reserve sufficient space during alignment.
[Description] On a 32-bit OS, the maximum length of the pointer and size_t is 8 bits (hexadecimal) or 10 bits (decimal). On a 64-bit OS, their maximum length is 20 bits. Therefore, you need to consider the length range when printing the data.
#### [Rule] Do not use L/UL as the suffix of constants. You can add the suffix U to indicate the unsigned int type and the suffix LL/ULL to indicate the 64-bit length.
[Description] By default, constants without suffixes are of the int type. When L/UL is used as the suffix, the length may change on 32- and 64-bit OSs. Therefore, use LL/ULL as the suffix to ensure that the length is fixed at 64 bits in both the 32- and 64-bit environments.
| 1 | 4 | 4 | The default type is int32_t, and the length is fixed.|
| 1U | 4 | 4 | The default type is uint32_t, and the length is fixed.|
| 1L | **4** | **8** | The suffix is L. The length is not fixed. Do not use this constant.|
| 1UL | **4** | **8** | The suffix is UL. The length is not fixed. Do not use this constant.|
| 1LL | 8 | 8 | The default type is int64_t. The value is a long integer, and the length is fixed at 64 bits.|
| 1ULL | 8 | 8 | The type is uint64_t, and the value is an unsigned long integer.|
| 0x7FFFFFFF | 4 | 4 | The value is an unsigned number. It can be used within the value range of int32\_t. The default type is int32\_t. |
| 0x7FFFFFFFL | **4** | **8** | The length is not fixed. Do not use this constant.|
| 0x7FFFFFFFLL | 8 | 8 | The length is fixed.|
| 0x80000000 | 4 | 4 | It can be used within the value range of uint32\_t. The type is uint32\_t.|
| 0x80000000L | **4** | **8** | The suffix is L. It can be used within the value range of uint32\_t. This constant is meaningless and should be avoided.|
| 0x80000000LL | 8 | 8 | The suffix is LL. It can be used within the value range of uint32\_t. The length is fixed.|
| 0x8000000000 | **NA or 8**| **8** | No prefix. It can be used when the value range of uint32\_t is exceeded. The compiler uses LL by default or considers the value invalid. On a 64-bit OS, the type is fixed at uint64\_t.|
| 0x8000000000L | **NA or 8**| **8** | The suffix is L. It can be used when the value range of uint32_t is exceeded. This constant is meaningless and should be avoided.|
| 0x8000000000LL | 8 | 8 | The suffix is LL. The type is uint64_t.|
As shown in the preceding table, a constant with the L or UL suffix has different lengths in the 32- and 64-bit environments. This hinders code portability. Therefore, do not use the L or UL suffix.
[Example]
```c
// UL in the following definition is meaningless. It causes an error on a 32-bit OS and is unnecessary on a 64-bit OS.
#### [Rule] Use macro constants defined in the standard header file.
[Description] The standard header files **stdint.h** (C) and **cstdint.h** (C++) contain macro constants with the maximum and minimum values. Reference these macro constants, rather than customizing new ones.
[Example]
```c
#include <cstdio>
#include <cinttypes>
intmain()
{
std::printf("%zu\n",sizeof(std::int64_t));
std::printf("%s\n",PRId64);
std::printf("%+"PRId64"\n",INT64_MIN);
std::printf("%+"PRId64"\n",INT64_MAX);
std::int64_tn=7;
std::printf("%+"PRId64"\n",n);
}
```
#### [Rule] Use unified definitions instead of all Fs to indicate invalid values of constants.
[Description] The same numeric constant value may be understood differently on 32- and 64-bit OSs, since the 32-bit OS has the signed and unsigned types. Especially, if the most significant bit is 1, this bit is considered as a negative number on a 32-bit OS based on the signed type and a positive number on a 64-bit OS. Use the definitions in **typedef.h** to indicate invalid values.
```c
// Use the definitions in typedef.h.
#define INVALID_INT8((int8_t)(-1))
#define INVALID_UINT8((uint8_t)(-1))
#define INVALID_INT16((int16_t)(-1))
#define INVALID_UINT16((uint16_t)(-1))
#define INVALID_INT32((int32_t)(-1))
#define INVALID_UINT32((uint32_t)(-1))
#define INVALID_INT64((int64_t)(-1))
#define INVALID_UINT64((uint64_t)(-1))
```
[Example]
```c
// On a 32-bit OS, n is a negative number.
longn=0xFFFFFFFF;
// On a 64-bit OS, n is a positive number. The actual value is 0x00000000FFFFFFFF.
longn=0xFFFFFFFF;
```
#### [Rec] Use uint32_t to define temporary variables whose size does not exceed 32 bits.
[Description] You do not need to pay special attention to the type of a variable. Use the default uint32_t type to minimize forced type conversions caused by type inconsistency.
### Structure Alignment and Padding
#### [Rule] Do not hardcode a constant to specify the variable length and structure length. Use built-in types such as **sizeof** to obtain the variable length and structure length.
[Description] **sizeof** automatically calculates the variable length and structure length, which might be incorrect if hardcoded. In addition, the running performance will not be adversely affected since the variable length is calculated during build.
On a 64-bit OS, 8-byte alignment is used by default. Using **sizeof()** to obtain the structure length can avoid length calculation errors caused by structure alignment.
Pay attention to the length differences on 32- and 64-bit OSs to avoid length calculation errors. Calculate and apply for space based on the maximum length.
[Example] **sizeof** is not used to calculate the structure length, causing insufficient memory space.
```c
int32_t*p;
p=(int32_t*)malloc(4*ELEMENTS_NUMBER);
// This code assumes that the pointer length is 4 bytes. However, in LP64, the pointer length is 8 bytes.
// The correct method is to use sizeof().
int32_t*p;
p=(int32_t*)malloc(sizeof(p)*ELEMENTS_NUMBER);
```
#### [Rec] In special cases, force the compiler to use a specific alignment mode on the 64-bit OS.
[Description] If necessary, you can use the specified alignment mode to ensure code compatibility. If the pseudo-instruction **#pragma pack (n)** is used, the compiler aligns data by n bytes. If the pseudo-instruction **#pragma pack ()** is used, the compiler cancels the custom byte alignment mode.
[Example]
```c
#pragma pack(push) # Save the current alignment mode.
#pragma pack(1) # Set the alignment mode to 1-byte alignment.
structtest
{
......
};
#pragma pack(pop) # Restore the previous alignment mode.
```
#### [Rule] Uniform the message structures related to multi-device communication. For compatibility purposes, 1-byte alignment is preferred. Do not use 8-byte alignment or 64-bit data types to avoid errors during communication with a 32-bit OS.
Note: Inter-board communication messages involve inter-board operations. The communication fails unless all software is upgraded synchronously. For the sake of compatibility, use 1-byte alignment for the existing protocols and structures and convert them into the network byte order. For new communication protocols, use 4-byte alignment for higher communication efficiency and processing performance.
#### [Rule] Avoid structure padding for external APIs and use at least 4-byte alignment.
[Description] If structure definitions are included in an API header file provided externally, do not pad the structures. It is recommended that natural alignment be used to avoid data holes. Use at least 4-byte alignment.
#### [Rec] Use member names to access structure members. Do not use the offset mode.
[Description] The offsets of data structure members are different in the 32- and 64-bit environments. Therefore, the size of each member cannot be used as the offset. A 32-bit OS does not have structures automatically padded. However, on a 64-bit OS, automatic padding may occur.
[Example]
```c
StructA
{
uint32_ta;
uint32_t*p;
uint32_tb;
};
```
The offset of member b is equal to sizeof(a) + sizeof(p) on a 32-bit OS. This is not true on a 64-bit OS. The correct method is to locate the index based on the variable name.
```c
xxx.b=123;
```
If the structure definition is special, for example, if the structure is only the message header and there are other fields, then you can redefine the structure so that it does not include padding fields.
[Example]
```c
typedefstruct{
uint32_tself;/* Structure used for alignment. */
uint32_tbrother;/* Structure used for alignment. */
uint8_tprocessedFlag;/* Flag indicating whether the current node has been processed. */
uint8_treserve[3];/* Reserved for 4-byte alignment. */
}TreeNodeInfo;
typedefstruct{
TreeNodeInfonodeInfo;/* Tree information data structure of each node */
void*userInfo;/* User information data structure of each node */
}TreeNode;
```
The **TreeNode** structure has two member structures. In the following code, the address of the first member is the initial address of the second member minus the value of sizeof (the first member). (**inUserInfo** points to the **userInfo** field in the structure.)
The structure adopts natural alignment. Note that the length of the substructure **TreeNodeInfo** is 12 bytes on both 32- and 64-bit OSs. On a 32-bit OS, there is no padding between member structures of the **TreeNode** structure, and the structure length is 16 bytes. On a 64-bit OS, **sizeof(TreeNodeInfo)** is 12 and **sizeof(TreeNode)** is 24, which means that there is a 4-byte padding field after the substructure **TreeNodeInfo**. Therefore, when the preceding method is used to obtain the address of the previous field on a 64-bit OS, the 4-byte padding field is not calculated, causing a member access error.
#### [Rec] When defining a structure, implement 8-byte natural alignment to save storage space and avoid padding on the premise that readability is ensured.
[Description] If a structure can be naturally aligned, no padding is required, which effectively reduces the invalid space of the structure. You are advised to define 64-bit data types such as size_t and pointer at both ends of the structure without affecting readability.
[Example]
```c
// The length of the following structure is 24 bytes in natural alignment mode.
structFoo
{
int32_ta;
uint64_tl;
int32_tx;
}
// After proper adjustment, the size can be reduced to 16 bytes.
structFoo
{
uint64_tl;
int32_ta;
int32_tx;
}
```
### Data Type Conversion and Calculation
#### [Rule] Avoid implicit type conversion between different data types. If necessary, use explicit type conversion to avoid result inconsistency between the 32- and 64-bit environments.
[Description] Exercise caution when performing operations between operands with different lengths and precisions. Pay attention to the following about implicit type conversion:
1. When the value of a 64-bit variable is assigned to a 32-bit variable, the values of the least significant 32 bits are directly assigned, and the values of the most significant 32 bits are ignored. Then the least significant 32 bits are treated as signed or unsigned based on the left value variable type.
2. When the value of a 32-bit variable is assigned to a 64-bit variable, sign extension is performed based on whether the 32-bit variable is signed or unsigned, and then the 64-bit variable is treated as signed or unsigned based on the variable type.
3. For operations of signed and unsigned numbers, if the result type is not specified, the result is treated as unsigned by default.
The preceding conversion process may cause unexpected results. Therefore, exercise caution to avoid implicit type conversion as much as possible.
[Example] Example of the correct conversion result
```c
int32_tt1=-2;
int64_tt2=1;
int32_tt3=t1+t2;
printf("t3 = %d\n",t3);
// Printed: t3 = -1
```
t1 is a 32-bit number, and t2 is a 64-bit number. Before the calculation, t1 is extended to 64 bits. After the calculation, the result is a 64-bit int64_t type. The hexadecimal value stored in the memory is 0xffffffffffffffff. During the value assignment, the value is truncated into 0xffffffff. Then, the value is treated as signed, which is -1. Although the result is correct, data truncation occurs. This may not be the author's intention.
[Example] Conversion from signed to unsigned
```c
int64_tt1=-1;
uint32_tt2=t1;
printf("t2=%u",t2);
// Printed: t2=4294967295
```
t1 is a 64-bit int64_t type, which is 0xffffffffffffffff in binary mode. When this value is assigned to a 32-bit int type, the most significant 32 bits are ignored and the least significant 32 bits are displayed. The binary value is 0xffffffff, which is 4294967295 in unsigned mode.
[Example] Conversion from 32-bit to unsigned 64-bit
```c
int32_tt1=-1;
uint64_tt2=t1;
printf("t2 = %lu\n",t2);
// Printed: t2 = 18446744073709551615
```
t1 is a signed negative 32-bit number, which must be extended with signs. The most significant bits of the negative number are all fs, and the value after extension is 0xffffffffffffffff. t2 is an unsigned 64-bit number, the value of which is a large positive number.
#### [Rule] When a pointer is used as the base address and the offset is calculated by byte, the pointer must be forcibly converted to a single-byte pointer such as uintptr_t or uint8_t *.
[Description] If the pointer is converted to an integer of the uint32_t type, the pointer may be truncated. This will not occur if the pointer is converted to uintptr_t. The pointer can also be converted to a single-byte pointer such as uint8_t * and char *. In this case, the offset is considered as bytes. A one-byte offset will be carried out for the void * type. To clarify the type, you are advised to use the type that is more specific.
void*pPkt=(void*)((uintptr_t)MSG_GET_DATA_ADDR(msgAddr)+OFFSET);// C
void*pPkt=reinterpret_cast<void*>(reinterpret_cast<uintptr_t>(MSG_GET_DATA_ADDR(msgAddr))+OFFSET);// C++
```
#### [Rule] Mutual assignment is forbidden between pointers and uint32_t, including function parameter passing.
[Description] If the variable to be defined is a length-variable pointer, use void *. If the variable to be defined is a pointer or an integer, use uintptr_t.
[Example] Conversion between pointers and integers
```c
int32_ti,*p,*q;
p=&i;
q=(int32_t*)(int32_t)&i;
// In ARM Cortex-A32, p = q; in A64-LP64, p != q
```
To avoid this type conflict, use uintptr_t to indicate the pointer type.
#### [Rule] Mutual assignment is forbidden between size_t and int32_t/uint32_t, including function parameter passing.
[Description] The variable-length type cannot be forcibly converted to the 32-bit type.
[Example]
```c
int32_tlength=(int32_t)strlen(str);// Incorrect
```
strlen returns size_t (unsigned long in LP64). When the value is assigned to int32_t, truncation is inevitable. Generally, truncation occurs only when the length of **str** is greater than 2 GB. This is rare in programs.
#### [Rule] When a large array or large `for` loop index is used on a 64-bit OS, the index type must be consistent with the subscript boundary.
[Description] If a large array or large loop is used on a 64-bit OS, the index range may exceed 32 bits. In this case, the variable-length type or 64-bit type must be used to define the array subscript or loop variable to prevent full traversal failures caused by an incorrect variable range.
[Example]
```c
int64_tcount=BIG_NUMBER;
for(unsignedintindex=0;index!=count;index++)
...
```
On a 64-bit OS, int64_t is a 64-bit type, and count is a large number. unsigned int is a 32-bit type. As a result, the loop never ends. Therefore, the index type should be changed to int64_t.
### Bit Field and Byte Order
#### [Rule] When defining variables based on bit fields, fully consider the basic types and alignment of bit fields to avoid calculation errors in different bit widths.
[Description] Consider both the width of a bit field and alignment. The structure length is different in different environments. Use the name rather than direct calculation result for the value of a bit field.
#### [Rule] On a 64-bit OS, consider the length difference caused by the shift operation and the problem that the value generated after shift is implicitly extended to 64 bits.
[Description] During the shift operation, check whether overflow and rewind occur. Change the data type to 32-bit to avoid result inconsistency.
[Example]
```c
int64_tt=1<<a;// Consider the size of a.
```
The maximum value of a is 32 on a 32-bit OS and 64 on a 64-bit OS. If a is a 32-bit variable, the extension to 64 bits must also be considered.
### Third-Party Libraries and Differentiated Features
#### [Rule] The third-party class libraries used by a 64-bit OS must support 64-bit.
[Description] Some library functions and third-party open-source code may not fully support 64-bit. You must evaluate all involved code to ensure that it can run in the 64-bit environment. Some library functions are implemented using different APIs in the 32- and 64-bit environments. Ensure that correct APIs are used.
[Example] In the 32-bit environment, **mmap** can be used. If the size of the memory to map exceeds 2 GB, **mmap64** is required. In the 64-bit environment, **mmap** is used.
#### [Rule] Functionalities involving bottom-layer assembly must be debugged separately on the 32- and 64-bit OSs.
[Description] The number and bit width of registers are different in the 32- and 64-bit environments. The debugging functionalities related to assembly must be adjusted. You must also pay attention to the code validity in the 32-bit and 64-bit environments.
[Example] For the push-to-stack functionality of the call stack, you must write and debug the assembly code in the 32- and 64-bit environment separately.
#### [Rule] The patch functionality must support both 32- and 64-bit instructions.
[Description] The patch mechanism and functionalities must be adopted to the command length changes.
#### [Rule] All tools used on a 64-bit OS must support 64-bit.
[Description] If type inconsistency is inevitable, convert the type with caution to ensure that the final result meets the application requirements.
OpenHarmony aims to build an open, distributed OS framework for smart IoT devices in the full-scenario, full-connectivity, and full-intelligence era. It has the following technical features: hardware collaboration for resource sharing, one-time development for multi-device deployment, and a unified OS for flexible deployment.
The Hardware Driver Foundation (HDF) provides the following driver framework capabilities: driver loading, driver service management, and driver message mechanism. This unified driver architecture system is designed to provide a more precise and efficient development environment, where you can perform one-time driver development for multi-system deployment.
As such, certain coding specifications are required for the OpenHarmony driver implemented based on the HDF. This document stipulates the specifications on the driver code, helping you improve code standardization and portability.
## Coding Guide
### General Principles
#### [Rule] Use the capabilities provided by the HDF to implement drivers.
[Description] The HDF supports driver loading, driver service management, and driver message mechanism. It provides the Operating System Abstraction Layer (OSAL) and Platform Abstraction Layer (PAL) to support cross-system and cross-platform driver deployment. It also provides capabilities such as driver model abstraction, common tools, and peripheral component framework. You should develop drivers based on these capabilities to ensure that the drivers can be deployed on various devices powered by OpenHarmony.
#### [Rule] Follow this coding guide to develop drivers that can run in both the kernel space and user space.
[Description] Kernel-mode drivers are different from user-mode drivers in essence. They apply to different use cases. You must follow this guide during service design and development and use the HDF OSAL and PAL to shield the differences, so as to ensure that the drivers can run in both the kernel space and user space.
#### [Rec] Include the drivers/framework/include directory instead of a subdirectory in the build script.
[Description] The **drivers/framework/include** directory is the root directory of the header file exposed by the HDF externally. This directory contains multiple subdirectories to represent different modules such as the core framework, OSAL, and PAL. When using a header file, you are advised to include the **drivers/framework/include** directory in the build script. This avoids repeated inclusion when the script is referenced in the code.
[Example]
```gn
config("xxxx_private_config") {
include_dirs = [
"//drivers/framework/include",
"//drivers/framework/include/core", # Not recommended.
]
}
```
```c
#include <core/hdf_device_desc.h>
#include <hdf_device_desc.h> // Not recommended.
```
### HDF Core Framework
#### [Rule] Implement the Bind, Init, and Release methods based on the responsibility definitions in the HdfDriverEntry object.
[Description] The **HdfDriverEntry** object is the entry of an HDF driver. The **Bind**, **Init**, and **Release** methods have their own responsibilities. You must implement the corresponding functions based on the responsibilities.
```c
structHdfDriverEntryg_sampleDriverEntry={
.moduleVersion=1,
.moduleName="sample_driver",
.Bind=SampleDriverBind,// Responsibility: Bind the service interface provided by the driver to the HDF.
.Init=SampleDriverInit,// Responsibility: Initialize the driver service.
.Release=SampleDriverRelease,// Responsibility: Release driver resources. It is invoked when an exception occurs.
};
HDF_INIT(g_sampleDriverEntry);
```
#### [Rule] The first member in the driver service structure must be of the IDeviceIoService type.
[Description] The first member of the service interface defined by the driver must be of the **IDeviceIoService** type.
[Example]
```c
structISampleDriverService{
structIDeviceIoServiceioService;// The first member must be of the IDeviceIoService type.
int32_t(*FunctionA)(void);// The first service interface of the driver.
int32_t(*FunctionB)(uint32_tinputCode);// The second service interface of the driver. More service interfaces can be added here.
};
```
[Example]
```c
structISampleDriverService{
structIDeviceIoServiceioService;// The first member must be of the IDeviceIoService type.
void*instance;// A service instance can be encapsulated here to provide service interfaces.
};
```
#### [Rule] All driver service interfaces must be bound using the Bind method of the HdfDriverEntry object. All service interfaces must be defined. They cannot be defined as null.
[Description] The service interfaces defined by the driver are exposed externally. If a service interface is not defined or is defined as null, exceptions may occur during external invocation.
.FunctionB=NULL,// The service interface cannot be defined as null.
};
// Bind ioService to the device object created by the HDF.
deviceObject->service=&sampleDriver.ioService;
returnHDF_SUCCESS;
}
```
#### [Rec] Call the HdfDeviceSetClass interface in the Init method of the HdfDriverEntry object to define the driver type.
[Description] Based on the driver type, you can classify the drivers of the current device and query the driver capabilities of the current device. For better driver management, you are advised to call **HdfDeviceSetClass** to set the driver type.
HDF Configuration Source (HCS) describes the configuration source code of the HDF in the form of key-value pairs. It decouples configuration code from driver code, making it easy for you to manage the driver configuration.
The driver configuration consists of the driver device description defined by the HDF and the private configuration of a driver.
**Driver Device Description**
The driver loading information required by the HDF comes from the driver device description. Therefore, you must add the driver device description to the **device_info.hcs** file defined by the HDF.
#### [Rule] Before configuring a driver, determine the hardware to which the driver belongs and the deployment mode, and plan the directories and files to be configured.
[Description] In the **vendor** directory of the OpenHarmony source code, plan the directories based on the chip vendor, development board, and configuration. The HDF driver configuration is stored in the **hdf\_config** directory. According to the hardware specifications, the **hdf\_config** directory stores kernel-mode configuration information or both kernel- and user-mode configuration information. You should determine the directory where the driver is to be configured based on the driver hardware and deployment mode.
[Example]
```bash
$openharmony_src_root/vendor/hisilicon/hispark_taurus/hdf_config # Directory for storing the kernel-mode configuration file. There are no user-mode configuration files.
$openharmony_src_root/vendor/hisilicon/Hi3516DV300/hdf_config/khdf # Directory for storing the kernel-mode configuration file.
$openharmony_src_root/vendor/hisilicon/Hi3516DV300/hdf_config/uhdf # Directory for storing the user-mode configuration file.
$openharmony_src_root/vendor/hisilicon/Hi3516DV300/hdf_config/khdf/device_info/device_info.hcs # Device description file of the kernel-mode driver.
$openharmony_src_root/vendor/hisilicon/Hi3516DV300/hdf_config/khdf/lcd/lcd_config.hcs # Private configuration file of the kernel-mode driver.
```
#### [Rule] Use existing configuration information and inherit existing configuration templates during driver configuration.
[Description] The **host**, **device**, and **deviceNode** templates have been configured in the **device_info.hcs** file. When configuring a driver, make full use of the existing configuration information and inherit HCS features to minimize your configuration workload.
[Example]
```
root {
device_info {
match_attr = "hdf_manager";
template host { // host template
hostName = "";
priority = 100; // Host startup priority. The value ranges from 0 to 200. A larger value indicates a lower priority. The default value 100 is recommended. If the priorities are the same, the host loading sequence cannot be ensured.
template device { // device template
template deviceNode { // deviceNode template
policy = 0; // Policy for publishing drive services.
priority = 100; // Driver startup priority. The value ranges from 0 to 200. A larger value indicates a lower priority. The default value 100 is recommended. If the priorities are the same, the device loading sequence cannot be ensured.
preload = 0; // The driver is loaded as required.
permission = 0664; // Permission for the driver to create a device node.
moduleName = "";
serviceName = "";
deviceMatchAttr = "";
}
}
}
// To use the default values in the template, the node fields can be not included.
sample_host :: host { // sample_host inherits the host template.
hostName = "host0"; // Host name. The host node is a container used to store a type of drivers.
device_sample :: device { // device_sample inherits the device template.
device0 :: deviceNode { // device0 inherits the deviceNode template.
policy = 1; // Overwrite the policy in the template.
moduleName = "sample_driver"; // Driver name. The value of this field must be the same as that of moduleName in the HdfDriverEntry structure.
serviceName = "sample_service"; // Service name of the driver, which must be unique.
deviceMatchAttr = "sample_config"; // Keyword for matching the private data of the driver. The value must be the same as that of match_attr in the private data configuration table of the driver.
}
}
}
}
}
```
#### [Rule] Use the defined types during driver model design and classification. Do not configure hosts and devices repeatedly.
[Description] The HDF places the same type of devices in the same host. You can develop and deploy the driver functionalities of the host by layer, so that one driver has multiple nodes. The following figure shows the HDF driver model.
Place devices of the same type in the same host. When adding a device, check whether the host of the same type already exists. If such a host already exists, configure the device in the host. Do not configure the same host again. A device belongs to only one driver. Therefore, do not configure the same device in different hosts.
#### [Rule] Set publication policies for driver services based on service rules.
[Description] The driver service is the object of capabilities provided by the driver to external systems and is managed by the HDF in a unified manner. The HDF uses the **policy** field in the configuration file to define policies for drivers to publish services externally. The values and meanings of this field are as follows:
```c
typedefenum{
/* The driver does not provide services.*/
SERVICE_POLICY_NONE=0,
/* The driver provides services for kernel-space applications. */
SERVICE_POLICY_PUBLIC=1,
/* The driver provides services for both kernel- and user-space applications. */
SERVICE_POLICY_CAPACITY=2,
/** Driver services are not published externally but can be subscribed to. */
SERVICE_POLICY_FRIENDLY=3,
/* Driver services are not published externally and cannot be subscribed to. */
SERVICE_POLICY_PRIVATE=4,
/** Invalid policy. */
SERVICE_POLICY_INVALID
}ServicePolicy;
```
You must set the policies based on service rules. Do not set unnecessary policies, for example, setting user-mode publication policies for kernel-mode drivers.
[Example]
```
root {
device_info {
sample_host {
sample_device {
device0 {
policy = 1; // The driver provides services for kernel-space applications.
...
}
}
}
}
}
```
#### [Rule] The permission to create device nodes for a driver must match the publication policy of the driver.
[Description] In the **device_info.hcs** file, the **permission** field specifies the permission used by the driver to create a device node. This field is a 4-digit octal number and uses the Unix file permissions, for example, 0644. This field takes effect only when the driver provides services for user-space applications (policy = 2).
You must ensure that the publication policy of the driver service matches the device node permission. Otherwise, access to the driver service may fail or the permission of the device node may be inappropriate.
[Example]
```
root {
device_info {
sample_host {
sample_device {
device0 {
policy = 2; // The driver provides services for both kernel- and user-space applications.
permission = 0640; // Recommended value
...
}
}
}
}
}
```
[Counterexample]
```
root {
device_info {
sample_host {
sample_device {
device0 {
policy = 2; // The driver provides services for both kernel- and user-space applications.
permission = 0777; // Excessive permission.
...
}
}
}
}
}
```
[Counterexample]
```
root {
device_info {
sample_host {
sample_device {
device0 {
policy = 1; // The driver provides services for kernel-space applications but does not create a device node.
permission = 0640; // Redundancy configuration
...
}
}
}
}
}
```
#### [Rule] Configure whether to load a driver as required based on service requirements.
[Description] In the **device_info.hcs**, **preload** specifies the driver loading mode. The values and meanings of this field are as follows:
```c
typedefenum{
/* The driver is loaded by default during the system boot process. */
DEVICE_PRELOAD_ENABLE=0,
/* The driver is loaded after a quick start is complete if the system supports quick start. If the system does not support quick start, this value has the same meaning as DEVICE\_PRELOAD\_ENABLE. */
DEVICE_PRELOAD_ENABLE_STEP2,
/* The driver is not loaded during the system boot process. When a user-mode process requests the driver service, the HDF attempts to dynamically load the driver if the driver service does not exist. */
DEVICE_PRELOAD_DISABLE,
/** Invalid value. */
DEVICE_PRELOAD_INVALID
}DevicePreload;
```
Set the **preload** field based on the service requirements.
[Example]
```
root {
device_info {
sample_host {
sample_device {
device0 {
preload = 2; // The driver is loaded as required.
...
}
}
}
}
}
```
#### [Rec] When the preload field is set to 0, configure the loading priority based on the service requirements.
[Description] In the **device_info.hcs** file, the **priority** field indicates the host and driver loading priority. The value of this field is an integer ranging from 0 to 200. For drivers in different hosts, a smaller priority value of the host indicates a higher driver loading priority. For drivers in the same host, a smaller priority value of the driver indicates a higher driver loading priority. The default value of the **priority** field is 100. If this field is not set or set to the same value for different drivers, the driver loading sequence cannot be ensured. You should configure the **priority** field based on the service requirements to ensure the driver loading sequence.
[Example]
```
root {
device_info {
sample_host0 {
priority = 100;
sample_device {
device0 {
preload = 0; // The driver is loaded by default.
priority = 100; // The HDF ensures that the driver is loaded before device1.
...
}
device1 {
preload = 0; // The driver is loaded by default.
priority = 200; // The HDF ensures that the driver is loaded after device0.
...
}
}
}
sample_host1 {
priority = 100; // The HDF does not ensure the loading sequence because this host has the same priority as sample_host0.
...
}
}
}
```
**Private Configuration Information of the Driver**
If a driver has private configurations, you can add a driver configuration file to fill in default configurations of the driver. When loading the driver, the HDF obtains the configuration information, saves it in the **property** field of **HdfDeviceObject**, and passes it to the driver through **Bind** and **Init**.
#### [Rule] Store the private configuration files of the drivers in different directories according to the component type or module.
[Description] You must properly plan the directory for storing private configuration files of drivers. Do not store them in the root directory.
[Example]
```bash
$openharmony_src_root/vendor/hisilicon/Hi3516DV300/hdf_config/khdf/sample/sample_config.hcs # Correct. The private configuration file is stored in the sample directory.
$openharmony_src_root/vendor/hisilicon/Hi3516DV300/hdf_config/khdf/sample_config.hcs # Incorrect. The private configuration file is placed in the root directory.
```
#### [Rule] Add the private configuration file of a driver to the hdf.hcs file in the hdf_config directory.
[Description] The **hdf.hcs** file summarizes the configuration information. The HDF parses the file content and loads the private configuration information of the driver to the device node during the build and runtime. Include the private configuration file of the driver in the **hdf.hcs** file to trigger driver initialization.
[Example]
```c
#include "device_info/device_info.hcs"
#include "sample/sample_config.hcs" // The file contains the private configuration file of a driver.
root{
module="hisilicon,hi35xx_chip";
}
```
#### [Rule] The value of the matchAttr field in the private configuration file of the driver must be the same as that of the deviceMatchAttr field in device_info.hcs.
[Description] The HDF associates with the driver device through the **match_attr** field. A mismatch causes a failure to obtain the private configuration information.
[Example]
```
root {
sample_config {
...
match_attr = "sample_config"; // The value of this field must be the same as that of deviceMatchAttr in device_info.hcs.
}
}
```
#### [Rule] Use underscores (_) in field names in the private configuration file.
[Description] According to the naming rules in the C/C++ coding guide, use underscores (_) in field names in the private configuration file of a driver. In this way, the naming rule is satisfied during the definition of the private configuration data structure in the implementation code. It also makes unified management of the code and configuration files easier.
[Example]
```
root {
sample_config {
sample_version = 1; // Use an underscore (_) in the field name.
sample_bus = "I2C_0";
match_attr = "sample_config";
}
}
```
### HCS Macros
The private configuration information of a driver is loaded to **property** of **HdfDeviceObject**. This occupies memory space, which should be avoided for mini- and small-system devices. To minimize the memory usage, the HDF provides HCS macros to parse the private configuration information.
#### [Rule] Use HCS macros to parse the private configuration information in memory-sensitive or cross-system scenario.
[Description] You should specify the use cases of drivers. In memory-sensitive scenarios or if a driver needs to be used in mini-, small-, and standard-system devices, use HCS macros to parse the private configuration information for higher performance and portability.
#### [Rule] Determine the communication scenario and HdfSbuf type.
[Description] **HdfSbuf** is a data structure used for data transfer. This structure is classified into different types based on the communication scenario. These types are defined in the **hdf_sbuf.h** header file.
```c
enumHdfSbufType{
SBUF_RAW=0,/* SBUF used for communication between the user space and the kernel space. */
SBUF_IPC,/* SBUF used for inter-process communication (IPC). */
SBUF_IPC_HW,/* Reserved for extension. */
SBUF_TYPE_MAX,/* Maximum value of the SBUF type. */
};
```
Determine whether the data transfer is IPC in the user space or between the user space and kernel space, and then create the corresponding **HdfSbuf** structure.
[Example]
```c
voidSampleDispatchBetweenUserAndKernel()
{
int32_tret;
/* Communication between the user space and kernel space. */
#### [Rule] Define the HDF_LOG_TAG macro when using HDF logging.
[Description] The HDF provides the **hdf_log.h** tool ,using which you can output driver run logs. The **HDF_LOG_TAG** macro specifies the log tag. You must define this macro before printing logs.
[Example]
```c
#include <hdf_log.h>
#define HDF_LOG_TAG sample_driver // Define the log tag.
HDF_LOGI("sample driver is initialized");// Use the tool to print logs.
returnHDF_SUCCESS;
}
```
#### [Rule] Verify the return values of the HDF methods and use the error codes provided by the HDF.
[Description] The HDF methods have specific return values. You should verify them rather than ignoring them. The return values correspond to error codes in the **hdf_base.h** header file. Use the error codes provided by the HDF when using the HDF or implementing custom methods.
// A custom method uses an error code provided by the HDF.
if(ret!=HDF_SUCCESS){
HDF_LOGE("init drvier is failed");
returnret;
}
returnHDF_SUCCESS;
}
```
### OSAL
The HDF OSAL shields the interface differences between OpenHarmony subsystems and provides unified OS interfaces, including memory management, threads, mutexes, spin locks, semaphores, timers, files, IRQ, time, atoms, firmware, and I/O operation modules.
#### [Rule] Use OS interfaces through the OSAL for drivers used across mini-, small-, and standard-system devices.
[Description] The OSAL shields the differences between OS interfaces. You should operate these OS interfaces based on the OSAL to ensure that drivers can run on different types of systems.
The HDF PAL abstracts platform drivers and provides unified operation interfaces for modules such as the GPIO, I2C, SPI, UART, RTC, SDIO, eMMC, DSI, PWM, and watchdog.
#### [Rule] Use platform drivers across mini, small, and standard systems through the PAL.
[Description] The PAL masks the differences between platform driver interfaces of different system types. You should operate these interfaces based on PAL to ensure that drivers can run on different types of systems.
