MAM example

VMM application package offers capability to dynamically manage memory shared between multiple 
clients via Memory Allocation Manager (MAM). MAM helps to simulate HW memory usage patterns and 
guarantees memory block allocation based on constraints. This utility is a set of four base 
classes with configurable memory address range and allocation scheme.


1. vmm_cfg: This class is used to specify the memory managed by an instance of a "vmm_mam" 
memory allocation manager class.


2. vmm_mam: This class is a memory allocation management utility similar to C's malloc() and 
free(). A single instance of this class is used to manage a single, contiguous address space.


3. vmm_mam_allocator: An instance of this class is randomized to determine the starting offset 
of a randomly allocated memory region. This class can be extended to provide additional 
constraints on the starting offset.


4. vmm_mam_region: This class is used by the memory allocation manager to describe allocated 
memory regions. Instances of this class should not be created directly.




VMM MAM Flow:


* "vmm_mam" class uses "vmm_cfg" class handle to determine the minimum, maximum addresses 
and difference allocation schemes (mode and locality) of a memory space. A memory space can 
be reconfigured with new min, max and allocation scheme at run-time through "vmm_cfg" class 
with exception that number of bytes per memory location cannot be modified once a "vmm_mam" 
instance has been constructed and all currently allocated regions must fall within the new 
address space.
 
* On every call of request_region() function "vmm_mam" randomize "vmm_mam_allocator" instance 
to determine start_offset of randomly allocated memory region. This region is represented by 
an instance of "vmm_mam_region" class.


* Now if this "vmm_mam" is associated with a "vmm_ral_mem" instance, randomly allocation 
"vmm_mam_region" can be used to perform read/write operation on actual memory block.




In cases default selection constraints work fines but user might want to add new variables 
to "vmm_mam_region" and has additionally constraints (in "vmm_mam_allocator") to start_offset 
of memory region. Also for debugging purpose it could be require printing out values of user 
defined variables along with address range of randomly allocated region. The attached example 
demonstrates three possible user requirements:


1. Additional constraints over start_offset by adding new variables.
   This can be easily done by extending "vmm_mam_allocator" class and then pass instance of extended 
class to vmm_mam::request_region() function to replace default allocator.


   class cust_allocator extends vmm_mam_allocator;
     bus_width attribute;
     ...
     constraint cust_allocator_attri{
       (this.attribute==BIT16)->this.start_offset[0:0]==1'b0;
     ...




2. Has a customized vmm_mam::request_region() function which can take user defined variables as 
input arguments to constraint "vmm_mam_region" allocation.
   In this example customized vmm_mam::request_region() got a wrapper around it to have user defined 
variables as argument. Internally it construct a allocator and calls super.request_region(). User 
vmm_mam class keep a track of allocated regions which will get queried while calling release_region().


   class cust_mam extends vmm_mam;
     function cust_mam_region cust_request_region(bus_width attribute=...);
       ...
       region=super.request_region(...);
       cust_request_region = new(region.get_start_offset(),...);
       ...
       this.cust_in_use.push_back(cust_request_region);
     ...


     function void release_region(cust_mam_region cust_region);
       ...
       foreach(this.in_use[i]) begin
         ... 
         super.release_region(this.in_use[i]);
         this.cust_in_use.delete(i);
   ...




3. Adding new variables to "vmm_mam_region" and overwrite psdisplay() of  "vmm_mam" and "vmm_mam_region" 
to print out values of these variable for debugging purpose.
   These variables (in example owner for a memory region) are added by extending "vmm_mam_region" and 
populated in extension of "vmm_mam" after getting a "vmm_mam_region" from request_region() function. 
Even instances of new "mam_region" class should not be created directly. Both vmm_mam_region::psdisplay() 
and vmm_mam::psdisplay() needs to be overridden for this purpose. In vmm_mam_region::psdisplay() print 
values of user variables and then just call super.psdisplay(). New implementation of  vmm_mam::psdisplay()
will just call psdisplay() for all allocated regions.


   class cust_mam_region extends vmm_mam_region;
     function string psdisplay(string prefix = "");
       ... 
       psdisplay ={$psprintf("[%s]: ",attribute.name),
       $psprintf("[%s]",super.psdisplay())};
   ...


   class cust_mam extends vmm_mam;
     function string psdisplay(string prefix="");
       foreach (this.cust_in_use[i]) begin
       $sformat(psdisplay, "%s%s   %s\n", psdisplay, prefix, this.cust_in_use[i].psdisplay());
   ...




Adding only constraint to start_offset is very simple in MAM as explain above and doesn't need extension 
of any class other than "vmm_mam_allocator". Adding user define variables requires overriding of few 
functions, as shown in example, and rest can be used at it is. There is absolutely no change in use model.




Example:
MAM is build inside vmm_subenv to re-use it from block level to system level. Note that a memory does NOT 
actually exist in this example. The intent of the example is to show the how MAM can be customized to 
have additional constraints and user variables.  Attached tarball (mam.tar.gz).




To run it:
>  make run


At first 10 regions will be allocated, then after releasing all these regions MAM is reconfigured to new 
min/max addresses and again allocates new regions. Regions are requested on the basic of allocator 
instance or by the custom made function which takes user variables as arguments.




Cust_mam.sv
This file has customized classes extended from vmm_mam_region, vmm_mam and vmm_mam_allocator.




tb_subenv.sv
Subenv access vmm_mam handle via constructor and exercise all MAM function/tasks.