Memory Allocation Manager

Manages the exclusive allocation of consecutive memory locations called regions.  The regions can subsequently be accessed like little memories of their own, without knowing in which memory or offset they are actually located.

The memory allocation manager should be used by any application-level process that requires reserved space in the memory, such as DMA buffers.

A region will remain reserved until it is explicitly released.

Contents
Memory Allocation ManagerManages the exclusive allocation of consecutive memory locations called regions.
uvm_mem_mamMemory allocation manager
uvm_mem_regionAllocated memory region descriptor
uvm_mem_mam_policyAn instance of this class is randomized to determine the starting offset of a randomly allocated memory region.
uvm_mem_mam_cfgSpecifies the memory managed by an instance of a uvm_mem_mam memory allocation manager class.

uvm_mem_mam

Memory allocation manager

Memory allocation management utility class similar to C’s malloc() and free().  A single instance of this class is used to manage a single, contiguous address space.

Summary
uvm_mem_mam
Memory allocation manager
Class Declaration
class uvm_mem_mam
Initialization
alloc_mode_eMemory allocation mode
locality_eLocation of memory regions
default_allocRegion allocation policy
newCreate a new manager instance
reconfigureReconfigure the manager
Memory Management
reserve_regionReserve a specific memory region
request_regionRequest and reserve a memory region
release_regionRelease the specified region
release_all_regionsForcibly release all allocated memory regions.
Introspection
convert2stringImage of the state of the manager
for_eachIterate over all currently allocated regions
get_memoryGet the managed memory implementation

Initialization

alloc_mode_e

Memory allocation mode

Specifies how to allocate a memory region

GREEDYConsume new, previously unallocated memory
THRIFTYReused previously released memory as much as possible (not yet implemented)

locality_e

Location of memory regions

Specifies where to locate new memory regions

BROADLocate new regions randomly throughout the address space
NEARBYLocate new regions adjacent to existing regions

default_alloc

uvm_mem_mam_policy default_alloc

Region allocation policy

This object is repeatedly randomized when allocating new regions.

new

function new(
    string  name,   
    uvm_mem_mam_cfg  cfg,   
    uvm_mem  mem  =  null
)

Create a new manager instance

Create an instance of a memory allocation manager with the specified name and configuration.  This instance manages all memory region allocation within the address range specified in the configuration descriptor.

If a reference to a memory abstraction class is provided, the memory locations within the regions can be accessed through the region descriptor, using the uvm_mem_region::read() and uvm_mem_region::write() methods.

reconfigure

function uvm_mem_mam_cfg reconfigure(
    uvm_mem_mam_cfg  cfg  =  null
)

Reconfigure the manager

Modify the maximum and minimum addresses of the address space managed by the allocation manager, allocation mode, or locality.  The number of bytes per memory location cannot be modified once an allocation manager has been constructed.  All currently allocated regions must fall within the new address space.

Returns the previous configuration.

if no new configuration is specified, simply returns the current configuration.

Memory Management

reserve_region

function uvm_mem_region reserve_region(
    bit  [63:0]  start_offset,   
    int  unsigned  n_bytes,   
    string  fname  =  "",
    int  lineno  =  0
)

Reserve a specific memory region

Reserve a memory region of the specified number of bytes starting at the specified offset.  A descriptor of the reserved region is returned.  If the specified region cannot be reserved, null is returned.

It may not be possible to reserve a region because it overlaps with an already-allocated region or it lies outside the address range managed by the memory manager.

Regions can be reserved to create “holes” in the managed address space.

request_region

function uvm_mem_region request_region(
    int  unsigned  n_bytes,   
    uvm_mem_mam_policy  alloc  =  null,
    string  fname  =  "",
    int  lineno  =  0
)

Request and reserve a memory region

Request and reserve a memory region of the specified number of bytes starting at a random location.  If an policy is specified, it is randomized to determine the start offset of the region.  If no policy is specified, the policy found in the uvm_mem_mam::default_alloc class property is randomized.

A descriptor of the allocated region is returned.  If no region can be allocated, null is returned.

It may not be possible to allocate a region because there is no area in the memory with enough consecutive locations to meet the size requirements or because there is another contradiction when randomizing the policy.

