Documentation Requirements

Block Diagrams for Synthesizeable VHDL Descriptions

Creating two independent versions (textual and graphical) of a single design is poor practice since it allows the two versions to get out of step with each other. However, these diagrams will help you visualize the hardware that will be synthesized by your description and should make you a more effective designer. Hand-drawn diagrams are sufficient.

Your diagrams should include the correct graphical equivalent for each of the following VHDL constructs:

• input and outputs ports: should show the bus width and the signal names
• internal signals (those declared in architectures): should show the bus width and the signal names
• selected assignments or ROMs: draw as a multiplexer (if one or more of the multiplexer inputs is a signal) or as a ROM (if all "inputs" are constants). Label the name and bus width of the select (or address) signal. ROMs implementing lookup tables should be described in tabular format elsewhere. Each input to a multiplexer should show the corresponding select input value.
• conditional assignments: draw a tree of 2-way multiplexers
• expressions: expressions should show each operator using the appropriate symbol (gates, blocks for adders, comparators, etc).
• registers: label the input, output and clock names and signal widths
• other connections: label the signals names and bus widths
• omit the bus width when it is 1

Assembly-Language Programs

As a minimum, include the following:

• a comment block at the top of the file describing:
  • the name of the file (e.g. asg2.c)
  • the purpose of the program
  • the author (your name and students number)
  • the date it was written
• a comment block before each function describing:
  • the inputs and the allowable range of values for each input
  • the outputs (return values or other results)
  • what the function does including how it handles invalid inputs (e.g. error return codes)
  • what registers are modified by the function (or an indication that a well-defined interface convention is being followed)
  • any side-effects (for example, global memory or processor flags that are altered)
• a block comment for the each major section of code explaining what it does
• in-line comments for every:
  • compare-and-branch explaining it's purpose:

    	; skip lower-case characters
    
    	; return when ESC key entered
    
    	; repeat until end of file
    

  • every non-obvious line of code (explaining the PURPOSE of the code -- answer WHY, not HOW):

    	BAD:
    
    	xor	ax,ax		; exclusive-OR ax with ax	
    	mov	count,ax	; move ax to count
    
    	GOOD:
    
    	xor	ax,ax		; reset error count
    	mov	count,ax