Collaboration diagram for HDMI CEC Header:

Files
file	hdmi_cec_driver.h

Typedefs
typedef void(*	HdmiCecRxCallback_t) (int handle, void callbackData, unsigned char buf, int len)
	Callback function triggered when a complete CEC packet is received.

typedef void(*	HdmiCecTxCallback_t) (int handle, void *callbackData, int result)
	Callback function triggered to report the status of the latest transmit message.

Enumerations
enum	{ HDMI_CEC_IO_SUCCESS = 0 , HDMI_CEC_IO_SENT_AND_ACKD = 1 , HDMI_CEC_IO_SENT_BUT_NOT_ACKD , HDMI_CEC_IO_SENT_FAILED , HDMI_CEC_IO_INVALID_STATE , HDMI_CEC_IO_INVALID_ARGUMENT , HDMI_CEC_IO_LOGICALADDRESS_UNAVAILABLE , HDMI_CEC_IO_GENERAL_ERROR }

Functions
int	HdmiCecOpen (int *handle)
	Initializes the HDMI CEC HAL.

int	HdmiCecClose (int handle)
	Closes an instance of HDMI CEC HAL.

int	HdmiCecSetLogicalAddress (int handle, int *logicalAddresses, int num)
	This API is DEPRECATED due to possible race conditions competing for a logical address.

void	HdmiCecGetPhysicalAddress (int handle, unsigned int *physicalAddress)
	Gets the Physical Address obtained by the module.

int	HdmiCecAddLogicalAddress (int handle, int logicalAddresses)
	Adds one Logical Addresses to be used by host device.

int	HdmiCecRemoveLogicalAddress (int handle, int logicalAddresses)
	Clears the Logical Addresses claimed by the host device.

int	HdmiCecGetLogicalAddress (int handle, int devType, int *logicalAddress)
	Gets the Logical Address obtained by the module.

int	HdmiCecSetRxCallback (int handle, HdmiCecRxCallback_t cbfunc, void *data)
	Sets CEC packet receive callback.

int	HdmiCecSetTxCallback (int handle, HdmiCecTxCallback_t cbfunc, void *data)
	Sets CEC packet transmit callback.

int	HdmiCecTx (int handle, const unsigned char buf, int len, int result)
	Synchronous transmit call.

int	HdmiCecTxAsync (int handle, const unsigned char *buf, int len)
	Writes CEC packet onto bus asynchronously.

Detailed Description

Typedef Documentation

◆ HdmiCecRxCallback_t

typedef void(* HdmiCecRxCallback_t) (int handle, void *callbackData, unsigned char *buf, int len)

Callback function triggered when a complete CEC packet is received.

Upon each callback, only 1 complete packet should be contained in the buffer.

Parameters

[in]	handle	- The handle used by application to uniquely identify the HAL instance. Non zero value
[in]	callbackData	- Callback data for the receive callback
[in]	buf	- Buffer passed in receive callback
[in]	len	- Length of buffer passed in receive callback

◆ HdmiCecTxCallback_t

typedef void(* HdmiCecTxCallback_t) (int handle, void *callbackData, int result)

Callback function triggered to report the status of the latest transmit message.

Parameters

[in]	handle	- The handle used by application to uniquely identify the HAL instance. Non zero value
[in]	callbackData	- Callback data for the transmit callback
[in]	result	- Async transmit result from the platform implementation

Enumeration Type Documentation

◆ anonymous enum

anonymous enum

Enumerator
HDMI_CEC_IO_SUCCESS	Input output operation is successful.
HDMI_CEC_IO_SENT_AND_ACKD	Send and acknowledgement received.
HDMI_CEC_IO_SENT_BUT_NOT_ACKD	Sent but acknowledgement not received.
HDMI_CEC_IO_SENT_FAILED	Operation failed.
HDMI_CEC_IO_INVALID_STATE
HDMI_CEC_IO_INVALID_ARGUMENT	Invalid argument is passed to the module.
HDMI_CEC_IO_LOGICALADDRESS_UNAVAILABLE	Logical address is not available.
HDMI_CEC_IO_GENERAL_ERROR	Operation general error.

Function Documentation

◆ HdmiCecAddLogicalAddress()

int HdmiCecAddLogicalAddress	(	int	handle,
		int	logicalAddresses )

Adds one Logical Addresses to be used by host device.

