updated user`s manual is now available
Contents
1. Each following line is taken to define a CSR and is expected to start with a numeric character The next line that csrGen User s Manual Automated CSRs for ASICs FPGAs 8 begins with s is understood as the end of the CSRs for that address The sa declaration format 1S A lt address gt name or comment properties writetaskname readtaskname The numeric address may be decimal or hex in the form 0x 1a Properties and any text in quotes may precede or follow the tasks The first token not quoted and not recognized as a property will be taken as a verilog task name to be called when the address is written The second such token will be taken as a verilog task name to be called when the address is read The properties are a subset of the properties described below for individual CSRs and apply to all fields at the specific address The subset is RO COR W1C all defined below as CSR properties The calls to verilog tasks for write and read operations allow for the designer to add special logic that might be associated with triggering related operations Execute action as described in section 2 A repeated form of A is also supported as sAREPEAT with a repeat count following the address which is the starting address for the repetition If no further parameter is present then the CSRs will be repeated at addresses incrementing by 1 otherwise the third parameter is the address increment between repetitions If2. options can define properties of the entire module created by csrGen B lt name gt specifies a name to be used for the verilog module and files If not specified the default value of chip_up_ifc is used C lt name gt specifies a name for flop clocks It is added to the module inputs The default name is clock The clock is used as a positive edge csrGen User s Manual Automated CSRs for ASICs FPGAs 10 RST lt name gt specifies a name for flop resets It is added to the module inputs The default name is init1 The reset is used as a negative logic 0 asserted value e WD lt name gt specifies the name used as the source of data written to CSRs The default name is up_datain This is not automatically added to the module inputs so may be an internal signal or declared with a 1 declaration RD lt name gt specifies the name used as the destination for data read from CSRs The default name is up_dataout_D This is not automatically added to the module outputs RM lt number gt specifies that the read multiplexer should be partitioned into blocks of addresses the number is the size of each block This is done by appending a number to the read data destination name the number at each address is calculated by dividing the address by the read multiplexer block size Using this option the designer can create a pipelined read multiplexer csrGen creates just the logic up to the first pipeline stage e AUTO Selects the
3. output from flops with optional width VCL starts the user defined combinational logic which ends with sz The swritecase and readcase are expanded by csrGen with all necessary write and read logic AUTO Selects the use of automatics from emacs verilog mode for the module IO list and for the sensitivity list csrGen can generate these directly but this option may be preferred by designers already using emacs verilog mode and it also cuts the number of lines in the output for our example so it fits on just one page This example uses just a small subset of the options and properties supported by csrGen csrGen User s Manual Automated CSRs for ASICs FPGAs 6 someerrorS_D up_dataout_D someerror module chip_up_ifc AUTOARG input clock initl input 7 0 version input someerror input read input write input 320 address input 7 0 up_datain output 7 0 fieldl output 3 0 field2 output 7 0 up_dataout reg TEQ fieldl fieldl_D reg 3 0 field2 field2_D reg someerrors reg 7 0 up_dataout always AUTOSENSE begin field1l_D fieldl field2_D field2 someerrorS_D someerrors up_dataout_D wie relic O end hes end 2 3 end begin fieldl_D begin begin field2_D someerrors endcase up_dataout case address up_datain 7 0 up_datain 3 0 SD someerrorS_D amp up_datain 6 if read case address beg
4. set of control status registers CSRs described by a memory map spanning many addresses Often these register sets are quite large and there may be a variety of behaviors associated with different fields in the registers The logic structures to implement these CSRs are repetitive and relatively simple This makes automating the task of RTL coding them attractive Automating the task has several advantages e Time savings the RTL coding is verbose and different code fragments relating to one CSR field are scattered in many different places in the RTL declaration module I O list sensitivity list read logic write logic reset and clock logic Automation allows one simple specification of a field to propagate to all of those code fragments Correctness with all of those code fragments for one field dispersed errors are possible e Consistency an automated tool tends to suggest preferred structures not by limiting options but by making the preferred way easy and simplifies the use of templates examples or descriptions of structures to be used for all chips in a project e Single source code a specification that is more than the source for RTL also generates o the verification environment including automated testing of CSR fields o embedded firmware which usually needs a h file to describe field locations o documentation This paper describes csrGen which is a PERL script to automate the CSRs in a processor interface
5. to zero A similar property would be that the value is reset to zero by writing a non zero value the intent being that writes can be made to other fields usually control fields at the same address without modifying this field usually a status or counter field For multi bit fields some implementations of this might reset all bits if any non zero value is written others might do a bit by bit write 1 to clear and require all 1 s to clear the multi bit field Sticky often used to describe register bits that are set and remain set in response to an event Often these may be events that propagate as an interrupt The sticky bit would usually be cleared by a clear on read or write 1 to clear operation Counters another common CSR type They also may be clear on read or write 1 to clear Execute action some CSR fields act as triggers when written some operation should be performed The value written may or may not be significant Sometimes the field retains it s value until the operation is complete and can be read to determine completion status or the field might not be read at all write only There are many other possibilities for CSR behaviors these are simply the most common Most designers and programmers first become familiar with basic read write registers as part of a standard processor model and then may learn about the variations as microprocessor peripherals or peripherals integrated in a microcontroller 3 Implem
6. It was written with these goals in mind 1 Simple but powerful template format to describe CSR fields 2 Quick operation to produce updated RTL after any change 3 Many different types of CSR field behavior 4 Allow for functionality beyond register read write access integrate user written RTL directly in the template Create synthesis ready Verilog RTL code csrGen could be adapted for VHDL Create CSR field definitions for C Verilog and Vera 7 Create code fragments for the module that instantiates the processor interface wire declarations and an instantiation ON Mi csrGen is freely available at http asics chuckbenz com 2 CSR Operation and Types of CSRs A basic CSR is an entity that a processor can read and or write at a specific address and bit position s This implies a set of flops a write multiplexer controlled by a write strobe and an address decode and a read multiplexer controlled by an address decode This can be termed a read write CSR csrGen User s Manual Automated CSRs for ASICs FPGAs 3 Many applications require a broad variety of different CSR properties often combining several of these properties A small subset of common CSR types is summarized below as examples Read Only a common variation with no logic for writing Sometimes this may be a constant value for example a chip ID or version number Clear on read the read operation returns the value of the CSR but then the contents are reset
7. any of the optional parts of the sa declaration are desired they must be preceded by an increment value even if itis 1 If a CSR name in a sAREPEAT declaration includes a character it will be replaced by the incrementing index If the CSR has the buss property then the index is used as a bit subscript in the form name index only for single bit fields otherwise the index is appended to the name 4 4 csrGen CSR Properties This section lists the properties that may be set on individual register fields Most can be applied in combination with others These keywords can be in any order on the same line with the register field definition Upper vs lower case is not significant Intern internal indicates that the field is not an output or input of this verilog module e RO read only the field is only present in the read logic and is an input to the module unless Intern property is also declared COR clear on read the field is reset to 0 when the address is read e WIC write 1 to clear the field is reset to 0 when the address is written and the corresponding bit s is are 1 but is not altered if the bit s is are 0 csrGen implements this on a per bit basis for multi bit fields e ST sticky the field is sticky The name in the definition is taken as an input to the module unless Intern and a flop is created for the sticky memory The sticky value will remain 1 if the nominal value
8. ation csrGen aids design verification by automatically creating definitions associated with every CSR field specifying the address width and bit position Another structure often required for verification is coverage measurements csrGen can be enhanced to generate code to measure read and write coverage of CSR fields Today this may be in formats structures that differ between projects but perhaps a general structure for this will emerge so that it can become a standard feature of csrGen The template file does specify CSR behavior well enough to lead to automatic testing of many CSR operations This could include e basic read and write operations e randomized data to validate field position and independence e reset value checking e clear on read write 1 to clear testing 6 Future Enhancements and Improvements csrGen has many places for improvement This section is a loosely arranged laundry list The template file parsing is simplistic a hardware engineer rather than a proper programmer developed it Much of the verilog creation is currently done as the template file is parsed so no main data structure results from the parsing That sort of data structure may be needed to enable future enhancements Wider exposure of csrGen may bring out requests or completed code for additional features and logic structures as each design may have different requirements csrGen User s Manual Automated CSRs for ASICs FPGAs 12 A
9. csrGen Automated CSRs for ASIC FPGA Processor Interfaces Chuck Benz Chuck Benz ASIC and FPGA Design cbenz chuckbenz com ABSTRACT csrGen is a tool to automatically produce synthesizable verilog RTL code for the registers that make up the memory map of a processor interface from a simple template that lists and describes the registers Using a tool for registers speeds ASIC or FPGA development avoids common errors and can also aid documentation verification and firmware development Table of Contents Tablet Content Sns a va ccnecaaeatecatuaseatasanaeenscenceacounecnet ance mea N RE 2 Table or Pisutes is eka elie ee E eh ea ase ali alee tee ea ae 2 IniroductoNeiseirnsriose nn e a E AS NE EE a eE nET 3 2 MCSROperation and Types of CSRS sissies sscsnewvecnes Seve soeseahe ipanssstovas tary ees i S E AOE Epo aE TEs ai 3 3 Implementing CSRs in an ASIC FPGA Design ecccccesncecssececesececesecesnsecesssccesnsceeesseees 4 3 1 Implementation Errors fe 12 enen era a E E T S E ES 5 3 2 Automating CSRs with an EDA Tool sessesssseesssesseesseesseeessseessressresseesseeessseesseessessee 5 4 The csrGen Template File Syntax sx eicciseccectivsevsstisduencsivavalsasedvaccaesnskssasdevaaea seonaceasadecevassoneatas 6 4 1 PSS TERE ES eA Gs oad cis eats AEE ae a E EAEE E eats Bacay nae E 6 42 ESRC SIUC HUTS Declarations seed drnalus Us E EE E veers tgs EE 8 4 3 Address Declarations s 25 sigiscssssdeavestesanvacs pesecaveneasine
10. e a custom syntax and generated verilog code fragments and documentation fragments Repeating the assembly of the fragments for each change became tiresome For csrGen the decision was made to use a template file syntax specific for csrGen that would define CSR fields and also include as much verilog code as a designer might wish to integrate with the CSR code The csrGen program processes the template and produces a verilog file ready for synthesis with the complete module It also generates a file with verilog wire declarations for all module IO signals and a file with a verilog instantiation these files can be inserted into the verilog file for the next higher module in the hierarchy csrGen User s Manual Automated CSRs for ASICs FPGAs 4 The csrGen Template File Syntax 4 1 A Simple Example Figure is a very simple example of a csrGen template file and Figure 2 is the verilog RTL that is produced by csrGen A 0 0 fieldl oe oe gt 0 version RO A2 0 field2 someerror sticky W1C OY W ol SI read SI write I address 4 SI up_datain 8 SOF up_dataout 8 SVCL if write case address Swritecase endcase if read case address Sreadcase endcase op oh AUTO Figure 1 Example csrGen Template File sa describes an address the lines following a define fields at that address with optional properties 1 describes an input with an optional width OF describes an
11. enting CSRs in an ASIC FPGA Design Most processor interface logic is coded in RTL by a designer with some logic specific to how the processor bus operates flops for the CSRs read logic write logic and ancillary logic for special functions such as triggered operations counters and interrupts Sometimes this may be in a single module or it may be spread over several modules in a design with one module for the actual chip IO When the CSR logic is in a single module most CSR fields are outputs from that module and connect to other modules that use the values Or for status fields they are inputs to the CSR module coming from other modules Additionally a file is created with definitions of each CSR s address with and position in a general form that is easily transformed into C verilog or Vera define statements csrGen User s Manual Automated CSRs for ASICs FPGAs 4 3 1 Implementation Errors The CSRs can be an error prone area of a design for several reasons e The behavior is spread across many distinct locations of the RTL code including the module IO list and declarations the flop reset value the read logic the write logic and logic for any special properties e The logic is simple so often designers are less careful in coding it particularly when making a late change to a design Often the focus is on the application of the CSR field that is being added rather than the read write access logic for it e Verification so
12. flops o designer code from svc block in template file with read and write cases expanded e always verilog block for flops clock and reset 4 2 esrGen Structure Declarations Aside from CSRs csrGen provides for declaring and creating the usual variety of structures used in RTL coding such as inputs outputs flops and wires The declaration format is somewhat simpler so syntax errors are less likely These declarations include I input with an optional width 0 output with an optional width w wire declaration with an optional width R verilog reg declaration with an optional width creates no other structure F flop with an optional width reset value and direct value SEF lt flopname gt width resetvalue directvalue OF output from a flop with an optional width reset value and direct value All of these also can be specified as repeated structures s IREPEAT SOREPEAT etc with a repeat count specified before the name SFREPEAT lt repeatcount gt lt flopname gt width resetvalue directvalue If the name contains a character it will be replaced by an index incrementing from 0 as the structure is repeated otherwise the index will be appended to the name A character in the direct value will also be replaced by the index 4 3 Address Declarations The sa declaration begins definition of a set of CSRs at a specified address
13. hyd sat E sich oaaaa EE suedentaateeenence peated 8 AA esrGe CSR Properties chilies cone n ca onwsha om snag dacs deesudensacdaecona aE 9 4 5 estGen Module Propertie Sene eren E rue ala sace R 10 4 6 PALO os PRG CCE S esas es sian esos cacy clas Gees acter T adieu acre esac ace nan tee eho i 11 4 7 Direct Verilog Coderen risintia ta s e tated aes teee ee eed aaeaoanets 11 5 Design VeornficatoN tsesen na ae A E RE REEE EEEN RIE Rii 12 6 Future Enhancements and Improvements sssssesesseessseessresseesseesseetesseesstessensseesseeessseesseest 12 6 1 csrGen Enhancements eatiscicnetauat ane aves getened Error Bookmark not defined 6 2 Other Directions 4s cwssiasinuiiaergswauennwens Error Bookmark not defined 7 Conclusions and Recommendations saics cesses cccessssabencaessvecsisecees seavsecesesastessansdveredepeons leweseceacs 13 o9 Acknowledgements anaa e a EE E E ceo ve Mess ates nena ae aa 13 o E E E EA E E A T E EE E E E ATA 13 Table of Figures Figure 1 Example csrGen Template File nnnnnnessenssessseesseessseesseesseeeseressretsseesseesseesseeessseesseese 6 Figure 2 Example csrGen verilog output eseeeesessesseseesseseeestesreserssresstsersstessesetsstensesstereeseeseeeesste 7 csrGen User s Manual Automated CSRs for ASICs FPGAs 2 1 Introduction Many ASIC and FPGA designs include processor interfaces Beyond the logic specific to how the particular processor bus operates these interfaces consist mainly of a
14. ilar to Incr but decrementing DecrS decrementer saturating same as Decr but stops decrementing at all 0 s SUB SUBM subset and subset msb if several fields addresses are to be catenated to form a larger field the same name is used for each subset and is defined as a field with the SUB property followed by a range definition The subset field with the most significant bit of the larger field must use the SUBM property For example A 0 31 0 bigfield SUB 31 0 SA 1 15 0 bigfield SUBM 47 32 Shadow any field that is not to be constructed by csrGen but is implemented by user added logic can still be defined in the template for the purpose of documentation and generating firmware or verification definition files The shadow property prevents csrGen from generating logic for the register Pulse the field asserts for one cycle when written as 1 and always reads as 0 PulseA assert until acknowledged when written as 1 the field asserts until an acknowledgement is received The name used for the acknowledgment is the field name with _ack appended The acknowledgment results in the deassertion at the next clock edge any numeric value is taken as a reset value for the flops in the register buss for 3AREPEAT only single bit fields only specifies that the name is taken as a vector with a width matching the repeat count and each address corresponds to one bit of the vector csrGen Module Properties A number of
15. in O u end es u end 2 u u end p_dataout begin p_dataout begin p_dataou p_dataou endcase end always f o i fiel fiel cat ct D begin r r someerror lt 0 up_dataout lt 0 nd else begin e end csrGen User s Manual Automated CSRs for ASICs FPGAs fiel fiel nd modul Le Figure 2 Example csrGen verilog output ldl lt fiel l d2 lt fiel someerrors lt someerrors_D up_dataout lt up_dataout_D r ld1_D A2 D 0 fieldl 0 version 0 field2 someerrors 7 L T A posedge clock or negedge initl Init ldl lt 0 l d2 lt 0 someerror L Highlighted in figure 2 is the verilog code that was written by the designer in the template file In this example very little was written by the designer but it should be clear from the example that the designer can insert any desired statements to alter values before or after the case statements for write and read logic The coding style separates all combinational logic from the code for flops this allows for the designer to add statements to modify the _D variables as desired with statements The generated code has the main structure shown Comments from template file Module input output reg wire declarations Designer code from v block in template file always Verilog block for combinational logic o defaults for all _D inputs to
16. is ever 1 if even only for one clock cycle In the example above someerror becomes an input someerrorS is the sticky flop and logic is also present for the W1C property This is customarily a single bit field SOR set on read the field is set to all 1 s when the address is read e DOR decrement on read the field is decremented by 1 when the address is read csrGen User s Manual Automated CSRs for ASICs FPGAs 9 4 5 DORS decrement on read saturating if not zero the field is decremented by 1 when the address is read IOR increment on read the field is incremented by 1 when the address is read IORS increment on read saturating if not all 1 s the field is incremented by 1 when the address is read WIS write 1 to set the field is set to 1 s when the address is written and the corresponding bit s is are 1 but is not altered if the bit s is are 0 csrGen implements this on a per bit basis for multi bit fields WO write only the field is only present in the write logic STO sticky low like sticky but the sticky value stays 0 if the nominal value is ever 0 Incr incrementer the field is an incrementing counter The name in the definition is taken as a one bit input to the module unless Intern and a counter with the field width is defined with _cntr appended to the name IncrS incrementer saturating same as Incr but stops incrementing at all 1 s Decr decrementer sim
17. le that will be used in the module verilog code that is generated svc and sv Both mark the start of a block of verilog code many lines that ends with a E which is required VCL is always necessary for the designer to control when the write and read operations are performed and is for combinational logic statements in the form of verilog s blocking assignments Code between the svc and the is preceded by an always begin and default assignments for all _D inputs to flops and followed by end csrGen User s Manual Automated CSRs for ASICs FPGAs 11 Code in the sv block is enclosed only by the module declaration and the endmodule statement This code follows all of the verilog declarations input output wire reg This may be used for instantiations assign statements and even additional always blocks as desired by the designer Both svc and sv allow for a line or several lines to be repeated with any characters in the line s being replaced by an incrementing index the elusive verilog generate statement This is done with the Loop and sLoopenp declarations If Loop has one parameter it is a repeat count if there are two parameters they are the first and last indexes Additionally any lines with verilog format comments or blocks formed by and are copied to the verilog module file before the module If multiple svc or sv blocks are present then they are appended together 5 Design Verific
18. metimes may focus more on control of chip operation writes rather than chip status reads As a designer I have often made late changes to CSRs in a design and stumbled over errors in sensitivity lists module IO lists and other minor syntax errors I have also observed a bug in a released commercial IP core from a good vendor in which two bit positions were reversed between read and write operations 3 2 Automating CSRs with an EDA Tool Portions of the processor interface are obviously automated but doing just those portions then requires a way to integrate the automatic parts with the rest And the rest of the logic will differ for almost every design One possibility is generating code fragments that are then assembled by a designer using a favorite text editor but that requires repeating that step with every change and change seems inevitable Another might be using constructs like verilog s include construct but many including this author reject that preferring that the full RTL code be apparent when looking at the main file and there may be file management issues A more elegant model of tool operation is the automatics present in verilog emacs mode 1 This uses special comments which are expanded by the emacs editor to add the automatic code Automating RTL code for CSRs has been done by designers on many projects csrGen is the second such tool I have developed The first tool read a list of CSR definitions from a fil
19. precursor to csrGen produced documentation in the form of tables describing the contents of each address in Microsoft s RTF format this is very desirable HTML seems like the right format now The combinational logic block coding structure may be criticized as possibly inefficient in simulation as the block may be invoked multiple times in one clock cycle It may be possible to use that structure only for fields that the designer wants to manipulate with added logic and place the plain fields in logic that is directly in the clocked always block Some designs may incorporate multiple processor interfaces requiring multiple address maps with some shared CSRs various sharing mechanisms are possible Support for multiple clocks specifically for F flops may be desirable for some designs although I expect that all writeable CSRs in a single address map would be on a single clock Another structure that could be added would be flopped constants since some constants that may be used as CSRs are values like version numbers and if a chip is ECO ed the version number should usually also be changed It can be easier to change if the constant value is at the input to flops rather than absorbed directly into read multiplexers and using the complement of the value as the reset value can prevent synthesis from optimizing away the flops 7 Conclusions and Recommendations I believe that csrGen has saved me enough time and mistakes
20. to balance the investment I ve made in developing it csrGen has been part of the design flow for two ASICs I have developed Each design had specific needs that led to new features csrGen is free for any user and I hope that it may be adopted for use anywhere designers are implementing large memory maps of CSRs I welcome feedback whether as code contributions or requests for more features As of the end of December 2002 the csrGen PERL script has been downloaded from my website over 800 times since it was mentioned in an EE Times article in September 2002 but to date I ve only received feedback from one user who suggested further CSR structures which I added and contributed code to add support for the emacs verilog mode RTL code for CSRs can be fruitfully automated and csrGen is a good illustration of how it can be done 8 Acknowledgements Thanks to Mark Matulaitis Mark Levesque Andy Moroney Jeff Koehler Jim Wu George Nicholas Chris Payson and Steve Sherman for ideas and suggestions that have ended up in various ways in csrGen 9 References 1 Verilog mode for Emacs verilog mode el 1996 2002 and continuing Mike McNamara http www verilog com verilog mode html csrGen User s Manual Automated CSRs for ASICs FPGAs 13
21. use of automatics from emacs verilog mode for the module IO list and for the sensitivity list csrGen will execute emacs to expand these automatically Note your sensitivity list may not be complete if you are using tasks or function calls e sv2x selects the use of the verilog 2001 2000 automatic sensitivity list always Note this construct does not explore tasks and functions to determine sensitivities to global references so like AUTO this may not work properly in conjunction with tasks and functions e INCLUDE lt filename gt specifies a file to be inserted in place INCLUDE can be recursive e BASEADDR lt address gt specifies an offset to be applied to all register definitions that follow 4 6 Flop Properties For flops created from the sF and oF structures and as CSR fields the reset and direct values do not have to be specified on the declaration line they can be set separately with sRESETVALUE and FLOPVALUE with the flop name and value as parameters the remainder of the line is taken as the value SRESETVALUEREPEAT and FLOPVALUEREPEAT are equivalents for repeating structures taking a repeat count before the flop name When declared a direct value for a flop is used instead of lt name gt _D as the right side of the flop posedge assignment 4 7 Direct Verilog Code Two definitions are used with csrGen for placing verilog code into the template fi
Download Pdf Manuals
Related Search