osvvm documentation - read the docs · pdf fileosvvm documentation, ... or throw out your...

OSVVM DocumentationRelease 2016.01

Jim Lewis

June 09, 2016

Contents

1 News 31.1 xx.01.2016 - 2016.01 was release. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

i

OSVVM Documentation, Release 2016.01

Open Source VHDL Verification Methodology (OSVVM) is an intelligent testbench methodology that allowsmixing of “Intelligent Coverage” (coverage driven randomization) with directed, algorithmic, file based, and con-strained random test approaches. The methodology can be adopted in part or in whole as needed. With OSVVMyou can add advanced verification methodologies to your current testbench without having to learn a new languageor throw out your existing testbench or testbench models.

Contents 1


2 Contents

CHAPTER 1

News

1.1 xx.01.2016 - 2016.01 was release.

Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore etdolore magna aliquyam erat, sed diam voluptua. At vero eos et accusam et justo duo dolores et ea rebum. Stet clitakasd gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet. Lorem ipsum dolor sit amet, consetetursadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diamvoluptua. At vero eos et accusam et justo duo dolores et ea rebum. Stet clita kasd gubergren, no sea takimatasanctus est Lorem ipsum dolor sit amet

1.1.1 Quick Start Guide

Getting OSVVM

CoveragePkg is released under the Perl Artistic open source license. It is free (both to download and use - thereare no license fees). You can download it from http://www.synthworks.com/downloads. It will be updated fromtime to time. Currently there are numerous planned revisions.

Todo

Link to GitHub as an addition download source

If you add features to the package, please donate them back under the same license as candidates to be added tothe standard version of the package package. If you need features, be sure to contact us. I blog about the packagesat http://www.synthworks.com/blog. We also support a user community and blogs through http://www.osvvm.org.

The STANDARD revision of this package requires VHDL-2008. It will work with a VHDL-2002 compliantsimulator by uncommenting the VHDL-2008 compatibility packages.

Release notes are listed here

1.1.2 Functional Coverage

Overview

The VHDL package, CoveragePkg, provides subprograms that facilitate implementation of functional coveragewithin VHDL. It is a core part of the Open Source VHDL Verification Methodology (OSVVM). While Cover-agePkg is just a package, it offers a similar conciseness to the language syntax of other verification languages,such as SystemVerilog or ‘e’. In addition it offers capability and flexibility that is a step ahead.

Functional coverage is code we write to track execution of a test plan. It is important to any verification approachsince it is one of the factors in determining when testing is done. I will address this more in the section, “What

3

http://www.synthworks.com/downloads

http://www.synthworks.com/blog

http://www.osvvm.org


is Functional Coverage and why do I need it?” In this section I will also address, “Why can’t I just use codecoverage?” and “Why you need functional coverage, even with directed testing.”

Writing functional coverage is concise and flexible. The basics of writing functional coverage using coveragepackage are covered in the section, “Writing Functional Coverage using CoveragePkg.”

One important, unique feature is the “Intelligent Coverage” that is built directly into the coverage data structure.This capability allows us to randomly select a hole in the current functional coverage to pass to the stimulusgeneration process. Using “Intelligent Coverage” helps minimize the number of test cases generated to achievecomplete coverage - resulting in fewer simulation cycles and a higher velocity of verification. More details areprovided in the section, “Intelligent Coverage is 5X or more faster than constrained random testing.”

Functional coverage with CoveragePkg is captured incrementally using sequential code. This provides a greatdeal of flexibility and capability, and facilitates writing high fidelity functional coverage models. More details areprovided in the section, “Flexibility and Capability.”

CoveragePkg provides numerous methods (functions and procedures of a protected type) that provide a powerfulcapability. These methods are documented in the remaining part of the document. Note the package containsadditional undocumented methods that are either experimental features or artifacts from older use models that aremaintained for backward compatibility. Use these at your own risk as they may be removed from future revisions.

This documentation is not a substitute for a great training class. CoveragePkg was developed and is maintainedby Jim Lewis of SynthWorks. It evolved from methodology and packages developed for SynthWorks’ VHDLTestbenches and Verification class. This class includes additional packages that are not yet part of OSVVM.Please support our effort in supporting OSVVM by purchasing your VHDL training from SynthWorks.

All CoveragePkg features are supported now by many simulators. The only required features are protected types(VHDL-2002) and integer_vector (in package std.standard in VHDL-2008). In addition, since they are opensource, the packages are free (download and usage) and will be updated on a regular basis.

What is Functional Coverage?

Functional coverage is code that observes execution of a test plan. As such, it is code you write to track whetherimportant values, sets of values, or sequences of values that correspond to design or interface requirements, fea-tures, or boundary conditions have been exercised.

Functional coverage is important to any verification approach since it is one of the factors used to determine whentesting is done. Specifically, 100% functional coverage indicates that all items in the test plan have been tested.Combine this with 100% code coverage and it indicates that testing is done.

Functional coverage that examines the values within a single object is called either point (SystemVerilog) or item(‘e’) coverage. I prefer the term item coverage since point can also be a single value within a particular bin. Onerelationship we might look at is different transfer sizes across a packet based bus. For example, the test plan mayrequire that transfer sizes with the following size or range of sizes be observed: 1, 2, 3, 4 to 127, 128 to 252, 253,254, or 255.

Functional coverage that examines the relationships between different objects is called cross coverage. An exam-ple of this would be examining whether an ALU has done all of its supported operations with every different inputpair of registers.

Many think functional coverage is an exclusive capability of a verification language such as SystemVerilog. How-ever, functional coverage collection is really just a matter of implementing a data structure.

CoveragePkg contains a protected type and methods (procedures and functions of a protected type) that facilitatescreating the functional coverage data structure and writing functional coverage.

Why can’t I just use code coverage?

VHDL simulation tools can automatically calculate a metric called code coverage (assuming you have licensesfor this feature). Code coverage tracks what lines of code or expressions in the code have been exercised.

4 Chapter 1. News


Code coverage cannot detect conditions that are not in the code. For example, in the packet bus item coverageexample discussed above, code coverage cannot determine that the required values or ranges have occurred -unless the code contains expressions to test for each of these sizes. Instead, we need to write functional coverage.

In the ALU cross coverage example above, code coverage cannot determine whether particular register pairs havebeen used together, unless the code is written this way. Generally each input to the ALU is selected independentlyof the other. Again, we need to write functional coverage.

Code coverage on a partially implemented design can reach 100%. It cannot detect missing features (oops forgotto implement one of the timers) and many boundary conditions (in particular those that span more than one block).Hence, code coverage cannot be used exclusively to indicate we are done testing.

In addition, code coverage is an optimistic metric. In combinational logic code in an HDL, a process may beexecuted many times during a given clock cycle due to delta cycle changes on input signals. This can result inseveral different branches of code being executed. However, only the last branch of code executed before the clockedge truly has been covered.

Test Done = Test Plan Executed and All Code Executed

To know testing is done, we need to know that both the test plan is executed and all of the code has been executed.Is 100% functional coverage enough?

Unfortunately a test can reach 100% functional coverage without reaching 100% code coverage. This indicatesthe design contains untested code that is not part of the test plan. This can come from an incomplete test plan,extra undocumented features in the design, or case statement others branches that do not get exercised in normalhardware operation. Untested features need to either be tested or removed.

As a result, even with 100% functional coverage it is still a good idea to use code coverage as a fail-safe for thetest plan.

Why You Need Functional Coverage, even with Directed Testing

You might think, “I have written a directed test for each item in the test plan, I am done right?”

As design size grows, the complexity increases. A test that completely validates one version of the design, maynot validate the design after revisions. For example, if the size a of FIFO increases, the test may no longer provideenough stimulus values to fill it completely and cause a FIFO Full condition. If new features are added, a test mayneed to change its configuration register values to enable the appropriate mode.

Without functional coverage, you are assuming your directed, algorithmic, file based, or constrained random testactually hits the conditions in your test plan.

Don’t forget the engineers creed, “In the divine we trust, all others need to show supporting data.” Whether youare using directed, algorithmic, file based, or constrained random test methods, functional coverage provides yoursupporting data.

What is “Coverage” then?

The word coverage can refer to functional coverage, code coverage, or property coverage (such as with PSL).Since this document focuses on functional coverage, when the word coverage is used by itself, it is functionalcoverage.

1.1.3 User Guides

Todo

Write an introduction for all user guides.

1.1. xx.01.2016 - 2016.01 was release. 5


Functional Coverage Package

Todo

link to Functional Coverage

Writing Functional Coverage Using CoveragePkg

Functional coverage can be written using any code. CoveragePkg and language syntax are solely intended tosimplify this effort. In this section, we will first look at implementing functional coverage manually (withoutCoveragePkg). Then we will look at using CoveragePkg to capture item and cross coverage.

Item (Point) Coverage done Manually In this subsection we write item coverage using regular VHDL code.While for most problems this is the hard way to capture coverage, it provides a basis for understanding functionalcoverage.

In a packet based transfer (such as across an ethernet port), most interesting things happen when the transfer size isat or near either the minimum or maximum sized transfers. It is important that a number of medium sized transfersoccur, but we do not need to see as many of them. For this example, let’s assume that we are interested in trackingtransfers that are either the following size or range: 1, 2, 3, 4 to 127, 128 to 252, 253, 254, or 255. The sizes welook for are specified by our test plan.

We also must decide when to capture (aka sample) the coverage. In the following code, we use the rising edge ofclock where the flag TransactionDone is 1.

signal Bin : integer_vector(1 to 8) ; . . . process begin wait until rising_edge(Clk) and TransactionDone = ‘1’; case to_integer(unsigned(ActualData)) is when 1 => Bin(1) <= Bin(1) + 1 ; when 2 => Bin(2) <= Bin(2) + 1 ;when 3 => Bin(3) <= Bin(3) + 1 ; when 4 to 127 => Bin(4) <= Bin(4) + 1 ; when 128 to 252 => Bin(5) <= Bin(5)+ 1 ; when 253 => Bin(6) <= Bin(6) + 1 ; when 254 => Bin(7) <= Bin(7) + 1 ;

when 255 => Bin(8) <= Bin(8) + 1 ; when others => end case ; end process ;

Any coverage can be written this way. However, this is too much work and too specific to the problem at hand. Wecould make a small improvement to this by capturing the code in a procedure. This would help with local reuse,but there are still no built-in operations to determine when testing is done, to print reports, or to save results andthe data structure to a file.

Basic Item (Point) Coverage with CoveragePkg In this subsection we use CoveragePkg to write the itemcoverage for the same packet based transfer sizes created in the previous section manually. Again, we are mostinterested in the smallest and largest transfers. Hence, for an interface that can transfer between 1 and 255 wordswe will track transfers of the following size or range: 1, 2, 3, 4 to 127, 128 to 252, 253, 254, and 255.

The basic steps to model functional coverage are declare the coverage object, create the coverage model, accumu-late coverage, interact with the coverage data structure, and report the coverage.

Coverage is modeled using a data structure stored inside of a coverage object. The coverage object is created bydeclaring a shared variable of type CovPType, such as CovBin1 shown below.

architecture Test1 of tb is shared variable CovBin1 : CovPType ; begin

Internal to the data structure, each bin in an item coverage model is represented by a minimum and maximumvalue (effectively a range). Bins that have only a single value, such as 1 are represented by the pair 1, 1 (meaning1 to 1). Internally, the minimum and maximum values are stored in a record with other bin information.

The coverage model is constructed by using the method AddBins and the function GenBin. The function GenBintransforms a bin descriptor into a set of bins. The method AddBins inserts these bins into the data structure internalto the protected type. Note that when calling a method of a protected type, such as AddBins shown below, themethod name is prefixed by the protected type variable name, CovBin1. The version of GenBin shown below has

6 Chapter 1. News


three parameters: min value, max value, and number of bins. The call, GenBin(1,3,3), breaks the range 1 to 3 intothe 3 separate bins with ranges 1 to 1, 2 to 2, 3 to 3.

TestProc : process begin – min, max, #bins CovBin1.AddBins(GenBin(1, 3, 3)); – bins 1 to 1, 2 to 2, 3 to 3 . . .

Additional calls to AddBins appends additional bins to the data structure. As a result, the call, GenBin(4, 252, 2),appends two bins with the ranges 4 to 127 and 128 to 252 respectively to the coverage model.

CovBin1.AddBins(GenBin( 4, 252, 2)) ; – bins 4 to 127 and 128 to 252

Since creating one bin for each value within a range is common, there is also a version of GenBin that has twoparameters: min value and max value which creates one bin per value. As a result, the call GenBin(253, 255)appends three bins with the ranges 253 to 253, 254 to 254, and 255 to 255.

CovBin1.AddBins(GenBin(253, 255)) ; – bins 253, 254, 255

Coverage is accumulated using the method ICover. Since coverage is collected using sequential code, either clockbased sampling (shown below) or transaction based sampling (by calling ICover after a transaction completes -shown in later examples) can be used.

– Accumulating coverage using clock based sampling loop wait until rising_edge(Clk) and nReset = ‘1’ ; Cov-Bin1.ICover(to_integer(unsigned(RxData_slv))) ; end loop ; end process ;

A test is done when functional coverage reaches 100%. The method IsCovered returns true when all the countbins in the coverage data structure have reached their goal. The following code shows the previous loop modifiedso that it exits when coverage reaches 100%.

– capture coverage until coverage is 100% while not CovBin1.IsCovered loop wait until rising_edge(Clk) andnReset = ‘1’ ; CovBin1.ICover(to_integer(RxData_slv)) ; end loop ;

Finally, when the test is done, the method WriteBin is used to print the coverage results to the file specified byTranscriptPkg (either TranscriptFile, OUTPUT, or both if mirroring is enabled).

CovBin1.WriteBin ;

Putting the entire example together, we end up with the following.

architecture Test1 of tb is shared variable CovBin1 : CovPType ; – Coverage Object begin TestProc : pro-cess begin – Model the coverage CovBin1.AddBins(GenBin( 1, 3 )) ; CovBin1.AddBins(GenBin( 4, 252, 2)); CovBin1.AddBins(GenBin(253, 255 )) ; – Accumulating Coverage – clock based sampling while not Cov-Bin1.IsCovered loop wait until rising_edge(Clk) and nReset = ‘1’ ; CovBin1.ICover(to_integer(RxData_slv)) ;end loop ; – Print Results CovBin1.WriteBin ; wait ; end process ;

Note that when modeling coverage, we primarily work with integer values. All of the inputs to GenBin and ICoverare integers; WriteBin reports results in terms of integers. This is similar to what other verification languages do.

Cross Coverage with CoveragePkg Cross coverage examines the relationships between different objects, suchas making sure that each register source has been used with an ALU. The hardware we are working with is asshown below. Note that the test plan will also be concerned about what values are applied to the adder. We are notintending to address that part of the test here.

Mux8:1Mux8:1Q0Q7D0D7............SRC1SRC2

Cross coverage for SRC1 crossed SRC2 with can be visualized as a matrix of 8 x 8 bins.

R7R6R5R4R3R2R1R0R7R6R5R4R3R2R1R0SRC2SRC1

The steps for modeling cross coverage are the same steps used for item coverage: declare, model, accumulate,interact, and report. Collecting cross coverage only differs in the model and accumulate steps.

Cross coverage is modeled using the method AddCross and two or more calls to function GenBin. AddCrosscreates the cross product of the set of bins (created by GenBin) on its inputs. The code below shows the call tocreate the 8 x 8 cross. Each call to GenBin(0,7) creates the 8 bins: 0, 1, 2, 3, 4, 5, 6, 7. The AddCross creates the64 bins cross product of these bins. This can be visualized as the matrix shown previously.

ACov.AddCross( GenBin(0,7), GenBin(0,7) );

1.1. xx.01.2016 - 2016.01 was release. 7


AddCross supports crossing of up to 20 items. Internal to the data structure there is a record that holds minimumand maximum values for each item in the cross. Hence for the first bin, the record contains SRC1 minimum 0,SRC1 maximum 0, SRC2 minimum 0, and SRC2 maximum 0. The record also contains other bin information(such as coverage goal, current count, bin type (count, illegal, ignore), and weight).

The accumulate step now requires a value for SRC1 and SRC2. The overloaded ICover method for cross coverageuses an integer_vector input. This allows it to accept a value for each item in the cross. The extra set of parenthesesaround Src1 and Src2 in the call to ICover below designate that it is a integer_vector.

ACov.ICover( (Src1, Src2) ) ;

The code below shows the entire example. The shared variable, ACov, declares the coverage object. AddCrosscreates the cross coverage model. IsCovered is used to determine when all items in the coverage model have beencovered. Each register is selected using uniform randomization (RandInt). The transaction procedure, DoAluOp,applies the stimulus. ICover accumulates the coverage. WriteBin reports the coverage.

13

architecture Test2 of tb is shared variable ACov : CovPType ; – Declare begin TestProc : process variable RV: RandomPType ; variable Src1, Src2 : integer ; begin – create coverage model ACov.AddCross( GenBin(0,7),GenBin(0,7) ); – Model while not ACov.IsCovered loop – Done? Src1 := RV.RandInt(0, 7) ; – Uniform Random-ization Src2 := RV.RandInt(0, 7) ; DoAluOp(TRec, Src1, Src2) ; – Transaction ACov.ICover( (Src1, Src2) ) ; –Accumulate end loop ; ACov.WriteBin ; – Report EndStatus(. . . ) ; end process ;

Intelligent Coverage is 5X or more faster than constrained random

Constrained Random Repeats Test Cases In the previous section we used uniform randomization (shownbelow) to select the register pairs for the ALU. Constrained random at its best produces a uniform distribution.As a result, the previous example is a best case model of constrained random tests. Src1 := RV.RandInt(0, 7) ;– Uniform Randomization Src2 := RV.RandInt(0, 7) ; The problem with constrained random testbenches is thatthey repeat some test cases before generating all test cases. In general to generate N cases, it takes “N * log N”randomizations. The “log N” represents repeated test cases and significantly adds to simulation run times. Ideallywe would like to run only N test cases.

Running the previous ALU testbench, we get the following coverage matrix when the code completes. Notethat some case were generated 10 time before all were done at least 1 time. It took 315 randomizations togenerate all 64 unique pairs. This is slightly less than 5X more iterations than the 64 in the ideal case. Thiscorrelates well with theory as 315 64 * log(64). By changing the seed value, the exact number of random-izations may increase or decrease but this would be a silly way to try to reduce the number of iterations a testruns. R7R6R5R4R3R2R1R0R7R6R5R4R3R2R1R0SRC2SRC1566419664559634364323514644336557710910554835363646417436354566437

5.2 Intelligent Coverage “Intelligent Coverage” is a coverage driven randomization approach that randomlyselects a hole in the functional coverage and passes it to the stimulus generation process. Using “IntelligentCoverage” allows the stimulus generation to focus on missing coverage and reduces the number of test casesgenerated to approach the ideal of N randomizations to generate N test cases.

Let’s return to the ALU example. The Intelligent Coverage methodology starts by writing functional coverage.We did this in the previous example too. Next preliminary stimulus is generated by randomizing using the func-tional coverage model. In this example, we will replace the uniform randomization with RandInt with a call toRandCovPoint (one of the Intelligent Coverage randomization methods). This is shown below. In this case, Src1and Src2 are used directly in the test, so we are done.

architecture Test3 of tb is shared variable ACov : CovPType ; – Declare begin TestProc : process variable RV :RandomPType ; variable Src1, Src2 : integer ; begin – create coverage model ACov.AddCross( GenBin(0,7), Gen-Bin(0,7) ); – Model while not ACov.IsCovered loop – Done? (Src1, Src2) := ACov.RandCovPoint ; – IntelligentCoverage Randomization

DoAluOp(TRec, Src1, Src2) ; – Transaction ACov.ICover( (Src1, Src2) ) ; – Accumulate end loop ;ACov.WriteBin ; – Report EndStatus(. . . ) ; end process ;

8 Chapter 1. News


When randomizing across a cross coverage model, the output of RandCovPoint is an integer_vector. Instead ofusing the separate integers, Src1 and Src2, it is also possible to use an integer_vector as shown below.

variable Src : integer_vector(1 to 2) ; . . . Src := ACov.RandCovPoint ; – Intelligent Coverage Randomization

The process is not always this easy. Sometimes the value out of RandCovPoint will need to be further shaped bythe stimulus generation process.

The Intelligent Coverage methodology works now and works with your current testbench approach. You can adoptthis methodology incrementally. Add functional coverage today to make sure you are executing all of your testplan. For the tests that need help, use the Intelligent Coverage.

Intelligent Coverage reduces your work The Intelligent Coverage methodology is different from what is donein a constrained random methodology. Rather than randomizing across holes in the functional coverage, theconstrained random approach adds an equally complex set of randomization constraints to shape the stimulus. Inmany ways, the randomization constraints and functional coverage needed in a constrained random approach areduplicate views of the same information.

With Intelligent coverage, we focus on writing high fidelity coverage models. The constrained random step isreduced to a refinement step and only needs to focus on things that are not already shaped by the coverage. Hence,Intelligent Coverage methodology reduces (or eliminates) the work needed to generate test constraints.

Flexibility and Capability

OSVVM implements functional coverage as a data structure within a protected type. Using methods of the pro-tected type allows both a concise capture of the model (as we saw in the previous examples) and a great degree offlexibility and capability.

The added flexibility and capability comes from writing the model incrementally using any sequential code (if,loop). As long as the entire model is captured before we start collecting coverage, we can use as many calls toAddBins or AddCross as needed. As a result, conditionally capturing coverage based on a generic is straightforward. In addition, algorithms that iterate using a loop are no more trouble than writing the code.

Additional flexibility and capability comes from being able to give each bin within a coverage model a differentcoverage goal. A coverage goal specifies the number of times a value from a particular bin needs to be observedbefore it is considered covered. The Intelligent Coverage randomization by default will use these coverage goalsas randomization weights.

To demonstrate this flexibility, let’s consider a contrived example based on the ALU. In this example, each SRC1crossed with any SRC2 has a different coverage goal. In addition, it is an error if SRC1 and SRC2 are equal. Thecoverage goal for each bin is specified in the table below.

Coverage Goal Src1 Src2 2 0 1, 2, 3, 4, 5, 6, 7 3 1 0, 2, 3, 4, 5, 6, 7 4 2 0, 1, 3, 4, 5, 6, 7 5 3 0, 1, 2, 4, 5, 6, 7 5 4 0,1, 2, 3, 5, 6, 7 4 5 0, 1, 2, 3, 4, 6, 7 3 6 0, 1, 2, 3, 4, 5, 7 2 7 0, 1, 2, 3, 4, 5, 6 Illegal Src1 = Src2

To model the above functional coverage, we use a separate call for each different coverage goal. The function,IllegalBin, is used to mark the bins with Src1 = Src2 illegal. This is shown below.

architecture Test4 of tb is shared variable ACov : CovPType ; – Declare Cov Object begin TestProc : processvariable Src1, Src2 : integer ; begin – Capture coverage model ACov.AddCross( 2, GenBin (0), IllegalBin(0) &GenBin(1,7)) ; ACov.AddCross( 3, GenBin (1), GenBin(0) & IllegalBin(1) & GenBin(2,7)) ; ACov.AddCross(4, GenBin (2), GenBin(0,1) & IllegalBin(2) & GenBin(3,7)) ; ACov.AddCross( 5, GenBin (3), GenBin(0,2) &IllegalBin(3) & GenBin(4,7)) ; ACov.AddCross( 5, GenBin (4), GenBin(0,3) & IllegalBin(4) & GenBin(5,7)); ACov.AddCross( 4, GenBin (5), GenBin(0,4) & IllegalBin(5) & GenBin(6,7)) ; ACov.AddCross( 3, GenBin(6), GenBin(0,5) & IllegalBin(6) & GenBin(7)) ; ACov.AddCross( 2, GenBin (7), GenBin(0,6) & IllegalBin(7)) ; while not ACov.IsCovered loop – Done? (Src1, Src2) := ACov.RandCovPoint ; – Randomize with cover-age DoAluOp(TRec, Src1, Src2) ; – Do a transaction ACov.ICover( (Src1, Src2) ) ; – Accumulate end loop ;ACov.WriteBin ; – Report EndStatus(. . . ) ; end process ;

Note that the remainder of this document covers further details of these methods and additional overloading.

1.1. xx.01.2016 - 2016.01 was release. 9


Package References and Compilation for CoveragePkg and Friends

Your programs will need to reference CoveragePkg as follows. Setting the CovOptionsType parameters on Write-Bin, WriteCovHoles, and SetReportOptions may require the usage of OsvvmGlobalPkg in some simulators.

library osvvm ;

use osvvm.OsvvmGlobalPkg.all ; – options for WriteBin, SetReportOptions use osvvm.CoveragePkg.all ;

CoveragePkg references the packages NamePkg, MessagePkg, and OsvvmGlobalPkg. We compile NamePkg,MessagePkg, OsvvmGlobalPkg, and CoveragePkg into a library named “osvvm”. Be sure to use the VHDL-2008switch when you compile them.

Declaration of the Coverage Object - CovPType

A coverage model is contained within a CovPType typed shared variable. Using a protected type allows bothaccess to the structure from multiple processes and hides details of the model within the data structure.

The shared variable declaration for the coverage object is commonly put in the architecture of the design as shownbelow.

architecture Test3 of tb is shared variable ACov : CovPType ; – Declare Cov Object begin

Basic Bin Description

The functions GenBin, IllegalBin, and IgnoreBin are used to create bins of type CovBinType. These bins are usedas inputs to the methods, AddBins and AddCross, that create the coverage data structure. Using these functionsreplaces the need to know the details of type CovBinType.

Basic Type for Coverage Bins The output type of the functions GenBin, IllegalBin, and IgnoreBin is CovBin-Type. It is declared as an array of the record type, CovBinBaseType. This is shown below. Note the details ofCovBinBaseType are not provided as they may change from time to time.

type CovBinBaseType is record . . . end record ; type CovBinType is array (natural range <>) of CovBinBaseType;

Creating Count Bins - GenBin The following are five variations of GenBin. The ones with AtLeast and Weightparameters are mainly intended to for use with constants.

function GenBin(Min, Max, NumBin : integer ) return CovBinType ; function GenBin(Min, Max : integer) returnCovBinType ; function GenBin(A : integer) return CovBinType ;

The version of GenBin shown below has three parameters: min value, max value, and number of bins. The call,GenBin(1, 3, 3), breaks the range 1 to 3 into the 3 separate bins with ranges1 to 1, 2 to 2, 3 to 3.

– min, max, #bins

CovBin1.AddBins(GenBin(1, 3, 3)); – bins 1 to 1, 2 to 2, 3 to 3

If there are less values (between max and min) than bins, then only “max - min + 1” bins will be created. As aresult, the call GenBin(1,3,20), will still create the three bins: 1 to 1, 2 to 2 and 3 to 3.

CovBin2.AddBins( GenBin(1, 3, 20) ) ; – bins 1 to 1, 2 to 2, and 3 to 3

If there are more values (between max and min) than bins and the range does not divide evenly among bins, theneach bin with have on average (max - min + 1)/bins. Later bins will have one more value than earlier bins. Theexact formula used is (number of values remaining)/(number of bins remaining). As a result, the call GenBin(1,14, 4) creates four bins with ranges 1 to 3, 4 to 6, 7 to 10, and 11 to 14.

CovBin2.AddBins( GenBin(1, 14, 4) ) ; – 1 to 3, 4 to 6, 7 to 10, 11 to 14

10 Chapter 1. News


Since creating one bin per value in the range is common, there is also a version of GenBin that has two parameters:min value and max value which creates one bin per value. As a result, the first call to AddBins/GenBin can beshortened to the following.

– min, max CovBin1.AddBins(GenBin(1, 3)); – bins 1 to 1, 2 to 2, and 3 to 3 GenBin can also be called withone parameter, the one value that is contained in the bin. Hence the call, GenBin(5) creates a single bin withthe range 5 to 5. The following two calls are equivalent. CovBin3.AddBins( GenBin(5) ) ; CovBin3.AddBins(GenBin(5,5,1) ) ; – equivalent call

Creating Illegal and Ignore Bins - IllegalBin and IgnoreBin When creating bins, at times we need to markbins as illegal and flag errors or as ignored actions and not to count them.

The functions IllegalBin and IgnoreBin are used to create illegal and ignore bins. One version of IllegalBin andIgnoreBin has three parameters: min value, max value, and number of bins (just like GenBin).

– min, max, NumBin IllegalBin( 1, 9, 3) – creates 3 illegal bins: 1-3, 4-6, 7-9 IllegalBin( 1, 9, 1) – creates oneillegal bin with range 1-9 IgnoreBin ( 1, 3, 3) – creates 3 ignore bins: 1, 2, 3

There are also two parameter versions of IgnoreBin and IllegalBin that creates a single bin. Some examples ofthis are illustrated below. While this is different from the action of the two parameter GenBin calls, it matches thecommon behavior of creating illegal and ignore bins.

– min, max IllegalBin( 1, 9) – creates one illegal bin with range 1-9 IgnoreBin ( 1, 3) – creates one ignore bin withrange 1-3

There are also one parameter versions of IgnoreBin and IllegalBin that creates a single bin with a single value.Some examples of this are illustrated below.

– AVal IllegalBin( 5 ) – creates one illegal bin with range 5-5 IgnoreBin ( 7 ) – creates one ignore bin with range7-7

Predefined Bins - ALL_BIN, . . . , ALL_ILLEGAL, ZERO_BIN, ONE_BIN The following are predefinedbins.

constant ALL_BIN : CovBinType := GenBin(integer’left, integer’right, 1) ; constant ALL_COUNT : CovBin-Type := GenBin(integer’left, integer’right, 1) ; constant ALL_ILLEGAL : CovBinType := IllegalBin(integer’left,integer’right, 1) ; constant ALL_IGNORE : CovBinType := IgnoreBin(integer’left, integer’right, 1) ; constantZERO_BIN : CovBinType := GenBin(0) ; constant ONE_BIN : CovBinType := GenBin(1) ;

Combining Bins Using Concatenation - & Since GenBin, IllegalBin, and IgnoreBin all return CovBinType,their results can be concatenated together. As a result, the following calls to GenBin creates the bins: 1 to 1, 2 to2, 3 to 3, 2 to 127, 128 to 252, 253 to 253, 254 to 254, and 255 to 255.

CovBin1.AddBins(GenBin(0, 2) & GenBin(3, 252, 2) & GenBin(253, 255));

Calls to GenBin, IllegalBin, and IgnoreBin can also be combined. As a result the following creates the fourseparate legal bins (1, 2, 5, and 6), a single ignore bin (3 to 4), and everything else falls into an illegal bin.

CovBin2.AddBins( GenBin(1,2) & IgnoreBin(3,4) & GenBin(5,6) & ALL_ILLEGAL ) ;

Data Structure Construction

The coverage model data structure is created using the methods AddBins and AddCross.

Item (Point) Bins - AddBins The method AddBins is used to add item coverage bins to the coverage datastructure. Each time it is called new bins are appended after any existing bins. AddBins has additional parametersto allow specification of coverage goal (AtLeast) and randomization weight (Weight). By using separate calls toAddBins, each bin can have a different coverage goal and/or randomization weight.

procedure AddBins (CovBin : CovBinType) ;

1.1. xx.01.2016 - 2016.01 was release. 11


Cross Coverage Bins - AddCross The method AddCross is used to add cross coverage bins to the coverage datastructure. Each time it is called new bins are appended after any existing bins. AddCross has additional parametersto allow specification of coverage goal (AtLeast) and randomization weight (Weight). By using separate calls toAddCross, each bin can have a different coverage goal and/or randomization weight.

procedure AddCross( Bin1, Bin2 : CovBinType ; Bin3, Bin4, Bin5, Bin6, Bin7, Bin8, Bin9, Bin10, Bin11, Bin12,Bin13, Bin14, Bin15, Bin16, Bin17, Bin18, Bin19, Bin20 : CovBinType := NULL_BIN ) ;

Controlling Reporting for Illegal Bins - SetIllegalMode By default, illegal bins both count and flag a severityerror alert (see AlertLogPkg user guide). This behavior is controlled by the IllegalMode variable. The default valueof the variable is ILLEGAL_ON. Setting IllegalMode to ILLEGAL_OFF, as shown below, suppresses printing ofmessages when an item is added to an illegal bin. Setting IllegalMode to ILLEGAL_FAILURE causes a severityfailure alert to be printed when an item is added to an illegal bin.

type IllegalModeType is (ILLEGAL_ON, ILLEGAL_FAILURE, ILLEGAL_OFF) ; Cov-Bin4.SetIllegalMode(ILLEGAL_OFF) ; – Illegal printing off CovBin4.SetIllegalMode(ILLEGAL_ON) ; –Default: Illegal printing on

Bin Size Optimization - SetBinSize SetBinSize can help the creation of a coverage model be more efficient bypre-declaring the number of bins to be created in the coverage data structure. Use this for small bins to save spaceor for large bins to suppress the resize and copy that occurs when the bins automatically resize.

procedure SetBinSize (NewNumBins : integer) ;

Accumulating Coverage - ICover

The method ICover is used to accumulate coverage. For item (point) coverage, ICover accepts an integer value.For cross coverage, ICover accepts an integer_vector. The procedure interfaces are shown below. Since thecoverage accumulation is written procedurally, ICover will support either clock based sampling or transactionbased sampling (examples of both shown previously).

procedure ICover( CovPoint : in integer ) ; procedure ICover( CovPoint : in integer_vector ) ;

Since the inputs must be either type integer or integer_vector, conversions must be used. To convert fromstd_logic_vector to integer, numeric_std_unsigned and numeric_std provide the following conversions.

CovBin3.ICover( to_integer(RxData_slv) ) ; – using numeric_std_unsigned (2008) CovBin3.ICover(to_integer(unsigned(RxData_slv)) ) ; – using numeric_std

To convert either std_logic or boolean to integer, CoveragePkg provides overloading for to_integer.

CovBin3.ICover( to_integer(Empty) ) ; – std_logic CovBin3.ICover( to_integer(Empty = ‘1’) ) ; – boolean

To convert either std_logic_vector or boolean_vector to integer_vector (bitwise), CoveragePkg providesto_integer_vector functions.

CrossBin.ICover( to_integer_vector(CtrlReg_slv) ) ; – std_logic_vector CrossBin.ICover(to_integer_vector((Empty=‘1’)&(Rdy=‘1’)) ) ; – boolean_vector

Since the language does not do introspection of aggregate values when determining the type of an expression, theboolean vector expression needs to be constructed using concatenation (as shown above) rather than aggregates(as shown below).

–! CrossBin.ICover( to_integer_vector( ((Empty=‘1’),(Rdy=‘1’)) )); – ambiguous

Basic Randomization

Randomization is handled by either RandCovPoint and RandCovBinVal. The randomization is coverage targetbased. Once a count bin has reached its coverage goal it is no longer selected for randomization. The randomiza-tion results can be modified by using coverage goals, randomization weights, coverage targets, and randomizationthresholds. These topics are discussed later in this document.

12 Chapter 1. News


Randomly generating a value within a bin - RandCovPoint RandCovPoint returns a randomly selected value(also referred to as a point) within the randomly selected bin. It returns integer_vector values for cross coveragebins, and integer or integer_vector for item (point) bins. The overloading for RandCovPoint is shown below.

impure function RandCovPoint return integer_vector ; impure function RandCovPoint return integer ;

Randomly selecting a coverage bin - RandCovBinVal RandCovBinVal returns a randomly selected bin valueof type RangeArrayType. The type RangeArrayType and the function definitions are shown below. Note RangeAr-rayType may change in the future.

type RangeType is record min, max : integer ; end record ; type RangeArrayType is array (integer range <>) ofRangeType; impure function RandCovBinVal return RangeArrayType ;

Randomization, Illegal, and Ignore Bins RandCovPoint and RandCovBinVal will never select a bin markedas illegal or ignore. However, if count bin intersects with a prior specified illegal or ignore bin then the illegalor ignore value may be generated by randomization. Currently care must be taken to avoid this. In revision2013.04, if merging is enabled (see SetMerging) any count bin that is included in a prior illegal or ignore bin willbe dropped.

Coverage Model Statistics

Coverage model statistics collecting methods allow us to check if the model is covered/testing is done (IsCovered),check if the model is initialized (IsInitialized), or check the current total coverage (GetCov).

Model Covered - Testing Done - IsCovered The function IsCovered returns TRUE when all count bins havereached their coverage goal. This indicates that coverage is complete and testing is done. IsCovered is declared asfollows. Just like ICover, IsCovered is called either at a sampling point of either the clock or a transaction.

impure function IsCovered return boolean ; – Uses CovTarget impure function IsCovered ( PercentCov : real )return boolean ;

Model Initialized - IsInitialized The function IsInitialized returns a true when a coverage model has bins (hasbeen initialized). IsInitialized is a useful check when constructing the coverage model in a separate process fromcollecting the coverage.

impure function IsInitialized return boolean ;

Number of Items Randomized - GetItemCount The function GetItemCount returns the number of items thathave been randomized in the coverage model.

impure function GetItemCount return integer ;

Total Coverage Goal - GetTotalCovGoal The function GetTotalCovGoal returns the sum of each bins cov-erage. Coverage models with a simple relationship between the stimulus and the desired coverage will reachcoverage closure in GetTotalCovGoal number of randomizations.

impure function GetTotalCovGoal return integer ; – uses CovTarget impure function GetTotalCovGoal ( Percent-Cov : real ) return integer ;

13.5 Current Percent Coverage - GetCov The function GetCov returns a type real value that indicates thecurrent percent completion (0.0 to 100.0) of the coverage model. It has the following overloading.

impure function GetCov return real ; impure function GetCov (PercentCov : real) return real ;

1.1. xx.01.2016 - 2016.01 was release. 13


Reporting Coverage

Coverage results can be written as either all the bins (WriteBin) or just the bins that have not reached their cov-erage goal (WriteCovHoles). By default, these print to the file specified by TranscriptPkg (either TranscriptFile,OUTPUT, or both if mirroring is enabled). There is also an option to use a local file. In addition, one or morelines of heading (SetMessage) may be printed before the results.

Reporting Bin Results - WriteBin The procedure WriteBin prints out the coverage results with one bin printedper line. All count bins are printed. Illegal bins are printed if they have a non-zero count. Ignore bins are notprinted. The weight field of the coverage bin is only printed when the weight is being use (see WeightMode). Itsdeclaration and an example of usage is shown below.

