Documentation Requirements
Assembly-Language Programs
Assembly-language programs need to be heavily commented because
assembly code is much harder to understand than code in a
higher-level language. However, quality is more important than
quantity -- don't use meaningless, irrelevant (``cute'') or
incorrect comments.
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
The in-line comments should be a high-level explanation of your
algorithm similar to pseudo-code rather than an explanation of
the effects of each instruction. It should be possible for
someone to figure out what your code does simply by reading the
comments.
Block Diagrams for Synthesizeable VHDL Descriptions
In this course you are required to draw a block diagram for each
VHDL description that you prepare as part of an assignment or
lab.
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
EECE 379 Home Page