287 lines
12 KiB
C
287 lines
12 KiB
C
/*
|
|
Copyright (c) 2012, Broadcom Europe Ltd
|
|
All rights reserved.
|
|
|
|
Redistribution and use in source and binary forms, with or without
|
|
modification, are permitted provided that the following conditions are met:
|
|
* Redistributions of source code must retain the above copyright
|
|
notice, this list of conditions and the following disclaimer.
|
|
* Redistributions in binary form must reproduce the above copyright
|
|
notice, this list of conditions and the following disclaimer in the
|
|
documentation and/or other materials provided with the distribution.
|
|
* Neither the name of the copyright holder nor the
|
|
names of its contributors may be used to endorse or promote products
|
|
derived from this software without specific prior written permission.
|
|
|
|
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
|
|
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
|
|
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
|
|
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY
|
|
DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
|
|
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
|
|
LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
|
|
ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
|
|
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
|
|
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
|
*/
|
|
|
|
#ifndef MMAL_PORT_H
|
|
#define MMAL_PORT_H
|
|
|
|
#ifdef __cplusplus
|
|
extern "C" {
|
|
#endif
|
|
|
|
/** \defgroup MmalPort Ports
|
|
* Definition of a MMAL port and its associated API */
|
|
/* @{ */
|
|
|
|
#include "mmal_types.h"
|
|
#include "mmal_format.h"
|
|
#include "mmal_buffer.h"
|
|
#include "mmal_parameters.h"
|
|
|
|
/** List of port types */
|
|
typedef enum
|
|
{
|
|
MMAL_PORT_TYPE_UNKNOWN = 0, /**< Unknown port type */
|
|
MMAL_PORT_TYPE_CONTROL, /**< Control port */
|
|
MMAL_PORT_TYPE_INPUT, /**< Input port */
|
|
MMAL_PORT_TYPE_OUTPUT, /**< Output port */
|
|
MMAL_PORT_TYPE_CLOCK, /**< Clock port */
|
|
MMAL_PORT_TYPE_INVALID = 0xffffffff /**< Dummy value to force 32bit enum */
|
|
|
|
} MMAL_PORT_TYPE_T;
|
|
|
|
/** \name Port capabilities
|
|
* \anchor portcapabilities
|
|
* The following flags describe the capabilities advertised by a port */
|
|
/* @{ */
|
|
/** The port is pass-through and doesn't need buffer headers allocated */
|
|
#define MMAL_PORT_CAPABILITY_PASSTHROUGH 0x01
|
|
/** The port wants to allocate the buffer payloads. This signals a preference that
|
|
* payload allocation should be done on this port for efficiency reasons. */
|
|
#define MMAL_PORT_CAPABILITY_ALLOCATION 0x02
|
|
/** The port supports format change events. This applies to input ports and is used
|
|
* to let the client know whether the port supports being reconfigured via a format
|
|
* change event (i.e. without having to disable the port). */
|
|
#define MMAL_PORT_CAPABILITY_SUPPORTS_EVENT_FORMAT_CHANGE 0x04
|
|
/* @} */
|
|
|
|
/** Definition of a port.
|
|
* A port is the entity that is exposed by components to receive or transmit
|
|
* buffer headers (\ref MMAL_BUFFER_HEADER_T). A port is defined by its
|
|
* \ref MMAL_ES_FORMAT_T.
|
|
*
|
|
* It may be possible to override the buffer requirements of a port by using
|
|
* the MMAL_PARAMETER_BUFFER_REQUIREMENTS parameter.
|
|
*/
|
|
typedef struct MMAL_PORT_T
|
|
{
|
|
struct MMAL_PORT_PRIVATE_T *priv; /**< Private member used by the framework */
|
|
const char *name; /**< Port name. Used for debugging purposes (Read Only) */
|
|
|
|
MMAL_PORT_TYPE_T type; /**< Type of the port (Read Only) */
|
|
uint16_t index; /**< Index of the port in its type list (Read Only) */
|
|
uint16_t index_all; /**< Index of the port in the list of all ports (Read Only) */
|
|
|
|
uint32_t is_enabled; /**< Indicates whether the port is enabled or not (Read Only) */
|
|
MMAL_ES_FORMAT_T *format; /**< Format of the elementary stream */
|
|
|
|
uint32_t buffer_num_min; /**< Minimum number of buffers the port requires (Read Only).
|
|
This is set by the component. */
|
|
uint32_t buffer_size_min; /**< Minimum size of buffers the port requires (Read Only).
|
|
This is set by the component. */
|
|
uint32_t buffer_alignment_min; /**< Minimum alignment requirement for the buffers (Read Only).
|
|
A value of zero means no special alignment requirements.
|
|
This is set by the component. */
|
|
uint32_t buffer_num_recommended; /**< Number of buffers the port recommends for optimal performance (Read Only).
|
|
A value of zero means no special recommendation.
|
|
This is set by the component. */
|
|
uint32_t buffer_size_recommended; /**< Size of buffers the port recommends for optimal performance (Read Only).
|
|
A value of zero means no special recommendation.
|
|
This is set by the component. */
|
|
uint32_t buffer_num; /**< Actual number of buffers the port will use.
|
|
This is set by the client. */
|
|
uint32_t buffer_size; /**< Actual maximum size of the buffers that will be sent
|
|
to the port. This is set by the client. */
|
|
|
|
struct MMAL_COMPONENT_T *component; /**< Component this port belongs to (Read Only) */
|
|
struct MMAL_PORT_USERDATA_T *userdata; /**< Field reserved for use by the client */
|
|
|
|
uint32_t capabilities; /**< Flags describing the capabilities of a port (Read Only).
|
|
* Bitwise combination of \ref portcapabilities "Port capabilities"
|
|
* values.
|
|
*/
|
|
|
|
} MMAL_PORT_T;
|
|
|
|
/** Commit format changes on a port.
|
|
*
|
|
* @param port The port for which format changes are to be committed.
|
|
* @return MMAL_SUCCESS on success
|
|
*/
|
|
MMAL_STATUS_T mmal_port_format_commit(MMAL_PORT_T *port);
|
|
|
|
/** Definition of the callback used by a port to send a \ref MMAL_BUFFER_HEADER_T
|
|
* back to the user.
|
|
*
|
|
* @param port The port sending the buffer header.
|
|
* @param buffer The buffer header being sent.
|
|
*/
|
|
typedef void (*MMAL_PORT_BH_CB_T)(MMAL_PORT_T *port, MMAL_BUFFER_HEADER_T *buffer);
|
|
|
|
/** Enable processing on a port
|
|
*
|
|
* If this port is connected to another, the given callback must be NULL, while for a
|
|
* disconnected port, the callback must be non-NULL.
|
|
*
|
|
* If this is a connected output port and is successfully enabled:
|
|
* <ul>
|
|
* <li>The port shall be populated with a pool of buffers, allocated as required, according
|
|
* to the buffer_num and buffer_size values.
|
|
* <li>The input port to which it is connected shall be set to the same buffer
|
|
* configuration and then be enabled. Should that fail, the original port shall be
|
|
* disabled.
|
|
* </ul>
|
|
*
|
|
* @param port port to enable
|
|
* @param cb callback use by the port to send a \ref MMAL_BUFFER_HEADER_T back
|
|
* @return MMAL_SUCCESS on success
|
|
*/
|
|
MMAL_STATUS_T mmal_port_enable(MMAL_PORT_T *port, MMAL_PORT_BH_CB_T cb);
|
|
|
|
/** Disable processing on a port
|
|
*
|
|
* Disabling a port will stop all processing on this port and return all (non-processed)
|
|
* buffer headers to the client.
|
|
*
|
|
* If this is a connected output port, the input port to which it is connected shall
|
|
* also be disabled. Any buffer pool shall be released.
|
|
*
|
|
* @param port port to disable
|
|
* @return MMAL_SUCCESS on success
|
|
*/
|
|
MMAL_STATUS_T mmal_port_disable(MMAL_PORT_T *port);
|
|
|
|
/** Ask a port to release all the buffer headers it currently has.
|
|
*
|
|
* Flushing a port will ask the port to send all the buffer headers it currently has
|
|
* to the client. Flushing is an asynchronous request and the flush call will
|
|
* return before all the buffer headers are returned to the client.
|
|
* It is up to the client to keep a count on the buffer headers to know when the
|
|
* flush operation has completed.
|
|
* It is also important to note that flushing will also reset the state of the port
|
|
* and any processing which was buffered by the port will be lost.
|
|
*
|
|
* \attention Flushing a connected port behaviour TBD.
|
|
*
|
|
* @param port The port to flush.
|
|
* @return MMAL_SUCCESS on success
|
|
*/
|
|
MMAL_STATUS_T mmal_port_flush(MMAL_PORT_T *port);
|
|
|
|
/** Set a parameter on a port.
|
|
*
|
|
* @param port The port to which the request is sent.
|
|
* @param param The pointer to the header of the parameter to set.
|
|
* @return MMAL_SUCCESS on success
|
|
*/
|
|
MMAL_STATUS_T mmal_port_parameter_set(MMAL_PORT_T *port,
|
|
const MMAL_PARAMETER_HEADER_T *param);
|
|
|
|
/** Get a parameter from a port.
|
|
* The size field must be set on input to the maximum size of the parameter
|
|
* (including the header) and will be set on output to the actual size of the
|
|
* parameter retrieved.
|
|
*
|
|
* \note If MMAL_ENOSPC is returned, the parameter is larger than the size
|
|
* given. The given parameter will have been filled up to its size and then
|
|
* the size field set to the full parameter's size. This can be used to
|
|
* resize the parameter buffer so that a second call should succeed.
|
|
*
|
|
* @param port The port to which the request is sent.
|
|
* @param param The pointer to the header of the parameter to get.
|
|
* @return MMAL_SUCCESS on success
|
|
*/
|
|
MMAL_STATUS_T mmal_port_parameter_get(MMAL_PORT_T *port,
|
|
MMAL_PARAMETER_HEADER_T *param);
|
|
|
|
/** Send a buffer header to a port.
|
|
*
|
|
* @param port The port to which the buffer header is to be sent.
|
|
* @param buffer The buffer header to send.
|
|
* @return MMAL_SUCCESS on success
|
|
*/
|
|
MMAL_STATUS_T mmal_port_send_buffer(MMAL_PORT_T *port,
|
|
MMAL_BUFFER_HEADER_T *buffer);
|
|
|
|
/** Connect an output port to an input port.
|
|
*
|
|
* When connected and enabled, buffers will automatically progress from the
|
|
* output port to the input port when they become available, and released back
|
|
* to the output port when no longer required by the input port.
|
|
*
|
|
* Ports can be given either way around, but one must be an output port and
|
|
* the other must be an input port. Neither can be connected or enabled
|
|
* already. The format of the output port will be applied to the input port
|
|
* on connection.
|
|
*
|
|
* @param port One of the ports to connect.
|
|
* @param other_port The other port to connect.
|
|
* @return MMAL_SUCCESS on success.
|
|
*/
|
|
MMAL_STATUS_T mmal_port_connect(MMAL_PORT_T *port, MMAL_PORT_T *other_port);
|
|
|
|
/** Disconnect a connected port.
|
|
*
|
|
* If the port is not connected, an error will be returned. Otherwise, if the
|
|
* ports are enabled, they will be disabled and any buffer pool created will be
|
|
* freed.
|
|
*
|
|
* @param port The ports to disconnect.
|
|
* @return MMAL_SUCCESS on success.
|
|
*/
|
|
MMAL_STATUS_T mmal_port_disconnect(MMAL_PORT_T *port);
|
|
|
|
/** Allocate a payload buffer.
|
|
* This allows a client to allocate memory for a payload buffer based on the preferences
|
|
* of a port. This for instance will allow the port to allocate memory which can be shared
|
|
* between the host processor and videocore.
|
|
*
|
|
* See \ref mmal_pool_create_with_allocator().
|
|
*
|
|
* @param port Port responsible for allocating the memory.
|
|
* @param payload_size Size of the payload buffer which will be allocated.
|
|
*
|
|
* @return Pointer to the allocated memory.
|
|
*/
|
|
uint8_t *mmal_port_payload_alloc(MMAL_PORT_T *port, uint32_t payload_size);
|
|
|
|
/** Free a payload buffer.
|
|
* This allows a client to free memory allocated by a previous call to \ref mmal_port_payload_alloc.
|
|
*
|
|
* See \ref mmal_pool_create_with_allocator().
|
|
*
|
|
* @param port Port responsible for allocating the memory.
|
|
* @param payload Pointer to the memory to free.
|
|
*/
|
|
void mmal_port_payload_free(MMAL_PORT_T *port, uint8_t *payload);
|
|
|
|
/** Get an empty event buffer header from a port
|
|
*
|
|
* @param port The port from which to get the event buffer header.
|
|
* @param buffer The address of a buffer header pointer, which will be set on return.
|
|
* @param event The specific event FourCC required. See the \ref MmalEvents "pre-defined events".
|
|
* @return MMAL_SUCCESS on success
|
|
*/
|
|
MMAL_STATUS_T mmal_port_event_get(MMAL_PORT_T *port, MMAL_BUFFER_HEADER_T **buffer, uint32_t event);
|
|
|
|
/* @} */
|
|
|
|
#ifdef __cplusplus
|
|
}
|
|
#endif
|
|
|
|
#endif /* MMAL_PORT_H */
|