/*
 * Copyright (C) 2016 The Android Open Source Project
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package android.hardware.tv.cec@1.0;

import IHdmiCecCallback;

/**
 * HDMI-CEC HAL interface definition.
 */
interface IHdmiCec {
    /**
     * Passes the logical address that must be used in this system.
     *
     * HAL must use it to configure the hardware so that the CEC commands
     * addressed the given logical address can be filtered in. This method must
     * be able to be called as many times as necessary in order to support
     * multiple logical devices.
     *
     * @param addr Logical address that must be used in this system. It must be
     *        in the range of valid logical addresses for the call to succeed.
     * @return result Result status of the operation. SUCCESS if successful,
     *         FAILURE_INVALID_ARGS if the given logical address is invalid,
     *         FAILURE_BUSY if device or resource is busy
     */
    @callflow(next={"*"})
    addLogicalAddress(CecLogicalAddress addr) generates (Result result);

    /**
     * Clears all the logical addresses.
     *
     * It is used when the system doesn't need to process CEC command any more,
     * hence to tell HAL to stop receiving commands from the CEC bus, and change
     * the state back to the beginning.
     */
    @callflow(next="addLogicalAddress")
    @exit
    clearLogicalAddress();

    /**
     * Gets the CEC physical address.
     *
     * The physical address depends on the topology of the network formed by
     * connected HDMI devices. It is therefore likely to change if the cable is
     * plugged off and on again. It is advised to call getPhysicalAddress to get
     * the updated address when hot plug event takes place.
     *
     * @return result Result status of the operation. SUCCESS if successful,
     *         FAILURE_INVALID_STATE if HAL cannot retrieve the physical
     *         address.
     * @return addr Physical address of this device.
     */
    @callflow(next="*")
    getPhysicalAddress() generates (Result result, uint16_t addr);

    /**
     * Transmits HDMI-CEC message to other HDMI device.
     *
     * The method must be designed to return in a certain amount of time and not
     * hanging forever which may happen if CEC signal line is pulled low for
     * some reason.
     *
     * It must try retransmission at least once as specified in the section '7.1
     * Frame Re-transmissions' of the CEC Spec 1.4b.
     *
     * @param message CEC message to be sent to other HDMI device.
     * @return result Result status of the operation. SUCCESS if successful,
     *         NACK if the sent message is not acknowledged,
     *         BUSY if the CEC bus is busy.
     */
    @callflow(next="*")
    sendMessage(CecMessage message) generates (SendMessageResult result);

    /**
     * Sets a callback that HDMI-CEC HAL must later use for incoming CEC
     * messages or internal HDMI events.
     *
     * @param callback Callback object to pass hdmi events to the system. The
     *        previously registered callback must be replaced with this one.
     */
    @callflow(next={"addLogicalAddress"})
    @entry
    setCallback(IHdmiCecCallback callback);

    /**
     * Returns the CEC version supported by underlying hardware.
     *
     * @return version the CEC version supported by underlying hardware.
     */
    @callflow(next={"*"})
    getCecVersion() generates (int32_t version);

    /**
     * Gets the identifier of the vendor.
     *
     * @return vendorId Identifier of the vendor that is the 24-bit unique
     *         company ID obtained from the IEEE Registration Authority
     *         Committee (RAC). The upper 8 bits must be 0.
     */
    @callflow(next={"*"})
    getVendorId() generates (uint32_t vendorId);

    /**
     * Gets the hdmi port information of underlying hardware.
     *
     * @return infos The list of HDMI port information
     */
    @callflow(next={"*"})
    getPortInfo() generates (vec<HdmiPortInfo> infos);

    /**
     * Sets flags controlling the way HDMI-CEC service works down to HAL
     * implementation. Those flags must be used in case the feature needs update
     * in HAL itself, firmware or microcontroller.
     *
     * @param key The key of the option to be updated with a new value.
     * @param value Value to be set.
     */
    @callflow(next="*")
    setOption(OptionKey key, bool value);

    /**
     * Passes the updated language information of Android system. Contains
     * three-letter code as defined in ISO/FDIS 639-2. Must be used for HAL to
     * respond to <Get Menu Language> while in standby mode.
     *
     * @param language Three-letter code defined in ISO/FDIS 639-2. Must be
     *        lowercase letters. (e.g., eng for English)
     */
    @callflow(next="*")
    setLanguage(string language);

    /**
     * Configures ARC circuit in the hardware logic to start or stop the
     * feature.
     *
     * @param portId Port id to be configured.
     * @param enable Flag must be either true to start the feature or false to
     *        stop it.
     */
    @callflow(next="*")
    enableAudioReturnChannel(int32_t portId, bool enable);

    /**
     * Gets the connection status of the specified port.
     *
     * @param portId Port id to be inspected for the connection status.
     * @return status True if a device is connected, otherwise false. The HAL
     *         must watch for +5V power signal to determine the status.
     */
    @callflow(next="*")
    isConnected(int32_t portId) generates (bool status);
};