V1.0.5

doc/luban-lite_driver_development_guide.md

@@ -1,56 +0,0 @@
-# 1. 代码存放位置
-
-在Luban-Lite中，将Driver、HAL、sys（最小系统）代码统称为bsp，存放在SDK跟目录中的`bsp`文件夹中。
-
-在bsp文件夹中，再按照SoC内置 和 外挂 分为两个文件夹：`artinchip` 和`peripheral`
-
-![](images/bsp_dir.png)
-
-
-
-# 2. 编译框架修改
-
-`SConscript` 文件的修改和编写。
-
-# 3. 编码规范
-
-## 3.1 编码风格
-
-编码风格以RT-Thread的原生规范为准，参考文件：
-
-`kernel/rt-thread/documentation/contribution_guide/**coding_style_cn.md`
-
-## 3.2 驱动分层的设计规范
-
-对于每一个模块的驱动，按照  Driver + HAL 两层来设计：
-
-- Driver层：**连接HAL和Driver Framework的桥梁**，主要是将Driver Framework的各功能接口转换成HAL层的操作组合。
-- HAL层：完全屏蔽直接访问 **寄存器层面的操作**，将寄存器操作封装为一个个单独的功能点（HAL可理解为一个执行器）。
-- 一个简单的区分方法：所有寄存器级别的访问，都放在HAL层去封装。也就是说，Driver层不应该出现直接读写寄存器。
-- 理想情况：**如果要换OS，就只需要换Driver；如果要换硬件，就只需要换HAL。**
-
-
-
-当然，个别驱动比如syscfg模块的逻辑很简单，不需要模块初始化，也可以不需要Driver层，只实现HAL层即可。
-
-## 3.3 命名规则
-
-**文件名的命名**：
-
-- 全部用 `小写字母 + 下划线"_"` 组成，如 hal_rtc.h
-- 放在 bsp/artinchip/ 目录下都属于ArtInChip开发的代码，除common的文件如aic_log.h，其他各模块的**文件名不需再加公司名称的前缀**
-- Driver层的文件名格式：`“drv_” + 模块名 + “_子功能”（如果需要的话）`，如 drv_rtc.c
-- HAL层的文件名格式：`“hal_” + 模块名 + “_子功能”（如果需要的话）`，如 hal_rtc.c
-
-**接口的命名**：
-
-- 这里只约束对外的接口，内部使用接口全部用static修饰 ，避免命名冲突即可
-- Driver层的对外接口命名格式： `“drv_” + 模块名 + “_子功能”（如果需要的话）`，如drv_rtc_init()
-- HAL层的对外接口命名格式： `“hal_” + 模块名 + “_子功能”（如果需要的话）`，如hal_rtc_init()
-
-**数据结构的命名**：
-
-一个模块分成Driver和HAL层后，可能需要不同层次的数据结构来存放相应的信息，这个数据结构的名称最好大家也统一风格。
-
-- Driver层的数据结构名称格式：`aic_模块缩写` 或者 `aic_模块缩写_dev` ，如aic_i2c、aic_sdmc、aic_wdt_dev
-- HAL层的数据结构名称格式：`aic_模块名称_host` 或者 `aic_模块名称_ctrl` ，如 aic_sdmc_host

doc/luban-lite_sdk_design.md

