# 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 Manager | Manages the exclusive allocation of consecutive memory locations called regions.
uvm_mem_mam | Memory allocation manager
uvm_mem_region | Allocated memory region descriptor
uvm_mem_mam_policy | An instance of this class is randomized to determine the starting offset of a randomly allocated memory region.
uvm_mem_mam_cfg | Specifies 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_e | Memory allocation mode
locality_e | Location of memory regions
default_alloc | Region allocation policy
new | Create a new manager instance
reconfigure | Reconfigure the manager
Memory Management |
reserve_region | Reserve a specific memory region
request_region | Request and reserve a memory region
release_region | Release the specified region
release_all_regions | Forcibly release all allocated memory regions.
Introspection |
convert2string | Image of the state of the manager
for_each | Iterate over all currently allocated regions
get_memory | Get the managed memory implementation

### Initialization

### alloc_mode_e

Memory allocation mode

Specifies how to allocate a memory region

GREEDY | Consume new, previously unallocated memory
THRIFTY | Reused previously released memory as much as possible (not yet implemented)

### locality_e

Location of memory regions

Specifies where to locate new memory regions

BROAD | Locate new regions randomly throughout the address space
NEARBY | Locate 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_offset | Get the start offset of the region
get_end_offset | Get the end offset of the region
get_len | Size of the memory region
get_n_bytes | Number of bytes in the region
release_region | Release this region
get_memory | Get the memory where the region resides
get_virtual_registers | Get the virtual register array in this region
write | Write to a memory location in the region.
read | Read from a memory location in the region.
burst_write | Write to a set of memory location in the region.
burst_read | Read from a set of memory location in the region.
poke | Deposit in a memory location in the region.
peek | Sample 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 |
len | Number of addresses required
start_offset | The starting offset of the region
min_offset | Minimum address offset in the managed address space
max_offset | Maximum address offset in the managed address space
in_use | Regions 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_bytes | Number of bytes in each memory location
end_offset | Last address of managed space
mode | Region allocation mode
locality | Region 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