1@page helloworld_demo helloworld简单示例
2
3[更正文档](https://gitee.com/alios-things/helloworld_demo/edit/master/README.md)      [贡献说明](https://help.aliyun.com/document_detail/302301.html)
4
5# 1. 案例简介
6helloworld_demo是我们提供的最简化的运行实例，该app从字面上来看功能也比较简单，即完成**hello world!**的关键字符输出，以表明系统初始化完成并能够正常输出。但是虽然功能看似简单单一，该app能够运行成功，即代码内核小系统以及基本的打印输出功能即正常运行。
7其完成的主要功能包括：
8- 系统板级初始化
9- 内核基础组件初始化
10- application_start用户入口
11- 串口打印输出
12- 循环睡眠打印
13该示例的运行依赖下述基本功能完成对接：
14- uart串口
15- 内核的任务和中断运行正常
16- 系统tick定时器正常运行
17即helloworld_demo这个示例运行，代码系统的**任务调度**、**tick调度**以及**串口打印功能**已经OK。
18
19# 2. 基础知识
20## 2.1 基础目录结构
21
22```tree
23.
24├── helloworld.c   # 该solution核心打印输出代码，入口**application_start**
25├── k_app_config.h # 内核组件的配置开关，优先级低于**k_config.h**
26├── maintask.c     # 系统主任务入口处理，入口**aos_maintask**
27├── Makefile       # aos make编译时入口
28├── package.yaml   # 编译系统配置文件
29└── SConstruct     # Makefile => Scon => aostools
30```
31
32## 2.2 基本规范
33solution统一以**aos_maintask**作为入口函数,从具体单板的C入口main函数开始，通过创建一个主任务来执行，即aos_maintask是系统主任务的入口函数：
34```c
35static void aos_main_task_entry(void)
36{
37    ......
38    aos_maintask();
39}
40
41/* main一般为单板的C程序入口 */
42int main(void)
43{
44    ......
45    krhino_task_dyn_create(&g_main_task, "main_task", 0, OS_MAIN_TASK_PRI, 0, OS_MAIN_TASK_STACK, (task_entry_t)aos_main_task_entry, 1);
46
47    while (1) {
48        krhino_task_sleep(100);
49    }
50}
51```
52aos_maintask内实现包括板级初始化**board_init**、基础组件初始化**aos_components_init**、以及app入口**application_start**
53```c
54/*  For user config
55    kinit.argc = 0;
56    kinit.argv = NULL;
57    kinit.cli_enable = 1;
58*/
59static kinit_t kinit = {0, NULL, 1};
60
61void board_init(void)
62{
63    board_tick_init();    // tick板级初始化，实现在具体board目录内
64    board_stduart_init(); // uart串口初始化，实现在具体board目录内
65    board_dma_init();     // 如果使用dma相关初始化，没有置空
66    board_gpio_init();    // gpio的时钟等初始化，没有可置空
67}
68
69void aos_maintask(void* arg)
70{
71    board_init();
72    board_kinit_init(&kinit);    // 给系统参数赋值，可使用默认值
73    aos_components_init(&kinit); // 系统基础组件的初始化
74
75#ifndef AOS_BINS
76    application_start(kinit.argc, kinit.argv); // app的实际实现入口
77#endif
78}
79
80```
81其中为了统一不同单板的板级初始化，新增单板需要统一支持board_init内各板级模块初始化，如果没有相关函数可以实现为空；
82对于helloworld功能比较简单，一般需要tick和uart的初始化即可；而对于复杂的app，即需要初始化的模块则按照实际情况来增加，对应实现在具体board中添加，如：
83```c
84void board_stduart_init(void)
85void board_tick_init(void)
86void board_flash_init(void)
87void board_network_init(void)
88void board_gpio_init(void)
89void board_wdg_init(void)
90void board_ota_init(void)
91void board_dma_init(void)
92```
93对于aos_components_init，其完成了一些基础组件如vfs、cli、kv等基础中间件的初始化，并通过组件宏开关，一旦相应该基础组件模块被加入编译，则aos_components_init即进行相关模块的初始化。
94application_start是实际solution的实现，即app的统一入口。
95
96## 2.3 基本运行流程
97
98<div align=left display=flex>
99    <img src="https://img.alicdn.com/imgextra/i3/O1CN01hHWuKH1gO2oeDXMtR_!!6000000004131-2-tps-399-302.png" style="max-width:800px;" />
100</div>
101
102# 3. 物料清单
103
104## 3.1 HaaS100 硬件
105
106[HaaS100 硬件简介](https://help.aliyun.com/document_detail/184426.html)
107
108<div align=left display=flex>
109    <img src="https://img.alicdn.com/imgextra/i4/O1CN01XxD6Xo217CB3FZnEU_!!6000000006937-2-tps-746-497.png" style="max-width:800px;" />
110</div>
111
112# 4. 案例实现
113
114## 4.1 硬件连接
115该案例只需要连接电源线以及串口线，如下图所示：
116
117<div align=left display=flex>
118    <img src="https://img.alicdn.com/imgextra/i2/O1CN01S9jkJw1dihpqURQH4_!!6000000003770-0-tps-1280-960.jpg" style="max-width:800px;" />
119</div>
120
121## 4.2 软件实现
122application_start实际app入口内实现较简单，主要包括：
123- 基本的串口打印
124- while循环睡眠10S打印计数
125代码如下：
126```c
127int application_start(int argc, char *argv[])
128{
129    int count = 0;
130
131    printf("nano entry here!\r\n");
132
133    while(1) {
134        printf("hello world! count %d \r\n", count++);
135        aos_msleep(10000);
136    };
137}
138```
139其中系统能够正常打印代表uart功能正常；能够循环1S打印代表tick中断以及任务切换功能正常。
140
141## 4.3 编译下载
142开发环境的搭建请参考[《AliOS Things集成开发环境使用说明之搭建开发环境》](https://help.aliyun.com/document_detail/302378.html)，其中详细的介绍了AliOS Things 3.3的IDE集成开发环境的搭建流程。
143
144helloworld_demo的代码下载请参考[《AliOS Things集成开发环境使用说明之创建工程》](https://help.aliyun.com/document_detail/302379.html)，
145
146*> 选择解决方案: “helloworld简单示例”*
147
148*> 选择开发板: Haas100 board configure*
149
150-- 编译固件可参考[《AliOS Things集成开发环境使用说明之编译固件》](https://help.aliyun.com/document_detail/302384.html)。
151
152-- 烧录固件可参考[《AliOS Things集成开发环境使用说明之烧录固件》](https://help.aliyun.com/document_detail/302383.html)。
153
154## 4.4 串口输出效果
155```sh
156             Welcome to AliOS Things
157nano entry here!
158hello world! count 0
159hello world! count 1
160hello world! count 2
161hello world! count 3
162hello world! count 4
163hello world! count 5
164hello world! count 6
165```
166
167# 5 添加新组件
168helloworld_demo作为一个基础组件，其本身依赖的组件相对较少，主要包括内核基础代码、cli以及单板和mcu相关的组件。
169用户可以基于此solution作为参考，来开发属于自己的app。
170如期望在helloworld_demo中增加ramfs文件系统的组件功能，操作步骤如下：
171
172## 5.1 yaml增加组件
173- 在helloworld_demo的yaml文件中添加组件依赖ramfs。由于需要使用标准vfs接口，因此还需要加上vfs组件。
174```yaml
175depends:
176  - ramfs: master
177  - vfs: master
178```
179至于ramfs本身依赖的组件，则在ramfs自身的yaml中需要添加完全。
180
181- 在helloworld_demo的app入口helloworld.c中添加ramfs头文件引用以及初始化函数调用，
182如下图，先注册一个根目录为**/test**的ramfs：
183
184<div align=left display=flex>
185    <img src="https://img.alicdn.com/imgextra/i3/O1CN01yyLyVL1mbgIjh55DK_!!6000000004973-2-tps-660-404.png" style="max-width:800px;" />
186</div>
187
188- 添加功能调用
189示例：
190```c
191    #include <fcntl.h>
192    #include <sys/types.h>
193    #include <unistd.h>
194    #include "ramfs.h"
195
196    int fd;
197    int ret;
198    char teststring = "1234";
199    char readbuf[10];
200
201    ramfs_register("/test");
202    fd = open("/test/file1", O_RDWR);
203    if(fd < 0){
204        printf("ramfs open fail!\r\n");
205        return fd;
206    }
207    ret = write(fd, teststring, 5);
208    if(ret < 0){
209        printf("ramfs write fail!\r\n");
210        return ret;
211    }
212    lseek(fd, 0, SEEK_SET);
213    ret = read(fd, readbuf, 5);
214    if(ret < 0){
215        printf("ramfs read fail!\r\n");
216        return ret;
217    }
218    if(strncmp(readbuf, teststring, 5)){
219        printf("ramfs test fail! readbuf:%s\r\n",readbuf);
220    }else{
221        printf("ramfs test success!\r\n");
222    }
223    ramfs_unregister("/test");
224```
225由于使用了标准文件系统的O_RDWR相关定义，需要包含#include "fcntl.h"
226
227- 编译、运行
228
229```sh
230aos make helloworld_demo@haas100 -c config
231aos make
232```
233运行效果：
234
235```sh
236             Welcome to AliOS Things
237nano entry here!
238ramfs test success!
239hello world! count 0
240hello world! count 1
241hello world! count 2
242hello world! count 3
243```
244
245# 6. 总结
246helloworld_demo虽然代码较少，但是其完成了一个最小系统需要的基本功能，包括：内核启动、任务切换、tick中断，以及串口输出。一般作为单板移植的基本solution来参考对接；
247同时，还可以此solution为基础，开始添加用户需要的其他组件，并定制修改自身需要的APP。
248