1 /* Copyright 2022 Advanced Micro Devices, Inc. 2 * 3 * Permission is hereby granted, free of charge, to any person obtaining a 4 * copy of this software and associated documentation files (the "Software"), 5 * to deal in the Software without restriction, including without limitation 6 * the rights to use, copy, modify, merge, publish, distribute, sublicense, 7 * and/or sell copies of the Software, and to permit persons to whom the 8 * Software is furnished to do so, subject to the following conditions: 9 * 10 * The above copyright notice and this permission notice shall be included in 11 * all copies or substantial portions of the Software. 12 * 13 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 14 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 15 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL 16 * THE COPYRIGHT HOLDER(S) OR AUTHOR(S) BE LIABLE FOR ANY CLAIM, DAMAGES OR 17 * OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, 18 * ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR 19 * OTHER DEALINGS IN THE SOFTWARE. 20 * 21 * Authors: AMD 22 * 23 */ 24 25 #pragma once 26 27 #include "vpe_types.h" 28 #include "vpe_version.h" 29 30 #ifdef __cplusplus 31 extern "C" { 32 #endif 33 34 /* @brief Create the VPE lib instance. 35 * 36 * Caler provides the current asic info, 37 * logging and system memory APIs. 38 * It initializes all the necessary resources for the asic 39 * and returns the general capabilities of the engines. 40 * 41 * For capabilities based on conditions, 42 * shall be done by vpe->cap_funcs.* 43 * 44 * 45 * @param[in] params provide the asic version, APIs for logging and memory 46 * @return vpe instance if supported. NULL otherwise 47 */ 48 struct vpe *vpe_create(const struct vpe_init_data *params); 49 50 /* @brief Destroy the VPE lib instance and resources 51 * 52 * @param[in] vpe the vpe instance created by vpe_create 53 */ 54 void vpe_destroy(struct vpe **vpe); 55 56 /** 57 * @brief Check if the VPE operation is supported. 58 * 59 * Caller must call this to check if the VPE supports 60 * the requested operation before calling vpe_build_commands(). 61 * If operation is supported, it returns the memory requirement. 62 * 63 * The caller has to prepare those required memories 64 * and pass them to the vpe_build_commands(). 65 * 66 * @param[in] vpe vpe instance returned by vpe_initialize() 67 * @param[in] param build params 68 * @param[out] req memory required for the command buffer and 69 embedded data if return VPE_OK. 70 caller has to alloc them and provide it to build_vpbilts API. 71 * @return VPE_OK if supported 72 */ 73 enum vpe_status vpe_check_support( 74 struct vpe *vpe, const struct vpe_build_param *param, struct vpe_bufs_req *req); 75 76 /************************************ 77 * Command building functions 78 ************************************/ 79 /** 80 * Build the command descriptors for No-Op operation 81 * @param[in] vpe vpe instance created by vpe_create() 82 * @param[in] num_dwords number of noops 83 * @param[in,out] ppcmd_space in: dword aligned command buffer start address 84 * out: dword aligned next good write address 85 * @return status 86 */ 87 enum vpe_status vpe_build_noops(struct vpe *vpe, uint32_t num_dwords, uint32_t **ppcmd_space); 88 89 /** 90 * build the command descriptors for the given param. 91 * caller must call vpe_check_support() before this function, 92 * unexpected result otherwise. 93 * 94 * @param[in] vpe vpe instance created by vpe_create() 95 * @param[in] param vpe build params 96 * @param[in,out] bufs [in] memory allocated for the command buffer, embedded buffer and 3dlut. 97 * If size is 0, it reports the required size for this checked 98 * operation. [out] the next write address and the filled sizes. 99 * @return status 100 */ 101 enum vpe_status vpe_build_commands( 102 struct vpe *vpe, const struct vpe_build_param *param, struct vpe_build_bufs *bufs); 103 104 /** 105 * get the optimal number of taps based on the scaling ratio. 106 * @param[in] vpe vpe instance created by vpe_create() 107 * @param[in,out] scaling_info [in] source and destination rectangles [out] calculated taps. 108 */ 109 110 void vpe_get_optimal_num_of_taps(struct vpe *vpe, struct vpe_scaling_info *scaling_info); 111 112 #ifdef __cplusplus 113 } 114 #endif 115