1 /* 2 * Copyright (c) 2021 Rockchip Electronics Co., Ltd. 3 * Licensed under the Apache License, Version 2.0 (the "License"); 4 * you may not use this file except in compliance with the License. 5 * You may obtain a copy of the License at 6 * 7 * http://www.apache.org/licenses/LICENSE-2.0 8 * 9 * Unless required by applicable law or agreed to in writing, software 10 * distributed under the License is distributed on an "AS IS" BASIS, 11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 * See the License for the specific language governing permissions and 13 * limitations under the License. 14 */ 15 16 #ifndef __RK_MPI_H__ 17 #define __RK_MPI_H__ 18 19 /** 20 * @addtogroup rk_mpi 21 * @brief Rockchip Media Process Interface 22 * @details Media Process Platform(MPP) provides application programming 23 * interface for the application layer, by which applications can 24 * call hardware encode and decode. Current MPP fully supports 25 * chipset RK3288/RK3228/RK3229/RK3399/RK3328/RV1108. Old chipset 26 * like RK29xx/RK30xx/RK31XX/RK3368 is partly supported due to lack 27 * of some hardware register generation module. 28 */ 29 30 #include "rk_mpi_cmd.h" 31 #include "mpp_task.h" 32 33 /** 34 * @ingroup rk_mpi 35 * @brief MPP main work function set 36 * @details all api function are seperated into two sets: data io api set 37 * and control api set 38 * 39 * (1). the data api set is for data input/output flow including: 40 * 41 * (1.1) simple data api set: 42 * 43 * decode : both send video stream packet to decoder and get video frame from 44 * decoder at the same time. 45 * 46 * encode : both send video frame to encoder and get encoded video stream from 47 * encoder at the same time. 48 * 49 * decode_put_packet: send video stream packet to decoder only, async interface 50 * 51 * decode_get_frame : get video frame from decoder only, async interface 52 * 53 * encode_put_frame : send video frame to encoder only, async interface 54 * 55 * encode_get_packet: get encoded video packet from encoder only, async interface 56 * 57 * (1.2) advanced task api set: 58 * 59 * poll : poll port for dequeue 60 * 61 * dequeue : pop a task from mpp task queue 62 * 63 * enqueue : push a task to mpp task queue 64 * 65 * (2). the control api set is for mpp context control including: 66 * 67 * control : similiar to ioctl in kernel driver, setup or get mpp internal parameter 68 * 69 * reset : clear all data in mpp context, discard all packet and frame, 70 * reset all components to initialized status 71 */ 72 typedef struct MppApi_t { 73 /** 74 * @brief size of struct MppApi 75 */ 76 RK_U32 size; 77 /** 78 * @brief mpp api version, generated by Git 79 */ 80 RK_U32 version; 81 82 // simple data flow interface 83 /** 84 * @brief both send video stream packet to decoder and get video frame from 85 * decoder at the same time 86 * @param[in] ctx The context of mpp, created by mpp_create() and initiated 87 * by mpp_init(). 88 * @param[in] packet The input video stream, its usage can refer mpp_packet.h. 89 * @param[out] frame The output picture, its usage can refer mpp_frame.h. 90 * @return 0 and positive for success, negative for failure. The return 91 * value is an error code. For details, please refer mpp_err.h. 92 */ 93 MPP_RET (*decode)(MppCtx ctx, MppPacket packet, MppFrame *frame); 94 /** 95 * @brief send video stream packet to decoder only, async interface 96 * @param[in] ctx The context of mpp, created by mpp_create() and initiated 97 * by mpp_init(). 98 * @param[in] packet The input video stream, its usage can refer mpp_packet.h. 99 * @return 0 and positive for success, negative for failure. The return 100 * value is an error code. For details, please refer mpp_err.h. 101 */ 102 MPP_RET (*decode_put_packet)(MppCtx ctx, MppPacket packet); 103 /** 104 * @brief get video frame from decoder only, async interface 105 * @param[in] ctx The context of mpp, created by mpp_create() and initiated 106 * by mpp_init(). 107 * @param[out] frame The output picture, its usage can refer mpp_frame.h. 108 * @return 0 and positive for success, negative for failure. The return 109 * value is an error code. For details, please refer mpp_err.h. 110 */ 111 MPP_RET (*decode_get_frame)(MppCtx ctx, MppFrame *frame); 112 /** 113 * @brief both send video frame to encoder and get encoded video stream from 114 * encoder at the same time 115 * @param[in] ctx The context of mpp, created by mpp_create() and initiated 116 * by mpp_init(). 117 * @param[in] frame The input video data, its usage can refer mpp_frame.h. 118 * @param[out] packet The output compressed data, its usage can refer mpp_packet.h. 119 * @return 0 and positive for success, negative for failure. The return 120 * value is an error code. For details, please refer mpp_err.h. 121 */ 122 MPP_RET (*encode)(MppCtx ctx, MppFrame frame, MppPacket *packet); 123 /** 124 * @brief send video frame to encoder only, async interface 125 * @param[in] ctx The context of mpp, created by mpp_create() and initiated 126 * by mpp_init(). 127 * @param[in] frame The input video data, its usage can refer mpp_frame.h. 128 * @return 0 and positive for success, negative for failure. The return 129 * value is an error code. For details, please refer mpp_err.h. 130 */ 131 MPP_RET (*encode_put_frame)(MppCtx ctx, MppFrame frame); 132 /** 133 * @brief get encoded video packet from encoder only, async interface 134 * @param[in] ctx The context of mpp, created by mpp_create() and initiated 135 * by mpp_init(). 136 * @param[out] packet The output compressed data, its usage can refer mpp_packet.h. 137 * @return 0 and positive for success, negative for failure. The return 138 * value is an error code. For details, please refer mpp_err.h. 139 */ 140 MPP_RET (*encode_get_packet)(MppCtx ctx, MppPacket *packet); 141 142 /** 143 * @brief ISP interface, will be supported in the future. 144 */ 145 MPP_RET (*isp)(MppCtx ctx, MppFrame dst, MppFrame src); 146 /** 147 * @brief ISP interface, will be supported in the future. 148 */ 149 MPP_RET (*isp_put_frame)(MppCtx ctx, MppFrame frame); 150 /** 151 * @brief ISP interface, will be supported in the future. 152 */ 153 MPP_RET (*isp_get_frame)(MppCtx ctx, MppFrame *frame); 154 155 // advance data flow interface 156 /** 157 * @brief poll port for dequeue 158 * @param[in] ctx The context of mpp, created by mpp_create() and initiated 159 * by mpp_init(). 160 * @param[in] type input port or output port which are both for data transaction 161 * @param[in] timeout mpp poll type, its usage can refer mpp_task.h. 162 * @return 0 and positive for success, negative for failure. The return 163 * value is an error code. For details, please refer mpp_err.h. 164 */ 165 MPP_RET (*poll)(MppCtx ctx, MppPortType type, MppPollType timeout); 166 /** 167 * @brief dequeue MppTask, pop a task from mpp task queue 168 * @param[in] ctx The context of mpp, created by mpp_create() and initiated 169 * by mpp_init(). 170 * @param[in] type input port or output port which are both for data transaction 171 * @param[out] task MppTask popped from mpp task queue, its usage can refer mpp_task.h. 172 * @return 0 and positive for success, negative for failure. The return 173 * value is an error code. For details, please refer mpp_err.h. 174 */ 175 MPP_RET (*dequeue)(MppCtx ctx, MppPortType type, MppTask *task); 176 /** 177 * @brief enqueue MppTask, push a task to mpp task queue 178 * @param[in] ctx The context of mpp, created by mpp_create() and initiated 179 * by mpp_init(). 180 * @param[in] type input port or output port which are both for data transaction 181 * @param[in] task MppTask which is sent to mpp for process, its usage can refer mpp_task.h. 182 * @return 0 and positive for success, negative for failure. The return 183 * value is an error code. For details, please refer mpp_err.h. 184 */ 185 MPP_RET (*enqueue)(MppCtx ctx, MppPortType type, MppTask task); 186 187 // control interface 188 /** 189 * @brief discard all packet and frame, reset all component, 190 * for both decoder and encoder 191 * @param[in] ctx The context of mpp, created by mpp_create() and initiated 192 * by mpp_init(). 193 * @return 0 for success, others for failure. The return value is an 194 * error code. For details, please refer mpp_err.h. 195 */ 196 MPP_RET (*reset)(MppCtx ctx); 197 /** 198 * @brief control function for mpp property setting 199 * @param[in] ctx The context of mpp, created by mpp_create() and initiated 200 * by mpp_init(). 201 * @param[in] cmd The mpi command, its definition can refer rk_mpi_cmd.h. 202 * @param[in,out] param The mpi command parameter 203 * @return 0 for success, others for failure. The return value is an 204 * error code. For details, please refer mpp_err.h. 205 */ 206 MPP_RET (*control)(MppCtx ctx, MpiCmd cmd, MppParam param); 207 208 /** 209 * @brief The reserved segment, may be used in the future 210 */ 211 RK_U32 reserv[16]; 212 } MppApi; 213 214 215 #ifdef __cplusplus 216 extern "C" { 217 #endif 218 219 /** 220 * @ingroup rk_mpi 221 * @brief Create empty context structure and mpi function pointers. 222 * Use functions in MppApi to access mpp services. 223 * @param[in,out] ctx pointer of the mpp context, refer to MpiImpl_t. 224 * @param[in,out] mpi pointer of mpi function, refer to MppApi. 225 * @return 0 for success, others for failure. The return value is an 226 * error code. For details, please refer mpp_err.h. 227 * @note This interface creates base flow context, all function calls 228 * are based on it. 229 */ 230 MPP_RET mpp_create(MppCtx *ctx, MppApi **mpi); 231 /** 232 * @ingroup rk_mpi 233 * @brief Call after mpp_create to setup mpp type and video format. 234 * This function will call internal context init function. 235 * @param[in] ctx The context of mpp, created by mpp_create(). 236 * @param[in] type specify decoder or encoder, refer to MppCtxType. 237 * @param[in] coding specify video compression coding, refer to MppCodingType. 238 * @return 0 for success, others for failure. The return value is an 239 * error code. For details, please refer mpp_err.h. 240 */ 241 MPP_RET mpp_init(MppCtx ctx, MppCtxType type, MppCodingType coding); 242 /** 243 * @ingroup rk_mpi 244 * @brief Call after mpp_init to start mpp working. 245 * Control SET_CFG can be called both before and after mpp_start. 246 * Before mpp_start is called both global param and dynamic param can be set. 247 * After mpp_start is called only dynamic param can be set. 248 * This funciton purpose is to stop recieving global param and do 249 * preparation for processing data flow. 250 * This function will call internal context start function. 251 * @param[in] ctx The context of mpp, created by mpp_create(). 252 * @return 0 for success, others for failure. The return value is an 253 * error code. For details, please refer mpp_err.h. 254 */ 255 MPP_RET mpp_start(MppCtx ctx); 256 /** 257 * @ingroup rk_mpi 258 * @brief Call before mpp_destroy to stop mpp working. 259 * Control SET_CFG can be called after starting. 260 * Before mpp_stop is called only dynamic param can be set. 261 * After mpp_stop is called both global param and dynamic param can be set. 262 * This funciton purpose is to stop processing data and do preparation 263 * to receive global param. 264 * @param[in] ctx The context of mpp, created by mpp_create(). 265 * @return 0 for success, others for failure. The return value is an 266 * error code. For details, please refer mpp_err.h. 267 */ 268 MPP_RET mpp_stop(MppCtx ctx); 269 /** 270 * @ingroup rk_mpi 271 * @brief Destroy mpp context and free both context and mpi structure, 272 * it matches with mpp_init(). 273 * @param[in] ctx The context of mpp, created by mpp_create(). 274 * @return 0 for success, others for failure. The return value is an 275 * error code. For details, please refer mpp_err.h. 276 */ 277 MPP_RET mpp_destroy(MppCtx ctx); 278 /** 279 * @ingroup rk_mpi 280 * @brief judge given format is supported or not by MPP. 281 * @param[in] type specify decoder or encoder, refer to MppCtxType. 282 * @param[in] coding specify video compression coding, refer to MppCodingType. 283 * @return 0 for support, -1 for unsupported. 284 */ 285 MPP_RET mpp_check_support_format(MppCtxType type, MppCodingType coding); 286 /** 287 * @ingroup rk_mpi 288 * @brief List all formats supported by MPP 289 * @param NULL no need to input parameter 290 * @return No return value. This function just prints format information supported 291 * by MPP on standard output. 292 */ 293 void mpp_show_support_format(void); 294 void mpp_show_color_format(void); 295 296 #ifdef __cplusplus 297 } 298 #endif 299 300 #endif /* __RK_MPI_H__ */