@@ -1,194 +0,0 @@
-# 1. Luban-Lite简介
-
-Luban-Lite SDK 的设计目标：
-
-- 兼容目前市面上最流行的几种 RTOS 内核：RT-Thread、FreeRTOS等
-- 支持baremetal模式
-- 提供完整的软件栈生态资源
-
-为了满足上述目标，Luban-Lite 在原有的 RT-Thread SDK 框架基础之上进行二次开发和扩展：
-
-- 对于内核部分，做成 RT-Thread、FreeRTOS、baremetal 无感切换
-- 尽可能复用 RT-Thread的 驱动框架和组件生态
-
-## 1.1 Luban-Lite 框架
-
-根据是否使用OS，Luban-Lite SDK 架构分为两种情况：
-
-- 使用RTOS的情况：
-
-![](images/lbl_os_framework.png)
-
-其中，对FreeRTOS的适配，存在两种方案（对APP层都是透明的）：
-
-![](images/freertos_adapter.png)
-
-- 使用baremetal的情况：（虚线外框表示可能不存在）
-
-![](images/lbl_baremetal_framework.png)
-
-## 1.2 目录结构
-
-Luban-Lite SDK的目录结构如下：
-
-```
-luban-lite $ tree -L 2
-├── application     // 存放APP代码
-│   ├── baremetal
-│   └── os
-├── bsp // 存放BSP代码，和RT-Thread原生的bsp目录功能相同
-│   ├── artinchip // ArtInChip SoC内部的driver、hal以及最小系统sys代码
-│   ├── common 
-│   └── test // 各驱动的测试代码
-├── doc // Luban-Lite SDK的介绍文档
-│   ├── luban-lite_driver_development_guid.md  // 设备驱动开发指南
-│   ├── luban-lite_sdk_design.md // SDK设计说明
-│   ├── luban-lite_user_guid_linux.md // Linux环境的用户使用说明 
-│   └── luban-lite_user_guid_windows.md // Windows环境的用户使用说明
-├── win_env.bat // 启动RT-Thread的env工具，用于Windows环境的开发
-├── win_cmd.bat // 启动CMD.exe，用于Windows环境的开发
-├── kernel // 存放各种RTOS内核
-│   ├── common
-│   ├── freertos
-│   └── rt-thread
-├── output // SDK的编译输出
-├── packages // 组件包
-│   ├── artinchip // ArtInChip开发的组件包
-│   └── third-party // 第三方的组件包
-├── target // 方案（板）级的代码和配置
-│   ├── configs // 整个方案的SDK配置文件
-│   └── d21x // d21x 芯片对应的板级代码（见子目录）
-│      ├── demo100-nand
-│      ├── per2-nand
-│      └── per2-nor
-├── toolchain // 解压后的工具链存放目录
-└── tools // 一些工具
-    ├── onestep.sh  // ArtInChip开发的OneStep命令行增强工具
-    └── toolchain // 工具链的压缩包
-```
-
-# 2. Luban-Lite 设计说明
-
-## 2.1 四级抽象模型
-
-对于一个跨（软/硬件）平台的SDK 来说，需要支持：
-
-- 多个SoC芯片，需要做好驱动和设备的分离、驱动实例化等
-- 多块单板，每块板子的外设、IO、性能配置各不相同
-- 多种应用，1块板子可能支持多个应用
-- 若干组件，驱动、组件、应用的对应存在一对多的依赖
-
-总体上，以上元素形成了  `N x N x N` 的多对多组合关系。
-
-在满足以上复杂映射关系的基础上，SDK 设计还需要达到：
-
-- 用高内聚提供复用：减少代码冗余，减少维护工作量
-- 用低耦合应对变化：针对某个方案又能灵活配置，满足客户的多元化使用
-
-为了解决上述需求，Luban-Lite SDK框架中抽象出四个层级的元素：
-
-![](images/lbl_element.png)
-
-在具体的 Luban-Lite 设计中，从用户角度看，以上四级基本元素和SDK目录的对应关系如下图：
-
-![](images/lbl_prj_struct.png)
-
-
-
-## 2.2 编译框架
-
-Luban-Lite SDK 采用了 `scons` 作为编译框架的基础语言，相对传统的 `Makefile`会更灵活更强大。
-
- `scons` 是基于 python 语言的，除了编译语法远胜于语法难记功能弱小的 `Makefile` 语法，它还有无限的扩展性可以把任意操作扩展成和编译命令并列的命令，方便用户使用。另外 `Cmake` 的编译配置也是非常方便远优于 `Makefile`，但是 `Cmake` 扩展性也是远不及 `scons` 的。
-
-关于 `scons` 请参考非常经典的官方文档 [scons-user-guid](https://www.scons.org/doc/production/HTML/scons-user.html) 和 [scons-man-page](https://www.scons.org/doc/production/HTML/scons-man.html) 。
-
-Luban-Lite 编译框架使用了以下树形结构进行层次化的引用：
-
-![](images/lbl_build_struct.png)
-
-有了 `scons` 框架的加持，Luban-Lite SDK 非常方便的支持 3 种场景的编译：
-
-- Linux 命令行
-- Windows 命令行，含CMD、Git-bash、RT-Thread env环境
-- Windows IDE
-
-## 2.3 Menuconfig 配置框架
-
-Luban-Lite SDK 采用了 Menuconfig 工具来进行配置，提升用户修改配置的易用性和简洁性。
-
-Luban-Lite Menuconfig 配置框架使用了以下树形结构进行层次化的引用：
-
-![](images/lbl_kconfig_struct.png)
-
-值得特别说明的一个概念是在 Linux Kernel 下用户配置是分成两部分来保存的，它的设计思想：
-
-- `.config` 文件保存 `Driver` 配置信息
-- `dts` 文件保存 `Device` 配置信息。
-
-在 Luban-Lite 下，我们使用一个 `.config` 文件同时保存 `Driver` 和 `Device` 配置信息，没有 DTS 配置方式。
-
-为了更好的管理这些配置信息，对于单个模块来说，我们把 `Kconfig` 细分成两个：
-
--  `Kconfig.dev`，存放Device相关的配置参数，比如UART模块的波特率、停止位参数
--  `Kconfig.drv`，存放Driver的通用配置参数，比如UART模块的DMA开关
-
-在命令行下，Luban-Lite SDK的Menuconfig 的配置方法：
-
-```
-$ cd luban-lite
-$ scons --menuconfig                // Linux 命令行下启动 Menuconfig
-$ ....                              // Menuconfig 配置过程
-```
-
-## 2.4 驱动框架
-
-如本文开头所示，AIC Driver 需要支持多种形态下的复用。为了达到这个目的，整个驱动框架会分成 3 个层次：
-
-- RT-Thread Driver Framework：由RT-Thread 提供的驱动模型，我们只需要实现驱动模型中现有的功能即可。
-- AIC Driver Layer：对接RT-Thread Driver Framework的具体实现。
-- AIC HAL Layer：对底层硬件操作的封装，一般是寄存器级别的功能接口。也用于baremetal模式的APP调用。
-
-对于移植一个新的设备驱动来说，我们要开发Driver和HAL两层。
-
-为了保证开发的驱动在多种形态下的复用，我们需要遵循以下的原则：
-
-- 在 AIC Driver Layer 和 AIC HAL Layer 尽可能的使用 AIC OSAL 接口，避免直接调用具体 Kernel 接口。
-- 为了保证可移植性，在 AIC Driver Layer 中除了驱动注册不可避免的需要调用 RT-Thread 接口，在其他地方避免直接调用 RT-Thread 系统接口和 RT-Thread 的相关类型定义。
-- 对于中断注册和互斥锁、信号量的操作，尽可能放在 AIC Driver Layer 中，避免放在 AIC HAL Layer 中。
-
-## 2.5 驱动调试
-
-在menuconfig中，特意为ArtInChip的每个驱动都设置了一个DEBUG开关，用于打开相应模块的调试信息或者调试命令。
-
-并且这些DEBUG开关统一放在一个地方，方便客户查找。在menuconfig中打开测试代码的配置方法：
-
-![](images/driver_debug.png)
-
-## 2.6 驱动测试
-
-在 `bsp/test/` 目录中，ArtInChip实现了一些驱动的测试代码，也可以作为Sample供客户的APP设计参考。
-
-这些测试代码，一般是实现了一个shell命令，在系统启动后可以通过输入shell命令的方式来触发测试代码。
-
-在menuconfig中打开测试代码的配置方法：
-
-![](images/driver_test.png)
-
-# 3. BSP 适配
-
-## 3.1 编译选项
-
-## 3.2 startup 启动
-
-## 3.3 中断和异常
-
-## 3.4 任务切换
-
-## 3.5 libc 调用
-
-## 3.6 内存管理
-
-## 3.7 IO 访问
-
-# 4. AIC OSAL 适配

doc/luban-lite_user_guide_linux.md

@@ -1,109 +0,0 @@
-
-# 1. 环境安装
-
-Luban-Lite SDK 采用了 `scons` 作为编译框架的基础语言，对开发环境的依赖：
-
-- Python2，需安装插件：
-  - scons
-- Python3，需安装插件：
-  - pycryptodomex
-
-
-
-已验证可用的操作系统环境：
-
-- Ubuntu 20.04
-- Windows 10
-
-
-
-# 2. 使用方法
-
-## 2.1 方案加载
-
-在编译一个方案之前，首先需要加载方案的现有配置：
-
-```
-$ cd luban-lite
-$ scons --list-def                  // 列出当前可选的方案配置
-$ scons --apply-def=xxx_defconfig   // 应用上述列表其中一条方案配置
-$ scons --info                      // 查看当前方案的基本配置
-```
-
-## 2.2 Menuconfig 配置
-
-在加载完方案配置后，可以使用 menuconfig 命令来修改当前配置：
-
-```
-$ cd luban-lite
-$ scons --menuconfig                // Linux 命令行下启动 Menuconfig
-$ ....                              // Menuconfig 配置过程
-```
-
-在修改 `Project options` 中的配置时需要注意以下要求：
-
-![](images/lbl_menuconfig_prj.png)
-
-## 2.3 编译
-
-配置完成后，可以使用以下的命令进行编译：
-
-```
-$ cd luban-lite
-$ scons                             // 编译当前方案
-$ scons --verbose                   // 编译当前方案，显示更多详细信息（如GCC命令行参数）
-$ scons -c                          // clean当前方案
-$ ls output/$chip_$board_$kernel_$app/images/$soc.elf   // 编译生成的目标文件
-```
-
-## 2.4 其他命令
-
-```
-$ cd luban-lite
-$ scons --run-qemu           // 运行当前编译出来的qemu目标文件，需要先打开chip->QEMU配置
-$ scons --list-size          // size 命令列出所有 .o 文件的 text/data/bss 各个 section 大小
-$ scons --pkgs-update        // 下载选择的在线 packages
-```
-
-如果需要 Windows IDE 中编译，首先在命令行下使用命令生成当前方案对应的 IDE 方案文件：
-
-```
-$ scons --target=eclipse            // 生成当前方案对应的 eclipse 方案文件
-```
-
-然后使用 Eclipse IDE 打开方案文件进行调试。
-
-# 3. OneStep 增强命令
-
-Luban-Lite 中对命令行中的scons工具进行了封装，将一些高频命令行操作定义了一组快捷命令，统称为OneStep命令。
-
-OneStep命令的设计目标是：任意目录，只需一步。
-
-使用方法：
-
-- 需要先导入脚本onestep.sh
-- 然后在该shell中就可以从任意目录执行以下命令，包括:
-  	- lunch - 选择方案
-  	- m - 编译SDK
-  	- c - clean SDK
-  	- cr - 跳转到SDK根目录等
-
-```
-$ cd luban-lite
-$ source tools/onestep.sh
-$ h
-Luban-Lite SDK OneStep commands:
-  hmm|h                     : Get this help.
-  lunch          [keyword]  : Start with selected defconfig.e.g. lunch mmc
-  menuconfig|me             : Config SDK with menuconfig
-  m                         : Build all and generate final image
-  c                         : Clean all
-  croot|cr                  : cd to SDK root directory.
-  cout|co                   : cd to build output directory.
-  cbuild|cb                 : cd to build root directory.
-  ctarget|ct                : cd to target board directory.
-  godir|gd       [keyword]  : Go/jump to selected directory.
-  list                      : List all SDK defconfig.
-  i                         : Get current project's information.
-```
-

doc/luban-lite_user_guide_windows.md

@@ -1,168 +0,0 @@
-
-# 1. 环境安装
-
-Luban-Lite SDK 采用了 `scons` 作为编译框架的基础语言，Windows 下的对应的各种工具已经存放在 `luban-lite/tools/env/tools` 目录当中，**不需要安装**。
-
-# 2. 命令行使用方法
-
-## 2.1 env 运行环境
-
-直接双击 `luban-lite/win_env.bat` 打开专有的 Windows 的env命令行工具：
-
-![](images/lbl_win_env.png)
-
-后面所有命令都在该命令行工具中进行操作。
-
-## 2.2 CMD 运行环境
-
-直接双击 `luban-lite/win_cmd.bat` 打开 Windows 的CMD命令行工具：
-
-![](images/lbl_win_cmd.png)
-
-后面所有命令的使用和env相同。
-
-## 2.3 工程加载
-
-在编译一个工程之前，首先需要加载工程的现有配置：
-
-```
-$ cd luban-lite
-$ scons --list-def                  // 列出当前所有的工程默认配置
-$ scons --apply-def=xxx_defconfig   // 加载应用上述列表其中一条工程配置
-```
-
-和工程相关的命令还有：
-
-```
-$ scons --save-def                  // 手工保存当前工程配置  
-$ scons --info                      // 列出当前工程的基本配置
-```
-
-## 2.4 Menuconfig 配置
-
-在加载完工程配置后，可以使用 menuconfig 命令来修改当前配置：
-
-```
-$ cd luban-lite
-$ scons --menuconfig                // Linux 命令行下启动 Menuconfig
-$ ....                              // Menuconfig 配置过程
-```
-
-在修改 `Project options` 中的配置时需要注意以下要求：
-
-![](images/lbl_menuconfig_prj.png)
-
-## 2.5 编译
-
-配置完成后，可以使用以下的命令进行编译：
-
-```
-$ cd luban-lite
-$ scons                             // 编译当前工程，简洁输出
-$ scons --verbose                   // 编译当前工程，详细输出
-$ scons -c                          // 清理当前工程
-$ ls output/$chip_$board_$kernel_$app/images/$soc.elf   // 编译生成的目标文件
-```
-
-## 2.6 其他命令
-
-```
-$ cd luban-lite
-$ scons --run-qemu                  // 运行当前编译出来的qemu目标文件
-$ scons --list-size                 // size 命令列出所有 .o 文件的 text/data/bss 各个 section 大小
-$ scons --pkgs-update               // 下载选择的在线 packages
-```
-
-# 3. OneStep 增强命令
-
-Luban-Lite 中对命令行中的scons工具进行了封装，将一些高频命令行操作定义了一组快捷命令，统称为OneStep命令。
-
-OneStep命令的设计目标是：任意目录，只需一步。
-
-在CMD、或者env窗口启动后，OneStep命令已经生效，在其中可以从任意目录执行以下命令，包括:
-
-- lunch - 选择方案
-- m - 编译SDK
-- c - clean SDK
-- cr - 跳转到SDK根目录等
-
-![](images/win_onestep.png)
-
-# 4. Eclipse IDE
-
-Luban-Lite 支持使用 Eclipse IDE 来进行调试，首先下载最新版本的 [Eclipse IDE for Embedded C/C++ Developers](https://www.eclipse.org/downloads/download.php?file=/technology/epp/downloads/release/2023-03/R/eclipse-embedcpp-2023-03-R-win32-x86_64.zip) 。
-
-## 4.1 生成 Eclipse 工程
-
-> 特别注意：首先确保工程已经在命令行环境下已经正确配置并且能成功编译以后，再使用下述命令一键生成工程对应的 Eclipse 工程文件。在工程配置发生改变以后，需要重新在命令行下编译成功后再重新生成 Eclipse 工程文件。
-
-使用命令生成当前工程对应的 Eclipse 工程文件：
-
-```
-$ cd luban-lite
-$ scons --target=eclipse            // 生成当前工程对应的 Eclipse 工程文件
-```
-
-生成的 Eclipse 工程文件存储在 `luban-lite/output/xxxx/project_eclipse` 目录：
-
-```
-$ ls -a output/d21x_demo100-nand_rt-thread_helloworld/project_eclipse
-./  ../  .cproject  .project  .settings/
-```
-
-为了方便用户使用 Eclipse IDE 来添加自己的代码，还增加了一条命令来生成一个完整的 Eclipse SDK 软件包。该命令会把用户需要的所有源文件和库文件都独立的拷贝一份：
-
-```
-$ scons --target=eclipse_sdk        // 生成当前工程对应的 Eclipse SDK 工程
-```
-
-生成的 Eclipse 工程文件存储在 `luban-lite/output/xxxx/project_eclipse_sdk` 目录。因为所有需要的文件都已经拷贝，所以 `project_eclipse_sdk` 目录已经是一份独立的 SDK 了，可以拷贝到任何路径下进行调试。
-
-## 4.2 导入 Eclipse 工程
-
-打开下载的 `Eclipse IDE for Embedded C/C++ Developers`，通过菜单 `File -> Import -> Existing Projects into Workspace` 来导入上一步创建的 Eclipse 工程：
-
-![](images/eclipse_import_proj.png)
-
-## 4.3 编译
-
-在 `Project Explorer` 中选择成功导入的工程，在右键菜单中选择 `Build Project` 即可对整个工程进行编译。
-
-![](images/eclipse_build_proj.png)
-
-编译生成的目标文件在 `luban-lite/output/xxxx/project_eclipse/Debug` 目录：
-
-```
-$ ll output/d21x_demo100-nand_rt-thread_helloworld/project_eclipse/Debug/
- d21x.bin
- d21x.elf                           // 调试需要的 elf 文件
- d21x.map
- d21x_demo100_nand_page_2k_block_128k_v1.0.0.img    // 烧录需要的 img 文件
- d21x_demo100_nand_page_4k_block_256k_v1.0.0.img
-```
-
-## 4.4 调试
-
-Eclipse 通过 JTAG 调试器在线调试还需要以下关键组件：
-
--  `ddr_init.json`。修改该文件中的 jtag 值为 1。
--  `AiBurn`。烧录软件，把上述固件烧录到单板。
--  `CKLink`。JTAG 调试器。
--  `T-HeadDebugServer`。调试器在 PC 端的代理，以 GDB-Server 的形式提供调试服务。
-
-Eclipse 在线调试的具体步骤如下：
-
-- Step 1：编译 SDK ，生成镜像 img 文件。
-
-- Step 2：安装 `AiBurn` 软件，使用 AiBurn 将 `ddr_init_only.img` 固件烧录到单板。烧录成功后，每次单板上电和复位后都会自动把 DDR 初始化好。
-
-- Step 3：启动 `T-HEADDebugServer`，配置 GDB-Server 端口号：
-
-    ![](images/debug_server.png)
-
-- Step 4: Eclipse 中创建对应的 `Debug Configuration`。通过菜单 `Run -> Debug Configurations` 给编译成功的工程新建一个对应的调试配置：
-
-    ![](images/eclipse_debug_config.png)
-
-经过上述配置以后，就可以方便的在 Eclipse 下进行在线调试了。
-