This function will block until the intended logical address is secured by the module.
HAL will forward all received messages with destination being the acquired logical address.
HAL should ACK all POLL messages destined to this logical address.
This API is only applicable for sink devices. Supported logical address value must be 0x0.
Invoking this API in source device must return HDMI_CEC_IO_INVALID_ARGUMENT

In HAL implementation, this API would trigger HAL sending a POLL CEC packet to the CEC Bus:
Packet::HeaderBlock::Initiator = Requested LogicalAddress
Packet::HeaderBlock::Destination = Requested LogicalAddress
Packet::DataBlock = Empty

Parameters

[in]	handle	- The handle returned from the HdmiCecOpen() function. Non zero value
[in]	logicalAddresses	- The logical address to be acquired

Returns: Error Code - Status

Return values

HDMI_CEC_IO_SUCCESS	- POLL message is sent successfully and not ACK'd by any device on the bus
HDMI_CEC_IO_INVALID_ARGUMENT	- Parameter passed to this function is invalid i.e. be if any logical address other than 0x0 is given as argument
HDMI_CEC_IO_LOGICALADDRESS_UNAVAILABLE	- POLL message is sent and ACK'd by a device on the bus
HDMI_CEC_IO_SENT_FAILED	- POLL message send failed.

Precondition: HdmiCecOpen() must be called before calling this API.

Warning: This API is NOT thread safe.

See also: HdmiCecRemoveLogicalAddress(), HdmiCecGetLogicalAddress()

◆ HdmiCecClose()

int HdmiCecClose ( int handle )

Closes an instance of HDMI CEC HAL.

This function will uninitialise the module.
Close will clear up registered logical addresses.
Subsequent calls to this API will return HDMI_CEC_IO_SUCCESS.

Parameters

[in] handle - The handle returned from the HdmiCecOpen(). Non zero value

Returns: Error Code - Status

Return values

HDMI_CEC_IO_SUCCESS - Success

Precondition: HdmiCecOpen() must be called before calling this API.

Warning: This API is NOT thread safe.

See also: HdmiCecOpen()

◆ HdmiCecGetLogicalAddress()

int HdmiCecGetLogicalAddress	(	int	handle,
		int	devType,
		int *	logicalAddress )

Gets the Logical Address obtained by the module.

This function gets the logical address for the specified device type.
For sink devices, if logical address is not added or removed, the logical address returned will be 0x0F. For source devices, logical address returned must be in between 0x00 and 0x0F, excluding both the values.

Parameters

[in]	handle	- The handle returned from the HdmiCecOpen(). Non zero value
[in]	devType	- device type (tuner, record, playback etc.).
[out]	logicalAddress	- The logical address acquired

Returns: Error Code - Status

Return values

HDMI_CEC_IO_SUCCESS	- Success
HDMI_CEC_IO_INVALID_ARGUMENT	- Parameter passed to this function is invalid

Precondition: HdmiCecOpen() must be called before calling this API.

Warning: This API is NOT thread safe.

Note: This API is not required if the SOC is performing the logical address discovery.

See also: HdmiCecAddLogicalAddress(), HdmiCecRemoveLogicalAddress()

◆ HdmiCecGetPhysicalAddress()

void HdmiCecGetPhysicalAddress	(	int	handle,
		unsigned int *	physicalAddress )

Gets the Physical Address obtained by the module.

This function gets the Physical address for the specified device type.

Parameters

[in]	handle	- The handle returned from the HdmiCecOpen(). Non zero value
[out]	physicalAddress	- Physical address acquired Max possible physical address is 4.4.4.4 and respective integer value is (((0x04 &0xF0 ) << 20)\|( (0x04 &0x0F ) << 16) \|((0x04 & 0xF0) << 4) \| (0x04 & 0x0F)) Min value for physicalAddress is 0

Precondition: HdmiCecOpen() must be called before calling this API.

Warning: This API is NOT thread safe.

See also: HdmiCecGetLogicalAddress()

◆ HdmiCecOpen()

int HdmiCecOpen ( int * handle )

Initializes the HDMI CEC HAL.

This function is required to be called before the other APIs in this module.
Subsequent calls to this API will return HDMI_CEC_IO_SUCCESS.

Parameters

[out] handle - The handle used by application to uniquely identify the HAL instance

Returns: Error Code - Status

Return values

