EGG Extension Guidelines

From: Kathy McKinley (mckinley@cadence.com)
Date: Mon Dec 15 2003 - 07:40:21 PST

  • Next message: Kurt Baty: "draft of Process Flow Specification"

    Hello,

    I have appended the initial version of the Extensions Guidelines from
    the EGG group. This document is not complete (section 4 is empty and we
    would like to add a section on BNF guidelines), however it contains
    significant content on which we would like feedback.

    Enjoy!

    Kathy

                    IEEE 1364 VERILOG EXTENSION GUIDELINES

    1. OVERVIEW

    [1] This document defines a set of guidelines for extending the Verilog
    language during an IEEE 1364 revision process. The purpose of these
    guidelines is to:

        1) ensure consistent treatment of language features across
           extension subcommittees that are working in parallel

        2) eliminate the need to repeat discussion of fundamental
           principles when considering each new language feature proposal

        3) expedite review of proposals by the Behavioral Task Force (BTF)
           by providing a framework for discussing merits and problems

    Application of these guidelines will result in a self-consistent
    Verilog language and a more efficient extension process.

    [2] The rest of this document is organized into the following sections:

    [3] The "Applying the Guidelines" section explains how the guidelines
    are intended to be used during the extension process.

    [4] The "Fundamental Principles" section puts forth a set of basic
    principles to follow when defining an extension. These principles
    do not deal with specific language constructs. Some of these principles
    are very basic principles of good language design that have been
    recognized and followed in the language/compiler community for years.
    Other principles attempt to codify the elusive "spirit of Verilog"
    so that the aspects of Verilog that have made it so powerful and popular
    are preserved.

    [5] The "Language Guidelines" section covers language constructs
    that can be used to extend the language. Each construct is analyzed
    in a subsection that describes how the construct is currently used
    in Verilog. Guidelines for what constitutes appropriate future use
    are also given.

    [6] The "Editorial Guidelines" section describes the proper form
    for an extension description in editorial terms.

    2. APPLYING THE GUIDELINES

    [7] The Extension Guidelines are intended to be used in conjunction
    with The Guidelines Checklist, a survey that is completed by the sponsor
    of a language enhancement proposal. The sponsor might be an individual,
    a company, a BTF subcommittee, or another organization.

    [8] The checklist asks detailed questions about the nature of a proposed
    extension, and serves as a measure of conformance to the guidelines.
    The act of completing the checklist can help a sponsor to recognize and
    possibly address nonconformance with the guidelines before submitting
    an extension proposal.

    [9] A completed checklist will be used by the BTF to evaluate the
    conformance of a proposal to the guidelines. A lack of conformance to
    the guidelines does not imply an out-of-hand rejection of the proposal;
    however, the proposal's sponsor will need to provide rationale for why
    the guideline should not apply in a particular case.

    [10] This set of guidelines is likely to be incomplete, and thus will
    need to grow as the language grows. During the extension process
    additional principles may emerge. The guidelines and the corresponding
    checklist will be maintained as living documents that can be updated
    upon approval by the BTF.

    3. FUNDAMENTAL PRINCIPLES

    [11] This section puts forth a set of principles that together constitute
    the guiding design principles of Verilog. These principles do not discuss
    specific features but rather a philosophy to be followed when designing
    new features or evaluating them as additions to the language.

    [12] During discussion of extension proposals a significant amount
    of debate typically revolves around whether something is a "Verilog-like"
    way of doing things. In abstract terms, many of these principles define
    "Verilog-like".

    3.1 Backward Compatibility

    ------------------------------------------------------------------------
    Guideline 1: An existing design that is legal with respect to the latest
    IEEE 1364 standard must continue to be syntactically legal and to have
    exactly the same simulation semantics in the next version of the language.
    ------------------------------------------------------------------------

    [13] A primary goal of language extension must be backward compatibility
    with the latest version of the IEEE 1364 standard. Designers are
    understandably reluctant to modify legacy designs, and rightly expect
    their designs to continue to be valid and behave in the same way in tools
    that support later revisions of the language.

    [14] The single exception to this guideline is the case where a design
    written for in the older version of the standard uses an identifier that
    has been adopted in the newer version as a keyword. These cases can be
    minimized by minimizing the number of new keywords and by choosing keywords
    that would be rare in designs.

    [15] This guideline does not state that code that was previously
    illegal continues to be illegal. The language may be extended in ways
    that make previously illegal designs legal.

    3.2 Built-in Primitives

    ------------------------------------------------------------------------
    Guideline 2: Primitive constructs should be used to represent
    fundamental concepts that are widely understood and used.
    ------------------------------------------------------------------------

    [16] Verilog defines built-in primitives that represent well-defined,
    commonly-used design elements. Examples of built-in support include
    the basic gates and the predefined wire types. This sort of primitive
    support is one of the aspects of Verilog that makes it so easy to use.

    [17] In the interest of minimizing language size, complexity, and keyword
    conflicts, the barrier for adding built-in primitives should be high.
    Possible justifications include:

        1) It is very difficult or impossible to model a certain situation
           with the existing primitives

        2) Addition of a primitive would make it significantly easier
           to model certain widely-used cases

    3.3 Design Refinement

    ------------------------------------------------------------------------
    Guideline 3: Design components that are modeled at different levels of
    abstraction should be able to coexist, interact, and evolve, with
    appropriate allowance for conversion between levels of abstraction.
    ------------------------------------------------------------------------

    [18] Verilog is capable of modeling a given device at different levels
    of abstraction, and the range of abstraction will only grow in the future
    as system-level and analog/RF extensions to the language are adopted.
    A key feature of the success of Verilog over the years has been
    the ability to move between different levels of abstraction with
    relative ease. This characteristic should be preserved whenever possible.

    [19] Exchanging a module with a construct at a different level of
    abstraction should affect only the immediate interconnect. It should not
    be necessary to change a distantly connected module because of a change
    in the level of abstraction. A known exception to this principle occurs
    when a module makes a hierarchical reference to an internal node that
    does not exist in the replacement. This is an accepted risk in using
    hierarchical references.

    [20] This guideline explicitly allows for the presence of interface
    constructs -- such as type conversion expressions or connection modules --
    to perform conversion between different levels of abstraction.

    [21] This guideline does not require that refinement be automatic.
    A design element may be refined by synthesis or some other automated
    process, but this is not required.

    3.4 Simplicity and Ease of Use

    ------------------------------------------------------------------------
    Guideline 4: Conciseness, simplicity, and clear inference of intent
    should be preserved wherever possible.
    ------------------------------------------------------------------------

    [22] A strength of Verilog has always been the simplicity of Verilog
    descriptions -- its "concise clarity". Within the Verilog application
    domain, the designer's intent can often be inferred from the use of a
    few simple constructs. Existing mechanisms, such as implicit declaration
    of wires and automatic sign-extension or truncation of assignments of
    differing widths, are examples of the application of this principle.

    [23] When it does not create a potential for ambiguous interpretation
    of the language or lead to obvious potential design mistakes,
    this principle should be observed. This guideline becomes increasingly
    important when comparing multiple proposals on a given topic or deciding
    on default behavior. During this process, the simplest, most intuitive
    proposal will often be the most appropriate.

    3.5 Consistency

    ------------------------------------------------------------------------
    Guideline 5: New capabilities should be integrated into the language
    in a way that is consistent with existing constructs, usage, and
    expectations.
    ------------------------------------------------------------------------

    [24] Verilog is widely viewed by hardware designers as a language that
    is very natural to use. To preserve this characteristic as the language
    gets bigger, it is important to minimize the learning curve by taking
    advantage of a user's existing knowledge. Members of the software industry
    commonly refer to the principle behind this guideline as "the principle
    of least surprise".

    [25] New capabilities should be integrated into the language in a uniform
    and regular way. User functionality associated with like language elements
    should match as consistently as possible. Special cases where new
    language constructs do not blend well into the existing language fabric
    should be minimized.

    [26] An example of this principle in practice is the extension to allow
    named association of parameters in an instantiation. Named associations
    for port connections already existed, and the parameter extension adopted
    the same ".name()" syntax.

    [27] A corollary to this guideline is that constructs that are only
    superficially similar should not be made to look alike. The similarity
    may create false expectations and cause designers to use the new construct
    in incorrect or undesirable ways.

    3.6 Completeness

    ------------------------------------------------------------------------
    Guideline 6: New capabilities should include extensions for all
    related aspects of the standard.
    ------------------------------------------------------------------------

    [28] The Verilog community has long recognized the fact that there are
    many ways to interact with a design, and that a viable hardware description
    standard must provide more than just a set of language constructs.
    Verilog defines standard support for activities like debugging, recording
    simulation activity, and interfacing to other languages. Making a language
    extension complete by defining its impact and treatment in all aspects
    of the standard is critical for making a new construct generally usable.

    [29] When defining a new construct or capability, corresponding extensions
    in related support facilities should be defined as well. Examples of such
    facilities are the Verilog Procedural Interface (VPI), the Value Change Dump
    (VCD), and configurations for flexible binding. Defining a complete
    extension provides a secondary benefit. The effort to extend a support
    facility such as VPI has frequently uncovered subtle design issues with
    the feature being added.

    [30] The Verilog Procedural Interface (VPI) provides access to almost all
    aspects of the Verilog design. For each enhancement to the Verilog language,
    corresponding modifications to VPI will likely be required.

    [31] All types of scopes and data objects should be supported in
    Value Change Dump (VCD) files. This may require extending the VCD
    file syntax for new types of values, scopes, or data objects.
    This guideline applies to both static objects and dynamic objects
    (objects that change size or go in and out of existence, like an
    automatic variable in a function).

    3.7 Efficiency of Implementation

    ------------------------------------------------------------------------
    Guideline 7: New capabilities should have an efficient, practical
    implementation.
    ------------------------------------------------------------------------

    [32] A primary strength of Verilog is that it can be implemented
    efficiently to allow for high-performance, high-capacity simulation
    and synthesis. If a new construct cannot be implemented at all, or
    if its implementation would be incredibly inefficient, then there is
    little chance that the new construct will be implemented and widely used.

    [33] Efficient, practical implementation is a legitimate, but not exclusive,
    criteria for 1) deciding to include a new capability or for 2) choosing
    between alternatives for how to provide a certain capability. During
    discussion on any given proposal, a compromise may need to be made between
    the power of expression and efficiency of implementation.

    3.8 Flexibility of Implementation

    ------------------------------------------------------------------------
    Guideline 8: New constructs should not overly constrain or favor a
    particular implementation approach.
    ------------------------------------------------------------------------

    [34] Verilog is a popular language, and Verilog users have access to
    a wide variety of tools, methodologies, integrations, and productivity
    enhancing utilities. It is important to extend Verilog in ways that allow
    for innovation and flexibility at the tool level.

    [35] The addition of a new construct or capability should not assume a
    narrow style of use, or force the use of one common style over another.
    An example of implementation flexibility in practice would be to consider
    both separate compilation and single invocation methodologies when adding
    a new kind of design unit to the language. Another example of flexibility
    would be to consider a construct's value and impact in both simulation and
    synthesis domains.

    3.9 Lexical and Syntactic Integrity

    ------------------------------------------------------------------------
    Guideline 9:
    ------------------------------------------------------------------------

    [35] This is a placeholder for a guideline about supporting established
    compiler methodology and practices (no context-sensitive parsing, etc.).

    3.10 Forward Compatibility

    ------------------------------------------------------------------------
    Guideline 10: The impact of a capability on future language extensions
    should be considered in any proposal.
    ------------------------------------------------------------------------

    [36] The current IEEE 1364 standard will not be the last revision of
    the Verilog language. Whenever possible, the impact of a capability
    on future extension of the language should be considered. This guideline
    may frequently conflict with other guidelines, but is nonetheless very
    important. The balance between simplicity of specification and forward
    compatibility is critical in extending the language.

    [37] For example, Verilog memories (one dimensional arrays of vector regs)
    existed in the 1995 version of the standard. The 2001 version of the
    standard generalized the notion of array and added the capability of
    declaring multi-dimensional arrays of regs. The 1995 VPI specification
    provided access to vpiMemory objects with a specific VPI access function.
    The Verilog 2001 specification added a general VPI access function to
    access all reg arrays but also kept the original access function to
    obtain memories. This lead to two different ways of obtaining the same
    Verilog object since a memory is also a reg array of one dimension.
    Unfortunately the two different accesses create two different object
    types (one is a memory and the other is a reg array). If extensions
    of multi-dimensional arrays had been anticipated, a more generalized
    and extensible method could have been designed initially.

    4. LANGUAGE GUIDELINES

    This section will provide a feature-by-feature analysis of the Verilog
    1364-2001 LRM and provides guidelines on the appropriate uses of these
    features. The intended use of important language features like
    compiler directives, attributes, system functions and tasks, etc.
    will discussed. Content is TBD.

    5. EDITORIAL GUIDELINES

    When an extension is incorporated into the IEEE 1364 standard,
    the description and rules pertaining to the extension must adhere
    to certain conventions and requirements. The guidelines below describe
    the proper editorial form for an extension.

    5.1 Clearness and completeness

    IEEE 1364 is a standard. The two most important characteristics
    are clearness and completeness. Almost everything else is derived
    from these.

    5.1 Descriptive Style

    IEEE 1364 is a langage reference manual (LRM); it is not a user's guide.

    There is no need to give advice to the reader, such as suggesting
    applications of a feature. Such advice is liable to become outdated
    quickly, and what seems like good advice to some may be viewed as
    bad advice by others. However, warning about likely traps is appropriate,
    as is specifying implications that are not obvious.

    The readers of the standard have various backgrounds.
    Assume that the reader is intelligent, but do not assume that
    the reader is an expert or has a degree in Computer Science.

    What is obvious to some may not be obvious to others. It is better
    to be more explicit than to depend on the reader to read between
    the lines to guess intent. When in doubt, be explicit.

    5.3 Organization

    Organize the description logically. Try to describe a subject completely
    in one place; that is, avoid splitting up discussion of a subject into
    several places.

    Use of a term or concept that is described later is a forward reference;
    add a cross-reference to the appropriate section. Cross-references should
    be as exact as possible (exact sub-section).

    A cross-reference to another section should also be included where
    a reader might have trouble finding related material without help
    (don't depend on the Index), or where a reader might otherwise
    be unaware that related material exists.

    5.4 Readability

    Don't make paragraphs too long. Most paragraphs should be no longer
    than six lines.

    Be concise, but not at the cost of clarity. Avoid roundabout ways of saying
    things. Use active voice where possible. Avoid saying the same thing several
    times. Avoid duplication, i.e., repeating information in several places
    in the LRM.

    Define terms before using them, or the first time they are used.
    Use italics in definition.

    Define abbreviations at first use.

    Use code examples generously.

    5.5 Terminology

    Use consistent terminology. Don't use different terms for the same thing,
    and don't use the same term with different meanings. This is a standard,
    it does not have to be fascinating reading.

    Avoid creating a new term if an appropriate one exists in the latest
    IEEE 1364 standard.

    Avoid overloading existing terminology. That is, where a term is already
    used in the LRM, don't appropriate the term for use with a different meaning.

    New terms should go into a glossary section and the index.

    5.6 IEEE Style

    Conform to IEEE Standard Style Guidelines. For example, use "shall"
    to denote a requirement.

    Pay attention to the distinction between normative and informative text.
    Examples and notes are informative.

    5.6 Formatting

    Be consistent with the latest IEEE 1364 standard formatting style.

    Diagrams and figures should be prepared in FrameMaker 5.5 or 6.0,
    if possible.

    Color may be used as a supplemental visual aid, but do not rely
    upon its presence. The printed copy will be black and white, as will
    most pages printed from the PDF, and there are also color-blind people.
    Never refer to a color in the text, as in, for example, "The red arrow
    points to ...".

    5.6 BNF

    Include BNF where relevant. Syntax box should include all relevant BNF,
    but only what is necessary. Avoid presenting the same BNF in many
    syntax boxes. Use clear and meaningful BNF names.

    Be consistent with the latest IEEE 1364 standard BNF style.

    This archive was generated by hypermail 2.1.4 : Mon Dec 15 2003 - 07:30:50 PST and
    sponsored by Boyd Technology, Inc.