同步操作将从 Huawei LiteOS/LiteOS 强制同步,此操作会覆盖自 Fork 仓库以来所做的任何修改,且无法恢复!!!
确定后同步将在后台操作,完成时将刷新页面,请耐心等待。
建议将工程按照功能模块划分子目录(可参考LiteOS的功能模块划分),子目录再定义头文件和源文件目录。
类型 | 命名风格 | 形式 |
---|---|---|
函数,自定义的类型 | 大驼峰,或带有模块前缀的大驼峰 | AaaBbb, XXX_AaaBbb |
局部变量,函数参数,宏参数,结构体成员,联合体成员 | 小驼峰 | aaaBbb |
全局变量 | 带'g_'前缀的小驼峰 | g_aaaBbb |
宏,枚举值 | 全大写并下划线分割 | AAA_BBB |
内核头文件中防止重复包含的宏变量 | 带'_LOS'前缀和'H'后缀,中间为大写模块名,以下划线分割 | _LOS_MODULE_H |
LOS_TaskCreate
LOS_SwtmrStart
LOS_SemPend
OsTaskScan
OsSwtmrStart
struct MyType { // 左大括号跟随语句放行末,前置1个空格
...
}; // 右大括号后面紧跟分号
int Foo(int a)
{ // 函数左大括号独占一行,放行首
if (a > 0) { // 左大括号跟随语句放行末,前置1个空格
...
} else { // 右大括号、"else"、以及后续的左大括号均在同一行
...
} // 右大括号独占一行
...
}
if (objectIsNotExist) { // 单行条件语句也加大括号
return CreateNewObject();
}
while (condition) {} // 即使循环体是空,也应使用大括号
while (condition) {
continue; // continue表示空逻辑,使用大括号
}
switch (var) {
case 0: // 缩进一层
DoSomething1(); // 缩进一层
break;
case 1:
DoSomething2();
break;
default:
break;
}
// 假设下面第一行不满足行宽要求
if (currentValue > MIN && // 换行后,布尔操作符放在行末
currentValue < MAX) { // 与(&&)操作符的两个操作数同类对齐
DoSomething();
...
}
// 假设下面的函数调用不满足行宽要求,需要换行
ReturnType result = FunctionName(paramName1,
paramName2,
paramName3); // 保持与上方参数对齐
ReturnType result = VeryVeryVeryLongFunctionName( // 写入第1个参数后导致过长,直接换行
paramName1, paramName2, paramName3); // 换行后,4空格缩进一层
// 每行的参数代表一组相关性较强的数据结构,放在一行便于理解,此时可理解性优先于格式排版要求
int result = DealWithStructLikeParams(left.x, left.y, // 表示一组相关参数
right.x, right.y); // 表示另外一组相关参数
int *p1; // Good:右跟随变量,和左边的类型隔了1个空格
int* p2; // Bad:左跟随类型
int*p3; // Bad:两边都没空格
int * p4; // Bad:两边都有空格
char * const VERSION = "V100"; // Good:当有const修饰符时,"*"两边都有空格
int Foo(const char * restrict p); // Good:当有restrict修饰符时,"*"两边都有空格
#if defined(__x86_64__) && defined(__GCC_HAVE_SYNC_COMPARE_AND_SWAP_16) // 位于行首,不缩进
#define ATOMIC_X86_HAS_CMPXCHG16B 1 // 缩进一层,区分层次,便于阅读
#else
#define ATOMIC_X86_HAS_CMPXCHG16B 0
#endif
注释的内容要清楚、明了,含义准确,防止注释二义性。
在代码的功能、意图层次上进行注释,即注释解释代码难以直接表达的意图,而不是仅仅重复描述代码。
函数声明处注释描述函数功能、性能及用法,包括输入和输出参数、函数返回值、可重入的要求等;定义处详细描述函数功能和实现要点,如实现的简要步骤、实现的理由、设计约束等。
全局变量要有较详细的注释,包括对其功能、取值范围以及存取时注意事项等的说明。
避免在注释中使用缩写,除非是业界通用或子系统内标准化的缩写。
文件头部要进行注释,建议注释列出:版权说明、版本号、生成日期、作者姓名、功能说明、与其它文件的关系、修改日志等。
注释风格要统一,建议优先选择/* */的方式,注释符与注释内容之间要有1空格,单行、多行注释风格如下:
/* 单行注释 */
/*
* 多行注释
* 第二行
*/
注释应放在其代码上方或右方。
上方的注释,与代码行之间无空行,保持与代码一样的缩进。 右边的注释,与代码之间至少相隔1个空格。如果有多条右置注释,上下对齐会更加美观,比如:
#define A_CONST 100 // 此处两行注释属于同类
#define ANOTHER_CONST 200 // 可保持左侧对齐
#ifdef LOSCFG_XXX
...
#endif
#define SUM(a, b) a + b // 不符合本条要求
#define SUM(a, b) ((a) + (b)) // 符合本条要求
#define SOME_CONST 100 // 单独的数字无需括号
#define ANOTHER_CONST (-1) // 负数需要使用括号
#define THE_CONST SOME_CONST // 单独的标识符无需括号
#define FOO(x) do { \
(void)printf("arg is %d\n", (x)); \
DoSomething((x)); \
} while (0)
#ifndef _LOS_<MODULE>_H // 比如 _LOS_TASK_H
#define _LOS_<MODULE>_H
...
#endif
基础类型定义统一使用los_typedef.h中定义的类型,比如定义无符号32位整型变量使用UINT32。
int *Func(void)
{
int localVar = 0;
...
return &localVar; // 错误
}
void Caller(void)
{
int *p = Func();
...
int x = *p; // 程序产生未定义行为
}
int Func(void)
{
int localVar = 0;
...
return localVar;
}
void Caller(void)
{
int x = Func();
...
}
// 私有头文件中引入全局变量,但要避免直接使用
extern LosMuxCB *g_allMux;
// 通过GET_MUX的方式对g_allMux进行访问
#define GET_MUX(muxID) (((LosMuxCB *)g_allMux) + GET_MUX_INDEX(muxID))
不使用与硬件或操作系统关系很大的语句,而使用建议的标准语句,以提高软件的可移植性和可重用性。
C语言编程规范参考资料较多,大家可以自行了解,本文不再过多赘述。
Huawei LiteOS(以下简称LiteOS)欢迎开发者参与到开源社区的贡献中来,本文主要介绍参与LiteOS文档贡献的写作规范,如果贡献者提交文档的修改或提交新的文档,请参照此规范。
如需提交新的文档,在LiteOS代码仓doc目录下创建新的.md文件,命名需遵循 xxx_xxx.md 格式,根据文档的内容来声明。
比如介绍写作规范的文档,可以命名为 LiteOS_doc_write_standard.md。
以简洁、直观地表达所述内容为目的,介绍性文档言简意赅介绍原理、架构、设计思路等,操作类文档写明关键步骤,以便能对其他开发者起到帮助。可以优先使用中文,建议中英文都支持,LiteOS也将持续更新,保证中英文的同步。
标题
建议标题层级不超过三级。
正文
操作类文档以移植为例,文档结构可以参考如下:
介绍性文档以开发指南某一功能为例,文档结构可以参考如下:
图片
图片统一存放到文档同级目录下的figures文件夹中(英文文档对应figures-en),如 LiteOS/doc/quick_start/LiteOS_doc_write_standard.md 中使用的图片,统一放置到 LiteOS/doc/quick_start/figures 目录下,文档中使用相对路径引用图片。图片建议根据内容命名,只用数字序列不利于后续图片的继承。
说明: 引用方式: ![](./figures/figures-standard.png)
如果是自制图片,配色请参考如下,格式不限,png/jpg/gif...均可,如果是截图或者其他地方引用图片,风格不做限制。
表格
在md文件中可以按照如下形式插入表格。
| Tables | Type | Note |
| ----------- |:-------------:| -----:|
| first | standard | None |
| second | outstanding | 5 |
| third | inside | with |
代码
正文中插入代码段,可以在段落前后加上符号 ```。
```cint size = 10;
```
目前,社区有多种 Commit message 的写法规范。LiteOS采用的是Angular规范,这是目前使用最广的写法,比较合理和系统化,并且有配套的工具。
格式化的Commit message有几个好处:
每次提交,Commit message 都包括三个部分:Header,Body 和 Footer。
<header>
空一行
<body>
空一行
<footer>
比如:
fix(stm32f411): fix stm32f411 migration guide file error
fix some error in stm32f411re migration guide file.
Close #75
Header格式
Header部分只有一行,格式为:
<type>(<scope>): <subject>
Header部分共包括三个字段:type(必需)、scope(可选)和subject(必需)。
type
type用于说明 commit 的类别,只允许使用下面7个标识。
feat:feature的缩写,表示这是一个新功能
fix:修补bug
docs:documentation的缩写,表示修改的是文档
style: 格式修改,是不影响代码运行的变动
refactor:重构,它即不是新增功能,也不是修改bug
test:增加测试
chore:构建过程或辅助工具的变动
scope
scope用于说明 commit 影响的范围,比如对LiteOS Kernel的base的修改会影响全部代码,所以填写all。如果只修改STM32F411的代码,则填写STM32F411。
subject
subject用于简短描述 commit 目的,不超过50个字符。subject以动词开头,使用第一人称现在时,比如change,而不是changed或changes。subject的第一个字母小写,结尾不加英文句号(.)。
Body格式
Body 部分是对本次 commit 的详细描述,可以分成多行,下面是一个范例。
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
有两个注意点:
Footer格式
Footer 部分只用于两种情况。
不兼容变动
如果当前代码与上一个版本不兼容,则 Footer 部分以BREAKING CHANGE开头,后面是对变动的描述、以及变动理由和迁移方法。
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.
关闭 Issue
如果当前 commit 针对某个issue,那么可以在 Footer 部分关闭这个 issue 。
Closes #16, #24, #92
更详细的commit规则请参考原始的规范说明:Angular规范。
LiteOS的代码仓托管在gitee上,因此代码贡献者需要在gitee上注册账号才能贡献代码。注册账号可以参考注册Gitee账号。
代码贡献可以分为在线修改和本地提交两种。
在线修改适用于修改量较少的情况,方便快捷,点击页面“编辑”按钮,跳转到对应的编辑页面。
编辑修改后,点击页面下方“提交”按钮,即提交修改到 LiteOS 工程,静候工作人员审核即可。
本地提交适用于修改量较大的情况,主要说明如何参与LiteOS开源代码贡献。进行LiteOS的代码贡献可以遵循以下流程:
1) 先查看本地是否有公钥。如果存在公钥,则返回类似如下显示的一对文件,一般文件名为 id_rsa 和 id_rsa.pub,其中 .pub 后缀的文件是公钥,另一个文件是密钥。
$ ls ~/.ssh
id_rsa id_rsa.pub
如果系统内没有公钥文件,可以执行如下命令生成,公钥文件一般默认存放在 ~/.ssh路径下:
$ ssh-keygen -t rsa -C "your-email@youremail.com" //其中的邮箱为注册gitee账户时使用的邮箱
2) 配置gitee账户的SSH公钥,参考gitee上SSH公钥设置。
账户信息即用户名和邮箱,注意此处的用户名和邮箱指的是注册gitee账户所使用的账户名和邮箱。配置以后,每次Git提交都会使用该信息:
$ git config --global user.name "your-username"
$ git config --global user.email "your-email@youremail.com"
如果本地pc上已经存储了账户信息,可以在“控制面板->用户帐户->凭据管理器”中确认保存的gitee账号密码是否正确,如果错误会导致无法提交修改到远程仓库。如果无法在本地pc上确认或修改为正确的账号信息,可以执行如下命令,不使用本地pc中保存的账号密码:
$ git config --global --unset credential.helper
查看git的所有配置信息,可以使用如下命令:
$ git config --list
1) 使用个人gitee账号登陆gitee。
2) 进入LiteOS官方主仓库(master分支):LiteOS源码仓。
3) 点击右上角fork按钮,将LiteOS的代码fork到个人账号下,在弹出的窗口中选择要fork到的个人账号,点击确认后,稍等一会就会自动跳转到刚刚fork出来的个人账号下的LiteOS仓库。
开发代码前,首先需要确保当前个人账号下的LiteOS代码和LiteOS官方仓库是一致的。 因为从fork代码到现在,LiteOS官方仓库可能已经更新了内容,所以开发代码前需要先同步LiteOS仓库代码到fork的仓库。如果仓库刚刚fork,可以跳过此步。
点击上图中红框中的按钮从LiteOS官方仓库拉取代码到个人账号fork的仓库,此时会弹出一个对话框以确定同步动作,如下图所示:
点击确定后,gitee就会开始同步代码,用户无需再做其他操作。
1) 开发的第一步,是clone代码到本地pc。
git clone https://gitee.com/gitee账户名/LiteOS.git //个人账号fork的仓库地址,clone下来后仓库名默认为origin
基于LiteOS的远程master分支,创建并切换到本地分支,例如本地分支名也是master:
git checkout -b master origin/master
2) 在本地分支上进行开发。开发完成之后,git add 添加代码到本地仓库,并git commit 提交到本地仓库,具体commit信息的填写规范,请参考Commit message规范。
3) 执行git push origin master操作,将代码提交到gitee上自己个人账号的master分支。
说明: 所有git命令相关操作,如果不熟悉,请自行上网查找。
通过上述步骤,修改已经提交到个人远程仓库中,此时就可以向LiteOS官方主仓库master分支提交Pull Request,该操作在gitee网页上进行。
1) 进入个人账号下fork的LiteOS仓库首页,点击下图红框中的“+ Pull Request”。
2) 之后gitee会跳转到创建Pull Request的详细页面,并给出对应的源分支和要修改的目标分支,目标分支为LiteOS官方主仓库master分支,如下图。
如果代码没有冲突则会显示下图红框中“可自动合并”的提示,否则需要先解决冲突然后再重新创建Pull Request。在线解决代码冲突可以参考在线解决代码冲突。
填入Pull Request的标题和说明,点击“创建”,就可以提交一个Pull Request。右边的审查人员、测试人员、里程碑、标签、优先级是可选项,不选择也不影响Pull Request的创建。
说明: >- 如果提交的代码是为了解决issue问题,记得将issue和此次代码提交相关联,关联方法请参考Commit关联Issue和Pull Request关联Issue。 >- 如果提交的Pull Request中有新增意见,需要在评论里回复,并@提意见的人说明已经解决。
1) 进入LiteOS主仓库首页。
2) 点击下图中的“Pull Requests”,可以看到当前LiteOS主仓库上所有的Pull Request。
“开启的”表示这个Pull Request的代码还没有合入,“已合并”表示这个Pull Request的代码已经合入,“已关闭”表示这个Pull Request虽然已经关闭但是代码没有被合入。
现在就静候LiteOS主仓库管理员review代码吧,验证ok就会合入修改,恭喜您成为Contributor,感谢您为开源社区做出的贡献。
您可以自由地:
分享 — 在任何媒介以任何形式复制、发行本文档。
演绎 — 修改、转换或以本文档为基础进行创作。
只要你遵守许可协议条款,许可人就无法收回你的这些权利。
惟须遵守下列条件:
署名 — 您必须提供适当的证书,提供一个链接到许可证,并指示是否作出更改。您可以以任何合理的方式这样做,但不是以任何方式表明,许可方赞同您或您的使用。
非商业性使用 — 您不得将本文档用于商业目的。
相同方式共享 — 如果您的修改、转换,或以本文档为基础进行创作,仅得依本素材的授权条款来散布您的贡献作品。
没有附加限制 — 您不能增设法律条款或科技措施,来限制别人依授权条款本已许可的作为。
声明:
当您使用本素材中属于公众领域的元素,或当法律有例外或限制条款允许您的使用,则您不需要遵守本授权条款。
未提供保证。本授权条款未必能完全提供您预期用途所需要的所有许可。例如:形象权、隐私权、著作人格权等其他权利,可能限制您如何使用本素材。
须知: 为了方便用户理解,这是协议的概述。您可以访问网址https://creativecommons.org/licenses/by-nc-sa/3.0/legalcode了解完整协议内容。
定义
1.1 关联公司: 是指就一个实体而言,该实体直接或间接控制的另一实体,或者,直接或间接控制该实体的另一实体,或者与该实体被某一实体共同控制的其他实体;这里的“控制”是指直接或间接拥有一个实体中多于50%份额的投票权或表决权或者以任何其他方式直接或间接控制该实体50%以上的具有该实体决策权的所有者权益。
1.2 遵从软件: 是指由华为技术有限公司(后称“华为”)正式发布且未经过修改的Huawei LiteOS,或者虽经修改,但能通过认证测试的Huawei LiteOS。
1.3 认证测试: 是指为了确保Huawei LiteOS与其一起使用的软件或硬件的兼容性和接口一致性而由华为开发的测试。认证测试套件及相关要求和指导将在Huawei LiteOS官网公布。
1.4 贡献: 是指由任何人提交给Huawei LiteOS将其纳入或建议纳入Huawei LiteOS中的任何信息或资料,包括软件源代码,文档或相关材料。
1.5 贡献者: 是指提交贡献给Huawei LiteOS的人。
1.6 您: 是指任何个人,公司,合作企业,共同控股公司,有限合伙,协会,有限责任公司或企业或实体。
1.7 Huawei LiteOS: 是指由华为主导开发、管理、并由华为在Huawei LiteOS官网上发布的可用于芯片,网关,智能家居,物联网领域的轻量开源操作系统项目。华为可能会对该软件不断进行更新。
1.8 承诺的专利权利要求: 是指专利或专利申请的一个或多个权利要求,且满足如下条件:(i)由贡献者或其关联公司现在或将来拥有控制的,或其他有权许可且无需向无关联的第三方支付费用的,且(ii)会因接受者制造,使用,许诺销售,销售,进口或以其他方式转移贡献者提交给Huawei LiteOS的贡献单独或将该贡献与前述Huawei LiteOS的结合所必然且直接侵犯。
1.9 政策: 是指本Huawei LiteOS知识产权政策。
1.10 接收者: 是指接受本政策并享有本政策下许可的个人或法律实体。
1.11 承诺者: 是指贡献者及其关联公司。
许可
Huawei LiteOS的代码将以BSD 3-Clause License,除非华为另选其他许可证 (“可适用的许可证”)。接收者可以访问 http://opensource.org/licenses/BSD-3-Clause查看该许可证的详细内容。
专利不诉承诺
3.1 在接收者遵守本政策的前提下,每个承诺者许诺不对任何接收者就其制造,使用,许诺销售,销售,进口或以其他方式转移遵从软件的行为发起指控,诉讼或其他法律程序指控其侵犯该承诺者的承诺专利权利主张。前述承诺不适用于因以下原因引起的侵犯承诺专利权利主张的指控:i. 由其他方提交的贡献;ii 承诺者贡献代码后其他人对该贡献的修改;iii 该贡献与硬件的结合或者与不属于贡献所针对的Huawei LiteOS的其他代码的结合;或者 iv 不属于遵从软件的软件。前述承诺也不适用于集成在个人便携产品(如手机,便携电脑,可穿戴设备等)中的遵从软件。
3.2 这是每个承诺者对接收者的个人承诺。
3.3 每个承诺者理解并同意专利不诉承诺是具有法律约束力且不可撤回的(根据第4条撤回的除外),而且对该承诺者、其继受者、受让方以及有权对第三方实施该承诺专利主张的任何独占被许可人都是有约束力的。
终止许可及专利不诉承诺的权利
在满足可适用许可证规定的前提下,如果贡献者或其关联公司向其他基于第3条享有专利不诉承诺权益且未根据本条终止的接收者发起指控,诉讼或其他法律程序,指控其制造,使用,许诺销售,销售,进口或者以其他形式转移遵从软件构成对其专利直接侵权或帮助侵权的,那么该接收者及其关联公司本政策下所有的许可以及专利不诉承诺将立即终止。
无其他权利
5.1 本政策并不授予接收者使用华为的贸易名称,商标,服务标记或产品名称的许可。
5.2 除本政策和可使用许可证明确约定外,没有其他明示或默示的专利,商标,版权或其他知识产权的许可授予接收者,不论是通过默示,放弃,禁止反言或其他形式。
无担保
除非适用法强制规定或者双方有明确书面约定, Huawei LiteOS, 遵从软件以及任何贡献均如是提供,无任何形式的担保,不论是明示还是默示,包括但不限于不侵权,适销性或满足特定目的的担保。
责任限制
除非适用法强制规定,在任何情况下,不论是基于侵权,合同或其他,华为及其关联公司或任何贡献者均不对其他贡献者,接收者或第三方因本政策或因使用或未能使用华为发布的Huawei LiteOS或者对Huawei LiteOS的任何贡献导致的损失,包括任何直接的,间接的,特别的,偶然的损失或者数据丢失等,即使该方已经被建议该种可能的损失。
可分离性
如果本政策内的任何条款被认定为无效,不可实施或者与适用法冲突,本政策中的其他条款继续有效。
修改
华为有权自行决定修改本政策。该修改后的政策从其在Huawei LiteOS官网上公布之日起生效,并仅适用于同时或此后发布的Huawei LiteOS软件版本。
适用法和争议解决
本政策适用中华人民共和国法律。任何因本政策引起或与本政策相关的纠纷应提交到北京中国国际经济贸易仲裁委员会。该仲裁裁决是终局的并对仲裁双方具有法律约束力。
技术支持
欢迎提交issue对关心的问题发起讨论,欢迎到LiteOS论坛交流。 您也可以发送问题至邮箱LiteOSSupport@huawei.com。
参与贡献
如您有兴趣参与开源贡献,欢迎提交PR参与特性建设,可至LiteOS gitee源码仓或者LiteOS github源码仓下载开源代码。
技术合作
如您有合作意向,希望加入Huawei LiteOS生态合作伙伴,请发邮件至LiteOSSupport@huawei.com,或访问LiteOS官网,进一步了解详细信息。
此处可能存在不合适展示的内容,页面不予展示。您可通过相关编辑功能自查并修改。
如您确认内容无涉及 不当用语 / 纯广告导流 / 暴力 / 低俗色情 / 侵权 / 盗版 / 虚假 / 无价值内容或违法国家有关法律法规的内容,可点击提交进行申诉,我们将尽快为您处理。