Ports

Classes
struct	MMAL_PORT_T

Typedefs
typedef struct MMAL_PORT_T	MMAL_PORT_T
typedef void(*	MMAL_PORT_BH_CB_T) (MMAL_PORT_T *port, MMAL_BUFFER_HEADER_T *buffer)

Enumerations
enum	MMAL_PORT_TYPE_T {   MMAL_PORT_TYPE_UNKNOWN = 0, MMAL_PORT_TYPE_CONTROL, MMAL_PORT_TYPE_INPUT, MMAL_PORT_TYPE_OUTPUT,   MMAL_PORT_TYPE_CLOCK, MMAL_PORT_TYPE_INVALID = 0xffffffff }

Functions
MMAL_STATUS_T	mmal_port_format_commit (MMAL_PORT_T *port)
MMAL_STATUS_T	mmal_port_enable (MMAL_PORT_T *port, MMAL_PORT_BH_CB_T cb)
MMAL_STATUS_T	mmal_port_disable (MMAL_PORT_T *port)
MMAL_STATUS_T	mmal_port_flush (MMAL_PORT_T *port)
MMAL_STATUS_T	mmal_port_parameter_set (MMAL_PORT_T *port, const MMAL_PARAMETER_HEADER_T *param)
MMAL_STATUS_T	mmal_port_parameter_get (MMAL_PORT_T *port, MMAL_PARAMETER_HEADER_T *param)
MMAL_STATUS_T	mmal_port_send_buffer (MMAL_PORT_T *port, MMAL_BUFFER_HEADER_T *buffer)
MMAL_STATUS_T	mmal_port_connect (MMAL_PORT_T *port, MMAL_PORT_T *other_port)
MMAL_STATUS_T	mmal_port_disconnect (MMAL_PORT_T *port)
uint8_t *	mmal_port_payload_alloc (MMAL_PORT_T *port, uint32_t payload_size)
void	mmal_port_payload_free (MMAL_PORT_T *port, uint8_t *payload)
MMAL_STATUS_T	mmal_port_event_get (MMAL_PORT_T *port, MMAL_BUFFER_HEADER_T **buffer, uint32_t event)

Port capabilities
The following flags describe the capabilities advertised by a port
#define	MMAL_PORT_CAPABILITY_PASSTHROUGH   0x01
#define	MMAL_PORT_CAPABILITY_ALLOCATION   0x02
#define	MMAL_PORT_CAPABILITY_SUPPORTS_EVENT_FORMAT_CHANGE   0x04

Detailed Description

Definition of a MMAL port and its associated API

Macro Definition Documentation

MMAL_PORT_CAPABILITY_ALLOCATION

#define MMAL_PORT_CAPABILITY_ALLOCATION   0x02

The port wants to allocate the buffer payloads. This signals a preference that payload allocation should be done on this port for efficiency reasons.

Definition at line 64 of file mmal_port.h.

MMAL_PORT_CAPABILITY_PASSTHROUGH

#define MMAL_PORT_CAPABILITY_PASSTHROUGH   0x01

The port is pass-through and doesn't need buffer headers allocated

Definition at line 61 of file mmal_port.h.

MMAL_PORT_CAPABILITY_SUPPORTS_EVENT_FORMAT_CHANGE

#define MMAL_PORT_CAPABILITY_SUPPORTS_EVENT_FORMAT_CHANGE   0x04

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).

Definition at line 68 of file mmal_port.h.

Typedef Documentation

MMAL_PORT_BH_CB_T

typedef void(* MMAL_PORT_BH_CB_T) (MMAL_PORT_T *port, MMAL_BUFFER_HEADER_T *buffer)

Definition of the callback used by a port to send a MMAL_BUFFER_HEADER_T back to the user.

Parameters

port	The port sending the buffer header.
buffer	The buffer header being sent.

Definition at line 132 of file mmal_port.h.

MMAL_PORT_T

typedef struct MMAL_PORT_T MMAL_PORT_T

Definition of a port. A port is the entity that is exposed by components to receive or transmit buffer headers (MMAL_BUFFER_HEADER_T). A port is defined by its MMAL_ES_FORMAT_T.

