AI/rocm-systems
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

rocr: Add support for Mipmapped Array (#1847)

Browse Source 
SWDEV-539526 - Add support for Mipmapped Array in Rocr

Add support for Mipmapped Array functionality in Rocr Runtimeenabling GPU applications to work with multi-level texture mipmaps. The implementation introduces new public APIs for creating, querying, and managing mipmapped arrays across different GPU architectures.

Signed-off-by: Apurv Mishra <Apurv.Mishra@amd.com>
Co-authored-by: Shweta Khatri <shweta.khatri@amd.com>
Co-authored-by: taosang2 <tao.sang@amd.com>
This commit is contained in:
Apurv Mishra
2026-01-08 18:14:39 -05:00
committed by GitHub
parent 8b529e7b29
commit be375c2dbf
21 changed files with 2918 additions and 101 deletions
Download Patch File Download Diff File Expand all files Collapse all files
projects/rocr-runtime/runtime/hsa-runtime/inc/hsa_ext_image.h
+191
View File
@@ -356,6 +356,56 @@ typedef struct hsa_ext_image_descriptor_s {
hsa_ext_image_format_t format;
} hsa_ext_image_descriptor_t;
/**
* @brief Implementation independent image descriptor (Version 2).
*
* @details This version adds mipmap support, allowing both regular images
* (mipmap_levels = 0 or 1) and mipmapped arrays (mipmap_levels > 1) to be
* created with a single unified API.
*/
typedef struct hsa_ext_image_descriptor_v2_s {
/**
* Image geometry.
*/
hsa_ext_image_geometry_t geometry;
/**
* Width of the image, in components.
*/
size_t width;
/**
* Height of the image, in components. Only used if the geometry is
* ::HSA_EXT_IMAGE_GEOMETRY_2D, ::HSA_EXT_IMAGE_GEOMETRY_3D,
* HSA_EXT_IMAGE_GEOMETRY_2DA, HSA_EXT_IMAGE_GEOMETRY_2DDEPTH, or
* HSA_EXT_IMAGE_GEOMETRY_2DADEPTH, otherwise must be 0.
*/
size_t height;
/**
* Depth of the image, in components. Only used if the geometry is
* ::HSA_EXT_IMAGE_GEOMETRY_3D, otherwise must be 0.
*/
size_t depth;
/**
* Number of image layers in the image array. Only used if the geometry is
* ::HSA_EXT_IMAGE_GEOMETRY_1DA, ::HSA_EXT_IMAGE_GEOMETRY_2DA, or
* HSA_EXT_IMAGE_GEOMETRY_2DADEPTH, otherwise must be 0.
*/
size_t array_size;
/**
* Image format.
*/
hsa_ext_image_format_t format;
/**
* Number of mipmap levels.
* - 0 or 1: Regular single-level image (default behavior)
* - >1: Mipmapped array with multiple levels
*
* When mipmap_levels > 1, the image is treated as a complete mipmap chain.
* The maximum valid value is determined by the image dimensions and can be
* queried using ::hsa_ext_image_data_get_info_v2.
*/
size_t mipmap_levels;
} hsa_ext_image_descriptor_v2_t;
/**
* @brief Image capability.
*/
@@ -663,6 +713,48 @@ hsa_status_t HSA_API hsa_ext_image_data_get_info_with_layout(
size_t image_data_slice_pitch,
hsa_ext_image_data_info_t *image_data_info);
/**
* @brief Retrieve image data requirements with unified mipmap support (V2 API).
*
* @details This is a unified API that handles both regular images (mipmap_levels = 0 or 1)
* and mipmapped arrays (mipmap_levels > 1).
*
* For regular images:
* - Set image_descriptor->mipmap_levels to 0 or 1
* - Returns size/alignment for a single image level
*
* For mipmapped arrays:
* - Set image_descriptor->mipmap_levels to desired level count (> 1)
* - Returns total size/alignment for all mip levels combined
* - The maximum valid mipmap_levels is computed from image dimensions
*
* @param[in] agent Agent that will access the image.
*
* @param[in] image_descriptor Pointer to a V2 image descriptor. Must not be NULL.
*
* @param[in] access_permission Access permission when the image is accessed by the agent.
*
* @param[out] image_data_info Memory location where the runtime stores the size and
* alignment requirements. Must not be NULL.
*
* @retval ::HSA_STATUS_SUCCESS The function has been executed successfully.
*
* @retval ::HSA_STATUS_ERROR_NOT_INITIALIZED The HSA runtime has not been initialized.
*
* @retval ::HSA_EXT_STATUS_ERROR_IMAGE_FORMAT_UNSUPPORTED The image format is not
* supported for the specified access permission.
*
* @retval ::HSA_EXT_STATUS_ERROR_IMAGE_SIZE_UNSUPPORTED The image dimensions are not
* supported for the specified access permission.
*
* @retval ::HSA_STATUS_ERROR_INVALID_ARGUMENT @p image_descriptor is NULL,
* @p mipmap_levels exceeds maximum for image dimensions, @p access_permission is invalid,
* or @p image_data_info is NULL.
*/
hsa_status_t HSA_API hsa_ext_image_data_get_info_v2(
hsa_agent_t agent, const hsa_ext_image_descriptor_v2_t* image_descriptor,
hsa_access_permission_t access_permission, hsa_ext_image_data_info_t* image_data_info);
/**
* @brief Creates an agent specific image handle to an image with an
* opaque image data layout.
@@ -864,6 +956,105 @@ hsa_status_t HSA_API hsa_ext_image_destroy(
hsa_agent_t agent,
hsa_ext_image_t image);
/**
* @brief Creates an agent specific image handle with unified mipmap support (V2 API).
*
* @details This is a unified API that handles both regular images (mipmap_levels = 0 or 1)
* and mipmapped arrays (mipmap_levels > 1). This simplifies the API surface and aligns
* with modern graphics API conventions where all images are conceptually mipmapped.
*
* For regular images:
* - Set image_descriptor->mipmap_levels to 0 or 1
* - Behavior is identical to ::hsa_ext_image_create
*
* For mipmapped arrays:
* - Set image_descriptor->mipmap_levels to the desired level count (> 1)
* - Behavior is identical to ::hsa_amd_mipmap_array_create
* - The image_data must contain all mip levels laid out sequentially
*
* @param[in] agent Agent to be associated with the image handle created.
*
* @param[in] image_descriptor Pointer to a V2 image descriptor. Must not be NULL.
*
* @param[in] image_data Image data buffer allocated according to size and alignment
* requirements from ::hsa_ext_image_data_get_info_v2. Must not be NULL.
*
* @param[in] access_permission Access permission of the image when accessed by agent.
*
* @param[out] image Pointer to memory location where the HSA runtime stores the
* newly created image handle. Must not be NULL.
*
* @retval ::HSA_STATUS_SUCCESS The function has been executed successfully.
*
* @retval ::HSA_STATUS_ERROR_NOT_INITIALIZED The HSA runtime has not been initialized.
*
* @retval ::HSA_STATUS_ERROR_INVALID_AGENT The agent is invalid.
*
* @retval ::HSA_EXT_STATUS_ERROR_IMAGE_FORMAT_UNSUPPORTED The agent does not support
* the image format for the specified access permission.
*
* @retval ::HSA_EXT_STATUS_ERROR_IMAGE_SIZE_UNSUPPORTED The agent does not support
* the image dimensions for the specified access permission.
*
* @retval ::HSA_STATUS_ERROR_INVALID_ARGUMENT @p image_descriptor is NULL, @p image_data
* is NULL, @p image_data does not have valid alignment, @p access_permission is invalid,
* @p mipmap_levels exceeds maximum for image dimensions, or @p image is NULL.
*
* @retval ::HSA_STATUS_ERROR_OUT_OF_RESOURCES The HSA runtime failed to allocate
* required resources.
*/
hsa_status_t HSA_API hsa_ext_image_create_v2(hsa_agent_t agent,
const hsa_ext_image_descriptor_v2_t* image_descriptor,
const void* image_data,
hsa_access_permission_t access_permission,
hsa_ext_image_t* image);
/**
* @brief Destroys an image handle created with ::hsa_ext_image_create_v2.
*
* @details This function can destroy both regular images and mipmapped arrays
* created with ::hsa_ext_image_create_v2. It does not free the image_data memory,
* which remains the responsibility of the caller.
*
* @param[in] agent Agent associated with the image handle.
*
* @param[in] image Image handle to destroy.
*
* @retval ::HSA_STATUS_SUCCESS The function has been executed successfully.
*
* @retval ::HSA_STATUS_ERROR_NOT_INITIALIZED The HSA runtime has not been initialized.
*
* @retval ::HSA_STATUS_ERROR_INVALID_AGENT The agent is invalid.
*
* @retval ::HSA_STATUS_ERROR_INVALID_ARGUMENT @p image is invalid.
*/
hsa_status_t HSA_API hsa_ext_image_destroy_v2(hsa_agent_t agent, hsa_ext_image_t image);
/**
* @brief Create an image view for a specific mip level of a mipmapped array.
*
* @param[in] agent : GPU agent
* @param[in] mipmapped_array : Pointer to the mipmapped array handle previously
* created by hsa_amd_mipmap_array_create
* @param[in] mip_level : Level index (0 = base). Must be < array's num levels.
* @param[out] level_image_out : Output image handle for the level view
*
* @details
* - Dimensions are clamped to at least 1 when shifting (right shift per level).
* - Row/slice pitches follow underlying layout; for tiled images internal
* SRD setup derives pitches; for linear layout the base pitches may
* be adjusted if required per level (future enhancement).
* - The view inherits access permissions from the parent array.
*
* @retval HSA_STATUS_SUCCESS
* @retval HSA_STATUS_ERROR_INVALID_ARGUMENT (null pointers, bad level, bad handle)
* @retval HSA_STATUS_ERROR_OUT_OF_RESOURCES (allocation of view metadata failed)
*/
hsa_status_t HSA_API hsa_ext_image_mipmap_array_get_level(hsa_agent_t agent,
const hsa_ext_image_t* mipmapped_array,
uint32_t mip_level,
hsa_ext_image_t* level_image_out);
/**
* @brief Copies a portion of one image (the source) to another image (the
* destination).