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 Orthogonality ------------------------------------------------------------------------ Guideline 6: Orthogonality is an important goal when defining a language extension. ------------------------------------------------------------------------ [28] In order to pave the way for future extensions, a significant addition to the language should be added in a general way rather than tailored for a very narrow need. Lack of orthogonality (or independence) between language constructs can lead to unintended consequences and exceptions that may complicate the language and preclude natural extensions in the future. [29] If the new capability is just one of many related features that could be desired in the future, then it may be better to introduce a new class of language construct rather than extend an existing construct for the one case. Although the one case could be "grafted" onto an existing construct, other related extensions may have conflicts with the existing construct that could be avoided if the extension were defined more independently. The new capability may in fact have more in common with a related set of extensions than an existing construct. [30] Minimizing the dependence of one language construct on another can lead to a more flexible, extensible language. Orthogonality of langage constructs can also make the language easier to understand and use. 3.7 Excessive Redundancy ------------------------------------------------------------------------ Guideline 7: Excessive redundancy should be avoided. ------------------------------------------------------------------------ [31] It is important for the language to be flexible, and it often desirable to have different ways to describe something; the different forms of concatenation syntax are an example of beneficial flexibility. However, it is also important not to cross the line into excessive redundancy. Too many ways of doing the same thing may cause the language to become confusing to use, difficult to extend, and costly to implement. [32] The decision to add a new language feature should involve an examination of how other language features -- those already in the language or perhaps in another extension under consideration -- could be used to accomplish the goal of the extension. This consideration is particularly important when the extension is complicated or difficult to implement. To justify the extension, significant benefits in terms of ease of use or new capability should be demonstrated. 3.8 Weight of Existing Implementation and Extent of Use ------------------------------------------------------------------------ Guideline 8: Existing implementation and extent of use should be factors in deciding how to define a language extension. ------------------------------------------------------------------------ [33] A proposed feature that has been implemented and has a broad user base should be considered with special weight, particularly if reference software is provided with the proposal. When incorporating such a feature, changes should be considered carefully and in most cases kept to a minimum. An example of such a case is the set of the features in the original Verilog donation, which defined language constructs that had been widely used for many years and came with a reference simulator. [34] A distinction should be drawn between 1) features that have been "designed by committee" and not implemented yet, 2) features that have been implemented but have not seen broad/extended use, and 3) features that have been "proven" through years of broad use. [35] The same weight does not apply to a feature that has been: - enhanced in the proposal beyond the scope of the implementation - in narrow use, or in use only a short time - only partially implemented Although some implementation is better than none, such features have not really been proven, and may still have significant issues with their definition and general usefulness that need to be addressed for future implementers and users of the language feature. 3.9 Completeness ------------------------------------------------------------------------ Guideline 9: New capabilities should include extensions for all related aspects of the standard. ------------------------------------------------------------------------ [36] 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. [37] 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. [38] 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. [39] 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.10 Efficiency of Implementation ------------------------------------------------------------------------ Guideline 10: New capabilities should have an efficient, practical implementation. ------------------------------------------------------------------------ [40] 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. [41] 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.11 Flexibility of Implementation ------------------------------------------------------------------------ Guideline 11: New constructs should not overly constrain or favor a particular implementation approach. ------------------------------------------------------------------------ [42] 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. [43] 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.12 Forward Compatibility ------------------------------------------------------------------------ Guideline 12: The impact of a capability on future language extensions should be considered in any proposal. ------------------------------------------------------------------------ [44] 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. [45] 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. 3.13 Lexical and Syntactic Integrity ------------------------------------------------------------------------ Guideline 13: ------------------------------------------------------------------------ [46] This is a placeholder for a guideline about supporting established compiler methodology and practices (no context-sensitive parsing, etc.). 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.