内核子系统文档撰写方法
1.前言
本文档主要讲述如何去撰写一个内核子系统分析文档。内容主要来源于对如下网站文章的学习与总结：
一般来讲比较全面的分析一个内核子系统，大概包含如下几个部分：
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的角度介绍
介绍怎么借助framework管理相关的SOC资源。换句话说，就是怎么编写一个driver。
（1） 主要数据结构和API
主要数据结构为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.进一步说明
对于如上给出的文档结构，有如下几点个人实践的经验来供参考：
1. 本文给出的是host-bus-device结构的内核子系统撰写的基本思路，在实际文档撰写时，有的子系统可能不是host-bus-device的结构，也可以抽象出相应的对象，理清对应的数据结构和API。如从大的方面仍然可以区分成provider(供上层调用)部分、consumer(调用其它更低层模块)部分以及core内部实现部分；
2. 理清流程是学习内核子系统非常重要的一点，可以遵循先硬件后软件，先抽象后具体，结构与流程相结合的原则进行撰写，而且这样更符合常人的思维模式；
3.可以通过头文件来找到相应的数据结构和API，一般我们在介绍API的时候，可以先不涉及API内部的实现，以求先从广度上对系统有所呈现；
4. 最好是先介绍host和device相关的结构和流程，这样可以先从core中过滤掉部分内容，之后再介绍core中相关结构和流程
总而言之，内核子系统的分析文档撰写的目的是为了向读者更加清晰的呈现内核子系统的架构和特性，以利于对子系统有更深入的理解，只要是撰写的文档能够满足这个需求就是好文档。
接下来，后面将尝试按如上的方法来进行。
