Description

The Driver component access the HDMI-CEC SoC Driver via the CEC HAL API. Vendors are responsible in delivering a SoC Driver that conforms to the HAL API (see hdmi_cec_driver.h)

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

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

Functions
int	HdmiCecOpen (int *handle)
	opens an instance of CEC driver. This function should be call once before the functions in this API can be used. More...

int	HdmiCecClose (int handle)
	close an instance of CEC driver. This function should close the currently opened driver instance. More...

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

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

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

int	HdmiCecGetLogicalAddress (int handle, int devType, int *logicalAddress)
	Get the Logical Addresses claimed by host device. More...

void	HdmiCecGetPhysicalAddress (int handle, unsigned int *physicalAddress)
	Get the Physical Address obtained by the driver. More...

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

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

int	HdmiCecTx (int handle, const unsigned char buf, int len, int result)
	Writes CEC packet onto bus. More...

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

Typedef Documentation

◆ HdmiCecRxCallback_t

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

CEC Driver should call this function whenever there is a complete CEC packet received. Upon each callback, only 1 complete CEC packet should be contained in the buffer.

Definition at line 158 of file hdmi_cec_driver.h.

◆ HdmiCecTxCallback_t

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

CEC Driver should call this function to report the status of the latest transmit.

Definition at line 164 of file hdmi_cec_driver.h.

Function Documentation

◆ HdmiCecOpen()

int HdmiCecOpen ( int * handle )

opens an instance of CEC driver.
This function should be call once before the functions in this API can be used.

Parameters

[in]		None.
[out]		handle used by application to uniquely identify the driver instance.

Returns: Error Code: If error code is returned, the open is failed.

Definition at line 68 of file hdmi_cec_driver.c.

◆ HdmiCecClose()

int HdmiCecClose ( int handle )

close an instance of CEC driver.
This function should close the currently opened driver instance.

Parameters

[in]		handle returned from the HdmiCecOpen() function.
[out]		None

Returns: Error Code: If error code is returned, the open is failed.

Definition at line 106 of file hdmi_cec_driver.c.

◆ 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]		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.
[out]		None

Returns: Error Code: If error code is returned, the set is failed.

Definition at line 324 of file hdmi_cec_driver.c.

◆ HdmiCecAddLogicalAddress()

int HdmiCecAddLogicalAddress	(	int	handle,
		int	logicalAddresses
	)

Add one Logical Addresses to be used by host device.

This function can block until the intended logical address is secured by the driver.

In driver implementation, this API would trigger driver sending a POLL CEC packet to the CEC Bus,

Packet::HeaderBlock::Initiator = Requested LogicalAddress. Packet::HeaderBlock::Destination = Requested LogicalAddress. Packet::DataBlock = Empty.

The function shall return HDMI_CEC_IO_SUCCESS if the POLL message is sent successfully and not ACK'd by any device on the bus. From this point on the driver shall forward all received messages with destination being the acquired logical address. Driver should ACK all POLL messages destined to this logical address.

The function shall return HDMI_CEC_IO_LOGICALADDRESS_UNAVAILABLE if the POLL message is sent and ACK'd by a device on the bus.

The function shall return relevant error code if the POLL message is not sent successfully.

Parameters

[in]		handle returned from the HdmiCecOpen() function.
[in]		logicalAddresses to be acquired.
[out]		None

Returns: Error Code: See above.

This function can block until the intended logical address is secured by the driver.

In driver implementation, this API would trigger driver sending a POLL CEC packet to the CEC Bus,

Packet::HeaderBlock::Initiator = Requested LogicalAddress. Packet::HeaderBlock::Destination = Requested LogicalAddress. Packet::DataBlock = Empty.

The function shall return HDMI_CEC_IO_SUCCESS if the POLL message is sent successfully and not ACK'd by any device on the bus. From this point on the driver shall forward all received messages with destination being the acquired logical address. Driver should ACK all POLL messsges destined to this logical address.

The function shall return HDMI_CEC_IO_LOGICALADDRESS_UNAVAILABLE if the POLL message is sent and ACK'd by a device on the bus.

The function shall return relevant error code if the POLL message is not sent successfully.

Parameters

[in]		handle returned from the HdmiCecOpen() function.
[in]		logicalAddresses to be acquired.
[out]		None

Returns: Error Code: See above.

Definition at line 146 of file hdmi_cec_driver.c.

◆ HdmiCecRemoveLogicalAddress()

int HdmiCecRemoveLogicalAddress	(	int	handle,
		int	logicalAddresses
	)

Clear the Logical Addresses claimed by host device.

This function releases the previously acquired logical address. Once released, driver should not ACK any POLL message destined to the released address.

Parameters

[in]		handle returned from the HdmiCecOpen() function.
[in]		logicalAddresses to be released.
[out]		None

Returns: Error Code: see above.

This function release the previously acquired logical address. Once released, driver should not ACK any POLL message destined to the released address.

Parameters

[in]		handle returned from the HdmiCecOpen() function.
[in]		logicalAddresses to be released.
[out]		None

Returns: Error Code: see above.

Definition at line 172 of file hdmi_cec_driver.c.

◆ HdmiCecGetLogicalAddress()

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

Get the Logical Addresses claimed by host device.

This function gets multiple logical addresses set by the host. It also means that the driver is actively pick up unicast messages destined to the set of logical addresses returned.

Parameters

[in]		handle returned from the HdmiCecOpen() function.
[out]		logicalAddresses list of addresses currently set.
	[in/out]	: size of the logicalAddress list. Returned number is the total number of addresses currently set. This can be larger than the input value. An returned value 0 indicate that no address is set.

