Packages and File Structure
 

 


next up previous contents
Next: Naming Conventions Up: No Title Previous: Introduction

Packages and File Structure

 

Packages

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.

C Header Files

Both the internal and external headers follow the same structure:

  1. 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.

  2. #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.

  3. 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.

  4. Declarations of non-functions, each type in a separate section with a leading comment.

  5. 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.

  6. 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 /* _ */

C Source Files

A C source file contains the following:

  1. A CFile structured comment describing the contents of the file, described in Section 2.4.2.

  2. #include "packageInt.h".

  3. An RCS string, used by the revision control system described in Chapter 5.

  4. Declarations and definitions of non-functions, each type in a separate section with a leading comment.

  5. 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.

  6. Three sections, each with a leading comment, separated into definitions for

    1. Functions visible outside the package
    2. Functions visible to all files within the package only
    3. 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                                            */
/*---------------------------------------------------------------------------*/

Structured Comments

 

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 HTMLgif 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.

CHeaderFile

 

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 $]
******************************************************************************/

CFile

 

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. ]
******************************************************************************/

Function

 

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 */)
{ /* ... */ }

Macro

 

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

 

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;

Low-Level Coding Conventions

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 up previous contents
Next: Naming Conventions Up: No Title Previous: Introduction


Tom Shiple
Fri May 10 17:19:47 PDT 1996
Contact 
©2002-2018 U.C. Regents