1 /* 2 This file is provided under a dual BSD/GPLv2 license. When using or 3 redistributing this file, you may do so under either license. 4 5 GPL LICENSE SUMMARY 6 7 Copyright(c) 2007-2009 Intel Corporation. All rights reserved. 8 9 This program is free software; you can redistribute it and/or modify 10 it under the terms of version 2 of the GNU General Public License as 11 published by the Free Software Foundation. 12 13 This program is distributed in the hope that it will be useful, but 14 WITHOUT ANY WARRANTY; without even the implied warranty of 15 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 16 General Public License for more details. 17 18 You should have received a copy of the GNU General Public License 19 along with this program; if not, write to the Free Software 20 Foundation, Inc., 51 Franklin St - Fifth Floor, Boston, MA 02110-1301 USA. 21 The full GNU General Public License is included in this distribution 22 in the file called LICENSE.GPL. 23 24 Contact Information: 25 26 BSD LICENSE 27 28 Copyright(c) 2007-2009 Intel Corporation. All rights reserved. 29 All rights reserved. 30 31 Redistribution and use in source and binary forms, with or without 32 modification, are permitted provided that the following conditions 33 are met: 34 35 * Redistributions of source code must retain the above copyright 36 notice, this list of conditions and the following disclaimer. 37 * Redistributions in binary form must reproduce the above copyright 38 notice, this list of conditions and the following disclaimer in 39 the documentation and/or other materials provided with the 40 distribution. 41 * Neither the name of Intel Corporation nor the names of its 42 contributors may be used to endorse or promote products derived 43 from this software without specific prior written permission. 44 45 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 46 "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 47 LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 48 A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 49 OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 50 SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 51 LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 52 DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 53 THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 54 (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 55 OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 56 57 */ 58 59 #ifndef VIDDEC_FW_DECODER_HOST_H 60 #define VIDDEC_FW_DECODER_HOST_H 61 62 #ifdef __cplusplus 63 extern "C" { 64 #endif 65 66 #include "viddec_fw_common_defs.h" 67 68 /** @weakgroup viddec Fw Decoder interface Functions */ 69 /** @ingroup viddec_fw_decoder */ 70 /*@{*/ 71 72 /** 73 This function returns the size required for loading fw. 74 @retval size : Required size. 75 */ 76 uint32_t viddec_fw_decoder_query_fwsize(void); 77 78 /** 79 This function loads Decoder Firmware and initialises necessary state information. 80 @param[in] phys : Physical address on where firmware should be loaded. 81 @param[in] len : Length of data allocated at phys. 82 @retval VIDDEC_FW_SUCCESS : Successfully loaded firmware. 83 @retval VIDDEC_FW_FAILURE : Failed to communicate with firmware. 84 @retval VIDDEC_FW_NORESOURCES : Failed to allocate resources for Loading firmware. 85 @retval VIDDEC_FW_INVALID_PARAM: The input parameters are not valid. 86 */ 87 uint32_t viddec_fw_decoder_loadfw(uint32_t phys, uint32_t len); 88 89 /** 90 This function returns required size for global memory for all supported decoders. This is a synchronous message to FW. 91 @param[out] size : returns the size required. 92 @retval VIDDEC_FW_SUCCESS : Successfuly got required information from FW. 93 @retval VIDDEC_FW_FAILURE : Failed to communicate with firmware. 94 */ 95 uint32_t viddec_fw_decoder_query_fwsize_scratchmem(uint32_t *size); 96 97 /** 98 This function sets global memory for the firmware to use.This is a synchronous message to FW. 99 @param[in] phys : Physical address on where global memory starts. 100 @param[in] len : Length of data allocated at phys. 101 @retval VIDDEC_FW_SUCCESS : Successfully setup global memory. 102 @retval VIDDEC_FW_FAILURE : Failed to communicate with firmware. 103 */ 104 uint32_t viddec_fw_decoder_set_fw_scratchmem(uint32_t phys, uint32_t len); 105 106 /** 107 This function returns the size required opening a stream. This a synchronous message to FW. 108 @param[in] codec_type : Type of codec that we want information about. 109 @param[out] size : Size of memory required for opening a stream. 110 @retval VIDDEC_FW_SUCCESS : Successfuly talked to FW and got required size. 111 @retval VIDDEC_FW_FAILURE : Failed to communicate with firmware. 112 */ 113 uint32_t viddec_fw_decoder_query_streamsize(uint32_t codec_type, uint32_t *size); 114 115 /** 116 This function opens requested codec.This a synchronous message to FW. 117 @param[in] codec_type : Type of codec that we want to open. 118 @param[in] phys : Physical address of allocated memory for this codec. 119 @param[in] prority : Priority of stream. 1 for realtime and 0 for background. 120 @param[out] strm_handle : Handle of the opened stream. 121 @retval VIDDEC_FW_SUCCESS : Successfully Opened the stream. 122 @retval VIDDEC_FW_FAILURE : Failed to Open a stream. 123 */ 124 uint32_t viddec_fw_decoder_openstream(uint32_t codec_type, uint32_t *strm_handle, uint32_t phys, uint32_t priority); 125 126 127 /** 128 This function closes stream.This a synchronous message to FW. 129 @param[in] strm_handle : Handle of the stream to close. 130 */ 131 void viddec_fw_decoder_closestream(uint32_t strm_handle); 132 133 /** 134 This function allows to get current status of the decoder workload queues. If the current stream is active we return 135 number of input messages that can be written to input queue and the number of messages in output queue of the stream. 136 137 Normally this is called when Host receives an interrupt from decoder, In which case before releasing the INT 138 Host will try its best to keep the FW busy. Normally when a interrupt is received it means at least one workload is 139 written into output queue of a stream. 140 @param[in] strm_handle : The handle of stream that we want to get status of queues. 141 @param[out] status : The status of each queue gets updated in here. 142 @retval VIDDEC_FW_SUCCESS : Successfully Got the status information. 143 @retval VIDDEC_FW_INVALID_PARAM: Invalid parameter in this case an inactive stream. 144 */ 145 uint32_t viddec_fw_decoder_get_queue_status(uint32_t strm_handle, viddec_fw_decoder_q_status_t *status); 146 147 /** 148 This function flushes the current stream. This is a synchronous message to FW. 149 Before calling this function the host has to make sure the output queue of the firmware 150 is empty. After this function is executed the FW will read all entries in input 151 wkld buffer queue into output queue. After this operation the host has to read all entries 152 in output queue again to finish the flush operation. 153 @param[in] flush_type : Type of flush we want to perform.ex:flush and discard. 154 @param[in] strm_handle : Handle of the stream we want to flush. 155 @retval VIDDEC_FW_SUCCESS : Successfully flushed the stream. 156 @retval VIDDEC_FW_FAILURE : Failed to flush a stream. 157 */ 158 uint32_t viddec_fw_decoder_flushstream(uint32_t strm_handle, uint32_t flush_type); 159 160 /** 161 This function sends an input workload buffer. The host should provide required frame buffers in this workload before 162 sending it to fw. 163 @param[in] strm_handle : The handle of stream that we want to send workload buffer to. 164 @param[in] cur_wkld : The workload buffer we want to send. 165 @retval VIDDEC_FW_SUCCESS : Successfully Sent the message. 166 @retval VIDDEC_FW_PORT_FULL : Port to fw full unsuccesful in sending message. 167 */ 168 uint32_t viddec_fw_decoder_send(uint32_t strm_handle, ipc_msg_data *cur_wkld); 169 170 /** 171 This function gets the decoded workload from fw. 172 @param[in] strm_handle : The handle of stream that we want to read workload from. 173 @param[out] cur_wkld : The workload descriptor. 174 @retval VIDDEC_FW_SUCCESS : Successfully Sent the message. 175 @retval VIDDEC_FW_PORT_EMPTY : Workload port is empty,unsuccesful in reading wkld. 176 */ 177 uint32_t viddec_fw_decoder_recv(uint32_t strm_handle, ipc_msg_data *cur_wkld); 178 179 /** 180 This function unloads Decoder Firmware and free's the resources allocated in Load fw. 181 If this function is called before load fw it will crash with a segmentation fault. 182 */ 183 void viddec_fw_decoder_deinit(void); 184 185 /** 186 This function gets the major and minor revison numbers of the loaded firmware. 187 @param[out] major : The major revision number. 188 @param[out] minor : The minor revision number. 189 @param[out] build : The Internal Build number. 190 */ 191 void viddec_fw_decoder_get_version_number(unsigned int *major, unsigned int *minor, unsigned int *build); 192 193 /** 194 This function returns the interrupt status of all streams which need to be processed. A value of zero 195 means no active streams which generated this interrupt. 196 */ 197 uint32_t viddec_fw_decoder_active_pending_interrupts(void); 198 199 /** 200 This function clears the interrupts for all active streams represented by status input parameter. 201 The status should always be a value that was returned by viddec_fw_decoder_active_pending_interrupts(). 202 @param[in] status : The status value that was returned by viddec_fw_decoder_active_pending_interrupts(). 203 */ 204 void viddec_fw_decoder_clear_all_pending_interrupts(uint32_t status); 205 206 /** 207 This function enables/disables interrupt for the stream specified. 208 @param[in] strm_handle : The handle of stream that we want enable or disable interrupts for. 209 @param[in] enable : Boolean value if ==0 means disable Interrupts else enable. 210 @retval VIDDEC_FW_SUCCESS : Successfully Sent the message. 211 @retval VIDDEC_FW_INVALID_PARAM: Invalid stream handle was passed. 212 */ 213 uint32_t viddec_fw_decoder_set_stream_interrupt_mask(uint32_t stream_handle, uint32_t enable); 214 215 /** 216 This function returns which stream interrupted in the past based on status, which is a snapshot of 217 interrupt status that was cleared in the past. The host has to call clear with status information 218 before calling this function again with status value. The Host should do this operation until this function 219 returns 0, which means all the streams that generated interrupt have been processed. 220 @param[out]strm_handle : The handle of a stream that generated interrupt. 221 @param[in] status : Snapshot of Interrupt status which was returned by viddec_fw_decoder_active_pending_interrupts(). 222 @retval 1 : A valid stream handle was found. 223 @retval 0 : No more streams from the status which caused interrupt. 224 */ 225 uint32_t viddec_fw_decoder_get_next_stream_from_interrupt_status(uint32_t status, uint32_t *stream_handle); 226 227 /** 228 This function clears the stream_handle from the status snapshot that we got from viddec_fw_decoder_active_pending_interrupts(), 229 This should be called after host performs all necessary actions for the stream. 230 @param[in] strm_handle : The handle of a stream that we want to clear to indicate we handled it. 231 @param[in] status : Snapshot of Interrupt status which was returned by viddec_fw_decoder_active_pending_interrupts(). 232 @retval 1 : Operation was sucessful. 233 @retval 0 : Invalid stream handle was passed. 234 */ 235 uint32_t viddec_fw_decoder_clear_stream_from_interrupt_status(uint32_t *status, uint32_t stream_handle); 236 237 /*@}*/ 238 #ifdef __cplusplus 239 } 240 #endif 241 242 #endif//#ifndef VIDDEC_FW_DECODER_HOST_H 243
