CamelCase is the practice of writing compound words or phrases so that each word or abbreviation in the phrase begins with a capital letter, with no intervening spaces or punctuation.
Type | Naming Style | Format |
---|---|---|
Functions and customized types | UpperCamelCase with or without a module prefix | AaaBbb, XXX_AaaBbb |
Local variables, function parameters, macro parameters, structure members, and union members | lowerCamelCase | aaaBbb |
Global variables | lowerCamelCase with the prefix 'g_' | g_aaaBbb |
Macros, enumerated values | All-capitalized words separated by underscores (_) | AAA_BBB |
Macro variables that prevent duplicate kernel header files | All-capitalized module name with the prefix '_LOS' and suffix 'H', separated by underscores (_) | _LOS_MODULE_H |
Names of global functions, global variables, macros, types, and enumerations shall be accurate and globally unique.
Names of local variables or structure or union member variables should be as short as possible on the premise that related meanings can be accurately expressed.
External LiteOS APIs are in the LOS_<Module><Func> format. For example:
LOS_TaskCreate
LOS_SwtmrStart
LOS_SemPend
APIs between internal modules in the kernel directory are in the Os<Module><Func> format. For example:
OsTaskScan
OsSwtmrStart
Low-level APIs provided by the arch directory for upper-layer modules are in the Arch<Module><Func> format. In other cases, <Module><Func> can be used.
struct MyType { // The left brace is placed at the end of the statement, with a space left between them.
...
}; // The right brace is followed by a semicolon (;).
int Foo(int a)
{ // The left brace of the function starts a new line and exclusively occupies the line.
if (a > 0) { // The left brace is placed at the end of the statement, with a space left between them.
...
} else { // The right brace, "else", and subsequent left brace are in the same line.
...
} // The right brace exclusively occupies the line.
...
}
if (objectIsNotExist) { // Braces are added to a single-line conditional statement.
return CreateNewObject();
}
while (condition) {} // Braces are used even if the loop body is empty.
while (condition) {
continue; // Braces are used even if the continue indicates the empty logic.
}
switch (var) {
case 0: // The statement is indented by one level.
DoSomething1(); // The statement is indented by two levels.
break;
case 1:
DoSomething2();
break;
default:
break;
}
// Assume that the first line exceeds the length limit.
if (currentValue > MIN && // After the line break, the Boolean operator is placed at the end of the line.
currentValue < MAX) { // The new line is aligned with the two operands of the (&&) operator.
DoSomething();
...
}
// Assume that the line for function calling exceeds the length limit.
ReturnType result = FunctionName(paramName1,
paramName2,
paramName3); // Parameters are aligned with the preceding parameters.
ReturnType result = VeryVeryVeryLongFunctionName( // The first parameter is too long, resulting in a line break.
paramName1, paramName2, paramName3); // The line is indented with four spaces.
// If parameters represent a group of data structures with a strong correlation, they are placed in one line for ease of understanding. In this case, the understandability takes precedence over the formatting and typesetting requirements.
int result = DealWithStructLikeParams(left.x, left.y, // A group of related parameters.
right.x, right.y); // Another group of related parameters.
int *p1; // Good example: The pointer type "*" follows a variable on its right-hand side, and leaves a space between itself and the type on its left-hand side.
int* p2; // Bad example: The pointer type "*" follows the type on its left-hand side.
int*p3; // Bad example: The pointer type "*" leaves spaces on neither sides.
int * p4; // Bad example: The pointer type "*" leaves spaces on both sides.
char * const VERSION = "V100"; // Good example: When the const modifier exists, the pointer type "*" leaves spaces on both sides.
int Foo(const char * restrict p); // Good example: When the restrict modifier exists, the pointer type "*" leaves spaces on both sides.
#if defined(__x86_64__) && defined(__GCC_HAVE_SYNC_COMPARE_AND_SWAP_16) // The number sign (#) is at the beginning of the line which is not indented.
#define ATOMIC_X86_HAS_CMPXCHG16B 1 // The line is indented by one level to facilitate reading.
#else
#define ATOMIC_X86_HAS_CMPXCHG16B 0
#endif
Comments must be clear, accurate, and non-ambiguous.
Comments are used to express the function and intention of code, rather than repeating the code.
Comments in the function declaration describe the function, performance, and usage, including the input and output parameters, return values, and reentering requirements. Comments in the function definition detail the function and implementation points, such as the procedure, reason, and design constraints.
Detailed comments must be provided for global variables, including the function, value range, and access precautions.
Abbreviations should be avoided in comments unless they are commonly used in the industry or are standardized in subsystems.
Comments must be added to the file header. It is recommended that the comments contain the following information: copyright description, version number, generation date, author name, function description, relationship with other files, and modification log.
The comment style must be unified. The /* */ format is recommended. There must be a space between the comment character and the content. The comment styles of a single line and multiple lines are as follows:
/* Single-line comment */
/*
* Multi-line comment
* Second line
*/
Comments should be placed above or to the right of the code.
There is no blank line between the comment line and the code line. Indentations of the two lines are the same. There must be at least one space between the code and the comment on the right. It is more appealing sometimes when multiple comments placed on the right are aligned vertically. For example:
#define A_CONST 100 // The two comment lines are of the same type.
#define ANOTHER_CONST 200 // The lines are left-aligned.
#ifdef LOSCFG_XXX
...
#endif
#define SUM(a, b) a + b // Unqualified.
#define SUM(a, b) ((a) + (b)) // Qualified.
#define SOME_CONST 100 // Parentheses are not required for a single number.
#define ANOTHER_CONST (-1) // Parentheses are required for negative numbers.
#define THE_CONST SOME_CONST // Parentheses are not required for a single identifier.
#define FOO(x) do { \
(void)printf("arg is %d\n", (x)); \
DoSomething((x)); \
} while (0)
The responsibility of a header file should be simple.
It is recommended that all .c files in a module be stored in one directory whose name is the module name. If a module contains multiple sub-modules, it is recommended that each sub-module provide an external .h file whose name is the sub-module name.
It is recommended that each .c file have a .h file with the same name, which is used to declare the APIs that need to be exposed externally.
The header file is suitable for placing API declarations instead of implementations.
Variables cannot be defined in the header file.
Cyclic dependency of header files is forbidden. Cyclic dependency means that a.h contains b.h, b.h contains c.h, and c.h contains a.h.
Header files should be self-contained. That is, any header file can be compiled independently. In addition, unnecessary header files should not be included.
Header files must have #define guards to prevent multiple inclusions. For example, the following macro definition guards are used in the kernel:
#ifndef _LOS_<MODULE>_H // For example, _LOS_TASK_H
#define _LOS_<MODULE>_H
...
#endif
External function APIs or variables cannot be referenced in declaration. APIs provided by other modules or files can be used only by including header files.
Header files cannot be included in extern "C".
Header files are included in a reasonable sequence:
1) Header file corresponding to the source file
2) C standard library
3) Other OS header files to be included
int *Func(void)
{
int localVar = 0;
...
return &localVar; // Bad example
}
void Caller(void)
{
int *p = Func();
...
int x = *p; // The program generates undefined behavior.
}
int Func(void)
{
int localVar = 0;
...
return localVar;
}
void Caller(void)
{
int x = Func();
...
}
// Introduce global variables in the private header file. Do not use them directly.
extern LosMuxCB *g_allMux;
// Access g_allMux in GET_MUX mode.
#define GET_MUX(muxID) (((LosMuxCB *)g_allMux) + GET_MUX_INDEX(muxID))
Do not use statements that are closely related to hardware or operating systems. Instead, use recommended standard statements to improve software portability and reusability.
Huawei LiteOS (hereinafter referred to as "LiteOS") welcomes developers to contribute to the open-source community. If contributors want to commit document changes or new documents, please refer to the following specifications.
To commit a new document, create the .md file under the doc directory of the LiteOS code on Gitee. The file name must be in the xxx_xxx.md format.
For example, a document that describes writing specifications can be named LiteOS_doc_write_standard.md.
The content should be concise and intuitive. Introductory documents describe principles, architecture, and design ideas in a concise manner, and operation documents describe key steps to help other developers. Chinese is preferred. It is recommended that both Chinese and English be supported. LiteOS will be updated continuously to ensure the synchronization between Chinese and English.
Title
It is recommended that the title have no more than three levels.
Body
Operation documents: Porting is used as an example to show the document structure.
Introductory documents: A feature in a development guide is used as an example to show the document structure.
Images
Images are stored in the figures-en folder in the directory where the document is stored. For example, images used in LiteOS/doc/quick_start/LiteOS_doc_write_standard.md are stored in LiteOS/doc/quick_start/figures-en, and relative paths are used to reference images in the document. It is recommended that images be named based on the content. Using only a number is difficult for image inheritance.
NOTE: Reference: ![](./figures/figures-standard.png)
If a self-made image is used, refer to the following figure to configure the color. The format can be .png, .jpg, .gif, and so on. If a screenshot or an image referenced in other places is used, there is no restriction on the style.
Table
You can insert a table in the .md file in the following format:
| Tables | Type | Note |
| ----------- |:-------------:| -----:|
| first | standard | None |
| second | outstanding | 5 |
| third | inside | with |
Code
To insert a code segment in the body, add ``` before and after the code segment. The following uses the C language as an example:
```cint size = 10;
```
There are multiple commit message rules. LiteOS uses the Angular specification, which is the most widely used format. It is reasonable and systematic, and has matching tools.
A formatted commit message has the following advantages:
Each commit message contains three parts: header, body, and footer.
<header>
Blank line
<body>
Blank line
<footer>
For example:
fix(stm32f411): fix stm32f411 migration guide file error
fix some error in stm32f411re migration guide file.
Close #75
Header Format
A header contains only one line and its format is as follows:
<type>(<scope>): <subject>
A header consists of three fields: type (mandatory), scope (optional), and subject (mandatory).
type
type indicates the commit type. Only the following seven identifiers are allowed:
feat: short for feature, indicating a new function
fix: bug fixing
docs: short for documentation, indicating document changes
style: format changes without affecting code running
refactor: refactoring (neither function adding nor bug fixing)
test: new testing
chore: changes to build processes or tools
scope
scope indicates the scope affected by the commit operation. For example, if the base modification of the LiteOS kernel affects all code, set scope to all. If only stm32f411 is modified, set scope to stm32f411.
subject
subject provides a short description of the commit purpose, which contains a maximum of 50 characters. subject starts with a verb and use the first-person present tense. For example, use change instead of changed or changes. The first letter of subject is in lowercase, and no period (.) is added at the end.
Body Format
A body describes the commit operation in detail. Multiple lines can be used.
Add porting contest board projects to LiteOS
Board list:
Arduino-M0-PRO
ATSAM4S-XPRO
ATSAMD21-XPRO
EFM32-SLSTK3400A
EFM32-SLSTK3401A
EFM32-STK3700
FRDM-KL26Z
FRDM-KW41Z
Note:
Use the first-person present tense. For example, use change instead of changed or changes.
Explain the motivation of code changes and the comparison with previous behavior.
Footer Format
A footer is used only in the following two scenarios:
Incompatible changes
If the current code is incompatible with the previous version, the footer starts with BREAKING CHANGE, followed by the change, change reason, and migration method.
BREAKING CHANGE: isolate scope bindings definition has changed.
To migrate the code follow the example below:
Before:
scope: {
myAttr: 'attribute',
}
After:
scope: {
myAttr: '@',
}
The removed `inject` wasn't generaly useful for directives so there should be no code using it.
Close Issue
If the current commit operation is performed for an issue, you can close the issue in the footer.
Closes #16, #24, #92
For more details on commit message rules, see the original specifications: Angular specification.
LiteOS code repository is hosted on Gitee. Therefore, a code contributor needs to register an account with Gitee to contribute code. For details about how to register an account, see Registering a Gitee Account.
Code contributions can be classified into online changes and local committing.
Online changes are applicable to scenarios with a small number of changes. You can click Edit to go to the editing page.
After editing, click Commit at the bottom of the page to commit changes to the LiteOS project and then wait for the review.
The LiteOS code contribution process is as follows:
Download Git from the official website. For details about how to install it, see the Installation Guide.
1) Check whether there is a local public key. If the public key exists, a pair of files similar to the following is returned. Generally, the file names are id_rsa (key) and id_rsa.pub (public key).
$ ls ~/.ssh
id_rsa id_rsa.pub
If no public key file is available in the system, run the following command to generate one. The public key file is stored in the ~/.ssh directory by default.
$ ssh-keygen -t rsa -C "your-email@youremail.com" // The email address is the one used for registering the Gitee account.
2) Configure the SSH public key for the Gitee account. For details, see the SSH Public Key Settings.
The account information includes a username and an email address used for registering the Gitee account. The configured information is used for each Git committing.
$ git config --global user.name "your-username"
$ git config --global user.email "your-email@youremail.com"
If the account information has been stored on a local PC, choose Control Panel > User Accounts > Credential Manager to check whether the Gitee account password is correct. If it is incorrect, the code changes cannot be committed to a remote repository. If you cannot confirm or correct the account information on the local PC, run the following command to disable the local account and password:
$ git config --global --unset credential.helper
To view all Git configurations, run the following command:
$ git config --list
1) Log in to Gitee using your personal Gitee account.
2) Go to the official LiteOS main repository (master branch): LiteOS source code repository.
3) Click Fork in the upper right corner to fork the LiteOS code to your account. In the dialog box that is displayed, select a personal account and click OK. Wait for a while. The LiteOS repository forked to your account is automatically displayed.
Before developing code, ensure that the LiteOS code in your account is consistent with that in the official LiteOS repository. The official LiteOS repository may have been updated since the last code forking, so you need to synchronize the LiteOS repository code to the forked repository before code development. If the repository has just been forked, skip this step.
Click the icon in the red box in the preceding figure to pull code from the official LiteOS repository to the forked repository in your account. A dialog box is displayed, as shown in the following figure.
After you click OK, Gitee starts to synchronize the code. You do not need to perform other operations.
1) Clone the code to the local PC.
git clone https://gitee.com/*Gitee account name*/LiteOS.git // Address of the forked repository in your account. The default repository name is **origin**.
Create a local branch based on the LiteOS remote master branch and switch to the local branch. In the following example, the local branch name is master.
git checkout -b master origin/master
2) Develop on your local branch. After the development is complete, run the git add and git commit commands to add and commit code, respectively, to the local repository. For details about the commit messages, see LiteOS Commit Message Rules.
3) Run the git push origin master command to commit the code to the master branch of your Gitee account.
Note: If you are unfamiliar with the git commands, search for references in the Internet.
After the preceding steps are performed, the changes have been committed to your remote repository. Then, you can commit a pull request to the master branch of the official LiteOS main repository on Gitee.
1) Go to the forked LiteOS repository page in your account and click + Pull Request as shown below.
2) On the displayed page, select the source branch and set target branch to the master branch of the official LiteOS main repository, as shown below.
If the code does not conflict, a message in green is displayed, indicating that the code can be automatically merged, as shown in the following figure. Otherwise, you need to resolve the conflict first. For details about how to resolve code conflicts online, see Resolving Code Conflicts Online.
Enter the title and description and click Create to commit a pull request. The reviewer, tester, milestone, tag, and priority on the right of the page are optional for creating a pull request.
NOTE:
- If the committed code is used to resolve an issue, link the issue to the code. For details, see Linking a Commit to an Issue and Linking a Pull Request to an Issue.
- If there is new comment in the committed pull request, reply to the comment and @ the person who leaves the comment to tell them that the issue is solved.
1) Go to the LiteOS main repository.
2) Click Pull Requests to display all pull requests in the LiteOS repository.
Open indicates that the code of the pull request is not merged. Merged indicates that the code has been merged. Closed indicates that the code is closed without being merged.
After the code changes are reviewed and approved by the LiteOS main repository administrator, they will be merged. Congratulations! You are a contributor now. Thank you for your contribution to the open-source community.
You are free to:
Share — copy and redistribute the material in any medium or format
Adapt — remix, transform, and build upon the material
The licensor cannot revoke these freedoms as long as you follow the license terms.
Under the following terms:
Attribution — You must give appropriate credit, provide a link to the license, and indicate if changes were made. You may include this attribution in any reasonable manner, but not in any way that suggests the licensor endorses you or your use.
NonCommercial — You may not use the material for commercial purposes.
ShareAlike — If you remix, transform, or build upon the material, you must distribute your contributions under the same license as the original.
No additional restrictions — You may not apply legal terms or technological measures that legally restrict others from doing anything the license permits.
Notices:
You do not have to comply with the license for elements of the material in the public domain or where your use is permitted by an applicable exception or limitation.
No warranties are given. The license may not give you all of the permissions necessary for your intended use. For example, other rights such as publicity, privacy, or moral rights may limit how you use the material.
NOTICE: This is a human-readable summary of (and not a substitute for) the license. Visit https://creativecommons.org/licenses/by-nc-sa/3.0/legalcode for the complete license.
Definitions
1.1 Affiliate: refers to, with respect to an entity, any other entity that directly or indirectly controls, is controlled by or is under common control with such entity, where "control" means the possession, direct or indirect, of the power to own or hold more than fifty percent (50%) of such entity, whether through ownership of voting rights or equity of owners with decision-making rights.
1.2 Compliance software: refers to Huawei LiteOS, which is officially released by Huawei Technologies Co., Ltd. (hereinafter referred to as "Huawei") and has not been modified, or Huawei LiteOS that has been modified but can pass the certification test.
1.3 Certification test: refers to the test developed by Huawei to ensure the compatibility and interface consistency of the software or hardware used together with Huawei LiteOS. The certification test suite and related requirements and guides will be released on the Huawei LiteOS official website.
1.4 Contribution: refers to any information or materials submitted by any person to Huawei LiteOS for inclusion or proposed inclusion, including software source code, documents, or related materials.
1.5 Contributor: refers to a person who makes contributions to Huawei LiteOS.
1.6 You: refers to any individual, company, enterprise, cooperative enterprises, joint holding company, limited partnership, association, limited liability company, or entity.
1.7 Huawei LiteOS: refers to a lightweight open-source operating system (OS) developed, managed, and subject to updates by Huawei. Released on the Huawei LiteOS official website, it can be used in chip, gateway, smart home, IoT, and other domains.
1.8 Patent claim: refers to one or more claims in a patent or patent application, which satisfy the following conditions: the claim (i) is now or will be controlled by the contributor or its affiliates, or parties entitled to license without payment to an unrelated third party, and (ii) is inevitably and directly infringed if the recipient makes, uses, offers to sell, sells, imports, or otherwise transfers the contribution submitted by the contributor to Huawei LiteOS alone, or combines the contribution with the aforementioned Huawei LiteOS.
1.9 Policy: refers to Huawei LiteOS IPR policy.
1.10 Recipient: refers to an individual or legal entity who accepts this Policy and is licensed under this Policy.
1.11 Committer: refers to contributors and their affiliates.
License Grant
Huawei LiteOS code is licensed under BSD 3-Clause License, unless another applicable license is selected by Huawei. Recipients can access http://opensource.org/licenses/BSD-3-Clause to view detailed license information.
Patent Non-prosecution Commitment
3.1 Subject to the recipient's compliance with this Policy, if the recipient makes, uses, offers to sell, sells, imports, or otherwise transfers the compliance software, the committer agrees not to allege, suit, or bring other legal proceedings against the recipient for infringing the patent claim of the committer. The aforementioned commitment shall not apply to an allegation of infringement of a patent claim arising out of: (i) contributions submitted by other parties; (ii) changes made by others to the code contributed by the committer; (iii) the contribution combined with hardware or Huawei LiteOS code that is not the target of the contribution; or (iv) non-compliance software. The aforementioned commitment does not apply to compliance software integrated into personal portable products (such as mobile phones, portable computers, and wearable devices).
3.2 This is the individual commitment of each committer to the recipient.
3.3 Each committer understands and agrees that the patent non-prosecution commitment is legally binding and irrevocable (except for those withdrawn under Article 4) and that it is directed to the committer, its successor, the transferee, and any exclusive licensee entitled to enforce the commitment's patent claim against a third party are binding.
License and Patent Non-prosecution Commitment Termination
Subject to the provisions of the applicable license, if a recipient who is entitled to the patent non-prosecution interest under article 3 but has not terminated the interest under this article, makes, uses, offers to sell, sells, imports, or otherwise transfers the compliance software and causes direct infringement or aids infringement of the patent, and the contributor or its affiliates allege, suit, or bring other proceedings against the recipient, all license and patent non-prosecution commitments under this Policy of the recipient and its affiliates shall be terminated immediately.
Other Rights
5.1 This Policy does not grant the recipient a license to use Huawei's trade names, trademarks, service marks, or product names.
5.2 No other express or implied patents, trademarks, copyrights or other intellectual property rights are granted to the recipients, whether by implication, waiver, estoppel or otherwise, except as expressly provided in this Policy and the License.
Warranty Terms
Unless otherwise specified by applicable laws or agreed by both parties in written form, Huawei LiteOS compliance software and any contributions are provided "AS IS" without warranties, express or implied, including but not limited to non-infringement, marketability, or warranties for specific purposes.
Limitation of Liability
Unless otherwise specified by applicable laws, Huawei and its affiliates or any contributors shall not be liable to any direct, indirect, special, or occasional loss or data loss caused by this Policy, or by using or not using Huawei LiteOS, even if contributors, recipients, or third parties have been advised of the possible loss.
Severability
To the extent that any provisions of this Policy are determined to be invalid, unenforceable, or in conflict with applicable laws, the other provisions of this Policy shall remain in force.
Changes
Huawei reserves the right to change this Policy at its sole discretion. The changed policy takes effect as of the date when it is published on the Huawei LiteOS official website, and applies only to Huawei LiteOS software versions that are released at the same time or later.
Governing Laws and Dispute Settlement
This Policy shall be governed by and construed in accordance with the laws of the People's Republic of China. Any dispute arising out of or in connection with this Policy shall be submitted to the China International Economic and Trade Arbitration Commission. The arbitration award shall be final and binding upon both Parties.
If you are interested in being Huawei LiteOS ecosystem partners, send an email to liteossupport@huawei.com to describe your product roadmap and cooperation requirements.
If you are interested in contributing to the open-source community, download the open-source code from Gitee or GitHub.
If you have any questions, feel free to visit the LiteOS forum or Huawei LiteOS official website for more details.
此处可能存在不合适展示的内容,页面不予展示。您可通过相关编辑功能自查并修改。
如您确认内容无涉及 不当用语 / 纯广告导流 / 暴力 / 低俗色情 / 侵权 / 盗版 / 虚假 / 无价值内容或违法国家有关法律法规的内容,可点击提交进行申诉,我们将尽快为您处理。