关于内核子系统文章撰写的方法

[转]http://www.wowotech.net

1.前言

本文档主要讲述如何去撰写一个内核子系统分析文档。内容主要来源于对如下网站文章的学习与总结：

http://www.wowotech.net

一般来讲比较全面的分析一个内核子系统，大概包含如下几个部分：

1）framework的整体介绍，包括基础知识、软件框架、API汇总；

2）从Provider的角度，介绍怎么借助framework管理模块相关的SOC资源。换句话说，就是怎么编写一个模块driver。

3）从Consumer的角度，介绍framework为使用者提供了哪些功能、哪些API，以及怎样利用framework编写程序。

4）从内部实现的角度，分析framework的实现逻辑。

2.包含的主要部分

2.1 framework整体介绍

（1）基础知识

阐述要理解本模块，需要具备的背景知识，如需要理解i2c子系统，则需要对i2c协议有相关的了解。

此部分可以专门单独列为一章阐述

（2）硬件框架

一般给出硬件的框图架构，并对框图中相关的实体和接口给出解释

（3）软件框架

给出软件的框图架构，并对组成软件框图架构的实体文件及它们之间的关联进行说明，也可以联系硬件框架给出相关的解释

2.2 从provider的角度介绍

主要数据结构为maser驱动使用的结构体，如对于i2c controller来说，对应为i2c_adapter，则主要介绍i2c_adapter，i2c_algorithm, i2c_msg等；
主要API则是master驱动使用的API，如对于i2c_adapter为i2c_add_adapter等；

实际上我们可以通过阅读内核driver源码中相关示例代码来找出主要的数据结构和API
（2）主要的软件流程
主要是master驱动关键软件流程，如对于i2c_adapter的注册流程等，还可以从其它角度如设备驱动模型的角度来讲述软件流程
（3）编写provider驱动的方法
在这里主要指master驱动，如对i2c子系统，则为i2c controller驱动

2.3 从Consumer的角度

介绍framework为使用者提供了哪些数据结构、哪些API，以及怎样利用framework编写程序。

（1）关键数据结构和API

主要是slave驱动所使用的数据结构和API

实际上我们可以通过阅读内核driver源码中相关示例代码来找出主要的数据结构和API

（2）主要软件流程

主要是slave驱动中涉及的软件流程

（3）编写consumer驱动的方法

介绍slave驱动的编写方法

2.4 从内部实现的角度

一般是介绍framework中主要的数据结构、API及软件流程，偏向于机制方面

（1）主要数据结构和API

介绍framework的主要结构体及API

（2）关键流程

介绍framwork的主要流程

3.进一步说明

对于如上给出的文档结构，只是给出内核子系统撰写的基本思路，在实际文档撰写时，完全可以根据子系统的特点和需求进行更改或删减。

可以遵循先硬件后软件，先抽象后具体，先结构后流程的原则进行撰写，这样更符合常人的思维模式。

总而言之，内核子系统的分析文档撰写的目的是为了向读者更加清晰的呈现内核子系统的架构和特性，以利于对子系统有更深入的理解，只要是撰写的文档能够满足这个需求就是好文档。

接下来，后面将尝试按如上的方法来进行。

4. 参考文档

[1] http://www.wowotech.net/sort/comm