1 /* 2 * Copyright (C) 2016 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 package android.hardware.tv.cec@1.0; 18 19 import IHdmiCecCallback; 20 21 /** 22 * HDMI-CEC HAL interface definition. 23 */ 24 interface IHdmiCec { 25 /** 26 * Passes the logical address that must be used in this system. 27 * 28 * HAL must use it to configure the hardware so that the CEC commands 29 * addressed the given logical address can be filtered in. This method must 30 * be able to be called as many times as necessary in order to support 31 * multiple logical devices. 32 * 33 * @param addr Logical address that must be used in this system. It must be 34 * in the range of valid logical addresses for the call to succeed. 35 * @return result Result status of the operation. SUCCESS if successful, 36 * FAILURE_INVALID_ARGS if the given logical address is invalid, 37 * FAILURE_BUSY if device or resource is busy 38 */ 39 @callflow(next={"*"}) 40 addLogicalAddress(CecLogicalAddress addr) generates (Result result); 41 42 /** 43 * Clears all the logical addresses. 44 * 45 * It is used when the system doesn't need to process CEC command any more, 46 * hence to tell HAL to stop receiving commands from the CEC bus, and change 47 * the state back to the beginning. 48 */ 49 @callflow(next="addLogicalAddress") 50 @exit 51 clearLogicalAddress(); 52 53 /** 54 * Gets the CEC physical address. 55 * 56 * The physical address depends on the topology of the network formed by 57 * connected HDMI devices. It is therefore likely to change if the cable is 58 * plugged off and on again. It is advised to call getPhysicalAddress to get 59 * the updated address when hot plug event takes place. 60 * 61 * @return result Result status of the operation. SUCCESS if successful, 62 * FAILURE_INVALID_STATE if HAL cannot retrieve the physical 63 * address. 64 * @return addr Physical address of this device. 65 */ 66 @callflow(next="*") 67 getPhysicalAddress() generates (Result result, uint16_t addr); 68 69 /** 70 * Transmits HDMI-CEC message to other HDMI device. 71 * 72 * The method must be designed to return in a certain amount of time and not 73 * hanging forever which may happen if CEC signal line is pulled low for 74 * some reason. 75 * 76 * It must try retransmission at least once as specified in the section '7.1 77 * Frame Re-transmissions' of the CEC Spec 1.4b. 78 * 79 * @param message CEC message to be sent to other HDMI device. 80 * @return result Result status of the operation. SUCCESS if successful, 81 * NACK if the sent message is not acknowledged, 82 * BUSY if the CEC bus is busy. 83 */ 84 @callflow(next="*") 85 sendMessage(CecMessage message) generates (SendMessageResult result); 86 87 /** 88 * Sets a callback that HDMI-CEC HAL must later use for incoming CEC 89 * messages or internal HDMI events. 90 * 91 * @param callback Callback object to pass hdmi events to the system. The 92 * previously registered callback must be replaced with this one. 93 */ 94 @callflow(next={"addLogicalAddress"}) 95 @entry 96 setCallback(IHdmiCecCallback callback); 97 98 /** 99 * Returns the CEC version supported by underlying hardware. 100 * 101 * @return version the CEC version supported by underlying hardware. 102 */ 103 @callflow(next={"*"}) 104 getCecVersion() generates (int32_t version); 105 106 /** 107 * Gets the identifier of the vendor. 108 * 109 * @return vendorId Identifier of the vendor that is the 24-bit unique 110 * company ID obtained from the IEEE Registration Authority 111 * Committee (RAC). The upper 8 bits must be 0. 112 */ 113 @callflow(next={"*"}) 114 getVendorId() generates (uint32_t vendorId); 115 116 /** 117 * Gets the hdmi port information of underlying hardware. 118 * 119 * @return infos The list of HDMI port information 120 */ 121 @callflow(next={"*"}) 122 getPortInfo() generates (vec<HdmiPortInfo> infos); 123 124 /** 125 * Sets flags controlling the way HDMI-CEC service works down to HAL 126 * implementation. Those flags must be used in case the feature needs update 127 * in HAL itself, firmware or microcontroller. 128 * 129 * @param key The key of the option to be updated with a new value. 130 * @param value Value to be set. 131 */ 132 @callflow(next="*") 133 setOption(OptionKey key, bool value); 134 135 /** 136 * Passes the updated language information of Android system. Contains 137 * three-letter code as defined in ISO/FDIS 639-2. Must be used for HAL to 138 * respond to <Get Menu Language> while in standby mode. 139 * 140 * @param language Three-letter code defined in ISO/FDIS 639-2. Must be 141 * lowercase letters. (e.g., eng for English) 142 */ 143 @callflow(next="*") 144 setLanguage(string language); 145 146 /** 147 * Configures ARC circuit in the hardware logic to start or stop the 148 * feature. 149 * 150 * @param portId Port id to be configured. 151 * @param enable Flag must be either true to start the feature or false to 152 * stop it. 153 */ 154 @callflow(next="*") 155 enableAudioReturnChannel(int32_t portId, bool enable); 156 157 /** 158 * Gets the connection status of the specified port. 159 * 160 * @param portId Port id to be inspected for the connection status. 161 * @return status True if a device is connected, otherwise false. The HAL 162 * must watch for +5V power signal to determine the status. 163 */ 164 @callflow(next="*") 165 isConnected(int32_t portId) generates (bool status); 166 }; 167
