Reply To: How does genbin work?

[Jim Lewis]

First, you are using the older, protected type based API. You might want to consider using the newer, singleton based API – it is simpler and does not require the test writer to use protected types (they are hidden internal to the singleton).

If you look at the document, OsvvmLibraries/Documentation/CoveragePkg_user_guide.pdf, you will find GenBin discussed in sections 6.4 and 12.2. Note that these examples are for the newer, singleton based API. For the older, protected type based API, see the documentation in OsvvmLibraries/Documentation/ProtectedType_the_old_way/CovereagePkg_user_guide.pdf.

6.4 Model Coverage: Item Coverage
Internal to the data structure, each bin in an item coverage model is represented by a minimum and maximum value (effectively a range). Bins that have only a single value, such as 1 are represented by the pair 1, 1 (meaning 1 to 1). Internally, the minimum and maximum values are stored in a record with other bin information.
The coverage items are added to the coverage model by using the procedure AddBins and the function GenBin. GenBin transforms a bin descriptor into a set of bins. AddBins inserts these bins into the coverage data structure. 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 ranges 1 to 1, 2 to 2, 3 to 3.

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

Additional calls to AddBins appends 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.
AddBins(Cov1, 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 two parameters: 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.

AddBins(Cov1, GenBin(253, 255)) ; -- bins 253, 254, 255

You will also find more detail in the GenBin section:
12.2 Creating Count Bins – GenBin
The following are three variations of GenBin. The ones with AtLeast and Weight parameters are mainly intended to for use with constants.

  function GenBin(Min, Max, NumBin : integer ) return CovBinType ;
  function GenBin(Min, Max : integer) return CovBinType ;
  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
    AddBins(CovBin1, 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 a result, the call GenBin(1,3,20), will still create the three bins: 1 to 1, 2 to 2 and 3 to 3.
AddBins(CovBin2, 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, then each bin with have on average (max – min + 1)/bins. Later bins will have one more value than earlier bins. The exact 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.
AddBins(CovBin2, 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 be shortened to the following.

--                    min, max
AddBins(CovBin1, GenBin(1,   3));  -- bins 1 to 1, 2 to 2, and 3 to 3

GenBin can also be called with one parameter, the one value that is contained in the bin. Hence the call, GenBin(5) creates a single bin with the range 5 to 5. The following two calls are equivalent.

AddBins(CovBin3, GenBin(5) ) ;
AddBins(CovBin2, GenBin(5,5,1) ) ;  -- equivalent call