vc_cecservice.lua

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

]]