Annotation & Documentation

Document your circuit designs with comments, remarks, and structured documentation.

Introduction

It is highly recommended that comments and documentation be added to the Network Description (NET) file. This will not only make it easier to keep track of decisions made in describing a circuit, but it is immeasurably helpful to anyone else who may need to understand this file.

SNL provides three ways to annotate a file.

The REMARK Keyword (REM, R)

REMARK is a SNL keyword that allows a message to be sent to the console while the circuit is being compiled. The REMARK should be placed within the type block requiring the annotation (i.e. below the type statement). Remarks are displayed at the console during circuit compilation. SIMIC ignores remarks that are not in a !LOGICAL section. Textual case within a REMARK statement is preserved.

Basic Syntax

REMARK=<message text>
Case Preservation: Unlike most SNL text, case is preserved in a REMARK. This allows you to use proper capitalization and mixed case for readability.

Line Continuation in Remarks

The dollar sign ($) continuation character is not supported for remarks. In order to continue a remark beyond one line, a REMARK keyword must start the remark on the following line. The following example illustrates remark continuation. 

TYPE=my8590 I=i1,i2,i3 O=o1,o2
  P=p1 T=8590 I=i1,i2,i3 O=o1,o2

  REMARK= Caution: the 8590 cell is obsolete,
  REMARK= please use the 8690 cell in all
  REMARK= new designs.

Display Behavior

During circuit compilation, only remarks in type blocks actually used in the circuit will be displayed, and then only once, no matter how many times the type is instantiated.

Example Output During Compilation

>>: get type=processor
Main Get Network : PROCESSOR
* Remark: Caution: the 8590 cell is obsolete,
* Remark: please use the 8690 cell in all
* Remark: new designs.
GET completed, Circuit totals: Parts = 157; Signals = 342

When to Use REMARK

The COMMENT Keyword (COM, C)

Frequently, brief commentary can be very helpful. If the commentary will only occupy a few lines, the COMMENT keyword is appropriate. Comments are ignored by SIMIC.

The dollar sign ($) continuation character is not supported for comments. All text from the COMMENT= keyword to the end of the physical line is ignored. The COMMENT keyword-field can appear anywhere in the Network Description File; either at the end of part, type, or delay statements, or in lines between these statements.

Unlike remarks, comments are not displayed during circuit compilation.

Basic Syntax

COMMENT=<comment text>
C=<comment text>

Usage Examples

C= ***************************************
C= * An Example of some ways to include *
C= * commentary.                         *
C= ***************************************

C= Comments may be put anywhere in a NET file,
C= as long as you remember that '$' is ignored
C= in comments, and that all comments begin
C= with the COMMENT keyword.

!LOGICAL C= The network description section

TYPE=buf I=in O=out C= Another comment!

Inline Comments

Comments can be placed at the end of any SNL statement to document that specific line: 

t=full-adder i=a,b,cin o=sum,cout  c= 1-bit full adder

p=xor1 t=exor i=a,b o=xor1_out     c= Sum of first two inputs
p=xor2 t=exor i=xor1_out,cin o=sum c= Final sum output
p=and1 t=and i=a,b                 c= Carry from a and b
p=and2 t=and i=xor1_out,cin        c= Carry from sum and cin
p=or1  t=or i=and1,and2 o=cout     c= Final carry output

COMMENT vs REMARK

Feature COMMENT REMARK
Display during compilation No Yes
Placement Anywhere in file Within type blocks (!LOGICAL section only)
Case preservation No (converted to uppercase) Yes (case preserved)
Inline usage Yes (end of statements) No (separate lines only)
Best for Code documentation User warnings and notifications

The $= Continuation Comment

Since dollar signs ($) are ignored in comments, a special construct is provided in order to put comments inside continued statements. If an equals sign (=) is appended to the $ continuation character, then the remainder of the line will be treated as a comment and the statement will properly continue on the next physical line. If the = is omitted, then a warning will be issued if anything but whitespace is found before the physical end of line.

Basic Syntax

<statement text> $= <comment text>
<continuation of statement>

Example: Documenting Continued Statements

TYPE=johnson_counter $= type block name
  I=clock,reset $= Inputs for this type
  O=q1,q2,q3 C= Outputs for this type

Note that if the last comment used the $= comment instead of the C= comment, then a blank next line would have been required to properly terminate the statement.

Key Differences

Example Requiring Blank Line

TYPE=processor $= Main processor type
  I=clk,data,addr $= Input signals
  O=ready,output $= Output signals
                    c= Blank line terminates the TYPE statement
