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
17package android.hardware.tv.cec@1.0;
18
19import IHdmiCecCallback;
20
21/**
22 * HDMI-CEC HAL interface definition.
23 */
24interface 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