aclrtMemManagedAdviseType

1
2
3
4
5
6
7
8

typedef enum aclrtMemManagedAdviseType {
     ACL_MEM_ADVISE_SET_READ_MOSTLY = 0,
     ACL_MEM_ADVISE_UNSET_READ_MOSTLY,
     ACL_MEM_ADVISE_SET_PREFERRED_LOCATION,
     ACL_MEM_ADVISE_UNSET_PREFERRED_LOCATION,
     ACL_MEM_ADVISE_SET_ACCESSED_BY,
     ACL_MEM_ADVISE_UNSET_ACCESSED_BY,
} aclrtMemManagedAdviseType;

The enumerations are described as follows:

• ACL_MEM_ADVISE_SET_READ_MOSTLY

  Sets the memory multi-copy attribute, commonly referred to as the read-mostly attribute.

  If this attribute is set for a UVM memory segment, a read-only memory copy is created for each object (host or device) that accesses the segment, except for the first object to access it. This means a virtual address can have multiple read-only copies. For an object with a read-only memory copy, the page-table mapping from virtual memory to physical memory is established only on the first access. Subsequent accesses do not trigger page fault interrupts, reducing performance overhead.

  However, if a write operation occurs on memory with the read-mostly attribute set, copies on all objects except the one on the writing object become invalid, and the read-mostly attribute is unset. Subsequent accesses will trigger page faults, requiring the system to re-establish the page-table mappings, which affects performance. Therefore, you are advised to set the read-mostly attribute only for UVM memory that is predominantly read-only and rarely written to.

  If ACL_MEM_ADVISE_SET_READ_MOSTLY is set, the location parameter is ignored. In this case, a read-only copy is created on the host, and one copy of data is retained by default.

• ACL_MEM_ADVISE_UNSET_READ_MOSTLY

  Unsets the read-mostly attribute.

  After unsetting, only one memory copy is retained for the UVM memory segment. Which object's memory copy is retained depends on the input location parameter. If an invalid location is passed, the copy on the host is retained. If no copy exists at the specified location, a new copy is created. In addition, memory copies on other objects become invalid, and their corresponding physical memory is freed.

• ACL_MEM_ADVISE_SET_PREFERRED_LOCATION

  Sets the preferred location attribute, indicating whether the host or device is the preferred location for accessing the memory.

  This attribute can be used together with the accessed-by attribute (ACL_MEM_ADVISE_SET_ACCESSED_BY). When both locations are the same, physical memory is allocated in advance and page-table mappings are established to avoid page fault overhead when accessing memory at the preferred location.

  When setting the preferred location attribute, check whether the read-mostly attribute is set.

  • If the read-mostly attribute is not set and the preferred location is the host, the API checks whether the current memory address has been mapped on the device. If yes, an error is returned. If no, the API checks whether the current memory address has been mapped on the host. If mapped, the API returns successfully. If not, the API allocates physical memory and establishes a page-table mapping with the readwrite attribute before returning.
  • If the read-mostly attribute is not set and the preferred location is a specified device, the API checks whether the current address is mapped on the host or other devices. If a mapping exists, an error is returned. If no mapping exists, the API allocates physical memory on the specified device and establishes a page-table mapping with the readwrite attribute before returning.
  • If the read-mostly attribute is set and the preferred location is the host, the API returns successfully without any internal operations.
  • If the read-mostly attribute is set and the preferred location is a specified device, the API checks whether a copy exists on the specified device. If a copy exists, the API returns successfully. If no copy exists, the API creates a read-only copy and then returns.
• ACL_MEM_ADVISE_UNSET_PREFERRED_LOCATION

  Unsets the preferred location attribute.

• ACL_MEM_ADVISE_SET_ACCESSED_BY

  Sets the remote mapping attribute, commonly referred to as the accessed-by attribute.

  This attribute must be used together with the preferred location attribute (ACL_MEM_ADVISE_SET_PREFERRED_LOCATION). When both locations are the same, this attribute is used to allocate physical memory in advance and establish page-table mappings to avoid page fault overhead when accessing memory at the preferred location.

• ACL_MEM_ADVISE_UNSET_ACCESSED_BY

  Unsets the accessed-by attribute.