Skip to content

D
Docs

OpenHarmony / Docs
1 年多 前同步成功

通知 159
Star 292
Fork 28
D
Docs
提交 3fa8915b 编写于 作者: O openharmony_ci 提交者： Gitee
浏览文件
操作

!387 add kernel documentation contribution resources 

Merge pull request !387 from NEEN/master
上级 da68c8bc 90193740
隐藏空白更改
内联 并排
Showing with 724 addition and 0 deletion
zh-cn/device-dev/kernel-contribution/OpenHarmony内核文档共建ToDo-List.md 0 → 100644
浏览文件 @ 3fa8915b
# OpenHarmony文档共建计划--内核文档共建
| 2021-06-28-2021-07-30 | 2021-07-05 | 2021-07-05-2021-07-30 | 2021-08-01-2021-08-31 |
| --------------------------------- | -------------------------------- | -------------------------- | --------------------- |
| **任务招募** | **线上会议** | **文档共建** | **结项发布** |
| ToDo List、文档模板、共建手册大纲 | 文档共建介绍、写作规范、常见操作 | 小组周进展跟踪、导师辅导制 | 发布共建后内核文档 |
- [如何参与](#section_register)
- [文档共建范围](#section_outline_summary)
- [文档大纲及认领明细](section_outline_detail)
## 共建活动ToDoList
OpenHarmony文档共建活动是由OpenHarmony社区举办，旨在进一步丰富和完善现有文档，提升文档体验**，**更好地服务于广大开发者。本次文档共建活动有共建移植文档、内核文档、Qemu仿真文档。详情请参考共建手册大纲：《基于Qemu运行OpenHarmony》、 《小型系统三方芯片移植指南》、《OpenHarmony内核开发指南》。
即日起开发者可自主选择并认领感兴趣的任务，获得社区资深**技术导师**和**文档导师**的指导。根据项目的难易程度和完成情况，参与者还将获得"**OpenHarmony 文档共建贡献者** " 荣誉及周边纪念品。
1. **活动时间：** 2021-06-28~2021-07-30
2. **招募对象：**
- 技术写作者
- 文档验证/审核者
- 小组组织人员
3. **招募要求：**
- 熟悉嵌入式、物联网等OS开发相关知识
- 有扎实的C语言编程经验
- 有较强的文字写作能力、逻辑思维能力
4. **参与方式：**
- Gitee社区内认领任务反馈
- 开发者加入内核文档共建招募活动微信群
5. 共建激励规则
**卓越贡献奖**
- **奖励对象：**审核通过&内容被采纳的contributor。
- **奖励礼品：**OpenHarmonyT恤、帽子等周边纪念品。
## 如何参与<a name='section_register'></a>
- 方式1 [Issue回帖](https://gitee.com/openharmony/docs/issues/I3Y9MU?from=project-issue)
- 方式2 微信交流群报名
- 方式3 邮件反馈 @neeen @rtos_yuan ，邮件主题：OpenHarmony轻内核文档共建报名
3种方式均可报名，建议同时提供邮箱，方便后续发送线上会议交流通知。
## 文档共建范围 <a name='section_outline_summary'></a>
### 1、基于Qemu运行OpenHarmony---招募内容写作<a name='section_outline_qemu'></a>
- 背景
- 对于想体验OpenHarmony的开发者，手头不一定有现成的开发板，基于Qemu可以降低入门体验门槛。
- 已经支持Qemu，但是没有对应的文档, 快速入门只有3861、3516、3518等板子。
- 文档计划
LiteOS-A、LiteOS-M Qemu使用教程第一时间上社区，社区化运作文档，降低社区开发者体验OpenHarmony开发的门槛。
- **访问[《基于Qemu运行OpenHarmony 文档大纲》](#section_qemu_outline_detail)。**
### 2、小型系统三方芯片移植指南---招募内容体验&验证<a name='section_outline_porting'></a>
社区支持的开发板有限，三方芯片、开发板移植需要更丰富的开发板场景案例。
- 文档计划
- 鼓励开发者完善移植文档，支持社区开发者移植支持更多的开发板、支持手头的开发板能运行起来。
- 鼓励移植经验文档回馈社区。
- **访问[《小型系统三方芯片移植指南 文档大纲》](#porting_tutorial_outline_detail)。**
### 3、小型系统内核开发指南（LiteOS-A核）---招募内容体验&验证<a name='section_outline_kernel_tutorial'></a>
- 文档计划
- 优化后内核文档初稿完成，鼓励开发者体验新内容，验证内容。
- 社区化文档运作，鼓励社区开发者参与文档的优化编写，文档问题反馈。
- **访问[《OpenHarmony 内核开发指南（LiteOS-A核） 文档大纲》](#kernel_a_tutorial_outline_detail)。**
## 文档大纲及认领明细<a name='section_outline_detail'></a>
✨**文档大纲用于维护文档的组成章节、章节意图，编写责任人，及PR合入状态**。
✨**使用对号[✔]表示文档的完成状态，第一个对号表示文档开发完成，第二个对号表示文档开发完成**。
### 一、基于Qemu运行OpenHarmony 文档大纲 <a name='section_qemu_outline_detail'></a>
#### 1 Qemu简介 [@rtos_yuan](https://gitee.com/rtos_yuan) [✔] [@mgy917](https://gitee.com/mgy917) [✔]
<!-- 简介Qemu用途，对社区开发者价值。 -->
#### 2 开发环境准备 [@mgy917](https://gitee.com/mgy917) [✔] [@rtos_yuan](https://gitee.com/rtos_yuan) [✔]
- 2.1 OpenHarmony开发环境准备
- 环境搭建 <!-- 介绍需要什么样的环境，可以链接跳转到相应章节 -->
- 获取OpenHarmony源码
- 2.2 Qemu软件安装
开发者根据需求，选择运行LiteOS-A、LiteOS-M的Qemu软件。
- Qemu软件编译安装
- Qemu-Virt软件
- Qemu-Riscv32软件 [@zhushengle](https://gitee.com/zhushengle) [✔]
<!-- 介绍如何搭建开发环境，如何获取Qemu工程源码，安装Qemu软件。环境准备等可以链接跳转 -->
#### 3 Qemu工程源码介绍 [@waitForContributor](https://gitee.com/openharmony/docs/issues)[ ？]
* 3.1 Qemu工程源码介绍
#### 4 编译运行LiteOS-A Qemu Virt工程 [@waitForContributor](https://gitee.com/openharmony/docs/issues)[ ？]
- 4.1 编译构建LiteOS-A <!--演示编译构建。 -->
- 4.2 运行镜像 <!-- 介绍如何准备镜像、如何配置、如何运行程序。 -->
- 准备Flash镜像
- 配置主机网桥
- 运行程序
#### 5 编译运行LiteOS-M Qemu Riscv工程 [@waitForContributor](https://gitee.com/openharmony/docs/issues)[ ？]
- 4.1 编译构建LiteOS-M <!--演示编译构建。 -->
- 4.2 运行程序
### 二、小型系统三方芯片移植指南 <a name='porting_tutorial_outline_detail'></a>---招募内容体验&验证
#### 1 移植准备 [@arvinzzz](https://gitee.com/arvinzzz) [✔] [@rtos_yuan](https://gitee.com/rtos_yuan) [✔]
<!-- 简介移植须知和编译构建知识：流程、编译脚本、目录规则等 -->
##### 1.1 移植须知
##### 1.2 编译构建
#### 2 内核移植 [@waitForContributor](https://gitee.com/openharmony/docs/issues)[ ？]
- 2.1 LiteOS-A内核
<!-- 详细介绍如何移植OpenHarmony LiteOS-A内核 -->
- 2.1.1 移植概述 <!-- 介绍移植场景、目录规范等 -->
- 2.1.2 内核基础适配 <!-- 移植适配的具体步骤 -->
- 2.1.3 内核移植验证 <!-- 验证移植是否成功 -->
- 2.2 Linux内核
<!-- 详细介绍如何移植OpenHarmony Linux内核 -->
#### 3 板级移植 [@waitForContributor](https://gitee.com/openharmony/docs/issues)[ ？]
<!-- 详细介绍如何移植驱动、HDI移植等 -->
### 三、小型系统内核开发指南（LiteOS-A核）<a name='kernel_a_tutorial_outline_detail'></a>---招募内容体验&验证
#### 1 认识LiteOS-A内核 [@kkup180](https://gitee.com/kkup180) [✔] [@mgy917](https://gitee.com/mgy917) [✔]
<!-- 介绍OpenHarmony LiteOS-A内核的内核架构、CPU体系支持与体系架构扩展 -->
- 1.1 简介
- 1.2 内核架构
- 1.3 CPU体系架构支持
#### 2 基础内核 [@waitForContributor](https://gitee.com/openharmony/docs/issues)[ ？]
<!-- OpenHarmony LiteOS-A 基础内核的概念、运行机制、开发指导、编程实例 -->
- 2.1 中断及异常处理
- 2.2 进程管理
- 2.3 线程管理
- 2.4 调度
- 2.5 内存管理
- 2.5.1 堆内存管理
- 2.5.2 虚拟内存管理
- 2.5.3 物理内存管理
- 2.5.4 虚实映射
- 2.6 IPC
- 2.6.1 事件
- 2.6.2 信号量
- 2.6.3 互斥锁
- 2.6.4 消息队列
- 2.6.5 读写锁
- 2.6.6 futex
- 2.6.7 信号
- 2.7 系统调用
- 2.8 时间管理
- 2.9 软件定时器
- 2.10 原子操作
#### 3 扩展组件 [@waitForContributor](https://gitee.com/openharmony/docs/issues)[ ？]
<!-- OpenHarmony LiteOS-A 扩展组件的概念、运行机制、开发指导、编程实例 -->
- 3.1 ELF内核加载器
- 3.2 VDSO
- 3.3 LiteIPC
- 3.4 CPUP
- 3.5 C++支持
#### 4 文件系统 [@waitForContributor](https://gitee.com/openharmony/docs/issues)[ ？]
<!-- OpenHarmony LiteOS-A 文件系统的概念、运行机制、开发指导、编程实例 -->
- 4.1 vfs
- 4.2 支持的文件系统
- 4.2.1 FAT
- 4.2.2 jffs2
- 4.2.3 nfs
- 4.2.4 ramfs
- 4.2.5 procfs
- 4.3 适配新的文件系统
#### 5 内核启动 [@waitForContributor](https://gitee.com/openharmony/docs/issues)[ ？]
- 5.1 运行机制
#### 6 用户态启动 [@waitForContributor](https://gitee.com/openharmony/docs/issues)[ ？]
- 6.1 用户态根进程启动
- 6.2 用户态程序运行
#### 7 调测 [@waitForContributor](https://gitee.com/openharmony/docs/issues)[ ？]
<!-- OpenHarmony LiteOS-A 调测能力的概念、运行机制、开发指导、编程实例 -->
- 7.1 内存调测
- 7.2 Trace
- 7.3 魔法键
- 7.4 Dying gasp
- 7.5 常见问题定位方法
#### 8 附录 [@rtos_yuan](https://gitee.com/rtos_yuan) [✔] [@harylee](https://gitee.com/harylee)[✔]
- 8.1 基本数据结构 <!-- 介绍下是数据结构的概念、功能接口说明、开发流程和编程实例。 -->
- 8.1.1 双向链表
- 8.1.2 位操作
zh-cn/device-dev/kernel-contribution/template/常见问题.md 0 → 100644
浏览文件 @ 3fa8915b
# 常见问题
** *【写作要求】***
*可选。描述开发过程遇到的各类问题以及解决方案，以提高开发效率。*
- * 如果无常见问题，删除此章节。*
- * 如果有常见问题，建议单独章节，后续具备扩展性。*
- * 如果有常见问题，问题少于1屏且未来扩充可能性不大，可放在“开发指导”。*
*具体写作要求见下，完成写作后，请逐项自检下。*
| 要求项 | 内容要求 | 是否满足 |
| -------- | -------- | -------- |
| **N1** | **整体要求** | |
| N1.1 | 问题是否对外呈现（考虑重要性、出现概率等），请在部门内部CCB达成一致。 | |
| N1.2 | 每个问题描述里一般只问一个问题，避免多个问题合在一个问题描述。 | |
| N1.3 | 如果问题比较多，可以对问题进行分类。 | |
| **N2** | **单个问题要求** | |
| N2.1 | 标题：1句话描述问题场景、现象。 | |
| N2.2 | 现象描述：以用户视角黑盒描述问题出现的场景、现象、条件、概率等。描述问题现象清晰，没有歧义。 | |
| N2.3 | 可能原因：明确问题根本的原因。 | |
| N2.4 | 处理步骤-1：明确处理问题的步骤，step&nbsp;by&nbsp;step操作，具体要求同“开发步骤”部分。 | |
| N2.5 | 处理步骤-2：答复必须是严谨、明确的解决方法，口径与产品宣传一致，不能是参考建议这类含糊的回答。 | |
| N2.6 | 处理步骤-3：如果问题与能力版本有关联性的，需要明确。 | |
## 1.XX问题（简单问题）
XXX
## 2.XX问题（复杂问题）
**现象描述**
XXX
**可能原因**
XXX
**解决办法**
XXX
zh-cn/device-dev/kernel-contribution/template/开发实例.md 0 → 100644
浏览文件 @ 3fa8915b
# 开发实例
** *【写作要求】***
*必选。描述开发完成后，基于一个任务整体做代码段的描述。*
- * 标题名称不变。如果“开发指导”是多场景，标题名称可以调整为拍照开发实例、预览开发指导等。*
- * 标题可合并。如果产品链接到示例代码或内容少于1屏，可合并到“开发指导”，整本统一。*
*具体写作要求见下，完成写作后，请逐项自检下。*
| 要求项 | 内容要求 | 是否满足 |
| -------- | -------- | -------- |
| M1.1 | 有任务的场景介绍，且和代码端内容呼应。 | |
| M1.2 | 代码段顺利指导完成操作，无缺失。 | |
| M1.3 | 代码涉及开发者拷贝的命令，必须用可编辑的报文呈现，避免截图（DOCS插入Screen）。 | |
| M1.4 | 代码中关键段用蓝色（RGB：0.0.255）突出显示，关键步骤要有注释说明。 | |
| M1.5 | 代码显示符合代码缩进要求。 | |
**【写作样例---节选】**
SDIO设备完整的使用示例如下所示，首先打开总线号为1的SDIO控制器，然后独占HOST、使能设备、注册中断，接着进行SDIO通信（读写等），通信完成之后，释放中断、去使能设备、释放HOST，最后关闭SDIO控制器。
```
#include "hdf_log.h"
#include "sdio_if.h"
#define TEST_FUNC_NUM 1 /* 本测试用例中，使用编号为1的I/O function */
#define TEST_FBR_BASE_ADDR 0x100 /* 编号为1的I/O function的FBR基地址 */
#define TEST_ADDR_OFFSET 9 /* 本测试用例中，需要读写的寄存器的地址偏移 */
#define TEST_DATA_LEN 3 /* 本测试用例中，读写数据的长度 */
#define TEST_BLOCKSIZE 2 /* 本测试用例中，数据块的大小，单位字节 */
/* 中断服务函数，需要根据各自平台的情况去实现 */
static void SdioIrqFunc(void *data)
{
if (data == NULL) {
HDF_LOGE("SdioIrqFunc: data is NULL.\n");
return;
}
/* 需要开发者自行添加具体的实现 */
}
```
zh-cn/device-dev/kernel-contribution/template/开发指导.md 0 → 100644
浏览文件 @ 3fa8915b
# 开发指导
** *【写作要求】***
*必选。* *描述各个场景下，开发者如何完成开发任务。* *可根据多场景任务增加章节。写作要求见下，完成写作后，请逐项自检。*
| 要求项 | 内容要求 | 是否满足 |
| -------- | -------- | -------- |
| H.1.1 | 如果有多个场景，请写起多个“开发指导”章节，如音频播放开发指导、音量管理开发指导、短音播放开发指导。 | |
| H.1.2 | 标题尽量使用“动词+名词”的句式表述任务操作。 | |
## 场景介绍
** *【写作要求】***
*必选。* *描述在什么情景下解决什么问题，最终达到什么样的效果。*应用SCQA描述方法：
- S：situation（情景），由大家都熟悉的的情景，事实引入。
- C：complication（冲突），但是实际情况往往和我们的要求有冲突。
- Q：question（疑问），怎么办？
- A：answer（回答），我们的解决方案是 …
*写作要求见下，完成写作后，请逐项自检。*
| 要求项 | 内容要求 | 是否满足 |
| -------- | -------- | -------- |
| I.1.1 | 背景原因、什么时候在哪、做了什么操作、最终解决什么问题或操作效果都明确。 | |
**【写作样例】**
音频播放的主要工作是将音频数据转码为可听见的音频模拟信号并通过输出设备进行播放，同时对播放任务进行管理。
## 接口说明
** *【写作要求】***
*必选。* *描述本开发指导相关的接口有哪些，旨在要开发者在开发前有大体了解，提升开发效率。* *写作要求见下，完成写作后，请逐项自检。*
| 要求项 | 内容要求 | 是否满足 |
| -------- | -------- | -------- |
| J.1.1 | 不在本开发任务的接口无需提供。 | |
| J.1.2 | 如果接口太多，超过10个，可以提供主要的接口 | |
**【写作样例】**
音频播放开放能力如下：AudioRenderer类，具体的API详见接口文档。
**表1** 音频播放API接口功能介绍
| 接口名 | 描述 |
| -------- | -------- |
| AudioRenderer(AudioRendererInfo&nbsp;audioRendererInfo,&nbsp;PlayMode&nbsp;pm)&nbsp;throws&nbsp;IllegalArgumentException | 构造函数，设置播放相关音频参数和播放模式，使用默认播放设备 |
| AudioRenderer(AudioRendererInfo&nbsp;audioRendererInfo,&nbsp;PlayMode&nbsp;pm,&nbsp;AudioDeviceDescriptor&nbsp;outputDevice)&nbsp;throws&nbsp;IllegalArgumentException | 构造函数，设置播放相关音频参数、播放模式和播放设备 |
| boolean&nbsp;play() | 播放音频流 |
| boolean&nbsp;write(byte[]&nbsp;data,&nbsp;int&nbsp;offset,&nbsp;int&nbsp;size) | 将音频数据以byte流写入音频接收器以进行播放 |
## 开发步骤
** *【写作要求】***
* 必选。描述* *开发的整体过程，便于开发者快速完成开发。* * 具体 写作要求见下，完成写作后，请逐项自检下。*
| 要求项 | 内容要求 | 是否满足 |
| -------- | -------- | -------- |
| **K.1** | **如何写好步骤** | |
| K.1.1 | 步骤完整：提供必须的步骤，顺利指导完成操作，无缺失。 | |
| K.1.2 | 脉络清楚：文档逻辑清晰、合理。文档前面的概述、准备、操作围绕一条线描述，不能章节断裂或前后矛盾的现象。 | |
| K.1.3 | 任务句式：标题或句子尽量使用“动词+名词”的句式表述动作。 | |
| K.1.4 | 预防提前：操作过程中的限制、易错的、有潜在风险的，要提前描述，使用DOCS平台的“插入&gt;&nbsp;说明&nbsp;&gt;&nbsp;须知”描述。 | |
| K.1.5 | 步骤清晰-1：无论步骤简单或复杂，都需要写步骤目的，即为什么做。 | |
| K.1.6 | 步骤清晰-2：明确在什么环境下，使用什么工具，做什么操作，怎么做该操作。 | |
| K.1.7 | 步骤具体：如果操作可选，要明确可选条件。 | |
| K.1.8 | 在开发步骤执行完成后，及时明确操作正确的标准。 | |
| **K.2** | **如何写好代码段** | |
| K.2.1 | 代码涉及开发者拷贝的命令，必须用可编辑的报文呈现，避免截图（DOCS插入Screen）。 | |
| K.2.2 | 代码中关键段用蓝色（RGB：0.0.255）突出显示，关键步骤要有注释说明。 | |
| K.2.3 | 代码显示符合代码缩进要求。 | |
| K.2.4 | 步骤涉及接口调用，清晰给出接口及其使用说明或示例代码，代码来源于具体实例。 | |
**【写作样例】**
1. 构造音频流参数的数据结构AudioStreamInfo，推荐使用AudioStreamInfo.Builder类来构造，模板如下，模板中设置的均为AudioStreamInfo.Builder类的默认值，根据音频流的具体规格来设置具体参数。
```
AudioStreamInfo audioStreamInfo = new AudioStreamInfo.Builder().sampleRate( AudioStreamInfo.SAMPLE_RATE_UNSPECIFIED) .audioStreamFlag(AudioStreamInfo.AudioStreamFlag.AUDIO_STREAM_FLAG_NONE) .encodingFormat(AudioStreamInfo.EncodingFormat.ENCODING_INVALID) .channelMask(AudioStreamInfo.ChannelMask.CHANNEL_INVALID) .streamUsage(AudioStreamInfo.StreamUsage.STREAM_USAGE_UNKNOWN) .build();
```
以真实的播放pcm流为例：
```
AudioStreamInfo audioStreamInfo = new AudioStreamInfo.Builder().sampleRate(44100)//44.1kHz .audioStreamFlag(AudioStreamInfo.AudioStreamFlag.AUDIO_STREAM_FLAG_MAY_DUCK)//混音 .encodingFormat(AudioStreamInfo.EncodingFormat.ENCODING_PCM_16BIT)//16-bit PCM .channelMask(AudioStreamInfo.ChannelMask.CHANNEL_OUT_STEREO)//双声道 .streamUsage(AudioStreamInfo.StreamUsage.STREAM_USAGE_MEDIA)//媒体类音频 .build();
```
2. 使用步骤1创建的音频流构建音频播放的参数结构AudioRendererInfo，推荐使用AudioRendererInfo.Builder类来构造，模板如下，模板中设置的均为AudioRendererInfo.Builder类的默认值，根据音频播放的具体规格来设置具体参数。
```
AudioRendererInfo audioRendererInfo = new AudioRendererInfo.Builder().audioStreamInfo(audioStreamInfo) .audioStreamOutputFlag(AudioRendererInfo.AudioStreamOutputFlag.AUDIO_STREAM_OUTPUT_FLAG_NONE) .bufferSizeInBytes(0) .distributedDeviceId("") .isOffload(false) .sessionID(AudioRendererInfo.SESSION_ID_UNSPECIFIED) .build();
```
以真实的播放pcm流为例：
```
AudioRendererInfo audioRendererInfo = new AudioRendererInfo.Builder().audioStreamInfo(audioStreamInfo) .audioStreamOutputFlag(AudioRendererInfo.AudioStreamOutputFlag.AUDIO_STREAM_OUTPUT_FLAG_DIRECT_PCM)//pcm格式的输出流 .bufferSizeInBytes(100) .distributedDeviceId("E54***5E8")//使用分布式设备E54***5E8播放 .isOffload(false)//false表示分段传输buffer并播放，true表示整个音频流一次性传输到HAL层播放 .build();
```
3. 根据要播放音频流指定PlayMode，不同的PlayMode在写数据时存在差异，详情见步骤7，其余播放流程是无区别的。并通过构造函数获取AudioRenderer类的实例化对象。
....
4. 播放任务结束后，调用AudioRenderer实例化对象的release()释放资源。
## 调测验证（可选）
** *【写作要求】***
*可选。* *描述开发完成后，进行调测验证，确保最终操作成功。* *操作步骤要求同“开发指导”，其他具体写作要求见下，完成写作后，请逐项自检下。*
| 要求项 | 内容要求 | 是否满足 |
| -------- | -------- | -------- |
| L1.1 | 仅进行最后的业务调测，每个小任务的操作结果，在开发步骤执行完成后，及时验证操作结果。 | |
| L1.2 | 明确开发成功标准。 | |
**【写作样例---节选】**
![1624266401415](C:\Users\LWX104~1\AppData\Local\Temp\1624266401415.png)
zh-cn/device-dev/kernel-contribution/template/搭建环境.md 0 → 100644
浏览文件 @ 3fa8915b
# 搭建环境
** *【写作要求】***
*条件必选。* *如果在快速入门里已提供此部分，此章节可以不提供。明确如何搭建开发环境（如开发工具、编译工具）*。
## 环境要求
** *【写作要求】***
*必选。* *明确开发环境所需要的软硬件配置，* *旨在要用户提前准备环境。*如果软硬件内容比较多，可以再增加子标题。写作要求见下，完成写作后，请逐项自检。
| 要求项 | 内容要求 | 是否满足 |
| -------- | -------- | -------- |
| E.1.1 | 分别明确开发的软硬环境和手机的开发环境，下载路径。 | |
| E1.2 | 明确具体的版本号。 | |
**【写作样例】**
**表1** 环境要求
| 项目 | PC | 手机 |
| -------- | -------- | -------- |
| 硬件 | -&nbsp;内存：8G及以上<br/>-&nbsp;硬盘：100G及以上<br/>-&nbsp;分辨率：1280\*800 | 处理器不低于kirin&nbsp;980的华为手机 |
| 软件 | 操作系统：Windows10&nbsp;64位&nbsp;&nbsp;或&nbsp;Mac&nbsp;10。 | 系统软件版本不低于EMUI_10.0.0 |
## 安装环境
** *【写作要求】***
必选。描述安装环境的具体步骤，如果内容比较多，可以区分安装环境章节，如：安装编译基础环境、安装编译工具环境、安装gcc_riscv32（WLAN模组类编译工具链）。
写作要求见下，完成写作后，请逐项自检。
| 要求项 | 内容要求 | 是否满足 |
| -------- | -------- | -------- |
| **F.1** | **如何写好步骤** | |
| F.1.1 | 步骤完整：提供必须的步骤，顺利指导完成操作，无缺失。 | |
| F.1.2 | 脉络清楚：文档逻辑清晰、合理。文档前面的概述、准备、操作围绕一条线描述，不能章节断裂或前后矛盾的现象。 | |
| F.1.3 | 任务句式：标题或句子尽量使用“动词+名词”的句式表述动作。 | |
| F.1.4 | 预防提前：操作过程中的限制、易错的、有潜在风险的，要提前描述，使用DOCS平台的“插入&gt;&nbsp;说明&nbsp;&gt;&nbsp;须知”描述。 | |
| F.1.5 | 步骤清晰-1：无论步骤简单或复杂，都需要写步骤目的，即为什么做。 | |
| F.1.6 | 步骤清晰-2：明确在什么环境下，使用什么工具，做什么操作，怎么做该操作。 | |
| F.1.7 | 步骤具体：如果操作可选，要明确可选条件。 | |
| F.1.8 | 在开发步骤执行完成后，及时明确操作正确的标准。 | |
| **F.2** | **如何写好代码段** | |
| F.2.1 | 代码涉及开发者拷贝的命令，必须用可编辑的报文呈现，避免截图（DOCS插入Screen）。 | |
| F.2.2 | 代码中关键段用蓝色（RGB：0.0.255）突出显示，关键步骤要有注释说明。 | |
| F.2.3 | 代码显示符合代码缩进要求。 | |
| F.2.4 | 步骤涉及接口调用，清晰给出接口及其使用说明或示例代码，代码来源于具体实例。 | |
**【写作样例】**
1. 双击下载的exe文件，进入DevEco Studio安装向导。
2. 配置DevEco Studio安装路径，点击<parmvalue>Next</parmvalue>。
3. 配置DevEco Studio安装选项，点击<parmvalue>Next</parmvalue>。
- Create Desktop Shortcut：配置是否创建桌面快捷方式，根据操作系统位数进行选择。
- Update PATH variable：配置是否将启动器路径添加到环境变量PATH中，需要从命令行启动DevEco Studio时，需要勾选<parmvalue>Add launchers dir to the PATH</parmvalue>。
- Update context menu：配置是否将DevEco Studio功能添加至上下文菜单。勾选后，右键上下文菜单将出现“Open Folder as Project”选项。
4. 配置桌面快捷方式的开始菜单文件夹，点击<parmvalue>Install</parmvalue>。
5. 等待DevEco Studio安装完成后，点击<parmvalue>Finish</parmvalue>。
## 检验环境是否搭建成功
** *【写作要求】***
*必选。* *环境搭建完成后，需要明确给出环境搭建是否成功的检验标准*。
| 要求项 | 内容要求 | 是否满足 |
| -------- | -------- | -------- |
| G.1.1 | 仅进行最后的结果验证，每个小任务的操作结果，在开发步骤执行完成后，及时验证操作结果。 | |
| G1.2 | 明确搭建成功的标准。 | |
zh-cn/device-dev/kernel-contribution/template/概述.md 0 → 100644
浏览文件 @ 3fa8915b
# 概述
* **【开发指南总体** **写作要求】***
* 适用于鸿蒙南北向子系统开发、应用侧的设备开发、南向开发指南。*
* 章节调整：本模板知识点内容结构可以根据产品内容多少微调，具体操作方式见下。*
| 章节 | 可选/必选说明 | 备注 |
| -------- | -------- | -------- |
| 概述 | 必选，标题名称不变 | - |
| 搭建环境 | 可选，如果快速入门已有，可不用提供，否则需提供。 | - |
| 开发指导 | 必选，可根据多场景任务增加章节。 | 拍照开发指导<br/>预览开发指导<br/>录像开发指导 |
| 开发实例 | 必选。<br/>-&nbsp;标题名称可自定义。如果“开发指导”是多场景，标题名称可以调整为拍照开发实例、预览开发实例等。<br/>-&nbsp;标题可合并。如果产品链接到示例代码或内容少于1屏，可合并到“开发指导”，整本统一。 | - |
| 常见问题 | 可选，标题不变。<br/>-&nbsp;如果无常见问题，删除此章节。<br/>-&nbsp;如果有常见问题，建议单独章节，后续具备扩展性。<br/>-&nbsp;如果有常见问题，问题少于1屏，未来扩充可能行不大，可放在“开发指导”。 | - |
| 参考 | 可选，根据实际需要补充。 | - |
* 整体写作要求见下，完成写作后，请逐项自检。*
| 要求项 | 内容要求 | 是否满足 |
| -------- | -------- | -------- |
| **A.1** | **用语要求** | |
| A.1.1 | 行文风格：文档在官方网站发布，用语正式，避免口语化。 | |
| A.1.2 | 合规要求：不能使用Android特有概念等存在合规和法务风险的词汇。敏感词汇包含但不限于：Android、Google、EMUI、Activity、AOSP、provider、binder、APK、Dalvik、AVD、ADT、DDMS、adb、AAPT、AndroidManifest、NDK、ART、dex、ANR、Cursor、Blacklist、Whitelist、Master、Slave、L0、L1、轻鸿蒙、富鸿蒙等。 | |
| A.1.3 | 内容简洁：内容采用信息必备、最小化原则，旨在指导开发者在尽量短的时间完成操作。 | |
| A.1.4 | 内容正确：文档的代码、需要设置的参数等需要跟产品实际情况实时保持一致。 | |
| A.1.5 | 用语准确：应当确切，不能出现多义性的描述。 | |
| A.1.6 | 用语一致：同一叫法，全文保持一致，术语与术语库保持一致，正文中缩略语首次出现要给出全称。 | |
| A.1.7 | 用语具体：如表示数量或程度时，避免用笼统的“多”“少”“大”，建议用具体数字表示。 | |
| **A.2** | **格式要求** | |
| A.2.1 | 标点符号正确、句尾有符号结尾。 | |
| A.2.2 | 内容尽量用项目列表或分类的方式清晰呈现。不要有单个项目列表；不要有多余空行。 | |
| A.2.3 | 英文字母和中文字之间不要有空格。 | |
| A.2.4 | 链接必须有效，具体，可直接跳转或下载。 | |
| A.2.5 | 如果是内容的辅助说明，请使用“说明”式样；如果提前申明事项，，请使用“须知”式样。To&nbsp;D的资料不用“注意”格式。 | |
| **A.3** | **表格** | |
| A.3.1 | 表格有表注，表头风格一致，采用名词或名词词组形式。 | |
| A.3.2 | 表格有表头，至少为2行2列，避免出现单行或单列表。 | |
| A.3.3 | 表格无内容用“_”，不出现空白的单元格。 | |
| **A.4** | **图形** | |
| A.4.2 | 符合华为调性，避免互联网化，避免涉及宗教信仰类截图。 | |
| A.4.3 | 图文并茂，行文应力求简明，如有可能，配以适当的图，表。 | |
| A.4.4 | 图形有图注（不可直接粘贴图形），图注风格一致，采用名词或名词词组形式。 | |
| A.4.5 | 图形应清晰可辩识，信息表达完整，易于阅读。如流程图不可缺少“开始”和“结束”。 | |
| A.4.6 | 图形逻辑清晰，图文配合使用，切忌图文分离。 | |
| A.4.7 | 图片的高度建议在640px左右，宽度不超过820px，一般为.png格式，图片的大小建议不超过150k。 | |
| A.4.8 | 图形建议尽量不要用文字，中文图用中文，英文图用英文。 | |
## 基本概念
*【 **写作要求】***
*必选，描述本开发任务相关的基本概念，帮助开发者更好的理解开发任务。* *写作要求见下，完成写作后，请逐项自检。*
| 要求项 | 内容要求 | 是否满足 |
| -------- | -------- | -------- |
| B.1.1 | 业界通用的概念不用再此赘述。 | |
| B.1.2 | 注意使用业界通用术语来表达，不用华为研发内部语言。 | |
| B.1.3 | 基本概念要黑盒描述，不用体现具体细节。 | |
【写作样例】
鸿蒙系统音频模块支持音频业务的开发，提供音频相关的功能，主要包括音频播放、音频采集、音量管理和短音播放等。
在进行应用的开发前，开发者应了解以下基本概念：
- 采样
采样就是把模拟信号数字化的过程，所有的模拟信号都需要通过采样转换为可以用0101来表示的数字信号。
- 采样率
采样率为每秒从连续信号中提取并组成离散信号的采样次数，单位用赫兹（Hz）来表示。通常人耳能听到频率范围大约在20Hz～20kHz之间的声音。常用的音频采样频率有：8kHz、11.025kHz、22.05kHz、16kHz、37.8kHz、44.1kHz、48kHz、96kHz、192kHz等。
- 声道
声道是指声音在录制或播放时在不同空间位置采集或回放的相互独立的音频信号，所以声道数也就是声音录制时的音源数量或回放时相应的扬声器数量。
- 音频帧
音频数据是流式的，本身没有明确的一帧帧的概念，在实际的应用中，为了音频算法处理/传输的方便，一般约定俗成取2.5ms~60ms为单位的数据量为一帧音频。这个时间被称之为“采样时间”，其长度没有特别的标准，它是根据编解码器和具体应用的需求来决定的。
## 运作机制
*【 **写作要求】***
*可选。如果机制比较简单，通过前面基本概念就可以说清楚，此章节可以不用提供，删除标题即可。*
*描述实现原理介绍机制，如关键步骤相关接口调用时机和触发时机，帮助开发者了解该功能的基本运作原理，以便更好的理解开发任务和定位问题。*
* 写作要求见下，完成写作后，请逐项自检。*
| 要求项 | 内容要求 | 是否满足 |
| -------- | -------- | -------- |
| C.1.1 | 仅描述开发任务相关的原理。 | |
| C.1.2 | 尽量图文配合，一般使用时序图、流程图等形式。文字描述与图形描述匹配。 | |
| C.1.3 | 原理要黑盒描述，注意不要泄密。 | |
【写作样例-1】
- 信号量初始化，为配置的N个信号量申请内存（N值可以由用户自行配置，受内存限制），并把所有的信号量初始化成未使用，并加入到未使用链表中供系统使用。
- 信号量创建，从未使用的信号量链表中获取一个信号量资源，并设定初值。
- 信号量申请，若其计数器值大于0，则直接减1返回成功。否则任务阻塞，等待其它任务释放该信号量，等待的超时时间可设定。当任务被一个信号量阻塞时，将该任务挂到信号量等待任务队列的队尾。
- 信号量释放，若没有任务等待该信号量，则直接将计数器加1返回。否则唤醒该信号量等待任务队列上的第一个任务。
- 信号量删除，将正在使用的信号量置为未使用信号量，并挂回到未使用链表。
- 信号量允许多个任务在同一时刻访问同一资源，但会限制同一时刻访问此资源的最大任务数目。访问同一资源的任务数达到该资源的最大数量时，会阻塞其他试图获取该资源的任务，直到有任务释放该信号量。
![1624266502700](C:\Users\LWX104~1\AppData\Local\Temp\1624266502700.png)
【写作样例-2】
**互斥锁运作原理**
多任务环境下会存在多个任务访问同一公共资源的场景，而有些公共资源是非共享的，需要任务进行独占式处理。互斥锁怎样来避免这种冲突呢？
用互斥锁处理非共享资源的同步访问时，如果有任务访问该资源，则互斥锁为加锁状态。此时其他任务如果想访问这个公共资源则会被阻塞，直到互斥锁被持有该锁的任务释放后，其他任务才能重新访问该公共资源，此时互斥锁再次上锁，如此确保同一时刻只有一个任务正在访问这个公共资源，保证了公共资源操作的完整性。
**图2** 互斥锁运作示意图
![1624266485662](C:\Users\LWX104~1\AppData\Local\Temp\1624266485662.png)
## 约束与限制
* **【写作要求】***
*必选。* *描述本开发任务过程中* *的约束条件，以及此操作约束带来相应的负面影响，包括但不限于如下几方面：*
* **功能限制：***
- * 功能使用范围（明确不支持的场景）。*
- *规格限制。*
* **操作限制** **：***
- * 已知问题的操作。*
- * 潜在风险的操作（如引起性能降低）。*
- * 引起性能降低的操作*。
* 写作要求见下，完成写作后，请逐项自检。*
| 要求项 | 内容要求 | 是否满足 |
| -------- | -------- | -------- |
| D.1.1 | 明确功能限制或操作限制。 | |
| D.1.2 | 约束对指导任务开发有影响或体验有感知，否则不用体现。 | |
| D.1.3 | 容易出错的操作在步骤里描述，不在此体现。 | |
**【写作样例】**
**互斥锁的约束与限制：**
- 两个任务不能对同一把互斥锁加锁。如果某任务对已被持有的互斥锁加锁，则该任务会被挂起，直到持有该锁的任务对互斥锁解锁，才能执行对这把互斥锁的加锁操作。
- 互斥锁不能在中断服务程序中使用。
- Huawei LiteOS作为实时操作系统需要保证任务调度的实时性，尽量避免任务的长时间阻塞，因此在获得互斥锁之后，应该尽快释放互斥锁。
- 持有互斥锁的过程中，不得再调用LOS_TaskPriSet等接口更改持有互斥锁任务的优先级。
Markdown is supported
0% 或 .
You are about to add 0 people to the discussion. Proceed with caution.
先完成此消息的编辑！
想要评论请 注册 或