Port connection utility

Classes
struct	MMAL_CONNECTION_T

Typedefs
typedef struct MMAL_CONNECTION_T	MMAL_CONNECTION_T
typedef void(*	MMAL_CONNECTION_CALLBACK_T) (MMAL_CONNECTION_T *connection)

Functions
MMAL_STATUS_T	mmal_connection_create (MMAL_CONNECTION_T **connection, MMAL_PORT_T *out, MMAL_PORT_T *in, uint32_t flags)
void	mmal_connection_acquire (MMAL_CONNECTION_T *connection)
MMAL_STATUS_T	mmal_connection_release (MMAL_CONNECTION_T *connection)
MMAL_STATUS_T	mmal_connection_destroy (MMAL_CONNECTION_T *connection)
MMAL_STATUS_T	mmal_connection_enable (MMAL_CONNECTION_T *connection)
MMAL_STATUS_T	mmal_connection_disable (MMAL_CONNECTION_T *connection)
MMAL_STATUS_T	mmal_connection_event_format_changed (MMAL_CONNECTION_T *connection, MMAL_BUFFER_HEADER_T *buffer)

Connection flags
The following flags describe the properties of the connection.
#define	MMAL_CONNECTION_FLAG_TUNNELLING   0x1
#define	MMAL_CONNECTION_FLAG_ALLOCATION_ON_INPUT   0x2
#define	MMAL_CONNECTION_FLAG_ALLOCATION_ON_OUTPUT   0x4
#define	MMAL_CONNECTION_FLAG_KEEP_BUFFER_REQUIREMENTS   0x8
#define	MMAL_CONNECTION_FLAG_DIRECT   0x10
#define	MMAL_CONNECTION_FLAG_KEEP_PORT_FORMATS   0x20

Detailed Description

The port connection utility functions can be used in place of common sequences of calls to the MMAL API in order to process buffers being passed between two ports.

Processing connection buffer headers

Either in response to the client callback function being called, or simply on a timer, the client will need to process the buffer headers of the connection (unless tunneling is used).

Buffer headers that are in the pool queue will need to be sent to the output port, while buffer headers in the connection queue are sent to the input port. The buffer headers in the connection queue may contain pixel data (the cmd field is zero) or an event (the cmd field is non-zero). In general, pixel data buffer headers need to be passed on, while event buffer headers are released. In the case of the format changed event, mmal_connection_event_format_changed() can be called before the event is released.

Other, specialized use cases may also be implemented, such as getting and immediately releasing buffer headers from the connection queue in order to prevent their propagation. This could be used to drop out video, for example.

Tunnelling connections

If the MMAL_CONNECTION_FLAG_TUNNELLING flag is set when the connection is created, MMAL tunneling will be used. This automates the passing of the buffer headers between the output port and input port, and back again. It will also do this as efficiently as possible, avoiding trips between the ARM and the VideoCore if both components are implemented on the VideoCore. The consequence of this is that there is no client callback made as buffer headers get transferred.

The client can still monitor the control port of a component (usually a sink component, such as video_render) for the end of stream, in order to know when to dismantle the connection.

Client callback

When not using tunnelling, the client callback function is called each time a buffer arrives from a port (either input or output).

Note

The callback is made on a different thread from the one used by the client to set up the connection, so care must be taken with thread safety. One option is to raise a signal to the main client thread that queue processing needs to be done, another is for the callback to perform the queue processing itself.

The client can also store an opaque pointer in the connection object, which is never used by the MMAL code and is only meaningful to the client.

Macro Definition Documentation

MMAL_CONNECTION_FLAG_ALLOCATION_ON_INPUT

#define MMAL_CONNECTION_FLAG_ALLOCATION_ON_INPUT   0x2

Force the pool of buffer headers used by the connection to be allocated on the input port.

Definition at line 94 of file mmal_connection.h.

MMAL_CONNECTION_FLAG_ALLOCATION_ON_OUTPUT

#define MMAL_CONNECTION_FLAG_ALLOCATION_ON_OUTPUT   0x4

Force the pool of buffer headers used by the connection to be allocated on the output port.

Definition at line 96 of file mmal_connection.h.

MMAL_CONNECTION_FLAG_DIRECT

#define MMAL_CONNECTION_FLAG_DIRECT   0x10

The connection is flagged as direct. This doesn't change the behaviour of the connection itself but is used by the the graph utility to specify that the buffer should be sent to the input port from with the port callback.

Definition at line 102 of file mmal_connection.h.

MMAL_CONNECTION_FLAG_KEEP_BUFFER_REQUIREMENTS

#define MMAL_CONNECTION_FLAG_KEEP_BUFFER_REQUIREMENTS   0x8

Specify that the connection should not modify the buffer requirements.

