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 /** @mainpage VPELIB 26 * @section intro_sec Introduction 27 * 28 * VPE is a hardware pipeline that does baseline video processing from DRAM to DRAM. 29 * The objective of VPE is to offload the graphic workload to VPE to save power. 30 * The main functionality of VPE is to read video stream from memory, process the video stream and 31 * write it back to memory. VPE is meant to augment the abilities of both the graphics (GFX) and 32 * multi plane overlay (MPO) and deliver more power efficient use cases. 33 * 34 * 35 * @section main_api Main API Functions 36 * @subsection create VPE Create 37 * @link vpe_create @endlink 38 * @subsection destroy VPE Destroy 39 * @link vpe_destroy @endlink 40 * @subsection check_support VPE Check Support 41 * @link vpe_check_support @endlink 42 * @subsection vpe_build_noops VPE Build No-Operation Commands 43 * @link vpe_build_noops @endlink 44 * @subsection build_commands VPE Build Commands 45 * @link vpe_build_commands @endlink 46 * @subsection get_optimal_num_of_taps VPE Get the Optimal Number of Taps 47 * @link vpe_get_optimal_num_of_taps @endlink 48 * @file vpelib.h 49 * @brief This is the file containing the main API for the VPE library. 50 * 51 */ 52 53 #pragma once 54 55 #include "vpe_types.h" 56 #include "vpe_version.h" 57 58 #ifdef __cplusplus 59 extern "C" { 60 #endif 61 62 /** @brief Create the VPE lib instance. 63 * 64 * Caler provides the current asic info, 65 * logging and system memory APIs. 66 * It initializes all the necessary resources for the asic 67 * and returns the general capabilities of the engines. 68 * 69 * For capabilities based on conditions, 70 * shall be done by vpe->cap_funcs.* 71 * 72 * 73 * @param[in] params provide the asic version, APIs for logging and memory 74 * @return vpe instance if supported. NULL otherwise 75 */ 76 struct vpe *vpe_create(const struct vpe_init_data *params); 77 78 /** @brief Destroy the VPE lib instance and resources 79 * 80 * @param[in] vpe the vpe instance created by vpe_create 81 */ 82 void vpe_destroy(struct vpe **vpe); 83 84 /** 85 * @brief Check if the VPE operation is supported. 86 * 87 * Caller must call this to check if the VPE supports 88 * the requested operation before calling vpe_build_commands(). 89 * If operation is supported, it returns the memory requirement. 90 * 91 * The caller has to prepare those required memories 92 * and pass them to the vpe_build_commands(). 93 * 94 * @param[in] vpe vpe instance returned by vpe_initialize() 95 * @param[in] param build params 96 * @param[out] req memory required for the command buffer and 97 embedded data if return VPE_OK. 98 caller has to alloc them and provide it to build_vpbilts API. 99 * @return VPE_OK if supported 100 */ 101 enum vpe_status vpe_check_support( 102 struct vpe *vpe, const struct vpe_build_param *param, struct vpe_bufs_req *req); 103 104 /************************************ 105 * Command building functions 106 ************************************/ 107 /** 108 * Build the command descriptors for No-Op operation 109 * @param[in] vpe vpe instance created by vpe_create() 110 * @param[in] num_dwords number of noops 111 * @param[in,out] ppcmd_space in: dword aligned command buffer start address 112 * out: dword aligned next good write address 113 * @return status 114 */ 115 enum vpe_status vpe_build_noops(struct vpe *vpe, uint32_t num_dwords, uint32_t **ppcmd_space); 116 117 /** 118 * build the command descriptors for the given param. 119 * caller must call vpe_check_support() before this function, 120 * unexpected result otherwise. 121 * 122 * @param[in] vpe vpe instance created by vpe_create() 123 * @param[in] param vpe build params 124 * @param[in,out] bufs [in] memory allocated for the command buffer, embedded buffer and 3dlut. 125 * If size is 0, it reports the required size for this checked 126 * operation. [out] the next write address and the filled sizes. 127 * @return status 128 */ 129 enum vpe_status vpe_build_commands( 130 struct vpe *vpe, const struct vpe_build_param *param, struct vpe_build_bufs *bufs); 131 132 /** 133 * get the optimal number of taps based on the scaling ratio. 134 * @param[in] vpe vpe instance created by vpe_create() 135 * @param[in,out] scaling_info [in] source and destination rectangles [out] calculated taps. 136 */ 137 void vpe_get_optimal_num_of_taps(struct vpe *vpe, struct vpe_scaling_info *scaling_info); 138 139 #ifdef __cplusplus 140 } 141 #endif 142