1/* 2 * Copyright (C) 2019 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 17package android.hardware.tv.cec@2.0; 18 19import IHdmiCecCallback; 20 21/** 22 * HDMI-CEC HAL interface definition. 23 */ 24interface IHdmiCec { 25 /** 26 * Passes Primary Device Type that must be used in this system. 27 * 28 * HAL must use it to allocate logical address as specified in CEC section 29 * 11.3.2 of the CEC spec 2.0b. Then CEC commands addressed the given 30 * logical address can be filtered in. 31 * This method shall be able to be called up to twice to support two Primary 32 * Device Type as specified in CEC Table 11-8 of the CEC spec 2.0b. 33 * 34 * @param deviceType that must be used in this system. It must be a valid 35 * value in CecDeviceType for the call to succeed. 36 * @return result Result status of the operation. SUCCESS if successful, 37 * FAILURE_INVALID_ARGS if the given device type is invalid, 38 * FAILURE_BUSY if device or resource is busy 39 */ 40 @callflow(next={"*"}) 41 addDeviceType(CecDeviceType deviceType) generates (Result result); 42 43 /** 44 * Clears all Primary Device Types. 45 * 46 * It is used when the system plan to reconfigure Primary Device Type, 47 * hence to tell HAL to release all logical address associated to them, 48 * and change the state back to the beginning. 49 */ 50 @callflow(next="addDeviceType") 51 @exit 52 clearDeviceTypes(); 53 54 /** 55 * Set All Device Types for a Primary Device Type. 56 * 57 * This value must be used in REPORT_FEATURES message to response 58 * GIVE_FEATURES message in HAL. 59 * 60 * @param allDeviceTypes device all device types for a Primary Device Type. 61 */ 62 @callflow(next="addDeviceType") 63 setAllDeviceTypes(CecAllDeviceTypes allDeviceTypes); 64 65 /** 66 * Set Device Features for a Primary Device Type. 67 * 68 * This value must be used in REPORT_FEATURES message to response 69 * GIVE_FEATURES message in HAL. 70 * 71 * @param deviceType The device Primary Device Type. 72 * @param deviceFeatures device features for a Primary Device Type. 73 */ 74 @callflow(next="addDeviceType") 75 setDeviceFeatures(CecDeviceType deviceType, 76 CecDeviceFeatures deviceFeatures); 77 78 /** 79 * Set Remote Control Profile for a Primary Device Type. 80 * 81 * This value must be used in REPORT_FEATURES message to response 82 * GIVE_FEATURES message in HAL. 83 * 84 * @param deviceType The device Primary Device Type. 85 * @param rcProliles remote control profiles for a Primary Device Type. 86 */ 87 @callflow(next="addDeviceType") 88 setRcProfile(CecDeviceType deviceType, CecRcProfile rcProfile); 89 90 /** 91 * Retrieve CEC device information. 92 * 93 * CEC section 11.3 of the CEC spec 2.0b specify that a device should not 94 * ask for static information that another device has already supplied. 95 * Therefore, CEC 2.0 software stack need a map to store all cec 96 * devices’ information of current CEC network. 97 * The device information is broadcasted by a device after it allocates a 98 * logical address. Messages used to send out these information are 99 * REPORT_FEATURES, REPORT_PHYSICAL_ADDRESS, DEVICE_VENDOR_ID. 100 * The spec also requires less than 1 second between REPORT_FEATURES and 101 * REPORT_PHYSICAL_ADDRESS message, and less than 2 second between 102 * REPORT_PHYSICAL_ADDRESS and DEVICE_VENDOR_ID. An Implementation of 103 * device information map in hal can help to meet the timing constraints. 104 * Logical addressing is part of the process to build this map, so the 105 * implementation shall include allocating logical address too. 106 * Whenever a device plug/unplug, the topology of CEC network changes. 107 * The hal implementation shall update devices’ information map, and 108 * send out onTopologyEvent to Android system. Then Android system 109 * will use readDeviceInfo to retreive latest devices’ information of CEC 110 * network. 111 * If SYSTEM_CEC_CONTROL is false, the hal implementation need continue to 112 * maintain and update device information map, and send out pending 113 * onTopologyEvent to Android system when SYSTEM_CEC_CONTROL is 114 * changed to true. 115 * 116 * @param logicalAddress logical address of CEC device. 117 * @param physicalAddress physical address of CEC device. 118 * @return CecDeviceInfo from device information map. 119 * @return result Result status of the operation. SUCCESS if successful, 120 * FAILURE_INVALID_ARGS if logical or physical address is invalid. 121 * FAILURE_INVALID_STATE if device information isn't available yet. 122 */ 123 @callflow(next="onTopologyChangeEvent") 124 readDeviceInfo(CecLogicalAddress logicalAddress, 125 CecPhysicalAddress physicalAddress) 126 generates (Result result, CecDeviceInfo deviceInfo); 127 128 /** 129 * Transmits HDMI-CEC message to other HDMI device. 130 * 131 * The method must be designed to return in a certain amount of time and not 132 * hanging forever. This method MUST complete with in 1 second. 133 * 134 * It must try retransmission at least once as specified in the section '7.1 135 * Frame Re-transmissions' of the CEC Spec 1.4b. 136 * 137 * @param message CEC message to be sent to other HDMI device. 138 * @return result Result status of the operation. SUCCESS if successful, 139 * NACK if the sent message is not acknowledged, 140 * BUSY if the CEC bus is busy. 141 */ 142 @callflow(next="*") 143 sendMessage(CecMessage message) generates (SendMessageResult result); 144 145 /** 146 * Set the callback 147 * 148 * It is used by the framework to receive CecMessages, HDMI hotplug event 149 * and topology update event. Only one callback client is supported. 150 * 151 * @param callback Callback object to pass hdmi events to the system. The 152 * previously registered callback must be replaced with this one. 153 */ 154 @callflow(next={"*"}) 155 @entry 156 setCallback(IHdmiCecCallback callback); 157 158 /** 159 * Gets the hdmi port information of underlying hardware. 160 * 161 * @return infos The list of HDMI port information 162 */ 163 @callflow(next={"*"}) 164 getPortInfo() generates (vec<HdmiPortInfo> infos); 165 166 /** 167 * Sets flags controlling the way HDMI-CEC service works down to HAL 168 * implementation. Those flags must be used in case the feature needs update 169 * in HAL itself, firmware or microcontroller. 170 * 171 * @param key The key of the option to be updated with a new value. 172 * @param value Value to be set. 173 */ 174 @callflow(next="*") 175 setOption(OptionKey key, bool value); 176 177 /** 178 * Passes the updated language information of Android system. Contains 179 * three-letter code as defined in ISO/FDIS 639-2. Must be used for HAL to 180 * respond to <Get Menu Language> while in standby mode. 181 * 182 * @param language Three-letter code defined in ISO/FDIS 639-2. Must be 183 * lowercase letters. (e.g., eng for English) 184 */ 185 @callflow(next="*") 186 setLanguage(string language); 187 188 /** 189 * Configures ARC circuit in the hardware logic to start or stop the 190 * feature. 191 * 192 * @param portId Port id to be configured. 193 * @param enable Flag must be either true to start the feature or false to 194 * stop it. 195 */ 196 @callflow(next="*") 197 enableAudioReturnChannel(HdmiPortId portId, bool enable); 198 199 /** 200 * Gets the connection status of the specified port. 201 * 202 * It's specified in CEC section 10.8 of the CEC spec 2.0b 203 * 204 * @param portId Port id to be inspected for the connection status. 205 * @return status True if a device is connected, otherwise false. 206 */ 207 @callflow(next="*") 208 isConnected(HdmiPortId portId) generates (bool connected); 209}; 210