OpenCores Coding Guidelines Authors Yair Amitay yair amitay flextronicssemi com Jamil Khatib khatib opencores org Damjan Lampret lampret opencores org Rev 1 0 October 24 2001 OpenCores OpenCores Coding Guidelines 10 24 01 This page has been intentionally left blank www opencores org Rev 1 0 ii OpenCores OpenCores Coding Guidelines 10 24 01 Revision History Rev 0 1 0 2 Date 15 05 01 29 05 01 Author Yair Amitay Jamil Khatib 0 3 07 06 01 Jamil Khatib 0 4 28 7 01 Damjan Lampret 0 5 22 10 01 Damjan Lampret 1 0 24 10 01 Damjan Lampret www opencores org Description First Draft VHDL and Verilog notes are split Major sections reorganization Comments from discussions on emails are added Revision history added Dedicated clock and reset pins added OpenCores logo added Switched to latest OC document template Added new introduction chapter Reorganized and updated old content Added feedback from Rudi Usselmann Don Reid Illan Glasner David Kessner Incorporated feedback from Illan Glasner David Kessner Yair Amitay and Lior Shtram Added I O ports table Fixed some typing errors Added Blue Beaver s comment about tri state First official version Rev 1 0 iii OpenCores OpenCores Coding Guidelines 10 24 01 Contents INTRODUCTION 1 BEFORE YOU START 2 2 1 SPECIFICATION DOCUMENT 2 2 2 DESIGN DOCUMENT 2 2 3 CVS AND TEAM WORK 3 2 4 VERIFICATION 3 2 5 DIRECTORY STRUCTURE 3 GENERAL DESIGN GUIDELINES 6 3 1 GENERAL 6 3 2 RESET 6 3 3 CLOCKS 7 3 4 BUSES 8 3 5 TRI STATE 8 3 6 MEMORIES 9 3 7 CODING FOR SYNTHESIS 9 3 8 CORE I O PORTS 10 VERILOG GUIDELINES 11 4 1 GENERAL 11 4 2 CODING FOR SYNTHESIS 12 4 3 CODING FOR SIMULATION AND DEBUGGING 12 4 4 FILE HEADER 13 VHDL GUIDELINES 15 5 1 GENERAL 15 5 2 CODING FOR SYNTHESIS 17 5 3 CODING FOR SIMULATION AND DEBUGGING 19 5 4 FILE HEADER 19 www opencores org Rev 1 0 iv OpenCores OpenCores Coding Guidelines 10 24 01 1 Introduction This document contains guidelines and recommendations for HDL coding Adopting these guidelines will reduce the amount of time required to get high quality IP cores and will reduce possibilities for functional problems Following these guidelines will improve reusability and readability of the code The guidelines are sorted according to main subjects but most of them are related to other subjects as well Each guideline is placed in the section where its influence is major but it can have a marked impact on other sections as well The guidelines are of different importance and are classified in the following way Good practice signifies a guideline that is common good practice and should be used in most cases This means that in some cases there are specific problems that violate this guideline Recommendation signifies a guideline that is recommended It is uncommon that a problem cannot be solved without violating this guideline You should read it as a SHOULD rule Strong recommendation signifies a hard guideline this should be used in all situations unless a very good reason exists to violate it You should read it as a MUST rule This document will change in the future Anyone is encouraged to make changes or contribute additional content Latest document is available from OpenCores CVS using module name common TO DO list Sections on Code Style Comment Style and Module Naming there are certain guidelines www opencores org Rev 1 0 1 of 21 OpenCores OpenCores Coding Guidelines 10 24 01 2 Before You Start 2 1 Specification Document Before you jump into HDL coding try to check existing cores and write a specification document This will have several advantages clear definition what the core should do and which standards will be supported defines profiles of developers for formation of a team Essentially the core is a black box and the specification documentation should only be concerned with the interface to this black box Anyone wishing to use the core should only have to read the specification document while those wishing to modify or add to the core should read design document as well For specification document you should use Specification Template available from OpenCores CVS At the time of this writing only MS Word Template is available 2 2 Design Document While you are coding HDL try to write design document If team is working on a core design document might have to be written before HDL coding begins so that developed blocks will be able to work together without spending too much time on integration Design document is important because better understanding how the core s internal blocks should work and communicate to each other allows work of a team on different parts of the core allows future development and contribution by others simplifies verification and bug fixing www opencores org Rev 1 0 2 of 21 OpenCores OpenCores Coding Guidelines 10 24 01 2 3 CVS and Team Work Try to share development efforts with others This way you do not have to do anything yourself and results will come sooner Also we are doing this for fun and part of fun is also communication with others and team solving problems CVS is central OpenCores resource for development and final source storage Even if you work alone try to use CVS as much as possible Do not wait until your design is stable CVS is meant for development If you check in changes on your source file regularly you can most effectively use advantages of CVS such as comparing two different version of the same file However for efficient CVS use we recommend that you first spend some time and familiar yourself with it by reading http www opencores org cvs shtml and CVS manual that is available there Once your design is stable CVS will allow others to most effectively download the latest stable version while you are working on checked in development version and send you testing feedback Additionally we are integrating Verilog and VHDL Linter tool that will check designs commited to the CVS and in a matter of minutes send a lint report to the developer Lint rules will be based on guidelines found in this document 2 4 Verification As part of an early design stage you will also have to think thoroughly about verification strategy If you are unfamiliar with verification try to read Verification Strategies document If your design uses recommended WISHBONE SOC interconnect bus your next step is to download WISHBONE models At the time of writing there are several WISHBONE models in OpenCores CVS written both in Verilog as well as in VHDL 2 5 Directory structure To simplify integration of various cores into SOC try to use
View Full Document
Unlocking...