If the memory allocation is configured to THRIFTY or NEARBY, a suitable region is first sought procedurally.

release_region

function void release_region(
    uvm_mem_region  region
)

Release the specified region

Release a previously allocated memory region.  An error is issued if the specified region has not been previously allocated or is no longer allocated.

release_all_regions

function void release_all_regions()

Forcibly release all allocated memory regions.

Introspection

convert2string

function string convert2string()

Image of the state of the manager

Create a human-readable description of the state of the memory manager and the currently allocated regions.

for_each

function uvm_mem_region for_each(
    bit  reset  =  0
)

Iterate over all currently allocated regions

If reset is TRUE, reset the iterator and return the first allocated region.  Returns null when there are no additional allocated regions to iterate on.

get_memory

function uvm_mem get_memory()

Get the managed memory implementation

Return the reference to the memory abstraction class for the memory implementing the locations managed by this instance of the allocation manager.  Returns null if no memory abstraction class was specified at construction time.

uvm_mem_region

Allocated memory region descriptor

Each instance of this class describes an allocated memory region.  Instances of this class are created only by the memory manager, and returned by the uvm_mem_mam::reserve_region() and uvm_mem_mam::request_region() methods.

Summary
uvm_mem_region
Allocated memory region descriptor
Class Declaration
class uvm_mem_region
Methods
get_start_offsetGet the start offset of the region
get_end_offsetGet the end offset of the region
get_lenSize of the memory region
get_n_bytesNumber of bytes in the region
release_regionRelease this region
get_memoryGet the memory where the region resides
get_virtual_registersGet the virtual register array in this region
writeWrite to a memory location in the region.
readRead from a memory location in the region.
burst_writeWrite to a set of memory location in the region.
burst_readRead from a set of memory location in the region.
pokeDeposit in a memory location in the region.
peekSample a memory location in the region.

Methods

get_start_offset

function bit [63:0] get_start_offset()

Get the start offset of the region

Return the address offset, within the memory, where this memory region starts.

get_end_offset

function bit [63:0] get_end_offset()

Get the end offset of the region

Return the address offset, within the memory, where this memory region ends.

get_len

function int unsigned get_len()

Size of the memory region

Return the number of consecutive memory locations (not necessarily bytes) in the allocated region.

get_n_bytes

function int unsigned get_n_bytes()

Number of bytes in the region

Return the number of consecutive bytes in the allocated region.  If the managed memory contains more than one byte per address, the number of bytes in an allocated region may be greater than the number of requested or reserved bytes.

release_region

function void release_region()

Release this region

get_memory

function uvm_mem get_memory()

Get the memory where the region resides

Return a reference to the memory abstraction class for the memory implementing this allocated memory region.  Returns null if no memory abstraction class was specified for the allocation manager that allocated this region.

get_virtual_registers

function uvm_vreg get_virtual_registers()

Get the virtual register array in this region

Return a reference to the virtual register array abstraction class implemented in this region.  Returns null if the memory region is not known to implement virtual registers.

write

task write(
    output  uvm_status_e  status,   
    input  uvm_reg_addr_t  offset,   
    input  uvm_reg_data_t  value,   
    input  uvm_path_e  path  =  UVM_DEFAULT_PATH,
    input  uvm_reg_map  map  =  null,
    input  uvm_sequence_base  parent  =  null,
    input  int  prior  =  -1,
    input  uvm_object  extension  =  null,
    input  string  fname  =  "",
    input  int  lineno  =  0
)

Write to a memory location in the region.

Write to the memory location that corresponds to the specified offset within this region.  Requires that the memory abstraction class be associated with the memory allocation manager that allocated this region.

See uvm_mem::write() for more details.

read

task read(
    output  uvm_status_e  status,   
    input  uvm_reg_addr_t  offset,   
    output  uvm_reg_data_t  value,   
    input  uvm_path_e  path  =  UVM_DEFAULT_PATH,
    input  uvm_reg_map  map  =  null,
    input  uvm_sequence_base  parent  =  null,
    input  int  prior  =  -1,
    input  uvm_object  extension  =  null,
    input  string  fname  =  "",
    input  int  lineno  =  0
)