HDMI_CEC_IO_SUCCESS	- Success
HDMI_CEC_IO_INVALID_ARGUMENT	- Parameter passed to this function is invalid
HDMI_CEC_IO_LOGICALADDRESS_UNAVAILABLE	- Logical address is not available for source devices.

Note: For sink devices logical address discovery will not happen in HdmiCecOpen()

Warning: This API is NOT thread safe.

See also: HdmiCecClose()

◆ HdmiCecRemoveLogicalAddress()

int HdmiCecRemoveLogicalAddress	(	int	handle,
		int	logicalAddresses )

Clears the Logical Addresses claimed by the host device.

This function releases the previously acquired logical address.
Once released, the module must not ACK any POLL message destined to the released address.
Subsequent calls to this API will return HDMI_CEC_IO_SUCCESS. This API is only applicable for sink devices. Invoking this API in source device must return HDMI_CEC_IO_INVALID_ARGUMENT

Parameters

[in]	handle	- The handle returned from the HdmiCecOpen(). Non zero value
[in]	logicalAddresses	- The logicalAddresses to be released

Returns: Error Code - Status

Return values

HDMI_CEC_IO_SUCCESS	- Success
HDMI_CEC_IO_INVALID_ARGUMENT	- Parameter passed to this function is invalid - i.e. if any logical address other than 0x0 is given as argument

Precondition: HdmiCecOpen() must be called before calling this API.

Warning: This API is NOT thread safe.

See also: HdmiCecAddLogicalAddress(), HdmiCecGetLogicalAddress()

◆ HdmiCecSetLogicalAddress()

int HdmiCecSetLogicalAddress	(	int	handle,
		int *	logicalAddresses,
		int	num )

This API is DEPRECATED due to possible race conditions competing for a logical address.

Set the Logical Addresses claimed by host device. This function sets multiple logical addresses used by the host. The host has claimed these logical address through the Discovery process. Once set, the host shall receive all CEC packets destined to these addresses.

Once the driver is opened, the host shall receive all broadcast messages regardless the Logical addresses.

when there is no logical address set, the host shall only receive broadcast messages.

Parameters

[in]	handle	- returned from the HdmiCecOpen() function.
[in]	logicalAddresses	- set or replace addresses claimed by host. A null value clears the current list.
[in]	num	- number of logical addresses. If any logical address in the list cannot be set, none of them should be set upon return. Success return indicates that all addresses in the list are set.

Returns: Error Code - Status

Return values

HDMI_CEC_IO_SUCCESS - Success

Precondition: HdmiCecOpen() must be called before calling this API.

Warning: This API is NOT thread safe.

◆ HdmiCecSetRxCallback()

int HdmiCecSetRxCallback	(	int	handle,
		HdmiCecRxCallback_t	cbfunc,
		void *	data )

Sets CEC packet receive callback.

This function sets the callback function to be invoked for each packet arrival
The packet contained in the buffer will follow this format (ref <HDMI Specification 1-4> Section <CEC 6.1>) :

complete packet = header block + data block
header block = destination logical address (4-bit) + source address (4-bit)
data block = opcode block (8-bit) + operand block (N-bytes)

|------------------------------------------------
| header block  |          data blocks          |
|------------------------------------------------
|3|2|1|0|3|2|1|0|7|6|5|4|3|2|1|0|7|6|5|4|3|2|1|0|  
|------------------------------------------------
| Dest  |  src  |  opcode block | operand block |
|------------------------------------------------

When receiving, the returned buffer should not contain EOM and ACK bits. HAL internal logic.
HAL implementation should remove the EOM and ACK bits in the returned buffer

When transmitting, it is HAL's responsibility to insert EOM bit and ACK bit for each header or data block.

When HdmiCecSetRxCallback() is called, it replaces the previous set cbfunc and data values. Setting a value of (cbfunc=null) disables the callback.

This function will block if callback invocation is in progress.

Parameters

