Ability to query free memory without using SYSMAN (#395)

* Add extension ze_device_memory_ext_usablemem_limit_t to memory properties structure to track usable memory.
* Correct documentation in sysman to indicate tracking physical memory instead of allocatable memory and
   deprecate the use of size field in the zes_mem_state_t structure to gather usable memory information.
* Correct documentation for physicalSize field in zes_mem_properties_t
* add usable memory extension to the extension memory properties documentation.

Author: pbg-intel

scripts/core/EXT_DeviceUsablememProperties.rst

@@ -0,0 +1,57 @@
+<%
+import re
+from templates import helper as th
+%><%
+    OneApi=tags['$OneApi']
+    x=tags['$x']
+    X=x.upper()
+%>
+:orphan:
+
+.. _ZE_extension_device_usablemem_size_properties:
+
+======================================
+ Device Usable Memory Size Properties Extension
+======================================
+
+API
+----
+
+* Enumerations
+
+
+    * ${x}_device_usablemem_size_properties_ext_version_t
+
+
+* Structures
+
+    * ${x}_device_usablemem_size_ext_properties_t
+
+
+Extended Device Properties
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Users may wish get the status of the available allocatable/usable memory. Since this is a transient information based on the overall state of the device usage, user would need to invoke the extension to obtain the information at each point of interest. This extension provides extended information about the usable memory size available as part of the device. The extension introduces the ${x}_device_usablemem_size_ext_properties_t struct which can be passed to $xDeviceGetProperties via the `pNext` member of $x_device_properties_t.
+
+The following psuedo-code demonstrates a sequence for obtaining extended information about the usable memory size 
+
+.. parsed-literal::
+
+       ...
+        // Discover properties on device
+        //Driver handle ze_driver_handle_t Driverh obtained through previous call to zeInitDrivers
+        //Obtain Device handle ze_device_handle_t Deviceh
+        //zeDeviceGet(Driverh, 1, Deviceh);
+
+        ze_device_properties_t deviceProperties {};
+        ${x}_device_usablemem_size_ext_properties_t* pUsablememProps = allocate(sizeof(${x}_device_usablemem_size_ext_properties_t));
+
+        pUsablememProps.stype =  ZE_STRUCTURE_TYPE_DEVICE_USABLEMEM_SIZE_EXT_PROPERTIES;
+        deviceProperties.stype = ZE_STRUCTURE_TYPE_DEVICE_PROPERTIES;
+        deviceProperties.pNext = pUsablememProps;
+        
+        //obtain device and extended memory properties
+        zeDeviceGetProperties(Deviceh, &deviceProperties);
+
+
+

scripts/core/common.yml

@@ -685,6 +685,10 @@ etors:
       desc: $x_physical_mem_properties_t
       version: "1.15"
       value: "0x00020040"
+    - name: DEVICE_USABLEMEM_SIZE_EXT_PROPERTIES
+      desc: $x_device_usablemem_size_ext_properties_t
+      version: "1.15"
+      value: "0x00020041"
 --- #--------------------------------------------------------------------------
 type: enum
 desc: "External memory type flags"

scripts/core/deviceusablememproperties.yml

@@ -0,0 +1,32 @@
+--- #--------------------------------------------------------------------------
+type: header
+desc: "Intel $OneApi Level-Zero Extension APIs for Device UsableMem Size Properties Extension"
+version: "1.15"
+--- #--------------------------------------------------------------------------
+type: macro
+desc: "Device Usable Memory Size Properties Extension Name"
+version: "1.15"
+name: $X_DEVICE_USABLEMEM_SIZE_PROPERTIES_EXT_NAME
+value: '"$X_extension_device_usablemem_size_properties"'
+--- #--------------------------------------------------------------------------
+type: enum
+desc: "Device Usable Mem Size  Extension Version(s)"
+version: "1.15"
+name: $x_device_usablemem_size_properties_ext_version_t
+etors:
+    - name: "1_0"
+      value: "$X_MAKE_VERSION( 1, 0 )"
+      desc: "version 1.0"
+--- #--------------------------------------------------------------------------
+type: struct
+desc: "Memory access property to discover current status of usable memory"
+version: "1.15"
+class: $xDevice
+name: $x_device_usablemem_size_ext_properties_t
+base: $x_base_properties_t
+members:
+    - type: uint64_t
+      name: currUsableMemSize
+      desc: "[out] Returns the available usable memory at the device level. This is typically less than or equal to the available physical memory on the device. It important to note that usable memory size reported is transient in nature and cannot be used to reliably guarentee success of future allocations. The usable memory includes all the memory that the clients can allocate for their use and by L0 Core for its internal allocations."
+details:
+    - "This structure may be returned from $xDeviceGetProperties via the `pNext` member of $x_device_properties_t"

scripts/sysman/memory.yml

@@ -104,7 +104,7 @@ members:
       desc: "[out] Location of this memory (system, device)"
     - type: uint64_t
       name: physicalSize
-      desc: "[out] Physical memory size in bytes. A value of 0 indicates that this property is not known. However, a call to $sMemoryGetState() will correctly return the total size of usable memory."
+      desc: "[out] Physical memory capacity in bytes. A value of 0 indicates that this property is not known. However, a call to zesMemoryGetState() will return the available free physical memory."
     - type: int32_t
       name: busWidth
       desc: "[out] Width of the memory bus. A value of -1 means that this property is unknown."
@@ -118,18 +118,20 @@ class: $sMemory
 name: $s_mem_state_t
 base: $s_base_state_t
 details:
-    - "Percent allocation is given by 100 * (size - free / size."
-    - "Percent free is given by 100 * free / size."
+    - "Percent free is given by 100 * free / pysical mem size."
 members:
     - type: $s_mem_health_t
       name: health
       desc: "[out] Indicates the health of the memory"
     - type: uint64_t
       name: free
-      desc: "[out] The free memory in bytes"
+      desc: "[out] The free physical memory in bytes"
     - type: uint64_t
       name: size
-      desc: "[out] The total allocatable memory in bytes (can be less than the `physicalSize` member of $s_mem_properties_t)"
+      desc: |
+            [out] The total allocatable memory in bytes (can be less than the `physicalSize` member of $s_mem_properties_t). *DEPRECATED* 
+             This member can no longer track the allocatable memory reliably. Clients depending on this information can use the 
+             zeDeviceGetMemoryProperties with  ze_device_usablemem_size_ext_properties_t extention to get information of the available usable memory.
 --- #--------------------------------------------------------------------------
 type: struct
 desc: "Memory bandwidth"