Read from a memory location in the region.

Read from the memory location that corresponds to the specified offset within this region.  Requires that the memory abstraction class be associated with the memory allocation manager that allocated this region.

See uvm_mem::read() for more details.

burst_write

task burst_write(
    output  uvm_status_e  status,   
    input  uvm_reg_addr_t  offset,   
    input  uvm_reg_data_t  value[],   
    input  uvm_path_e  path  =  UVM_DEFAULT_PATH,
    input  uvm_reg_map  map  =  null,
    input  uvm_sequence_base  parent  =  null,
    input  int  prior  =  -1,
    input  uvm_object  extension  =  null,
    input  string  fname  =  "",
    input  int  lineno  =  0
)

Write to a set of memory location in the region.

Write to the memory locations that corresponds to the specified burst within this region.  Requires that the memory abstraction class be associated with the memory allocation manager that allocated this region.

See uvm_mem::burst_write() for more details.

burst_read

task burst_read(
    output  uvm_status_e  status,   
    input  uvm_reg_addr_t  offset,   
    output  uvm_reg_data_t  value[],   
    input  uvm_path_e  path  =  UVM_DEFAULT_PATH,
    input  uvm_reg_map  map  =  null,
    input  uvm_sequence_base  parent  =  null,
    input  int  prior  =  -1,
    input  uvm_object  extension  =  null,
    input  string  fname  =  "",
    input  int  lineno  =  0
)

Read from a set of memory location in the region.

Read from the memory locations that corresponds to the specified burst within this region.  Requires that the memory abstraction class be associated with the memory allocation manager that allocated this region.

See uvm_mem::burst_read() for more details.

poke

task poke(
    output  uvm_status_e  status,   
    input  uvm_reg_addr_t  offset,   
    input  uvm_reg_data_t  value,   
    input  uvm_sequence_base  parent  =  null,
    input  uvm_object  extension  =  null,
    input  string  fname  =  "",
    input  int  lineno  =  0
)

Deposit in a memory location in the region.

Deposit the specified value in the memory location that corresponds to the specified offset within this region.  Requires that the memory abstraction class be associated with the memory allocation manager that allocated this region.

See uvm_mem::poke() for more details.

peek

task peek(
    output  uvm_status_e  status,   
    input  uvm_reg_addr_t  offset,   
    output  uvm_reg_data_t  value,   
    input  uvm_sequence_base  parent  =  null,
    input  uvm_object  extension  =  null,
    input  string  fname  =  "",
    input  int  lineno  =  0
)

Sample a memory location in the region.

Sample the memory location that corresponds to the specified offset within this region.  Requires that the memory abstraction class be associated with the memory allocation manager that allocated this region.

See uvm_mem::peek() for more details.

uvm_mem_mam_policy

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, such as word alignment or location of the region within a memory page.  If a procedural region allocation policy is required, it can be implemented in the pre/post_randomize() method.

Summary
uvm_mem_mam_policy
An instance of this class is randomized to determine the starting offset of a randomly allocated memory region.
Class Declaration
class uvm_mem_mam_policy
Variables
lenNumber of addresses required
start_offsetThe starting offset of the region
min_offsetMinimum address offset in the managed address space
max_offsetMaximum address offset in the managed address space
in_useRegions already allocated in the managed address space

Variables

len

int unsigned len

Number of addresses required

start_offset

rand bit [63:0] start_offset

The starting offset of the region

min_offset

bit [63:0] min_offset

Minimum address offset in the managed address space

max_offset

bit [63:0] max_offset

Maximum address offset in the managed address space

in_use

uvm_mem_region in_use[$]

Regions already allocated in the managed address space

uvm_mem_mam_cfg

Specifies the memory managed by an instance of a uvm_mem_mam memory allocation manager class.

Summary
uvm_mem_mam_cfg
Specifies the memory managed by an instance of a uvm_mem_mam memory allocation manager class.
Class Declaration
class uvm_mem_mam_cfg
Variables
n_bytesNumber of bytes in each memory location
end_offsetLast address of managed space
modeRegion allocation mode
localityRegion location mode

