Skip to content
Find file
Fetching contributors…
Cannot retrieve contributors at this time
492 lines (453 sloc) 18.8 KB
local ffi = require "ffi"
/*
* CEC service host API,
* See vc_cec.h and vc_cecservice_defs.h for related constants
*/
ffi.cdef[[
#include "vcinclude/common.h"
#include "interface/vcos/vcos.h"
#include "interface/vchi/vchi.h"
#include "interface/vmcs_host/vc_cecservice_defs.h"
#include "interface/vmcs_host/vc_cec.h"
/**
* \file
* This API defines the controls for CEC. HDMI must be powered on before
* CEC is available (subject to CEC support in TV).
*
* In general, a zero return value indicates success; a negative return
* value indicates error in VCHI layer; a positive return value indicates
* alternative return value from the server
*/
/**
* Callback function for host side notification
* This is the SAME as the callback function type defined in vc_cec.h
* Host applications register a single callback for all CEC related notifications.
* See vc_cec.h for meanings of all parameters
*
* @param callback_data is the context passed in by user in <DFN>vc_cec_register_callback</DFN>
*
* @param reason bits 15-0 is VC_CEC_NOTIFY_T in vc_cec.h;
* bits 23-16 is the valid length of message in param1 to param4 (LSB of param1 is the byte0, MSB of param4 is byte15), little endian
* bits 31-24 is the return code (if any)
*
* @param param1 is the first parameter
*
* @param param2 is the second parameter
*
* @param param3 is the third parameter
*
* @param param4 is the fourth parameter
*
* @return void
*/
typedef void (*CECSERVICE_CALLBACK_T)(void *callback_data, uint32_t reason, uint32_t param1, uint32_t param2, uint32_t param3, uint32_t param4);
//API at application start time
/**
* Call <DFN>vc_vchi_cec_init</DFN> to initialise the CEC service for use.
*
* @param initialise_instance is the VCHI instance
* @param connections are array of pointers to VCHI connections
* @param num_connections is the number of connections in array
* @return void
**********************************************************/
VCHPRE_ void vc_vchi_cec_init(VCHI_INSTANCE_T initialise_instance, VCHI_CONNECTION_T **connections, uint32_t num_connections );
/**
* Call <DFN>vc_vchi_cec_stop</DFN> to stop host side CEC service.
*
* @param none
* @return void
**********************************************************/
VCHPRE_ void vc_vchi_cec_stop( void );
/**
* Host applications use <DFN>vc_cec_register_callaback</DFN> to register
* callback to handle all CEC notifications. If more than one applications
* need to use CEC, there should be ONE central application which acts on
* behalf of all clients and handles all communications with CEC services.
*
* @param callback function
* @param context to be passed when function is called
* @return void
***********************************************************/
VCHPRE_ void vc_cec_register_callback(CECSERVICE_CALLBACK_T callback, void *callback_data);
//Service API
/**
* Use <DFN>vc_cec_register_command</DFN> to register an opcode to
* to forwarded to the host application. By default <Feature Abort>
* is always forwarded. Once an opcode is registered, it is left to
* the host application to reply to a CEC message (where appropriate).
* It is recommended NOT to register the following commands as they
* are replied to automatically by CEC middleware:
* <Give Physical Address>, <Give Device Vendor ID>, <Give OSD Name>,
* <Get CEC Version>, <Give Device Power Status>, <Menu Request>,
* and <Get Menu Language>
* In addition, the following opcodes cannot be registered:
* <User Control Pressed>, <User Control Released>,
* <Vendor Remote Button Down>, <Vendor Remote Button Up>,
* and <Abort>.
* <Feature Abort> is always forwarded if it is the reply
* of a command the host sent.
*
* @param opcode to be registered.
*
* @return zero if the command is successful, non-zero otherwise
***********************************************************/
VCHPRE_ int VCHPOST_ vc_cec_register_command(CEC_OPCODE_T opcode);
/**
* <DFN>vc_cec_register_all</DFN> registers all opcodes except <Abort>
* to be forwarded as CEC_RX notification.
* Button presses <User Control Pressed>, etc. will still be forwarded
* separately as VC_CEC_BUTTON_PRESSED etc. notification.
*
* @param None
*
* @return zero if the command is successful, non-zero otherwise
***********************************************************/
VCHPRE_ int VCHPOST_ vc_cec_register_all( void );
/**
* Use <DFN>vc_cec_deregister_command</DFN> to remove an opcode from
* the filter for forwarding. By default <Feature Abort> is always forwarded.
* The following opcode cannot be deregistered:
* <User Control Pressed>, <User Control Released>,
* <Vendor Remote Button Down>, <Vendor Remote Button Up>,
* and <Abort>.
*
* @param opcode to be deregistered
*
* @return zero if the command is successful, non-zero otherwise
***********************************************************/
VCHPRE_ int VCHPOST_ vc_cec_deregister_command(CEC_OPCODE_T opcode);
/**
* <DFN>vc_cec_deregister_all</DFN> removes all registered opcodes,
* except the ones (e.g. button presses) which are always forwarded.
*
* @param None
*
* @return zero if the command is successful, non-zero otherwise
***********************************************************/
VCHPRE_ int VCHPOST_ vc_cec_deregister_all( void );
/**
* <DFN>vc_cec_send_message</DFN> allows a host application to
* send a CEC message to another device. There are several
* built-in functions for sending command messages. The host
* application MUST have a valid logical address (between 1 and
* 14 inclusive) before it can send a message.
* (For poll message set payload to NULL and length to zero).
*
* @param Follower's logical address
*
* @param Message payload WITHOUT the header byte (can be NULL)
*
* @param Payload length WITHOUT the header byte (can be zero)
*
* @param VC_TRUE if the message is a reply to an incoming message
*
* @return zero if the command is successful, non-zero otherwise
* If the command is successful, there will be a Tx callback
* in due course to indicate whether the message has been
* acknowledged by the recipient or not
***********************************************************/
VCHPRE_ int VCHPOST_ vc_cec_send_message(const uint32_t follower,
const uint8_t *payload,
uint32_t length,
bool_t is_reply);
/**
* <DFN>vc_cec_get_logical_address</DFN> gets the logical address,
* If one is being allocated 0xF (unregistered) will be set.
* A address value of 0xF also means CEC system is not yet ready
* to send or receive any messages.
*
* @param pointer to logical address (set to allocated address)
*
* @return zero if the command is successful, non-zero otherwise
* logical_address is not modified if command failed
***********************************************************/
VCHPRE_ int VCHPOST_ vc_cec_get_logical_address(CEC_AllDevices_T *logical_address);
/**
* <DFN>vc_cec_alloc_logical_address</DFN> starts the allocation
* of a logical address. Logical address is automatically allocated
* after HDMI power on is complete and AV mute is deassert.
* The host only needs to call this if the
* initial allocation failed (logical address being 0xF and
* physical address is NOT 0xFFFF from <DFN>VC_CEC_LOGICAL_ADDR</DFN>
* notification), or if the host explicitly released its logical
* address.
*
* @param none
*
* @return zero if the command is successful, non-zero otherwise
* If successful, there will be a callback notification
* <DFN>VC_CEC_LOGICAL_ADDR</DFN>.
* The host should wait for this before calling this
* function again.
***********************************************************/
VCHPRE_ int VCHPOST_ vc_cec_alloc_logical_address( void );
/**
* Normally <DFN>vc_cec_release_logical_address</DFN> will not
* be called by the host application. It is used to release
* our logical address. This effectively disables CEC.
* The host will need to allocate a new logical address before
* doing any CEC calls (send/receive message, get topology, etc.).
*
* @param none
*
* @return zero if the command is successful, non-zero otherwise
* The host should get a callback <DFN>VC_CEC_LOGICAL_ADDR</DFN>
* with 0xF being the logical address and 0xFFFF
* being the physical address.
***********************************************************/
VCHPRE_ int VCHPOST_ vc_cec_release_logical_address( void );
/**
* Use <DFN>vc_cec_get_topology</DFN> to get the topology.
*
* @param pointer to <DFN>VC_CEC_TOPOLOGY_T</DFN>
*
* @return zero if the command is successful, non-zero otherwise
* If successful, the topology will be set, otherwise it is unchanged
* A topology with only 1 device (us) means CEC is not supported.
* If there is no topology available, this also returns a failure.
***********************************************************/
VCHPRE_ int VCHPOST_ vc_cec_get_topology( VC_CEC_TOPOLOGY_T* topology);
/**
* Use <DFN>vc_cec_set_vendor_id</DFN> to
* set the response to <Give Device Vendor ID>
*
* @param 24-bit IEEE vendor id
*
* @return zero if the command is successful, non-zero otherwise
***********************************************************/
VCHPRE_ int VCHPOST_ vc_cec_set_vendor_id( const uint32_t id );
/**
* Use <DFN>vc_cec_set_osd_name</DFN> to
* set the response to <Give OSD Name>
*
* @param OSD name (14 byte char array)
*
* @return zero if the command is successful, non-zero otherwise
***********************************************************/
VCHPRE_ int VCHPOST_ vc_cec_set_osd_name( const char* name );
/**
* <DFN>vc_cec_get_physical_address</DFN> gets our physical address
*
* @param pointer to physical address (returned as 16-bit packed value)
*
* @return zero if the command is successful, non-zero otherwise
* If failed, physical address argument will not be changed
* A physical address of 0xFFFF means CEC is not supported
***********************************************************/
VCHPRE_ int VCHPOST_ vc_cec_get_physical_address(uint16_t *physical_address);
/**
* <DFN>vc_cec_get_vendor_id(</DFN> gets the vendor id of a particular logical address
*
* @param logical_address is the logical address of the device [in]
*
* @param vendorid is the pointer to vendor ID (24-bit IEEE OUI value) [out]
*
* @return zero if the command is successful, non-zero otherwise
* If failed, vendor id argument will not be changed
* A vendor ID of 0xFFFFFF means the device does not exist
* A vendor ID of 0x0 means vendor ID is not known and
* the application can send <Give Device Vendor ID> to that device
***********************************************************/
VCHPRE_ int VCHPOST_ vc_cec_get_vendor_id(const CEC_AllDevices_T logical_address, uint32_t *vendor_id);
/**
* <DFN>vc_cec_device_type(</DFN> returns the default device type of a particular
* logical address, which can be used as the argument to vc_cec_send_ReportPhysicalAddress.
*
* @param logical address
*
* @return the default device type, if there is any error, the return device
* type will be CEC_DeviceType_Invalid
*
************************************************************/
VCHPRE_ CEC_DEVICE_TYPE_T VCHPOST_ vc_cec_device_type(const CEC_AllDevices_T logical_address);
/**
* These couple of functions are provided for host application's convenience:
* If the xmit message is encapsulate in a VC_CEC_MESSAGE_T
* then it can be sent as a normal message (not as a reply)
* and the initiator field is ignored with vc_cec_send_message2
* and return zero for success
*
* Applications can call vc_cec_param2message to turn the callback parameters
* into a VC_CEC_MESSAGE_T (not for LOGICAL_ADDR and TOPOLOGY callbacks).
* It also returns zero for success.
*/
VCHPRE_ int VCHPOST_ vc_cec_send_message2(const VC_CEC_MESSAGE_T *message);
VCHPRE_ int VCHPOST_ vc_cec_param2message( const uint32_t reason, const uint32_t param1,
const uint32_t param2, const uint32_t param3,
const uint32_t param4, VC_CEC_MESSAGE_T *message);
//Extra API if CEC is running in passive mode
//If CEC is not in passive mode the following 3 functions always
//return failure
/**
* <DFN> vc_cec_poll_address </DFN> sets and polls a particular address to find out
* its availability in the CEC network. Only available when CEC is running in passive
* mode. The host can only call this function during logical address allocation stage.
*
* @param logical address to try
*
* @return 0 if poll is successful (address is occupied)
* >0 if poll is unsuccessful (Error code is in VC_CEC_ERROR_T in vc_cec.h)
* <0 VCHI errors
*/
VCHPRE_ int VCHPOST_ vc_cec_poll_address(const CEC_AllDevices_T logical_address);
/**
* <DFN> vc_cec_set_logical_address </DFN> sets the logical address, device type
* and vendor ID to be in use. Only available when CEC is running in passive
* mode. It is the responsibility of the host to make sure the logical address
* is actually free to be used. Physical address will be what is read from EDID.
*
* @param logical address
*
* @param device type
*
* @param vendor ID
*
* @return 0 if successful, non-zero otherwise
*/
VCHPRE_ int VCHPOST_ vc_cec_set_logical_address(const CEC_AllDevices_T logical_address,
const CEC_DEVICE_TYPE_T device_type,
const uint32_t vendor_id);
/**
* <DFN> vc_cec_add_device </DFN> adds a new device to topology.
* Only available when CEC is running in passive mode. Device will be
* automatically removed from topology if a failed xmit is detected.
* If last_device is true, it will trigger a topology computation
* (and may trigger a topology callback).
*
* @param logical address
*
* @param physical address
*
* @param device type
*
* @param true if this is the last device, false otherwise
*
* @return 0 if successful, non-zero otherwise
*/
VCHPRE_ int VCHPOST_ vc_cec_add_device(const CEC_AllDevices_T logical_address,
const uint16_t physical_address,
const CEC_DEVICE_TYPE_T device_type,
bool_t last_device);
/**
* <DFN> vc_cec_set_passive </DFN> enables and disables passive mode.
* Call this function first (with VC_TRUE as the argument) to enable
* passive mode before calling any of the above passive API functions
*
* @param TRUE to enable passive mode, FALSE to disable
*
* @return 0 if successful, non-zero otherwise
*/
VCHPRE_ int VCHPOST_ vc_cec_set_passive(bool_t enabled);
//API for some common CEC messages
/**
* Functions beginning with vc_cec_send_xxx make it easier for the
* host application to send CEC message xxx to other devices
*/
/**
* <DFN>vc_cec_send_FeatureAbort</DFN> sends <Feature Abort>
* for a received command.
*
* @param follower (cannot be 0xF)
*
* @param rejected opcode
*
* @param reject reason <DFN>CEC_ABORT_REASON_T</DFN>
*
* @return zero if the command is successful, non-zero otherwise
* Tx callback if successful
***********************************************************/
VCHPRE_ int VCHPOST_ vc_cec_send_FeatureAbort(uint32_t follower,
CEC_OPCODE_T opcode,
CEC_ABORT_REASON_T reason);
/**
* <DFN>vc_cec_send_ActiveSource</DFN> broadcasts
* <Active Source> to all devices
*
* @param physical address (16-bit packed)
*
* @param reply or not (normally not)
*
* @return zero if the command is successful, non-zero otherwise
* Tx callback if successful
***********************************************************/
VCHPRE_ int VCHPOST_ vc_cec_send_ActiveSource(uint16_t physical_address, bool_t is_reply);
/**
* <DFN>vc_cec_send_ImageViewOn</DFN> sends <Image View On>
*
* @param follower
*
* @param reply or not (normally not)
*
* @return zero if the command is successful, non-zero otherwise
* Tx callback if successful
***********************************************************/
VCHPRE_ int VCHPOST_ vc_cec_send_ImageViewOn(uint32_t follower, bool_t is_reply);
/**
* <DFN>vc_cec_send_SetOSDString</DFN> sends <Set OSD String>
*
* @param follower
*
* @param string (char[13])
*
* @param display control <DFN>CEC_DISPLAY_CONTROL_T</DFN>
*
* @param reply or not (normally not)
*
* @return zero if the command is successful, non-zero otherwise
* Tx callback if successful
***********************************************************/
VCHPRE_ int VCHPOST_ vc_cec_send_SetOSDString(uint32_t follower,
CEC_DISPLAY_CONTROL_T disp_ctrl,
const char* string,
bool_t is_reply);
/**
* <DFN>vc_cec_send_Standby</DFN> sends <Standby>.
* This will put any/all devices to standby if they support
* this CEC message.
*
* @param follower (can be 0xF)
*
* @param reply or not (normally not)
*
* @return zero if the command is successful, non-zero otherwise
* Tx callback if successful
***********************************************************/
VCHPRE_ int VCHPOST_ vc_cec_send_Standby(uint32_t follower, bool_t is_reply);
/**
* <DFN>vc_cec_send_MenuStatus</DFN> sends <Menu Status>
* (response to <Menu Request>)
*
* @param follower
*
* @param menu state <DFN>CEC_MENU_STATE_T</DFN> but NOT CEC_MENU_STATE_QUERY
*
* @param reply or not (should always be yes)
*
* @return zero if the command is successful, non-zero otherwise
* Tx callback if successful
***********************************************************/
VCHPRE_ int VCHPOST_ vc_cec_send_MenuStatus(uint32_t follower,
CEC_MENU_STATE_T menu_state,
bool_t is_reply);
/**
* <DFN>vc_cec_send_ReportPhysicalAddress</DFN> broadcasts
* <Report Physical Address> to all devices. Note although
* the passed in device type can be override the default one
* associated the allocated logical address, it is not
* recommended to do so. One can use <DFN>vc_cec_device_type</DFN>
* to get the default device type associated with the logical
* address returned via VC_CEC_LOGICAL_ADDR callback.
*
* @param physical address (16-bit packed)
*
* @param device type to be broadcasted
*
* @param reply or not (normally not)
*
* @return zero if the command is successful, non-zero otherwise
* Tx callback if successful
***********************************************************/
VCHPRE_ int VCHPOST_ vc_cec_send_ReportPhysicalAddress(uint16_t physical_address,
CEC_DEVICE_TYPE_T device_type,
bool_t is_reply);
]]
Something went wrong with that request. Please try again.