It may be possible to override the buffer requirements of a port by using the MMAL_PARAMETER_BUFFER_REQUIREMENTS parameter.

Enumeration Type Documentation

MMAL_PORT_TYPE_T

enum MMAL_PORT_TYPE_T

List of port types

Enumerator
MMAL_PORT_TYPE_UNKNOWN	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	Dummy value to force 32bit enum

Definition at line 45 of file mmal_port.h.

Function Documentation

mmal_port_connect()

MMAL_STATUS_T mmal_port_connect	(	MMAL_PORT_T *	port,
		MMAL_PORT_T *	other_port
	)

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.

Parameters

port	One of the ports to connect.
other_port	The other port to connect.

Returns

MMAL_SUCCESS on success.

mmal_port_disable()

MMAL_STATUS_T mmal_port_disable

(

MMAL_PORT_T *

port

)

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.

Parameters

port	port to disable

Returns

MMAL_SUCCESS on success

mmal_port_disconnect()

MMAL_STATUS_T mmal_port_disconnect

(

MMAL_PORT_T *

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.

Parameters

port	The ports to disconnect.

Returns

MMAL_SUCCESS on success.

mmal_port_enable()

MMAL_STATUS_T mmal_port_enable	(	MMAL_PORT_T *	port,
		MMAL_PORT_BH_CB_T	cb
	)

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:

• The port shall be populated with a pool of buffers, allocated as required, according to the buffer_num and buffer_size values.
• 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.

Parameters

port	port to enable
cb	callback use by the port to send a MMAL_BUFFER_HEADER_T back

Returns

MMAL_SUCCESS on success

mmal_port_event_get()

MMAL_STATUS_T mmal_port_event_get	(	MMAL_PORT_T *	port,
		MMAL_BUFFER_HEADER_T **	buffer,
		uint32_t	event
	)

Get an empty event buffer header from a port

Parameters

port	The port from which to get the event buffer header.
buffer	The address of a buffer header pointer, which will be set on return.
event	The specific event FourCC required. See the pre-defined events.

Returns

MMAL_SUCCESS on success

mmal_port_flush()

MMAL_STATUS_T mmal_port_flush

(

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.

Parameters

port	The port to flush.

Returns

MMAL_SUCCESS on success

mmal_port_format_commit()

MMAL_STATUS_T mmal_port_format_commit

(

MMAL_PORT_T *

port

)

Commit format changes on a port.

Parameters

port	The port for which format changes are to be committed.

Returns

MMAL_SUCCESS on success

mmal_port_parameter_get()

MMAL_STATUS_T mmal_port_parameter_get	(	MMAL_PORT_T *	port,
		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.

Parameters

port	The port to which the request is sent.
param	The pointer to the header of the parameter to get.

Returns

MMAL_SUCCESS on success

mmal_port_parameter_set()

MMAL_STATUS_T mmal_port_parameter_set	(	MMAL_PORT_T *	port,
		const MMAL_PARAMETER_HEADER_T *	param
	)

Set a parameter on a port.

Parameters

port	The port to which the request is sent.
param	The pointer to the header of the parameter to set.

Returns

MMAL_SUCCESS on success

mmal_port_payload_alloc()

uint8_t* mmal_port_payload_alloc	(	MMAL_PORT_T *	port,
		uint32_t	payload_size
	)

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 mmal_pool_create_with_allocator().

Parameters

port	Port responsible for allocating the memory.
payload_size	Size of the payload buffer which will be allocated.

Returns

Pointer to the allocated memory.

mmal_port_payload_free()

void mmal_port_payload_free	(	MMAL_PORT_T *	port,
		uint8_t *	payload
	)

Free a payload buffer. This allows a client to free memory allocated by a previous call to mmal_port_payload_alloc.

See mmal_pool_create_with_allocator().

Parameters

port	Port responsible for allocating the memory.
payload	Pointer to the memory to free.

mmal_port_send_buffer()

MMAL_STATUS_T mmal_port_send_buffer	(	MMAL_PORT_T *	port,
		MMAL_BUFFER_HEADER_T *	buffer
	)

Send a buffer header to a port.

Parameters

port	The port to which the buffer header is to be sent.
buffer	The buffer header to send.

Returns

MMAL_SUCCESS on success