Returns: Error Code: If error code is returned, the get is failed.

Get the Logical Address obtained by the driver.

This function get the logical address for the specified device type.

Parameters

[in]		handle returned from the HdmiCecOpen() function.
[in]		device type (tuner, record, playback etc.).
[out]		logical address acquired

Returns: Error Code: If error code is returned, the get is failed.

Definition at line 179 of file hdmi_cec_driver.c.

◆ HdmiCecGetPhysicalAddress()

void HdmiCecGetPhysicalAddress	(	int	handle,
		unsigned int *	physicalAddress
	)

Get the Physical Address obtained by the driver.

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

Parameters

[in]		handle returned from the HdmiCecOpen() function.
[out]		physical address acquired

Returns: None.

Definition at line 211 of file hdmi_cec_driver.c.

◆ HdmiCecSetRxCallback()

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

Sets CEC packet Receive callback.

This function sets a callback function to be invoked for each packet arrival.
The packet contained in the buffer is expected to 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.

When transmitting, it is driver'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) turns off the callback.

This function should block if callback invocation is in progress.

Parameters

[in]	handle	Handle returned from the HdmiCecOpen(() function.
[in]	cbfunc	A callback function to be invoked when a complete packet is received.
[in]	data	It is used when invoking callback function.

Returns: Error Code: If error code is returned, the set is failed.

This function sets a callback function to be invoked for each packet arrival.
The packet contained in the buffer is expected to 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) + oprand 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.

When transmitting, it is driver'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) turns off the callback.

This function should block if callback invocation is in progress.

Parameters

[in]		handle returned from the HdmiCecOpen(() function.
[in]		cbfunc to be invoked when a complete packet is received.
[in]		data, used when invoking callback function.

Returns: Error Code: If error code is returned, the set is failed.

Definition at line 242 of file hdmi_cec_driver.c.

◆ HdmiCecSetTxCallback()

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

Sets CEC packet Transmit callback.

This function sets a callback function to be invoked once the async transmit result is available. This is only necessary if application choose to transmit the packet asynchronously.

This function should block if callback invocation is in progress.

Parameters

[in]	handle	Returned from the HdmiCecOpen(() function.
[in]	cbfunc	Function pointer to be invoked when a complete packet is received.
[in]	data	It is used when invoking callback function.

Returns: Error Code: If error code is returned, the set is failed.

This function sets a callback function to be invoked once the async tranmit result is available. This is only necessary if application choose to transmit the packet asynchronously.

This function should block if callback invocation is in progress.

Parameters

[in]		handle returned from the HdmiCecOpen(() function.
[in]		cbfunc to be invoked when a complete packet is received.
[in]		data, used when invoking callback function.

Returns: Error Code: If error code is returned, the set is failed.

Definition at line 255 of file hdmi_cec_driver.c.

◆ HdmiCecTx()

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

Writes CEC packet onto bus.

This function writes a complete CEC packet onto the CEC bus and wait for ACK. application should check for result when return value of the function is 0;

The bytes in

Parameters

	buf	that is to be transmitted should follow the buffer byte format required for receiving buffer. (See detailed description from HdmiCecSetRxCallback)
[in]	handle	Returned from the HdmiCecOpen(() function.
[in]	buf	Buffer contains a complete CEC packet.
[in]	len	Number of bytes in the packet.
[out]	result	Output of the send. 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: If error code is returned, the transmit did not happen.

This function writes a complete CEC packet onto the CEC bus and wait for ACK. application should check for result when return value of the function is 0;

The bytes in

Parameters

	buf	that is to be transmitted should follow the buffer byte format required for receiving buffer. (See detailed description from HdmiCecSetRxCallback)
[in]		handle returned from the HdmiCecOpen(() function.
[in]		buf contains a complete CEC packet.
[in]		len number of bytes in the packet.
[out]		result of the send. Possbile results are SENT_AND_ACKD, SENT_BUT_NOT_ACKD (e.g. no follower at the destionation), SENT_FAILED (e.g. collision).

Returns: Error Code: If error code is returned, the transmit did not happen.

Definition at line 284 of file hdmi_cec_driver.c.

◆ 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 CEC bus but does not wait for ACK. The result will be reported via HdmiCecRxCallback_t if return value of this function is 0.

Parameters

[in]	handle	Handle returned from the HdmiCecOpen(() function.
[in]	buf	Buffer contains a complete CEC packet.
[in]	len	Number of bytes in the packet.

Returns: Error Code: If error code is returned, the transmit did not happen.

This function writes a complete CEC packet onto the CEC bus but does not wait for ACK. The result will be reported via HdmiCecRxCallback_t if return value of this function is 0.

Parameters

[in]		handle returned from the HdmiCecOpen(() function.
[in]		buf contains a complete CEC packet.
[in]		len number of bytes in the packet.

Returns: Error Code: If error code is returned, the transmit did not happen.

Definition at line 268 of file hdmi_cec_driver.c.

Description

Typedefs

Functions

Typedef Documentation

◆ HdmiCecRxCallback_t

◆ HdmiCecTxCallback_t

Function Documentation

◆ HdmiCecOpen()

◆ HdmiCecClose()

◆ HdmiCecSetLogicalAddress()

◆ HdmiCecAddLogicalAddress()

◆ HdmiCecRemoveLogicalAddress()

◆ HdmiCecGetLogicalAddress()

◆ HdmiCecGetPhysicalAddress()

◆ HdmiCecSetRxCallback()

◆ HdmiCecSetTxCallback()

◆ HdmiCecTx()

◆ HdmiCecTxAsync()