开发指南写作模板.md · openharmony_docs/standards_template

# 开发指南写作模板

- [概述](#概述)
  - [功能简介](#功能简介)
  - [基本概念](#基本概念)
  - [运作机制](#运作机制)
  - [约束与限制](#约束与限制)
  - [相关模块](#相关模块)
- [开发指导](#开发指导)
  - [场景介绍](#场景介绍)
  - [接口说明](#接口说明)
  - [开发步骤](#开发步骤)
  - [调测验证](#调测验证)
  - [开发实例](#开发实例)
- [常见问题](#常见问题)
  - [XX问题](#xx问题)
  - [安装hb过程中，提示"module 'platform' has no attribute 'linux_distribution'"](#安装hb过程中-提示-module-platform-has-no-attribute-linux_distribution-)
- [参考](#参考)

**_【开发指南总体写作要求】_**

_适用于OpenHarmony特性的开发指南。_

_内容大纲：本模板知识点内容结构可以根据产品内容多少微调，整体包含以下章节。_

| 章节 | 可选/必选说明 | 备注 | 
| -------- | -------- | -------- |
| 概述 | 必选，标题名称不变 | - | 
| 开发指导 | 必选，可根据多场景任务增加章节。 | 拍照开发指导 预览开发指导 录像开发指导 | 
| 开发实例 | 必选。 -&nbsp;标题名称可自定义。如果“开发指导”是多场景，标题名称可以调整为拍照开发实例、预览开发实例等。 -&nbsp;标题可合并。如果产品链接到示例代码或内容少于1屏，可合并到“开发指导”，整本统一。 | - | 
| 常见问题 | 可选，标题不变。 -&nbsp;如果无常见问题，删除此章节。 -&nbsp;如果有常见问题，建议单独章节，后续具备扩展性。 -&nbsp;如果有常见问题，问题少于1屏，未来扩充可能行不大，可放在“开发指导”。 | - | 
| 参考 | 可选，根据实际需要补充。 | - |

_整体写作要求见下，完成写作后，请逐项自检。_

| 要求项 | 内容要求 | 是否满足 | 
| -------- | -------- | -------- |
| **A.1** | **用语要求** |  | 
| A.1.1 | 行文风格：用语正式，避免口语化。 |  | 
| A.1.4 | 内容正确：文档的代码、需要设置的参数等需要跟产品实际情况实时保持一致。 |  | 
| **A.2** | **格式要求** |  | 
| A.2.2 | 内容尽量用项目列表或分类的方式清晰呈现。不要有单个项目列表；不要有多余空行。 |  | 
| A.2.4 | 链接必须有效，具体，可直接跳转或下载。 |  | 
| A.2.5 | 如果是内容的辅助说明，请使用“说明”式样；如果提前申明事项，请使用“须知”式样。 |  | 
| **A.3** | **表格** |  | 
| A.3.2 | 表格有表头，避免出现单行或单列表。 |  | 
| **A.4** | **图形** |  | 
| A.4.2 | 符合华为调性，避免互联网化，避免涉及宗教信仰类截图。 |  | 
| A.4.5 | 图形应清晰可辩识，信息表达完整，易于阅读。如流程图不可缺少“开始”和“结束”。 |  | 
| A.4.6 | 图形逻辑清晰，图文配合使用，切忌图文分离。 |  |

## 概述

### 功能简介

**_【写作要求】_**

总体介绍本功能特性的主要功能、使用场景、组成架构等。

**【写作样例】**

OpenHarmony LiteOS-M内核是面向IoT领域构建的轻量级物联网操作系统内核，具有小体积、低功耗、高性能的特点。其代码结构简单，主要包括内核最小功能集、内核抽象层、可选组件以及工程目录等。

OpenHarmony LiteOS-M内核架构包含硬件相关层以及硬件无关层，如下图所示，其中硬件相关层按不同编译工具链、芯片架构分类，提供统一的HAL（Hardware Abstraction Layer）接口，提升了硬件易适配性，满足AIoT类型丰富的硬件和编译工具链的拓展；其他模块属于硬件无关层，其中基础内核模块提供基础能力，扩展模块提供网络、文件系统等组件能力，还提供错误处理、调测等能力，KAL（Kernel Abstraction Layer）模块提供统一的标准接口。

**图1** 内核架构图
![zh-cn_image_0000001181788470](figures/zh-cn_image_0000001181788470.png)

### 基本概念

_【_**_写作要求】_**

_必选，描述本开发任务相关的基本概念，帮助开发者更好的理解开发任务。写作要求见下，完成写作后，请逐项自检。_

| 要求项 | 内容要求 | 是否满足 | 
| -------- | -------- | -------- |
| B.1.1 | 业界通用的概念不用再此赘述。 |  | 
| B.1.2 | 注意使用业界通用术语来表达，避免使用研发内部语言。 |  | 
| B.1.3 | 基本概念要黑盒描述，不体现具体细节。 |  |

**【写作样例】**

_OpenHarmony_系统音频模块支持音频业务的开发，提供音频相关的功能，主要包括音频播放、音频采集、音量管理和短音播放等。

在进行应用的开发前，开发者应了解以下基本概念：

- 采样

采样就是把模拟信号数字化的过程，所有的模拟信号都需要通过采样转换为可以用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返回。否则唤醒该信号量等待任务队列上的第一个任务。

- 信号量删除，将正在使用的信号量置为未使用信号量，并挂回到未使用链表。

- 信号量允许多个任务在同一时刻访问同一资源，但会限制同一时刻访问此资源的最大任务数目。访问同一资源的任务数达到该资源的最大数量时，会阻塞其他试图获取该资源的任务，直到有任务释放该信号量。
  **图2** 信号量运作示意图
  ![zh-cn_image_0000001181948444](figures/zh-cn_image_0000001181948444.png)

**【写作样例-2】**

**互斥锁运作原理**

多任务环境下会存在多个任务访问同一公共资源的场景，而有些公共资源是非共享的，需要任务进行独占式处理。互斥锁怎样来避免这种冲突呢？

用互斥锁处理非共享资源的同步访问时，如果有任务访问该资源，则互斥锁为加锁状态。此时其他任务如果想访问这个公共资源则会被阻塞，直到互斥锁被持有该锁的任务释放后，其他任务才能重新访问该公共资源，此时互斥锁再次上锁，如此确保同一时刻只有一个任务正在访问这个公共资源，保证了公共资源操作的完整性。

**图3** 互斥锁运作示意图
  ![zh-cn_image_0000001227626665](figures/zh-cn_image_0000001227626665.png)

### 约束与限制

**_【写作要求】_**

_必选。描述本开发任务过程中的约束条件，以及此操作约束带来相应的负面影响，包括但不限于如下几方面：_

**_功能限制：_**

- _功能使用范围（明确不支持的场景）。_

- _规格限制。_

**_操作限制：_**

- _已知问题的操作。_

- _潜在风险的操作（如引起性能降低）。_

- _引起性能降低的操作_。

_写作要求见下，完成写作后，请逐项自检。_

| 要求项 | 内容要求 | 是否满足 | 
| -------- | -------- | -------- |
| D.1.2 | 约束对指导任务开发有影响或体验有感知，否则不用体现。 |  |

**【写作样例】**

**互斥锁的约束与限制：**

- 两个任务不能对同一把互斥锁加锁。如果某任务对已被持有的互斥锁加锁，则该任务会被挂起，直到持有该锁的任务对互斥锁解锁，才能执行对这把互斥锁的加锁操作。

- 互斥锁不能在中断服务程序中使用。

- Huawei LiteOS作为实时操作系统需要保证任务调度的实时性，尽量避免任务的长时间阻塞，因此在获得互斥锁之后，应该尽快释放互斥锁。

- 持有互斥锁的过程中，不得再调用LOS_TaskPriSet等接口更改持有互斥锁任务的优先级。

### 相关模块

**_【写作要求】_**

_可选。因本次文档开发以模块为粒度，如果本模块无法独立完成开发指导所描述的功能，那么需要在此处列出强相关的特性模块。_

_所谓强相关特性模块，应当为开发指导中必须使用到的其他特性。_

_但如果是基础能力、通用能力，则无需在此列举。_

## 开发指导

**_【写作要求】_**

_必选。描述各个场景下，开发者如何完成开发任务。可根据多场景任务增加章节。写作要求见下，完成写作后，请逐项自检。_

| 要求项 | 内容要求 | 是否满足 | 
| -------- | -------- | -------- |
| H.1.1 | 如果有多个场景，请写多个“开发指导”章节，如音频播放开发指导、音量管理开发指导、短音播放开发指导。 |  | 
| H.1.2 | 标题尽量使用“动词+名词”的句式表述任务操作。 |  |

### 场景介绍

**_【写作要求】_**

_必选。描述在什么情景下解决什么问题，最终达到什么样的效果。_应用SCQA描述方法：

- S：situation（情景），由大家都熟悉的的情景，事实引入。

- C：complication（冲突），但是实际情况往往和我们的要求有冲突。

- Q：question（疑问），怎么办？

- A：answer（回答），我们的解决方案是 …

_写作要求见下，完成写作后，请逐项自检。_

**【写作样例】**

音频播放的主要工作是将音频数据转码为可听见的音频模拟信号并通过输出设备进行播放，同时对播放任务进行管理。

### 接口说明

**_【写作要求】_**

_必选。描述本开发指导相关的接口有哪些，旨在要开发者在开发前有大体了解，提升开发效率。写作要求见下，完成写作后，请逐项自检。_

| 要求项 | 内容要求 | 是否满足 | 
| -------- | -------- | -------- |
| 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.7 | 步骤具体：如果操作可选，要明确可选条件。 |  | 
| **K.2** | **如何写好代码段** |  | 
| K.2.1 | 代码涉及开发者拷贝的命令，必须用可编辑的报文呈现，避免截图（DOCS插入Screen）。 |  | 
| K.2.2 | 关键步骤要有注释说明。 |  | 
| 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();
   ```

2. 以真实的播放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();
   ```

3. 使用步骤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();
   ```

4. 以真实的播放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();
   ```

5. 根据要播放音频流指定PlayMode，不同的PlayMode在写数据时存在差异，详情见步骤7，其余播放流程是无区别的。并通过构造函数获取AudioRenderer类的实例化对象。

6. ....

7. 播放任务结束后，调用AudioRenderer实例化对象的release()释放资源。

### 调测验证

**_【写作要求】_**

_可选。描述开发完成后，进行调测验证，确保最终操作成功。操作步骤要求同“开发指导”，其他具体写作要求见下，完成写作后，请逐项自检下。_

| 要求项 | 内容要求 | 是否满足 | 
| -------- | -------- | -------- |
| L1.2 | 明确开发成功标准。 |  |

**【写作样例---节选】**

![zh-cn_image_0000001182107002](figures/zh-cn_image_0000001182107002.png)

### 开发实例

**_【写作要求】_**

_必选。描述开发完成后，基于一个任务整体做代码段的描述。_

- _标题名称不变。如果“开发指导”是多场景，标题名称可以调整为拍照开发实例、预览开发指导等。_

- _标题可合并。如果产品链接到示例代码或内容少于1屏，可合并到“开发指导”，整本统一。_

_具体写作要求见下，完成写作后，请逐项自检下。_

| 要求项 | 内容要求 | 是否满足 | 
| -------- | -------- | -------- |
| M1.1 | 有任务的场景介绍，且和代码端内容呼应。 |  | 
| M1.2 | 代码段顺利指导完成操作，无缺失。 |  | 
| 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; 
    } 
    /* 需要开发者自行添加具体的实现 */ 
}
```

## 常见问题

**_【写作要求】_**

_可选。描述开发过程遇到的各类问题以及解决方案，以提高开发效率。_

- _如果无常见问题，删除此章节。_

- _如果有常见问题，建议单独章节，后续具备扩展性。_

- _如果有常见问题，问题少于1屏且未来扩充可能性不大，可放在“开发指导”。_

_具体写作要求见下，完成写作后，请逐项自检下。_

| 要求项 | 内容要求 | 是否满足 | 
| -------- | -------- | -------- |
| **N1** | **整体要求** |  | 
| N1.2 | 每个问题描述里一般只问一个问题，避免多个问题合在一个问题描述。 |  | 
| N1.3 | 如果问题比较多，可以对问题进行分类。 |  | 
| **N2** | **单个问题要求** |  | 
| N2.1 | 标题：1句话描述问题场景、现象。 |  | 
| N2.2 | 现象描述：以用户视角黑盒描述问题出现的场景、现象、条件、概率等。描述问题现象清晰，没有歧义。 |  | 
| N2.3 | 可能原因：明确问题根本的原因。 |  |

### XX问题

**现象描述**

XXX

**可能原因**

XXX

**解决办法**

XXX

**【写作样例】**

### 安装hb过程中，提示"module 'platform' has no attribute 'linux_distribution'"

- **现象描述**
  执行“python3 -m pip install --user ohos-build”提示"module 'platform' has no attribute 'linux_distribution'"。

- **可能原因**
  python3 pip安装兼容性问题。

- **解决办法**
  执行如下命令重新安装pip。

```
  sudo apt remove python3-pip
  curl https://bootstrap.pypa.io/get-pip.py -o get-pip.py
  python get-pip.py
  ```

## 参考

**_【写作要求】_**

_可选。为开发者提供参考信息。_

**【写作样例】**

如果您想了解更多关于XXX特性的源码及使用信息，请参考XXX代码仓（给出链接）。

openharmony_docs/standards_template

简介

发行版

贡献者

近期动态

openharmony_docs/standards_template .gitee-modal { width: 500px !important; }

简介

发行版

贡献者

近期动态

搜索帮助

openharmony_docs/standards_template