Variables

n_bytes

rand int unsigned n_bytes

Number of bytes in each memory location

end_offset

rand bit [63:0] end_offset

Last address of managed space

mode

rand uvm_mem_mam::alloc_mode_e mode

Region allocation mode

locality

rand uvm_mem_mam::locality_e locality

Region location mode

class uvm_mem_mam
Memory allocation manager
class uvm_mem_region
Allocated memory region descriptor
class uvm_mem_mam_policy
An instance of this class is randomized to determine the starting offset of a randomly allocated memory region.
class uvm_mem_mam_cfg
Specifies the memory managed by an instance of a uvm_mem_mam memory allocation manager class.
uvm_mem_mam_policy default_alloc
Region allocation policy
function new(
    string  name,   
    uvm_mem_mam_cfg  cfg,   
    uvm_mem  mem  =  null
)
Create a new manager instance
function uvm_mem_mam_cfg reconfigure(
    uvm_mem_mam_cfg  cfg  =  null
)
Reconfigure the manager
function uvm_mem_region reserve_region(
    bit  [63:0]  start_offset,   
    int  unsigned  n_bytes,   
    string  fname  =  "",
    int  lineno  =  0
)
Reserve a specific memory region
function uvm_mem_region request_region(
    int  unsigned  n_bytes,   
    uvm_mem_mam_policy  alloc  =  null,
    string  fname  =  "",
    int  lineno  =  0
)
Request and reserve a memory region
function void release_region(
    uvm_mem_region  region
)
Release the specified region
function void release_all_regions()
Forcibly release all allocated memory regions.
function string convert2string()
Image of the state of the manager
function uvm_mem_region for_each(
    bit  reset  =  0
)
Iterate over all currently allocated regions
function uvm_mem get_memory()
Get the managed memory implementation
task read(
    output  uvm_status_e  status,   
    input  uvm_reg_addr_t  offset,   
    output  uvm_reg_data_t  value,   
    input  uvm_path_e  path  =  UVM_DEFAULT_PATH,
    input  uvm_reg_map  map  =  null,
    input  uvm_sequence_base  parent  =  null,
    input  int  prior  =  -1,
    input  uvm_object  extension  =  null,
    input  string  fname  =  "",
    input  int  lineno  =  0
)
Read from a memory location in the region.
task write(
    output  uvm_status_e  status,   
    input  uvm_reg_addr_t  offset,   
    input  uvm_reg_data_t  value,   
    input  uvm_path_e  path  =  UVM_DEFAULT_PATH,
    input  uvm_reg_map  map  =  null,
    input  uvm_sequence_base  parent  =  null,
    input  int  prior  =  -1,
    input  uvm_object  extension  =  null,
    input  string  fname  =  "",
    input  int  lineno  =  0
)
Write to a memory location in the region.
function bit [63:0] get_start_offset()
Get the start offset of the region
function bit [63:0] get_end_offset()
Get the end offset of the region
function int unsigned get_len()
Size of the memory region
function int unsigned get_n_bytes()
Number of bytes in the region
function void release_region()
Release this region
function uvm_mem get_memory()
Get the memory where the region resides
function uvm_vreg get_virtual_registers()
Get the virtual register array in this region
task burst_write(
    output  uvm_status_e  status,   
    input  uvm_reg_addr_t  offset,   
    input  uvm_reg_data_t  value[],   
    input  uvm_path_e  path  =  UVM_DEFAULT_PATH,
    input  uvm_reg_map  map  =  null,
    input  uvm_sequence_base  parent  =  null,
    input  int  prior  =  -1,
    input  uvm_object  extension  =  null,
    input  string  fname  =  "",
    input  int  lineno  =  0
)
Write to a set of memory location in the region.
task burst_read(
    output  uvm_status_e  status,   
    input  uvm_reg_addr_t  offset,   
    output  uvm_reg_data_t  value[],   
    input  uvm_path_e  path  =  UVM_DEFAULT_PATH,
    input  uvm_reg_map  map  =  null,
    input  uvm_sequence_base  parent  =  null,
    input  int  prior  =  -1,
    input  uvm_object  extension  =  null,
    input  string  fname  =  "",
    input  int  lineno  =  0
)
Read from a set of memory location in the region.
task poke(
    output  uvm_status_e  status,   
    input  uvm_reg_addr_t  offset,   
    input  uvm_reg_data_t  value,   
    input  uvm_sequence_base  parent  =  null,
    input  uvm_object  extension  =  null,
    input  string  fname  =  "",
    input  int  lineno  =  0
)
Deposit in a memory location in the region.
task peek(
    output  uvm_status_e  status,   
    input  uvm_reg_addr_t  offset,   
    output  uvm_reg_data_t  value,   
    input  uvm_sequence_base  parent  =  null,
    input  uvm_object  extension  =  null,
    input  string  fname  =  "",
    input  int  lineno  =  0
)
Sample a memory location in the region.
virtual task write(
    output  uvm_status_e  status,   
    input  uvm_reg_addr_t  offset,   
    input  uvm_reg_data_t  value,   
    input  uvm_path_e  path  =  UVM_DEFAULT_PATH,
    input  uvm_reg_map  map  =  null,
    input  uvm_sequence_base  parent  =  null,
    input  int  prior  =  -1,
    input  uvm_object  extension  =  null,
    input  string  fname  =  "",
    input  int  lineno  =  0
)
Write the specified value in a memory location
virtual task read(
    output  uvm_status_e  status,   
    input  uvm_reg_addr_t  offset,   
    output  uvm_reg_data_t  value,   
    input  uvm_path_e  path  =  UVM_DEFAULT_PATH,
    input  uvm_reg_map  map  =  null,
    input  uvm_sequence_base  parent  =  null,
    input  int  prior  =  -1,
    input  uvm_object  extension  =  null,
    input  string  fname  =  "",
    input  int  lineno  =  0
)
Read the current value from a memory location
virtual task burst_write(
    output  uvm_status_e  status,   
    input  uvm_reg_addr_t  offset,   
    input  uvm_reg_data_t  value[],   
    input  uvm_path_e  path  =  UVM_DEFAULT_PATH,
    input  uvm_reg_map  map  =  null,
    input  uvm_sequence_base  parent  =  null,
    input  int  prior  =  -1,
    input  uvm_object  extension  =  null,
    input  string  fname  =  "",
    input  int  lineno  =  0
)
Write the specified values in memory locations
virtual task burst_read(
    output  uvm_status_e  status,   
    input  uvm_reg_addr_t  offset,   
    ref  uvm_reg_data_t  value[],   
    input  uvm_path_e  path  =  UVM_DEFAULT_PATH,
    input  uvm_reg_map  map  =  null,
    input  uvm_sequence_base  parent  =  null,
    input  int  prior  =  -1,
    input  uvm_object  extension  =  null,
    input  string  fname  =  "",
    input  int  lineno  =  0
)
Read values from memory locations
virtual task poke(
    output  uvm_status_e  status,   
    input  uvm_reg_addr_t  offset,   
    input  uvm_reg_data_t  value,   
    input  string  kind  =  "",
    input  uvm_sequence_base  parent  =  null,
    input  uvm_object  extension  =  null,
    input  string  fname  =  "",
    input  int  lineno  =  0
)
Deposit the specified value in a memory location
virtual task peek(
    output  uvm_status_e  status,   
    input  uvm_reg_addr_t  offset,   
    output  uvm_reg_data_t  value,   
    input  string  kind  =  "",
    input  uvm_sequence_base  parent  =  null,
    input  uvm_object  extension  =  null,
    input  string  fname  =  "",
    input  int  lineno  =  0
)
Read the current value from a memory location
int unsigned len
Number of addresses required
rand bit [63:0] start_offset
The starting offset of the region
bit [63:0] min_offset
Minimum address offset in the managed address space
bit [63:0] max_offset
Maximum address offset in the managed address space
uvm_mem_region in_use[$]
Regions already allocated in the managed address space
rand int unsigned n_bytes
Number of bytes in each memory location
rand bit [63:0] end_offset
Last address of managed space
rand uvm_mem_mam::alloc_mode_e mode
Region allocation mode
rand uvm_mem_mam::locality_e locality
Region location mode