procedure WriteBin ; . . . CovBin1.WriteBin ;

Reporting Coverage Holes - WriteCovHoles WriteCovHoles prints out count bin results that are below thecoverage goal. Its declaration and an example usage is shown below.

procedure WriteCovHoles ( LogLevel : LogType := ALWAYS ) ; . . . CovBin1.WriteCovHoles ;

When the LogLevel parameter is specified (such as DEBUG) and that Level is not enabled within AlertLogPkg,then the WriteCovHoles will not print. The WriteCovHoles with a LogLevel parameter of “ALWAYS” alwaysprints.

Setting Headings - SetMessage The method SetMessage sets headings for WriteBin and WriteCovHoles. Eachcall to SetMessage creates a separate line in the output of either WriteBin or WriteCovHoles.

procedure SetMessage (NameIn : String ) ; . . . CovBin1.SetMessage(“DMA”) ; – first line of heading Cov-Bin1.SetMessage(“Stat, WordCnt”) ; – second line of heading

If the headings need to be cleared, use the method DeallocateMessage. It is called as follows.

CovBin1.DeallocateMessage ; – clears all headings

If the internal randomization seed has not yet been initialized, the first call to SetMessage will initialize the seedusing the string value.

The method SetItemName is deprecated. It is currently maintained for backward compatibility and it simply callsSetMessage.

If SetMessage is not set, the value in SetName will be used instead.

Setting the Coverage Model Name - SetName The method SetName sets the name of the coverage model.The coverage model name is printed when an illegal bin is encountered and in alerts generated withn a particularcoverage model. Additional calls to SetName will replace the previous value in SetName.

procedure SetName (NameIn : String ) ; impure function SetName (Name : String) return string ; . . . Cov-Bin1.SetName(“DMA Cov”) ;

If the internal randomization seed has not yet been initialized, the first call to SetName will initialize the seedusing the string value.

The function form is intended to be used with chaining calls. For example, a more explicit way to set the coveragemodel name and set the seed can be accomplished by:

CovBin1.InitSeed( CovBin1.SetName(“DMA Cov”) ) ;

If SetName is not set, the first word in the first message (SetMessage) will be used instead.

Getting the Coverage Model Name - GetName The method GetName gets the name of the coverage model.

impure function GetName return String ; . . . CovBin1.InitSeed( CovBin1.GetName ) ;

14 Chapter 1. News


Setting Bin Names Each bin can be named. The bin name is specified as the first parameter to AddBins andAddCross. This means to use names, one must specify each bin individually (bin by bin). The intent behind binnames it to correlate a requirement with a bin name and furthermore associate this with a pass or fail indication ofthe requirement.

procedure AddBins ( Name : String ; CovBin : CovBinType ) ; procedure AddCross( Name : string ; Bin1, Bin2: CovBinType ; Bin3, Bin4, Bin5, Bin6, Bin7, Bin8, Bin9, Bin10, Bin11, Bin12, Bin13, Bin14, Bin15, Bin16,Bin17, Bin18, Bin19, Bin20 : CovBinType := NULL_BIN ) ;

Note that each call to AddBins and AddCross supports a Name as the first parameter.

Enabling and Disabling WriteBin fields WriteBin uses the following format when printing. This format is anextension of the original WriteBin format and was added to facilitate integration with requirements tracing tools.

{Prefix} [BinName] [PASSED|FAILED] [BinInfo] [Count]

WriteBin has parameters to control printing of each of these fields. The overloading for WriteBin (without a filestring specified) is:

procedure WriteBin ( – without LogLevel WritePassFail : CovOptionsType := COV_OPT_DEFAULT ; Write-BinInfo : CovOptionsType := COV_OPT_DEFAULT ; WriteCount : CovOptionsType := COV_OPT_DEFAULT; WriteAnyIllegal : CovOptionsType := COV_OPT_DEFAULT ; WritePrefix : string := “” ; PassName : string:= “” ; FailName : string := “” ) ; procedure WriteBin ( – With LogLevel LogLevel : LogType ; WritePassFail :OsvvmOptionsType := COV_OPT_DEFAULT ; WriteBinInfo : OsvvmOptionsType := COV_OPT_DEFAULT; WriteCount : OsvvmOptionsType := COV_OPT_DEFAULT ; WriteAnyIllegal : OsvvmOptionsType :=COV_OPT_DEFAULT ; WritePrefix : string := OSVVM_DEFAULT_STRING_INIT ; PassName : string :=OSVVM_DEFAULT_STRING_INIT ; FailName : string := OSVVM_DEFAULT_STRING_INIT ) ;

If the LogLevel parameter is specified (such as DEBUG) and that Level is not enabled within AlertLogPkg, thenthe WriteBin will not print. The WriteBin without the LogLevel parameter always prints.

The type CovOptionsType is used to specify values for many of these parameters. It is defined as follows.

type CovOptionsType is (COV_OPT_DEFAULT, DISABLED, ENABLED) ;

The default values for parameters to Write bins is initially as shown in the table below. The reason they arenot specified directly on the WriteBin interface is that they are [local/global] settings that can be changed by theprocedure set SetReportOptions. For details, see next section.

WritePassFail DISABLED WriteBinInfo ENABLED WriteCount ENABLED WriteAnyIllegal DISABLEDWritePrefix “%% ” PassName “PASSED” FailName “FAILED”

When all parameters are enabled, the report will print with the following format.

%% State0 PASSED Bin:(0) Count = 1 AtLeast = 1 %% State1 PASSED Bin:(1) Count = 1 AtLeast = 1 %%State2 FAILED Bin:(2) Count = 0 AtLeast = 1 %% State3 FAILED Bin:(3) Count = 0 AtLeast = 1

The “%% ” is the default prefix. It can be changed by specifying a value for WritePrefix. The “State0”, “State1”,. . . are the names of the bins and if present always print. Next is the PassFail message. It will print “PASSED” ifthe count is greater than or equal to the goal (AtLeast value), otherwise, it prints “FAILED”. The PassFail messageis enabled using the WritePassFail field. The value printed when it passes or fails is controlled by the PassNameand FailName fields. Printing of bin information is redundant when a bin is named. This information can bedisabled suing the WriteBinInfo field. Printing of the Count (current coverage) and AtLeast (coverage goal) canbe disabled with the WriteCount field. Nominally illegal bins are only printed when the have failed (somethinglanded in that bin). The parameter, WriteAnyIllegal, can be used to enable printing of all illegal bins (includingthe ones with no values and hence pass).

Setting Defaults for WriteBin fields: SetReportOptions The procedure SetReportOptions sets defaults forthe WriteBin options for a single coverage model. To set report options for all coverage models, see Osvvm-GlobalPkg. SetOsvvmGlobalOptions. The interface for SetReportOptions is as follows. procedure SetReportOp-tions ( WritePassFail : CovOptionsType := COV_OPT_INIT_PARM_DETECT ; WriteBinInfo : CovOptionsType:= COV_OPT_INIT_PARM_DETECT ; WriteCount : CovOptionsType := COV_OPT_INIT_PARM_DETECT; WriteAnyIllegal : CovOptionsType := COV_OPT_INIT_PARM_DETECT ; WritePrefix : string :=

1.1. xx.01.2016 - 2016.01 was release. 15


OSVVM_STRING_INIT_PARM_DETECT ; PassName : string := OSVVM_STRING_INIT_PARM_DETECT;

FailName : string := OSVVM_STRING_INIT_PARM_DETECT ) ;

After setting a value, a string value can be reset using OSVVM_STRING_USE_DEFAULT and an OsvvmOption-sType value can be reset using OPT_USE_DEFAULT.

Using Files - FileOpenWriteBin, WriteBin, and WriteCovHoles Since a file parameter cannot be used withWriteBin and WriteCovHoles, either a file must be opened within the coverage model or an awkward set of stringand File_Open_Kind parameters must be used.

If every WriteBin or WriteCovHoles writes to the same file, then FileOpenWriteBin can be use to open a fileinternal to the coverage model. The declaration of FileOpenWriteBin is shown below. When a file is open andWriteBin or WriteCovHoles is called without a file specification, then the opened file is used rather than OUTPUT.

procedure FileOpenWriteBin (FileName : string; OpenKind : File_Open_Kind ) ;

There is also a corresponding FileCloseWriteBin.

procedure FileCloseWriteBin ;

If several different files are used with WriteBin or WriteCovHoles, then the file name and open kind can bespecified as a parameters. The overloading for WriteBin is as follows.

procedure WriteBin ( – Without LogLevel FileName : string; OpenKind : File_Open_Kind := AP-PEND_MODE ; WritePassFail : CovOptionsType := COV_OPT_DEFAULT ; WriteBinInfo : CovOptionsType:= COV_OPT_DEFAULT ; WriteCount : CovOptionsType := COV_OPT_DEFAULT ; WriteAnyIllegal : Cov-OptionsType := COV_OPT_DEFAULT ; WritePrefix : string := “” ; PassName : string := “” ; FailName :string := “” ) ; procedure WriteBin ( – With LogLevel LogLevel : LogType ; FileName : string; OpenKind: File_Open_Kind := APPEND_MODE ; WritePassFail : OsvvmOptionsType := COV_OPT_DEFAULT; WriteBinInfo : OsvvmOptionsType := COV_OPT_DEFAULT ; WriteCount : OsvvmOptionsType :=COV_OPT_DEFAULT ; WriteAnyIllegal : OsvvmOptionsType := COV_OPT_DEFAULT ; WritePrefix : string:= OSVVM_DEFAULT_STRING_INIT ; PassName : string := OSVVM_DEFAULT_STRING_INIT ; FailName: string := OSVVM_DEFAULT_STRING_INIT ) ;


The overloading for WriteCovHoles is as follows.

procedure WriteCovHoles ( FileName : string; OpenKind : File_Open_Kind := APPEND_MODE ) ; procedureWriteCovHoles ( LogLevel : LogType ; FileName : string; OpenKind : File_Open_Kind := APPEND_MODE ) ;

When a LogLevel parameter is specified (such as DEBUG) and that Level is not enabled within AlertLogPkg,then the WriteCovHoles will not print. The WriteCovHoles without the LogLevel parameter always prints.

Note, WRITE_MODE initializes and opens a file, so make sure to only use it on the first write to the file. For allsubsequent writes to the same file use APPEND_MODE (hence it is the default). The following shows a call toWriteBin followed by a call to WriteCovHoles.

– FileName, OpenKind CovBin1.WriteBin (“Test1.txt”, WRITE_MODE); CovBin1.WriteCovHoles (“Test1.txt”,APPEND_MODE);

Coverage Goals and Randomization Weights

Coverage goals and randomization weights are an important part of the Intelligent Coverage methodology. Acoverage goal specifies how many times a value must land in a bin before the bin is considered covered. Arandomization weight determines the relative number of times a bin will be selected in randomization. In VHDL,each bin within a coverage model may have a different coverage goal and randomization weight.

Up to this point, every coverage bin has a coverage goal of 1 and that value has been used as the randomizationweight. However, some tests require coverage goal of other than one and some tests require a randomization

16 Chapter 1. News


weight that is different from the coverage goal. This section addresses how to set coverage goals and randomizationweights using overloaded methods and functions in CoveragePkg.

Specifying Coverage Goals - AddBins, AddCross, and GenBin A coverage goal can be set by using theAtLeast parameter of AddBins or AddCross. By default this coverage goal will also be used as the randomizationweight. The declaration for these is shown below.

procedure AddBins (AtLeast : integer ; CovBin : CovBinType) ; procedure AddCross( AtLeast : integer ; Bin1,Bin2 : CovBinType ; Bin3, Bin4, Bin5, Bin6, Bin7, Bin8, Bin9, Bin10, Bin11, Bin12, Bin13,

Bin14, Bin15, Bin16, Bin17, Bin18, Bin19, Bin20 : CovBinType := NULL_BIN ) ;

The GenBin function also has an AtLeast parameter. Its declaration is shown below.

function GenBin(AtLeast, Min, Max, NumBin : integer ) return CovBinType ;

If a bin is an ignore or illegal bin, then the coverage goal is set to 0. If a bin is a count bin and a coverage goal isspecified in more than one place, then the largest specified value is used. If a bin is a count bin and no coveragegoal is specified then the coverage goal is set to 1.

Selecting Randomization Weights - SetWeightMode By default, a coverage goal is used as the randomizationweight. The coverage weight can also be set to use either a bin weight or remaining coverage as the randomizationweight.

Selection of the randomization weight is done using SetWeightMode. The following table lists the current set ofsupported modes and how the randomization weight is calculated.

Mode Weight AT_LEAST AtLeast WEIGHT Bin Weight REMAIN AtLeast - Count *

• Note AtLeast is adjusted if the coverage target /= 100 %

The interface for procedure SetWeightMode is shown below.

type WeightModeType is (AT_LEAST, WEIGHT, REMAIN) ; procedure SetWeightMode (A : WeightModeType);

Note that there are additional undocumented features on SetWeightMode and WeightModeType. Use these at yourown risk as they are subject to change in each revision. Their names and implementation were changed in revision2013.04. If there is one that you have tried that is working better than documented options, please let me know.

Specifying Bin Weight - AddBins, AddCross, and GenBin A bin’s weight is used as the randomization weightwhen the WeightMode WEIGHT is selected by SetWeightMode. A bin’s weight can be set by using the Weightparameter of AddBins or AddCross. If not specified, a bin’s weight value will be 1. The declaration for these isshown below. Note this use of the Weight parameter also requires a coverage goal to be specified.

procedure AddBins (AtLeast, Weight : integer ; CovBin : CovBinType) ; procedure AddCross( AtLeast : integer; Weight : integer ; Bin1, Bin2 : CovBinType ; Bin3, Bin4, Bin5, Bin6, Bin7, Bin8, Bin9, Bin10, Bin11, Bin12,Bin13, Bin14, Bin15, Bin16, Bin17, Bin18, Bin19, Bin20 : CovBinType := NULL_BIN ) ;

The GenBin function also has an Weight parameter. Its declaration is shown below.

function GenBin(AtLeast, Weight, Min, Max, NumBin : in integer) return CovBinType ;

If a bin is an ignore or illegal bin, then the bin weight is set to 0. If a bin is a count bin and a bin weight is specifiedin more place, then the largest specified value is used. If a bin is a count bin and no bin weight is specified thenthe coverage goal is set to 1. Likewise for the coverage goal.

Coverage Targets

For some tests, the AtLeast parameters will be used to set an initial coverage distribution. Later it may be desirableto use the same coverage distribution, but run it for much longer. Use of a coverage target allows the coveragegoal to be scaled (increased or decreased) without having to change anything else in the coverage model. Hence,

1.1. xx.01.2016 - 2016.01 was release. 17


the effective coverage goal for a bin is the product of bin’s AtLeast least value and the coverage model’s coveragetarget value (specifically, AtLeast * CovTarget / 100.0).

Setting a Coverage Target - SetCovTarget The method SetCovTarget sets the coverage model’s coverage target(internally the CovTarget variable).

procedure SetCovTarget (Percent : real) ;

The coverage target is intended to scale the run time of a test without having to change a bin’s AtLeast values.CovTarget is set to 100.0 initially. Setting the coverage target to 1000.0 will increase the run time 10X. Setting thecoverage target to 50.0 will decrease the run time by 2X.

The versions of the following methods that do not have a PercentCov parameter use the CovTarget value: Rand-CovPoint, RandCovBinVal, IsCovered, and WriteCovHoles.

Overriding the Global Coverage Target - PercentCov The methods that use CovTarget also have a versionwith a PercentCov parameter that overrides the CovTarget value. The following methods have a PercentCovparameter.

impure function RandCovPoint (PercentCov : real) return integer_vector ; impure function RandCovPoint (Per-centCov : real) return integer ; impure function RandCovBinVal (PercentCov : real) return RangeArrayType ;impure function IsCovered (PercentCov : real) return boolean ; procedure WriteCovHoles ( PercentCov : real ); procedure WriteCovHoles ( LogLevel : LogType ; PercentCov : real ) ; procedure WriteCovHoles ( FileName: string; PercentCov : real ; OpenKind : File_Open_Kind := APPEND_MODE ) ; procedure WriteCovHoles (LogLevel : LogType ; FileName : string; PercentCov : real ; OpenKind : File_Open_Kind := APPEND_MODE );

Randomization Thresholds - SetThresholding and SetCovThreshold

Ordinarily randomization (using RandCovPoint or RandCovBinVal) can select any bin whose coverage targethas not been reached. Thresholding modifies this by also excluding bins whose coverage exceeds the minimumcoverage plus the threshold value (MinCov + threshold). Thresholding is intended to balance how a test convergesto coverage closure. Thresholding only has meaning when coverage goals (AtLeast * CovTarget/100.0) are greaterthan 1.

The threshold value is set using SetCovThreshold. Thresholding is enabled by either SetCovThreshold or Set-Thresholding.

procedure SetThresholding (A : boolean := TRUE ) ; procedure SetCovThreshold (Percent : real) ;

By setting a coverage threshold of 0.0, the notion of cyclic randomization is extended to work across a coveragemodel.

Handling Overlapping Bins

LastIndex - Count bins overlapping with other counts When RandCovPoint or RandCovBinVal is called, thebin index that generates it is logged in the LastIndex variable. When ICover is called, it searches for the value inthe bin whose index is currently stored in the LastIndex variable. This way if bins overlap, it insures that the binthat generated the value is the bin whose count value is incremented.

Bin Merging

Count Bins Contained in an Illegal or Ignore Bin Bin merging is an experimental feature that drops a countbin if it is contained in a previously defined ignore or illegal bin. Merging is off by default and can be enabled ordisabled with the SetMerging procedure shown below.

procedure SetMerging (A : boolean := TRUE ) ;

18 Chapter 1. News


Currently bin merging also merges count bins when they have identical bin values. Merging of count bins isexpensive. Since this feature is correctly handled by LastIndex, it may be removed in the future. If you need countbins to be merged, please contact the package author.

Count Bins Overlapping with an Illegal or Ignore Bin Count bins overlapping with a previous ignore orillegal bin are problematic. When the count bin is selected for randomization, it may generate an illegal value dueto the overlap.

This may be addressed in a future version. For now it is up to the user understand overlap and to avoid this.

Multiple Matches with ICover - SetCountMode By default, ICover searches for the point in the bin pointedto by LastIndex. If not found there, it searches the bins in order. This mode should satisfy most use models.

SetCountMode is an experimental feature that can be used to change the default behavior. SetCountMode sets theinternal CountMode variable. The default mode, described above, is COUNT_FIRST. If the CountMode is set toCOUNT_ALL, each matching bin is counted. The following shows how to set the CountMode.

type CountModeType is (COUNT_FIRST, COUNT_ALL) ; CovBin4.SetCountMode(COUNT_ALL) ; – Countall matching bins CovBin4.SetCountMode(COUNT_FIRST) ; – default. Only count first matching bin

Attention: This experimental feature may be removed from future versions if it

impacts run time. If you have need for COUNT_ALL, please contact the package author.

Initializing the Seeds - InitSeed, SetSeed, and GetSeed

Intelligent coverage uses pseudo random number generation as its basis. As such, for a given randomization seedvalue it will generate the same sequence of numbers every time a simulation is run. This is important as it meansthat when a bug is found and fixed, the fix can be validated since the same test sequence that caused the bug willbe generated.

On the other hand, it also means that if a design has two identical interfaces and the testbench uses the twoidentical coverage models to generate tests that they will both see the same test sequence. This is not desirablesince it is unlikely to generate interesting interactions between the two interfaces. As a result, it is desirable thateach coverage model is given a different initial seed value. This is simple to do.

The InitSeed method initializes a coverage model’s internal randomization seed. The following example showsthe method overloading and an example call. One easy way to generate a unique seed value for each coverage binis to use the string value generated by ‘path_name applied to the coverage object as shown. Note that the methodSetMessage will also call InitSeed with its parameter if the seed is not already set.

procedure InitSeed (S : string ) ; impure function InitSeed (S : string ) return string ; procedure InitSeed (I : integer) ; . . . CovBin1.InitSeed( CovBin1’path_name ) ; – string


CovBin1.SetName ( CovBin1.InitSeed (“DMA Cov”) ) ;

The methods GetSeed and SetSeed are intended for saving and restoring the seeds. In this case the seed valueis of type RandomSeedType, which is defined in RandomBasePkg. RandomBasePkg also defines procedures forreading and writing RandomSeedType values (see RandomPkg Users Guide for details).

procedure SetSeed (RandomSeedIn : RandomSeedType ) ; impure function GetSeed return RandomSeedType ;

Note that the time it takes to achieve coverage closure with open loop randomization methods, such as Sys-temVerilog’s constrained random, may depend heavily on the initial seed value. Hence, within the SystemVerilogcommunity some may try out different seeds when running simulations just to see if they can improve run times.This is not necessary with OSVVM’s Intelligent Coverage methodology since it only selects from coverage holes.

1.1. xx.01.2016 - 2016.01 was release. 19


Using an AlertLogID

Alerts signaled by CoveragePkg use the internal AlertLogIDVar. By default the value isOSVVM_ALERT_LOG_ID. It can be set to something different by SetAlertLogID.

SetAlertLogID SetAlertLogID sets the internal AlertLogIDVar. There are two forms of SetAlertLogID. Thefirst form is intended to be used when an AlertLogID is shared with other items in the testbench. It is defined asfollows.

procedure SetAlertLogID (A : AlertLogIDType) ;

The second form is intended to create an AlertLogID that is exclusive to the coverage model. It is defined asfollows.

procedure SetAlertLogID( Name : string ; ParentID : AlertLogIDType := ALERTLOG_BASE_ID ; CreateHier-archy : Boolean := TRUE ) ;

GetAlertLogID GetAlertLogID returns the current AlertLogID used to report alerts.

impure function GetAlertLogID return AlertLogIDType ;

Interacting with the Coverage Data Structure

Basic Bin Information impure function GetNumBins return integer ; impure function GetMinIndex return in-teger ; impure function GetMinCov return real ; impure function GetMinCount return integer ; impure functionGetMaxIndex return integer ; impure function GetMaxCov return real ; impure function GetMaxCount returninteger ; impure function GetErrorCount return integer ;

The function GetNumBins returns the number of bins in the coverage model. Bin values are numbered from 1 toNumBins.

The functions GetMinIndex and GetMaxIndex return the index of the first bin with the minimum and maximumpercent coverage of a bin. The functions GetMinCov and GetMaxCov return the minimum and maximum percentcoverage of a bin. The functions GetMinCount and GetMaxCount return the minimum and maximum count in abin.

The function GetErrorCount sums up the count in each of the error bins and returns the resulting value. GenerallyGetErrorCount is called at the end of a testbench for coverage models that have bins marked as illegal.

TestErrCount := CovBin1.GetErrorCount + (Other_Error_Sources) ;

Getting Coverage Point Values In addition to RandCovPoint, there are also the following that return coveragevalue that is within a particular coverage bin. Integer return values are for bins with a single item. Integer_vectorare for single item or cross coverage bins.

impure function GetPoint ( BinIndex : integer ) return integer ; impure function GetPoint ( BinIndex : integer) return integer_vector ; impure function GetMinPoint return integer ; impure function GetMinPoint return inte-ger_vector ; impure function GetMaxPoint return integer ; impure function GetMaxPoint return integer_vector;

The function GetPoint returns a random point within the addressed bin (BinIndex). The functions GetMinPointand GetMaxPoint return a random point within the first bin with minimum and maximum percent coverage.

Getting Coverage Bin Values In addition to RandCovBinVal, there are also the following that return coveragebin value. The return value has type RangeArrayType.

impure function GetBinVal ( BinIndex : integer ) return RangeArrayType ; impure function GetMinBinVal returnRangeArrayType ; impure function GetMaxBinVal return RangeArrayType ;

20 Chapter 1. News


The function GetBinVal returns the bin value of the addressed bin (BinIndex). The functions GetMinBinVal andGetMaxBinVal return the bin value of the first bin with minimum and maximum percent coverage.

Getting Last Randomization Information The method GetLastIndex returns the index value the bin last se-lected for randomization. The method GetLastBinVal returns the bin value of the bin indexed by LastIndex. Theoverloading is as follows.

impure function GetLastIndex return integer ; impure function GetLastBinVal return RangeArrayType ;

Getting Coverage Holes The following functions return information about coverage holes.

impure function CountCovHoles return integer ; impure function CountCovHoles (PercentCov : real) return inte-ger ;

impure function GetHoleBinVal(ReqHoleNum : integer := 1) return RangeArrayType ; impure function GetH-oleBinVal(PercentCov : real) return RangeArrayType ; impure function GetHoleBinVal(ReqHoleNum : integer ;PercentCov : real) return RangeArrayType ;

The function CountCovHoles returns the number of holes that are below the PercentCov parameter. CountCov-Holes without a PercentCov parameter returns the number of holes that are below the CovTarget value.

– PercentCov NumHoles := CovBin1.CountCovHoles( 100.0 ) ;

GetHoleBinVal gets the ReqHoleNum bin with a coverage value less than the PercentCov value. The followingcall to GetHoleBinVal gets the 5th bin that has less than 100% coverage. Note that ReqHoleNum must be between1 and CountCovHoles. GetHoleBinVal without a PercentCov parameter uses CovTarget in its place.

– ReqHoleNum, PercentCov TestData := CovBin1.GetHoleBinVal( 5, 100.0 ) ;

Coverage Database Operations

A coverage model can be written and read using WriteCovDb and ReadCovDb. Using these allows results tobe accumulated across multiple tests, and hence, things like test configurations can be covered and randomized.The method declarations are shown below. Like WriteBin file parameters cannot be used, so WriteCovDb andReadCovDb use parameters that specify the file name as a string and the file open mode.

procedure WriteCovDb (FileName : in string; OpenKind : File_Open_Kind := WRITE_MODE ) ; procedureReadCovDb (FileName : string ; Merge : boolean := FALSE) ;

WriteCovDb saves the coverage model and internal variables into a file. The following shows a call to Write-CovDb. Generally WriteCovDb is called once per test. As a result, WRITE_MODE is the default.

– FileName, OpenKind CovBin1.WriteCovDb( “CovDb.txt”, WRITE_MODE ) ;

The procedure method ReadCovDb reads the coverage model and internal variables from a file. If the optionalMerge parameter is set to TRUE, the values read will be merged with the current coverage model. The followingshows a call to ReadCovDb.

– FileName CovBin1.ReadCovDb( “CovDb.txt”, TRUE );

Bin Clearing and Deconstruction

The procedure SetCovZero sets all the coverage counts in a coverage bin to zero. This allows the counts to be setto zero after reading in a coverage database. A simple call to it is shown below.

CovBin1.SetCovZero ; – set all counts to 0

The procedure Deallocate deallocates the entire database structure and sets the internal variables back to theirdefaults.

CovBin1.Deallocate ;

1.1. xx.01.2016 - 2016.01 was release. 21


Creating Bin Constants

Constants are used for two purposes. The first is to create a short hand name for an item (point) bin (normalconstant stuff) and then use that name later in composing the coverage model. The second is to create the entirecoverage model in the constant to facilitate reuse of the model.

Item (Point) Bin Constants - CovBinType In a previous model, we constructed a cross coverage model usingthe following call to AddCross.

ACov.AddCross( GenBin(0,7), GenBin(0,7) ); – Model

One step of refinement is to create an item bin constant for the register addresses, such as REG_ADDR shownbelow. The type of REG_ADDR is CovBinType. Since constants can extract their range based on the objectassigned to them, it is easiest to leave CovBinType unconstrained.

constant REG_ADDR : CovBinType := GenBin(0, 7) ;

Once created the constant can be used in for further composition, such as shown below. Just like normal constants,this increases both the readability and maintainability of the code.

ACov.AddCross(REG_ADDR, REG_ADDR); – Model

Since each element in an item bin may require different coverage goals or weights, additional overloading ofGenBin were added. These are shown below.

function GenBin(AtLeast, Weight, Min, Max, NumBin : integer ) return CovBinType ; function GenBin(AtLeast,Min, Max, NumBin : integer ) return CovBinType ;

As demonstrated earlier, item bins can be composed using concatenation. The following example creates twobins: 0 to 31 with coverage goal of 5, and 32 to 63 with coverage goal of 10.

constant A_BIN : CovBinType := GenBin(5, 0, 31, 1) & GenBin(10, 32, 63, 1) ;

Writing an Cross Coverage Model as a Constant - CovMatrix?Type To capture a cross coverage model in aconstant requires some additional types and functions. The following methodology is based the language prior toVHDL-2008 and requires a separate type definition for each size of cross coverage model. Currently up to a crossproduct of 9 separate items are supported by the following type. In VHDL-2008 where composites are allowedto have unconstrained elements, this will be reduced to a single type (and cross products of greater than 9 can beeasily supported).

type CovMatrix2Type is array (natural range <>) of CovMatrix2BaseType; type CovMatrix3Type is array (naturalrange <>) of CovMatrix3BaseType; type CovMatrix4Type is array (natural range <>) of CovMatrix4BaseType;type CovMatrix5Type is array (natural range <>) of CovMatrix5BaseType; type CovMatrix6Type is array (naturalrange <>) of CovMatrix6BaseType; type CovMatrix7Type is array (natural range <>) of CovMatrix7BaseType;type CovMatrix8Type is array (natural range <>) of CovMatrix8BaseType; type CovMatrix9Type is array (naturalrange <>) of CovMatrix9BaseType;

The function GenCross is used to generate these cross products. We need a separate overloaded function for eachof these types. The interface that generates CovMatrix2Type and CovMatrix9Type are shown below.

function GenCross( – cross 2 item bins - see method AddCross constant AtLeast : integer ; constant Weight :integer ; constant Bin1, Bin2 : in CovBinType ) return CovMatrix2Type ; function GenCross(AtLeast : integer ;Bin1, Bin2 : CovBinType) return CovMatrix2Type ; function GenCross(Bin1, Bin2 : CovBinType) return Cov-Matrix2Type ; function GenCross( – cross 9 item bins - intended only for constants constant AtLeast : integer; constant Weight : integer ; constant Bin1, Bin2, Bin3, Bin4, Bin5, Bin6, Bin7, Bin8, Bin9 : in CovBinType )return CovMatrix9Type ; function GenCross( AtLeast : integer ; Bin1, Bin2, Bin3, Bin4, Bin5, Bin6, Bin7, Bin8,Bin9 : CovBinType ) return CovMatrix9Type ; function GenCross( Bin1, Bin2, Bin3, Bin4, Bin5, Bin6, Bin7,Bin8, Bin9 : CovBinType ) return CovMatrix9Type ;

Now we can write our constant for our simple ALU coverage model.

constant ALU_COV_MODEL : CovMatrix2Type := GenCross(REG_ADDR, REG_ADDR);

22 Chapter 1. News


When we want to add this to our coverage data structure, we need methods that handle types CovMatrix2Typethrough CovMatrix9Type. This is handled by the overloaded versions of AddCross shown below.

procedure AddCross (CovBin : CovMatrix2Type) ; procedure AddCross (CovBin : CovMatrix3Type) ;

procedure AddCross (CovBin : CovMatrix4Type) ; procedure AddCross (CovBin : CovMatrix5Type) ; procedureAddCross (CovBin : CovMatrix6Type) ; procedure AddCross (CovBin : CovMatrix7Type) ; procedure AddCross(CovBin : CovMatrix8Type) ; procedure AddCross (CovBin : CovMatrix9Type) ;

To create the coverage data structure for the simple ALU coverage model, call AddCross as shown below.

ACov.AddCross ( ALU_COV_MODEL ); – Model

This capability is here mostly due to evolution of the package. Keep in mind, the intent is to create readable andperhaps reusable coverage models.

GenCross also allows specification of weights. In a similar manner to AddCross, we can build up our coveragemodel incrementally using constants and concatenation. This is shown in the following example.

architecture Test4 of tb is shared variable ACov : CovPType ; – Declare Cov Object constant ALU_BIN_CONST: CovMatrix2Type := GenCross(1, GenBin (0), GenBin(1,7)) & GenCross(2, GenBin (1), GenBin(0) & Gen-Bin(2,7)) & GenCross(3, GenBin (2), GenBin(0,1) & GenBin(3,7)) & GenCross(4, GenBin (3), GenBin(0,2) &GenBin(4,7)) & GenCross(5, GenBin (4), GenBin(0,3) & GenBin(5,7)) & GenCross(6, GenBin (5), GenBin(0,4)& GenBin(6,7)) & GenCross(7, GenBin (6), GenBin(0,5) & GenBin(7)) & GenCross(8, GenBin (7), GenBin(0,6)) ; begin TestProc : process variable RegIn1, RegIn2 : integer ; begin – Capture coverage model ACov. AddCross( ALU_BIN_CONST ) ; while not ACov.IsCovered loop – Interact – Randomize register addresses – see Ran-domPkg documentation (RegIn1, RegIn2) := ACov.RandCovPoint ; DoAluOp(TRec, RegIn1, RegIn2) ; – Do atransaction ACov.ICover( (RegIn1, RegIn2) ) ; – Accumulate end loop ; ACov.WriteBin ; – Report EndStatus(. .. ) ; end process ;

Reuse of Coverage

There are a couple of ways to reuse a coverage model. If the intent is to reuse and accumulate coverage acrosstests, then the only way to accomplish this is to use WriteCovDb and ReadCovDb. If the intent is to just reusethe coverage model itself, then either a constant or a subprogram can be used. The calls to ICover generally aresimple enough that we do not try to abstract them.

CoveragePkg vs. Language Syntax

The basic level of item (point) coverage that can be captured with CoveragePkg is similar to when can be capturedwith IEEE 1647, ‘e’. CoveragePkg and ‘e’ allow an item bin to consist of either a single value or a single range.SystemVerilog extends this to allow a value, a range, or a collection of values and ranges. While this additionalcapability of SystemVerilog is interesting, it did not seem to offer any compelling advantage that would justify theadditional complexity required to specify it to the coverage model.

For cross coverage, both SystemVerilog and ‘e’ focus on first capturing item coverage and then doing a cross ofthe items. There is some capability to modify the bins contents within the cross, but at best it is awkward. On theother hand, CoveragePkg allows one to directly capture cross coverage, bin by bin and incrementally if necessary.Helper functions are provided to simplify the process. This means for simple things, such as making sure everyregister pair of an ALU is used, the coverage is captured in a very concise syntax, however, when more complexthings need to be done, such as modeling the coverage for a CPU, the cross coverage can be captured on a line byline basis.

As a result, with CoveragePkg it is easier to capture high fidelity coverage within a single coverage object. A highfidelity coverage model in a single coverage object is required to do Intelligent Coverage.

Deprecated Methods

In the original design of the coverage feedback and randomization functions, there was no coverage goal or weight.Instead, each bin has a weight of 1 and the coverage goal is determined by the AtLeast parameter in the function

1.1. xx.01.2016 - 2016.01 was release. 23


calls. These functions are shown below. In this implementation, all bins had the same coverage goal. Usage ofthe AtLeast parameter has been subsumed by the real valued PercentCov parameter. In addition, each bin nowhas the capability to have a different coverage goal and weight. With different coverage goal values, PercentCovhas replaced the AtLeast parameter. The functionality of the AtLeast parameter has been subsumed by has beensubsumed by the PercentCov parameter. A PercentCov parameter of 200.0 is equivalent to an AtLeast parameterof 2.

impure function GetMinCov return integer ; impure function GetMaxCov return integer ; impure function Count-CovHoles ( AtLeast : integer ) return integer ; impure function IsCovered ( AtLeast : integer ) return boolean; impure function GetHoleBinVal ( ReqHoleNum : integer := 1 ; AtLeast : integer ) return RangeArrayType ;impure function RandCovBinVal ( AtLeast : in integer ) return RangeArrayType ; impure function RandCov-Point (AtLeast : in integer ) return integer_vector ; procedure WriteCovHoles ( AtLeast : in integer ) ; procedureWriteCovHoles ( FileName : string; AtLeast : in integer ; OpenKind : File_Open_Kind := APPEND_MODE ) ;

Future Work

CoveragePkg.vhd is a work in progress and will be updated from time to time.

Some of the plans for the next revision are:

• Revise bin merging. It is still an experimental feature and is off by

default. * Remove OrderCount (was for development purposes only).

If you have ideas that you would like to see, please contact me at [email protected].

Other Packages - RandomPkg

CoveragePkg is part of the Open Source VHDL Verification Methodology (OSVVM) packages. In addition to theCoveragePkg, our randomization packages (RandomPkg, RandomBasePkg, SortListPkg_int) are in OSVVM. Themost current versions are always available at http://www.SynthWorks.com/downloads. Over time we will also bereleasing other packages. With time, we hope simulation vendors will distribute the OSVVM libraries with theirtools.

About CoveragePkg

CoveragePkg was developed and is maintained by Jim Lewis of SynthWorks VHDL Training. It evolvedfrom methodology and packages developed for SynthWorks’ VHDL Testbenches and verification class. Itis part of the Open Source VHDL Verification Methodology (OSVVM), which brings leading edge verifica-tion techniques to the VHDL community. Please support our effort in supporting CoveragePkg and OSVVMby purchasing your VHDL training from SynthWorks. CoveragePkg is released under the Perl Artistic opensource license. It is free (both to download and use - there are no license fees). You can download it fromhttp://www.synthworks.com/downloads. It will be updated from time to time. Currently there are numerousplanned revisions. If you add features to the package, please donate them back under the same license as can-didates to be added to the standard version of the package. If you need features, be sure to contact us. I blogabout the packages at http://www.synthworks.com/blog. We also support a user community and blogs throughhttp://www.osvvm.org. Release notes are in the document OSVVM_release_notes.pdf.

References