p=alu t=arithmetic i=...

When to Use $= Comments

The !DOCUMENTATION Directive (!DOC)

The SNL !DOCUMENTATION directive provides the opportunity to make extensive comments in the Network Description (NET) file without having to begin each line with the COMMENT= keyword. SIMIC will ignore everything from the !DOCUMENTATION statement to the next section header (!LOGICAL, !DELAY, etc.) or the end of the file.

Basic Syntax

!DOCUMENTATION

<Free-form text, no keywords needed>
<Can span multiple lines>
<No special formatting required>

!LOGICAL  c= Resume normal SNL processing

Complete Example

!DOCUMENTATION

Many designers find it a tedious and distracting task to document
their work, despite the obvious benefits it provides to themselves and
to other designers.

This circuit implements a 3-stage Johnson counter with the following
characteristics:
  - Synchronous operation on positive clock edge
  - Active-low asynchronous reset
  - Output stages Q1, Q2, Q3

Design Notes:
  - The feedback path from Q3 through the inverter creates the
    characteristic Johnson counter sequence: 000 → 001 → 011 → 111
    → 110 → 100 → 000
  - Total propagation delay from clock to outputs is approximately
    15ns with standard cell library

Author: J. Smith
Date: March 2025
Revision: 1.2

!LOGICAL C= Start of Network Description
!FORMAT P= T= I= O=

t=johnson_counter i=clock,reset o=q1,q2,q3

buf     and     reset               rbuf
f1      dcf     rbuf,one,clock,back q1
f2      dcf     rbuf,one,clock,q1   q2
f3      dcf     rbuf,one,clock,q2   q3
back    inv     q3

!DOCUMENTATION

Additional documentation can appear between type definitions,
or at the end of the file. This makes it easy to maintain
design documentation alongside the circuit description.

!LOGICAL

c= More type definitions could follow here...
Important: Since a directive declaring a new section (!LOGICAL or !DELAY) implicitly terminates the !DOCUMENTATION section, the first character in each line of annotation should never be an exclamation mark.

Benefits of !DOCUMENTATION

Where to Place !DOCUMENTATION Blocks

Sectioning Your Documentation

!DOCUMENTATION
================================================================================
PROJECT: High-Speed ALU
MODULE:  8-bit Arithmetic Logic Unit
================================================================================

OVERVIEW:
This module implements a full 8-bit ALU with the following operations:
  - ADD, SUB (with carry/borrow)
  - AND, OR, XOR, NOT
  - Shift left/right (logical and arithmetic)
  - Zero flag, Negative flag, Overflow flag

ARCHITECTURE:
  [Detailed explanation here...]

REVISION HISTORY:
  v1.0 - Initial design (Jan 2025)
  v1.1 - Added overflow detection (Feb 2025)
  v1.2 - Optimized carry chain (Mar 2025)

!LOGICAL
c= Begin circuit topology...

Best Practices for Annotation

Choose the Right Tool

Use This When You Need
C= Inline comments on specific lines of code
$= Comments within multi-line continued statements
REMARK= Warnings displayed during compilation
!DOCUMENTATION Multi-paragraph design documentation

Documentation Guidelines

  1. Document the "why" - Explain design decisions, not just what the code does
  2. Use consistent style - Choose a commenting convention and stick to it
  3. Keep it current - Update documentation when you change the design
  4. Be concise - Inline comments should be brief; use !DOCUMENTATION for long text
  5. Mark sections - Use visual separators (===, ---, etc.) in documentation blocks

Example: Well-Documented Design

!DOCUMENTATION
Module: Full Adder (1-bit)
Description: Combinational logic for single-bit addition with carry

This design uses the traditional sum-of-products approach rather
than XOR trees to minimize propagation delay in the target ASIC
library where XOR gates have higher delay than AND/OR combinations.

!LOGICAL

c= ========================================
c= Full Adder - Type Definition
c= ========================================

t=full-adder i=a,b,carry-in o=sum,carry-out

c= Sum generation (XOR of all three inputs)
p=xor1 t=exor i=a,b o=xor1_out           c= Intermediate XOR
p=xor2 t=exor i=xor1_out,carry-in o=sum  c= Final sum

c= Carry generation (any two inputs high)
p=and1 t=and i=a,b                       c= Carry from A and B
p=and2 t=and i=a,carry-in               c= Carry from A and Cin
p=and3 t=and i=b,carry-in               c= Carry from B and Cin
p=or1  t=or i=and1,and2,and3 o=carry-out c= Combined carry out