CHAPTER 5 - Documentation

Abstract

Documentation is the most important collaborative tool that conveys information from hardware engineers necessary for firmware engineers to write their device drivers. Proper documentation is the most important tool for collaborative development between hardware and firmware engineers. Firmware engineers need it to write device drivers for the blocks. Hardware engineers need it to convey their designs to others. Both sides use it as they develop their respective components. Quality documentation is essential for hardware and firmware engineers to do their jobs. In this chapter, types of documents, document management, reviews, and content are discussed. Documentation helps new firmware engineers to quickly get acquainted with the block. This chapter discusses the importance of having complete and accurate documentation for the block and covers several aspects of what the content should be, such as high-level descriptions, reference and tutorials, registers, interactions, and state machines. Writing the document early in the design cycle for the block, so that firmware engineers can review it and make comments is also encouraged. Concept of block documentation and chip-specific implementation are also discussed in this chapter.