forked from Qortal/Brooklyn
516 lines
20 KiB
C
516 lines
20 KiB
C
/*
|
|
Copyright (c) 2012, Broadcom Europe Ltd
|
|
All rights reserved.
|
|
|
|
Redistribution and use in source and binary forms, with or without
|
|
modification, are permitted provided that the following conditions are met:
|
|
* Redistributions of source code must retain the above copyright
|
|
notice, this list of conditions and the following disclaimer.
|
|
* Redistributions in binary form must reproduce the above copyright
|
|
notice, this list of conditions and the following disclaimer in the
|
|
documentation and/or other materials provided with the distribution.
|
|
* Neither the name of the copyright holder nor the
|
|
names of its contributors may be used to endorse or promote products
|
|
derived from this software without specific prior written permission.
|
|
|
|
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
|
|
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
|
|
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
|
|
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY
|
|
DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
|
|
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
|
|
LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
|
|
ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
|
|
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
|
|
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
|
*/
|
|
|
|
/*
|
|
* CEC service host API,
|
|
* See vc_cec.h and vc_cecservice_defs.h for related constants
|
|
*/
|
|
|
|
#ifndef _VC_CECSERVICE_H_
|
|
#define _VC_CECSERVICE_H_
|
|
|
|
#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,
|
|
vcos_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,
|
|
vcos_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(vcos_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, vcos_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, vcos_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,
|
|
vcos_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, vcos_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,
|
|
vcos_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,
|
|
vcos_bool_t is_reply);
|
|
|
|
#endif //_VC_CECSERVICE_H_
|