[in]	handle	- The handle returned from the HdmiCecOpen(() function. Non zero value
[in]	cbfunc	- Function pointer to be invoked when a complete packet is received. Please refer HdmiCecRxCallback_t
[in]	data	- Callback data

Returns: Error Code - Status

Return values

HDMI_CEC_IO_SUCCESS	- Success
HDMI_CEC_IO_INVALID_ARGUMENT	- An invalid argument has been passed

Precondition: HdmiCecOpen() must be called before calling this API.

Warning: This API is NOT thread safe.

See also: HdmiCecTx(), HdmiCecTxAsync(), HdmiCecSetTxCallback()

◆ HdmiCecSetTxCallback()

int HdmiCecSetTxCallback	(	int	handle,
		HdmiCecTxCallback_t	cbfunc,
		void *	data )

Sets CEC packet transmit callback.

This function sets a callback which will be invoked once the async transmit result is available. This is only necessary if the caller chooses to transmit the packet asynchronously.

This function will block if callback invocation is in progress.

Parameters

[in]	handle	- The handle returned from the HdmiCecOpen(). Non zero value.
[in]	cbfunc	- Function pointer to be invoked when a complete packet is transmitted. Please refer HdmiCecTxCallback_t
[in]	data	- Callback data

Returns: Error Code - Status

Return values

HDMI_CEC_IO_SUCCESS	- Success
HDMI_CEC_IO_INVALID_ARGUMENT	- An invalid argument has been passed

Precondition: HdmiCecOpen() must be called before calling this API.

Warning: This API is NOT thread safe.

See also: HdmiCecTx(), HdmiCecTxAsync()

◆ HdmiCecTx()

int HdmiCecTx	(	int	handle,
		const unsigned char *	buf,
		int	len,
		int *	result )

Synchronous transmit call.

This function writes a complete CEC packet onto the bus and waits for ACK.

The packet contained in the buffer will follow the format detailed in HdmiCecSetRxCallback_t(). (ref <HDMI Specification 1-4> Section <CEC 6.1>)

Parameters

[in]	handle	- The handle returned from the HdmiCecOpen() function. Non zero value
[in]	buf	- The buffer contains a complete CEC packet to send.
[in]	len	- Number of bytes in the packet.
[out]	result	- send status buffer. Possible results are SENT_AND_ACKD, SENT_BUT_NOT_ACKD (e.g. no follower at the destination), SENT_FAILED (e.g. collision).

Returns: Error Code - Status

Return values

HDMI_CEC_IO_SUCCESS	- Success
HDMI_CEC_IO_INVALID_ARGUMENT	- Parameter passed to this function is invalid
HDMI_CEC_IO_SENT_AND_ACKD	- Cec message is send and acknowledged.
HDMI_CEC_IO_SENT_BUT_NOT_ACKD	- Message sent but not acknowledged by the receiver. Host device is trying to send an invalid logical address
HDMI_CEC_IO_SENT_FAILED	- Send message failed

Precondition: HdmiCecOpen(), HdmiCecSetRxCallback() should be called before calling this API.

Warning: This API is Not thread safe.

See also: HdmiCecTxAsync(), HdmiCecSetRxCallback()

◆ HdmiCecTxAsync()

int HdmiCecTxAsync	(	int	handle,
		const unsigned char *	buf,
		int	len )

Writes CEC packet onto bus asynchronously.

This function writes a complete CEC packet onto the bus but does not wait for ACK. The result will be reported via HdmiCecRxCallback_t()

Parameters

[in]	handle	- The handle returned from the HdmiCecOpen() function. Non zero value
[in]	buf	- The buffer contains a complete CEC packet to send
[in]	len	- Number of bytes in the packet

Returns: Error Code - Status

Return values

HDMI_CEC_IO_SUCCESS	- Success
HDMI_CEC_IO_INVALID_ARGUMENT	- Parameter passed to this function is invalid

Precondition: HdmiCecOpen(), HdmiCecSetRxCallback(), HdmiCecSetTxCallback() should be called before calling this API.

Warning: This API is Not thread safe.

See also: HdmiCecTx(), HdmiCecSetRxCallback()

Files

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ HdmiCecRxCallback_t

◆ HdmiCecTxCallback_t

Enumeration Type Documentation

◆ anonymous enum

Function Documentation

◆ HdmiCecAddLogicalAddress()

◆ HdmiCecClose()

◆ HdmiCecGetLogicalAddress()

◆ HdmiCecGetPhysicalAddress()

◆ HdmiCecOpen()

◆ HdmiCecRemoveLogicalAddress()

◆ HdmiCecSetLogicalAddress()

◆ HdmiCecSetRxCallback()

◆ HdmiCecSetTxCallback()

◆ HdmiCecTx()

◆ HdmiCecTxAsync()