include/hardware/hdmi_cec.h

   1 /*
   2  * Copyright (C) 2014 The Android Open Source Project
   3  *
   4  * Licensed under the Apache License, Version 2.0 (the "License");
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at
   7  *
   8  *      http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an "AS IS" BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16
  17 #ifndef ANDROID_INCLUDE_HARDWARE_HDMI_CEC_H
  18 #define ANDROID_INCLUDE_HARDWARE_HDMI_CEC_H
  19
  20 #include <stdint.h>
  21 #include <sys/cdefs.h>
  22
  23 #include <hardware/hardware.h>
  24
  25 __BEGIN_DECLS
  26
  27 #define HDMI_CEC_MODULE_API_VERSION_1_0 HARDWARE_MODULE_API_VERSION(1, 0)
  28 #define HDMI_CEC_MODULE_API_VERSION_CURRENT HDMI_MODULE_API_VERSION_1_0
  29
  30 #define HDMI_CEC_DEVICE_API_VERSION_1_0 HARDWARE_DEVICE_API_VERSION(1, 0)
  31 #define HDMI_CEC_DEVICE_API_VERSION_CURRENT HDMI_DEVICE_API_VERSION_1_0
  32
  33 #define HDMI_CEC_HARDWARE_MODULE_ID "hdmi_cec"
  34 #define HDMI_CEC_HARDWARE_INTERFACE "hdmi_cec_hw_if"
  35
  36 typedef enum cec_device_type {
  37     CEC_DEVICE_INACTIVE = -1,
  38     CEC_DEVICE_TV = 0,
  39     CEC_DEVICE_RECORDER = 1,
  40     CEC_DEVICE_RESERVED = 2,
  41     CEC_DEVICE_TUNER = 3,
  42     CEC_DEVICE_PLAYBACK = 4,
  43     CEC_DEVICE_AUDIO_SYSTEM = 5,
  44     CEC_DEVICE_MAX = CEC_DEVICE_AUDIO_SYSTEM
  45 } cec_device_type_t;
  46
  47 typedef enum cec_logical_address {
  48     CEC_ADDR_TV = 0,
  49     CEC_ADDR_RECORDER_1 = 1,
  50     CEC_ADDR_RECORDER_2 = 2,
  51     CEC_ADDR_TUNER_1 = 3,
  52     CEC_ADDR_PLAYBACK_1 = 4,
  53     CEC_ADDR_AUDIO_SYSTEM = 5,
  54     CEC_ADDR_TUNER_2 = 6,
  55     CEC_ADDR_TUNER_3 = 7,
  56     CEC_ADDR_PLAYBACK_2 = 8,
  57     CEC_ADDR_RECORDER_3 = 9,
  58     CEC_ADDR_TUNER_4 = 10,
  59     CEC_ADDR_PLAYBACK_3 = 11,
  60     CEC_ADDR_RESERVED_1 = 12,
  61     CEC_ADDR_RESERVED_2 = 13,
  62     CEC_ADDR_FREE_USE = 14,
  63     CEC_ADDR_UNREGISTERED = 15,
  64     CEC_ADDR_BROADCAST = 15
  65 } cec_logical_address_t;
  66
  67 /*
  68  * HDMI CEC messages
  69  */
  70 enum cec_message_type {
  71     CEC_MESSAGE_FEATURE_ABORT = 0x00,
  72     CEC_MESSAGE_IMAGE_VIEW_ON = 0x04,
  73     CEC_MESSAGE_TUNER_STEP_INCREMENT = 0x05,
  74     CEC_MESSAGE_TUNER_STEP_DECREMENT = 0x06,
  75     CEC_MESSAGE_TUNER_DEVICE_STATUS = 0x07,
  76     CEC_MESSAGE_GIVE_TUNER_DEVICE_STATUS = 0x08,
  77     CEC_MESSAGE_RECORD_ON = 0x09,
  78     CEC_MESSAGE_RECORD_STATUS = 0x0A,
  79     CEC_MESSAGE_RECORD_OFF = 0x0B,
  80     CEC_MESSAGE_TEXT_VIEW_ON = 0x0D,
  81     CEC_MESSAGE_RECORD_TV_SCREEN = 0x0F,
  82     CEC_MESSAGE_GIVE_DECK_STATUS = 0x1A,
  83     CEC_MESSAGE_DECK_STATUS = 0x1B,
  84     CEC_MESSAGE_SET_MENU_LANGUAGE = 0x32,
  85     CEC_MESSAGE_CLEAR_ANALOG_TIMER = 0x33,
  86     CEC_MESSAGE_SET_ANALOG_TIMER = 0x34,
  87     CEC_MESSAGE_TIMER_STATUS = 0x35,
  88     CEC_MESSAGE_STANDBY = 0x36,
  89     CEC_MESSAGE_PLAY = 0x41,
  90     CEC_MESSAGE_DECK_CONTROL = 0x42,
  91     CEC_MESSAGE_TIMER_CLEARED_STATUS = 0x043,
  92     CEC_MESSAGE_USER_CONTROL_PRESSED = 0x44,
  93     CEC_MESSAGE_USER_CONTROL_RELEASED = 0x45,
  94     CEC_MESSAGE_GIVE_OSD_NAME = 0x46,
  95     CEC_MESSAGE_SET_OSD_NAME = 0x47,
  96     CEC_MESSAGE_SET_OSD_STRING = 0x64,
  97     CEC_MESSAGE_SET_TIMER_PROGRAM_TITLE = 0x67,
  98     CEC_MESSAGE_SYSTEM_AUDIO_MODE_REQUEST = 0x70,
  99     CEC_MESSAGE_GIVE_AUDIO_STATUS = 0x71,
 100     CEC_MESSAGE_SET_SYSTEM_AUDIO_MODE = 0x72,
 101     CEC_MESSAGE_REPORT_AUDIO_STATUS = 0x7A,
 102     CEC_MESSAGE_GIVE_SYSTEM_AUDIO_MODE_STATUS = 0x7D,
 103     CEC_MESSAGE_SYSTEM_AUDIO_MODE_STATUS = 0x7E,
 104     CEC_MESSAGE_ROUTING_CHANGE = 0x80,
 105     CEC_MESSAGE_ROUTING_INFORMATION = 0x81,
 106     CEC_MESSAGE_ACTIVE_SOURCE = 0x82,
 107     CEC_MESSAGE_GIVE_PHYSICAL_ADDRESS = 0x83,
 108     CEC_MESSAGE_REPORT_PHYSICAL_ADDRESS = 0x84,
 109     CEC_MESSAGE_REQUEST_ACTIVE_SOURCE = 0x85,
 110     CEC_MESSAGE_SET_STREAM_PATH = 0x86,
 111     CEC_MESSAGE_DEVICE_VENDOR_ID = 0x87,
 112     CEC_MESSAGE_VENDOR_COMMAND = 0x89,
 113     CEC_MESSAGE_VENDOR_REMOTE_BUTTON_DOWN = 0x8A,
 114     CEC_MESSAGE_VENDOR_REMOTE_BUTTON_UP = 0x8B,
 115     CEC_MESSAGE_GIVE_DEVICE_VENDOR_ID = 0x8C,
 116     CEC_MESSAGE_MENU_REQUEST = 0x8D,
 117     CEC_MESSAGE_MENU_STATUS = 0x8E,
 118     CEC_MESSAGE_GIVE_DEVICE_POWER_STATUS = 0x8F,
 119     CEC_MESSAGE_REPORT_POWER_STATUS = 0x90,
 120     CEC_MESSAGE_GET_MENU_LANGUAGE = 0x91,
 121     CEC_MESSAGE_SELECT_ANALOG_SERVICE = 0x92,
 122     CEC_MESSAGE_SELECT_DIGITAL_SERVICE = 0x93,
 123     CEC_MESSAGE_SET_DIGITAL_TIMER = 0x97,
 124     CEC_MESSAGE_CLEAR_DIGITAL_TIMER = 0x99,
 125     CEC_MESSAGE_SET_AUDIO_RATE = 0x9A,
 126     CEC_MESSAGE_INACTIVE_SOURCE = 0x9D,
 127     CEC_MESSAGE_CEC_VERSION = 0x9E,
 128     CEC_MESSAGE_GET_CEC_VERSION = 0x9F,
 129     CEC_MESSAGE_VENDOR_COMMAND_WITH_ID = 0xA0,
 130     CEC_MESSAGE_CLEAR_EXTERNAL_TIMER = 0xA1,
 131     CEC_MESSAGE_SET_EXTERNAL_TIMER = 0xA2,
 132     CEC_MESSAGE_INITIATE_ARC = 0xC0,
 133     CEC_MESSAGE_REPORT_ARC_INITIATED = 0xC1,
 134     CEC_MESSAGE_REPORT_ARC_TERMINATED = 0xC2,
 135     CEC_MESSAGE_REQUEST_ARC_INITIATION = 0xC3,
 136     CEC_MESSAGE_REQUEST_ARC_TERMINATION = 0xC4,
 137     CEC_MESSAGE_TERMINATE_ARC = 0xC5,
 138     CEC_MESSAGE_ABORT = 0xFF
 139 };
 140
 141 /*
 142  * Operand description [Abort Reason]
 143  */
 144 enum abort_reason {
 145     ABORT_UNRECOGNIZED_MODE = 0,
 146     ABORT_NOT_IN_CORRECT_MODE = 1,
 147     ABORT_CANNOT_PROVIDE_SOURCE = 2,
 148     ABORT_INVALID_OPERAND = 3,
 149     ABORT_REFUSED = 4,
 150     ABORT_UNABLE_TO_DETERMINE = 5
 151 };
 152
 153 /*
 154  * HDMI event type. used for hdmi_event_t.
 155  */
 156 enum {
 157     HDMI_EVENT_CEC_MESSAGE = 1,
 158     HDMI_EVENT_HOT_PLUG = 2,
 159 };
 160
 161 /*
 162  * HDMI hotplug event type. Used when the event
 163  * type is HDMI_EVENT_HOT_PLUG.
 164  */
 165 enum {
 166     HDMI_NOT_CONNECTED = 0,
 167     HDMI_CONNECTED = 1
 168 };
 169
 170 /*
 171  * error code used for send_message.
 172  */
 173 enum {
 174     HDMI_RESULT_SUCCESS = 0,
 175     HDMI_RESULT_NACK = 1,        /* not acknowledged */
 176     HDMI_RESULT_BUSY = 2,        /* bus is busy */
 177     HDMI_RESULT_FAIL = 3,
 178 };
 179
 180 /*
 181  * HDMI port type.
 182  */
 183 typedef enum hdmi_port_type {
 184     HDMI_INPUT = 0,
 185     HDMI_OUTPUT = 1
 186 } hdmi_port_type_t;
 187
 188 /*
 189  * Flags used for set_option()
 190  */
 191 enum {
 192     /* When set to false, HAL does not wake up the system upon receiving
 193      * <Image View On> or <Text View On>. Used when user changes the TV
 194      * settings to disable the auto TV on functionality.
 195      * True by default.
 196      */
 197     HDMI_OPTION_WAKEUP = 1,
 198
 199     /* When set to false, all the CEC commands are discarded. Used when
 200      * user changes the TV settings to disable CEC functionality.
 201      * True by default.
 202      */
 203     HDMI_OPTION_ENABLE_CEC = 2,
 204
 205     /* Setting this flag to false means Android system will stop handling
 206      * CEC service and yield the control over to the microprocessor that is
 207      * powered on through the standby mode. When set to true, the system
 208      * will gain the control over, hence telling the microprocessor to stop
 209      * handling the cec commands. This is called when system goes
 210      * in and out of standby mode to notify the microprocessor that it should
 211      * start/stop handling CEC commands on behalf of the system.
 212      * False by default.
 213      */
 214     HDMI_OPTION_SYSTEM_CEC_CONTROL = 3,
 215 };
 216
 217 /*
 218  * Maximum length in bytes of cec message body (exclude header block),
 219  * should not exceed 16 (spec CEC 6 Frame Description)
 220  */
 221 #define CEC_MESSAGE_BODY_MAX_LENGTH 16
 222
 223 typedef struct cec_message {
 224     /* logical address of sender */
 225     cec_logical_address_t initiator;
 226
 227     /* logical address of receiver */
 228     cec_logical_address_t destination;
 229
 230     /* Length in bytes of body, range [0, CEC_MESSAGE_BODY_MAX_LENGTH] */
 231     size_t length;
 232     unsigned char body[CEC_MESSAGE_BODY_MAX_LENGTH];
 233 } cec_message_t;
 234
 235 typedef struct hotplug_event {
 236     /*
 237      * true if the cable is connected; otherwise false.
 238      */
 239     int connected;
 240     int port_id;
 241 } hotplug_event_t;
 242
 243 typedef struct tx_status_event {
 244     int status;
 245     int opcode;  /* CEC opcode */
 246 } tx_status_event_t;
 247
 248 /*
 249  * HDMI event generated from HAL.
 250  */
 251 typedef struct hdmi_event {
 252     int type;
 253     struct hdmi_cec_device* dev;
 254     union {
 255         cec_message_t cec;
 256         hotplug_event_t hotplug;
 257     };
 258 } hdmi_event_t;
 259
 260 /*
 261  * HDMI port descriptor
 262  */
 263 typedef struct hdmi_port_info {
 264     hdmi_port_type_t type;
 265     // Port ID should start from 1 which corresponds to HDMI "port 1".
 266     int port_id;
 267     int cec_supported;
 268     int arc_supported;
 269     uint16_t physical_address;
 270 } hdmi_port_info_t;
 271
 272 /*
 273  * Callback function type that will be called by HAL implementation.
 274  * Services can not close/open the device in the callback.
 275  */
 276 typedef void (*event_callback_t)(const hdmi_event_t* event, void* arg);
 277
 278 typedef struct hdmi_cec_module {
 279     /**
 280      * Common methods of the HDMI CEC module.  This *must* be the first member of
 281      * hdmi_cec_module as users of this structure will cast a hw_module_t to hdmi_cec_module
 282      * pointer in contexts where it's known the hw_module_t references a hdmi_cec_module.
 283      */
 284     struct hw_module_t common;
 285 } hdmi_module_t;
 286
 287 /*
 288  * HDMI-CEC HAL interface definition.
 289  */
 290 typedef struct hdmi_cec_device {
 291     /**
 292      * Common methods of the HDMI CEC device.  This *must* be the first member of
 293      * hdmi_cec_device as users of this structure will cast a hw_device_t to hdmi_cec_device
 294      * pointer in contexts where it's known the hw_device_t references a hdmi_cec_device.
 295      */
 296     struct hw_device_t common;
 297
 298     /*
 299      * (*add_logical_address)() passes the logical address that will be used
 300      * in this system.
 301      *
 302      * HAL may use it to configure the hardware so that the CEC commands addressed
 303      * the given logical address can be filtered in. This method can be called
 304      * as many times as necessary in order to support multiple logical devices.
 305      * addr should be in the range of valid logical addresses for the call
 306      * to succeed.
 307      *
 308      * Returns 0 on success or -errno on error.
 309      */
 310     int (*add_logical_address)(const struct hdmi_cec_device* dev, cec_logical_address_t addr);
 311
 312     /*
 313      * (*clear_logical_address)() tells HAL to reset all the logical addresses.
 314      *
 315      * It is used when the system doesn't need to process CEC command any more,
 316      * hence to tell HAL to stop receiving commands from the CEC bus, and change
 317      * the state back to the beginning.
 318      */
 319     void (*clear_logical_address)(const struct hdmi_cec_device* dev);
 320
 321     /*
 322      * (*get_physical_address)() returns the CEC physical address. The
 323      * address is written to addr.
 324      *
 325      * The physical address depends on the topology of the network formed
 326      * by connected HDMI devices. It is therefore likely to change if the cable
 327      * is plugged off and on again. It is advised to call get_physical_address
 328      * to get the updated address when hot plug event takes place.
 329      *
 330      * Returns 0 on success or -errno on error.
 331      */
 332     int (*get_physical_address)(const struct hdmi_cec_device* dev, uint16_t* addr);
 333
 334     /*
 335      * (*send_message)() transmits HDMI-CEC message to other HDMI device.
 336      *
 337      * The method should be designed to return in a certain amount of time not
 338      * hanging forever, which can happen if CEC signal line is pulled low for
 339      * some reason. HAL implementation should take the situation into account
 340      * so as not to wait forever for the message to get sent out.
 341      *
 342      * It should try retransmission at least once as specified in the standard.
 343      *
 344      * Returns error code. See HDMI_RESULT_SUCCESS, HDMI_RESULT_NACK, and
 345      * HDMI_RESULT_BUSY.
 346      */
 347     int (*send_message)(const struct hdmi_cec_device* dev, const cec_message_t*);
 348
 349     /*
 350      * (*register_event_callback)() registers a callback that HDMI-CEC HAL
 351      * can later use for incoming CEC messages or internal HDMI events.
 352      * When calling from C++, use the argument arg to pass the calling object.
 353      * It will be passed back when the callback is invoked so that the context
 354      * can be retrieved.
 355      */
 356     void (*register_event_callback)(const struct hdmi_cec_device* dev,
 357             event_callback_t callback, void* arg);
 358
 359     /*
 360      * (*get_version)() returns the CEC version supported by underlying hardware.
 361      */
 362     void (*get_version)(const struct hdmi_cec_device* dev, int* version);
 363
 364     /*
 365      * (*get_vendor_id)() returns the identifier of the vendor. It is
 366      * the 24-bit unique company ID obtained from the IEEE Registration
 367      * Authority Committee (RAC).
 368      */
 369     void (*get_vendor_id)(const struct hdmi_cec_device* dev, uint32_t* vendor_id);
 370
 371     /*
 372      * (*get_port_info)() returns the hdmi port information of underlying hardware.
 373      * info is the list of HDMI port information, and 'total' is the number of
 374      * HDMI ports in the system.
 375      */
 376     void (*get_port_info)(const struct hdmi_cec_device* dev,
 377             struct hdmi_port_info* list[], int* total);
 378
 379     /*
 380      * (*set_option)() passes flags controlling the way HDMI-CEC service works down
 381      * to HAL implementation. Those flags will be used in case the feature needs
 382      * update in HAL itself, firmware or microcontroller.
 383      */
 384     void (*set_option)(const struct hdmi_cec_device* dev, int flag, int value);
 385
 386     /*
 387      * (*set_audio_return_channel)() configures ARC circuit in the hardware logic
 388      * to start or stop the feature. Flag can be either 1 to start the feature
 389      * or 0 to stop it.
 390      *
 391      * Returns 0 on success or -errno on error.
 392      */
 393     void (*set_audio_return_channel)(const struct hdmi_cec_device* dev, int port_id, int flag);
 394
 395     /*
 396      * (*is_connected)() returns the connection status of the specified port.
 397      * Returns HDMI_CONNECTED if a device is connected, otherwise HDMI_NOT_CONNECTED.
 398      * The HAL should watch for +5V power signal to determine the status.
 399      */
 400     int (*is_connected)(const struct hdmi_cec_device* dev, int port_id);
 401
 402     /* Reserved for future use to maximum 16 functions. Must be NULL. */
 403     void* reserved[16 - 11];
 404 } hdmi_cec_device_t;
 405
 406 /** convenience API for opening and closing a device */
 407
 408 static inline int hdmi_cec_open(const struct hw_module_t* module,
 409         struct hdmi_cec_device** device) {
 410     return module->methods->open(module,
 411             HDMI_CEC_HARDWARE_INTERFACE, (struct hw_device_t**)device);
 412 }
 413
 414 static inline int hdmi_cec_close(struct hdmi_cec_device* device) {
 415     return device->common.close(&device->common);
 416 }
 417
 418 __END_DECLS
 419
 420 #endif /* ANDROID_INCLUDE_HARDWARE_HDMI_CEC_H */