1/*
2Copyright (c) 2012, Broadcom Europe Ltd
3All rights reserved.
4
5Redistribution and use in source and binary forms, with or without
6modification, are permitted provided that the following conditions are met:
7 * Redistributions of source code must retain the above copyright
8 notice, this list of conditions and the following disclaimer.
9 * Redistributions in binary form must reproduce the above copyright
10 notice, this list of conditions and the following disclaimer in the
11 documentation and/or other materials provided with the distribution.
12 * Neither the name of the copyright holder nor the
13 names of its contributors may be used to endorse or promote products
14 derived from this software without specific prior written permission.
15
16THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
17ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
18WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
19DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY
20DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
21(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
22LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
23ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
24(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
25SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
26*/
27
28/*
29 * CEC service host API,
30 * See vc_cec.h and vc_cecservice_defs.h for related constants
31 */
32
33#ifndef _VC_CECSERVICE_H_
34#define _VC_CECSERVICE_H_
35
36#include "vcinclude/common.h"
37#include "interface/vcos/vcos.h"
38#include "interface/vchi/vchi.h"
39#include "interface/vmcs_host/vc_cecservice_defs.h"
40#include "interface/vmcs_host/vc_cec.h"
41
42/**
43 * \file
44 * This API defines the controls for CEC. HDMI must be powered on before
45 * CEC is available (subject to CEC support in TV).
46 *
47 * In general, a zero return value indicates success; a negative return
48 * value indicates error in VCHI layer; a positive return value indicates
49 * alternative return value from the server
50 */
51
52/**
53 * Callback function for host side notification
54 * This is the SAME as the callback function type defined in vc_cec.h
55 * Host applications register a single callback for all CEC related notifications.
56 * See vc_cec.h for meanings of all parameters
57 *
58 * @param callback_data is the context passed in by user in <DFN>vc_cec_register_callback</DFN>
59 *
60 * @param reason bits 15-0 is VC_CEC_NOTIFY_T in vc_cec.h;
61 * 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
62 * bits 31-24 is the return code (if any)
63 *
64 * @param param1 is the first parameter
65 *
66 * @param param2 is the second parameter
67 *
68 * @param param3 is the third parameter
69 *
70 * @param param4 is the fourth parameter
71 *
72 * @return void
73 */
74typedef void (*CECSERVICE_CALLBACK_T)(void *callback_data, uint32_t reason, uint32_t param1, uint32_t param2, uint32_t param3, uint32_t param4);
75
76//API at application start time
77/**
78 * Call <DFN>vc_vchi_cec_init</DFN> to initialise the CEC service for use.
79 *
80 * @param initialise_instance is the VCHI instance
81 * @param connections are array of pointers to VCHI connections
82 * @param num_connections is the number of connections in array
83 * @return void
84 **********************************************************/
85VCHPRE_ void vc_vchi_cec_init(VCHI_INSTANCE_T initialise_instance, VCHI_CONNECTION_T **connections, uint32_t num_connections );
86
87/**
88 * Call <DFN>vc_vchi_cec_stop</DFN> to stop host side CEC service.
89 *
90 * @param none
91 * @return void
92 **********************************************************/
93VCHPRE_ void vc_vchi_cec_stop( void );
94
95/**
96 * Host applications use <DFN>vc_cec_register_callaback</DFN> to register
97 * callback to handle all CEC notifications. If more than one applications
98 * need to use CEC, there should be ONE central application which acts on
99 * behalf of all clients and handles all communications with CEC services.
100 *
101 * @param callback function
102 * @param context to be passed when function is called
103 * @return void
104 ***********************************************************/
105VCHPRE_ void vc_cec_register_callback(CECSERVICE_CALLBACK_T callback, void *callback_data);
106
107//Service API
108/**
109 * Use <DFN>vc_cec_register_command</DFN> to register an opcode to
110 * to forwarded to the host application. By default <Feature Abort>
111 * is always forwarded. Once an opcode is registered, it is left to
112 * the host application to reply to a CEC message (where appropriate).
113 * It is recommended NOT to register the following commands as they
114 * are replied to automatically by CEC middleware:
115 * <Give Physical Address>, <Give Device Vendor ID>, <Give OSD Name>,
116 * <Get CEC Version>, <Give Device Power Status>, <Menu Request>,
117 * and <Get Menu Language>
118 * In addition, the following opcodes cannot be registered:
119 * <User Control Pressed>, <User Control Released>,
120 * <Vendor Remote Button Down>, <Vendor Remote Button Up>,
121 * and <Abort>.
122 * <Feature Abort> is always forwarded if it is the reply
123 * of a command the host sent.
124 *
125 * @param opcode to be registered.
126 *
127 * @return zero if the command is successful, non-zero otherwise
128 ***********************************************************/
129VCHPRE_ int VCHPOST_ vc_cec_register_command(CEC_OPCODE_T opcode);
130
131/**
132 * <DFN>vc_cec_register_all</DFN> registers all opcodes except <Abort>
133 * to be forwarded as CEC_RX notification.
134 * Button presses <User Control Pressed>, etc. will still be forwarded
135 * separately as VC_CEC_BUTTON_PRESSED etc. notification.
136 *
137 * @param None
138 *
139 * @return zero if the command is successful, non-zero otherwise
140 ***********************************************************/
141VCHPRE_ int VCHPOST_ vc_cec_register_all( void );
142
143/**
144 * Use <DFN>vc_cec_deregister_command</DFN> to remove an opcode from
145 * the filter for forwarding. By default <Feature Abort> is always forwarded.
146 * The following opcode cannot be deregistered:
147 * <User Control Pressed>, <User Control Released>,
148 * <Vendor Remote Button Down>, <Vendor Remote Button Up>,
149 * and <Abort>.
150 *
151 * @param opcode to be deregistered
152 *
153 * @return zero if the command is successful, non-zero otherwise
154 ***********************************************************/
155VCHPRE_ int VCHPOST_ vc_cec_deregister_command(CEC_OPCODE_T opcode);
156
157/**
158 * <DFN>vc_cec_deregister_all</DFN> removes all registered opcodes,
159 * except the ones (e.g. button presses) which are always forwarded.
160 *
161 * @param None
162 *
163 * @return zero if the command is successful, non-zero otherwise
164 ***********************************************************/
165VCHPRE_ int VCHPOST_ vc_cec_deregister_all( void );
166
167/**
168 * <DFN>vc_cec_send_message</DFN> allows a host application to
169 * send a CEC message to another device. There are several
170 * built-in functions for sending command messages. The host
171 * application MUST have a valid logical address (between 1 and
172 * 14 inclusive) before it can send a message.
173 * (For poll message set payload to NULL and length to zero).
174 *
175 * @param Follower's logical address
176 *
177 * @param Message payload WITHOUT the header byte (can be NULL)
178 *
179 * @param Payload length WITHOUT the header byte (can be zero)
180 *
181 * @param VC_TRUE if the message is a reply to an incoming message
182 *
183 * @return zero if the command is successful, non-zero otherwise
184 * If the command is successful, there will be a Tx callback
185 * in due course to indicate whether the message has been
186 * acknowledged by the recipient or not
187 ***********************************************************/
188VCHPRE_ int VCHPOST_ vc_cec_send_message(const uint32_t follower,
189 const uint8_t *payload,
190 uint32_t length,
191 vcos_bool_t is_reply);
192/**
193 * <DFN>vc_cec_get_logical_address</DFN> gets the logical address,
194 * If one is being allocated 0xF (unregistered) will be set.
195 * A address value of 0xF also means CEC system is not yet ready
196 * to send or receive any messages.
197 *
198 * @param pointer to logical address (set to allocated address)
199 *
200 * @return zero if the command is successful, non-zero otherwise
201 * logical_address is not modified if command failed
202 ***********************************************************/
203VCHPRE_ int VCHPOST_ vc_cec_get_logical_address(CEC_AllDevices_T *logical_address);
204
205/**
206 * <DFN>vc_cec_alloc_logical_address</DFN> starts the allocation
207 * of a logical address. Logical address is automatically allocated
208 * after HDMI power on is complete and AV mute is deassert.
209 * The host only needs to call this if the
210 * initial allocation failed (logical address being 0xF and
211 * physical address is NOT 0xFFFF from <DFN>VC_CEC_LOGICAL_ADDR</DFN>
212 * notification), or if the host explicitly released its logical
213 * address.
214 *
215 * @param none
216 *
217 * @return zero if the command is successful, non-zero otherwise
218 * If successful, there will be a callback notification
219 * <DFN>VC_CEC_LOGICAL_ADDR</DFN>.
220 * The host should wait for this before calling this
221 * function again.
222 ***********************************************************/
223VCHPRE_ int VCHPOST_ vc_cec_alloc_logical_address( void );
224
225/**
226 * Normally <DFN>vc_cec_release_logical_address</DFN> will not
227 * be called by the host application. It is used to release
228 * our logical address. This effectively disables CEC.
229 * The host will need to allocate a new logical address before
230 * doing any CEC calls (send/receive message, get topology, etc.).
231 *
232 * @param none
233 *
234 * @return zero if the command is successful, non-zero otherwise
235 * The host should get a callback <DFN>VC_CEC_LOGICAL_ADDR</DFN>
236 * with 0xF being the logical address and 0xFFFF
237 * being the physical address.
238 ***********************************************************/
239VCHPRE_ int VCHPOST_ vc_cec_release_logical_address( void );
240
241/**
242 * Use <DFN>vc_cec_get_topology</DFN> to get the topology.
243 *
244 * @param pointer to <DFN>VC_CEC_TOPOLOGY_T</DFN>
245 *
246 * @return zero if the command is successful, non-zero otherwise
247 * If successful, the topology will be set, otherwise it is unchanged
248 * A topology with only 1 device (us) means CEC is not supported.
249 * If there is no topology available, this also returns a failure.
250 ***********************************************************/
251VCHPRE_ int VCHPOST_ vc_cec_get_topology( VC_CEC_TOPOLOGY_T* topology);
252
253/**
254 * Use <DFN>vc_cec_set_vendor_id</DFN> to
255 * set the response to <Give Device Vendor ID>
256 *
257 * @param 24-bit IEEE vendor id
258 *
259 * @return zero if the command is successful, non-zero otherwise
260 ***********************************************************/
261VCHPRE_ int VCHPOST_ vc_cec_set_vendor_id( const uint32_t id );
262
263/**
264 * Use <DFN>vc_cec_set_osd_name</DFN> to
265 * set the response to <Give OSD Name>
266 *
267 * @param OSD name (14 byte char array)
268 *
269 * @return zero if the command is successful, non-zero otherwise
270 ***********************************************************/
271VCHPRE_ int VCHPOST_ vc_cec_set_osd_name( const char* name );
272
273/**
274 * <DFN>vc_cec_get_physical_address</DFN> gets our physical address
275 *
276 * @param pointer to physical address (returned as 16-bit packed value)
277 *
278 * @return zero if the command is successful, non-zero otherwise
279 * If failed, physical address argument will not be changed
280 * A physical address of 0xFFFF means CEC is not supported
281 ***********************************************************/
282VCHPRE_ int VCHPOST_ vc_cec_get_physical_address(uint16_t *physical_address);
283
284/**
285 * <DFN>vc_cec_get_vendor_id(</DFN> gets the vendor id of a particular logical address
286 *
287 * @param logical_address is the logical address of the device [in]
288 *
289 * @param vendorid is the pointer to vendor ID (24-bit IEEE OUI value) [out]
290 *
291 * @return zero if the command is successful, non-zero otherwise
292 * If failed, vendor id argument will not be changed
293 * A vendor ID of 0xFFFFFF means the device does not exist
294 * A vendor ID of 0x0 means vendor ID is not known and
295 * the application can send <Give Device Vendor ID> to that device
296 ***********************************************************/
297VCHPRE_ int VCHPOST_ vc_cec_get_vendor_id(const CEC_AllDevices_T logical_address, uint32_t *vendor_id);
298
299/**
300 * <DFN>vc_cec_device_type(</DFN> returns the default device type of a particular
301 * logical address, which can be used as the argument to vc_cec_send_ReportPhysicalAddress.
302 *
303 * @param logical address
304 *
305 * @return the default device type, if there is any error, the return device
306 * type will be CEC_DeviceType_Invalid
307 *
308 ************************************************************/
309VCHPRE_ CEC_DEVICE_TYPE_T VCHPOST_ vc_cec_device_type(const CEC_AllDevices_T logical_address);
310
311/**
312 * These couple of functions are provided for host application's convenience:
313 * If the xmit message is encapsulate in a VC_CEC_MESSAGE_T
314 * then it can be sent as a normal message (not as a reply)
315 * and the initiator field is ignored with vc_cec_send_message2
316 * and return zero for success
317 *
318 * Applications can call vc_cec_param2message to turn the callback parameters
319 * into a VC_CEC_MESSAGE_T (not for LOGICAL_ADDR and TOPOLOGY callbacks).
320 * It also returns zero for success.
321 */
322VCHPRE_ int VCHPOST_ vc_cec_send_message2(const VC_CEC_MESSAGE_T *message);
323
324VCHPRE_ int VCHPOST_ vc_cec_param2message( const uint32_t reason, const uint32_t param1,
325 const uint32_t param2, const uint32_t param3,
326 const uint32_t param4, VC_CEC_MESSAGE_T *message);
327
328//Extra API if CEC is running in passive mode
329//If CEC is not in passive mode the following 3 functions always
330//return failure
331/**
332 * <DFN> vc_cec_poll_address </DFN> sets and polls a particular address to find out
333 * its availability in the CEC network. Only available when CEC is running in passive
334 * mode. The host can only call this function during logical address allocation stage.
335 *
336 * @param logical address to try
337 *
338 * @return 0 if poll is successful (address is occupied)
339 * >0 if poll is unsuccessful (Error code is in VC_CEC_ERROR_T in vc_cec.h)
340 * <0 VCHI errors
341 */
342VCHPRE_ int VCHPOST_ vc_cec_poll_address(const CEC_AllDevices_T logical_address);
343
344/**
345 * <DFN> vc_cec_set_logical_address </DFN> sets the logical address, device type
346 * and vendor ID to be in use. Only available when CEC is running in passive
347 * mode. It is the responsibility of the host to make sure the logical address
348 * is actually free to be used. Physical address will be what is read from EDID.
349 *
350 * @param logical address
351 *
352 * @param device type
353 *
354 * @param vendor ID
355 *
356 * @return 0 if successful, non-zero otherwise
357 */
358VCHPRE_ int VCHPOST_ vc_cec_set_logical_address(const CEC_AllDevices_T logical_address,
359 const CEC_DEVICE_TYPE_T device_type,
360 const uint32_t vendor_id);
361
362/**
363 * <DFN> vc_cec_add_device </DFN> adds a new device to topology.
364 * Only available when CEC is running in passive mode. Device will be
365 * automatically removed from topology if a failed xmit is detected.
366 * If last_device is true, it will trigger a topology computation
367 * (and may trigger a topology callback).
368 *
369 * @param logical address
370 *
371 * @param physical address
372 *
373 * @param device type
374 *
375 * @param true if this is the last device, false otherwise
376 *
377 * @return 0 if successful, non-zero otherwise
378 */
379VCHPRE_ int VCHPOST_ vc_cec_add_device(const CEC_AllDevices_T logical_address,
380 const uint16_t physical_address,
381 const CEC_DEVICE_TYPE_T device_type,
382 vcos_bool_t last_device);
383
384/**
385 * <DFN> vc_cec_set_passive </DFN> enables and disables passive mode.
386 * Call this function first (with VC_TRUE as the argument) to enable
387 * passive mode before calling any of the above passive API functions
388 *
389 * @param TRUE to enable passive mode, FALSE to disable
390 *
391 * @return 0 if successful, non-zero otherwise
392 */
393VCHPRE_ int VCHPOST_ vc_cec_set_passive(vcos_bool_t enabled);
394
395
396//API for some common CEC messages
397/**
398 * Functions beginning with vc_cec_send_xxx make it easier for the
399 * host application to send CEC message xxx to other devices
400 */
401/**
402 * <DFN>vc_cec_send_FeatureAbort</DFN> sends <Feature Abort>
403 * for a received command.
404 *
405 * @param follower (cannot be 0xF)
406 *
407 * @param rejected opcode
408 *
409 * @param reject reason <DFN>CEC_ABORT_REASON_T</DFN>
410 *
411 * @return zero if the command is successful, non-zero otherwise
412 * Tx callback if successful
413 ***********************************************************/
414VCHPRE_ int VCHPOST_ vc_cec_send_FeatureAbort(uint32_t follower,
415 CEC_OPCODE_T opcode,
416 CEC_ABORT_REASON_T reason);
417
418/**
419 * <DFN>vc_cec_send_ActiveSource</DFN> broadcasts
420 * <Active Source> to all devices
421 *
422 * @param physical address (16-bit packed)
423 *
424 * @param reply or not (normally not)
425 *
426 * @return zero if the command is successful, non-zero otherwise
427 * Tx callback if successful
428 ***********************************************************/
429VCHPRE_ int VCHPOST_ vc_cec_send_ActiveSource(uint16_t physical_address, vcos_bool_t is_reply);
430
431/**
432 * <DFN>vc_cec_send_ImageViewOn</DFN> sends <Image View On>
433 *
434 * @param follower
435 *
436 * @param reply or not (normally not)
437 *
438 * @return zero if the command is successful, non-zero otherwise
439 * Tx callback if successful
440 ***********************************************************/
441VCHPRE_ int VCHPOST_ vc_cec_send_ImageViewOn(uint32_t follower, vcos_bool_t is_reply);
442
443/**
444 * <DFN>vc_cec_send_SetOSDString</DFN> sends <Set OSD String>
445 *
446 * @param follower
447 *
448 * @param string (char[13])
449 *
450 * @param display control <DFN>CEC_DISPLAY_CONTROL_T</DFN>
451 *
452 * @param reply or not (normally not)
453 *
454 * @return zero if the command is successful, non-zero otherwise
455 * Tx callback if successful
456 ***********************************************************/
457VCHPRE_ int VCHPOST_ vc_cec_send_SetOSDString(uint32_t follower,
458 CEC_DISPLAY_CONTROL_T disp_ctrl,
459 const char* string,
460 vcos_bool_t is_reply);
461
462/**
463 * <DFN>vc_cec_send_Standby</DFN> sends <Standby>.
464 * This will put any/all devices to standby if they support
465 * this CEC message.
466 *
467 * @param follower (can be 0xF)
468 *
469 * @param reply or not (normally not)
470 *
471 * @return zero if the command is successful, non-zero otherwise
472 * Tx callback if successful
473 ***********************************************************/
474VCHPRE_ int VCHPOST_ vc_cec_send_Standby(uint32_t follower, vcos_bool_t is_reply);
475
476/**
477 * <DFN>vc_cec_send_MenuStatus</DFN> sends <Menu Status>
478 * (response to <Menu Request>)
479 *
480 * @param follower
481 *
482 * @param menu state <DFN>CEC_MENU_STATE_T</DFN> but NOT CEC_MENU_STATE_QUERY
483 *
484 * @param reply or not (should always be yes)
485 *
486 * @return zero if the command is successful, non-zero otherwise
487 * Tx callback if successful
488 ***********************************************************/
489VCHPRE_ int VCHPOST_ vc_cec_send_MenuStatus(uint32_t follower,
490 CEC_MENU_STATE_T menu_state,
491 vcos_bool_t is_reply);
492
493/**
494 * <DFN>vc_cec_send_ReportPhysicalAddress</DFN> broadcasts
495 * <Report Physical Address> to all devices. Note although
496 * the passed in device type can be override the default one
497 * associated the allocated logical address, it is not
498 * recommended to do so. One can use <DFN>vc_cec_device_type</DFN>
499 * to get the default device type associated with the logical
500 * address returned via VC_CEC_LOGICAL_ADDR callback.
501 *
502 * @param physical address (16-bit packed)
503 *
504 * @param device type to be broadcasted
505 *
506 * @param reply or not (normally not)
507 *
508 * @return zero if the command is successful, non-zero otherwise
509 * Tx callback if successful
510 ***********************************************************/
511VCHPRE_ int VCHPOST_ vc_cec_send_ReportPhysicalAddress(uint16_t physical_address,
512 CEC_DEVICE_TYPE_T device_type,
513 vcos_bool_t is_reply);
514
515#endif //_VC_CECSERVICE_H_
516