L1FE Documentation - A Firmware Documentation Example

1
L1FE Documentation-A Firmware Documentation
Example

• Carsten Noeding
• University of Mainz

2
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 wont
  be around forever
• Whoever is responsible for the system in a couple
  of years time doesnt 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

3
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?
  Carstens Word template

4
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)

5
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

6
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

7
Word Template

• Based on L1FE document Ive generated a Word
  template for general use
• Available at\\D0server4\projects\VHDL\Test_Code\
  Carsten
• NameDocumentation_Template.doc
• Very straightforward to use, just add
  text/graphics and update the contents

8
Conclusion (1)

• Documentation is absolutely necessary and worth
  spending time on it!
• Documentation has to be written by the person
  whos 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

9
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 Id like to see
• Timing diagrams (make it easier to understand
  whats actually going on)
• Informal review to ensure that documentation is
  understandable