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_PARSER_HOST_H 60 #define VIDDEC_FW_PARSER_HOST_H 61 62 #ifdef __cplusplus 63 extern "C" { 64 #endif 65 #include "viddec_fw_common_defs.h" 66 67 /** @weakgroup viddec Fw Parser interface Functions */ 68 /** @ingroup viddec_fw_parser */ 69 /*@{*/ 70 71 /** 72 This function returns the size required for loading fw. 73 @retval size : Required size. 74 */ 75 uint32_t viddec_fw_parser_query_fwsize(void); 76 77 /** 78 This function loads Parser Firmware and initialises necessary state information.This a synchronous message to FW. 79 @param[in] phys : Physical address on where firmware should be loaded. 80 @param[in] len : Length of data allocated at phys. 81 @retval VIDDEC_FW_SUCCESS : Successfully loaded firmware. 82 @retval VIDDEC_FW_FAILURE : Failed to communicate with firmware. 83 @retval VIDDEC_FW_NORESOURCES : Failed to allocate resources for Loading firmware. 84 @retval VIDDEC_FW_INVALID_PARAM: The input parameters are not valid. 85 */ 86 uint32_t viddec_fw_parser_loadfw(uint32_t phys, uint32_t len); 87 88 /** 89 This function returns the size required opening a stream. This a synchronous message to FW. 90 @param[in] codec_type : Type of codec that we want information about. 91 @param[out] num_wklds : Number of wklds required for initialisation. 92 @param[out] size : Size of memory required for opening a stream. 93 */ 94 void viddec_fw_parser_query_streamsize(uint32_t codec_type, uint32_t *num_wklds, uint32_t *size); 95 96 /** 97 This function opens requested codec.This a synchronous message to FW. 98 @param[in] codec_type : Type of codec that we want to open. 99 @param[in] phys : Physical address of allocated memory for this codec. 100 @param[in] prority : Priority of stream. 1 for realtime and 0 for background. 101 @param[out] strm_handle : Handle of the opened stream. 102 @retval VIDDEC_FW_SUCCESS : Successfully Opened the stream. 103 @retval VIDDEC_FW_FAILURE : Failed to Open a stream. 104 @retval VIDDEC_FW_NORESOURCES : Failed to Open a stream as we are out of resources. 105 */ 106 uint32_t viddec_fw_parser_openstream(uint32_t codec_type, uint32_t *strm_handle, uint32_t phys, uint32_t priority); 107 108 /** 109 This function closes stream.This a synchronous message to FW. 110 For the close stream to be effective, host has to do flush with discard first and then close the stream. 111 @param[in] strm_handle : Handle of the stream to close. 112 */ 113 void viddec_fw_parser_closestream(uint32_t strm_handle); 114 115 /** 116 This function flushes the current stream. This is a synchronous message to FW. 117 Before calling this function the host has to make sure the output queue of the firmware 118 is empty. After this function is executed the FW will read all entries in input 119 es buffer queue into a free or partial workload and push it into output queue. 120 After this operation the host has to read all entries in output queue again to 121 finish the flush operation. 122 @param[in] flush_type : Type of flush we want to perform.ex:flush and discard. 123 @param[in] strm_handle : Handle of the stream we want to flush. 124 @retval VIDDEC_FW_SUCCESS : Successfully flushed the stream. 125 @retval VIDDEC_FW_INVALID_PARAM: The input parameters are not valid. 126 @retval VIDDEC_FW_NEED_FREE_WKLD : Failed to flush sice a free wkld was not available. 127 */ 128 uint32_t viddec_fw_parser_flushstream(uint32_t strm_handle, uint32_t flush_type); 129 130 /** 131 This function sends an input es buffer. 132 @param[in] strm_handle : The handle of stream that we want to send es buffer to. 133 @param[in] message : The es buffer we want to send. 134 @retval VIDDEC_FW_SUCCESS : Successfully Sent the message. 135 @retval VIDDEC_FW_PORT_FULL : Port to fw full unsuccesful in sending message. 136 @retval VIDDEC_FW_INVALID_PARAM: The input parameters are not valid. 137 */ 138 uint32_t viddec_fw_parser_send(uint32_t strm_handle, ipc_msg_data *message); 139 140 /** 141 This function gets the next processed workload. The host is required to add free workloads 142 to keep the parser busy. The FW will stall when it doesn't have enough workloads(2) to continue. 143 @param[in] strm_handle : The handle of stream that we want to read workload from. 144 @param[out] message : The workload descriptor. 145 @retval VIDDEC_FW_SUCCESS : Successfully Sent the message. 146 @retval VIDDEC_FW_PORT_EMPTY : Workload port is empty,unsuccesful in reading wkld. 147 @retval VIDDEC_FW_INVALID_PARAM: The input parameters are not valid. 148 */ 149 uint32_t viddec_fw_parser_recv(uint32_t strm_handle, ipc_msg_data *message); 150 151 /** 152 This function adds a free workload to current stream. 153 @param[in] strm_handle : The handle of stream that we want to write workload to. 154 @param[out] message : The workload descriptor. 155 @retval VIDDEC_FW_SUCCESS : Successfully Sent the message. 156 @retval VIDDEC_FW_PORT_FULL : Workload port is full,unsuccesful in writing wkld. 157 @retval VIDDEC_FW_INVALID_PARAM: The input parameters are not valid. 158 */ 159 uint32_t viddec_fw_parser_addwkld(uint32_t strm_handle, ipc_msg_data *message); 160 161 /** 162 This function enables or disables Interrupts for a stream. By default the FW will always enable interrupts. 163 The driver can disable/enable Interrupts if it needs for this particular stream. 164 165 @param[in] strm_handle : The handle of stream that we want to get mask from 166 @param[in] mask : This is read as boolean variable, true to enable, false to disable. 167 @retval VIDDEC_FW_SUCCESS : Successfully set mask. 168 @retval VIDDEC_FW_INVALID_PARAM: The input parameters are not valid. 169 */ 170 uint32_t viddec_fw_parser_set_interruptmask(uint32_t strm_handle, uint32_t mask); 171 /** 172 This function gets the interrupt status for current stream. 173 When the host gets Interrupted since its a global interrupt it's expected that host will look at all active streams, 174 by calling this function. The status is what the FW thinks the current state of stream is. The status information that 175 FW provides is complete information on all possible events that are defined. The host should only access this information 176 in its ISR at which state FW doesn't modify this information. 177 178 @param[in] strm_handle : The handle of stream that we want to get mask from 179 @param[out] status : The status of the stream based on viddec_fw_parser_int_status_t enum. 180 @retval VIDDEC_FW_SUCCESS : Successfully in reading status. 181 @retval VIDDEC_FW_INVALID_PARAM: The input parameters are not valid. 182 */ 183 uint32_t viddec_fw_parser_getstatus(uint32_t strm_handle, uint32_t *status); 184 185 /** 186 This function allows to set stream attributes that are supported. 187 @param[in] strm_handle : The handle of stream that we want to set attribute on. 188 @param[in] type : The type of attribute we want to set, this should be one of items in viddec_fw_stream_attributes_t. 189 @param[in] value : The value of the type that we want to set. 190 @retval VIDDEC_FW_SUCCESS : Successfully Set the attribute. 191 @retval VIDDEC_FW_INVALID_PARAM: The input parameters are not valid. 192 */ 193 uint32_t viddec_fw_parser_set_stream_attributes(uint32_t strm_handle, uint32_t type, uint32_t value); 194 195 /** 196 This function allows to get current status of all the parser queues. If the current stream is active we return 197 number of inout messages that can be written to input queue, no of messages in output queue and number of 198 free available workloads the stream has. 199 Normally this is called when Host receives an interrupt from parser, In which case before releasing the INT 200 Host will try its best to keep the FW busy. We always get a interrupt if we passed the watermark on input or 201 a workload was pushed into output and INT line is free. If host holds onto INT when firmware tries to send an INT 202 FW would send the Interrupt after host releases INT. Since we have EDGE triggered interrupts we cannot guarantee 203 one interrupt per frame, ex: If three frames are generated and after the first frame FW was able to provide an INT 204 to host, but host held on to INT while the FW finished the next two frames, after host releases the INT the FW will 205 give only one INT and host should try to empty output queue. 206 @param[in] strm_handle : The handle of stream that we want to get status of queues. 207 @param[out] status : The status of each queue gets updated in here. 208 @retval VIDDEC_FW_SUCCESS : Successfully Got the status information. 209 @retval VIDDEC_FW_INVALID_PARAM: Invalid parameter in this case an inactive stream. 210 */ 211 uint32_t viddec_fw_parser_get_queue_status(uint32_t strm_handle, viddec_fw_q_status_t *status); 212 213 /** 214 This function unloads Parser Firmware and free's the resources allocated in Load fw. 215 If this function is called before load fw it will crash with a segmentation fault. 216 */ 217 void viddec_fw_parser_deinit(void); 218 219 /** 220 This function gets the major and minor revison numbers of the loaded firmware. 221 @param[out] major : The major revision numner. 222 @param[out] minor : The minor revision number. 223 @param[out] build : The Internal Build number. 224 */ 225 void viddec_fw_parser_get_version_number(unsigned int *major, unsigned int *minor, unsigned int *build); 226 227 /** 228 This function clears the global interrupt. This is the last thing host calls before exiting ISR. 229 */ 230 void viddec_fw_parser_clear_global_interrupt(void); 231 232 /*@}*/ 233 #ifdef __cplusplus 234 } 235 #endif 236 237 #endif//#ifndef VIDDEC_FW_PARSER_HOST_H 238