SynthWorks’ class. .. [#2]: Andrew Piziali, Functional Verification Coverage Measurement and Analysis, KluwerAcademic Publishers 2004, ISBN 1-4020-8025-5 .. [#3]: IEEE Standard for System Verilog, 2005, IEEE, ISBN0-7381-4811-3 .. [#4]: IEEE 1647, Standard for the Functional Verification Language ‘e’, 2006 .. [#5]: A Fitch,D Smith, “Functional Coverage - without SystemVerilog!”, DVCON 2010

24 Chapter 1. News

mailto:[email protected]

http://www.SynthWorks.com/downloads





Randomization Package

Overview

RandomPkg provides a set of utilities for randomizing a value in a range, a value in a set, or a value with aweighted distribution.

OSVVM’s constrained random capability uses these utilities to randomize a value, operation, or sequence that isvalid in a particular test environment. Since any constrained random methodology creates a significant amount ofredundant stimulus (5X or more for small problems), in OSVVM, we use Intelligent Coverage randomization asour main randomization methodology, and constrained random as a refinement methodology in our tests.

These packages are updated from time to time and are freely available at http://www.synthworks.com/downloads.

Randomization Using IEEE.math_real.uniform = Yuck!

A basic form of randomization can be accomplished by using the procedure uniform the IEEE math_real package.However, this always results in randomization being a multi-step process: call uniform to randomize a value, scalethe value, and then use the value.

RandomGenProc : process variable RandomVal : real ; – Random value variable DataSent : integer ; variableseed1 : positive :=7 ; – initialize seeds variable seed2 : positive := 1 ; begin for i in 0 to 255*6 loop uniform(seed1,seed2, RandomVal) ; – randomize 0.0 to 1.0 DataSent := integer(trunc(RandomVal*256.0)) ; – scale to 0 to 255do_transaction(. . . , DataSent, . . . ) ; . . .

Optimally we would like to be able to call a function to do this so we can do this all in one step. Unfortunately wecannot write a normal VHDL function since we need to read and update the seed as well as return a randomizedvalue.

Simplifying Randomization

RandomPkg uses a protected type, named RandomPType, to encapsulate the seed. Within a protected type, impurefunctions can read and update the seed as well as return a randomized value. To randomize values using theprotected type, declare a variable of type RandomPType, initialze the seed, and randomize values.

RandomGenProc : process variable RV : RandomPType ; – protected type from RandomPkg

begin RV.InitSeed (RV’instance_name) ; – Generate initial seeds for i in 0 to 255*6 loop do_transaction(. . . ,RV.RandInt(0, 255), . . . ) ; – random value between 0 and 255

Note the calls to protected type methods (subprograms) include the protected type variable (RV) within the call(such as RV.RandInt(0, 255)).

Manipulating the Seeds

With protected types internal objects are private and accessible only through methods. The internal representationof the seed has a valid initial value, however, to ensure that each process’ randomization is independent of eachother, it is important to give each seed to a different initial value. As a result for a test that uses more than onerandomization variable, initialize each seed once - if there is only one randomization variable, there is no need toinitialize the seed.

The method InitSeed converts its argument value to RandomSeedType (the internal representation of the seed)and stores the value within the protected type. InitSeed is overloaded to accept either string or integer values. Thepreferred way to give each seed a unique value is pass the string value, RV’instance_name.

RV.InitSeed (RV’instance_name) ;

The methods GetSeed and SetSeed are used to read and restore a seed value. The declarations for these are shownbelow.

1.1. xx.01.2016 - 2016.01 was release. 25



impure function GetSeed return RandomSeedType ; procedure SetSeed (RandomSeedIn : RandomSeedType ) ;

The function to_string and procedures write and read are used to write and read values of type RandomSeedType.The declarations for these subprograms are shown below. Note these are in RandomBasePkg.vhd and are separatefrom the protected type.

function to_string(A : RandomSeedType) return string ; procedure write(L: inout line ; A : RandomSeedType ) ;procedure read (L: inout line ; A : out RandomSeedType ; good : out boolean ) ; procedure read (L: inout line ; A: out RandomSeedType ) ;

For a long test, it may be advantageous to read the seed periodically and print it out. If a failure or other interestingcondition is generated, the seed may be restored to a value that was recorded near the failure with the intent ofgenerating the error quickly to assist with debug.

Basic Randomization

The basic randomization generates an integer value that is either within some range or within a set of values.The set of values and exclude values are all of type integer_vector (defined in VHDL-2008). The examples belowshow the basic randomization overloading. When a value of integer_vector is specifed, the extra set of parenthesesdenote that it is an aggregate value.

RandomGenProc : process variable RV : RandomPType ; – protected type from RandomPkg variable DataInt :integer ; begin RV.InitSeed (RV’instance_name) ; – Generate initial seeds – Generate a value in range 0 to 255DataInt := RV.RandInt(0, 255) ; . . . – Generate a value in range 1 to 9 except exclude values 2,4,6,8 DataInt:= RV.RandInt(1, 9, (2,4,6,8)) ; . . . – Generate a value in set 1,3,5,7,9 DataInt := RV.RandInt( (1,3,7,9) ) ; –note two sets of parens required . . . – Generate a value in set 1,3,5,7,9 except exclude values 3,7 DataInt :=RV.RandInt((1,3,7,9), (3,7) ) ;

The overloading for the RandInt functions is as follows.

impure function RandInt (Min, Max : integer) return integer ; impure function RandInt (Min, Max: integer;Exclude: integer_vector) return integer ; impure function RandInt ( A : integer_vector ) return integer ; impurefunction RandInt ( A : integer_vector; Exclude: integer_vector) return integer ;

These same functions are available for types std_logic_vector(RandSlv), unsigned (RandUnsigned) and signed(RandSigned). Note that parameter values are still specified as integers and there is an additional value used tospecify the size of the value to generate. For example, the following call to RandSlv defines the array size to be 8bits.

variable DataSlv : std_logic_vector(7 downto 0) ; begin . . . DataSlv := RV.RandSlv(0, 255, 8) ; – Generate avalue in range 0 to 255

The overloading for RandSlv is as shown below. RandUnsigned and RandSigned have the same overloading

impure function RandSlv (Min, Max, Size : natural) return std_logic_vector ; impure function RandSlv (Min,Max : natural ; Exclude: integer_vector ; Size : natural) return std_logic_vector ; impure function RandSlv (A:integer_vector ; size : natural ) return std_logic_vector ;

impure function RandSlv (A: integer_vector ; Exclude: integer_vector ; Size : natural) return std_logic_vector ;

The function, RandReal supports randomization for type real. The function with a range, like the procedureUniform, never generates its end values. RandReal has the following overloading:

impure function RandReal ( Min, Max : real ) return real ; impure function RandReal ( A : real_vector ) returnreal ; impure function RandReal ( A, Exclude : real_vector ) return real ;

The function, RandTime supports randomization for type time. RandTime supports the same overloading asRandInt. These are shown below:

impure function RandTime (Min, Max : time ; Unit : time := ns) return time ; impure function RandTime (Min,Max : time ; Exclude : time_vector ; Unit : time := ns) return time ; impure function RandTime (A : time_vector)return time ; impure function RandTime (A, Exclude : time_vector) return time ;

26 Chapter 1. News


Large Vector Randomization

Integer randomization is only valid in the range of -2**31 to +2**31 - 1. Large vector randomization uses mul-tiple randomizations to create a value. The following overloading is available for RandUnsigned, RandSlv, andRandSigned.

impure function RandUnsigned (Size : natural) return unsigned ; impure function RandUnsigned (Max : unsigned)return unsigned ; impure function RandUnsigned (Min, Max : unsigned) return unsigned ;

The size parameter specifies the number of bits in the vector. The Max parameter allows randomization between0 and Max. The Min and Max parameters allow randomizing a range of values.

Randomizing Sets of Values

A set of values can be represented by integer_vector, real_vector, or time_vector. The following illustrates thecapability supported for integer_vector.

RandomGenProc : process variable RV : RandomPType ; – protected type from RandomPkg variable IntV :integer_vector(1 to 15) ; begin RV.InitSeed (RV’instance_name) ; – Generate initial seeds – Generate 10 integervalues in the range 0 to 255 IntV(1 to 10) := RV.RandIntV(0, 255, 10) ; . . . – Generate 15 integer values in range1 to 9 except exclude values 2,4,6,8 IntV := RV.RandIntV(1, 9, (2,4,6,8), 15) ; . . . – Generate 5 integer valuesvalue in set 1,3,5,7,9 IntV(1 to 5) := RV.RandIntV( (1,3,7,9), 5 ) ;

. . . – Generate 15 integer values in set 1,3,5,7,9 except exclude values 3,7 IntV := RV.RandIntV((1,3,7,9), (3,7),15) ; – Generate 10 integer values in the range 0 to 255, do repeat the last value IntV(1 to 10) := RV.RandIntV(0,255, 1, 10) ; . . . – Generate 15 integer values in range 1 to 9 except exclude values 2,4,6,8 – Do not repeat thelast 3 values IntV:= RV.RandIntV(1, 9, (2,4,6,8), 3, 15) ; . . . – Generate 5 integer values in the set 1,3,5,7,9, donot repeat the last value IntV(1 to 5) := RV.RandIntV( (1,3,7,9), 1, 5 ) ; . . . – Generate 15 integer values in set1,3,5,7,9 except exclude values 3,7 – Do not repeat last value IntV := RV.RandIntV((1,3,7,9), (3,7), 1, 15) ;

The overloading for integer_vector, real_vector, or time_vector are as follows.

– Range and Exclude impure function RandIntV (Min, Max : integer ; Size : natural) return integer_vector ;impure function RandIntV (Min, Max : integer ; Exclude : integer_vector ; Size : natural) return integer_vector ;– Range, Exclude, and Unique impure function RandIntV (Min, Max : integer ; Unique : natural ; Size : natural)return integer_vector ; impure function RandIntV (Min, Max : integer ; Exclude : integer_vector ; Unique : natural; Size : natural) return integer_vector ; – Set and Exclude impure function RandIntV (A : integer_vector ; Size: natural) return integer_vector ; impure function RandIntV (A, Exclude : integer_vector ; Size : natural) returninteger_vector ; – Range, Exclude, and Unique impure function RandIntV (A : integer_vector ; Unique : natural ;Size : natural) return integer_vector ; impure function RandIntV (A, Exclude : integer_vector ; Unique : natural ;Size : natural) return integer_vector ;

Overloading for time_vector:

impure function RandTimeV (Min, Max : time; Size : natural; Unit : time := ns) return time_vector; impurefunction RandTimeV (Min, Max : time ; Exclude : time_vector ; Size : natural) return time_vector ; impurefunction RandTimeV (Min, Max : time; Unique : natural; Size : natural; Unit : time := ns) return time_vector; impure function RandTimeV (Min, Max : time; Exclude : time_vector; Unique : natural; Size : natural)return time_vector; impure function RandTimeV (A : time_vector; Size : natural) return time_vector ; impurefunction RandTimeV (A : time_vector; Unique : natural ; Size : natural) return time_vector; impure functionRandTimeV (A, Exclude : time_vector; Size : natural) return time_vector ; impure function RandTimeV (A,Exclude : time_vector; Unique : natural; Size : natural) return time_vector ;

Overloading real_vector

impure function RandRealV (Min, Max : real ; Size : natural) return real_vector ; impure function RandRealV (A: real_vector ; Size : natural) return real_vector ; impure function RandRealV (A : real_vector ; Unique : natural; Size : natural) return real_vector ; impure function RandRealV (A, Exclude : real_vector ; Size : natural) returnreal_vector ; impure function RandRealV (A, Exclude : real_vector ; Unique : natural ; Size : natural) returnreal_vector ;

1.1. xx.01.2016 - 2016.01 was release. 27


Weighted Randomization

A weighted distribution randomly generates each of set of values a specified percentage of the time. RandomPTypeprovides a weighted distribution that specifies a value and its weight (DistValInt) and one that only specifiesweights (DistInt).

DistValInt is called with an array of value pairs. The first item in the pair is the value and the second is theweight. The frequency that each value will occur is weight/(sum of weights). As a result, in the following call toDistValInt, the likelihood of a 1 to occur is 7/10 times or 70%. The likelihood of 3 is 20% and 5 is 10%.

variable RV : RandomPType ; . . . DataInt := RV.DistValInt( ((1, 7), (3, 2), (5, 1)) ) ; DistInt is a simplified versionof DistValInt. The input to DistInt is an integer_vector of weights. The return value is the index of the selectedweight. For a literal value, it will return a value from 0 to N-1 where N is the number of weights specified.As a result, the following call to DistInt the likelihood of a 0 is 70%, 1 is 20% and 2 is 10%. variable RV :RandomPType ; . . . DataInt := RV.DistInt( ((7, 2, 1)) ;

Usage

Each randomization result is produced by a function and that result can be used directly in an expression. Hence,we can randomize a delay that is between 3 and 10 clocks.

wait for RV.RandInt(3, 10) * tperiod_Clk - tpd ; wait until Clk = ‘1’ ;

The values can also be used directly inside a case statement. The following example uses DistInt to generate thefirst case target 70% of the time, the second 20%, and the third 10%.

variable RV : RandomPType ; . . . StimGen : while TestActive loop – Repeat until done case RV.DistInt( (7, 2, 1)) is when 0 => – Normal Handling – 70% . . . when 1 => – Error Case 1 – 20% . . . when 2 => – Error Case 2 –10% . . . when others => report “DistInt” severity failure ; – Signal bug in DistInt end case ; end loop ;

The following code segment generates the transactions for writing to DMA_WORD_COUNT, DMA_ADDR_HI,and DMA_ADDR_LO in a random order that is different every time this code segment is run. The sequencefinishes with a write to DMA_CTRL. When DistInt is called with a weight of 0, the corresponding value does notget generated. Hence by initializing all of the weights to 1 and then setting it to 0 when it is selected, each casetarget only occurs once. The “for loop” loops three times to allow each transaction to be selected.

variable RV : RandomPType ; . . . Wt0 := 1; Wt1 := 1; Wt2 := 1; – Initial Weights for i in 1 to 3 loop –Loop 1x per transaction case RV.DistInt( (Wt0, Wt1, Wt2) ) is – Select transaction when 0 => – Transaction 0CpuWrite(CpuRec, DMA_WORD_COUNT, DmaWcIn); Wt0 := 0 ; – remove from randomization when 1 =>– Transaction 1 CpuWrite(CpuRec, DMA_ADDR_HI, DmaAddrHiIn); Wt1 := 0 ; – remove from randomiza-tion when 2 => – Transaction 2 CpuWrite(CpuRec, DMA_ADDR_LO, DmaAddrLoIn); Wt2 := 0 ; – removefrom randomization when others => report “DistInt” severity failure ; end case ; end loop ; CpuWrite(CpuRec,DMA_CTRL, START_DMA or DmaCycle);

The following code segment uses an exclude list to keep from repeating the last value. Note when passing aninteger value to an integer_vector parameter, an aggregate using named association “(0=> LastDataInt)” is usedto denote a single element array. Note that during the first execution of this process, LastDataInt has the valueinteger’left (a very small number), which is outside the range 0 to 255, and as a result, has no impact on therandomization.

RandomGenProc : process variable RV : RandomPType ; variable DataInt, LastDataInt : integer ; begin . . .DataInt := RV.RandInt(0, 255, (0 => LastDataInt)) ;

LastDataInt := DataInt; . . .

The following code segment uses an exclude list to keep from repeating the four previous values.

RandProc : process variable RV : RandomPtype ; variable DataInt : integer ; variable Prev4DataInt : inte-ger_vector(3 downto 0) := (others => integer’low) ; begin . . . DataInt := RV.RandInt(0, 100, Prev4DataInt) ;Prev4DataInt := Prev4DataInt(2 downto 0) & DataInt ; . . .

28 Chapter 1. News


Creating a Test

Creating tests is all about methodology. SynthWorks’ methodology marries randomization subprograms(from RandomPkg) and functional coverage subprograms (from CoveragePkg - also freely available athttp://www.synthworks.com/downloads) with VHDL programming constructs. Each test sequence is derived byrandomly selecting either branches of code or values for operations. Randomization constraints are created usingnormal sequential coding techniques (such as nesting of case, if, loop, and assignment statements). This approachis simple yet powerful. Since all of the code is sequential, randomized sequences are readily mixed with directedand algorithmic sequences.

A simple demonstration of randomizing is the following test which uses heuristics (guesses) at length of bursts ofdata and delays between bursts of data to randomization traffic being sent to a FIFO.

variable RV : RandomPType ; . . . TxStimGen : while TestActive loop – Burst between 1 and 10 val-ues BurstLen := RV.RandInt(Min => 1, Max => 10); for i in 1 to BurstLen loop DataSent := DataSent + 1 ;WriteToFifo(DataSent) ; end loop ; – Delay between bursts: (BurstLen <=3: 1-6, >3: 3-10) if BurstLen <= 3 thenBurstDelay := RV.RandInt(1, 6) ; – small burst, small delay else BurstDelay := RV.RandInt(3, 10) ; – bigger burst,bugger delay end if ; wait for BurstDelay * tperiod_Clk - tpd ; wait until Clk = ‘1’ ; end loop TxStimGen ;

Functional coverage counts which test cases have been generated and give engineers an indication of when testingis done. This is essential when using randomization to create a test as otherwise there is no way to know whatthe test actually did. Functional coverage can be implemented using subprogram calls (either custom or from theCoveragePkg) or VHDL code. Functional coverage is stored in signals and can be used to change the randomiza-tion (either directly as a constraint or indirectly as something that contributes to changing a constraint) to generatemissing coverage items.

With a FIFO, we need to see lots of write attempts while full and read attempts while empty. One thing we cando to improve the previous test is to increase or decrease the burst length and delay based on the number of writeattempts while full or read attempts while empty we have seen. To explore how to generate the coverage, see theCoveragePkg documentation.

For a design for which has numerous conditions we need to generate, we can do coverage on the input stimulusand then randomly select one of the uncovered conditions as the next transaction to be generated.

Solutions for the two previous coverage driven randomization problems are provided in SynthWorks’ VHDLTestbenches and Verification class.

Random Stability

A protected type is always used with a variable object. If the object is declared in a process, it is a regular variable.If the object is declared in an architecture, then it is declared as a shared variable.

All of the examples in this document show RandomPType being defined in a process as a regular variable. This isdone to ensure random stability. Random stability is the ability to re-run a test and get exactly the same sequence.Random stability is required for verification since if we find a failure and then fix it, if the same sequence is notgenerated, we will not know the fix actually worked.

Random stability is lost when a randomization variable is declared as a shared variable in an architecture andshared among multiple processes. When a randomization variable is shared, the seed is shared. Each randomiza-tion reads and updates the seed. If the processes accessing the shared variable run during the same delta cycle, thenthe randomization of the test depends on the order of which RandomPType is accessed. This order can changeanytime the design is optimized - which will happen after fixing bugs. As a result, the test is unstable.

To ensure stability, create a separate variable for randomization in each process.

Other Distributions

By default, all randomizations use a uniform distribution. In addition to uniform distributions, RandomPType alsoprovides distributions for FavorSmall, FavorBig, normal, and poisson. The following is the overloading for thesefunctions.

1.1. xx.01.2016 - 2016.01 was release. 29



– Generate values, each with an equal probability impure function Uniform (Min, Max : in real) return real ;impure function Uniform (Min, Max : integer) return integer ; impure function Uniform (Min, Max : integer ;Exclude: integer_vector) return integer ; – Generate more small numbers than big impure function FavorSmall(Min, Max : real) return real ; impure function FavorSmall (Min, Max : integer) return integer ; impure functionFavorSmall(Min, Max: integer; Exclude: integer_vector) return integer ; – Generate more big numbers than smallimpure function FavorBig (Min, Max : real) return real ; impure function FavorBig (Min, Max : integer) returninteger ; impure function FavorBig (Min, Max : integer ; Exclude: integer_vector) return integer ; – Generatenormal = gaussian distribution impure function Normal (Mean, StdDeviation : real) return real ; impure functionNormal (Mean, StdDeviation, Min, Max : real) return real ; impure function Normal ( Mean : real ; StdDeviation :real ; Min : integer ; Max : integer ; Exclude : integer_vector := NULL_INTV ) return integer ; – Generate poissondistribution impure function Poisson (Mean : real) return real ; impure function Poisson (Mean, Min, Max : real)return real ; impure function Poisson ( Mean : real ; Min : integer ; Max : integer ; Exclude : integer_vector :=NULL_INTV ) return integer ;

The package also provides experimental mechanisms for changing the distributions used with functions RandInt,RandSlv, RandUnsigned, and RandSigned.

Sorting integer_vector

The package SortListPkg_int provides a Sort and RevSort functions for sorting type integer_vector. The followingexample uses RandIntV and Sort to create a random set of 10 integer values between 0 and 255 that increase invalue and do not repeat.

IntV := Sort(RV.RandIntV(0, 255, 10, 10)) ;

The overloading for Sort and RevSort are as follows.

impure function Sort (A : integer_vector) return integer_vector; impure function RevSort (A : integer_vector)return integer_vector ;

Compiling RandomPkg and Friends

Turn on the VHDL-2008 compile switch. Compile the files, SortListPkg_int.vhd, RandomBasePkg.vhd, andRandomPkg.vhd. We typically put these into a named library such as SynthWorks or OSVVM.

To take the packages for a test run, compile the program, Demo_Rand.vhd, into the same library as the packagesand run it for 1 ns in your simulator.

Your programs need to reference RandomPkg. If your programs use IO for the seed (to_string, write, read), thenyou will also need to include RandomBasePkg.

library OSVVM ; use OSVVM.RandomPkg.all ;

About RandomPkg

RandomPkg was developed and is maintained by Jim Lewis of SynthWorks VHDL Training. It evolved frommethodology and packages developed for SynthWorks’ VHDL Testbenches and verification class. It is part of theOpen Source VHDL Verification Methodology (OSVVM), which brings leading edge verification techniques tothe VHDL community.

Please support our effort in supporting RandomPkg and OSVVM by purchasing your VHDL training from Syn-thWorks.

RandomPkg is released under the Perl Artistic open source license. It is free (both to download and use - there areno license fees). You can download it from http://www.synthworks.com/downloads. It will be updated from timeto time. Currently there are numerous planned revisions.

If you add features to the package, please donate them back under the same license as candidates to be addedto the standard version of the package. If you need features, be sure to contact us. I blog about the packages athttp://www.synthworks.com/blog. We also support a user community and blogs through http://www.osvvm.org.

30 Chapter 1. News





If you find any innovative usage for the package, let us know - we can set you up to

Future Work

RandomPkg.vhd is a work in progress and will be updated from time to time. Things not documented in thisdocument, such as type RandomParmType and method SetRandomParm, are experimental and may be removedin a future revision of the package (to reduce the overhead to basic randomization). Note that the current ver-sion of this package gives direct access to this capability via methods FavorSmall, FavorBig, normal, and pois-son. In addition to the RandomPkg, we also are freely distributing our coverage package, CoveragePkg. Seehttp://www.SynthWorks.com/downloads. Over time we will also be releasing other packages that we currentlydistribute with our classes (such as scoreboards and memory modeling) and hope to convince simulation vendorsto distribute our libraries with their tools.

AlertLog Package

Overview

VHDL assert statements are a limited form of an alert and log filtering utility. In the simulator GUI, you can setan assertion level that will stop a simulation. In the simulator GUI, you can turn off some assertions from printing.However, none of this capability can be configured in VHDL, and in addition, at the end of a test, there is no wayto retrieve a count of the ERROR level assertions that have occurred.

The AlertLogPkg provides Alert and Log procedures that replace VHDL assert statements and gives VHDLdirect access to enabling and disabling of features, retrieving alert counts, and set stop counts (limits). All of thesefeatures can be used in either a simple global mode or a hierarchy of alerts.

Alert simplifies signaling errors (when an error occurs) and reporting errors (passed or failed when a test finishes).Alerts have the levels FAILURE, ERROR, and WARNING. Each level is counted and tracked in an internal datastructure. Within the data structure, each of these can be enabled or disabled. A test can be stopped if an alertvalue has been signaled too many times. Stop values for each counter can be set. The default for FAILURE is 0and ERROR and WARNING are integer’right. If all test errors are reported as an alert, at the end of the test,a report can be generated which provides pass/fail and a count of the different alert values.

Logs provide a mechanism to conditionally print information. This verbosity control allows messages (such asdebug, DO254 final test reports, or info) that are too detailed for normal testing to be printed when specificallyenabled. VIA the simulator GUI, assert has this capability to a limited degree.

AssertLogPkg uses TranscriptPkg to print to either std.textio.OUTPUT, a file, or both.When the TranscriptFile is opened, alert and log print to the TranscriptFile, otherwise, they print tostd.textio.OUTPUT. For more details on TranscriptPkg see the TranscriptPkg User Guide.

Already using another package for alerts and verbosity control? The AlertLogPkg has an extensive API that willallow you to retrieve any error information reported by the OSVVM packages and allow you to print a summaryof results via another package.

AlertLogPkg Use Models

Alerts and Logs may be used in either a simple mode or a hierarchy model.

In simple mode, there is single global alert counter that accumulates the number of FAILURE, ERROR, andWARNING level alerts for the entire testbench. When a test completes, a summary of the total number of errorsas well as the errors for each level can be produced.

In hierarchy mode, there is a hierarchy of alert counters. Each model and/or source of alerts has its own set of alertcounters. Counts from lower levels propagate up to the top level counter. Each level in the hierarchy also supportsseparate verbosity control. When a test completes, an error report can be produced for both the top level and eachlevel in the alert hierarchy.

1.1. xx.01.2016 - 2016.01 was release. 31



Simple Mode: Global Alert Counter

By default, there is a single global alert counter. All designs that use alert or log need to reference the packageAlertLogPkg.

use osvvm.AlertLogPkg.all ;architecture Test1 of tb is

Use Alert to flag an error, AlertIf to flag an error when a condition is true, or AlertIfNot to flag an error when acondition is false (similar to assert). Alerts can be of severity FAILURE, ERROR, or WARNING.

-- message, levelWhen others => Alert("Illegal State", FAILURE) ;. . .-- condition, message, levelAlertIf(ActualData /= ExpectedData, "Data Miscompare ?", ERROR) ;. . .read(Buf, A, ReadValid) ;-- condition, message, levelAlertIfNot( ReadValid, "read of A failed", FAILURE) ;

The output for an alert is as follows. Alert adds the time at which the log occurred.

%% Alert ERROR Data Miscompare ? at 20160 ns

When a test completes, use ReportAlerts to provide a summary of errors.

ReportAlerts ;

When a test passes, the following message is generated:

%% DONE PASSED t1_basic at 120180 ns

When a test fails, the following message is generated (on a single line):

%% DONE FAILED t1_basic Total Error(s) = 2 Failures: 0 Errors: 1 Warnings:

1 at 120180 ns

Similar to assert, by default, when an alert FAILURE is signaled, a test failed message (see ReportAlerts) isproduced and the simulation is stopped. This action is controlled by a stop count. The following call to SetAlert-StopCount, causes a simulation to stop after 20 ERROR level alerts are received.

SetAlertStopCount(ERROR, 20) ;

Alerts can be enabled by a general enable, SetGlobalAlertEnable (disables all alert handling) or an enable for eachalert level, SetAlertEnable. The following call to SetAlertEnable disables WARNING level alerts.

SetGlobalAlertEnable(TRUE) ; -- DefaultSetAlertEnable(WARNING, FALSE) ;

Logs are used for verbosity control. Log level values are ALWAYS, DEBUG, FINAL, and INFO.

Log ("A message", DEBUG) ;

Log formats the output as follows.

%% Log DEBUG A Message at 15110 ns

Each log level is independently enabled or disabled. This allows the testbench to support debug or final reportmessages and only enable them during the appropriate simulation run. The log ALWAYS is always enabled, allother logs are disabled by default. The following call to SetLogEnable enables DEBUG level logs.

SetLogEnable(DEBUG, TRUE) ;

32 Chapter 1. News


Hierarchy Mode: Separate Alert Counters

In hierarchy mode, each model and/or source of alerts has its own set of alert counters. Counts from lower levelspropagate up to the top level counter. The ultimate goal of using hierarchy mode is to get a summary of errors foreach model and/or source of alerts in the testbench:

%% DONE FAILED Testbench Total Error(s) = 21 Failures: 1 Errors: 20

Warnings: 0 at 10117000 ns %% Default Failures: 0 Errors: 4 Warnings: 0 %% OSVVM Failures: 0 Errors:0 Warnings: 0 %% U_CpuModel Failures: 0 Errors: 4 Warnings: 0 %% Data Error Failures: 0 Errors: 2Warnings: 0 %% Protocol Error Failures: 1 Errors: 2 Warnings: 0 %% U_UART_TX Failures: 0 Errors: 6Warnings: 0 %% U_UART_RX Failures: 0 Errors: 6 Warnings: 0

Using hierarchy mode requires a little more work. Behind the scenes within AlertLogPkg, there is a data structureinside shared variable. Each level in a hierarchy is referenced with an AlertLogID - which is currently an integerindex into the data structure. As a result, each model must get (allocate) an AlertLogID and then referencethe AlertLogID when signaling alerts. Other than referencing the AlertLogID, the usage is identical. A newAlertLogID is created by calling the function GetAlertLogID. GetAlertLogID has two parameters: Name andParentID. Name is a string of the ALERT (that prints when the alert prints). ParentID is of type AlertLogIDType.

In the following example, CPU_ALERT_ID uses the instance name of the model as its name. Since it is a toplevel model, it uses ALERTLOG_BASE_ID (which is also the default) as its ParentID. DATA_ALERT_ID is analert counter within the CPU. So it uses a string as its name and CPU_ALERT_ID as its ParentID.

constant CPU_ALERT_ID : AlertLogIDType :=-- Name (string value), Parent AlertLogIDGetAlertLogID(PathTail(CpuModel'PATH_NAME), ALERTLOG_ BASE_ID) ;constant DATA_ALERT_ID : AlertLogIDType :=GetAlertLogID("Data Error", CPU_ALERT_ID) ;constant PROTOCOL_ALERT_ID : AlertLogIDType :=GetAlertLogID("PROTOCOL Error", CPU_ALERT_ID) ;

The AlertLogID is specified first in calls to Alert, Log, SetAlertEnable, SetAlertStopCount, and SetLogEnable.

Alert(CPU_ALERT_ID, "CPU Error", ERROR) ;AlertIf(PROTOCOL_ALERT_ID, inRdy /= '0', "during CPU Read operation",

FAILURE); AlertIfNotEqual(DATA_ALERT_ID, ReadData, ExpectedData, “Actual /= Expected

Data”); – AlertLogID, Level, Enable SetAlertEnable(CPU_ALERT_ID, WARNING, FALSE) ; – AlertLogID,Level, Count SetAlertStopCount(CPU_ALERT_ID, ERROR, 20) ; Log(UartID, DEBUG, “Uart Parity Re-ceived”) ; – AlertLogID, Level, Enable, DescendHierarchy SetLogEnable(UartID, WARNING, FALSE,FALSE) ;

Printing of Alerts and Logs include the AlertLogID.

%% Alert FAILURE in CPU_1, Expect data XA5A5 at 2100 ns

%% Log ALWAYS in UART_1, Parity Error at 2100 ns

Package References

Using AlertLogPkg requires the following package references:

library osvvm ;use osvvm.OsvvmGlobalPkg.all ;use osvvm.AlertLogPkg.all ;

Alert Method Reference

AlertType Alert levels can be FAILURE, ERROR, or WARNING.

1.1. xx.01.2016 - 2016.01 was release. 33


type AlertType is (FAILURE, ERROR, WARNING) ;

Simple Alerts Simple alerts accumulate alerts in the default AlertLogID (ALERTLOG_DEFAULT_ID). It sup-ports the basic overloading and usage:

procedure Alert( Message : string ; Level : AlertType := ERROR ) ;. . .Alert("Uart Parity") ; -- ERROR by default

Alert has two conditional forms, AlertIf and AlertIfNot. The following is their overloading.

-- without an AlertLogIDprocedure AlertIf( condition : boolean ;Message : string ; Level : AlertType := ERROR ) ;impure function AlertIf( condition : boolean ;Message : string ; Level : AlertType := ERROR ) return boolean ;procedure AlertIfNot( condition : boolean ;Message : string ; Level : AlertType := ERROR ) ;impure function AlertIfNot( condition : boolean ;Message : string ; Level : AlertType := ERROR ) return boolean ;

Usage of conditional alerts:

AlertIf(Break='1', "Uart Break", ERROR) ;AlertIfNot(ReadValid, "Read Failed", FAILURE) ;

The function form is convenient for use for conditional exit of a loop.

exit AlertIfNot(ReadValid, “in ReadCovDb while reading ?”, FAILURE) ;

Alert form AlertIfEqual and AlertIfNotEqual to check two values. In the following, AType can be std_logic,std_logic_vector, unsigned, signed, integer, real, character, or string.

procedure AlertIfEqual( L, R : AType ; Message : string ; Level : AlertType := ERROR ) ; Message : string ;procedure AlertIfNotEqual( L, R : AType; Level : AlertType := ERROR ) ; Alert form AlertIfDiff is for comparingtwo files. procedure AlertIfDiff (Name1, Name2 : string; Message : string := “” ; Level : AlertType := ERROR ); procedure AlertIfDiff (file File1, File2 : text; Message : string := “” ; Level : AlertType := ERROR ) ;

Creating Hierarchy: GetAlertLogID Each level in a hierarchy is referenced with an AlertLogID. The func-tion, GetAlertLogID, creates a new AlertLogID. If an AlertLogID already exists for the specified name, GetAlert-LogID will return its AlertLogID. It is recommended to use the instance label as the Name. The interface forGetAlertLogID is as follows. impure function GetAlertLogID( Name : string ; ParentID : AlertLogIDType :=ALERTLOG_BASE_ID ; CreateHierarchy : Boolean := TRUE ) return AlertLogIDType ; The CreateHierarchyparameter is intended to allow packages to use a unique AlertLogID for reporting Alerts without creating hierarchyin ReportAlerts. As a function, GetAlertLogID can be called while elaborating the design by using it to initialize aconstant or signal: Constant UartID : AlertLogIDType := – Name, Parent AlertLogID GetAlertLogID(“UART_1”,ALERTLOG_BASE_ID);

FindAlertLogID: Find an AlertLogID The function, FindAlertLogID, finds an existing AlertLogID. If theAlertLogID is not found, ALERTLOG_ID_NOT_FOUND is returned. The interface for FindAlertLogID is asfollows. impure function FindAlertLogID(Name : string ; ParentID : AlertLogIDType) return AlertLogIDType ;impure function FindAlertLogID(Name : string ) return AlertLogIDType ; Note the single parameter FindAlert-LogID is only useful when there is only one AlertLogID with a particular name (such as for top-level instancenames). As a function, FindAlertLogID can be called while elaborating the design by using it to initialize a con-stant or signal. constant UartID : AlertLogIDType := FindAlertLogID(Name => “UART_1”) ; Caution: only useFindAlertLogID when it is known that the ID has already been created - such as in a testbench where the testbenchcomponents have already been elaborated, as otherwise, it is appropriate to use GetAlertLogID.

34 Chapter 1. News


PathTail - Used to Discover Instance Name of a Component When used in conjunction with at-tribute PATH_NAME applied to an entity name, PathTail returns the instance name of component.constant CPU_ALERT_ID : AlertLogIDType := – Name (string value), Parent AlertLogID GetAlert-LogID(PathTail(CpuModel’PATH_NAME), ALERTLOG_ BASE_ID) ;

Hierarchical Alerts Hierarchical alerts require the AlertLogID to be specified in the call to alert. It supportsthe basic overloading and usage: procedure alert( AlertLogID : AlertLogIDType ; Message : string ; Level :AlertType := ERROR ) ; . . . Alert(UartID, “Uart Parity”, ERROR) ; When an alert is signaled in a lowerlevel of the hierarchy, it increments all parent levels until it finds a level whose alert for that level is disabledor the top of the hierarchy. Alert has two conditional forms, AlertIf and AlertIfNot. The following is theiroverloading. The function form is convenient for use for conditional exit of a loop. procedure AlertIf( AlertLogID: AlertLogIDType ; condition : boolean ; Message : string ; Level : AlertType := ERROR ) ; impure functionAlertIf( AlertLogID : AlertLogIDType ; condition : boolean ; Message : string ; Level : AlertType := ERROR )return boolean ; procedure AlertIfNot( AlertLogID : AlertLogIDType ; condition : boolean ; Message : string ;Level : AlertType := ERROR ) ; impure function AlertIfNot( AlertLogID : AlertLogIDType ; condition : boolean ;Message : string ; Level : AlertType := ERROR ) return boolean ; Usage of conditional alerts: AlertIf(Break=‘1’,UartID, “Uart Break”, ERROR) ; AlertIfNot(ReadValid, UartID, “Read”, FAILURE); Alert form AlertIfEqualand AlertIfNotEqual to check two values. In the following, AType can be std_logic, std_logic_vector, unsigned,signed, integer, real, character, or string. procedure AlertIfEqual( AlertLogID : AlertLogIDType ; L, R : AType;Message : string ; Level : AlertType := ERROR ) ; procedure AlertIfNotEqual( AlertLogID : AlertLogIDType ;L, R : AType; Message : string ; Level : AlertType := ERROR ) ; Alert form AlertIfDiff is for comparing two files.procedure AlertIfDiff (AlertLogID : AlertLogIDType ; Name1, Name2 : string; Message : string := “” ; Level :AlertType := ERROR ) ; procedure AlertIfDiff (AlertLogID : AlertLogIDType ; file File1, File2 : text; Message :string := “” ; Level : AlertType := ERROR ) ;

IncrementAlertCount Intended as a silent alert. Used by CoveragePkg. – Hierarchy procedure IncAlertCount(– A silent form of alert AlertLogID : AlertLogIDType ;

Level : AlertType := ERROR ) ; – Global Alert Counters procedure IncAlertCount( Level : AlertType := ERROR) ;

ReportAlerts: Reporting Alerts At test completion alerts are reported with ReportAlerts. procedure Repor-tAlerts ( Name : string := “” ; AlertLogID : AlertLogIDType := ALERTLOG_BASE_ID ; ExternalErrors : Alert-CountType := (others => 0) ) ; . . . ReportAlerts ; ReportAlerts has 3 optional parameters: Name, AlertLogID, andExternalErrors. Name specifies the test name (and can also be set with SetAlertLogName). AlertLogID allowsreporting alerts for a specific AlertLogID and its children (if any). ExternalErrors allows separately detected errorsto be reported. ExternalErrors is type AlertCountType and the value (FAILURE => 0, ERROR => 5, WARNING=> 1) indicates detection logic separate from AlertLogPkg saw 0 Failures, 5 Errors, and 1 Warning. See notesunder AlertCountType. – Name, AlertLogID, ExternalErrors ReportAlerts(“Uart1”, UartID, (FAILURE => 0, ER-ROR => 5, WARNING => 1) ) ; ReportAlerts can also be used to print a passed/failed message for an AlertCountthat is passed into the procedure call. procedure ReportAlerts ( Name : String ; AlertCount : AlertCountType); This is useful to accumulate values returned by different phases of a test that need to be reported separately.ReportAlerts(“Test1: Final”, Phase1AlertCount + Phase2AlertCount) ; Also see SetAlertLogOptions.

ReportNonZeroAlerts Within the hierarchy, if a level has no alerts set, then that level will not be printed.procedure ReportNonZeroAlerts ( Name : string := OSVVM_STRING_INIT_PARM_DETECT ; AlertLogID :AlertLogIDType := ALERTLOG_BASE_ID ; ExternalErrors : AlertCountType := (others => 0) ) ;

SetAlertLogName: Setting the Test Name SetAlertLogName sets the name ReportAlerts prints when calledwithout parameters - such as when an internal stop count reached.

procedure SetAlertLogName(Name : string ) ; . . . SetAlertLogName(“Uart1”) ;

1.1. xx.01.2016 - 2016.01 was release. 35


GetAlertLogName GetAlertLogName returns the string value of name associated with an AlertLogID. Ifno AlertLogID is specified, it will return the name set bySetAlertLogName. impure function GetAlertLog-Name(AlertLogID : AlertLogIDType:= ALERTLOG_BASE_ID) return string ;

SetGlobalAlertEnable: Alert Global Enable / Disable SetGlobalAlertEnable allows Alerts to be globally en-abled and disabled. The intent is to be able to disable all alerts until the system goes into reset. Alerts are enabledby default. procedure SetGlobalAlertEnable (A : EnableType := TRUE) ; impure function SetGlobalAlertEn-able (A : EnableType := TRUE) return EnableType ; Suppress all alerts before reset by turning alerts off duringelaboration with a constant declaration and then turning them back on later. InitAlerts : Process constant Dis-ableAlerts : boolean := SetGlobalAlertEnable(FALSE); begin wait until nReset = ‘1’ ; – Deassertion of resetSetGlobalAlertEnable(TRUE) ; – enable alerts

GetGlobalAlertEnable Get the current value of the global alert enable impure function GetGlobalAlertEnablereturn boolean ;

SetAlertEnable: Alert Enable / Disable SetAlertEnable allows alert levels to be individually enabled. Whenused without AlertLogID, SetAlertEnable sets a value for all AlertLogIDs. procedure SetAlertEnable(Level :AlertType ; Enable : boolean) ; . . . – Level, Enable SetAlertEnable(WARNING, FALSE) ; When an AlertLogIDis used, SetAlertEnable sets a value for that AlertLogID, and if DescendHierarchy is TRUE, it?s the AlertLogID’sof its children. procedure SetAlertEnable(AlertLogID : AlertLogIDType ; Level : AlertType ; Enable : boolean ;DescendHierarchy : boolean := TRUE) ;

GetAlertEnable Get the value of the current alert enable for either a specific AlertLogId or for the global alertcounter. – Hierarchy impure function GetAlertEnable(AlertLogID : AlertLogIDType ; Level : AlertType) returnboolean ; – Global Alert Counter impure function GetAlertEnable(Level : AlertType) return boolean ;

SetAlertStopCount: Alert Stop Counts When an alert stop count is reached, the simulation stops. When usedwithout AlertLogID, SetAlertStopCount sets the alert stop count for the top level to the specified value if thecurrent count is integer’right, otherwise, it sets it to the specified value plus the current count. procedure SetAlert-StopCount(Level : AlertType ; Count : integer) ; . . . – Level, Count SetAlertStopCount(ERROR, 20) ; – Stopif 20 errors occur When used with an AlertLogID, SetAlertStopCount sets the value for the specified AlertLogIDand all of its parents. At each level, the current alert stop count is set to the specified value when the currentcount is integer’right, otherwise, the value is set to the specified value plus the current count. procedure SetAlert-StopCount(AlertLogID : AlertLogIDType ; Level : AlertType ; Count : integer) ; . . . – AlertLogID, Level,Count SetAlertStopCount(UartID, ERROR, 20) ; By default, the AlertStopCount for WARNING and ERROR areinteger’right, and FAILURE is 0.

GetAlertStopCount Get the value of the current alert stop count for either a specific AlertLogId or for theglobal alert counter. – Hierarchy impure function GetAlertStopCount( AlertLogID : AlertLogIDType ; Level :AlertType ) return integer ; – Global Alert Stop Count impure function GetAlertStopCount(Level : AlertType)return integer ;

AlertCountType Alerts are stored as a value of AlertCountType.

subtype AlertIndexType is AlertType range FAILURE to WARNING ; type AlertCountType is array (AlertIndex-Type) of integer ; CAUTION: When working with values of AlertCountType, be sure to use named association asthe type ordering may change in the future.

GetAlertCount GetAlertCount returns the AlertCount value at AlertLogID. GetAlertCount is overloaded to re-turn either AlertCountType or integer. impure function GetAlertCount(AlertLogID : AlertLogIDType := ALERT-LOG_BASE_ID) return AlertCountType ; impure function GetAlertCount(AlertLogID : AlertLogIDType :=ALERTLOG_BASE_ID) return integer ; . . . TopTotalErrors := GetAlertCount ; – AlertCount for Top of hi-erarchy UartTotalErrors := GetAlertCount(UartID) ; – AlertCount for UartID

36 Chapter 1. News


GetEnabledAlertCount GetEnabledAlertCount is similar to GetAlertCount except it returns 0 for disabledalert levels. GetEnabledAlertCount is overloaded to return either AlertCountType or integer. impure functionGetEnabledAlertCount(AlertLogID : AlertLogIDType := ALERTLOG_BASE_ID) return AlertCountType ; im-pure function GetEnabledAlertCount (AlertLogID : AlertLogIDType := ALERTLOG_BASE_ID) return integer; . . . TopTotalErrors := GetEnabledAlertCount ; – Top of hierarchy UartTotalErrors := GetEnabledAlert-Count(UartID) ; – UartID

GetDisabledAlertCount GetDisabledAlertCount returns the count of disabled errors for either the entire designhierarchy or a particular AlertLogID. GetDisabledAlertCount is relevant since a “clean” passing design will nothave any disabled alert counts. impure function GetDisabledAlertCount return AlertCountType ; impure functionGetDisabledAlertCount return integer ; impure function GetDisabledAlertCount(AlertLogID: AlertLogIDType)return AlertCountType ; impure function GetDisabledAlertCount(AlertLogID: AlertLogIDType) return integer ;Note that disabled errors are not added to higher levels in the hierarchy. Hence, often GetAlertCount /= GetEn-abledAlertCount + GetDisabledAlertCount.

ClearAlerts: Reset Alert and Stop Counts ClearAlerts resets all alert counts to 0 and stop counts back to theirdefault. procedure ClearAlerts ;

Math on AlertCountType function “+” (L, R : AlertCountType) return AlertCountType ; function “-” (L, R: AlertCountType) return AlertCountType ; function “-” (R : AlertCountType) return AlertCountType ; . . .TotalAlertCount := Phase1Count + Phase2Count ; TotalErrors := GetAlertCount - ExpectedErrors ; NegateErrors:= -ExpectedErrors ;

SumAlertCount: AlertCountType to Integer Error Count SumAlertCount sums up the FAILURE, ERROR,and WARNING values into a single integer value. impure function SumAlertCount(AlertCount: AlertCountType)return integer ; . . . ErrorCountInt := SumAlertCount(AlertCount) ;

GetAlertLogParentID Get the AlertLogID of the parent of a specified AlertLogID. impure function GetAlert-LogParentID(AlertLogID : AlertLogIDType) return AlertLogIDType ;

Log Method Reference

LogType Log levels can be ALWAYS, DEBUG, FINAL, or INFO. type LogType is (ALWAYS, DEBUG, FI-NAL, INFO) ;

Simple Logs Simple logs use default AlertLogID. If the log level is enabled, then the log message will print.The Enable parameter is an override of the internal settings and if true, the log message will print. procedure log(Message : string ; Level : LogType := ALWAYS ; Enable : boolean := FALSE – override internal enable ) ; . . .Log(“Received UART word”, DEBUG) ;

Hierarchical Logs Hierarchical logs use the specified AlertLogID. If the log level is enabled, then the logmessage will print. procedure log( AlertLogID : AlertLogIDType ; Message : string ;

Level : LogType := ALWAYS ; Enable : boolean := FALSE – override internal enable ) ; . . . Log(UartID, “UartParity Received”, DEBUG) ;

SetLogEnable: Enable / Disable Logging SetLogEnable allows alert levels to be individually enabled. Whenused without AlertLogID, SetLogEnable sets a value for all AlertLogIDs. procedure SetLogEnable(Level : Log-Type ; Enable : boolean) ; . . . Log(UartID, “Uart Parity Received”, DEBUG) ; When an AlertLogID is used,SetLogEnable sets a value for that AlertLogID, and if Hierarchy is true, the AlertLogIDs of its children. procedureSetLogEnable(AlertLogID : AlertLogIDType ; Level : LogType ; Enable : boolean ; DescendHierarchy : boolean:= TRUE) ; . . . – AlertLogID, Level, Enable, DescendHierarchy SetLogEnable(UartID, WARNING, FALSE,FALSE) ;

1.1. xx.01.2016 - 2016.01 was release. 37


Reading Log Enables from a FILE ReadLogEnables read enables from a file. procedure ReadLogEnables(FileName : string) ; procedure ReadLogEnables (file AlertLogInitFile : text) ; The preferred file format is:U_CpuModel DEBUG U_UART_TX DEBUG INFO U_UART_RX FINAL INFO DEBUG ReadLogEnables willalso read a file of the format: U_CpuModel DEBUG U_UART_TX DEBUG U_UART_TX INFO . . .

IsLoggingEnabled /GetLogEnable IsLoggingEnabled returns true when logging is enabled for a particularAlertLogID. impure function IsLoggingEnabled(Level : LogType) return boolean ; impure function IsLoggin-gEnabled(AlertLogID : AlertLogIDType ; Level : LogType) return boolean ; . . .

If IsLoggingEnabled(UartID, DEBUG) then . . . GetLogEnable is a synonym for IsLoggingEnabled. impurefunction GetLogEnable(AlertLogID : AlertLogIDType ; Level : LogType) return boolean ; impure function Get-LogEnable(Level : LogType) return boolean ;

Affirmation Method Reference

AffirmIf Affirmations are a combination of Alerts and Logs. If the Affirmation is true, then a log is generated. Ifan Affirmation is false, then an alert is generated. – Hierarchy procedure AffirmIf( AlertLogID : AlertLogIDType; condition : boolean ; Message : string ; LogLevel : LogType := PASSED ; AlertLevel : AlertType := ERROR) ; – Global Alert Counters procedure AffirmIf( condition : boolean ; Message : string ; LogLevel : LogType:= PASSED ; AlertLevel : AlertType := ERROR ) ; Affirmations are intended to be used for self-checking of atest. Each call to AffirmIf is counted and reported during ReportAlerts. This provides feedback on the amount ofself-checking added by a test and is used as a quality metric.

GetAffirmCheckCount Returns the current affirmation check count. impure function GetAffirmCheckCountreturn natural ;

IncAffirmCheckCount Increments the affirmation check count. Intended to be used only in special situations,such as packages that have additional considerations when using affirmations. procedure IncAffirmCheckCount ;

Alert and Log Output Control Options

SetAlertLogJustify SetAlertLogJustify justifies name fields of Alerts and Logs. Call after setting up the entirehierarchy if you want Alerts and Logs justified (hence optional). SetAlertLogJustify ;

OsvvmOptionsType OsvvmOptionsType defines the values for options. User values are: OPT_DEFAULT,DISABLED, FALSE, ENABLED, TRUE. The values DISABLED and FALSE are handled the same. Thevalues ENABLED and TRUE are treated the same. The value OPT_USE_DEFAULT causes the variableto use its default value. OsvvmOptionsType is defined in OsvvmGlobalPkg. type OsvvmOptionsType is(OPT_INIT_PARM_DETECT, OPT_USE_DEFAULT, DISABLED, FALSE, ENABLED, TRUE) ;

SetAlertLogOptions: Configuring Report Options The output from Alert, Log, and ReportAlerts is con-figurable using SetAlertLogOptions. procedure SetAlertLogOptions ( FailOnWarning : OsvvmOptionsType :=OPT_INIT_PARM_DETECT; FailOnDisabledErrors : OsvvmOptionsType := OPT_INIT_PARM_DETECT;ReportHierarchy : OsvvmOptionsType := OPT_INIT_PARM_DETECT; WriteAlertLevel : OsvvmOptionsType:= OPT_INIT_PARM_DETECT; WriteAlertName : OsvvmOptionsType := OPT_INIT_PARM_DETECT;WriteAlertTime : OsvvmOptionsType := OPT_INIT_PARM_DETECT; WriteLogLevel : OsvvmOptionsType:= OPT_INIT_PARM_DETECT; WriteLogName : OsvvmOptionsType := OPT_INIT_PARM_DETECT;WriteLogTime : OsvvmOptionsType := OPT_INIT_PARM_DETECT; AlertPrefix : string :=OSVVM_STRING_INIT_PARM_DETECT; LogPrefix : string := OSVVM_STRING_INIT_PARM_DETECT;ReportPrefix : string := OSVVM_STRING_INIT_PARM_DETECT; DoneName : string :=OSVVM_STRING_INIT_PARM_DETECT; PassName : string := OSVVM_STRING_INIT_PARM_DETECT;FailName : string := OSVVM_STRING_INIT_PARM_DETECT ) ; The following options are for ReportAlerts.FailOnWarning Count warnings as test errors. Enabled FailOnDisabledErrors Disabled errors are test errors.Enabled ReportHierarchy When multiple AlertLogIDs exist, print an error summary for each level. Enabled

38 Chapter 1. News


ReportPrefix Prefix for each line of ReportAlerts. “%% ” DoneName Value printed after ReportPrefix on firstline of ReportAlerts. “DONE” PassName Value printed when a test passes. “PASSED”. FailName Value printedwhen a test fails. “FAILED”

The following options are for alert: WriteAlertLevel Print level. Enabled WriteAlertName Print AlertLogIDname. Enabled WriteAlertTime Alerts print time. Enabled AlertPrefix Value printed at beginning of alert. “%%Alert” The following options are for Log: WriteLogLevel Print level. Enabled WriteLogName Print AlertLogIDname. Enabled WriteLogTime Logs print time. Enabled LogPrefix Value printed at beginning of log. “%%Alert” SetAlertOptions will change as AlertLogPkg evolves. Use of named association is required to ensurefuture compatibility. SetAlertLogOptions ( FailOnWarning => FALSE, FailOnDisabledErrors => FALSE ) ; Aftersetting a value, a string value can be reset using OSVVM_STRING_USE_DEFAULT and an OsvvmOptionsTypevalue can be reset using OPT_USE_DEFAULT.

ReportAlertLogOptions: Print Report Options Prints out AlertLogPkg Report Options.

Getting AlertLog Report Options Report options can be retrieved with one of the Get functions below.function GetAlertLogFailOnWarning return AlertLogOptionsType ; function GetAlertLogFailOnDisabledErrorsreturn AlertLogOptionsType ; function GetAlertLogReportHierarchy return AlertLogOptionsType ; functionGetAlertLogHierarchyInUse return AlertLogOptionsType ; function GetAlertLogWriteAlertLevel return Alert-LogOptionsType ; function GetAlertLogWriteAlertName return AlertLogOptionsType ; function GetAlertLog-WriteAlertTime return AlertLogOptionsType ; function GetAlertLogWriteLogLevel return AlertLogOptionsType; function GetAlertLogWriteLogName return AlertLogOptionsType ; function GetAlertLogWriteLogTime returnAlertLogOptionsType ; function GetAlertLogAlertPrefix return string ; function GetAlertLogLogPrefix returnstring ; function GetAlertLogReportPrefix return string ; function GetAlertLogDoneName return string ; functionGetAlertLogPassName return string ; function GetAlertLogFailName return string ;

Deallocating and Re-initializing the Data structure

DeallocateAlertLogStruct DeallocateAlertLogStruct deallocates all temporary storage allocated by AlertLog-Pkg. Also see ClearAlerts.

InitializeAlertLogStruct InitializeAlertLogStruct is used after DeallocateAlertLogStruct to create and initializeinternal storage.

Compiling AlertLogPkg and Friends

Use of AlertLogPkg requires use NamePkg and OsvvmGlobalPkg. The compile order is: NamePkg.vhd, Osvvm-GlobalPkg.vhd, TranscriptPkg.vhd, and AlertLogPkg.vhd. Compiling the packages requires VHDL-2008.

About AlertLogPkg

AlertLogPkg was developed and is maintained by Jim Lewis of SynthWorks VHDL Training. It originated as aninterface layer to the BitVis Utility Library (BVUL). However, it required a default implementation and that de-fault implementation grew into its own project. Please support our effort in supporting AlertLogPkg and OSVVMby purchasing your VHDL training from SynthWorks. AlertLogPkg is released under the Perl Artistic opensource license. It is free (both to download and use - there are no license fees). You can download it fromhttp://www.synthworks.com/downloads. It will be updated from time to time. Currently there are numerousplanned revisions. If you add features to the package, please donate them back under the same license as can-didates to be added to the standard version of the package. If you need features, be sure to contact us. I blogabout the packages at http://www.synthworks.com/blog. We also support the OSVVM user community and blogsthrough http://www.osvvm.org. Find any innovative usage for the package? Let us know, you can blog about it atosvvm.org.

1.1. xx.01.2016 - 2016.01 was release. 39





Future Work

AlertLogPkg.vhd is a work in progress and will be updated from time to time. Caution, undocumented items areexperimental and may be removed in a future version.

See also:

AlertLogPkg Reference The complete interface reference for this package.

TranscriptPkg Reference The complete interface reference for the uder laying transcript package.

Transcript Package

Overview

TranscriptPkg allows different parts of a testbench to use a common transcript file. It does this by providing aninternal file identifier (TranscriptFile), and subprograms for opening (TranscriptOpen) files, closing (Transcript-Close) files, printing (print and writeline), and checking if the file is open (IsTranscriptOpen).

TranscriptPkg Use Models

TranscriptPkg offers three printing methods, Print, WriteLine, and direct usage of TranscriptFile. If the Tran-scriptFile is open, Print and WriteLine write to the transcript file, otherwise, they write to std.textio.OUTPUT.

use osvvm.TranscriptPkg.all ; architecture Test1 of tb is process begin Transcrip-tOpen(”./results/Transcript_t1_nominal.txt”) ; Print(“Print 1”) ; swrite(buf, “Write 1”) ; writeline(buf) ; . .. TranscriptClose ; if IsTranscriptOpen then swrite(buf, “Write 1 - transcript open”) ; writeline(TranscriptFile,buf) ; end if;

TranscriptPkg also supports a mirror mode in which Print and WriteLine write to both TranscriptFile andstd.textio.OUTPUT. Entering mirror mode is via SetTranscriptMirror.

SetTranscriptMirror ; SetAlertStopCount(ERROR, 20) ;

Usage by other OSVVM packages

Print and WriteLine are used by other OSVVM packages.

In CoveragePkg, WriteBin without a file specification uses IsTranscriptOpen to determine whether to usestd.textio.OUTPUT or TranscriptFile.

In AlertLogPkg, alert, log, and ReportAlerts all use osvvm.TranscriptPkg.WriteLine.

Method Reference

Package Reference Using TranscriptPkg requires the following package reference:

library osvvm ; use osvvm.TranscriptPkg.all ;

Transcript File TranscriptFile is an internal file to the declarative region of TranscriptPkg.

file TranscriptFile : text ;

40 Chapter 1. News


TranscriptOpen TranscriptOpen opens the TranscriptFile. When the transcript is open, alert, log, ReportAlerts,WriteLine, and print use the TranscriptFile, otherwise, they use OUTPUT. procedure TranscriptOpen (Status: outFILE_OPEN_STATUS; ExternalName: STRING; OpenKind: FILE_OPEN_KIND := WRITE_MODE) ; pro-cedure TranscriptOpen (ExternalName: STRING; OpenKind: FILE_OPEN_KIND := WRITE_MODE) ; im-pure function TranscriptOpen (ExternalName: STRING; OpenKind: FILE_OPEN_KIND := WRITE_MODE)return FILE_OPEN_STATUS ; . . . – file open status, File name, file open kind TranscriptOpen(Status, ”./Re-sults.txt”, WRITE_MODE) ; TranscriptOpen( ”./Results.txt”, WRITE_MODE) ; WRITE_MODE is the default.If READ_MODE is used, an error is generated.

Usage of the function form allows a file to be opened in a declarative region (such as in a package).

Constant OPENED_RESULTS : FILE_OPEN_STATUS := TranscriptOpen(”./Results.txt”, WRITE_MODE) ;

TranscriptClose TranscriptClose closes the TranscriptFile.

procedure TranscriptClose ;

IsTranscriptOpen IsTranscriptOpen returns true when the TranscriptFile is open.

impure function IsTranscriptOpen return boolean ; . . . if IsTranscriptOpen then swrite(buf, “Write 1 - transcriptopen”) ; writeline(TranscriptFile, buf) ; end if;

WriteLine Writeline writes the buffer to the TranscriptFile when it is open, otherwise, to OUTPUT.

procedure WriteLine(buf : inout line) ; . . . swrite(buf, “A Message”) ; writeline(buf) ;

Print Print writes the string to the TranscriptFile if it is open, otherwise, to OUTPUT.

procedure Print(s : string) ; . . . Print(“Another Message”) ;

SetTranscriptMirror SetTranscriptMirror sets mirror mode in which Print and WriteLine write to both Tran-scriptFile and std.textio.OUTPUT.

procedure SetTranscriptMirror (A : boolean := TRUE) ; . . . SetTranscriptMirror ;

IsTranscriptMirrored IsTranscriptMirrored returns true when the transcript is mirrored.

impure function IsTranscriptMirrored return boolean ; . . . if IsTranscriptMirrored then . . .

5 Compiling TranscriptPkg and Friends

Use of AlertLogPkg requires use NamePkg, OsvvmGlobalPkg, and AlertLogBasePkg. The compile order is:NamePkg.vhd, OsvvmGlobalPkg.vhd, AlertLogBasePkg.vhd, and AlertLogPkg.vhd. Compiling the packagesrequires VHDL-2008.

6 About TranscriptPkg

TranscriptPkg was developed and is maintained by Jim Lewis of SynthWorks VHDL Training. It originated inconjunction with AlertLogPkg.

Please support our effort in supporting TranscriptPkg and OSVVM by purchasing your VHDL training fromSynthWorks.

TranscriptPkg is released under the Perl Artistic open source license. It is free (both to download and use - thereare no license fees). You can download it from

1.1. xx.01.2016 - 2016.01 was release. 41


http://www.synthworks.com/downloads. It will be updated from time to time. Currently there are numerousplanned revisions. If you add features to the package, please donate them back under the same license as can-didates to be added to the standard version of the package. If you need features, be sure to contact us. I blogabout the packages at http://www.synthworks.com/blog. We also support the OSVVM user community and blogsthrough http://www.osvvm.org. Find any innovative usage for the package? Let us know, you can blog about it atosvvm.org.

Future Work

TranscriptPkg.vhd is a work in progress and will be updated from time to time.

Caution, undocumented items are experimental and may be removed in a future version.

Memory Package

Overview

The AlertLogPkg provides a protected type and methods to simplify the creation of data structures required tomodel larger memories.



use osvvm.AlertLogPkg.all ; architecture Test1 of tb is


– message, level When others => Alert(“Illegal State”, FAILURE) ; . . . – condition, message, level Aler-tIf(ActualData /= ExpectedData, “Data Miscompare . . . ”, ERROR) ; . . . read(Buf, A, ReadValid) ; – condition,message, level AlertIfNot( ReadValid, “read of A failed”, FAILURE) ;


%% Alert ERROR Data Miscompare . . . at 20160 ns


ReportAlerts ;




%% DONE FAILED t1_basic Total Error(s) = 2 Failures: 0 Errors: 1 Warnings: 1 at 120180 ns




SetGlobalAlertEnable(TRUE) ; – Default SetAlertEnable(WARNING, FALSE) ;


Log (“A message”, DEBUG) ; Log formats the output as follows. %% Log DEBUG A Message at 15110 ns

42 Chapter 1. News







Method Reference

Package References Using MemoryPkg requires the following package references:

library osvvm ; use osvvm.MemoryPkg.all ;

MemInit Alert levels can be FAILURE, ERROR, or WARNING.


MemWrite Simple alerts accumulate alerts in the default AlertLogID (ALERTLOG_DEFAULT_ID). It sup-ports the basic overloading and usage:

procedure Alert( Message : string ; Level : AlertType := ERROR ) ; . . . Alert(“Uart Parity”) ; – ERROR bydefault

MemRead Procedure Each level in a hierarchy is referenced with an AlertLogID. The function, GetAlert-LogID, creates a new AlertLogID. If an AlertLogID already exists for the specified name,

GetAlertLogID will return its AlertLogID. It is recommended to use the instance label as the Name. The interfacefor GetAlertLogID is as follows.

impure function GetAlertLogID(Name : string ; ParentID : AlertLogIDType := ALERTLOG_BASE_ID ) returnAlertLogIDType ; GetAlertLogID(“UART_1”, ALERTLOG_BASE_ID);

MemRead Function The function, FindAlertLogID, finds an existing AlertLogID. If the AlertLogID is notfound, ALERTLOG_ID_NOT_FOUND is returned. The interface for FindAlertLogID is as follows.

impure function FindAlertLogID(Name : string ; ParentID : AlertLogIDType) return AlertLogIDType ; impurefunction FindAlertLogID(Name : string ) return AlertLogIDType ;

MemErase Hierarchical alerts require the AlertLogID to be specified in the call to alert. It supports the basicoverloading and usage:

procedure alert( AlertLogID : AlertLogIDType ; Message : string ; Level : AlertType := ERROR ) ; . . .Alert(UartID, “Uart Parity”, ERROR) ;

Deallocate At test completion alerts are reported with ReportAlerts.

procedure ReportAlerts ( Name : string := “” ; AlertLogID : AlertLogIDType := ALERTLOG_BASE_ID ; Exter-nalErrors : AlertCountType := (others => 0) ) ; . . . ReportAlerts ;

ReadMemB and ReadMemH Designed to mimic Verilog system functions $readmemb and readmemh.

procedure ReadMemB ( Name : string ; StartAddr : natural := 0 ; FinishAddr : natural := natural’right ) ;

The file shall contain only of the following:

• White space (spaces, new lines, tabs, and form-feeds)

• Comments (either //, #, or –)

• @ character (designating the adjacent number is an address)

1.1. xx.01.2016 - 2016.01 was release. 43


• Binary or hexadecimal numbers

Addresses specified in the call to ReadMemB ro ReadMemH provide both an initial starting address and a rangeof valid addresses for memory operations. Addressing advances from StartAddr to FinishAddr. If FinishAddr isgreater than StartAddr, then the next address is one larger than the current one, otherwise, the next address is oneless than the current address.

Addresses may also be specified in the file in the format ‘@’ followed by a hexadecimal number as shown below.There shall not be any space between the ‘@’ and the number. The address read must be between StartAddr andFinishAddr or a FAILURE is generated.

@hhhhh

Values not preceded by an ‘@’ character are data values. Data values must be separated by white space orcomments from other values. ReadMemB requires values compatible with read for std_ulogic. ReadMemHrequires hexadecimal values compatible with hread for std_ulogic_vector. If more digits are read than are requiredby the memory, left hand characters will be dropped provided they are 0. If fewer digits are read than are requiredby the memory, left hand characters will be 0.



About AlertLogPkg

AlertLogPkg was developed and is maintained by Jim Lewis of SynthWorks VHDL Training. It originated asan interface layer to the BitVis Utility Library (BVUL). However, it required a default implementation and thatdefault implementation grew into its own project.

Please support our effort in supporting AlertLogPkg and OSVVM by purchasing your VHDL training from Syn-thWorks.

AlertLogPkg is released under the Perl Artistic open source license. It is free (both to download and use - thereare no license fees). You can download it from http://www.synthworks.com/downloads. It will be updated fromtime to time. Currently there are numerous planned revisions.

If you add features to the package, please donate them back under the same license as candidates to be addedto the standard version of the package. If you need features, be sure to contact us. I blog about the pack-ages at http://www.synthworks.com/blog. We also support the OSVVM user community and blogs throughhttp://www.osvvm.org.

Find any innovative usage for the package? Let us know, you can blog about it at osvvm.org.

Future Work

AlertLogPkg.vhd is a work in progress and will be updated from time to time.

Caution, undocumented items are experimental and may be removed in a future version.

1.1.4 References

AlertLog Package User Guide

AlertLogPkg Overview

VHDL assert statements are a limited form of an alert and log filtering utility. In the simulator GUI, you can setan assertion level that will stop a simulation. In the simulator GUI, you can turn off some assertions from printing.

44 Chapter 1. News





However, none of this capability can be configured in VHDL, and in addition, at the end of a test, there is no wayto retrieve a count of the ERROR level assertions that have occurred.

The AlertLogPkg provides Alert and Log procedures that replace VHDL assert statements and gives VHDLdirect access to enabling and disabling of features, retrieving alert counts, and set stop counts (limits). All of thesefeatures can be used in either a simple global mode or a hierarchy of alerts.

Alert simplifies signaling errors (when an error occurs) and reporting errors (passed or failed when a test finishes).Alerts have the levels FAILURE, ERROR, and WARNING. Each level is counted and tracked in an internal datastructure. Within the data structure, each of these can be enabled or disabled. A test can be stopped if an alertvalue has been signaled too many times. Stop values for each counter can be set. The default for FAILURE is 0and ERROR and WARNING are integer’right. If all test errors are reported as an alert, at the end of the test,a report can be generated which provides pass/fail and a count of the different alert values.

Logs provide a mechanism to conditionally print information. This verbosity control allows messages (such asdebug, DO254 final test reports, or info) that are too detailed for normal testing to be printed when specificallyenabled. VIA the simulator GUI, assert has this capability to a limited degree.

AssertLogPkg uses TranscriptPkg to print to either std.textio.OUTPUT, a file, or both.When the TranscriptFile is opened, alert and log print to the TranscriptFile, otherwise, they print tostd.textio.OUTPUT. For more details on TranscriptPkg see the TranscriptPkg User Guide.

Already using another package for alerts and verbosity control? The AlertLogPkg has an extensive API that willallow you to retrieve any error information reported by the OSVVM packages and allow you to print a summaryof results via another package.

AlertLogPkg Use Models

Alerts and Logs may be used in either a simple mode or a hierarchy model.

In simple mode, there is single global alert counter that accumulates the number of FAILURE, ERROR, andWARNING level alerts for the entire testbench. When a test completes, a summary of the total number of errorsas well as the errors for each level can be produced.

In hierarchy mode, there is a hierarchy of alert counters. Each model and/or source of alerts has its own set of alertcounters. Counts from lower levels propagate up to the top level counter. Each level in the hierarchy also supportsseparate verbosity control. When a test completes, an error report can be produced for both the top level and eachlevel in the alert hierarchy.



use osvvm.AlertLogPkg.all ;architecture Test1 of tb is


-- message, levelWhen others => Alert("Illegal State", FAILURE) ;. . .-- condition, message, levelAlertIf(ActualData /= ExpectedData, "Data Miscompare ?", ERROR) ;. . .read(Buf, A, ReadValid) ;-- condition, message, levelAlertIfNot( ReadValid, "read of A failed", FAILURE) ;


1.1. xx.01.2016 - 2016.01 was release. 45


%% Alert ERROR Data Miscompare ? at 20160 ns


ReportAlerts ;




%% DONE FAILED t1_basic Total Error(s) = 2 Failures: 0 Errors: 1 Warnings: 1 at 120180 ns




SetGlobalAlertEnable(TRUE) ; -- DefaultSetAlertEnable(WARNING, FALSE) ;


Log ("A message", DEBUG) ;

Log formats the output as follows.

%% Log DEBUG A Message at 15110 ns



Hierarchy Mode: Separate Alert Counters

In hierarchy mode, each model and/or source of alerts has its own set of alert counters. Counts from lower levelspropagate up to the top level counter. The ultimate goal of using hierarchy mode is to get a summary of errors foreach model and/or source of alerts in the testbench:

%% DONE FAILED Testbench Total Error(s) = 21 Failures: 1 Errors: 20 Warnings: 0 at 10117000 ns

%% Default Failures: 0 Errors: 4 Warnings: 0

%% OSVVM Failures: 0 Errors: 0 Warnings: 0

%% U_CpuModel Failures: 0 Errors: 4 Warnings: 0

%% Data Error Failures: 0 Errors: 2 Warnings: 0

%% Protocol Error Failures: 1 Errors: 2 Warnings: 0

%% U_UART_TX Failures: 0 Errors: 6 Warnings: 0

%% U_UART_RX Failures: 0 Errors: 6 Warnings: 0

Using hierarchy mode requires a little more work. Behind the scenes within AlertLogPkg, there is a data structureinside shared variable. Each level in a hierarchy is referenced with an AlertLogID - which is currently an integerindex into the data structure. As a result, each model must get (allocate) an AlertLogID and then referencethe AlertLogID when signaling alerts. Other than referencing the AlertLogID, the usage is identical. A newAlertLogID is created by calling the function GetAlertLogID. GetAlertLogID has two parameters: Name andParentID. Name is a string of the ALERT (that prints when the alert prints). ParentID is of type AlertLogIDType.

46 Chapter 1. News


In the following example, CPU_ALERT_ID uses the instance name of the model as its name. Since it is a toplevel model, it uses ALERTLOG_BASE_ID (which is also the default) as its ParentID. DATA_ALERT_ID is analert counter within the CPU. So it uses a string as its name and CPU_ALERT_ID as its ParentID.

constant CPU_ALERT_ID : AlertLogIDType :=-- Name (string value), Parent AlertLogIDGetAlertLogID(PathTail(CpuModel'PATH_NAME), ALERTLOG_ BASE_ID) ;constant DATA_ALERT_ID : AlertLogIDType :=GetAlertLogID("Data Error", CPU_ALERT_ID) ;constant PROTOCOL_ALERT_ID : AlertLogIDType :=GetAlertLogID("PROTOCOL Error", CPU_ALERT_ID) ;

The AlertLogID is specified first in calls to Alert, Log, SetAlertEnable, SetAlertStopCount, and SetLogEnable.

Alert(CPU_ALERT_ID, "CPU Error", ERROR) ;AlertIf(PROTOCOL_ALERT_ID, inRdy /= '0', "during CPU Read operation", FAILURE);AlertIfNotEqual(DATA_ALERT_ID, ReadData, ExpectedData, "Actual /= Expected Data");-- AlertLogID, Level, EnableSetAlertEnable(CPU_ALERT_ID, WARNING, FALSE) ;-- AlertLogID, Level, CountSetAlertStopCount(CPU_ALERT_ID, ERROR, 20) ;Log(UartID, DEBUG, "Uart Parity Received") ;-- AlertLogID, Level, Enable, DescendHierarchySetLogEnable(UartID, WARNING, FALSE, FALSE) ;

Printing of Alerts and Logs include the AlertLogID.

%% Alert FAILURE in CPU_1, Expect data XA5A5 at 2100 ns

%% Log ALWAYS in UART_1, Parity Error at 2100 ns

Package References

Using AlertLogPkg requires the following package references:

library osvvm ;use osvvm.OsvvmGlobalPkg.all ;use osvvm.AlertLogPkg.all ;

Alert Method Reference

AlertType Alert levels can be FAILURE, ERROR, or WARNING.


Simple Alerts Simple alerts accumulate alerts in the default AlertLogID (ALERTLOG_DEFAULT_ID). It sup-ports the basic overloading and usage:

procedure Alert( Message : string ; Level : AlertType := ERROR ) ;. . .Alert("Uart Parity") ; -- ERROR by default

Alert has two conditional forms, AlertIf and AlertIfNot. The following is their overloading.

-- without an AlertLogIDprocedure AlertIf( condition : boolean ;Message : string ; Level : AlertType := ERROR ) ;impure function AlertIf( condition : boolean ;Message : string ; Level : AlertType := ERROR ) return boolean ;procedure AlertIfNot( condition : boolean ;Message : string ; Level : AlertType := ERROR ) ;

1.1. xx.01.2016 - 2016.01 was release. 47


impure function AlertIfNot( condition : boolean ;Message : string ; Level : AlertType := ERROR ) return boolean ;

Usage of conditional alerts:

AlertIf(Break='1', "Uart Break", ERROR) ;AlertIfNot(ReadValid, "Read Failed", FAILURE) ;

The function form is convenient for use for conditional exit of a loop.

exit AlertIfNot(ReadValid, “in ReadCovDb while reading ?”, FAILURE) ;

Alert form AlertIfEqual and AlertIfNotEqual to check two values. In the following, AType can be std_logic,std_logic_vector, unsigned, signed, integer, real, character, or string.

procedure AlertIfEqual( L, R : AType ; Message : string ; Level : AlertType := ERROR ) ; Message : string ;procedure AlertIfNotEqual( L, R : AType; Level : AlertType := ERROR ) ; Alert form AlertIfDiff is for comparingtwo files. procedure AlertIfDiff (Name1, Name2 : string; Message : string := “” ; Level : AlertType := ERROR ); procedure AlertIfDiff (file File1, File2 : text; Message : string := “” ; Level : AlertType := ERROR ) ;

Creating Hierarchy: GetAlertLogID Each level in a hierarchy is referenced with an AlertLogID. The func-tion, GetAlertLogID, creates a new AlertLogID. If an AlertLogID already exists for the specified name, GetAlert-LogID will return its AlertLogID. It is recommended to use the instance label as the Name. The interface forGetAlertLogID is as follows. impure function GetAlertLogID( Name : string ; ParentID : AlertLogIDType :=ALERTLOG_BASE_ID ; CreateHierarchy : Boolean := TRUE ) return AlertLogIDType ; The CreateHierarchyparameter is intended to allow packages to use a unique AlertLogID for reporting Alerts without creating hierarchyin ReportAlerts. As a function, GetAlertLogID can be called while elaborating the design by using it to initialize aconstant or signal: Constant UartID : AlertLogIDType := – Name, Parent AlertLogID GetAlertLogID(“UART_1”,ALERTLOG_BASE_ID);

FindAlertLogID: Find an AlertLogID The function, FindAlertLogID, finds an existing AlertLogID. If theAlertLogID is not found, ALERTLOG_ID_NOT_FOUND is returned. The interface for FindAlertLogID is asfollows. impure function FindAlertLogID(Name : string ; ParentID : AlertLogIDType) return AlertLogIDType ;impure function FindAlertLogID(Name : string ) return AlertLogIDType ; Note the single parameter FindAlert-LogID is only useful when there is only one AlertLogID with a particular name (such as for top-level instancenames). As a function, FindAlertLogID can be called while elaborating the design by using it to initialize a con-stant or signal. constant UartID : AlertLogIDType := FindAlertLogID(Name => “UART_1”) ; Caution: only useFindAlertLogID when it is known that the ID has already been created - such as in a testbench where the testbenchcomponents have already been elaborated, as otherwise, it is appropriate to use GetAlertLogID.

PathTail - Used to Discover Instance Name of a Component When used in conjunction with at-tribute PATH_NAME applied to an entity name, PathTail returns the instance name of component.constant CPU_ALERT_ID : AlertLogIDType := – Name (string value), Parent AlertLogID GetAlert-LogID(PathTail(CpuModel’PATH_NAME), ALERTLOG_ BASE_ID) ;

Hierarchical Alerts Hierarchical alerts require the AlertLogID to be specified in the call to alert. It supportsthe basic overloading and usage: procedure alert( AlertLogID : AlertLogIDType ; Message : string ; Level :AlertType := ERROR ) ; . . . Alert(UartID, “Uart Parity”, ERROR) ; When an alert is signaled in a lowerlevel of the hierarchy, it increments all parent levels until it finds a level whose alert for that level is disabledor the top of the hierarchy. Alert has two conditional forms, AlertIf and AlertIfNot. The following is theiroverloading. The function form is convenient for use for conditional exit of a loop. procedure AlertIf( AlertLogID: AlertLogIDType ; condition : boolean ; Message : string ; Level : AlertType := ERROR ) ; impure functionAlertIf( AlertLogID : AlertLogIDType ; condition : boolean ; Message : string ; Level : AlertType := ERROR )return boolean ; procedure AlertIfNot( AlertLogID : AlertLogIDType ; condition : boolean ; Message : string ;Level : AlertType := ERROR ) ; impure function AlertIfNot( AlertLogID : AlertLogIDType ; condition : boolean ;Message : string ; Level : AlertType := ERROR ) return boolean ; Usage of conditional alerts: AlertIf(Break=‘1’,UartID, “Uart Break”, ERROR) ; AlertIfNot(ReadValid, UartID, “Read”, FAILURE); Alert form AlertIfEqualand AlertIfNotEqual to check two values. In the following, AType can be std_logic, std_logic_vector, unsigned,

48 Chapter 1. News


signed, integer, real, character, or string. procedure AlertIfEqual( AlertLogID : AlertLogIDType ; L, R : AType;Message : string ; Level : AlertType := ERROR ) ; procedure AlertIfNotEqual( AlertLogID : AlertLogIDType ;L, R : AType; Message : string ; Level : AlertType := ERROR ) ; Alert form AlertIfDiff is for comparing two files.procedure AlertIfDiff (AlertLogID : AlertLogIDType ; Name1, Name2 : string; Message : string := “” ; Level :AlertType := ERROR ) ; procedure AlertIfDiff (AlertLogID : AlertLogIDType ; file File1, File2 : text; Message :string := “” ; Level : AlertType := ERROR ) ;

IncrementAlertCount Intended as a silent alert. Used by CoveragePkg. – Hierarchy procedure IncAlertCount(– A silent form of alert AlertLogID : AlertLogIDType ;

Level : AlertType := ERROR ) ; – Global Alert Counters procedure IncAlertCount( Level : AlertType := ERROR) ;

ReportAlerts: Reporting Alerts At test completion alerts are reported with ReportAlerts. procedure Repor-tAlerts ( Name : string := “” ; AlertLogID : AlertLogIDType := ALERTLOG_BASE_ID ; ExternalErrors : Alert-CountType := (others => 0) ) ; . . . ReportAlerts ; ReportAlerts has 3 optional parameters: Name, AlertLogID, andExternalErrors. Name specifies the test name (and can also be set with SetAlertLogName). AlertLogID allowsreporting alerts for a specific AlertLogID and its children (if any). ExternalErrors allows separately detected errorsto be reported. ExternalErrors is type AlertCountType and the value (FAILURE => 0, ERROR => 5, WARNING=> 1) indicates detection logic separate from AlertLogPkg saw 0 Failures, 5 Errors, and 1 Warning. See notesunder AlertCountType. – Name, AlertLogID, ExternalErrors ReportAlerts(“Uart1”, UartID, (FAILURE => 0, ER-ROR => 5, WARNING => 1) ) ; ReportAlerts can also be used to print a passed/failed message for an AlertCountthat is passed into the procedure call. procedure ReportAlerts ( Name : String ; AlertCount : AlertCountType); This is useful to accumulate values returned by different phases of a test that need to be reported separately.ReportAlerts(“Test1: Final”, Phase1AlertCount + Phase2AlertCount) ; Also see SetAlertLogOptions.

ReportNonZeroAlerts Within the hierarchy, if a level has no alerts set, then that level will not be printed.procedure ReportNonZeroAlerts ( Name : string := OSVVM_STRING_INIT_PARM_DETECT ; AlertLogID :AlertLogIDType := ALERTLOG_BASE_ID ; ExternalErrors : AlertCountType := (others => 0) ) ;

SetAlertLogName: Setting the Test Name SetAlertLogName sets the name ReportAlerts prints when calledwithout parameters - such as when an internal stop count reached.

procedure SetAlertLogName(Name : string ) ; . . . SetAlertLogName(“Uart1”) ;

GetAlertLogName GetAlertLogName returns the string value of name associated with an AlertLogID. Ifno AlertLogID is specified, it will return the name set bySetAlertLogName. impure function GetAlertLog-Name(AlertLogID : AlertLogIDType:= ALERTLOG_BASE_ID) return string ;

SetGlobalAlertEnable: Alert Global Enable / Disable SetGlobalAlertEnable allows Alerts to be globally en-abled and disabled. The intent is to be able to disable all alerts until the system goes into reset. Alerts are enabledby default. procedure SetGlobalAlertEnable (A : EnableType := TRUE) ; impure function SetGlobalAlertEn-able (A : EnableType := TRUE) return EnableType ; Suppress all alerts before reset by turning alerts off duringelaboration with a constant declaration and then turning them back on later. InitAlerts : Process constant Dis-ableAlerts : boolean := SetGlobalAlertEnable(FALSE); begin wait until nReset = ‘1’ ; – Deassertion of resetSetGlobalAlertEnable(TRUE) ; – enable alerts

GetGlobalAlertEnable Get the current value of the global alert enable impure function GetGlobalAlertEnablereturn boolean ;

SetAlertEnable: Alert Enable / Disable SetAlertEnable allows alert levels to be individually enabled. Whenused without AlertLogID, SetAlertEnable sets a value for all AlertLogIDs. procedure SetAlertEnable(Level :AlertType ; Enable : boolean) ; . . . – Level, Enable SetAlertEnable(WARNING, FALSE) ; When an AlertLogIDis used, SetAlertEnable sets a value for that AlertLogID, and if DescendHierarchy is TRUE, it?s the AlertLogID’s

1.1. xx.01.2016 - 2016.01 was release. 49


of its children. procedure SetAlertEnable(AlertLogID : AlertLogIDType ; Level : AlertType ; Enable : boolean ;DescendHierarchy : boolean := TRUE) ;

GetAlertEnable Get the value of the current alert enable for either a specific AlertLogId or for the global alertcounter. – Hierarchy impure function GetAlertEnable(AlertLogID : AlertLogIDType ; Level : AlertType) returnboolean ; – Global Alert Counter impure function GetAlertEnable(Level : AlertType) return boolean ;

SetAlertStopCount: Alert Stop Counts When an alert stop count is reached, the simulation stops. When usedwithout AlertLogID, SetAlertStopCount sets the alert stop count for the top level to the specified value if thecurrent count is integer’right, otherwise, it sets it to the specified value plus the current count. procedure SetAlert-StopCount(Level : AlertType ; Count : integer) ; . . . – Level, Count SetAlertStopCount(ERROR, 20) ; – Stopif 20 errors occur When used with an AlertLogID, SetAlertStopCount sets the value for the specified AlertLogIDand all of its parents. At each level, the current alert stop count is set to the specified value when the currentcount is integer’right, otherwise, the value is set to the specified value plus the current count. procedure SetAlert-StopCount(AlertLogID : AlertLogIDType ; Level : AlertType ; Count : integer) ; . . . – AlertLogID, Level,Count SetAlertStopCount(UartID, ERROR, 20) ; By default, the AlertStopCount for WARNING and ERROR areinteger’right, and FAILURE is 0.

GetAlertStopCount Get the value of the current alert stop count for either a specific AlertLogId or for theglobal alert counter. – Hierarchy impure function GetAlertStopCount( AlertLogID : AlertLogIDType ; Level :AlertType ) return integer ; – Global Alert Stop Count impure function GetAlertStopCount(Level : AlertType)return integer ;

AlertCountType Alerts are stored as a value of AlertCountType.

subtype AlertIndexType is AlertType range FAILURE to WARNING ; type AlertCountType is array (AlertIndex-Type) of integer ; CAUTION: When working with values of AlertCountType, be sure to use named association asthe type ordering may change in the future.

GetAlertCount GetAlertCount returns the AlertCount value at AlertLogID. GetAlertCount is overloaded to re-turn either AlertCountType or integer. impure function GetAlertCount(AlertLogID : AlertLogIDType := ALERT-LOG_BASE_ID) return AlertCountType ; impure function GetAlertCount(AlertLogID : AlertLogIDType :=ALERTLOG_BASE_ID) return integer ; . . . TopTotalErrors := GetAlertCount ; – AlertCount for Top of hi-erarchy UartTotalErrors := GetAlertCount(UartID) ; – AlertCount for UartID

GetEnabledAlertCount GetEnabledAlertCount is similar to GetAlertCount except it returns 0 for disabledalert levels. GetEnabledAlertCount is overloaded to return either AlertCountType or integer. impure functionGetEnabledAlertCount(AlertLogID : AlertLogIDType := ALERTLOG_BASE_ID) return AlertCountType ; im-pure function GetEnabledAlertCount (AlertLogID : AlertLogIDType := ALERTLOG_BASE_ID) return integer; . . . TopTotalErrors := GetEnabledAlertCount ; – Top of hierarchy UartTotalErrors := GetEnabledAlert-Count(UartID) ; – UartID

GetDisabledAlertCount GetDisabledAlertCount returns the count of disabled errors for either the entire designhierarchy or a particular AlertLogID. GetDisabledAlertCount is relevant since a “clean” passing design will nothave any disabled alert counts. impure function GetDisabledAlertCount return AlertCountType ; impure functionGetDisabledAlertCount return integer ; impure function GetDisabledAlertCount(AlertLogID: AlertLogIDType)return AlertCountType ; impure function GetDisabledAlertCount(AlertLogID: AlertLogIDType) return integer ;Note that disabled errors are not added to higher levels in the hierarchy. Hence, often GetAlertCount /= GetEn-abledAlertCount + GetDisabledAlertCount.

ClearAlerts: Reset Alert and Stop Counts ClearAlerts resets all alert counts to 0 and stop counts back to theirdefault. procedure ClearAlerts ;

50 Chapter 1. News


Math on AlertCountType function “+” (L, R : AlertCountType) return AlertCountType ; function “-” (L, R: AlertCountType) return AlertCountType ; function “-” (R : AlertCountType) return AlertCountType ; . . .TotalAlertCount := Phase1Count + Phase2Count ; TotalErrors := GetAlertCount - ExpectedErrors ; NegateErrors:= -ExpectedErrors ;

SumAlertCount: AlertCountType to Integer Error Count SumAlertCount sums up the FAILURE, ERROR,and WARNING values into a single integer value. impure function SumAlertCount(AlertCount: AlertCountType)return integer ; . . . ErrorCountInt := SumAlertCount(AlertCount) ;

GetAlertLogParentID Get the AlertLogID of the parent of a specified AlertLogID. impure function GetAlert-LogParentID(AlertLogID : AlertLogIDType) return AlertLogIDType ;

Log Method Reference

LogType Log levels can be ALWAYS, DEBUG, FINAL, or INFO. type LogType is (ALWAYS, DEBUG, FI-NAL, INFO) ;

Simple Logs Simple logs use default AlertLogID. If the log level is enabled, then the log message will print.The Enable parameter is an override of the internal settings and if true, the log message will print. procedure log(Message : string ; Level : LogType := ALWAYS ; Enable : boolean := FALSE – override internal enable ) ; . . .Log(“Received UART word”, DEBUG) ;

Hierarchical Logs Hierarchical logs use the specified AlertLogID. If the log level is enabled, then the logmessage will print. procedure log( AlertLogID : AlertLogIDType ; Message : string ;

Level : LogType := ALWAYS ; Enable : boolean := FALSE – override internal enable ) ; . . . Log(UartID, “UartParity Received”, DEBUG) ;

SetLogEnable: Enable / Disable Logging SetLogEnable allows alert levels to be individually enabled. Whenused without AlertLogID, SetLogEnable sets a value for all AlertLogIDs. procedure SetLogEnable(Level : Log-Type ; Enable : boolean) ; . . . Log(UartID, “Uart Parity Received”, DEBUG) ; When an AlertLogID is used,SetLogEnable sets a value for that AlertLogID, and if Hierarchy is true, the AlertLogIDs of its children. procedureSetLogEnable(AlertLogID : AlertLogIDType ; Level : LogType ; Enable : boolean ; DescendHierarchy : boolean:= TRUE) ; . . . – AlertLogID, Level, Enable, DescendHierarchy SetLogEnable(UartID, WARNING, FALSE,FALSE) ;

Reading Log Enables from a FILE ReadLogEnables read enables from a file. procedure ReadLogEnables(FileName : string) ; procedure ReadLogEnables (file AlertLogInitFile : text) ; The preferred file format is:U_CpuModel DEBUG U_UART_TX DEBUG INFO U_UART_RX FINAL INFO DEBUG ReadLogEnables willalso read a file of the format: U_CpuModel DEBUG U_UART_TX DEBUG U_UART_TX INFO . . .

IsLoggingEnabled /GetLogEnable IsLoggingEnabled returns true when logging is enabled for a particularAlertLogID. impure function IsLoggingEnabled(Level : LogType) return boolean ; impure function IsLoggin-gEnabled(AlertLogID : AlertLogIDType ; Level : LogType) return boolean ; . . .

If IsLoggingEnabled(UartID, DEBUG) then . . . GetLogEnable is a synonym for IsLoggingEnabled. impurefunction GetLogEnable(AlertLogID : AlertLogIDType ; Level : LogType) return boolean ; impure function Get-LogEnable(Level : LogType) return boolean ;

1.1. xx.01.2016 - 2016.01 was release. 51


Affirmation Method Reference

AffirmIf Affirmations are a combination of Alerts and Logs. If the Affirmation is true, then a log is generated. Ifan Affirmation is false, then an alert is generated. – Hierarchy procedure AffirmIf( AlertLogID : AlertLogIDType; condition : boolean ; Message : string ; LogLevel : LogType := PASSED ; AlertLevel : AlertType := ERROR) ; – Global Alert Counters procedure AffirmIf( condition : boolean ; Message : string ; LogLevel : LogType:= PASSED ; AlertLevel : AlertType := ERROR ) ; Affirmations are intended to be used for self-checking of atest. Each call to AffirmIf is counted and reported during ReportAlerts. This provides feedback on the amount ofself-checking added by a test and is used as a quality metric.

GetAffirmCheckCount Returns the current affirmation check count. impure function GetAffirmCheckCountreturn natural ;

IncAffirmCheckCount Increments the affirmation check count. Intended to be used only in special situations,such as packages that have additional considerations when using affirmations. procedure IncAffirmCheckCount ;

Alert and Log Output Control Options

SetAlertLogJustify SetAlertLogJustify justifies name fields of Alerts and Logs. Call after setting up the entirehierarchy if you want Alerts and Logs justified (hence optional). SetAlertLogJustify ;

OsvvmOptionsType OsvvmOptionsType defines the values for options. User values are: OPT_DEFAULT,DISABLED, FALSE, ENABLED, TRUE. The values DISABLED and FALSE are handled the same. Thevalues ENABLED and TRUE are treated the same. The value OPT_USE_DEFAULT causes the variableto use its default value. OsvvmOptionsType is defined in OsvvmGlobalPkg. type OsvvmOptionsType is(OPT_INIT_PARM_DETECT, OPT_USE_DEFAULT, DISABLED, FALSE, ENABLED, TRUE) ;

SetAlertLogOptions: Configuring Report Options The output from Alert, Log, and ReportAlerts is con-figurable using SetAlertLogOptions. procedure SetAlertLogOptions ( FailOnWarning : OsvvmOptionsType :=OPT_INIT_PARM_DETECT; FailOnDisabledErrors : OsvvmOptionsType := OPT_INIT_PARM_DETECT;ReportHierarchy : OsvvmOptionsType := OPT_INIT_PARM_DETECT; WriteAlertLevel : OsvvmOptionsType:= OPT_INIT_PARM_DETECT; WriteAlertName : OsvvmOptionsType := OPT_INIT_PARM_DETECT;WriteAlertTime : OsvvmOptionsType := OPT_INIT_PARM_DETECT; WriteLogLevel : OsvvmOptionsType:= OPT_INIT_PARM_DETECT; WriteLogName : OsvvmOptionsType := OPT_INIT_PARM_DETECT;WriteLogTime : OsvvmOptionsType := OPT_INIT_PARM_DETECT; AlertPrefix : string :=OSVVM_STRING_INIT_PARM_DETECT; LogPrefix : string := OSVVM_STRING_INIT_PARM_DETECT;ReportPrefix : string := OSVVM_STRING_INIT_PARM_DETECT; DoneName : string :=OSVVM_STRING_INIT_PARM_DETECT; PassName : string := OSVVM_STRING_INIT_PARM_DETECT;FailName : string := OSVVM_STRING_INIT_PARM_DETECT ) ; The following options are for ReportAlerts.FailOnWarning Count warnings as test errors. Enabled FailOnDisabledErrors Disabled errors are test errors.Enabled ReportHierarchy When multiple AlertLogIDs exist, print an error summary for each level. EnabledReportPrefix Prefix for each line of ReportAlerts. “%% ” DoneName Value printed after ReportPrefix on firstline of ReportAlerts. “DONE” PassName Value printed when a test passes. “PASSED”. FailName Value printedwhen a test fails. “FAILED”

The following options are for alert: WriteAlertLevel Print level. Enabled WriteAlertName Print AlertLogIDname. Enabled WriteAlertTime Alerts print time. Enabled AlertPrefix Value printed at beginning of alert. “%%Alert” The following options are for Log: WriteLogLevel Print level. Enabled WriteLogName Print AlertLogIDname. Enabled WriteLogTime Logs print time. Enabled LogPrefix Value printed at beginning of log. “%%Alert” SetAlertOptions will change as AlertLogPkg evolves. Use of named association is required to ensurefuture compatibility. SetAlertLogOptions ( FailOnWarning => FALSE, FailOnDisabledErrors => FALSE ) ; Aftersetting a value, a string value can be reset using OSVVM_STRING_USE_DEFAULT and an OsvvmOptionsTypevalue can be reset using OPT_USE_DEFAULT.

52 Chapter 1. News


ReportAlertLogOptions: Print Report Options Prints out AlertLogPkg Report Options.

Getting AlertLog Report Options Report options can be retrieved with one of the Get functions below.function GetAlertLogFailOnWarning return AlertLogOptionsType ; function GetAlertLogFailOnDisabledErrorsreturn AlertLogOptionsType ; function GetAlertLogReportHierarchy return AlertLogOptionsType ; functionGetAlertLogHierarchyInUse return AlertLogOptionsType ; function GetAlertLogWriteAlertLevel return Alert-LogOptionsType ; function GetAlertLogWriteAlertName return AlertLogOptionsType ; function GetAlertLog-WriteAlertTime return AlertLogOptionsType ; function GetAlertLogWriteLogLevel return AlertLogOptionsType; function GetAlertLogWriteLogName return AlertLogOptionsType ; function GetAlertLogWriteLogTime returnAlertLogOptionsType ; function GetAlertLogAlertPrefix return string ; function GetAlertLogLogPrefix returnstring ; function GetAlertLogReportPrefix return string ; function GetAlertLogDoneName return string ; functionGetAlertLogPassName return string ; function GetAlertLogFailName return string ;

Deallocating and Re-initializing the Data structure

DeallocateAlertLogStruct DeallocateAlertLogStruct deallocates all temporary storage allocated by AlertLog-Pkg. Also see ClearAlerts.

InitializeAlertLogStruct InitializeAlertLogStruct is used after DeallocateAlertLogStruct to create and initializeinternal storage.



About AlertLogPkg

AlertLogPkg was developed and is maintained by Jim Lewis of SynthWorks VHDL Training. It originated as aninterface layer to the BitVis Utility Library (BVUL). However, it required a default implementation and that de-fault implementation grew into its own project. Please support our effort in supporting AlertLogPkg and OSVVMby purchasing your VHDL training from SynthWorks. AlertLogPkg is released under the Perl Artistic opensource license. It is free (both to download and use - there are no license fees). You can download it fromhttp://www.synthworks.com/downloads. It will be updated from time to time. Currently there are numerousplanned revisions. If you add features to the package, please donate them back under the same license as can-didates to be added to the standard version of the package. If you need features, be sure to contact us. I blogabout the packages at http://www.synthworks.com/blog. We also support the OSVVM user community and blogsthrough http://www.osvvm.org. Find any innovative usage for the package? Let us know, you can blog about it atosvvm.org.

Future Work

AlertLogPkg.vhd is a work in progress and will be updated from time to time. Caution, undocumented items areexperimental and may be removed in a future version.

Functional Coverage Using CoveragePkg

Writing Functional Coverage Using CoveragePkg

Functional coverage can be written using any code. CoveragePkg and language syntax are solely intended tosimplify this effort. In this section, we will first look at implementing functional coverage manually (withoutCoveragePkg). Then we will look at using CoveragePkg to capture item and cross coverage.

1.1. xx.01.2016 - 2016.01 was release. 53





Item (Point) Coverage done Manually In this subsection we write item coverage using regular VHDL code.While for most problems this is the hard way to capture coverage, it provides a basis for understanding functionalcoverage.

In a packet based transfer (such as across an ethernet port), most interesting things happen when the transfer size isat or near either the minimum or maximum sized transfers. It is important that a number of medium sized transfersoccur, but we do not need to see as many of them. For this example, let’s assume that we are interested in trackingtransfers that are either the following size or range: 1, 2, 3, 4 to 127, 128 to 252, 253, 254, or 255. The sizes welook for are specified by our test plan.

We also must decide when to capture (aka sample) the coverage. In the following code, we use the rising edge ofclock where the flag TransactionDone is 1.

signal Bin : integer_vector(1 to 8) ; . . . process begin wait until rising_edge(Clk) and TransactionDone = ‘1’; case to_integer(unsigned(ActualData)) is when 1 => Bin(1) <= Bin(1) + 1 ; when 2 => Bin(2) <= Bin(2) + 1 ;when 3 => Bin(3) <= Bin(3) + 1 ; when 4 to 127 => Bin(4) <= Bin(4) + 1 ; when 128 to 252 => Bin(5) <= Bin(5)+ 1 ; when 253 => Bin(6) <= Bin(6) + 1 ; when 254 => Bin(7) <= Bin(7) + 1 ;

when 255 => Bin(8) <= Bin(8) + 1 ; when others => end case ; end process ;

Any coverage can be written this way. However, this is too much work and too specific to the problem at hand. Wecould make a small improvement to this by capturing the code in a procedure. This would help with local reuse,but there are still no built-in operations to determine when testing is done, to print reports, or to save results andthe data structure to a file.

Basic Item (Point) Coverage with CoveragePkg In this subsection we use CoveragePkg to write the itemcoverage for the same packet based transfer sizes created in the previous section manually. Again, we are mostinterested in the smallest and largest transfers. Hence, for an interface that can transfer between 1 and 255 wordswe will track transfers of the following size or range: 1, 2, 3, 4 to 127, 128 to 252, 253, 254, and 255.

The basic steps to model functional coverage are declare the coverage object, create the coverage model, accumu-late coverage, interact with the coverage data structure, and report the coverage.

Coverage is modeled using a data structure stored inside of a coverage object. The coverage object is created bydeclaring a shared variable of type CovPType, such as CovBin1 shown below.

architecture Test1 of tb is shared variable CovBin1 : CovPType ; begin

Internal to the data structure, each bin in an item coverage model is represented by a minimum and maximumvalue (effectively a range). Bins that have only a single value, such as 1 are represented by the pair 1, 1 (meaning1 to 1). Internally, the minimum and maximum values are stored in a record with other bin information.

The coverage model is constructed by using the method AddBins and the function GenBin. The function GenBintransforms a bin descriptor into a set of bins. The method AddBins inserts these bins into the data structure internalto the protected type. Note that when calling a method of a protected type, such as AddBins shown below, themethod name is prefixed by the protected type variable name, CovBin1. The version of GenBin shown below hasthree parameters: min value, max value, and number of bins. The call, GenBin(1,3,3), breaks the range 1 to 3 intothe 3 separate bins with ranges 1 to 1, 2 to 2, 3 to 3.

TestProc : process begin – min, max, #bins CovBin1.AddBins(GenBin(1, 3, 3)); – bins 1 to 1, 2 to 2, 3 to 3 . . .

Additional calls to AddBins appends additional bins to the data structure. As a result, the call, GenBin(4, 252, 2),appends two bins with the ranges 4 to 127 and 128 to 252 respectively to the coverage model.

CovBin1.AddBins(GenBin( 4, 252, 2)) ; – bins 4 to 127 and 128 to 252

Since creating one bin for each value within a range is common, there is also a version of GenBin that has twoparameters: min value and max value which creates one bin per value. As a result, the call GenBin(253, 255)appends three bins with the ranges 253 to 253, 254 to 254, and 255 to 255.

CovBin1.AddBins(GenBin(253, 255)) ; – bins 253, 254, 255

Coverage is accumulated using the method ICover. Since coverage is collected using sequential code, either clockbased sampling (shown below) or transaction based sampling (by calling ICover after a transaction completes -shown in later examples) can be used.

54 Chapter 1. News


– Accumulating coverage using clock based sampling loop wait until rising_edge(Clk) and nReset = ‘1’ ; Cov-Bin1.ICover(to_integer(unsigned(RxData_slv))) ; end loop ; end process ;

A test is done when functional coverage reaches 100%. The method IsCovered returns true when all the countbins in the coverage data structure have reached their goal. The following code shows the previous loop modifiedso that it exits when coverage reaches 100%.

– capture coverage until coverage is 100% while not CovBin1.IsCovered loop wait until rising_edge(Clk) andnReset = ‘1’ ; CovBin1.ICover(to_integer(RxData_slv)) ; end loop ;

Finally, when the test is done, the method WriteBin is used to print the coverage results to the file specified byTranscriptPkg (either TranscriptFile, OUTPUT, or both if mirroring is enabled).

CovBin1.WriteBin ;

Putting the entire example together, we end up with the following.

architecture Test1 of tb is shared variable CovBin1 : CovPType ; – Coverage Object begin TestProc : pro-cess begin – Model the coverage CovBin1.AddBins(GenBin( 1, 3 )) ; CovBin1.AddBins(GenBin( 4, 252, 2)); CovBin1.AddBins(GenBin(253, 255 )) ; – Accumulating Coverage – clock based sampling while not Cov-Bin1.IsCovered loop wait until rising_edge(Clk) and nReset = ‘1’ ; CovBin1.ICover(to_integer(RxData_slv)) ;end loop ; – Print Results CovBin1.WriteBin ; wait ; end process ;

Note that when modeling coverage, we primarily work with integer values. All of the inputs to GenBin and ICoverare integers; WriteBin reports results in terms of integers. This is similar to what other verification languages do.

Cross Coverage with CoveragePkg Cross coverage examines the relationships between different objects, suchas making sure that each register source has been used with an ALU. The hardware we are working with is asshown below. Note that the test plan will also be concerned about what values are applied to the adder. We are notintending to address that part of the test here.

Mux8:1Mux8:1Q0Q7D0D7............SRC1SRC2

Cross coverage for SRC1 crossed SRC2 with can be visualized as a matrix of 8 x 8 bins.

R7R6R5R4R3R2R1R0R7R6R5R4R3R2R1R0SRC2SRC1

The steps for modeling cross coverage are the same steps used for item coverage: declare, model, accumulate,interact, and report. Collecting cross coverage only differs in the model and accumulate steps.

Cross coverage is modeled using the method AddCross and two or more calls to function GenBin. AddCrosscreates the cross product of the set of bins (created by GenBin) on its inputs. The code below shows the call tocreate the 8 x 8 cross. Each call to GenBin(0,7) creates the 8 bins: 0, 1, 2, 3, 4, 5, 6, 7. The AddCross creates the64 bins cross product of these bins. This can be visualized as the matrix shown previously.

ACov.AddCross( GenBin(0,7), GenBin(0,7) );

AddCross supports crossing of up to 20 items. Internal to the data structure there is a record that holds minimumand maximum values for each item in the cross. Hence for the first bin, the record contains SRC1 minimum 0,SRC1 maximum 0, SRC2 minimum 0, and SRC2 maximum 0. The record also contains other bin information(such as coverage goal, current count, bin type (count, illegal, ignore), and weight).

The accumulate step now requires a value for SRC1 and SRC2. The overloaded ICover method for cross coverageuses an integer_vector input. This allows it to accept a value for each item in the cross. The extra set of parenthesesaround Src1 and Src2 in the call to ICover below designate that it is a integer_vector.

ACov.ICover( (Src1, Src2) ) ;

The code below shows the entire example. The shared variable, ACov, declares the coverage object. AddCrosscreates the cross coverage model. IsCovered is used to determine when all items in the coverage model have beencovered. Each register is selected using uniform randomization (RandInt). The transaction procedure, DoAluOp,applies the stimulus. ICover accumulates the coverage. WriteBin reports the coverage.

13

architecture Test2 of tb is shared variable ACov : CovPType ; – Declare begin TestProc : process variable RV: RandomPType ; variable Src1, Src2 : integer ; begin – create coverage model ACov.AddCross( GenBin(0,7),

1.1. xx.01.2016 - 2016.01 was release. 55


GenBin(0,7) ); – Model while not ACov.IsCovered loop – Done? Src1 := RV.RandInt(0, 7) ; – Uniform Random-ization Src2 := RV.RandInt(0, 7) ; DoAluOp(TRec, Src1, Src2) ; – Transaction ACov.ICover( (Src1, Src2) ) ; –Accumulate end loop ; ACov.WriteBin ; – Report EndStatus(. . . ) ; end process ;

Intelligent Coverage is 5X or more faster than constrained random

Constrained Random Repeats Test Cases In the previous section we used uniform randomization (shownbelow) to select the register pairs for the ALU. Constrained random at its best produces a uniform distribution.As a result, the previous example is a best case model of constrained random tests. Src1 := RV.RandInt(0, 7) ;– Uniform Randomization Src2 := RV.RandInt(0, 7) ; The problem with constrained random testbenches is thatthey repeat some test cases before generating all test cases. In general to generate N cases, it takes “N * log N”randomizations. The “log N” represents repeated test cases and significantly adds to simulation run times. Ideallywe would like to run only N test cases.

Running the previous ALU testbench, we get the following coverage matrix when the code completes. Notethat some case were generated 10 time before all were done at least 1 time. It took 315 randomizations togenerate all 64 unique pairs. This is slightly less than 5X more iterations than the 64 in the ideal case. Thiscorrelates well with theory as 315 64 * log(64). By changing the seed value, the exact number of randomizationsmay increase or decrease but this would be a silly way to try to reduce the number of iterations a test runs.R7R6R5R4R3R2R1R0R7R6R5R4R3R2R1R0SRC2SRC1566419664559634364323514644336557710910554835363646417436354566437

5.2 Intelligent Coverage “Intelligent Coverage” is a coverage driven randomization approach that randomlyselects a hole in the functional coverage and passes it to the stimulus generation process. Using “IntelligentCoverage” allows the stimulus generation to focus on missing coverage and reduces the number of test casesgenerated to approach the ideal of N randomizations to generate N test cases.

Let’s return to the ALU example. The Intelligent Coverage methodology starts by writing functional coverage.We did this in the previous example too. Next preliminary stimulus is generated by randomizing using the func-tional coverage model. In this example, we will replace the uniform randomization with RandInt with a call toRandCovPoint (one of the Intelligent Coverage randomization methods). This is shown below. In this case, Src1and Src2 are used directly in the test, so we are done.

architecture Test3 of tb is shared variable ACov : CovPType ; – Declare begin TestProc : process variable RV :RandomPType ; variable Src1, Src2 : integer ; begin – create coverage model ACov.AddCross( GenBin(0,7), Gen-Bin(0,7) ); – Model while not ACov.IsCovered loop – Done? (Src1, Src2) := ACov.RandCovPoint ; – IntelligentCoverage Randomization

DoAluOp(TRec, Src1, Src2) ; – Transaction ACov.ICover( (Src1, Src2) ) ; – Accumulate end loop ;ACov.WriteBin ; – Report EndStatus(. . . ) ; end process ;

When randomizing across a cross coverage model, the output of RandCovPoint is an integer_vector. Instead ofusing the separate integers, Src1 and Src2, it is also possible to use an integer_vector as shown below.

variable Src : integer_vector(1 to 2) ; . . . Src := ACov.RandCovPoint ; – Intelligent Coverage Randomization

The process is not always this easy. Sometimes the value out of RandCovPoint will need to be further shaped bythe stimulus generation process.

The Intelligent Coverage methodology works now and works with your current testbench approach. You can adoptthis methodology incrementally. Add functional coverage today to make sure you are executing all of your testplan. For the tests that need help, use the Intelligent Coverage.

Intelligent Coverage reduces your work The Intelligent Coverage methodology is different from what is donein a constrained random methodology. Rather than randomizing across holes in the functional coverage, theconstrained random approach adds an equally complex set of randomization constraints to shape the stimulus. Inmany ways, the randomization constraints and functional coverage needed in a constrained random approach areduplicate views of the same information.

With Intelligent coverage, we focus on writing high fidelity coverage models. The constrained random step isreduced to a refinement step and only needs to focus on things that are not already shaped by the coverage. Hence,Intelligent Coverage methodology reduces (or eliminates) the work needed to generate test constraints.

56 Chapter 1. News


Flexibility and Capability

OSVVM implements functional coverage as a data structure within a protected type. Using methods of the pro-tected type allows both a concise capture of the model (as we saw in the previous examples) and a great degree offlexibility and capability.

The added flexibility and capability comes from writing the model incrementally using any sequential code (if,loop). As long as the entire model is captured before we start collecting coverage, we can use as many calls toAddBins or AddCross as needed. As a result, conditionally capturing coverage based on a generic is straightforward. In addition, algorithms that iterate using a loop are no more trouble than writing the code.

Additional flexibility and capability comes from being able to give each bin within a coverage model a differentcoverage goal. A coverage goal specifies the number of times a value from a particular bin needs to be observedbefore it is considered covered. The Intelligent Coverage randomization by default will use these coverage goalsas randomization weights.

To demonstrate this flexibility, let’s consider a contrived example based on the ALU. In this example, each SRC1crossed with any SRC2 has a different coverage goal. In addition, it is an error if SRC1 and SRC2 are equal. Thecoverage goal for each bin is specified in the table below.

Coverage Goal Src1 Src2 2 0 1, 2, 3, 4, 5, 6, 7 3 1 0, 2, 3, 4, 5, 6, 7 4 2 0, 1, 3, 4, 5, 6, 7 5 3 0, 1, 2, 4, 5, 6, 7 5 4 0,1, 2, 3, 5, 6, 7 4 5 0, 1, 2, 3, 4, 6, 7 3 6 0, 1, 2, 3, 4, 5, 7 2 7 0, 1, 2, 3, 4, 5, 6 Illegal Src1 = Src2

To model the above functional coverage, we use a separate call for each different coverage goal. The function,IllegalBin, is used to mark the bins with Src1 = Src2 illegal. This is shown below.

architecture Test4 of tb is shared variable ACov : CovPType ; – Declare Cov Object begin TestProc : processvariable Src1, Src2 : integer ; begin – Capture coverage model ACov.AddCross( 2, GenBin (0), IllegalBin(0) &GenBin(1,7)) ; ACov.AddCross( 3, GenBin (1), GenBin(0) & IllegalBin(1) & GenBin(2,7)) ; ACov.AddCross(4, GenBin (2), GenBin(0,1) & IllegalBin(2) & GenBin(3,7)) ; ACov.AddCross( 5, GenBin (3), GenBin(0,2) &IllegalBin(3) & GenBin(4,7)) ; ACov.AddCross( 5, GenBin (4), GenBin(0,3) & IllegalBin(4) & GenBin(5,7)); ACov.AddCross( 4, GenBin (5), GenBin(0,4) & IllegalBin(5) & GenBin(6,7)) ; ACov.AddCross( 3, GenBin(6), GenBin(0,5) & IllegalBin(6) & GenBin(7)) ; ACov.AddCross( 2, GenBin (7), GenBin(0,6) & IllegalBin(7)) ; while not ACov.IsCovered loop – Done? (Src1, Src2) := ACov.RandCovPoint ; – Randomize with cover-age DoAluOp(TRec, Src1, Src2) ; – Do a transaction ACov.ICover( (Src1, Src2) ) ; – Accumulate end loop ;ACov.WriteBin ; – Report EndStatus(. . . ) ; end process ;

Note that the remainder of this document covers further details of these methods and additional overloading.

Package References and Compilation for CoveragePkg and Friends

Your programs will need to reference CoveragePkg as follows. Setting the CovOptionsType parameters on Write-Bin, WriteCovHoles, and SetReportOptions may require the usage of OsvvmGlobalPkg in some simulators.

library osvvm ;

use osvvm.OsvvmGlobalPkg.all ; – options for WriteBin, SetReportOptions use osvvm.CoveragePkg.all ;

CoveragePkg references the packages NamePkg, MessagePkg, and OsvvmGlobalPkg. We compile NamePkg,MessagePkg, OsvvmGlobalPkg, and CoveragePkg into a library named “osvvm”. Be sure to use the VHDL-2008switch when you compile them.

Declaration of the Coverage Object - CovPType

A coverage model is contained within a CovPType typed shared variable. Using a protected type allows bothaccess to the structure from multiple processes and hides details of the model within the data structure.

The shared variable declaration for the coverage object is commonly put in the architecture of the design as shownbelow.

architecture Test3 of tb is shared variable ACov : CovPType ; – Declare Cov Object begin

1.1. xx.01.2016 - 2016.01 was release. 57


Basic Bin Description

The functions GenBin, IllegalBin, and IgnoreBin are used to create bins of type CovBinType. These bins are usedas inputs to the methods, AddBins and AddCross, that create the coverage data structure. Using these functionsreplaces the need to know the details of type CovBinType.

Basic Type for Coverage Bins The output type of the functions GenBin, IllegalBin, and IgnoreBin is CovBin-Type. It is declared as an array of the record type, CovBinBaseType. This is shown below. Note the details ofCovBinBaseType are not provided as they may change from time to time.

type CovBinBaseType is record . . . end record ; type CovBinType is array (natural range <>) of CovBinBaseType;

Creating Count Bins - GenBin The following are five variations of GenBin. The ones with AtLeast and Weightparameters are mainly intended to for use with constants.

function GenBin(Min, Max, NumBin : integer ) return CovBinType ; function GenBin(Min, Max : integer) returnCovBinType ; function GenBin(A : integer) return CovBinType ;

The version of GenBin shown below has three parameters: min value, max value, and number of bins. The call,GenBin(1, 3, 3), breaks the range 1 to 3 into the 3 separate bins with ranges1 to 1, 2 to 2, 3 to 3.

– min, max, #bins

CovBin1.AddBins(GenBin(1, 3, 3)); – bins 1 to 1, 2 to 2, 3 to 3

If there are less values (between max and min) than bins, then only “max - min + 1” bins will be created. As aresult, the call GenBin(1,3,20), will still create the three bins: 1 to 1, 2 to 2 and 3 to 3.

CovBin2.AddBins( GenBin(1, 3, 20) ) ; – bins 1 to 1, 2 to 2, and 3 to 3

If there are more values (between max and min) than bins and the range does not divide evenly among bins, theneach bin with have on average (max - min + 1)/bins. Later bins will have one more value than earlier bins. Theexact formula used is (number of values remaining)/(number of bins remaining). As a result, the call GenBin(1,14, 4) creates four bins with ranges 1 to 3, 4 to 6, 7 to 10, and 11 to 14.

CovBin2.AddBins( GenBin(1, 14, 4) ) ; – 1 to 3, 4 to 6, 7 to 10, 11 to 14

Since creating one bin per value in the range is common, there is also a version of GenBin that has two parameters:min value and max value which creates one bin per value. As a result, the first call to AddBins/GenBin can beshortened to the following.

– min, max CovBin1.AddBins(GenBin(1, 3)); – bins 1 to 1, 2 to 2, and 3 to 3 GenBin can also be called withone parameter, the one value that is contained in the bin. Hence the call, GenBin(5) creates a single bin withthe range 5 to 5. The following two calls are equivalent. CovBin3.AddBins( GenBin(5) ) ; CovBin3.AddBins(GenBin(5,5,1) ) ; – equivalent call

Creating Illegal and Ignore Bins - IllegalBin and IgnoreBin When creating bins, at times we need to markbins as illegal and flag errors or as ignored actions and not to count them.

The functions IllegalBin and IgnoreBin are used to create illegal and ignore bins. One version of IllegalBin andIgnoreBin has three parameters: min value, max value, and number of bins (just like GenBin).

– min, max, NumBin IllegalBin( 1, 9, 3) – creates 3 illegal bins: 1-3, 4-6, 7-9 IllegalBin( 1, 9, 1) – creates oneillegal bin with range 1-9 IgnoreBin ( 1, 3, 3) – creates 3 ignore bins: 1, 2, 3

There are also two parameter versions of IgnoreBin and IllegalBin that creates a single bin. Some examples ofthis are illustrated below. While this is different from the action of the two parameter GenBin calls, it matches thecommon behavior of creating illegal and ignore bins.

– min, max IllegalBin( 1, 9) – creates one illegal bin with range 1-9 IgnoreBin ( 1, 3) – creates one ignore bin withrange 1-3

58 Chapter 1. News


There are also one parameter versions of IgnoreBin and IllegalBin that creates a single bin with a single value.Some examples of this are illustrated below.

– AVal IllegalBin( 5 ) – creates one illegal bin with range 5-5 IgnoreBin ( 7 ) – creates one ignore bin with range7-7

Predefined Bins - ALL_BIN, . . . , ALL_ILLEGAL, ZERO_BIN, ONE_BIN The following are predefinedbins.

constant ALL_BIN : CovBinType := GenBin(integer’left, integer’right, 1) ; constant ALL_COUNT : CovBin-Type := GenBin(integer’left, integer’right, 1) ; constant ALL_ILLEGAL : CovBinType := IllegalBin(integer’left,integer’right, 1) ; constant ALL_IGNORE : CovBinType := IgnoreBin(integer’left, integer’right, 1) ; constantZERO_BIN : CovBinType := GenBin(0) ; constant ONE_BIN : CovBinType := GenBin(1) ;

Combining Bins Using Concatenation - & Since GenBin, IllegalBin, and IgnoreBin all return CovBinType,their results can be concatenated together. As a result, the following calls to GenBin creates the bins: 1 to 1, 2 to2, 3 to 3, 2 to 127, 128 to 252, 253 to 253, 254 to 254, and 255 to 255.

CovBin1.AddBins(GenBin(0, 2) & GenBin(3, 252, 2) & GenBin(253, 255));

Calls to GenBin, IllegalBin, and IgnoreBin can also be combined. As a result the following creates the fourseparate legal bins (1, 2, 5, and 6), a single ignore bin (3 to 4), and everything else falls into an illegal bin.

CovBin2.AddBins( GenBin(1,2) & IgnoreBin(3,4) & GenBin(5,6) & ALL_ILLEGAL ) ;

Data Structure Construction

The coverage model data structure is created using the methods AddBins and AddCross.

Item (Point) Bins - AddBins The method AddBins is used to add item coverage bins to the coverage datastructure. Each time it is called new bins are appended after any existing bins. AddBins has additional parametersto allow specification of coverage goal (AtLeast) and randomization weight (Weight). By using separate calls toAddBins, each bin can have a different coverage goal and/or randomization weight.

procedure AddBins (CovBin : CovBinType) ;

Cross Coverage Bins - AddCross The method AddCross is used to add cross coverage bins to the coverage datastructure. Each time it is called new bins are appended after any existing bins. AddCross has additional parametersto allow specification of coverage goal (AtLeast) and randomization weight (Weight). By using separate calls toAddCross, each bin can have a different coverage goal and/or randomization weight.

procedure AddCross( Bin1, Bin2 : CovBinType ; Bin3, Bin4, Bin5, Bin6, Bin7, Bin8, Bin9, Bin10, Bin11, Bin12,Bin13, Bin14, Bin15, Bin16, Bin17, Bin18, Bin19, Bin20 : CovBinType := NULL_BIN ) ;

Controlling Reporting for Illegal Bins - SetIllegalMode By default, illegal bins both count and flag a severityerror alert (see AlertLogPkg user guide). This behavior is controlled by the IllegalMode variable. The default valueof the variable is ILLEGAL_ON. Setting IllegalMode to ILLEGAL_OFF, as shown below, suppresses printing ofmessages when an item is added to an illegal bin. Setting IllegalMode to ILLEGAL_FAILURE causes a severityfailure alert to be printed when an item is added to an illegal bin.

type IllegalModeType is (ILLEGAL_ON, ILLEGAL_FAILURE, ILLEGAL_OFF) ; Cov-Bin4.SetIllegalMode(ILLEGAL_OFF) ; – Illegal printing off CovBin4.SetIllegalMode(ILLEGAL_ON) ; –Default: Illegal printing on

1.1. xx.01.2016 - 2016.01 was release. 59


Bin Size Optimization - SetBinSize SetBinSize can help the creation of a coverage model be more efficient bypre-declaring the number of bins to be created in the coverage data structure. Use this for small bins to save spaceor for large bins to suppress the resize and copy that occurs when the bins automatically resize.

procedure SetBinSize (NewNumBins : integer) ;

Accumulating Coverage - ICover

The method ICover is used to accumulate coverage. For item (point) coverage, ICover accepts an integer value.For cross coverage, ICover accepts an integer_vector. The procedure interfaces are shown below. Since thecoverage accumulation is written procedurally, ICover will support either clock based sampling or transactionbased sampling (examples of both shown previously).

procedure ICover( CovPoint : in integer ) ; procedure ICover( CovPoint : in integer_vector ) ;

Since the inputs must be either type integer or integer_vector, conversions must be used. To convert fromstd_logic_vector to integer, numeric_std_unsigned and numeric_std provide the following conversions.

CovBin3.ICover( to_integer(RxData_slv) ) ; – using numeric_std_unsigned (2008) CovBin3.ICover(to_integer(unsigned(RxData_slv)) ) ; – using numeric_std

To convert either std_logic or boolean to integer, CoveragePkg provides overloading for to_integer.

CovBin3.ICover( to_integer(Empty) ) ; – std_logic CovBin3.ICover( to_integer(Empty = ‘1’) ) ; – boolean

To convert either std_logic_vector or boolean_vector to integer_vector (bitwise), CoveragePkg providesto_integer_vector functions.

CrossBin.ICover( to_integer_vector(CtrlReg_slv) ) ; – std_logic_vector CrossBin.ICover(to_integer_vector((Empty=‘1’)&(Rdy=‘1’)) ) ; – boolean_vector

Since the language does not do introspection of aggregate values when determining the type of an expression, theboolean vector expression needs to be constructed using concatenation (as shown above) rather than aggregates(as shown below).

–! CrossBin.ICover( to_integer_vector( ((Empty=‘1’),(Rdy=‘1’)) )); – ambiguous

Basic Randomization

Randomization is handled by either RandCovPoint and RandCovBinVal. The randomization is coverage targetbased. Once a count bin has reached its coverage goal it is no longer selected for randomization. The randomiza-tion results can be modified by using coverage goals, randomization weights, coverage targets, and randomizationthresholds. These topics are discussed later in this document.

Randomly generating a value within a bin - RandCovPoint RandCovPoint returns a randomly selected value(also referred to as a point) within the randomly selected bin. It returns integer_vector values for cross coveragebins, and integer or integer_vector for item (point) bins. The overloading for RandCovPoint is shown below.

impure function RandCovPoint return integer_vector ; impure function RandCovPoint return integer ;

Randomly selecting a coverage bin - RandCovBinVal RandCovBinVal returns a randomly selected bin valueof type RangeArrayType. The type RangeArrayType and the function definitions are shown below. Note RangeAr-rayType may change in the future.

type RangeType is record min, max : integer ; end record ; type RangeArrayType is array (integer range <>) ofRangeType; impure function RandCovBinVal return RangeArrayType ;

60 Chapter 1. News


Randomization, Illegal, and Ignore Bins RandCovPoint and RandCovBinVal will never select a bin markedas illegal or ignore. However, if count bin intersects with a prior specified illegal or ignore bin then the illegalor ignore value may be generated by randomization. Currently care must be taken to avoid this. In revision2013.04, if merging is enabled (see SetMerging) any count bin that is included in a prior illegal or ignore bin willbe dropped.

Coverage Model Statistics

Coverage model statistics collecting methods allow us to check if the model is covered/testing is done (IsCovered),check if the model is initialized (IsInitialized), or check the current total coverage (GetCov).

Model Covered - Testing Done - IsCovered The function IsCovered returns TRUE when all count bins havereached their coverage goal. This indicates that coverage is complete and testing is done. IsCovered is declared asfollows. Just like ICover, IsCovered is called either at a sampling point of either the clock or a transaction.

impure function IsCovered return boolean ; – Uses CovTarget impure function IsCovered ( PercentCov : real )return boolean ;

Model Initialized - IsInitialized The function IsInitialized returns a true when a coverage model has bins (hasbeen initialized). IsInitialized is a useful check when constructing the coverage model in a separate process fromcollecting the coverage.

impure function IsInitialized return boolean ;

Number of Items Randomized - GetItemCount The function GetItemCount returns the number of items thathave been randomized in the coverage model.

impure function GetItemCount return integer ;

Total Coverage Goal - GetTotalCovGoal The function GetTotalCovGoal returns the sum of each bins cov-erage. Coverage models with a simple relationship between the stimulus and the desired coverage will reachcoverage closure in GetTotalCovGoal number of randomizations.

impure function GetTotalCovGoal return integer ; – uses CovTarget impure function GetTotalCovGoal ( Percent-Cov : real ) return integer ;

13.5 Current Percent Coverage - GetCov The function GetCov returns a type real value that indicates thecurrent percent completion (0.0 to 100.0) of the coverage model. It has the following overloading.

impure function GetCov return real ; impure function GetCov (PercentCov : real) return real ;

Reporting Coverage

Coverage results can be written as either all the bins (WriteBin) or just the bins that have not reached their cov-erage goal (WriteCovHoles). By default, these print to the file specified by TranscriptPkg (either TranscriptFile,OUTPUT, or both if mirroring is enabled). There is also an option to use a local file. In addition, one or morelines of heading (SetMessage) may be printed before the results.

Reporting Bin Results - WriteBin The procedure WriteBin prints out the coverage results with one bin printedper line. All count bins are printed. Illegal bins are printed if they have a non-zero count. Ignore bins are notprinted. The weight field of the coverage bin is only printed when the weight is being use (see WeightMode). Itsdeclaration and an example of usage is shown below.

procedure WriteBin ; . . . CovBin1.WriteBin ;

1.1. xx.01.2016 - 2016.01 was release. 61


Reporting Coverage Holes - WriteCovHoles WriteCovHoles prints out count bin results that are below thecoverage goal. Its declaration and an example usage is shown below.

procedure WriteCovHoles ( LogLevel : LogType := ALWAYS ) ; . . . CovBin1.WriteCovHoles ;

When the LogLevel parameter is specified (such as DEBUG) and that Level is not enabled within AlertLogPkg,then the WriteCovHoles will not print. The WriteCovHoles with a LogLevel parameter of “ALWAYS” alwaysprints.

Setting Headings - SetMessage The method SetMessage sets headings for WriteBin and WriteCovHoles. Eachcall to SetMessage creates a separate line in the output of either WriteBin or WriteCovHoles.

procedure SetMessage (NameIn : String ) ; . . . CovBin1.SetMessage(“DMA”) ; – first line of heading Cov-Bin1.SetMessage(“Stat, WordCnt”) ; – second line of heading

If the headings need to be cleared, use the method DeallocateMessage. It is called as follows.

CovBin1.DeallocateMessage ; – clears all headings

If the internal randomization seed has not yet been initialized, the first call to SetMessage will initialize the seedusing the string value.

The method SetItemName is deprecated. It is currently maintained for backward compatibility and it simply callsSetMessage.

If SetMessage is not set, the value in SetName will be used instead.

Setting the Coverage Model Name - SetName The method SetName sets the name of the coverage model.The coverage model name is printed when an illegal bin is encountered and in alerts generated withn a particularcoverage model. Additional calls to SetName will replace the previous value in SetName.

procedure SetName (NameIn : String ) ; impure function SetName (Name : String) return string ; . . . Cov-Bin1.SetName(“DMA Cov”) ;

If the internal randomization seed has not yet been initialized, the first call to SetName will initialize the seedusing the string value.


CovBin1.InitSeed( CovBin1.SetName(“DMA Cov”) ) ;

If SetName is not set, the first word in the first message (SetMessage) will be used instead.

Getting the Coverage Model Name - GetName The method GetName gets the name of the coverage model.

impure function GetName return String ; . . . CovBin1.InitSeed( CovBin1.GetName ) ;

Setting Bin Names Each bin can be named. The bin name is specified as the first parameter to AddBins andAddCross. This means to use names, one must specify each bin individually (bin by bin). The intent behind binnames it to correlate a requirement with a bin name and furthermore associate this with a pass or fail indication ofthe requirement.

procedure AddBins ( Name : String ; CovBin : CovBinType ) ; procedure AddCross( Name : string ; Bin1, Bin2: CovBinType ; Bin3, Bin4, Bin5, Bin6, Bin7, Bin8, Bin9, Bin10, Bin11, Bin12, Bin13, Bin14, Bin15, Bin16,Bin17, Bin18, Bin19, Bin20 : CovBinType := NULL_BIN ) ;

Note that each call to AddBins and AddCross supports a Name as the first parameter.

62 Chapter 1. News


Enabling and Disabling WriteBin fields WriteBin uses the following format when printing. This format is anextension of the original WriteBin format and was added to facilitate integration with requirements tracing tools.

{Prefix} [BinName] [PASSED|FAILED] [BinInfo] [Count]

WriteBin has parameters to control printing of each of these fields. The overloading for WriteBin (without a filestring specified) is:

procedure WriteBin ( – without LogLevel WritePassFail : CovOptionsType := COV_OPT_DEFAULT ; Write-BinInfo : CovOptionsType := COV_OPT_DEFAULT ; WriteCount : CovOptionsType := COV_OPT_DEFAULT; WriteAnyIllegal : CovOptionsType := COV_OPT_DEFAULT ; WritePrefix : string := “” ; PassName : string:= “” ; FailName : string := “” ) ; procedure WriteBin ( – With LogLevel LogLevel : LogType ; WritePassFail :OsvvmOptionsType := COV_OPT_DEFAULT ; WriteBinInfo : OsvvmOptionsType := COV_OPT_DEFAULT; WriteCount : OsvvmOptionsType := COV_OPT_DEFAULT ; WriteAnyIllegal : OsvvmOptionsType :=COV_OPT_DEFAULT ; WritePrefix : string := OSVVM_DEFAULT_STRING_INIT ; PassName : string :=OSVVM_DEFAULT_STRING_INIT ; FailName : string := OSVVM_DEFAULT_STRING_INIT ) ;


The type CovOptionsType is used to specify values for many of these parameters. It is defined as follows.

type CovOptionsType is (COV_OPT_DEFAULT, DISABLED, ENABLED) ;

The default values for parameters to Write bins is initially as shown in the table below. The reason they arenot specified directly on the WriteBin interface is that they are [local/global] settings that can be changed by theprocedure set SetReportOptions. For details, see next section.

WritePassFail DISABLED WriteBinInfo ENABLED WriteCount ENABLED WriteAnyIllegal DISABLEDWritePrefix “%% ” PassName “PASSED” FailName “FAILED”

When all parameters are enabled, the report will print with the following format.

%% State0 PASSED Bin:(0) Count = 1 AtLeast = 1 %% State1 PASSED Bin:(1) Count = 1 AtLeast = 1 %%State2 FAILED Bin:(2) Count = 0 AtLeast = 1 %% State3 FAILED Bin:(3) Count = 0 AtLeast = 1

The “%% ” is the default prefix. It can be changed by specifying a value for WritePrefix. The “State0”, “State1”,. . . are the names of the bins and if present always print. Next is the PassFail message. It will print “PASSED” ifthe count is greater than or equal to the goal (AtLeast value), otherwise, it prints “FAILED”. The PassFail messageis enabled using the WritePassFail field. The value printed when it passes or fails is controlled by the PassNameand FailName fields. Printing of bin information is redundant when a bin is named. This information can bedisabled suing the WriteBinInfo field. Printing of the Count (current coverage) and AtLeast (coverage goal) canbe disabled with the WriteCount field. Nominally illegal bins are only printed when the have failed (somethinglanded in that bin). The parameter, WriteAnyIllegal, can be used to enable printing of all illegal bins (includingthe ones with no values and hence pass).

Setting Defaults for WriteBin fields: SetReportOptions The procedure SetReportOptions sets defaults forthe WriteBin options for a single coverage model. To set report options for all coverage models, see Osvvm-GlobalPkg. SetOsvvmGlobalOptions. The interface for SetReportOptions is as follows. procedure SetReportOp-tions ( WritePassFail : CovOptionsType := COV_OPT_INIT_PARM_DETECT ; WriteBinInfo : CovOptionsType:= COV_OPT_INIT_PARM_DETECT ; WriteCount : CovOptionsType := COV_OPT_INIT_PARM_DETECT; WriteAnyIllegal : CovOptionsType := COV_OPT_INIT_PARM_DETECT ; WritePrefix : string :=OSVVM_STRING_INIT_PARM_DETECT ; PassName : string := OSVVM_STRING_INIT_PARM_DETECT;

FailName : string := OSVVM_STRING_INIT_PARM_DETECT ) ;


Using Files - FileOpenWriteBin, WriteBin, and WriteCovHoles Since a file parameter cannot be used withWriteBin and WriteCovHoles, either a file must be opened within the coverage model or an awkward set of stringand File_Open_Kind parameters must be used.

1.1. xx.01.2016 - 2016.01 was release. 63


If every WriteBin or WriteCovHoles writes to the same file, then FileOpenWriteBin can be use to open a fileinternal to the coverage model. The declaration of FileOpenWriteBin is shown below. When a file is open andWriteBin or WriteCovHoles is called without a file specification, then the opened file is used rather than OUTPUT.

procedure FileOpenWriteBin (FileName : string; OpenKind : File_Open_Kind ) ;

There is also a corresponding FileCloseWriteBin.

procedure FileCloseWriteBin ;

If several different files are used with WriteBin or WriteCovHoles, then the file name and open kind can bespecified as a parameters. The overloading for WriteBin is as follows.

procedure WriteBin ( – Without LogLevel FileName : string; OpenKind : File_Open_Kind := AP-PEND_MODE ; WritePassFail : CovOptionsType := COV_OPT_DEFAULT ; WriteBinInfo : CovOptionsType:= COV_OPT_DEFAULT ; WriteCount : CovOptionsType := COV_OPT_DEFAULT ; WriteAnyIllegal : Cov-OptionsType := COV_OPT_DEFAULT ; WritePrefix : string := “” ; PassName : string := “” ; FailName :string := “” ) ; procedure WriteBin ( – With LogLevel LogLevel : LogType ; FileName : string; OpenKind: File_Open_Kind := APPEND_MODE ; WritePassFail : OsvvmOptionsType := COV_OPT_DEFAULT; WriteBinInfo : OsvvmOptionsType := COV_OPT_DEFAULT ; WriteCount : OsvvmOptionsType :=COV_OPT_DEFAULT ; WriteAnyIllegal : OsvvmOptionsType := COV_OPT_DEFAULT ; WritePrefix : string:= OSVVM_DEFAULT_STRING_INIT ; PassName : string := OSVVM_DEFAULT_STRING_INIT ; FailName: string := OSVVM_DEFAULT_STRING_INIT ) ;


The overloading for WriteCovHoles is as follows.

procedure WriteCovHoles ( FileName : string; OpenKind : File_Open_Kind := APPEND_MODE ) ; procedureWriteCovHoles ( LogLevel : LogType ; FileName : string; OpenKind : File_Open_Kind := APPEND_MODE ) ;

When a LogLevel parameter is specified (such as DEBUG) and that Level is not enabled within AlertLogPkg,then the WriteCovHoles will not print. The WriteCovHoles without the LogLevel parameter always prints.

Note, WRITE_MODE initializes and opens a file, so make sure to only use it on the first write to the file. For allsubsequent writes to the same file use APPEND_MODE (hence it is the default). The following shows a call toWriteBin followed by a call to WriteCovHoles.

– FileName, OpenKind CovBin1.WriteBin (“Test1.txt”, WRITE_MODE); CovBin1.WriteCovHoles (“Test1.txt”,APPEND_MODE);

Coverage Goals and Randomization Weights

Coverage goals and randomization weights are an important part of the Intelligent Coverage methodology. Acoverage goal specifies how many times a value must land in a bin before the bin is considered covered. Arandomization weight determines the relative number of times a bin will be selected in randomization. In VHDL,each bin within a coverage model may have a different coverage goal and randomization weight.

Up to this point, every coverage bin has a coverage goal of 1 and that value has been used as the randomizationweight. However, some tests require coverage goal of other than one and some tests require a randomizationweight that is different from the coverage goal. This section addresses how to set coverage goals and randomizationweights using overloaded methods and functions in CoveragePkg.

Specifying Coverage Goals - AddBins, AddCross, and GenBin A coverage goal can be set by using theAtLeast parameter of AddBins or AddCross. By default this coverage goal will also be used as the randomizationweight. The declaration for these is shown below.

procedure AddBins (AtLeast : integer ; CovBin : CovBinType) ; procedure AddCross( AtLeast : integer ; Bin1,Bin2 : CovBinType ; Bin3, Bin4, Bin5, Bin6, Bin7, Bin8, Bin9, Bin10, Bin11, Bin12, Bin13,

Bin14, Bin15, Bin16, Bin17, Bin18, Bin19, Bin20 : CovBinType := NULL_BIN ) ;

The GenBin function also has an AtLeast parameter. Its declaration is shown below.

64 Chapter 1. News


function GenBin(AtLeast, Min, Max, NumBin : integer ) return CovBinType ;

If a bin is an ignore or illegal bin, then the coverage goal is set to 0. If a bin is a count bin and a coverage goal isspecified in more than one place, then the largest specified value is used. If a bin is a count bin and no coveragegoal is specified then the coverage goal is set to 1.

Selecting Randomization Weights - SetWeightMode By default, a coverage goal is used as the randomizationweight. The coverage weight can also be set to use either a bin weight or remaining coverage as the randomizationweight.

Selection of the randomization weight is done using SetWeightMode. The following table lists the current set ofsupported modes and how the randomization weight is calculated.

Mode Weight AT_LEAST AtLeast WEIGHT Bin Weight REMAIN AtLeast - Count *

• Note AtLeast is adjusted if the coverage target /= 100 %

The interface for procedure SetWeightMode is shown below.

type WeightModeType is (AT_LEAST, WEIGHT, REMAIN) ; procedure SetWeightMode (A : WeightModeType);

Note that there are additional undocumented features on SetWeightMode and WeightModeType. Use these at yourown risk as they are subject to change in each revision. Their names and implementation were changed in revision2013.04. If there is one that you have tried that is working better than documented options, please let me know.

Specifying Bin Weight - AddBins, AddCross, and GenBin A bin’s weight is used as the randomization weightwhen the WeightMode WEIGHT is selected by SetWeightMode. A bin’s weight can be set by using the Weightparameter of AddBins or AddCross. If not specified, a bin’s weight value will be 1. The declaration for these isshown below. Note this use of the Weight parameter also requires a coverage goal to be specified.

procedure AddBins (AtLeast, Weight : integer ; CovBin : CovBinType) ; procedure AddCross( AtLeast : integer; Weight : integer ; Bin1, Bin2 : CovBinType ; Bin3, Bin4, Bin5, Bin6, Bin7, Bin8, Bin9, Bin10, Bin11, Bin12,Bin13, Bin14, Bin15, Bin16, Bin17, Bin18, Bin19, Bin20 : CovBinType := NULL_BIN ) ;

The GenBin function also has an Weight parameter. Its declaration is shown below.

function GenBin(AtLeast, Weight, Min, Max, NumBin : in integer) return CovBinType ;

If a bin is an ignore or illegal bin, then the bin weight is set to 0. If a bin is a count bin and a bin weight is specifiedin more place, then the largest specified value is used. If a bin is a count bin and no bin weight is specified thenthe coverage goal is set to 1. Likewise for the coverage goal.

Coverage Targets

For some tests, the AtLeast parameters will be used to set an initial coverage distribution. Later it may be desirableto use the same coverage distribution, but run it for much longer. Use of a coverage target allows the coveragegoal to be scaled (increased or decreased) without having to change anything else in the coverage model. Hence,the effective coverage goal for a bin is the product of bin’s AtLeast least value and the coverage model’s coveragetarget value (specifically, AtLeast * CovTarget / 100.0).

Setting a Coverage Target - SetCovTarget The method SetCovTarget sets the coverage model’s coverage target(internally the CovTarget variable).

procedure SetCovTarget (Percent : real) ;

The coverage target is intended to scale the run time of a test without having to change a bin’s AtLeast values.CovTarget is set to 100.0 initially. Setting the coverage target to 1000.0 will increase the run time 10X. Setting thecoverage target to 50.0 will decrease the run time by 2X.

The versions of the following methods that do not have a PercentCov parameter use the CovTarget value: Rand-CovPoint, RandCovBinVal, IsCovered, and WriteCovHoles.

1.1. xx.01.2016 - 2016.01 was release. 65


Overriding the Global Coverage Target - PercentCov The methods that use CovTarget also have a versionwith a PercentCov parameter that overrides the CovTarget value. The following methods have a PercentCovparameter.

impure function RandCovPoint (PercentCov : real) return integer_vector ; impure function RandCovPoint (Per-centCov : real) return integer ; impure function RandCovBinVal (PercentCov : real) return RangeArrayType ;impure function IsCovered (PercentCov : real) return boolean ; procedure WriteCovHoles ( PercentCov : real ); procedure WriteCovHoles ( LogLevel : LogType ; PercentCov : real ) ; procedure WriteCovHoles ( FileName: string; PercentCov : real ; OpenKind : File_Open_Kind := APPEND_MODE ) ; procedure WriteCovHoles (LogLevel : LogType ; FileName : string; PercentCov : real ; OpenKind : File_Open_Kind := APPEND_MODE );

Randomization Thresholds - SetThresholding and SetCovThreshold

Ordinarily randomization (using RandCovPoint or RandCovBinVal) can select any bin whose coverage targethas not been reached. Thresholding modifies this by also excluding bins whose coverage exceeds the minimumcoverage plus the threshold value (MinCov + threshold). Thresholding is intended to balance how a test convergesto coverage closure. Thresholding only has meaning when coverage goals (AtLeast * CovTarget/100.0) are greaterthan 1.

The threshold value is set using SetCovThreshold. Thresholding is enabled by either SetCovThreshold or Set-Thresholding.

procedure SetThresholding (A : boolean := TRUE ) ; procedure SetCovThreshold (Percent : real) ;

By setting a coverage threshold of 0.0, the notion of cyclic randomization is extended to work across a coveragemodel.

Handling Overlapping Bins

LastIndex - Count bins overlapping with other counts When RandCovPoint or RandCovBinVal is called, thebin index that generates it is logged in the LastIndex variable. When ICover is called, it searches for the value inthe bin whose index is currently stored in the LastIndex variable. This way if bins overlap, it insures that the binthat generated the value is the bin whose count value is incremented.

Bin Merging

Count Bins Contained in an Illegal or Ignore Bin Bin merging is an experimental feature that drops a countbin if it is contained in a previously defined ignore or illegal bin. Merging is off by default and can be enabled ordisabled with the SetMerging procedure shown below.

procedure SetMerging (A : boolean := TRUE ) ;

Currently bin merging also merges count bins when they have identical bin values. Merging of count bins isexpensive. Since this feature is correctly handled by LastIndex, it may be removed in the future. If you need countbins to be merged, please contact the package author.

Count Bins Overlapping with an Illegal or Ignore Bin Count bins overlapping with a previous ignore orillegal bin are problematic. When the count bin is selected for randomization, it may generate an illegal value dueto the overlap.

This may be addressed in a future version. For now it is up to the user understand overlap and to avoid this.

Multiple Matches with ICover - SetCountMode By default, ICover searches for the point in the bin pointedto by LastIndex. If not found there, it searches the bins in order. This mode should satisfy most use models.

66 Chapter 1. News


SetCountMode is an experimental feature that can be used to change the default behavior. SetCountMode sets theinternal CountMode variable. The default mode, described above, is COUNT_FIRST. If the CountMode is set toCOUNT_ALL, each matching bin is counted. The following shows how to set the CountMode.

type CountModeType is (COUNT_FIRST, COUNT_ALL) ; CovBin4.SetCountMode(COUNT_ALL) ; – Countall matching bins CovBin4.SetCountMode(COUNT_FIRST) ; – default. Only count first matching bin

Attention: This experimental feature may be removed from future versions if it impacts run time. If you haveneed for COUNT_ALL, please contact the package author.

Initializing the Seeds - InitSeed, SetSeed, and GetSeed

Intelligent coverage uses pseudo random number generation as its basis. As such, for a given randomization seedvalue it will generate the same sequence of numbers every time a simulation is run. This is important as it meansthat when a bug is found and fixed, the fix can be validated since the same test sequence that caused the bug willbe generated.

On the other hand, it also means that if a design has two identical interfaces and the testbench uses the twoidentical coverage models to generate tests that they will both see the same test sequence. This is not desirablesince it is unlikely to generate interesting interactions between the two interfaces. As a result, it is desirable thateach coverage model is given a different initial seed value. This is simple to do.

The InitSeed method initializes a coverage model’s internal randomization seed. The following example showsthe method overloading and an example call. One easy way to generate a unique seed value for each coverage binis to use the string value generated by ‘path_name applied to the coverage object as shown. Note that the methodSetMessage will also call InitSeed with its parameter if the seed is not already set.

procedure InitSeed (S : string ) ; impure function InitSeed (S : string ) return string ; procedure InitSeed (I : integer) ; . . . CovBin1.InitSeed( CovBin1’path_name ) ; – string


CovBin1.SetName ( CovBin1.InitSeed (“DMA Cov”) ) ;

The methods GetSeed and SetSeed are intended for saving and restoring the seeds. In this case the seed valueis of type RandomSeedType, which is defined in RandomBasePkg. RandomBasePkg also defines procedures forreading and writing RandomSeedType values (see RandomPkg Users Guide for details).

procedure SetSeed (RandomSeedIn : RandomSeedType ) ; impure function GetSeed return RandomSeedType ;

Note that the time it takes to achieve coverage closure with open loop randomization methods, such as Sys-temVerilog’s constrained random, may depend heavily on the initial seed value. Hence, within the SystemVerilogcommunity some may try out different seeds when running simulations just to see if they can improve run times.This is not necessary with OSVVM’s Intelligent Coverage methodology since it only selects from coverage holes.

Using an AlertLogID

Alerts signaled by CoveragePkg use the internal AlertLogIDVar. By default the value isOSVVM_ALERT_LOG_ID. It can be set to something different by SetAlertLogID.

SetAlertLogID SetAlertLogID sets the internal AlertLogIDVar. There are two forms of SetAlertLogID. Thefirst form is intended to be used when an AlertLogID is shared with other items in the testbench. It is defined asfollows.

procedure SetAlertLogID (A : AlertLogIDType) ;

The second form is intended to create an AlertLogID that is exclusive to the coverage model. It is defined asfollows.

1.1. xx.01.2016 - 2016.01 was release. 67


procedure SetAlertLogID( Name : string ; ParentID : AlertLogIDType := ALERTLOG_BASE_ID ; CreateHier-archy : Boolean := TRUE ) ;

GetAlertLogID GetAlertLogID returns the current AlertLogID used to report alerts.

impure function GetAlertLogID return AlertLogIDType ;

Interacting with the Coverage Data Structure

Basic Bin Information impure function GetNumBins return integer ; impure function GetMinIndex return in-teger ; impure function GetMinCov return real ; impure function GetMinCount return integer ; impure functionGetMaxIndex return integer ; impure function GetMaxCov return real ; impure function GetMaxCount returninteger ; impure function GetErrorCount return integer ;

The function GetNumBins returns the number of bins in the coverage model. Bin values are numbered from 1 toNumBins.

The functions GetMinIndex and GetMaxIndex return the index of the first bin with the minimum and maximumpercent coverage of a bin. The functions GetMinCov and GetMaxCov return the minimum and maximum percentcoverage of a bin. The functions GetMinCount and GetMaxCount return the minimum and maximum count in abin.

The function GetErrorCount sums up the count in each of the error bins and returns the resulting value. GenerallyGetErrorCount is called at the end of a testbench for coverage models that have bins marked as illegal.

TestErrCount := CovBin1.GetErrorCount + (Other_Error_Sources) ;

Getting Coverage Point Values In addition to RandCovPoint, there are also the following that return coveragevalue that is within a particular coverage bin. Integer return values are for bins with a single item. Integer_vectorare for single item or cross coverage bins.

impure function GetPoint ( BinIndex : integer ) return integer ; impure function GetPoint ( BinIndex : integer) return integer_vector ; impure function GetMinPoint return integer ; impure function GetMinPoint return inte-ger_vector ; impure function GetMaxPoint return integer ; impure function GetMaxPoint return integer_vector;

The function GetPoint returns a random point within the addressed bin (BinIndex). The functions GetMinPointand GetMaxPoint return a random point within the first bin with minimum and maximum percent coverage.

Getting Coverage Bin Values In addition to RandCovBinVal, there are also the following that return coveragebin value. The return value has type RangeArrayType.

impure function GetBinVal ( BinIndex : integer ) return RangeArrayType ; impure function GetMinBinVal returnRangeArrayType ; impure function GetMaxBinVal return RangeArrayType ;

The function GetBinVal returns the bin value of the addressed bin (BinIndex). The functions GetMinBinVal andGetMaxBinVal return the bin value of the first bin with minimum and maximum percent coverage.

Getting Last Randomization Information The method GetLastIndex returns the index value the bin last se-lected for randomization. The method GetLastBinVal returns the bin value of the bin indexed by LastIndex. Theoverloading is as follows.

impure function GetLastIndex return integer ; impure function GetLastBinVal return RangeArrayType ;

Getting Coverage Holes The following functions return information about coverage holes.

impure function CountCovHoles return integer ; impure function CountCovHoles (PercentCov : real) return inte-ger ;

68 Chapter 1. News


impure function GetHoleBinVal(ReqHoleNum : integer := 1) return RangeArrayType ; impure function GetH-oleBinVal(PercentCov : real) return RangeArrayType ; impure function GetHoleBinVal(ReqHoleNum : integer ;PercentCov : real) return RangeArrayType ;

The function CountCovHoles returns the number of holes that are below the PercentCov parameter. CountCov-Holes without a PercentCov parameter returns the number of holes that are below the CovTarget value.

– PercentCov NumHoles := CovBin1.CountCovHoles( 100.0 ) ;

GetHoleBinVal gets the ReqHoleNum bin with a coverage value less than the PercentCov value. The followingcall to GetHoleBinVal gets the 5th bin that has less than 100% coverage. Note that ReqHoleNum must be between1 and CountCovHoles. GetHoleBinVal without a PercentCov parameter uses CovTarget in its place.

– ReqHoleNum, PercentCov TestData := CovBin1.GetHoleBinVal( 5, 100.0 ) ;

Coverage Database Operations

A coverage model can be written and read using WriteCovDb and ReadCovDb. Using these allows results tobe accumulated across multiple tests, and hence, things like test configurations can be covered and randomized.The method declarations are shown below. Like WriteBin file parameters cannot be used, so WriteCovDb andReadCovDb use parameters that specify the file name as a string and the file open mode.

procedure WriteCovDb (FileName : in string; OpenKind : File_Open_Kind := WRITE_MODE ) ; procedureReadCovDb (FileName : string ; Merge : boolean := FALSE) ;

WriteCovDb saves the coverage model and internal variables into a file. The following shows a call to Write-CovDb. Generally WriteCovDb is called once per test. As a result, WRITE_MODE is the default.

– FileName, OpenKind CovBin1.WriteCovDb( “CovDb.txt”, WRITE_MODE ) ;

The procedure method ReadCovDb reads the coverage model and internal variables from a file. If the optionalMerge parameter is set to TRUE, the values read will be merged with the current coverage model. The followingshows a call to ReadCovDb.

– FileName CovBin1.ReadCovDb( “CovDb.txt”, TRUE );

Bin Clearing and Deconstruction

The procedure SetCovZero sets all the coverage counts in a coverage bin to zero. This allows the counts to be setto zero after reading in a coverage database. A simple call to it is shown below.

CovBin1.SetCovZero ; – set all counts to 0

The procedure Deallocate deallocates the entire database structure and sets the internal variables back to theirdefaults.

CovBin1.Deallocate ;

Creating Bin Constants

Constants are used for two purposes. The first is to create a short hand name for an item (point) bin (normalconstant stuff) and then use that name later in composing the coverage model. The second is to create the entirecoverage model in the constant to facilitate reuse of the model.

Item (Point) Bin Constants - CovBinType In a previous model, we constructed a cross coverage model usingthe following call to AddCross.

ACov.AddCross( GenBin(0,7), GenBin(0,7) ); – Model

One step of refinement is to create an item bin constant for the register addresses, such as REG_ADDR shownbelow. The type of REG_ADDR is CovBinType. Since constants can extract their range based on the objectassigned to them, it is easiest to leave CovBinType unconstrained.

1.1. xx.01.2016 - 2016.01 was release. 69


constant REG_ADDR : CovBinType := GenBin(0, 7) ;

Once created the constant can be used in for further composition, such as shown below. Just like normal constants,this increases both the readability and maintainability of the code.

ACov.AddCross(REG_ADDR, REG_ADDR); – Model

Since each element in an item bin may require different coverage goals or weights, additional overloading ofGenBin were added. These are shown below.

function GenBin(AtLeast, Weight, Min, Max, NumBin : integer ) return CovBinType ; function GenBin(AtLeast,Min, Max, NumBin : integer ) return CovBinType ;

As demonstrated earlier, item bins can be composed using concatenation. The following example creates twobins: 0 to 31 with coverage goal of 5, and 32 to 63 with coverage goal of 10.

constant A_BIN : CovBinType := GenBin(5, 0, 31, 1) & GenBin(10, 32, 63, 1) ;

Writing an Cross Coverage Model as a Constant - CovMatrix?Type To capture a cross coverage model in aconstant requires some additional types and functions. The following methodology is based the language prior toVHDL-2008 and requires a separate type definition for each size of cross coverage model. Currently up to a crossproduct of 9 separate items are supported by the following type. In VHDL-2008 where composites are allowedto have unconstrained elements, this will be reduced to a single type (and cross products of greater than 9 can beeasily supported).

type CovMatrix2Type is array (natural range <>) of CovMatrix2BaseType; type CovMatrix3Type is array (naturalrange <>) of CovMatrix3BaseType; type CovMatrix4Type is array (natural range <>) of CovMatrix4BaseType;type CovMatrix5Type is array (natural range <>) of CovMatrix5BaseType; type CovMatrix6Type is array (naturalrange <>) of CovMatrix6BaseType; type CovMatrix7Type is array (natural range <>) of CovMatrix7BaseType;type CovMatrix8Type is array (natural range <>) of CovMatrix8BaseType; type CovMatrix9Type is array (naturalrange <>) of CovMatrix9BaseType;

The function GenCross is used to generate these cross products. We need a separate overloaded function for eachof these types. The interface that generates CovMatrix2Type and CovMatrix9Type are shown below.

function GenCross( – cross 2 item bins - see method AddCross constant AtLeast : integer ; constant Weight :integer ; constant Bin1, Bin2 : in CovBinType ) return CovMatrix2Type ; function GenCross(AtLeast : integer ;Bin1, Bin2 : CovBinType) return CovMatrix2Type ; function GenCross(Bin1, Bin2 : CovBinType) return Cov-Matrix2Type ; function GenCross( – cross 9 item bins - intended only for constants constant AtLeast : integer; constant Weight : integer ; constant Bin1, Bin2, Bin3, Bin4, Bin5, Bin6, Bin7, Bin8, Bin9 : in CovBinType )return CovMatrix9Type ; function GenCross( AtLeast : integer ; Bin1, Bin2, Bin3, Bin4, Bin5, Bin6, Bin7, Bin8,Bin9 : CovBinType ) return CovMatrix9Type ; function GenCross( Bin1, Bin2, Bin3, Bin4, Bin5, Bin6, Bin7,Bin8, Bin9 : CovBinType ) return CovMatrix9Type ;

Now we can write our constant for our simple ALU coverage model.

constant ALU_COV_MODEL : CovMatrix2Type := GenCross(REG_ADDR, REG_ADDR);

When we want to add this to our coverage data structure, we need methods that handle types CovMatrix2Typethrough CovMatrix9Type. This is handled by the overloaded versions of AddCross shown below.

procedure AddCross (CovBin : CovMatrix2Type) ; procedure AddCross (CovBin : CovMatrix3Type) ;

procedure AddCross (CovBin : CovMatrix4Type) ; procedure AddCross (CovBin : CovMatrix5Type) ; procedureAddCross (CovBin : CovMatrix6Type) ; procedure AddCross (CovBin : CovMatrix7Type) ; procedure AddCross(CovBin : CovMatrix8Type) ; procedure AddCross (CovBin : CovMatrix9Type) ;

To create the coverage data structure for the simple ALU coverage model, call AddCross as shown below.

ACov.AddCross ( ALU_COV_MODEL ); – Model

This capability is here mostly due to evolution of the package. Keep in mind, the intent is to create readable andperhaps reusable coverage models.

GenCross also allows specification of weights. In a similar manner to AddCross, we can build up our coveragemodel incrementally using constants and concatenation. This is shown in the following example.

70 Chapter 1. News


architecture Test4 of tb is shared variable ACov : CovPType ; – Declare Cov Object constant ALU_BIN_CONST: CovMatrix2Type := GenCross(1, GenBin (0), GenBin(1,7)) & GenCross(2, GenBin (1), GenBin(0) & Gen-Bin(2,7)) & GenCross(3, GenBin (2), GenBin(0,1) & GenBin(3,7)) & GenCross(4, GenBin (3), GenBin(0,2) &GenBin(4,7)) & GenCross(5, GenBin (4), GenBin(0,3) & GenBin(5,7)) & GenCross(6, GenBin (5), GenBin(0,4)& GenBin(6,7)) & GenCross(7, GenBin (6), GenBin(0,5) & GenBin(7)) & GenCross(8, GenBin (7), GenBin(0,6)) ; begin TestProc : process variable RegIn1, RegIn2 : integer ; begin – Capture coverage model ACov. AddCross( ALU_BIN_CONST ) ; while not ACov.IsCovered loop – Interact – Randomize register addresses – see Ran-domPkg documentation (RegIn1, RegIn2) := ACov.RandCovPoint ; DoAluOp(TRec, RegIn1, RegIn2) ; – Do atransaction ACov.ICover( (RegIn1, RegIn2) ) ; – Accumulate end loop ; ACov.WriteBin ; – Report EndStatus(. .. ) ; end process ;

Reuse of Coverage

There are a couple of ways to reuse a coverage model. If the intent is to reuse and accumulate coverage acrosstests, then the only way to accomplish this is to use WriteCovDb and ReadCovDb. If the intent is to just reusethe coverage model itself, then either a constant or a subprogram can be used. The calls to ICover generally aresimple enough that we do not try to abstract them.

CoveragePkg vs. Language Syntax

The basic level of item (point) coverage that can be captured with CoveragePkg is similar to when can be capturedwith IEEE 1647, ‘e’. CoveragePkg and ‘e’ allow an item bin to consist of either a single value or a single range.SystemVerilog extends this to allow a value, a range, or a collection of values and ranges. While this additionalcapability of SystemVerilog is interesting, it did not seem to offer any compelling advantage that would justify theadditional complexity required to specify it to the coverage model.

For cross coverage, both SystemVerilog and ‘e’ focus on first capturing item coverage and then doing a cross ofthe items. There is some capability to modify the bins contents within the cross, but at best it is awkward. On theother hand, CoveragePkg allows one to directly capture cross coverage, bin by bin and incrementally if necessary.Helper functions are provided to simplify the process. This means for simple things, such as making sure everyregister pair of an ALU is used, the coverage is captured in a very concise syntax, however, when more complexthings need to be done, such as modeling the coverage for a CPU, the cross coverage can be captured on a line byline basis.

As a result, with CoveragePkg it is easier to capture high fidelity coverage within a single coverage object. A highfidelity coverage model in a single coverage object is required to do Intelligent Coverage.

Deprecated Methods

In the original design of the coverage feedback and randomization functions, there was no coverage goal or weight.Instead, each bin has a weight of 1 and the coverage goal is determined by the AtLeast parameter in the functioncalls. These functions are shown below. In this implementation, all bins had the same coverage goal. Usage ofthe AtLeast parameter has been subsumed by the real valued PercentCov parameter. In addition, each bin nowhas the capability to have a different coverage goal and weight. With different coverage goal values, PercentCovhas replaced the AtLeast parameter. The functionality of the AtLeast parameter has been subsumed by has beensubsumed by the PercentCov parameter. A PercentCov parameter of 200.0 is equivalent to an AtLeast parameterof 2.

impure function GetMinCov return integer ; impure function GetMaxCov return integer ; impure function Count-CovHoles ( AtLeast : integer ) return integer ; impure function IsCovered ( AtLeast : integer ) return boolean; impure function GetHoleBinVal ( ReqHoleNum : integer := 1 ; AtLeast : integer ) return RangeArrayType ;impure function RandCovBinVal ( AtLeast : in integer ) return RangeArrayType ; impure function RandCov-Point (AtLeast : in integer ) return integer_vector ; procedure WriteCovHoles ( AtLeast : in integer ) ; procedureWriteCovHoles ( FileName : string; AtLeast : in integer ; OpenKind : File_Open_Kind := APPEND_MODE ) ;

1.1. xx.01.2016 - 2016.01 was release. 71


Future Work

CoveragePkg.vhd is a work in progress and will be updated from time to time.

Some of the plans for the next revision are:

• Revise bin merging. It is still an experimental feature and is off by default.

• Remove OrderCount (was for development purposes only).

If you have ideas that you would like to see, please contact me at [email protected].

Other Packages - RandomPkg

CoveragePkg is part of the Open Source VHDL Verification Methodology (OSVVM) packages. In addition to theCoveragePkg, our randomization packages (RandomPkg, RandomBasePkg, SortListPkg_int) are in OSVVM. Themost current versions are always available at http://www.SynthWorks.com/downloads. Over time we will also bereleasing other packages. With time, we hope simulation vendors will distribute the OSVVM libraries with theirtools.

About CoveragePkg

CoveragePkg was developed and is maintained by Jim Lewis of SynthWorks VHDL Training. It evolvedfrom methodology and packages developed for SynthWorks’ VHDL Testbenches and verification class. Itis part of the Open Source VHDL Verification Methodology (OSVVM), which brings leading edge verifica-tion techniques to the VHDL community. Please support our effort in supporting CoveragePkg and OSVVMby purchasing your VHDL training from SynthWorks. CoveragePkg is released under the Perl Artistic opensource license. It is free (both to download and use - there are no license fees). You can download it fromhttp://www.synthworks.com/downloads. It will be updated from time to time. Currently there are numerousplanned revisions. If you add features to the package, please donate them back under the same license as can-didates to be added to the standard version of the package. If you need features, be sure to contact us. I blogabout the packages at http://www.synthworks.com/blog. We also support a user community and blogs throughhttp://www.osvvm.org. Release notes are in the document OSVVM_release_notes.pdf.

References

MemoryPkg User Guide

1 MemoryPkg Overview The AlertLogPkg provides a protected type and methods to simplify the creation ofdata structures required to model larger memories. 2 Simple Mode: Global Alert Counter By default, there isa single global alert counter. All designs that use alert or log need to reference the package AlertLogPkg. useosvvm.AlertLogPkg.all ; architecture Test1 of tb is Use Alert to flag an error, AlertIf to flag an error when a con-dition is true, or AlertIfNot to flag an error when a condition is false (similar to assert). Alerts can be of severityFAILURE, ERROR, or WARNING. – message, level When others => Alert(“Illegal State”, FAILURE) ; . . . –condition, message, level AlertIf(ActualData /= ExpectedData, “Data Miscompare . . . ”, ERROR) ; . . . read(Buf,A, ReadValid) ; – condition, message, level AlertIfNot( ReadValid, “read of A failed”, FAILURE) ; The outputfor an alert is as follows. Alert adds the time at which the log occurred. %% Alert ERROR Data Miscompare. . . at 20160 ns When a test completes, use ReportAlerts to provide a summary of errors. ReportAlerts ; Whena test passes, the following message is generated: %% DONE PASSED t1_basic at 120180 ns When a test fails,the following message is generated (on a single line): %% DONE FAILED t1_basic Total Error(s) = 2 Failures: 0Errors: 1 Warnings: 1 at 120180 ns Similar to assert, by default, when an alert FAILURE is signaled, a test failedmessage (see ReportAlerts) is produced and the simulation is stopped. This action is controlled by a stop count.The following call to SetAlertStopCount, causes a simulation to stop after 20 ERROR level alerts are received.SetAlertStopCount(ERROR, 20) ; Copyright © 2015 - 2016 by SynthWorks Design Inc. All rights reserved. 4Verbatim copies of this document may be used and distributed without restriction. Alerts can be enabled by a gen-eral enable, SetGlobalAlertEnable (disables all alert handling) or an enable for each alert level, SetAlertEnable.The following call to SetAlertEnable disables WARNING level alerts. SetGlobalAlertEnable(TRUE) ; – Default

72 Chapter 1. News

mailto:[email protected]






SetAlertEnable(WARNING, FALSE) ; Logs are used for verbosity control. Log level values are ALWAYS, DE-BUG, FINAL, and INFO. Log (“A message”, DEBUG) ; Log formats the output as follows. %% Log DEBUGA Message at 15110 ns Each log level is independently enabled or disabled. This allows the testbench to supportdebug or final report messages and only enable them during the appropriate simulation run. The log ALWAYS isalways enabled, all other logs are disabled by default. The following call to SetLogEnable enables DEBUG levellogs. SetLogEnable(DEBUG, TRUE) ; 3 Method Reference 3.1 Package References Using MemoryPkg requiresthe following package references: library osvvm ; use osvvm.MemoryPkg.all ; 3.2 MemInit Alert levels can beFAILURE, ERROR, or WARNING. type AlertType is (FAILURE, ERROR, WARNING) ; 3.3 MemWrite Simplealerts accumulate alerts in the default AlertLogID (ALERTLOG_DEFAULT_ID). It supports the basic overloadingand usage: procedure Alert( Message : string ; Level : AlertType := ERROR ) ; . . . Alert(“Uart Parity”) ; – ER-ROR by default 3.4 MemRead Procedure Each level in a hierarchy is referenced with an AlertLogID. The function,GetAlertLogID, creates a new AlertLogID. If an AlertLogID already exists for the specified name, Copyright ©2015 - 2016 by SynthWorks Design Inc. All rights reserved. 5 Verbatim copies of this document may be used anddistributed without restriction. GetAlertLogID will return its AlertLogID. It is recommended to use the instancelabel as the Name. The interface for GetAlertLogID is as follows. impure function GetAlertLogID(Name : string; ParentID : AlertLogIDType := ALERTLOG_BASE_ID ) return AlertLogIDType ; GetAlertLogID(“UART_1”,ALERTLOG_BASE_ID); 3.5 MemRead Function The function, FindAlertLogID, finds an existing AlertLogID.If the AlertLogID is not found, ALERTLOG_ID_NOT_FOUND is returned. The interface for FindAlertLogID isas follows. impure function FindAlertLogID(Name : string ; ParentID : AlertLogIDType) return AlertLogIDType; impure function FindAlertLogID(Name : string ) return AlertLogIDType ; 3.6 MemErase Hierarchical alertsrequire the AlertLogID to be specified in the call to alert. It supports the basic overloading and usage: procedurealert( AlertLogID : AlertLogIDType ; Message : string ; Level : AlertType := ERROR ) ; . . . Alert(UartID,“Uart Parity”, ERROR) ; 3.7 Deallocate At test completion alerts are reported with ReportAlerts. procedure Re-portAlerts ( Name : string := “” ; AlertLogID : AlertLogIDType := ALERTLOG_BASE_ID ; ExternalErrors :AlertCountType := (others => 0) ) ; . . . ReportAlerts ; 3.8 ReadMemB and ReadMemH Designed to mimicVerilog system functions $readmemb and readmemh. procedure ReadMemB ( Name : string ; StartAddr : nat-ural := 0 ; FinishAddr : natural := natural’right ) ; The file shall contain only of the following: • White space(spaces, new lines, tabs, and form-feeds) Copyright © 2015 - 2016 by SynthWorks Design Inc. All rights re-served. 6 Verbatim copies of this document may be used and distributed without restriction. • Comments (either//, #, or –) • @ character (designating the adjacent number is an address) • Binary or hexadecimal numbers Ad-dresses specified in the call to ReadMemB ro ReadMemH provide both an initial starting address and a rangeof valid addresses for memory operations. Addressing advances from StartAddr to FinishAddr. If FinishAddris greater than StartAddr, then the next address is one larger than the current one, otherwise, the next address isone less than the current address. Addresses may also be specified in the file in the format ‘@’ followed by ahexadecimal number as shown below. There shall not be any space between the ‘@’ and the number. The addressread must be between StartAddr and FinishAddr or a FAILURE is generated. @hhhhh Values not preceded byan ‘@’ character are data values. Data values must be separated by white space or comments from other val-ues. ReadMemB requires values compatible with read for std_ulogic. ReadMemH requires hexadecimal valuescompatible with hread for std_ulogic_vector. If more digits are read than are required by the memory, left handcharacters will be dropped provided they are 0. If fewer digits are read than are required by the memory, lefthand characters will be 0. 4 Compiling AlertLogPkg and Friends Use of AlertLogPkg requires use NamePkg andOsvvmGlobalPkg. The compile order is: NamePkg.vhd, OsvvmGlobalPkg.vhd, TranscriptPkg.vhd, and Alert-LogPkg.vhd. Compiling the packages requires VHDL-2008. 5 About AlertLogPkg AlertLogPkg was developedand is maintained by Jim Lewis of SynthWorks VHDL Training. It originated as an interface layer to the BitVisUtility Library (BVUL). However, it required a default implementation and that default implementation grew intoits own project. Please support our effort in supporting AlertLogPkg and OSVVM by purchasing your VHDLtraining from SynthWorks. AlertLogPkg is released under the Perl Artistic open source license. It is free (both todownload and use - there are no license fees). You can download it from http://www.synthworks.com/downloads.It will be updated from time to time. Currently there are numerous planned revisions. Copyright © 2015 - 2016by SynthWorks Design Inc. All rights reserved. 7 Verbatim copies of this document may be used and distributedwithout restriction. If you add features to the package, please donate them back under the same license as can-didates to be added to the standard version of the package. If you need features, be sure to contact us. I blogabout the packages at http://www.synthworks.com/blog. We also support the OSVVM user community and blogsthrough http://www.osvvm.org. Find any innovative usage for the package? Let us know, you can blog about it atosvvm.org. 6 Future Work AlertLogPkg.vhd is a work in progress and will be updated from time to time. Caution,undocumented items are experimental and may be removed in a future version.

1.1. xx.01.2016 - 2016.01 was release. 73





OsvvmGlobal Package

Overview

OsvvmGlobalPkg provides types and global settings for the OSVVM packages CoveragePkg and AlertLogPkg.

Package User Subprogram Reference

Package Referencelibrary osvvm ;use osvvm.OsvvmGlobalPkg.all ;

OsvvmOptionsType: Type for OSVVM optionstype OsvvmOptionsType is (OPT_INIT_PARM_DETECT, OPT_USE_DEFAULT, DISABLED, FALSE, ENABLED, TRUE) ;

SetOsvvmGlobalOptions: Configuring OSVVM Options Configuration values for the output from Alert,Log, and ReportAlerts.

procedure SetOsvvmGlobalOptions (WritePassFail : OsvvmOptionsType := OPT_INIT_PARM_DETECT ;WriteBinInfo : OsvvmOptionsType := OPT_INIT_PARM_DETECT ;WriteCount : OsvvmOptionsType := OPT_INIT_PARM_DETECT ;WriteAnyIllegal : OsvvmOptionsType := OPT_INIT_PARM_DETECT ;WritePrefix : string := OSVVM_STRING_INIT_PARM_DETECT ;DoneName : string := OSVVM_STRING_INIT_PARM_DETECT ;PassName : string := OSVVM_STRING_INIT_PARM_DETECT ;FailName : string := OSVVM_STRING_INIT_PARM_DETECT

) ;

The following options are for WriteBin and ReportAlerts are:

WritePassFail

WriteBin prints Pass / Fail information

WriteBinInfo

WriteBin prints Bin ranges

WriteCount

WriteBin prints Count

WriteAnyIllegal

WriteBin always prints illegal bins

WritePrefix

Prefix for each line of ReportAlerts. Default “%% “

DoneName

Value printed after ReportPrefix on first line of ReportAlerts. Default “DONE”

PassName

Value printed when a test passes. Default “PASSED”.

FailName

Value printed when a test fails. Default “FAILED”

74 Chapter 1. News


SetOsvvmGlobalOptions will change as the packages are revised. To ensure

forward compatibility into the future call it using named association.

SetOsvvmGlobalOptions (WritePrefix => ">> ",DoneName => "FIN"

) ;


OsvvmDeallocate Deallocates all temporary storage in OsvvmGlobalPkg.

Package Developer Subprogram Reference

function IsEnabled (A : OsvvmOptionsType) return boolean ;function ResolveOsvvmOption(A, B, C: OsvvmOptionsType) return OsvvmOptionsType;function ResolveOsvvmOption(A, B, C, D: OsvvmOptionsType) return OsvvmOptionsType;function IsOsvvmStringSet(A : string) return boolean ;function ResolveOsvvmOption(A, B : string) return string ;function ResolveOsvvmOption(A, B, C : string) return string ;function ResolveOsvvmOption(A, B, C, D : string) return string ;impure function ResolveOsvvmWritePrefix(A : String) return string ;impure function ResolveOsvvmWritePrefix(A, B : String) return string ;impure function ResolveOsvvmDoneName(A : String) return string ;impure function ResolveOsvvmDoneName(A, B : String) return string ;impure function ResolveOsvvmPassName(A : String) return string ;impure function ResolveOsvvmPassName(A, B : String) return string ;impure function ResolveOsvvmFailName(A : String) return string ;impure function ResolveOsvvmFailName(A, B : String) return string ;impure function ResolveCovWritePassFail(A, B : OsvvmOptionsType)return OsvvmOptionsType ; -- Covimpure function ResolveCovWriteBinInfo(A, B : OsvvmOptionsType)return OsvvmOptionsType ; -- Covimpure function ResolveCovWriteCount(A, B : OsvvmOptionsType)return OsvvmOptionsType ; -- Covimpure function ResolveCovWriteAnyIllegal(A, B : OsvvmOptionsType)return OsvvmOptionsType ; -- Cov

Future Work

OsvvmGlobalPkg.vhd is a work in progress and will be updated from time to time.

Randomization Using RandomPkg

1 RandomPkg Overview RandomPkg provides a set of utilities for randomizing a value in a range, a value in a set,or a value with a weighted distribution. OSVVM’s constrained random capability uses these utilities to random-ize a value, operation, or sequence that is valid in a particular test environment. Since any constrained randommethodology creates a significant amount of redundant stimulus (5X or more for small problems), in OSVVM,we use Intelligent Coverage randomization as our main randomization methodology, and constrained random asa refinement methodology in our tests. These packages are updated from time to time and are freely available athttp://www.synthworks.com/downloads. 2 Randomization Using IEEE.math_real.uniform = Yuck! A basic formof randomization can be accomplished by using the procedure uniform the IEEE math_real package. However,this always results in randomization being a multi-step process: call uniform to randomize a value, scale the value,and then use the value. RandomGenProc : process variable RandomVal : real ; – Random value variable DataSent: integer ; variable seed1 : positive :=7 ; – initialize seeds variable seed2 : positive := 1 ; begin for i in 0 to 255*6

1.1. xx.01.2016 - 2016.01 was release. 75



loop uniform(seed1, seed2, RandomVal) ; – randomize 0.0 to 1.0 DataSent := integer(trunc(RandomVal*256.0)) ;– scale to 0 to 255 do_transaction(. . . , DataSent, . . . ) ; . . . Optimally we would like to be able to call a function todo this so we can do this all in one step. Unfortunately we cannot write a normal VHDL function since we need toread and update the seed as well as return a randomized value. 3 Simplifying Randomization RandomPkg uses aprotected type, named RandomPType, to encapsulate the seed. Within a protected type, impure functions can readand update the seed as well as return a randomized value. To randomize values using the protected type, declare avariable of type RandomPType, initialze the seed, and randomize values. RandomGenProc : process variable RV :RandomPType ; – protected type from RandomPkg Copyright © 2011-2016 by SynthWorks Design Inc. All rightsreserved. 4 Verbatim copies of this document may be used and distributed without restriction. begin RV.InitSeed(RV’instance_name) ; – Generate initial seeds for i in 0 to 255*6 loop do_transaction(. . . , RV.RandInt(0, 255),. . . ) ; – random value between 0 and 255 Note the calls to protected type methods (subprograms) include theprotected type variable (RV) within the call (such as RV.RandInt(0, 255)). 4 Manipulating the Seeds With pro-tected types internal objects are private and accessible only through methods. The internal representation of theseed has a valid initial value, however, to ensure that each process’ randomization is independent of each other,it is important to give each seed to a different initial value. As a result for a test that uses more than one ran-domization variable, initialize each seed once - if there is only one randomization variable, there is no need toinitialize the seed. The method InitSeed converts its argument value to RandomSeedType (the internal represen-tation of the seed) and stores the value within the protected type. InitSeed is overloaded to accept either string orinteger values. The preferred way to give each seed a unique value is pass the string value, RV’instance_name.RV.InitSeed (RV’instance_name) ; The methods GetSeed and SetSeed are used to read and restore a seed value.The declarations for these are shown below. impure function GetSeed return RandomSeedType ; procedure Set-Seed (RandomSeedIn : RandomSeedType ) ; The function to_string and procedures write and read are used towrite and read values of type RandomSeedType. The declarations for these subprograms are shown below. Notethese are in RandomBasePkg.vhd and are separate from the protected type. function to_string(A : RandomSeed-Type) return string ; procedure write(L: inout line ; A : RandomSeedType ) ; procedure read (L: inout line ; A : outRandomSeedType ; good : out boolean ) ; procedure read (L: inout line ; A : out RandomSeedType ) ; For a longtest, it may be advantageous to read the seed periodically and print it out. If a failure or other interesting conditionis generated, the seed may be restored to a value that was recorded near the failure with the intent of generatingthe error quickly to assist with debug. Copyright © 2011-2016 by SynthWorks Design Inc. All rights reserved.5 Verbatim copies of this document may be used and distributed without restriction. 5 Basic Randomization Thebasic randomization generates an integer value that is either within some range or within a set of values. The setof values and exclude values are all of type integer_vector (defined in VHDL-2008). The examples below showthe basic randomization overloading. When a value of integer_vector is specifed, the extra set of parenthesesdenote that it is an aggregate value. RandomGenProc : process variable RV : RandomPType ; – protected typefrom RandomPkg variable DataInt : integer ; begin RV.InitSeed (RV’instance_name) ; – Generate initial seeds– Generate a value in range 0 to 255 DataInt := RV.RandInt(0, 255) ; . . . – Generate a value in range 1 to 9except exclude values 2,4,6,8 DataInt := RV.RandInt(1, 9, (2,4,6,8)) ; . . . – Generate a value in set 1,3,5,7,9DataInt := RV.RandInt( (1,3,7,9) ) ; – note two sets of parens required . . . – Generate a value in set 1,3,5,7,9except exclude values 3,7 DataInt := RV.RandInt((1,3,7,9), (3,7) ) ; The overloading for the RandInt functions isas follows. impure function RandInt (Min, Max : integer) return integer ; impure function RandInt (Min, Max:integer; Exclude: integer_vector) return integer ; impure function RandInt ( A : integer_vector ) return integer; impure function RandInt ( A : integer_vector; Exclude: integer_vector) return integer ; These same functionsare available for types std_logic_vector(RandSlv), unsigned (RandUnsigned) and signed (RandSigned). Note thatparameter values are still specified as integers and there is an additional value used to specify the size of the valueto generate. For example, the following call to RandSlv defines the array size to be 8 bits. variable DataSlv :std_logic_vector(7 downto 0) ; begin . . . DataSlv := RV.RandSlv(0, 255, 8) ; – Generate a value in range 0 to255 The overloading for RandSlv is as shown below. RandUnsigned and RandSigned have the same overloadingimpure function RandSlv (Min, Max, Size : natural) return std_logic_vector ; impure function RandSlv (Min,Max : natural ; Exclude: integer_vector ; Size : natural) return std_logic_vector ; impure function RandSlv (A:integer_vector ; size : natural ) return std_logic_vector ; Copyright © 2011-2016 by SynthWorks Design Inc. Allrights reserved. 6 Verbatim copies of this document may be used and distributed without restriction. impure func-tion RandSlv (A: integer_vector ; Exclude: integer_vector ; Size : natural) return std_logic_vector ; The function,RandReal supports randomization for type real. The function with a range, like the procedure Uniform, nevergenerates its end values. RandReal has the following overloading: impure function RandReal ( Min, Max : real) return real ; impure function RandReal ( A : real_vector ) return real ; impure function RandReal ( A, Exclude: real_vector ) return real ; The function, RandTime supports randomization for type time. RandTime supportsthe same overloading as RandInt. These are shown below: impure function RandTime (Min, Max : time ; Unit :time := ns) return time ; impure function RandTime (Min, Max : time ; Exclude : time_vector ; Unit : time := ns)

76 Chapter 1. News


return time ; impure function RandTime (A : time_vector) return time ; impure function RandTime (A, Exclude: time_vector) return time ; 6 Large Vector Randomization Integer randomization is only valid in the range of-2**31 to +2**31 - 1. Large vector randomization uses multiple randomizations to create a value. The followingoverloading is available for RandUnsigned, RandSlv, and RandSigned. impure function RandUnsigned (Size :natural) return unsigned ; impure function RandUnsigned (Max : unsigned) return unsigned ; impure functionRandUnsigned (Min, Max : unsigned) return unsigned ; The size parameter specifies the number of bits in thevector. The Max parameter allows randomization between 0 and Max. The Min and Max parameters allow ran-domizing a range of values. 7 Randomizing Sets of Values A set of values can be represented by integer_vector,real_vector, or time_vector. The following illustrates the capability supported for integer_vector. RandomGen-Proc : process variable RV : RandomPType ; – protected type from RandomPkg variable IntV : integer_vector(1to 15) ; begin RV.InitSeed (RV’instance_name) ; – Generate initial seeds – Generate 10 integer values in the range0 to 255 IntV(1 to 10) := RV.RandIntV(0, 255, 10) ; . . . – Generate 15 integer values in range 1 to 9 exceptexclude values 2,4,6,8 IntV := RV.RandIntV(1, 9, (2,4,6,8), 15) ; . . . – Generate 5 integer values value in set1,3,5,7,9 IntV(1 to 5) := RV.RandIntV( (1,3,7,9), 5 ) ; Copyright © 2011-2016 by SynthWorks Design Inc. Allrights reserved. 7 Verbatim copies of this document may be used and distributed without restriction. . . . –Generate 15 integer values in set 1,3,5,7,9 except exclude values 3,7 IntV := RV.RandIntV((1,3,7,9), (3,7), 15) ;– Generate 10 integer values in the range 0 to 255, do repeat the last value IntV(1 to 10) := RV.RandIntV(0, 255,1, 10) ; . . . – Generate 15 integer values in range 1 to 9 except exclude values 2,4,6,8 – Do not repeat the last3 values IntV:= RV.RandIntV(1, 9, (2,4,6,8), 3, 15) ; . . . – Generate 5 integer values in the set 1,3,5,7,9, donot repeat the last value IntV(1 to 5) := RV.RandIntV( (1,3,7,9), 1, 5 ) ; . . . – Generate 15 integer values in set1,3,5,7,9 except exclude values 3,7 – Do not repeat last value IntV := RV.RandIntV((1,3,7,9), (3,7), 1, 15) ; Theoverloading for integer_vector, real_vector, or time_vector are as follows. – Range and Exclude impure functionRandIntV (Min, Max : integer ; Size : natural) return integer_vector ; impure function RandIntV (Min, Max :integer ; Exclude : integer_vector ; Size : natural) return integer_vector ; – Range, Exclude, and Unique impurefunction RandIntV (Min, Max : integer ; Unique : natural ; Size : natural) return integer_vector ; impure functionRandIntV (Min, Max : integer ; Exclude : integer_vector ; Unique : natural ; Size : natural) return integer_vector; – Set and Exclude impure function RandIntV (A : integer_vector ; Size : natural) return integer_vector ; impurefunction RandIntV (A, Exclude : integer_vector ; Size : natural) return integer_vector ; – Range, Exclude, andUnique impure function RandIntV (A : integer_vector ; Unique : natural ; Size : natural) return integer_vector ;impure function RandIntV (A, Exclude : integer_vector ; Unique : natural ; Size : natural) return integer_vector; Overloading for time_vector: impure function RandTimeV (Min, Max : time; Size : natural; Unit : time := ns)return time_vector; impure function RandTimeV (Min, Max : time ; Exclude : time_vector ; Size : natural) returntime_vector ; impure function RandTimeV (Min, Max : time; Unique : natural; Size : natural; Unit : time := ns)return time_vector ; impure function RandTimeV (Min, Max : time; Exclude : time_vector; Unique : natural; Size: natural) return time_vector; impure function RandTimeV (A : time_vector; Size : natural) return time_vector; impure function RandTimeV (A : time_vector; Unique : natural ; Size : natural) return time_vector; impurefunction RandTimeV (A, Exclude : time_vector; Size : natural) return time_vector ; impure function RandTimeV(A, Exclude : time_vector; Unique : natural; Size : natural) return time_vector ; Copyright © 2011-2016 bySynthWorks Design Inc. All rights reserved. 8 Verbatim copies of this document may be used and distributedwithout restriction. Overloading real_vector impure function RandRealV (Min, Max : real ; Size : natural) returnreal_vector ; impure function RandRealV (A : real_vector ; Size : natural) return real_vector ; impure functionRandRealV (A : real_vector ; Unique : natural ; Size : natural) return real_vector ; impure function RandRealV (A,Exclude : real_vector ; Size : natural) return real_vector ; impure function RandRealV (A, Exclude : real_vector ;Unique : natural ; Size : natural) return real_vector ; 8 Weighted Randomization A weighted distribution randomlygenerates each of set of values a specified percentage of the time. RandomPType provides a weighted distributionthat specifies a value and its weight (DistValInt) and one that only specifies weights (DistInt). DistValInt is calledwith an array of value pairs. The first item in the pair is the value and the second is the weight. The frequency thateach value will occur is weight/(sum of weights). As a result, in the following call to DistValInt, the likelihood ofa 1 to occur is 7/10 times or 70%. The likelihood of 3 is 20% and 5 is 10%. variable RV : RandomPType ; . . .DataInt := RV.DistValInt( ((1, 7), (3, 2), (5, 1)) ) ; DistInt is a simplified version of DistValInt. The input to DistIntis an integer_vector of weights. The return value is the index of the selected weight. For a literal value, it willreturn a value from 0 to N-1 where N is the number of weights specified. As a result, the following call to DistIntthe likelihood of a 0 is 70%, 1 is 20% and 2 is 10%. variable RV : RandomPType ; . . . DataInt := RV.DistInt(((7, 2, 1)) ; 9 Usage Each randomization result is produced by a function and that result can be used directly inan expression. Hence, we can randomize a delay that is between 3 and 10 clocks. wait for RV.RandInt(3, 10)* tperiod_Clk - tpd ; wait until Clk = ‘1’ ; The values can also be used directly inside a case statement. Thefollowing example uses DistInt to generate the first case target 70% of the time, the second 20%, and the third10%. variable RV : RandomPType ; . . . StimGen : while TestActive loop – Repeat until done case RV.DistInt(

1.1. xx.01.2016 - 2016.01 was release. 77


(7, 2, 1) ) is when 0 => – Normal Handling – 70% . . . Copyright © 2011-2016 by SynthWorks Design Inc.All rights reserved. 9 Verbatim copies of this document may be used and distributed without restriction. when 1=> – Error Case 1 – 20% . . . when 2 => – Error Case 2 – 10% . . . when others => report “DistInt” severityfailure ; – Signal bug in DistInt end case ; end loop ; The following code segment generates the transactions forwriting to DMA_WORD_COUNT, DMA_ADDR_HI, and DMA_ADDR_LO in a random order that is differentevery time this code segment is run. The sequence finishes with a write to DMA_CTRL. When DistInt is calledwith a weight of 0, the corresponding value does not get generated. Hence by initializing all of the weights to 1and then setting it to 0 when it is selected, each case target only occurs once. The “for loop” loops three times toallow each transaction to be selected. variable RV : RandomPType ; . . . Wt0 := 1; Wt1 := 1; Wt2 := 1; – InitialWeights for i in 1 to 3 loop – Loop 1x per transaction case RV.DistInt( (Wt0, Wt1, Wt2) ) is – Select transactionwhen 0 => – Transaction 0 CpuWrite(CpuRec, DMA_WORD_COUNT, DmaWcIn); Wt0 := 0 ; – remove fromrandomization when 1 => – Transaction 1 CpuWrite(CpuRec, DMA_ADDR_HI, DmaAddrHiIn); Wt1 := 0 ; –remove from randomization when 2 => – Transaction 2 CpuWrite(CpuRec, DMA_ADDR_LO, DmaAddrLoIn);Wt2 := 0 ; – remove from randomization when others => report “DistInt” severity failure ; end case ; end loop; CpuWrite(CpuRec, DMA_CTRL, START_DMA or DmaCycle); The following code segment uses an excludelist to keep from repeating the last value. Note when passing an integer value to an integer_vector parameter, anaggregate using named association “(0=> LastDataInt)” is used to denote a single element array. Note that duringthe first execution of this process, LastDataInt has the value integer’left (a very small number), which is outside therange 0 to 255, and as a result, has no impact on the randomization. RandomGenProc : process variable RV : Ran-domPType ; variable DataInt, LastDataInt : integer ; begin . . . DataInt := RV.RandInt(0, 255, (0 => LastDataInt)); Copyright © 2011-2016 by SynthWorks Design Inc. All rights reserved. 10 Verbatim copies of this documentmay be used and distributed without restriction. LastDataInt := DataInt; . . . The following code segment usesan exclude list to keep from repeating the four previous values. RandProc : process variable RV : RandomPtype ;variable DataInt : integer ; variable Prev4DataInt : integer_vector(3 downto 0) := (others => integer’low) ; begin. . . DataInt := RV.RandInt(0, 100, Prev4DataInt) ; Prev4DataInt := Prev4DataInt(2 downto 0) & DataInt ; . .. 10 Creating a Test Creating tests is all about methodology. SynthWorks’ methodology marries randomizationsubprograms (from RandomPkg) and functional coverage subprograms (from CoveragePkg - also freely availableat http://www.synthworks.com/downloads) with VHDL programming constructs. Each test sequence is derivedby randomly selecting either branches of code or values for operations. Randomization constraints are createdusing normal sequential coding techniques (such as nesting of case, if, loop, and assignment statements). Thisapproach is simple yet powerful. Since all of the code is sequential, randomized sequences are readily mixedwith directed and algorithmic sequences. A simple demonstration of randomizing is the following test which usesheuristics (guesses) at length of bursts of data and delays between bursts of data to randomization traffic beingsent to a FIFO. variable RV : RandomPType ; . . . TxStimGen : while TestActive loop – Burst between 1 and10 values BurstLen := RV.RandInt(Min => 1, Max => 10); for i in 1 to BurstLen loop DataSent := DataSent + 1; WriteToFifo(DataSent) ; end loop ; – Delay between bursts: (BurstLen <=3: 1-6, >3: 3-10) if BurstLen <= 3then BurstDelay := RV.RandInt(1, 6) ; – small burst, small delay else BurstDelay := RV.RandInt(3, 10) ; – biggerburst, bugger delay end if ; wait for BurstDelay * tperiod_Clk - tpd ; wait until Clk = ‘1’ ; end loop TxStimGen; Copyright © 2011-2016 by SynthWorks Design Inc. All rights reserved. 11 Verbatim copies of this documentmay be used and distributed without restriction. Functional coverage counts which test cases have been generatedand give engineers an indication of when testing is done. This is essential when using randomization to createa test as otherwise there is no way to know what the test actually did. Functional coverage can be implementedusing subprogram calls (either custom or from the CoveragePkg) or VHDL code. Functional coverage is storedin signals and can be used to change the randomization (either directly as a constraint or indirectly as somethingthat contributes to changing a constraint) to generate missing coverage items. With a FIFO, we need to see lotsof write attempts while full and read attempts while empty. One thing we can do to improve the previous test isto increase or decrease the burst length and delay based on the number of write attempts while full or read at-tempts while empty we have seen. To explore how to generate the coverage, see the CoveragePkg documentation.For a design for which has numerous conditions we need to generate, we can do coverage on the input stimulusand then randomly select one of the uncovered conditions as the next transaction to be generated. Solutions forthe two previous coverage driven randomization problems are provided in SynthWorks’ VHDL Testbenches andVerification class. 11 Random Stability A protected type is always used with a variable object. If the object isdeclared in a process, it is a regular variable. If the object is declared in an architecture, then it is declared asa shared variable. All of the examples in this document show RandomPType being defined in a process as aregular variable. This is done to ensure random stability. Random stability is the ability to re-run a test and getexactly the same sequence. Random stability is required for verification since if we find a failure and then fix it,if the same sequence is not generated, we will not know the fix actually worked. Random stability is lost whena randomization variable is declared as a shared variable in an architecture and shared among multiple processes.

78 Chapter 1. News


When a randomization variable is shared, the seed is shared. Each randomization reads and updates the seed. Ifthe processes accessing the shared variable run during the same delta cycle, then the randomization of the testdepends on the order of which RandomPType is accessed. This order can change anytime the design is optimized- which will happen after fixing bugs. As a result, the test is unstable. To ensure stability, create a separate vari-able for randomization in each process. Copyright © 2011-2016 by SynthWorks Design Inc. All rights reserved.12 Verbatim copies of this document may be used and distributed without restriction. 12 Other Distributions Bydefault, all randomizations use a uniform distribution. In addition to uniform distributions, RandomPType alsoprovides distributions for FavorSmall, FavorBig, normal, and poisson. The following is the overloading for thesefunctions. – Generate values, each with an equal probability impure function Uniform (Min, Max : in real) returnreal ; impure function Uniform (Min, Max : integer) return integer ; impure function Uniform (Min, Max : integer; Exclude: integer_vector) return integer ; – Generate more small numbers than big impure function FavorSmall(Min, Max : real) return real ; impure function FavorSmall (Min, Max : integer) return integer ; impure functionFavorSmall(Min, Max: integer; Exclude: integer_vector) return integer ; – Generate more big numbers than smallimpure function FavorBig (Min, Max : real) return real ; impure function FavorBig (Min, Max : integer) returninteger ; impure function FavorBig (Min, Max : integer ; Exclude: integer_vector) return integer ; – Generatenormal = gaussian distribution impure function Normal (Mean, StdDeviation : real) return real ; impure functionNormal (Mean, StdDeviation, Min, Max : real) return real ; impure function Normal ( Mean : real ; StdDeviation: real ; Min : integer ; Max : integer ; Exclude : integer_vector := NULL_INTV ) return integer ; – Generatepoisson distribution impure function Poisson (Mean : real) return real ; impure function Poisson (Mean, Min,Max : real) return real ; impure function Poisson ( Mean : real ; Min : integer ; Max : integer ; Exclude : inte-ger_vector := NULL_INTV ) return integer ; The package also provides experimental mechanisms for changingthe distributions used with functions RandInt, RandSlv, RandUnsigned, and RandSigned. Copyright © 2011-2016by SynthWorks Design Inc. All rights reserved. 13 Verbatim copies of this document may be used and distributedwithout restriction. 13 Sorting integer_vector The package SortListPkg_int provides a Sort and RevSort functionsfor sorting type integer_vector. The following example uses RandIntV and Sort to create a random set of 10 in-teger values between 0 and 255 that increase in value and do not repeat. IntV := Sort(RV.RandIntV(0, 255, 10,10)) ; The overloading for Sort and RevSort are as follows. impure function Sort (A : integer_vector) return inte-ger_vector; impure function RevSort (A : integer_vector) return integer_vector ; 14 Compiling RandomPkg andFriends Turn on the VHDL-2008 compile switch. Compile the files, SortListPkg_int.vhd, RandomBasePkg.vhd,and RandomPkg.vhd. We typically put these into a named library such as SynthWorks or OSVVM. To takethe packages for a test run, compile the program, Demo_Rand.vhd, into the same library as the packages andrun it for 1 ns in your simulator. Your programs need to reference RandomPkg. If your programs use IO forthe seed (to_string, write, read), then you will also need to include RandomBasePkg. library OSVVM ; useOSVVM.RandomPkg.all ; 15 About RandomPkg RandomPkg was developed and is maintained by Jim Lewisof SynthWorks VHDL Training. It evolved from methodology and packages developed for SynthWorks’ VHDLTestbenches and verification class. It is part of the Open Source VHDL Verification Methodology (OSVVM),which brings leading edge verification techniques to the VHDL community. Please support our effort in sup-porting RandomPkg and OSVVM by purchasing your VHDL training from SynthWorks. RandomPkg is releasedunder the Perl Artistic open source license. It is free (both to download and use - there are no license fees). Youcan download it from http://www.synthworks.com/downloads. It will be updated from time to time. Currentlythere are numerous planned revisions. If you add features to the package, please donate them back under thesame license as candidates to be added to the standard version of the package. If you need features, be sure tocontact us. I blog about the packages at http://www.synthworks.com/blog. We also support a user community andblogs through http://www.osvvm.org. Copyright © 2011-2016 by SynthWorks Design Inc. All rights reserved.14 Verbatim copies of this document may be used and distributed without restriction. If you find any innovativeusage for the package, let us know - we can set you up to 16 Future Work RandomPkg.vhd is a work in progressand will be updated from time to time. Things not documented in this document, such as type RandomParmTypeand method SetRandomParm, are experimental and may be removed in a future revision of the package (to reducethe overhead to basic randomization). Note that the current version of this package gives direct access to thiscapability via methods FavorSmall, FavorBig, normal, and poisson. In addition to the RandomPkg, we also arefreely distributing our coverage package, CoveragePkg. See http://www.SynthWorks.com/downloads. Over timewe will also be releasing other packages that we currently distribute with our classes (such as scoreboards andmemory modeling) and hope to convince simulation vendors to distribute our libraries with their tools.

1.1. xx.01.2016 - 2016.01 was release. 79


Transcript Package User Guide

1 TranscriptPkg Overview TranscriptPkg allows different parts of a testbench to use a common transcript file.It does this by providing an internal file identifier (TranscriptFile), and subprograms for opening (Transcrip-tOpen) files, closing (TranscriptClose) files, printing (print and writeline), and checking if the file is open (Is-TranscriptOpen). 2 TranscriptPkg Use Models TranscriptPkg offers three printing methods, Print, WriteLine,and direct usage of TranscriptFile. If the TranscriptFile is open, Print and WriteLine write to the transcript file,otherwise, they write to std.textio.OUTPUT. use osvvm.TranscriptPkg.all ; architecture Test1 of tb is processbegin TranscriptOpen(”./results/Transcript_t1_nominal.txt”) ; Print(“Print 1”) ; swrite(buf, “Write 1”) ; write-line(buf) ; . . . TranscriptClose ; if IsTranscriptOpen then swrite(buf, “Write 1 - transcript open”) ; write-line(TranscriptFile, buf) ; end if; TranscriptPkg also supports a mirror mode in which Print and WriteLinewrite to both TranscriptFile and std.textio.OUTPUT. Entering mirror mode is via SetTranscriptMirror. Set-TranscriptMirror ; SetAlertStopCount(ERROR, 20) ; 3 Usage by other OSVVM packages Print and Write-Line are used by other OSVVM packages. In CoveragePkg, WriteBin without a file specification uses Is-TranscriptOpen to determine whether to use std.textio.OUTPUT or TranscriptFile. In AlertLogPkg, alert, log,and ReportAlerts all use osvvm.TranscriptPkg.WriteLine. Copyright © 2015 - 2016 by SynthWorks DesignInc. All rights reserved. 4 Verbatim copies of this document may be used and distributed without restric-tion. 4 Method Reference 4.1 Package Reference Using TranscriptPkg requires the following package refer-ence: library osvvm ; use osvvm.TranscriptPkg.all ; 4.2 Transcript File TranscriptFile is an internal file to thedeclarative region of TranscriptPkg. file TranscriptFile : text ; 4.3 TranscriptOpen TranscriptOpen opens theTranscriptFile. When the transcript is open, alert, log, ReportAlerts, WriteLine, and print use the Transcript-File, otherwise, they use OUTPUT. procedure TranscriptOpen (Status: out FILE_OPEN_STATUS; External-Name: STRING; OpenKind: FILE_OPEN_KIND := WRITE_MODE) ; procedure TranscriptOpen (External-Name: STRING; OpenKind: FILE_OPEN_KIND := WRITE_MODE) ; impure function TranscriptOpen (Exter-nalName: STRING; OpenKind: FILE_OPEN_KIND := WRITE_MODE) return FILE_OPEN_STATUS ; . . .– file open status, File name, file open kind TranscriptOpen(Status, ”./Results.txt”, WRITE_MODE) ; Transcrip-tOpen( ”./Results.txt”, WRITE_MODE) ; WRITE_MODE is the default. If READ_MODE is used, an error isgenerated. Usage of the function form allows a file to be opened in a declarative region (such as in a package).Constant OPENED_RESULTS : FILE_OPEN_STATUS := TranscriptOpen(”./Results.txt”, WRITE_MODE) ; 4.4TranscriptClose TranscriptClose closes the TranscriptFile. procedure TranscriptClose ; 4.5 IsTranscriptOpen Is-TranscriptOpen returns true when the TranscriptFile is open. impure function IsTranscriptOpen return boolean; . . . if IsTranscriptOpen then swrite(buf, “Write 1 - transcript open”) ; writeline(TranscriptFile, buf) ; end if;Copyright © 2015 - 2016 by SynthWorks Design Inc. All rights reserved. 5 Verbatim copies of this documentmay be used and distributed without restriction. 4.6 WriteLine Writeline writes the buffer to the TranscriptFilewhen it is open, otherwise, to OUTPUT. procedure WriteLine(buf : inout line) ; . . . swrite(buf, “A Message”) ;writeline(buf) ; 4.7 Print Print writes the string to the TranscriptFile if it is open, otherwise, to OUTPUT. proce-dure Print(s : string) ; . . . Print(“Another Message”) ; 4.8 SetTranscriptMirror SetTranscriptMirror sets mirrormode in which Print and WriteLine write to both TranscriptFile and std.textio.OUTPUT. procedure SetTranscript-Mirror (A : boolean := TRUE) ; . . . SetTranscriptMirror ; 4.9 IsTranscriptMirrored IsTranscriptMirrored returnstrue when the transcript is mirrored. impure function IsTranscriptMirrored return boolean ; . . . if IsTran-scriptMirrored then . . . 5 Compiling TranscriptPkg and Friends Use of AlertLogPkg requires use NamePkg,OsvvmGlobalPkg, and AlertLogBasePkg. The compile order is: NamePkg.vhd, OsvvmGlobalPkg.vhd, Alert-LogBasePkg.vhd, and AlertLogPkg.vhd. Compiling the packages requires VHDL-2008. 6 About TranscriptPkgTranscriptPkg was developed and is maintained by Jim Lewis of SynthWorks VHDL Training. It originated inconjunction with AlertLogPkg. Please support our effort in supporting TranscriptPkg and OSVVM by purchasingyour VHDL training from SynthWorks. TranscriptPkg is released under the Perl Artistic open source license. It isfree (both to download and use - there are no license fees). You can download it from Copyright © 2015 - 2016by SynthWorks Design Inc. All rights reserved. 6 Verbatim copies of this document may be used and distributedwithout restriction. http://www.synthworks.com/downloads. It will be updated from time to time. Currently thereare numerous planned revisions. If you add features to the package, please donate them back under the samelicense as candidates to be added to the standard version of the package. If you need features, be sure to contactus. I blog about the packages at http://www.synthworks.com/blog. We also support the OSVVM user communityand blogs through http://www.osvvm.org. Find any innovative usage for the package? Let us know, you can blogabout it at osvvm.org. 7 Future Work TranscriptPkg.vhd is a work in progress and will be updated from time totime. Caution, undocumented items are experimental and may be removed in a future version.

Name Package

80 Chapter 1. News





Todo

No documentation available.

TextUtil Package

Todo


Message Package

Todo


SortList Package

Todo


Osvvm Context

Todo


Release Notes

2016.01 - January 2016

Current Revision and Compile Order The following table lists the files and revision, starting with the filesthat need to be compiled first.

File Revision File RevisionAlertLogPkg.vhd 2016.01 OsvvmGlobalPkg.vhd 2015.01CoveragePkg.vhd 2016.01 RandomBasePkg.vhd 2015.06MemoryPkg.vhd 2016.01 RandomPkg.vhd 2015.06MessagePkg.vhd 2015.01 SortListPkg_int.vhd 2015.01NamePkg.vhd 2015.06 TextUtilPkg.vhd 2016.01OsvvmContext.vhd 2015.06 TranscriptPkg.vhd 2016.01

AlertLogPkg 2016.01

• Fixed bug that kept more than 32 bins from being used.

1.1. xx.01.2016 - 2016.01 was release. 81


CoveragePkg 2016.01

• Revised ConcatenateBins so it does not call Alert to allow it to be a pure function.

• Added bounds checking to ICover so that if ICover is called with the wrong length of integer_vector, it willcause an Alert FAILURE.

MemoryPkg and TextUtilPkg 2016.01

• Changed L.all(1) to L.all(L’left). GHDL does not default objects of type line to have an index of 1.

TranscriptPkg 2016.01

• Minor reorganization of code so that all calls to TranscriptOpen eventually call the same code.

2015.06 - June 2015

MemoryPkg (New) 2015.06

• New to OSVVM. Package with protected type for implementing memories. Methods MemInit, MemRead,MemWrite, MemErase, FileReadH, FileReadB, FileWriteH, FileWriteB, SetAlertLogID, Deallocate.

AlertLogPkg 2015.06

• Added AffirmIf.

• Added PASSED log level.

• Added IncAlertCount as a silent alert (Used by CoveragePkg).

• Revised ReportAlerts to print number of affirmations checked.

• Added GetAffirmCheckCount, IncAffirmCheckCOunt.

• ClearAlerts also clears affirmations.

• Added CreateHierarchy final parameter to GetAlertLogID.

• Added a Get for every Set.

• Moved EmptyOrCommentLine to TextUtilPkg and revised.

CoveragePkg 2015.06

• Implemented Mirroring for WriteBin and WriteCovHoles. When in ILLEGAL_OFF mode, added IncAlert-Count (as a silent alert).

• Added SetAlertLogID(Name, ParentID, CreateHierarchy).

• Updated Alert output format.

• Added AddCross(CovMatrix?Type).

• Deprecated AddBins(CovMatrix?Type).

• Moved EmptyOrCommentLine to TextUtilPkg and revised.

82 Chapter 1. News


TextUtilPkg (New) 2015.06

• Shared utilities for file reading. SkipWhiteSpace, EmptyOrCommentLine, ReadHexToken, ReadBinaryTo-ken.

RandomPkg 2015.06

• Revised calls to Alert to 2015.03 preferred format with AlertLogID first.

NamePkg 2015.06

• Added input parameter to Get to specify a return value when NamePtr is not initialized.

RandomBasePkg 2015.06

• Changed GenRandSeed to impure since it calls Alert (and Alert is a parent of a call to a protected typemethod).

OsvvmContext.pkg 2015.06

• Added MemoryPkg

2015.03 - March 2015

AlertLogPkg 2015.03

• Added AlertIfEqual, AlertIfNotEqual, and AlertIfDiff (file).

• Added ReadLogEnables to initialize LogEnables from a file.

• Added ReportNonZeroAlerts.

• Added PathTail to extract an instance name from MyEntity’PathName.

• Added ReportLogEnables and GetAlertLogName.

See also:

See AlertLogPkg_User_Guide.pdf for details.

Todo

replace this pdf by a doc link

For hierarchy mode, AlertIfEqual, AlertIfNotEqual, and AlertIfDiff have the AlertLogID parameter first. Over-loading was added for AlertIf and AlertIfNot to make these consistent. Now with multiple parameters, it is easierto remember that the AlertLogID parameter is first. The older AlertIf and AlertIfNot with the AlertLogID as thesecond parameter were kept for backward compatibility, but are considered bad practice to use in new code.

• Added ParentID parameter to FindAlertLogID. This is necessary to correctly find an ID within an entitythat is used more than once.

Bug Fixes:

• Bug fix: Updated GetAlertLogID to use the two parameter FindAlertLogID. Without this fix, Alerts withthe same name incorrectly use the same AlertLogID.

1.1. xx.01.2016 - 2016.01 was release. 83


• Bug fix: Updated NewAlertLogRec (called by GetAlertLogID) so a new record gets Alert and Log enablesbased on its ParentID rather than the ALERTLOG_BASE_ID. Issue, if created an Comp1_AlertLogID, anddisabled a level (such as WARNING), and then created a childID of Comp1_AlertLogID, WARNING wouldnot be disabled in childID.

• Bug fix: Updated ClearAlerts to correctly set stop counts (broke since it previously did not use namedassociation). Without this fix, after calling ClearAlerts, a single FAILURE would not stop a simulation,however, a single WARNING would stop a simulation.

2015.01 - January 2015

OsvvmContext (New) 2015.01

OsvvmContext is a context declaration. Rather than referencing osvvm packages with individual use clauses,instead use a single context reference:

library osvvm ; context osvvm.OsvvmContext ;

OsvvmGlobalPkg (New) 2015.01

Manages global report settings for CoveragePkg and AlertLogPkg. Provides constants and base types for Alert-LogPkg.

TranscriptPkg (New) 2015.01

TranscriptPkg simplifies different parts of a testbench using a common transcript file (named TranscriptFile). Alsoprovides overloading for Print and WriteLine that use TranscriptFile when it is opened (via TranscriptOpen), andotherwise, use std.env.OUTPUT.

AlertLogPkg (New) 2015.01

New package added to allow catching and counting of assert FAILURE, ERROR, WARNING as well as doverbosity filtering for log files.

The package offers either a native OSVVM mode or an interface mode. In the interface mode, the package bodyis used to redirect OSVVM internal calls to a separate alert/log package. For example, for BitVis Utility Library(BVUL), there is a package body of AlertLogPkg that allows OSVVM to record asserts and logs via BVUL. Byonly changing the package body, the interface mode can be recompiled without requiring other elements of theOSVVM library to be recompiled. This same methodology allows connection to other packages.

RandomPkg and RandomBasePkg 2015.01

Replaced all asserts with calls to AlertPkg.

CoveragePkg 2015.01

4.6.1 Changes

Replaced all asserts and reports with calls to AlertPkg. Added a verbosity flag to WriteBin to allow it to handledebug calls.

WriteBin prints a multiple line report. As a result, instead of calling Log in the AlertPkg, package, when calledwith a verbosity flag, WriteBin first checks to see if its ScopeID and Verbosity Level are allowed to print. Ifenabled, it then uses write and writeline to print the report.

84 Chapter 1. News


The undocumented method, DumpBin, now has a LogLevel parameter. Its interface is:

procedure DumpBin (LogLevel : LogType := DEBUG) ;

4.6.2 Additions

The following methods were added:

procedure SetAlertLogID (A : AlertLogIDType) ; impure function GetAlertLogID return AlertLogIDType ; im-pure function SetName (Name : String) return string ; impure function GetName return String ; impure functionInitSeed (S : string ) return string ; procedure WriteBin (LogLevel : LogType ; . . .) ; procedure WriteCovHoles (LogLevel : LogType ; . . . ) ;

2014.07a - December 2014

5.1 CoveragePkg, MessagePkg, NamePkg 2014.12

Removed memory leak in CoveragePkg.Deallocate. Removed initialized pointers from CoveragePkg, Mes-sagePkg, and NamePkg – when a protected type with initialized pointers is abandoned, such as when declaredin a subprogram exits, a memory leak will occur as there is no destructor to deallocate the initialized pointers.

2014.07 - July 2014

6.1 RandomPkg

No changes were made to RandomPkg. It is still labeled 2014.01.

6.2 CoveragePkg

CoveragePkg now references both MessagePkg and NamePkg.

Added names to bins. When using WriteBin or WriteCovHoles, if a bin name is set, it will print. For details, seeSetting Bin Names in the Reporting Coverage section of the CoveragePkg Users Guide.

Enhanced WriteBin to print “PASSED” if the count is greater than or equal to the goal (AtLeast value), otherwise,it prints “FAILED”. Added a number of parameters to WriteBin to control what fields of a WriteBin report getprinted. See Enabling and Disabling WriteBin fields in the Reporting Coverage section of the CoveragePkg UsersGuide.

2014.01 - January 2014

7.1 RandomPkg

Added randomization for time (RandTime), additional overloading for type real (RandReal), and sets of values fortypes (integer_vector, real_vector, and time_vector. Made Sort and RevSort from SortListPkg_int visible usingaliases.

7.2 CoveragePkg

Revised ReadCovDb to support merging of coverage models (from different test runs).

Revised RandCovPoint and RandCovBinVal to log the bin index in the LastIndex variable. Revised ICover to lookin bin referenced by LastIndex first. Added method GetLastIndex to get the variable value. Added GetLastBinValto get the BinVal of LastIndex.

Revised AddBins and AddCross bin merging to allow arbitrary CountBin overlap. With the addition of LastIndex,the overlap is not an issue.

Split SetName into SetMessage (headers) and SetName (printing illegal bins)

Added method GetItemCount to return the count of the number of randomizations and method GetTotalCovGoalto return the sum of the individual coverage goals in the coverage model.

1.1. xx.01.2016 - 2016.01 was release. 85


2013.05 - May 2013

8.1 RandomPkg

Added big vector randomization.

8.2 CoveragePkg

No substantial changes. Removed extra variable declaration in functions GetHoleBinval, RandCovBinVal, Rand-CovHole, GetHoleBinVal. Now referencing NULL_RANGE type from RandomPkg to remove NULL rangewarnings.

2013.04 - April 2013

9.1 RandomPkg

Changed DistInt return value. The return value is now determined by the range of the input array. For literalvalues, this produces the same value as it did previously. Also added better error checking for weight values.

Added better min, max error handling in Uniform, FavorBig, FavorSmall, Normal, Poisson.

9.2 CoveragePkg

Revised AddBins and AddCross such that bin merging is off by default. Added SetMerging to enable/disablemerging. Note: Merging is an experimental feature and still evolving.

Revised AddBins and AddCross to check for changes in BinVal size (different size bin).

Added RandCovPoint for integer.

Added SetThresholding and SetCovThreshold (Percent) to enable/disable(default) thresholding. Revised Rand-CovPoint and RandCovBinVal to use the new mechanism.

Added SetCovTarget to increase/decrease coverage goals for longer/shorter simulation runs. Made CovTarget thedefault percentage goal (via overloading) for methods RandCovPoint, RandCovBinVal, IsCovered, CountCov-Holes, GetHoleBinVal, and WriteCovHoles.

Revised SetIllegalMode and ICover to support ILLEGAL_FAILURE (severity FAILURE on illegal bin).

Added manual bin iteration support. Added the following methods that return a bin index value: GetNumBins,GetMinIndex, and GetMaxIndex. Added the following methods that return bin values: GetBinVal(BinIndex),GetMinBinVal, and GetMaxBinVal. Added the following methods that return point values: GetPoint(BinIndex),GetMinPoint, and GetMaxPoint.

Added GetCov to return the current percent done of the entire coverage model.

Added FileOpenWriteBin and FileCloseWriteBin to specify default file for WriteBin, WriteCovHoles, and Dump-Bin.

Added CompareBins to facilitate comparing two coverage models. Added CompareBins to facilitate comparingtwo coverage models.

Revised WriteBin, WriteCovHoles, and WriteCovDb to check for uninitialized model.

Revised WriteBins and WriteCovHoles to only print weight if the selected WeightMode uses the weight.

Added IsInitialized to check if a coverage model is initialized.

Added GetBinInfo and GetBinValLength to get bin information

Changed WriteCovDb default for File_Open_Kind to WRITE_MODE. Generally only one WriteCovDb is neededper coverage model.

Revised WriteCovDb and ReadCovDb for new internal control/state variables, in the order of ThresholdingEnable,CovTarget, and MergingEnable. To manually edit old file, add FALSE, 100.0, FALSE to end of first line.

Removed IgnoreBin with AtLeast and Weight parameters. These are zero for ignore bins.

Revised method naming for consistency. The following have changed:

86 Chapter 1. News


New Name Old Name Why GetErrorCount CovBinErrCnt Consistency between packages GetMinCount GetMin-Cov[return integer] Naming clarity GetMaxCount GetMaxCov[return integer] Naming clarity SetName SetItem-Name SetName now does multi-line messages RandCovBinVal RandCovHole Naming consistency (2.4) GetH-oleBinVal GetCovHole Naming consistency (2.4)

Deprecated usage of the AtLeast parameter (integer) with the following methods: RandCovPoint, RandCovBin-Val, IsCovered, CountCovHoles, GetHoleBinVal, and WriteCovHoles.

2.4 - January 2012

10.1 RandomPkg

No changes

10.2 CoveragePkg

Added bin merging and deletion for overlapping bins.

Working on consistency of naming. Renamed RandCovHole to RandCovBinVal. Renamed GetCovHole to Get-CovBinVal. Old names maintained for backward compatibility.

New Name Old Name Why RandCovBinVal RandCovHole Naming consistency GetCovBinVal GetCovHoleNaming consistency

2.3 - January 2012

11.1 RandomPkg

No changes

11.2 CoveragePkg

Revision 2.3 adds the function GetBin. GetBin is an accessor function that returns a bin in the form of a record.It is only intended for debugging. In particular, the return value of this function may change as the internal datatypes evolve.

2.2 - July 2011

12.1 RandomPkg

Removed ‘_’ in the name of subprograms FavorBig and FavorSmall to make more consistent with other subpro-gram names.

12.2 CoveragePkg

Revision 2.2 adds AtLeast and Weights to the coverage database. The AtLeast value allows individual bins to havea specific coverage goal. A conjunction of the AtLeast and Weight (depending on the WeightMode) are used toweight the random selection of coverage holes. These features are at the heart of intelligent coverage.

2.1 - June 2011

13.1 RandomPkg

Bug fix to convenience functions for slv, unsigned, and signed.

13.2 CoveragePkg

Removed signal based coverage support.

1.1. xx.01.2016 - 2016.01 was release. 87


2.0 - April 2011

14.1 CoveragePkg

Coverage modeled in a protected type.

1.X - June 2010

15.1 CoveragePkg

Coverage modeled in signals of type integer_vector. The signal based coverage methodology is available in thepackage, CoverageSigPkg, however, it is recommended that you use CoveragePkg instead.

Note: This is a local copy of the Artistic License 2.0.

1.1.5 Artistic License 2.0

Copyright © 2000-2006, The Perl Foundation.

Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is notallowed.

Preamble

This license establishes the terms under which a given free software Package may be copied, modified, distributed,and/or redistributed. The intent is that the Copyright Holder maintains some artistic control over the developmentof that Package while still keeping the Package available as open source and free software. You are alwayspermitted to make arrangements wholly outside of this license directly with the Copyright Holder of a givenPackage. If the terms of this license do not permit the full use that you propose to make of the Package, youshould contact the Copyright Holder and seek a different licensing arrangement.

Definitions

“Copyright Holder” means the individual(s) or organization(s) named in the copyright notice for the entirePackage.

“Contributor” means any party that has contributed code or other material to the Package, in accordance withthe Copyright Holder’s procedures.

“You” and “your” means any person who would like to copy, distribute, or modify the Package.

“Package” means the collection of files distributed by the Copyright Holder, and derivatives of that collectionand/or of those files. A given Package may consist of either the Standard Version, or a Modified Version.

“Distribute” means providing a copy of the Package or making it accessible to anyone else, or in the case of acompany or organization, to others outside of your company or organization.

“Distributor Fee” means any fee that you charge for Distributing this Package or providing support for thisPackage to another party. It does not mean licensing fees.

“Standard Version” refers to the Package if it has not been modified, or has been modified only in ways explicitlyrequested by the Copyright Holder.

“Modified Version” means the Package, if it has been changed, and such changes were not explicitly requestedby the Copyright Holder.

“Original License” means this Artistic License as Distributed with the Standard Version of the Package, in itscurrent version or as it may be modified by The Perl Foundation in the future.

88 Chapter 1. News

http://www.perlfoundation.org/artistic_license_2_0


“Source” form means the source code, documentation source, and configuration files for the Package.

“Compiled” form means the compiled bytecode, object code, binary, or any other form resulting from mechanicaltransformation or translation of the Source form.

Permission for Use and Modification Without Distribution

(1) You are permitted to use the Standard Version and create and use Modified Versions for any purpose withoutrestriction, provided that you do not Distribute the Modified Version.

Permissions for Redistribution of the Standard Version

(2) You may Distribute verbatim copies of the Source form of the Standard Version of this Package in any mediumwithout restriction, either gratis or for a Distributor Fee, provided that you duplicate all of the original copyrightnotices and associated disclaimers. At your discretion, such verbatim copies may or may not include a Compiledform of the Package.

(3) You may apply any bug fixes, portability changes, and other modifications made available from the CopyrightHolder. The resulting Package will still be considered the Standard Version, and as such will be subject to theOriginal License.

Distribution of Modified Versions of the Package as Source

(4) You may Distribute your Modified Version as Source (either gratis or for a Distributor Fee, and with or withouta Compiled form of the Modified Version) provided that you clearly document how it differs from the StandardVersion, including, but not limited to, documenting any non-standard features, executables, or modules, and pro-vided that you do at least ONE of the following:

• (a) make the Modified Version available to the Copyright Holder of the Standard Version, under the OriginalLicense, so that the Copyright Holder may include your modifications in the Standard Version.

• (b) ensure that installation of your Modified Version does not prevent the user installing or running theStandard Version. In addition, the Modified Version must bear a name that is different from the name of theStandard Version.

• (c) allow anyone who receives a copy of the Modified Version to make the Source form of the ModifiedVersion available to others under (i) the Original License or (ii) a license that permits the licensee to freelycopy, modify and redistribute the Modified Version using the same licensing terms that apply to the copythat the licensee received, and requires that the Source form of the Modified Version, and of any worksderived from it, be made freely available in that license fees are prohibited but Distributor Fees are allowed.

Distribution of Compiled Forms of the Standard Version or Modified Versions without the Source

(5) You may Distribute Compiled forms of the Standard Version without the Source, provided that you includecomplete instructions on how to get the Source of the Standard Version. Such instructions must be valid at the timeof your distribution. If these instructions, at any time while you are carrying out such distribution, become invalid,you must provide new instructions on demand or cease further distribution. If you provide valid instructions orcease distribution within thirty days after you become aware that the instructions are invalid, then you do notforfeit any of your rights under this license.

(6) You may Distribute a Modified Version in Compiled form without the Source, provided that you comply withSection 4 with respect to the Source of the Modified Version.

Aggregating or Linking the Package

(7) You may aggregate the Package (either the Standard Version or Modified Version) with other packages andDistribute the resulting aggregation provided that you do not charge a licensing fee for the Package. DistributorFees are permitted, and licensing fees for other components in the aggregation are permitted. The terms of thislicense apply to the use and Distribution of the Standard or Modified Versions as included in the aggregation.

1.1. xx.01.2016 - 2016.01 was release. 89


(8) You are permitted to link Modified and Standard Versions with other works, to embed the Package in a largerwork of your own, or to build stand-alone binary or bytecode versions of applications that include the Package,and Distribute the result without restriction, provided the result does not expose a direct interface to the Package.

Items That are Not Considered Part of a Modified Version

(9) Works (including, but not limited to, modules and scripts) that merely extend or make use of the Package, donot, by themselves, cause the Package to be a Modified Version. In addition, such works are not considered partsof the Package itself, and are not subject to the terms of this license.

General Provisions

(10) Any use, modification, and distribution of the Standard or Modified Versions is governed by this ArtisticLicense. By using, modifying or distributing the Package, you accept this license. Do not use, modify, or distributethe Package, if you do not accept this license.

(11) If your Modified Version has been derived from a Modified Version made by someone other than you, youare nevertheless required to ensure that your Modified Version complies with the requirements of this license.

(12) This license does not grant you the right to use any trademark, service mark, tradename, or logo of theCopyright Holder.

(13) This license includes the non-exclusive, worldwide, free-of-charge patent license to make, have made, use,offer to sell, sell, import and otherwise transfer the Package with respect to any patent claims licensable by theCopyright Holder that are necessarily infringed by the Package. If you institute patent litigation (including across-claim or counterclaim) against any party alleging that the Package constitutes direct or contributory patentinfringement, then this Artistic License to you shall terminate on the date that such litigation is filed.

14. Disclaimer of Warranty:

THE PACKAGE IS PROVIDED BY THE COPYRIGHT HOLDER AND CONTRIBUTORS “AS IS’ ANDWITHOUT ANY EXPRESS OR IMPLIED WARRANTIES. THE IMPLIED WARRANTIES OF MER-CHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT ARE DIS-CLAIMED TO THE EXTENT PERMITTED BY YOUR LOCAL LAW. UNLESS REQUIRED BY LAW,NO COPYRIGHT HOLDER OR CONTRIBUTOR WILL BE LIABLE FOR ANY DIRECT, INDIRECT,INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING IN ANY WAY OUT OF THE USE OF THEPACKAGE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

1.1.6 Get Involved

Todo

GitHub issue tracker URL

1.1.7 About the Author - Jim Lewis

Jim Lewis, the founder of SynthWorks, has twenty-eight years of design, teaching, and problem solving experi-ence. In addition to working as a Principal Trainer for SynthWorks, Mr Lewis has done ASIC and FPGA design,custom model development, and consulting.

Mr. Lewis is chair of the IEEE 1076 VHDL Working Group (VASG) and is the primary developer of the OpenSource VHDL Verification Methodology (OSVVM.org) packages. Neither of these activities generate revenue.Please support our volunteer efforts by buying your VHDL training from SynthWorks.

90 Chapter 1. News

osvvm documentation - read the docs · pdf fileosvvm documentation, ... or throw out your...

Documents