# Presentation: 182535

## L1FE Documentation-A Firmware Documentation Example

- Carsten Noeding
- University of Mainz

## Documentation?

**Aim:**
**Provide “good” documentation for **_**all**_** firmware designs in a “more or less” coherent way**
**Why is it necessary?**
**People who are now responsible for developing/writing firmware and protocols won’t be around forever**
**Whoever is responsible for the system in a couple of years time doesn’t want to re-invent the wheel just because some additional functionality is needed or obsolete**
**To have an up-to-date description of the implemented functionality and the protocols**
**Outsiders should be able to understand the system**

## Documentation!

**We need two types of documentation:**
**Within the code (as comments)**
**In an additional descriptive paper (more elaborated with overview diagrams etc.)**
**Comments on...**
**Good documentation**
**Logical division of code in independent components (files)**
**Description of entities**
**Description of functionality/algorithm**
**Description of signals used in the code**
**Why do I need them?**
**Where are they used?**
**“****More of less” coherent way**
**Not enough time/manpower to develop a standard, therefore everybody is free to do what he wants**
**But:**** people should have at least a basic starting point to get ideas from and to refer to******** L1FE******** Carsten’s Word template**

## Documentation example: L1FE

**L1FE describes the front end code used in all firmware designs which are part of the Level 1 CTT:**
**L1 CTOC, CTTT (not DFEA)**
**Functionality:**
**Synchronize input data**
**Store inputs in L1 pipeline**
**Parity correction**
**L3 sender**
**Common basic design, adjustments (e.g. number of links, depth of L1 pipeline)  are done using configuration parameters which are controlled by two VHDL packages**
**L1FE is published as D0-Note #3881 (available from the web)**
**(L1FE is basis for L2 front end)**

## L1FE Documentation (1)

**Document structure:**
**Introduction:**
**Description of tasks/implemented functionality**
**Code location and organization**
**Where can one find the code?**
**Basic structure of the code**
**Block diagrams simplify understanding of code and its structure**
**Configuration parameters (stored in VHDL package)**
**Description of individual parameters and their usage**
**Description of individual components**
**Functionality**
**Description of each entity (=incoming and outgoing signals)**
**Description of L1FE top level**
**Overview of how the components interact with each other**
**(How to use the code)**
**Outlook**
**Remaining tasks/problems**
**Pitfalls**

## L1FE Documentation (2)

**Document layout:**
**Division into self-contained chapters**
**Study of introduction gives enough information to understand basic tasks of design**
**More detailed information is provided in later chapters**
**Code is described in a bottom up approach**
**Very detailed, in the beginning confusing, but only logical approach**
**Not so nice:**
**Document is ps file (pdf is better choice)**
**Missing:**
**Timing diagrams**
**Detailed description of protocols and bit fields**
**Appendix**
**Short description of protocols**
**Coding convention**

## Word Template

**Based on L1FE document I’ve generated a Word template for general use**
**Available at:**_**[\\D0server4\projects\VHDL\Test_Code\Carsten](file://D0server4/projects/VHDL/Test_Code/Carsten)**_
**Name:****Documentation_Template.doc**
**Very straightforward to use, just add text/graphics and update the contents**

## Conclusion (1)

**Documentation is absolutely necessary and worth spending time on it!**
**Documentation has to be written by the person who’s in charge of the firmware implementation**
**Only she/he knows what functionality has been implemented**
**Only she/he knows why pipeline stages have to be at that certain point in the code**
**Needed documentation:**
**Comments in the code**
**Each FPGA firmware should have an accompanying document describing**
**Overall code structure**
**Explanation of components**
**Explanation of crucial signals (=signals which trigger other components in the design)**
**Implemented functionality**
**Protocols**

## Conclusion (2)

**L1FE is a good example for documentation of firmware and can be used as a template**
**For Word users a template based on L1FE is available**
**Possible synergy effects simplify documentation expense:**
**Same overall structure:**
**Synchronization; Algorithm; Sender**
**The same code is used with minor modifications in different designs**
**L2 CFT track sorting algorithm is used in L2 CTOC, STOV, STSX etc.**
**L3 sender**
**Basic ideas are often the same, but encoded  slightly different**
**Synchronization**
**In addition I’d like to see:**
**Timing diagrams (make it easier to understand what’s actually going on)**
**Informal review to ensure that documentation is understandable **