|
   
Next: Naming Conventions
Up: No Title
Previous: Introduction
Code in VIS is divided into packages. A package is a group of
source (.c) and header files (.h) in a subdirectory
centered around either a function (e.g., the BDD variable ordering
package ``ord''), or a data structure (e.g., the network package
``ntk''). Each package has a short two- to five-letter name,
called the short package name, placed in front of all filenames and
external identifiers related to the package. This name may appear in
all lowercase, or with its first letter capitalized, written as package and Package respectively.
Each package should contain two header files. The external header
file, named package.h, defines features visible from
outside the package. The internal header file, named packageInt.h, defines features used in multiple files inside
the package, but not outside. If necessary, a third header file,
named packagePort.h, can be included. This should contain
definitions for the package that hide differences between systems. No
additional header files should be used-everything should go into the
two main headers.
The names of C source files begin with the short package name followed
by a series of English words (or abbreviations) with their first
letters capitalized. No filename can be longer than fifteen
characters. (This is a limitation imposed by the library archive
program ar.)
Listed below are the names of files in an example package called rng. It has an external header file, an internal header file, a
header file for portability, and two .c files. Other packages
may have more .c files, but should not have more .h files.
Both the internal and external headers follow the same structure:
- A CHeaderFile structured comment describing the contents
of the file, described in Section 2.4.1. The
external header file's comment should be directed toward programmers
who will use the package; the internal header file's comment should
be directed toward maintainers. Both should be self-contained.
- #ifdef and #define statements that prevent this
from being #included twice. In the external header file, the
name should be an underscore followed by the short name of the
package in all caps, e.g., _NTK. In the internal header
file, the name should be an underscore followed by the short name of
the package followed by ``INT'', e.g., _NTKINT.
- In the internal header file, #include the external header
files from other packages that are directly needed for
internal or static code, but are not needed for external code. In
addition, packageInt.h should include package.h.
package.h should include those external header files
that are directly needed for the structures and functions that
package exports. In this manner, any package that includes
package automatically gets all of the packages that are needed
to compile package.
- Declarations of non-functions, each type in a separate section
with a leading comment.
- An automatically-generated section surrounded by AutomaticStart and AutomaticEnd comments. Anything between
these comments is removed by the automatic prototype extractor, so
the programmer should put nothing here.
- The #endif directive for the leading #ifdef.
A template C header file that includes all the required sections and
comments is shown below.
/**CHeaderFile*****************************************************************
FileName [ required ]
PackageName [ required ]
Synopsis [ required ]
Description [ optional ]
SeeAlso [ optional ]
Author [ optional ]
Copyright [ required ]
Revision [ $Id: node3.html,v 1.1.1.1 2001/04/26 21:30:15 vis Exp $ ]
******************************************************************************/
#ifndef _
#define _
/*---------------------------------------------------------------------------*/
/* Constant declarations */
/*---------------------------------------------------------------------------*/
/*---------------------------------------------------------------------------*/
/* Type declarations */
/*---------------------------------------------------------------------------*/
/*---------------------------------------------------------------------------*/
/* Stucture declarations */
/*---------------------------------------------------------------------------*/
/*---------------------------------------------------------------------------*/
/* Variable declarations */
/*---------------------------------------------------------------------------*/
/*---------------------------------------------------------------------------*/
/* Macro declarations */
/*---------------------------------------------------------------------------*/
/**AutomaticStart*************************************************************/
/*---------------------------------------------------------------------------*/
/* Function prototypes */
/*---------------------------------------------------------------------------*/
/**AutomaticEnd***************************************************************/
#endif /* _ */
A C source file contains the following:
- A CFile structured comment describing the contents of the
file, described in Section 2.4.2.
- #include "packageInt.h".
- An RCS string, used by the revision control system described in
Chapter 5.
- Declarations and definitions of non-functions, each type in a
separate section with a leading comment.
- An automatically-generated section surrounded by AutomaticStart and AutomaticEnd comments. Anything between
these comments is removed by the automatic prototype extractor, so
the programmer should put nothing here.
- Three sections, each with a leading comment, separated into
definitions for
- Functions visible outside the package
- Functions visible to all files within the package only
- Functions visible to the file only
A template C source file that includes all the required sections and
comments is shown below.
/**CFile***********************************************************************
FileName [ required ]
PackageName [ required ]
Synopsis [ required ]
Description [ optional ]
SeeAlso [ optional ]
Author [ optional ]
Copyright [ required ]
******************************************************************************/
#include "Int.h"
static char rcsid[] = "$Id: node3.html,v 1.1.1.1 2001/04/26 21:30:15 vis Exp $";
USE(rcsid);
/*---------------------------------------------------------------------------*/
/* Stucture declarations */
/*---------------------------------------------------------------------------*/
/*---------------------------------------------------------------------------*/
/* Type declarations */
/*---------------------------------------------------------------------------*/
/*---------------------------------------------------------------------------*/
/* Variable declarations */
/*---------------------------------------------------------------------------*/
/*---------------------------------------------------------------------------*/
/* Macro declarations */
/*---------------------------------------------------------------------------*/
/**AutomaticStart*************************************************************/
/**AutomaticEnd***************************************************************/
/*---------------------------------------------------------------------------*/
/* Definition of exported functions */
/*---------------------------------------------------------------------------*/
/*---------------------------------------------------------------------------*/
/* Definition of internal functions */
/*---------------------------------------------------------------------------*/
/*---------------------------------------------------------------------------*/
/* Definition of static functions */
/*---------------------------------------------------------------------------*/
Documentation for packages, functions, macros etc. is embedded within
C source and header files in ``structured comments,'' which can be
understood by programs. For example, the extdoc program
described in Section 5.2 can extract this documentation
and format it for a text file or in HTML format suitable for the World
Wide Web. The extproto program described in
Section 5.1 also uses these comments to extract
function declarations.
Any definition (e.g., functions, macros, structures) must be preceded
by a structured comment that indicates information about its
functionality, use, etc. We suggest you write this documentation for
your package before you write its code. This ensures the
documentation gets written and allows you to see the package's
complete interface.
A structured comment begins with a line beginning with ``/**''
(i.e., with no leading whitespace). The type of the comment (e.g.,
CFile, Function) is an alphanumeric string on the first
line that may be embedded in asterisks or whitespace. A structured
comment ends with a line containing ``*/''.
Between the start and end lines are field-value pairs separated by
whitespace. A field is an alphanumeric string and a value is a square
bracket-enclosed string that may include newlines. A value may not
include a close-bracket unless it is escaped with a backslash, i.e.,
"5C]. The order of field-value pairs in a structured
comment is irrelevant, but they must appear in pairs. A field-value
pair named Comment is ignored by all automatic extraction tools,
allowing comments within structured comments.
Certain values, such as the Synopsis and Description
fields, may include HTML
directives. These include <pre> and </pre>, which
begin and end a section of preformatted text, i.e., that will be
displayed with spaces and newlines intact, and <p>, which
indicates a paragraph break.
The CHeaderFile structured comment at the beginning of a header file
contains the following fields, some of which are optional:
example CHeaderFile comment is shown below.
/**CHeaderFile***************************************************************
FileName [ rng.h ]
PackageName [ rng ]
Synopsis [ Manipulation of integer ranges, e.g., 5-7. ]
Description [ Routines for creating, adding to, querying, and
deleting ranges. ]
SeeAlso [ rngInt.h ]
Author [ Gitanjali Swamy ]
Copyright [ Copyright (c) 1994-1996 The Regents of the Univ. of California.
All rights reserved. ]
Revision [$Id: node3.html,v 1.1.1.1 2001/04/26 21:30:15 vis Exp $]
******************************************************************************/
The CFile structured comment at the beginning of a source file
contains the following fields, some of which are optional:
example CFile comment is shown below.
/**CFile*********************************************************************
FileName [ rngUtil.c ]
PackageName [ rng ]
Synopsis [ Memory and read/write utilities for the Range package ]
Description [ Contains routines for creating and deleting ranges,
and asking questions of them ]
SeeAlso [ rngUtilInt.c ]
Author [ Gitanjali Swamy ]
Copyright [ Copyright (c) 1994-1996 The Regents of the Univ. of California.
All rights reserved. ]
******************************************************************************/
The fields in the Function structured comment are
document a function's parameters and return type, insert standard
/* */-enclosed C comments after each parameter and after
the return type. Parameter comments should follow the parameter name,
before the comma or close-parenthesis. A return type comment should
be between the return type and the function name. All of these
comments are optional.
If the function can be invoked directly from the command line, it
should include the Command fields. The sentence in the CommandSynopsis field should be an imperative command, e.g.,
``read a network'' instead of ``reads a network.'' Omit a
trailing period. The CommandArguments field should have
symbolic names enclosed in angle brackets (e.g., <list>), and
optional arguments enclosed in escaped square brackets (e.g., "5C[ -v "5C]). The CommandDescription field
should fully document the command, and may use arbitrary HTML
constructs.
An example Function comment with partial definition is shown
below.
/**Function*******************************************************************
Synopsis [ Check if two ranges overlap ]
Description [ If any integer is common to both of the given ranges,
return TRUE, otherwise return FALSE. ]
SideEffects []
SeeAlso [ Rng_RangeOrWithRange ]
******************************************************************************/
static boolean /* TRUE if the ranges overlap */
RangeOverlap(
Rng_Range_t * range1 /* first range */,
Rng_Range_t * range2 /* second range */)
{ /* ... */ }
The Macro fields in a structured comment are identical to those
for Function. It is intended that macros are
indistinguishable from functions.
To document the arguments in a macro, insert standard C comments
before each argument name to give the type, and after each argument
name (but before a comma or close-parenthesis) to comment the
argument. These comments are optional.
An example Macro comment with a partial definition is shown
below.
/**Macro**********************************************************************
Synopsis [ Return the lower number in a range ]
SideEffects []
SeeAlso [ Rng_RangeSetEnd ]
******************************************************************************/
#define /* int */ Rng_RangeReadEnd( \
/* Rng_Range_t * */ range /* argument comment */ \
) \
(((range->begin) =< RNG_MAX)? (range->begin): RNG_MAX)
Struct and Variable structured comments have identical
fields:
comment the fields in a structure definition, place a C comment
after each field definition, after the semicolon. These comments are
optional.
Example Struct and Variable comments are shown below.
/**Struct*************************************************************
Synopsis [ Represents an integer range ]
Description [ Uses two integers to represent the range.
Under normal circumstances, begin <= end. ]
SeeAlso [ Rng_RangeAlloc Rng_RangeFree ]
**********************************************************************/
typedef struct RngRangeStruct {
int begin; /* The lower limit */
int end; /* The upper limit */
} Rng_Range_t;
/**Variable***********************************************************
Synopsis [ The number of ranges current in existence ]
Description [ Whenever Rng_RangeAlloc is called, this is incremented.
Whenever Rng_RangeFree is called, this is
decremented. This should always be positive
SeeAlso [ Rng_RangeAlloc Rng_RangeFree ]
**********************************************************************/
int Rng_numRanges;
To make code in the VIS environment look consistent, we have the
following conventions about its appearance:
- Lines are eighty characters wide. Anything wider is
difficult to read and print. Insert line breaks as necessary to
ensure this.
- Indents are two spaces. This is smaller than other systems,
but reduces the chance of nested instructions marching off the right
side of the page.
- Comments within code occupy full lines. Comments tacked
on to the right of statements can be hard to see and make it
difficult to modify the code. Comments to the right of variable
declarations, structure members, and arguments in function
definitions are fine.
- Open-braces go at the end of lines. Close-braces should
come at the beginning of a following line. The braces enclosing a
function definition are the one exception to this rule.
Always use curly braces in compound statements, even if they enclose
only one statement. This makes it easier to correctly add
statements to the block, and simplifies setting breakpoints in a
debugger.
The following fragment illustrates these conventions.
void
Ntk_NodeDeclareAsCombinational(
Ntk_Node_t * node,
Tbl_Table_t * table,
array_t * inputNames /* array of char */,
int outputIndex)
{
/*
* If the output column of a table can take only
* a single value, set the constant flag.
*/
if ( Tbl_TableTestIsConstant(table, outputIndex) ) {
node->constant = 1;
}
/*
* Print the node's name, MDD id, type, and attributes.
*/
(void) fprintf(fp, "%s: mdd=%d, %s;%s%s%s%s%s%s\n",
Ntk_NodeReadName(node),
Ntk_NodeReadMddId(node),
typeString,
(Ntk_NodeTestIsPrimaryOutput(node) ? " output" : ""),
(Ntk_NodeTestIsConstant(node) ? " constant" : ""),
(Ntk_NodeTestIsLatchDataInput(node) ?
" data-input" : ""),
(Ntk_NodeTestIsLatchInitialInput(node) ?
" initial-input" : ""), ,
(Ntk_NodeTestIsCombInput(node) ? " comb-input" : ""),
(Ntk_NodeTestIsCombOutput(node) ? " comb-output" : "")
);
}
Next: Naming Conventions
Up: No Title
Previous: Introduction
Tom Shiple
Fri May 10 17:19:47 PDT 1996
| 