Definition at line 98 of file mmal_connection.h.

MMAL_CONNECTION_FLAG_KEEP_PORT_FORMATS

#define MMAL_CONNECTION_FLAG_KEEP_PORT_FORMATS   0x20

Specify that the connection should not modify the port formats.

Definition at line 104 of file mmal_connection.h.

MMAL_CONNECTION_FLAG_TUNNELLING

#define MMAL_CONNECTION_FLAG_TUNNELLING   0x1

The connection is tunnelled. Buffer headers do not transit via the client but directly from the output port to the input port.

Definition at line 92 of file mmal_connection.h.

Typedef Documentation

MMAL_CONNECTION_CALLBACK_T

typedef void(* MMAL_CONNECTION_CALLBACK_T) (MMAL_CONNECTION_T *connection)

Definition of the callback used by a connection to signal back to the client that a buffer header is available either in the pool or in the output queue.

Parameters

connection

Pointer to the connection

Definition at line 115 of file mmal_connection.h.

MMAL_CONNECTION_T

typedef struct MMAL_CONNECTION_T MMAL_CONNECTION_T

Forward type definition for a connection

Definition at line 108 of file mmal_connection.h.

Function Documentation

mmal_connection_acquire()

void mmal_connection_acquire

(

MMAL_CONNECTION_T *

connection

)

Acquire a reference on a connection. Acquiring a reference on a connection will prevent a connection from being destroyed until the acquired reference is released (by a call to mmal_connection_destroy). References are internally counted so all acquired references need a matching call to release them.

Parameters

connection

connection to acquire

mmal_connection_create()

MMAL_STATUS_T mmal_connection_create	(	MMAL_CONNECTION_T **	connection,
		MMAL_PORT_T *	out,
		MMAL_PORT_T *	in,
		uint32_t	flags
	)

Create a connection between two ports. The connection shall include a pool of buffer headers suitable for the current format of the output port. The format of the input port shall have been set to the same as that of the input port. Note that connections are reference counted and creating a connection automatically acquires a reference to it (released when mmal_connection_destroy is called).

Parameters

connection	The address of a connection pointer that will be set to point to the created connection.
out	The output port to use for the connection.
in	The input port to use for the connection.
flags	The flags specifying which type of connection should be created. A bitwise combination of Connection flags values.

Returns

MMAL_SUCCESS on success.

mmal_connection_destroy()

MMAL_STATUS_T mmal_connection_destroy

(

MMAL_CONNECTION_T *

connection

)

Destroy a connection. Release an acquired reference on a connection. Only actually destroys the connection when the last reference is being released. The actual destruction of the connection will start by disabling it, if necessary. Any pool, queue, and so on owned by the connection shall then be destroyed.

Parameters

connection

The connection to be destroyed.

Returns

MMAL_SUCCESS on success.

mmal_connection_disable()

MMAL_STATUS_T mmal_connection_disable

(

MMAL_CONNECTION_T *

connection

)

Disable a connection.

Parameters

connection

The connection to be disabled.

Returns

MMAL_SUCCESS on success.

mmal_connection_enable()

MMAL_STATUS_T mmal_connection_enable

(

MMAL_CONNECTION_T *

connection

)

Enable a connection. The format of the two ports must have been committed before calling this function, although note that on creation, the connection automatically copies and commits the output port's format to the input port.

The MMAL_CONNECTION_T::callback field must have been set if the MMAL_CONNECTION_FLAG_TUNNELLING flag was not specified on creation. The client may also set the MMAL_CONNECTION_T::user_data in order to get a pointer passed, via the connection, to the callback.

Parameters

connection

The connection to be enabled.

Returns

MMAL_SUCCESS on success.

mmal_connection_event_format_changed()

MMAL_STATUS_T mmal_connection_event_format_changed	(	MMAL_CONNECTION_T *	connection,
		MMAL_BUFFER_HEADER_T *	buffer
	)

Apply a format changed event to the connection. This function can be used when the client is processing buffer headers and receives a format changed event (MMAL_EVENT_FORMAT_CHANGED). The connection is reconfigured, changing the format of the ports, the number of buffer headers and the size of the payload buffers as necessary.

Parameters

connection	The connection to which the event shall be applied.
buffer	The buffer containing a format changed event.

Returns

MMAL_SUCCESS on success.

mmal_connection_release()

MMAL_STATUS_T mmal_connection_release

(

MMAL_CONNECTION_T *

connection

)

Release a reference on a connection Release an acquired reference on a connection. Triggers the destruction of the connection when the last reference is being released.

Note

This is in fact an alias of mmal_connection_destroy which is added to make client code clearer.

Parameters

connection

connection to release

Returns

MMAL_SUCCESS on success