ilclient.h (44592B)
1 /* 2 Copyright (c) 2012, Broadcom Europe Ltd 3 All rights reserved. 4 5 Redistribution and use in source and binary forms, with or without 6 modification, are permitted provided that the following conditions are met: 7 * Redistributions of source code must retain the above copyright 8 notice, this list of conditions and the following disclaimer. 9 * Redistributions in binary form must reproduce the above copyright 10 notice, this list of conditions and the following disclaimer in the 11 documentation and/or other materials provided with the distribution. 12 * Neither the name of the copyright holder nor the 13 names of its contributors may be used to endorse or promote products 14 derived from this software without specific prior written permission. 15 16 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND 17 ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED 18 WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 19 DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY 20 DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES 21 (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 22 LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND 23 ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 24 (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS 25 SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 26 */ 27 28 /* 29 * \file 30 * 31 * \brief This API defines helper functions for writing IL clients. 32 * 33 * This file defines an IL client side library. This is useful when 34 * writing IL clients, since there tends to be much repeated and 35 * common code across both single and multiple clients. This library 36 * seeks to remove that common code and abstract some of the 37 * interactions with components. There is a wrapper around a 38 * component and tunnel, and some operations can be done on lists of 39 * these. The callbacks from components are handled, and specific 40 * events can be checked or waited for. 41 */ 42 43 #ifndef _IL_CLIENT_H 44 #define _IL_CLIENT_H 45 46 #include "IL/OMX_Broadcom.h" 47 #include "interface/vcos/vcos.h" 48 49 /** 50 * The <DFN>ILCLIENT_T</DFN> structure encapsulates the state needed for the IL 51 * Client API. It contains a set of callback functions used to 52 * communicate with the user. It also includes a linked list of free 53 * event structures. 54 ***********************************************************/ 55 typedef struct _ILCLIENT_T ILCLIENT_T; 56 57 58 /** 59 * Each <DFN>ILEVENT_T</DFN> structure stores the result of an <DFN>EventHandler</DFN> 60 * callback from a component, storing the event message type and any 61 * parameters returned. 62 ***********************************************************/ 63 typedef struct _ILEVENT_T ILEVENT_T; 64 65 66 67 struct _COMPONENT_T; 68 69 /** 70 * The <DFN>COMPONENT_T</DFN> structure represents an IL component, 71 * together with the necessary extra information required by the IL 72 * Client API. This structure stores the handle to the OMX component, 73 * as well as the event list containing all events sent by this 74 * component. The component state structure also holds a pair of 75 * buffer queues, for input and output buffers returned to the client 76 * by the <DFN>FillBufferDone</DFN> and <DFN>EmptyBufferDone</DFN> 77 * callbacks. As some operations result in error callbacks that can 78 * be ignored, an error mask is maintained to allow some errors to be 79 * ignored. A pointer to the client state structure is also added. 80 ***********************************************************/ 81 typedef struct _COMPONENT_T COMPONENT_T; 82 83 84 /** 85 * The generic callback function is used for communicating events from 86 * a particular component to the user. 87 * 88 * @param userdata The data returned from when the callback was registered. 89 * 90 * @param comp The component structure representing the component that 91 * originated this event. 92 * 93 * @param data The relevant data field from the event. 94 * 95 * @return Void. 96 ***********************************************************/ 97 typedef void (*ILCLIENT_CALLBACK_T)(void *userdata, COMPONENT_T *comp, OMX_U32 data); 98 99 100 /** 101 * The buffer callback function is used for indicating that a 102 * component has returned a buffer on a port using client buffer 103 * communication. 104 * 105 * @param data The data returned from when the callback was registered. 106 * 107 * @param comp The component from which the buffer originated. 108 * 109 * @return Void. 110 ***********************************************************/ 111 typedef void (*ILCLIENT_BUFFER_CALLBACK_T)(void *data, COMPONENT_T *comp); 112 113 114 /** 115 * The malloc function is passed into 116 * <DFN>ilclient_enable_port_buffers()</DFN> and used for allocating the 117 * buffer payload. 118 * 119 * @param userdata Private pointer passed into 120 * <DFN>ilclient_enable_port_buffers()</DFN> call. 121 * 122 * @param size Size in bytes of the requested memory region. 123 * 124 * @param align Alignment requirement in bytes for the base memory address. 125 * 126 * @param description Text description of the memory being allocated. 127 * 128 * @return The memory address on success, <DFN>NULL</DFN> on failure. 129 ***********************************************************/ 130 typedef void *(*ILCLIENT_MALLOC_T)(void *userdata, VCOS_UNSIGNED size, VCOS_UNSIGNED align, const char *description); 131 132 133 /** 134 * The free function is passed into 135 * <DFN>ilclient_enable_port_buffers()</DFN> and 136 * <DFN>ilclient_disable_port_buffers()</DFN> and used for freeing the 137 * buffer payload. 138 * 139 * @param userdata Private pointer passed into 140 * <DFN>ilclient_enable_port_buffers()</DFN> and 141 * <DFN>ilclient_disable_port_buffers()</DFN>. 142 * 143 * @param pointer Memory address to free, that was previously returned 144 * from <DFN>ILCLIENT_MALLOC_T</DFN> function. 145 * 146 * @return Void. 147 ***********************************************************/ 148 typedef void (*ILCLIENT_FREE_T)(void *userdata, void *pointer); 149 150 151 /** 152 * The event mask enumeration describes the possible events that the 153 * user can ask to wait for when waiting for a particular event. 154 ***********************************************************/ 155 typedef enum { 156 ILCLIENT_EMPTY_BUFFER_DONE = 0x1, /**< Set when a buffer is 157 returned from an input 158 port */ 159 160 ILCLIENT_FILL_BUFFER_DONE = 0x2, /**< Set when a buffer is 161 returned from an output 162 port */ 163 164 ILCLIENT_PORT_DISABLED = 0x4, /**< Set when a port indicates 165 it has completed a disable 166 command. */ 167 168 ILCLIENT_PORT_ENABLED = 0x8, /**< Set when a port indicates 169 is has completed an enable 170 command. */ 171 172 ILCLIENT_STATE_CHANGED = 0x10, /**< Set when a component 173 indicates it has completed 174 a state change command. */ 175 176 ILCLIENT_BUFFER_FLAG_EOS = 0x20, /**< Set when a port signals 177 an EOS event. */ 178 179 ILCLIENT_PARAMETER_CHANGED = 0x40, /**< Set when a port signals a 180 port settings changed 181 event. */ 182 183 ILCLIENT_EVENT_ERROR = 0x80, /**< Set when a component 184 indicates an error. */ 185 186 ILCLIENT_PORT_FLUSH = 0x100, /**< Set when a port indicates 187 is has completed a flush 188 command. */ 189 190 ILCLIENT_MARKED_BUFFER = 0x200, /**< Set when a port indicates 191 it has marked a buffer. */ 192 193 ILCLIENT_BUFFER_MARK = 0x400, /**< Set when a port indicates 194 it has received a buffer 195 mark. */ 196 197 ILCLIENT_CONFIG_CHANGED = 0x800 /**< Set when a config parameter 198 changed. */ 199 } ILEVENT_MASK_T; 200 201 202 /** 203 * On component creation the user can set flags to control the 204 * creation of that component. 205 ***********************************************************/ 206 typedef enum { 207 ILCLIENT_FLAGS_NONE = 0x0, /**< Used if no flags are 208 set. */ 209 210 ILCLIENT_ENABLE_INPUT_BUFFERS = 0x1, /**< If set we allow the 211 client to communicate with 212 input ports via buffer 213 communication, rather than 214 tunneling with another 215 component. */ 216 217 ILCLIENT_ENABLE_OUTPUT_BUFFERS = 0x2, /**< If set we allow the 218 client to communicate with 219 output ports via buffer 220 communication, rather than 221 tunneling with another 222 component. */ 223 224 ILCLIENT_DISABLE_ALL_PORTS = 0x4, /**< If set we disable all 225 ports on creation. */ 226 227 ILCLIENT_HOST_COMPONENT = 0x8, /**< Create a host component. 228 The default host ilcore 229 only can create host components 230 by being locally hosted 231 so should only be used for testing 232 purposes. */ 233 234 ILCLIENT_OUTPUT_ZERO_BUFFERS = 0x10 /**< All output ports will have 235 nBufferCountActual set to zero, 236 if supported by the component. */ 237 } ILCLIENT_CREATE_FLAGS_T; 238 239 240 /** 241 * \brief This structure represents a tunnel in the OpenMAX IL API. 242 * 243 * Some operations in this API act on a tunnel, so the tunnel state 244 * structure (<DFN>TUNNEL_T</DFN>) is a convenient store of the source and sink 245 * of the tunnel. For each, a pointer to the relevant component state 246 * structure and the port index is stored. 247 ***********************************************************/ 248 typedef struct { 249 COMPONENT_T *source; /**< The source component */ 250 int source_port; /**< The output port index on the source component */ 251 COMPONENT_T *sink; /**< The sink component */ 252 int sink_port; /**< The input port index on the sink component */ 253 } TUNNEL_T; 254 255 256 /** 257 * The <DFN>set_tunnel</DFN> macro is a useful function that initialises a 258 * <DFN>TUNNEL_T</DFN> structure. 259 ***********************************************************/ 260 #define set_tunnel(t,a,b,c,d) do {TUNNEL_T *_ilct = (t); \ 261 _ilct->source = (a); _ilct->source_port = (b); \ 262 _ilct->sink = (c); _ilct->sink_port = (d);} while(0) 263 264 /** 265 * For calling OpenMAX IL methods directory, we need to access the 266 * <DFN>OMX_HANDLETYPE</DFN> corresponding to the <DFN>COMPONENT_T</DFN> structure. This 267 * macro enables this while keeping the <DFN>COMPONENT_T</DFN> structure opaque. 268 * The parameter <DFN>x</DFN> should be of the type <DFN>*COMPONENT_T</DFN>. 269 ***********************************************************/ 270 #define ILC_GET_HANDLE(x) ilclient_get_handle(x) 271 272 /** 273 * An IL Client structure is created by the <DFN>ilclient_init()</DFN> 274 * method. This structure is used when creating components, but 275 * otherwise is not needed in other API functions as a pointer to this 276 * structure is maintained in the <DFN>COMPONENT_T</DFN> structure. 277 * 278 * @return pointer to client structure 279 ***********************************************************/ 280 VCHPRE_ ILCLIENT_T VCHPOST_ *ilclient_init(void); 281 282 /** 283 * When all components have been deleted, the IL Client structure can 284 * be destroyed by calling the <DFN>ilclient_destroy()</DFN> function. 285 * 286 * @param handle The client handle. After calling this function, this 287 * handle should not be used. 288 * 289 * @return void 290 ***********************************************************/ 291 VCHPRE_ void VCHPOST_ ilclient_destroy(ILCLIENT_T *handle); 292 293 /** 294 * The <DFN>ilclient_set_port_settings_callback()</DFN> function registers a 295 * callback to be used when the <DFN>OMX_EventPortSettingsChanged</DFN> event is 296 * received. When the event is received, a pointer to the component 297 * structure and port index is returned by the callback. 298 * 299 * @param handle The client handle 300 * 301 * @param func The callback function to use. Calling this function 302 * with a <DFN>NULL</DFN> function pointer will deregister any existing 303 * registered callback. 304 * 305 * @param userdata Data to be passed back when calling the callback 306 * function. 307 * 308 * @return void 309 ***********************************************************/ 310 VCHPRE_ void VCHPOST_ ilclient_set_port_settings_callback(ILCLIENT_T *handle, 311 ILCLIENT_CALLBACK_T func, 312 void *userdata); 313 314 /** 315 * The <DFN>ilclient_set_eos_callback()</DFN> function registers a callback to be 316 * used when the <DFN>OMX_EventBufferFlag</DFN> is received with the 317 * <DFN>OMX_BUFFERFLAG_EOS</DFN> flag set. When the event is received, a pointer 318 * to the component structure and port index is returned by the 319 * callback. 320 * 321 * @param handle The client handle 322 * 323 * @param func The callback function to use. Calling this function 324 * with a <DFN>NULL</DFN> function pointer will deregister any existing 325 * registered callback. 326 * 327 * @param userdata Data to be passed back when calling the callback 328 * function. 329 * 330 * @return void 331 ***********************************************************/ 332 VCHPRE_ void VCHPOST_ ilclient_set_eos_callback(ILCLIENT_T *handle, 333 ILCLIENT_CALLBACK_T func, 334 void *userdata); 335 336 /** 337 * The <DFN>ilclient_set_error_callback()</DFN> function registers a callback to be 338 * used when the <DFN>OMX_EventError</DFN> is received from a component. When 339 * the event is received, a pointer to the component structure and the 340 * error code are reported by the callback. 341 * 342 * @param handle The client handle 343 * 344 * @param func The callback function to use. Calling this function 345 * with a <DFN>NULL</DFN> function pointer will deregister any existing 346 * registered callback. 347 * 348 * @param userdata Data to be passed back when calling the callback 349 * function. 350 * 351 * @return void 352 ***********************************************************/ 353 VCHPRE_ void VCHPOST_ ilclient_set_error_callback(ILCLIENT_T *handle, 354 ILCLIENT_CALLBACK_T func, 355 void *userdata); 356 357 /** 358 * The <DFN>ilclient_set_configchanged_callback()</DFN> function 359 * registers a callback to be used when an 360 * <DFN>OMX_EventParamOrConfigChanged</DFN> event occurs. When the 361 * event is received, a pointer to the component structure and the 362 * index value that has changed are reported by the callback. The 363 * user may then use an <DFN>OMX_GetConfig</DFN> call with the index 364 * as specified to retrieve the updated information. 365 * 366 * @param handle The client handle 367 * 368 * @param func The callback function to use. Calling this function 369 * with a <DFN>NULL</DFN> function pointer will deregister any existing 370 * registered callback. 371 * 372 * @param userdata Data to be passed back when calling the callback 373 * function. 374 * 375 * @return void 376 ***********************************************************/ 377 VCHPRE_ void VCHPOST_ ilclient_set_configchanged_callback(ILCLIENT_T *handle, 378 ILCLIENT_CALLBACK_T func, 379 void *userdata); 380 381 382 /** 383 * The <DFN>ilclient_set_fill_buffer_done_callback()</DFN> function registers a 384 * callback to be used when a buffer passed to an output port using the 385 * <DFN>OMX_FillBuffer</DFN> call is returned with the <DFN>OMX_FillBufferDone</DFN> 386 * callback. When the event is received, a pointer to the component 387 * structure is returned by the callback. The user may then use the 388 * <DFN>ilclient_get_output_buffer()</DFN> function to retrieve the buffer. 389 * 390 * @param handle The client handle 391 * 392 * @param func The callback function to use. Calling this function 393 * with a <DFN>NULL</DFN> function pointer will deregister any existing 394 * registered callback. 395 * 396 * @param userdata Data to be passed back when calling the callback 397 * function. 398 * 399 * @return void 400 ***********************************************************/ 401 VCHPRE_ void VCHPOST_ ilclient_set_fill_buffer_done_callback(ILCLIENT_T *handle, 402 ILCLIENT_BUFFER_CALLBACK_T func, 403 void *userdata); 404 405 /** 406 * The <DFN>ilclient_set_empty_buffer_done_callback()</DFN> function registers a 407 * callback to be used when a buffer passed to an input port using the 408 * <DFN>OMX_EmptyBuffer</DFN> call is returned with the <DFN>OMX_EmptyBufferDone</DFN> 409 * callback. When the event is received, a pointer to the component 410 * structure is returned by the callback. The user may then use the 411 * <DFN>ilclient_get_input_buffer()</DFN> function to retrieve the buffer. 412 * 413 * @param handle The client handle 414 * 415 * @param func The callback function to use. Calling this function 416 * with a <DFN>NULL</DFN> function pointer will deregister any existing 417 * registered callback. 418 * 419 * @param userdata Data to be passed back when calling the callback 420 * function. 421 * 422 * @return void 423 ***********************************************************/ 424 VCHPRE_ void VCHPOST_ ilclient_set_empty_buffer_done_callback(ILCLIENT_T *handle, 425 ILCLIENT_BUFFER_CALLBACK_T func, 426 void *userdata); 427 428 429 /** 430 * Components are created using the <DFN>ilclient_create_component()</DFN> 431 * function. 432 * 433 * @param handle The client handle 434 * 435 * @param comp On successful creation, the component structure pointer 436 * will be written back into <DFN>comp</DFN>. 437 * 438 * @param name The name of the component to be created. Component 439 * names as provided are automatically prefixed with 440 * <DFN>"OMX.broadcom."</DFN> before passing to the IL core. The name 441 * provided will also be used in debugging messages added about this 442 * component. 443 * 444 * @param flags The client can specify some creation behaviour by using 445 * the <DFN>flags</DFN> field. The meaning of each flag is defined 446 * by the <DFN>ILCLIENT_CREATE_FLAGS_T</DFN> type. 447 * 448 * @return 0 on success, -1 on failure 449 ***********************************************************/ 450 VCHPRE_ int VCHPOST_ ilclient_create_component(ILCLIENT_T *handle, 451 COMPONENT_T **comp, 452 char *name, 453 ILCLIENT_CREATE_FLAGS_T flags); 454 455 /** 456 * The <DFN>ilclient_cleanup_components()</DFN> function deallocates all 457 * state associated with components and frees the OpenMAX component 458 * handles. All tunnels connecting components should have been torn 459 * down explicitly, and all components must be in loaded state. 460 * 461 * @param list A null-terminated list of component pointers to be 462 * deallocated. 463 * 464 * @return void 465 ***********************************************************/ 466 VCHPRE_ void VCHPOST_ ilclient_cleanup_components(COMPONENT_T *list[]); 467 468 469 /** 470 * The <DFN>ilclient_change_component_state()</DFN> function changes the 471 * state of an individual component. This will trigger the state 472 * change, and also wait for that state change to be completed. It 473 * should not be called if this state change has dependencies on other 474 * components also changing states. Trying to change a component to 475 * its current state is treated as success. 476 * 477 * @param comp The component to change. 478 * 479 * @param state The new state to transition to. 480 * 481 * @return 0 on success, -1 on failure. 482 ***********************************************************/ 483 VCHPRE_ int VCHPOST_ ilclient_change_component_state(COMPONENT_T *comp, 484 OMX_STATETYPE state); 485 486 487 /** 488 * The <DFN>ilclient_state_transition()</DFN> function transitions a set of 489 * components that need to perform a simultaneous state transition; 490 * for example, when two components are tunnelled and the buffer 491 * supplier port needs to allocate and pass buffers to a non-supplier 492 * port. All components are sent a command to change state, then the 493 * function will wait for all components to signal that they have 494 * changed state. 495 * 496 * @param list A null-terminated list of component pointers. 497 * 498 * @param state The new state to which to transition all components. 499 * 500 * @return void 501 ***********************************************************/ 502 VCHPRE_ void VCHPOST_ ilclient_state_transition(COMPONENT_T *list[], 503 OMX_STATETYPE state); 504 505 506 /** 507 * The <DFN>ilclient_disable_port()</DFN> function disables a port on a 508 * given component. This function sends the disable port message to 509 * the component and waits for the component to signal that this has 510 * taken place. If the port is already disabled, this is treated as a 511 * success. 512 * 513 * @param comp The component containing the port to disable. 514 * 515 * @param portIndex The port index of the port to disable. This must 516 * be a named port index, rather than a <DFN>OMX_ALL</DFN> value. 517 * 518 * @return void 519 ***********************************************************/ 520 VCHPRE_ void VCHPOST_ ilclient_disable_port(COMPONENT_T *comp, 521 int portIndex); 522 523 524 /** 525 * The <DFN>ilclient_enable_port()</DFN> function enables a port on a 526 * given component. This function sends the enable port message to 527 * the component and waits for the component to signal that this has 528 * taken place. If the port is already disabled, this is treated as a 529 * success. 530 * 531 * @param comp The component containing the port to enable. 532 * 533 * @param portIndex The port index of the port to enable. This must 534 * be a named port index, rather than a <DFN>OMX_ALL</DFN> value. 535 * 536 * @return void 537 ***********************************************************/ 538 VCHPRE_ void VCHPOST_ ilclient_enable_port(COMPONENT_T *comp, 539 int portIndex); 540 541 542 543 /** 544 * The <DFN>ilclient_enable_port_buffers()</DFN> function enables a port 545 * in base profile mode on a given component. The port is not 546 * tunneled, so requires buffers to be allocated. 547 * 548 * @param comp The component containing the port to enable. 549 * 550 * @param portIndex The port index of the port to enable. This must 551 * be a named port index, rather than a <DFN>OMX_ALL</DFN> value. 552 * 553 * @param ilclient_malloc This function will be used to allocate 554 * buffer payloads. If <DFN>NULL</DFN> then 555 * <DFN>vcos_malloc_aligned</DFN> will be used. 556 * 557 * @param ilclient_free If an error occurs, this function is used to 558 * free previously allocated payloads. If <DFN>NULL</DFN> then 559 * <DFN>vcos_free</DFN> will be used. 560 * 561 * @param userdata The first argument to calls to 562 * <DFN>ilclient_malloc</DFN> and <DFN>ilclient_free</DFN>, if these 563 * arguments are not <DFN>NULL</DFN>. 564 * 565 * @return 0 indicates success. -1 indicates failure. 566 ***********************************************************/ 567 VCHPRE_ int VCHPOST_ ilclient_enable_port_buffers(COMPONENT_T *comp, 568 int portIndex, 569 ILCLIENT_MALLOC_T ilclient_malloc, 570 ILCLIENT_FREE_T ilclient_free, 571 void *userdata); 572 573 574 /** 575 * The <DFN>ilclient_disable_port_buffers()</DFN> function disables a 576 * port in base profile mode on a given component. The port is not 577 * tunneled, and has been supplied with buffers by the client. 578 * 579 * @param comp The component containing the port to disable. 580 * 581 * @param portIndex The port index of the port to disable. This must 582 * be a named port index, rather than a <DFN>OMX_ALL</DFN> value. 583 * 584 * @param bufferList A list of buffers, using <DFN>pAppPrivate</DFN> 585 * as the next pointer that were allocated on this port, and currently 586 * held by the application. If buffers on this port are held by IL 587 * client or the component then these are automatically freed. 588 * 589 * @param ilclient_free This function is used to free the buffer payloads. 590 * If <DFN>NULL</DFN> then <DFN>vcos_free</DFN> will be used. 591 * 592 * @param userdata The first argument to calls to 593 * <DFN>ilclient_free</DFN>. 594 * 595 * @return void 596 */ 597 VCHPRE_ void VCHPOST_ ilclient_disable_port_buffers(COMPONENT_T *comp, 598 int portIndex, 599 OMX_BUFFERHEADERTYPE *bufferList, 600 ILCLIENT_FREE_T ilclient_free, 601 void *userdata); 602 603 604 /** 605 * With a populated tunnel structure, the 606 * <DFN>ilclient_setup_tunnel()</DFN> function connects the tunnel. It 607 * first transitions the source component to idle if currently in 608 * loaded state, and then optionally checks the source event list for 609 * a port settings changed event from the source port. If this event 610 * is not in the event queue then this function optionally waits for 611 * it to arrive. To disable this check for the port settings changed 612 * event, set <DFN>timeout</DFN> to zero. 613 * 614 * Both ports are then disabled, and the source port is inspected for 615 * a port streams parameter. If this is supported, then the 616 * <DFN>portStream</DFN> argument is used to select which port stream 617 * to use. The two ports are then tunnelled using the 618 * <DFN>OMX_SetupTunnel</DFN> function. If this is successful, then 619 * both ports are enabled. Note that for disabling and enabling the 620 * tunnelled ports, the functions <DFN>ilclient_disable_tunnel()</DFN> 621 * and <DFN>ilclient_enable_tunnel()</DFN> are used, so the relevant 622 * documentation for those functions applies here. 623 * 624 * @param tunnel The tunnel structure representing the tunnel to 625 * set up. 626 * 627 * @param portStream If port streams are supported on the output port 628 * of the tunnel, then this parameter indicates the port stream to 629 * select on this port. 630 * 631 * @param timeout The time duration in milliseconds to wait for the 632 * output port to signal a port settings changed event before 633 * returning a timeout failure. If this is 0, then we do not check 634 * for a port settings changed before setting up the tunnel. 635 * 636 * @return 0 indicates success, negative indicates failure: 637 * - -1: a timeout waiting for the parameter changed 638 * - -2: an error was returned instead of parameter changed 639 * - -3: no streams are available from this port 640 * - -4: requested stream is not available from this port 641 * - -5: the data format was not acceptable to the sink 642 ***********************************************************/ 643 VCHPRE_ int VCHPOST_ ilclient_setup_tunnel(TUNNEL_T *tunnel, 644 unsigned int portStream, 645 int timeout); 646 647 648 /** 649 * The <DFN>ilclient_disable_tunnel()</DFN> function disables both ports listed in 650 * the tunnel structure. It will send a port disable command to each 651 * port, then waits for both to indicate they have completed the 652 * transition. The errors <DFN>OMX_ErrorPortUnpopulated</DFN> and 653 * <DFN>OMX_ErrorSameState</DFN> are both ignored by this function; the former 654 * since the first port to disable may deallocate buffers before the 655 * second port has been disabled, leading to the second port reporting 656 * the unpopulated error. 657 * 658 * @param tunnel The tunnel to disable. 659 * 660 * @return void 661 ***********************************************************/ 662 VCHPRE_ void VCHPOST_ ilclient_disable_tunnel(TUNNEL_T *tunnel); 663 664 665 /** 666 * The <DFN>ilclient_enable_tunnel()</DFN> function enables both ports listed in 667 * the tunnel structure. It will first send a port enable command to 668 * each port. It then checks whether the sink component is not in 669 * loaded state - if so, the function waits for both ports to complete 670 * the requested port enable. If the sink component was in loaded 671 * state, then this component is transitioned to idle to allow the 672 * ports to exchange buffers and enable the ports. This is since 673 * typically this function is used when creating a tunnel between two 674 * components, where the source component is processing data to enable 675 * it to report the port settings changed event, and the sink port has 676 * yet to be used. Before transitioning the sink component to idle, 677 * this function waits for the sink port to be enabled - since the 678 * component is in loaded state, this will happen quickly. If the 679 * transition to idle fails, the sink component is transitioned back 680 * to loaded and the source port disabled. If the transition 681 * succeeds, the function then waits for the source port to complete 682 * the requested port enable. 683 * 684 * @param tunnel The tunnel to enable. 685 * 686 * @return 0 on success, -1 on failure. 687 ***********************************************************/ 688 VCHPRE_ int VCHPOST_ ilclient_enable_tunnel(TUNNEL_T *tunnel); 689 690 691 /** 692 * The <DFN>ilclient_flush_tunnels()</DFN> function will flush a number of tunnels 693 * from the list of tunnels presented. For each tunnel that is to be 694 * flushed, both source and sink ports are sent a flush command. The 695 * function then waits for both ports to report they have completed 696 * the flush operation. 697 * 698 * @param tunnel List of tunnels. The list must be terminated with a 699 * tunnel structure with <DFN>NULL</DFN> component entries. 700 * 701 * @param max The maximum number of tunnels to flush from the list. 702 * A value of 0 indicates that all tunnels in the list are flushed. 703 * 704 * @return void 705 ***********************************************************/ 706 VCHPRE_ void VCHPOST_ ilclient_flush_tunnels(TUNNEL_T *tunnel, 707 int max); 708 709 710 /** 711 * The <DFN>ilclient_teardown_tunnels()</DFN> function tears down all tunnels in 712 * the list of tunnels presented. For each tunnel in the list, the 713 * <DFN>OMX_SetupTunnel</DFN> is called on the source port and on the sink port, 714 * where for both calls the destination component is <DFN>NULL</DFN> and the 715 * destination port is zero. The VMCSX IL implementation requires 716 * that all tunnels are torn down in this manner before components are 717 * freed. 718 * 719 * @param tunnels List of tunnels to teardown. The list must be 720 * terminated with a tunnel structure with <DFN>NULL</DFN> component entries. 721 * 722 * @return void 723 ***********************************************************/ 724 VCHPRE_ void VCHPOST_ ilclient_teardown_tunnels(TUNNEL_T *tunnels); 725 726 727 /** 728 * The <DFN>ilclient_get_output_buffer()</DFN> function returns a buffer 729 * that was sent to an output port and that has been returned from a 730 * component using the <DFN>OMX_FillBufferDone</DFN> callback. 731 * 732 * @param comp The component that returned the buffer. 733 * 734 * @param portIndex The port index on the component that the buffer 735 * was returned from. 736 * 737 * @param block If non-zero, the function will block until a buffer is available. 738 * 739 * @return Pointer to buffer if available, otherwise <DFN>NULL</DFN>. 740 ***********************************************************/ 741 VCHPRE_ OMX_BUFFERHEADERTYPE* VCHPOST_ ilclient_get_output_buffer(COMPONENT_T *comp, 742 int portIndex, 743 int block); 744 745 746 /** 747 * The <DFN>ilclient_get_input_buffer()</DFN> function returns a buffer 748 * that was sent to an input port and that has been returned from a 749 * component using the <DFN>OMX_EmptyBufferDone</DFN> callback. 750 * 751 * @param comp The component that returned the buffer. 752 * 753 * @param portIndex The port index on the component from which the buffer 754 * was returned. 755 * 756 * @param block If non-zero, the function will block until a buffer is available. 757 * 758 * @return pointer to buffer if available, otherwise <DFN>NULL</DFN> 759 ***********************************************************/ 760 VCHPRE_ OMX_BUFFERHEADERTYPE* VCHPOST_ ilclient_get_input_buffer(COMPONENT_T *comp, 761 int portIndex, 762 int block); 763 764 765 /** 766 * The <DFN>ilclient_remove_event()</DFN> function queries the event list for the 767 * given component, matching against the given criteria. If a matching 768 * event is found, it is removed and added to the free event list. 769 * 770 * @param comp The component that returned the matching event. 771 * 772 * @param event The event type of the matching event. 773 * 774 * @param nData1 The <DFN>nData1</DFN> field of the matching event. 775 * 776 * @param ignore1 Whether to ignore the <DFN>nData1</DFN> field when finding a 777 * matching event. A value of 0 indicates that <DFN>nData1</DFN> must match, a 778 * value of 1 indicates that <DFN>nData1</DFN> does not have to match. 779 * 780 * @param nData2 The <DFN>nData2</DFN> field of the matching event. 781 * 782 * @param ignore2 Whether to ignore the <DFN>nData2</DFN> field when finding a 783 * matching event. A value of 0 indicates that <DFN>nData2</DFN> must match, a 784 * value of 1 indicates that <DFN>nData2</DFN> does not have to match. 785 * 786 * @return 0 if the event was removed. -1 if no matching event was 787 * found. 788 ***********************************************************/ 789 VCHPRE_ int VCHPOST_ ilclient_remove_event(COMPONENT_T *comp, 790 OMX_EVENTTYPE event, 791 OMX_U32 nData1, 792 int ignore1, 793 OMX_U32 nData2, 794 int ignore2); 795 796 797 /** 798 * The <DFN>ilclient_return_events()</DFN> function removes all events 799 * from a component event list and adds them to the IL client free 800 * event list. This function is automatically called when components 801 * are freed. 802 * 803 * @param comp The component from which all events should be moved to 804 * the free list. 805 * 806 * @return void 807 ***********************************************************/ 808 VCHPRE_ void VCHPOST_ ilclient_return_events(COMPONENT_T *comp); 809 810 811 /** 812 * The <DFN>ilclient_wait_for_event()</DFN> function is similar to 813 * <DFN>ilclient_remove_event()</DFN>, but allows the caller to block until that 814 * event arrives. 815 * 816 * @param comp The component that returned the matching event. 817 * 818 * @param event The event type of the matching event. 819 * 820 * @param nData1 The <DFN>nData1</DFN> field of the matching event. 821 * 822 * @param ignore1 Whether to ignore the <DFN>nData1</DFN> field when finding a 823 * matching event. A value of 0 indicates that <DFN>nData1</DFN> must match, a 824 * value of 1 indicates that <DFN>nData1</DFN> does not have to match. 825 * 826 * @param nData2 The <DFN>nData2</DFN> field of the matching event. 827 * 828 * @param ignore2 Whether to ignore the <DFN>nData2</DFN> field when finding a 829 * matching event. A value of 0 indicates that <DFN>nData2</DFN> must match, a 830 * value of 1 indicates that <DFN>nData2</DFN> does not have to match. 831 * 832 * @param event_flag Specifies a bitfield of IL client events to wait 833 * for, given in <DFN>ILEVENT_MASK_T</DFN>. If any of these events 834 * are signalled by the component, the event list is then re-checked 835 * for a matching event. If the <DFN>ILCLIENT_EVENT_ERROR</DFN> bit 836 * is included, and an error is signalled by the component, then the 837 * function will return an error code. If the 838 * <DFN>ILCLIENT_CONFIG_CHANGED</DFN> bit is included, and this bit is 839 * signalled by the component, then the function will return an error 840 * code. 841 * 842 * @param timeout Specifies how long to block for in milliseconds 843 * before returning a failure. 844 * 845 * @return 0 indicates success, a matching event has been removed from 846 * the component's event queue. A negative return indicates failure, 847 * in this case no events have been removed from the component's event 848 * queue. 849 * - -1: a timeout was received. 850 * - -2: an error event was received. 851 * - -3: a config changed event was received. 852 ***********************************************************/ 853 VCHPRE_ int VCHPOST_ ilclient_wait_for_event(COMPONENT_T *comp, 854 OMX_EVENTTYPE event, 855 OMX_U32 nData1, 856 int ignore1, 857 OMX_U32 nData2, 858 int ignore2, 859 int event_flag, 860 int timeout); 861 862 863 /** 864 * The <DFN>ilclient_wait_for_command_complete()</DFN> function waits 865 * for a message from a component that indicates that the command 866 * has completed. This is either a command success message, or an 867 * error message that signals the completion of an event. 868 * 869 * @param comp The component currently processing a command. 870 * 871 * @param command The command being processed. This must be either 872 * <DFN>OMX_CommandStateSet</DFN>, <DFN>OMX_CommandPortDisable</DFN> 873 * or <DFN>OMX_CommandPortEnable</DFN>. 874 * 875 * @param nData2 The expected value of <DFN>nData2</DFN> in the 876 * command complete message. 877 * 878 * @return 0 indicates success, either the command successfully completed 879 * or the <DFN>OMX_ErrorSameState</DFN> was returned. -1 indicates 880 * that the command terminated with a different error message. 881 ***********************************************************/ 882 VCHPRE_ int VCHPOST_ ilclient_wait_for_command_complete(COMPONENT_T *comp, 883 OMX_COMMANDTYPE command, 884 OMX_U32 nData2); 885 886 887 /** 888 * The <DFN>ilclient_wait_for_command_complete_dual()</DFN> function 889 * is similar to <DFN>ilclient_wait_for_command_complete()</DFN>. The 890 * difference is that while waiting for the component to complete the 891 * event or raise an error, we can also report if another reports an 892 * error that terminates a command. This is useful if the two 893 * components are tunneled, and we need to wait for one component to 894 * enable a port, or change state to <DFN>OMX_StateIdle</DFN>. If the 895 * other component is the buffer supplier and reports an error, then 896 * it will not allocate buffers, so our first component may stall. 897 * 898 * @param comp The component currently processing a command. 899 * 900 * @param command The command being processed. This must be either 901 * <DFN>OMX_CommandStateSet</DFN>, <DFN>OMX_CommandPortDisable</DFN> 902 * or <DFN>OMX_CommandPortEnable</DFN>. 903 * 904 * @param nData2 The expected value of <DFN>nData2</DFN> in the 905 * command complete message. 906 * 907 * @param related Another component, where we will return if this 908 * component raises an error that terminates a command. 909 * 910 * @return 0 indicates success, either the command successfully 911 * completed or the <DFN>OMX_ErrorSameState</DFN> was returned. -1 912 * indicates that the command terminated with a different error 913 * message. -2 indicates that the related component raised an error. 914 * In this case, the error is not cleared from the related 915 * component's event list. 916 ***********************************************************/ 917 VCHPRE_ int VCHPOST_ ilclient_wait_for_command_complete_dual(COMPONENT_T *comp, 918 OMX_COMMANDTYPE command, 919 OMX_U32 nData2, 920 COMPONENT_T *related); 921 922 923 /** 924 * The <DFN>ilclient_debug_output()</DFN> function adds a message to a 925 * host-specific debug display. For a local VideoCore host the message is 926 * added to the internal message log. For a Win32 host the message is 927 * printed to the debug display. This function should be customised 928 * when IL client is ported to another platform. 929 * 930 * @param format A message to add, together with the variable 931 * argument list similar to <DFN>printf</DFN> and other standard C functions. 932 * 933 * @return void 934 ***********************************************************/ 935 VCHPRE_ void VCHPOST_ ilclient_debug_output(char *format, ...); 936 937 /** 938 * The <DFN>ilclient_get_handle()</DFN> function returns the 939 * underlying OMX component held by an IL component handle. This is 940 * needed when calling methods such as <DFN>OMX_SetParameter</DFN> on 941 * a component created using the IL client library. 942 * 943 * @param comp IL component handle 944 * 945 * @return The <DFN>OMX_HANDLETYPE</DFN> value for the component. 946 ***********************************************************/ 947 VCHPRE_ OMX_HANDLETYPE VCHPOST_ ilclient_get_handle(COMPONENT_T *comp); 948 949 950 #ifndef OMX_SKIP64BIT 951 952 /** 953 * Macro to return <DFN>OMX_TICKS</DFN> from a signed 64 bit value. 954 * This is the version where <DFN>OMX_TICKS</DFN> is a signed 64 bit 955 * value, an alternative definition is used when <DFN>OMX_TICKS</DFN> 956 * is a structure. 957 */ 958 #define ilclient_ticks_from_s64(s) (s) 959 960 /** 961 * Macro to return signed 64 bit value from <DFN>OMX_TICKS</DFN>. 962 * This is the version where <DFN>OMX_TICKS</DFN> is a signed 64 bit 963 * value, an alternative definition is used when <DFN>OMX_TICKS</DFN> 964 * is a structure. 965 */ 966 #define ilclient_ticks_to_s64(t) (t) 967 968 #else 969 970 /** 971 * Inline function to return <DFN>OMX_TICKS</DFN> from a signed 64 bit 972 * value. This is the version where <DFN>OMX_TICKS</DFN> is a 973 * structure, an alternative definition is used when 974 * <DFN>OMX_TICKS</DFN> is a signed 64 bit value. 975 */ 976 static inline OMX_TICKS ilclient_ticks_from_s64(int64_t s) { 977 OMX_TICKS ret; 978 ret.nLowPart = s; 979 ret.nHighPart = s>>32; 980 return ret; 981 } 982 983 /** 984 * Inline function to return signed 64 bit value from 985 * <DFN>OMX_TICKS</DFN>. This is the version where 986 * <DFN>OMX_TICKS</DFN> is a structure, an alternative definition is 987 * used when <DFN>OMX_TICKS</DFN> is a signed 64 bit value. 988 */ 989 static inline int64_t ilclient_ticks_to_s64(OMX_TICKS t) { 990 uint64_t u = t.nLowPart | ((uint64_t)t.nHighPart << 32); 991 return u; 992 } 993 994 995 #endif /* OMX_SKIP64BIT */ 996 997 /** 998 * The <DFN>ilclient_get_port_index()</DFN> function returns the n'th 999 * port index of the specified type and direction for the given 1000 * component. 1001 * 1002 * @param comp The component of interest 1003 * @param dir The direction 1004 * @param type The type, or -1 for any type. 1005 * @param index Which port (counting from 0). 1006 * 1007 * @return The port index, or -1 if not found. 1008 ***********************************************************/ 1009 VCHPRE_ int VCHPOST_ ilclient_get_port_index(COMPONENT_T *comp, 1010 OMX_DIRTYPE dir, 1011 OMX_PORTDOMAINTYPE type, 1012 int index); 1013 1014 1015 /** 1016 * The <DFN>ilclient_suggest_bufsize()</DFN> function gives a 1017 * component a hint about the size of buffer it should use. This size 1018 * is set on the component by setting the 1019 * <DFN>OMX_IndexParamBrcmOutputBufferSize</DFN> index on the given 1020 * component. 1021 * 1022 * @param comp IL component handle 1023 * @param nBufSizeHint Size of buffer in bytes 1024 * 1025 * @return 0 indicates success, -1 indicates failure. 1026 ***********************************************************/ 1027 VCHPRE_ int VCHPOST_ ilclient_suggest_bufsize(COMPONENT_T *comp, 1028 OMX_U32 nBufSizeHint); 1029 1030 1031 /** 1032 * The <DFN>ilclient_stack_size()</DFN> function suggests a minimum 1033 * stack size that tasks calling into with API will require. 1034 * 1035 * @return Suggested stack size in bytes. 1036 ***********************************************************/ 1037 VCHPRE_ unsigned int VCHPOST_ ilclient_stack_size(void); 1038 1039 #endif /* ILCLIENT_H */