/*
 * 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.nfc@1.0;

import INfcClientCallback;

interface INfc {
    /**
     * Opens the NFC controller device and performs initialization.
     * This may include patch download and other vendor-specific initialization.
     *
     * If open completes successfully, the controller should be ready to perform
     * NCI initialization - ie accept CORE_RESET and subsequent commands through
     * the write() call.
     *
     * If open() returns NfcStatus::OK, the NCI stack will wait for a
     * NfcEvent.OPEN_CPLT before continuing.
     *
     * If open() returns NfcStatus::FAILED, the NCI stack will stop.
     *
     */
    @entry
    @callflow(next={"write", "coreInitialized", "prediscover", "powerCycle", "controlGranted"})
    open(INfcClientCallback clientCallback) generates (NfcStatus status);

    /**
     * Performs an NCI write.
     *
     * This method may queue writes and return immediately. The only
     * requirement is that the writes are executed in order.
     *
     * @return number of bytes written to the NFCC
     */
    @callflow(next={"write", "prediscover", "coreInitialized", "close", "powerCycle",
                    "controlGranted"})
    write(NfcData data) generates (uint32_t retval);

    /**
     * coreInitialized() is called after the CORE_INIT_RSP is received from the
     * NFCC. At this time, the HAL can do any chip-specific configuration.
     *
     * If coreInitialized() returns NfcStatus::OK, the NCI stack will wait for a
     * NfcEvent.POST_INIT_CPLT before continuing.
     *
     * If coreInitialized() returns NfcStatus::FAILED, the NCI stack will
     * continue immediately.
     */
    @callflow(next={"write", "prediscover", "close"})
    coreInitialized(NfcData data) generates (NfcStatus status);

    /**
     * prediscover is called every time before starting RF discovery.
     * It is a good place to do vendor-specific configuration that must be
     * performed every time RF discovery is about to be started.
     *
     * If prediscover() returns NfcStatus::OK, the NCI stack will wait for a
     * NfcEvent.PREDISCOVER_CPLT before continuing.
     *
     * If prediscover() returns NfcStatus::FAILED, the NCI stack will start
     * RF discovery immediately.
     */
    @callflow(next={"write", "close", "coreInitialized", "powerCycle", "controlGranted"})
    prediscover() generates (NfcStatus status);

    /**
     * Close the NFC controller. Should free all resources.
     *
     * @return NfcStatus::OK on success and NfcStatus::FAILED on error.
     */
    @exit
    close() generates (NfcStatus status);

    /**
     * Grant HAL the exclusive control to send NCI commands.
     * Called in response to NfcEvent.REQUEST_CONTROL.
     * Must only be called when there are no NCI commands pending.
     * NfcEvent.RELEASE_CONTROL will notify when HAL no longer needs exclusive control.
     *
     * @return NfcStatus::OK on success and NfcStatus::FAILED on error.
     */
    @callflow(next={"write", "close", "prediscover", "coreInitialized", "powerCycle"})
    controlGranted() generates (NfcStatus status);

     /**
     * Restart controller by power cyle;
     * NfcEvent.OPEN_CPLT will notify when operation is complete.
     *
     * @return NfcStatus::OK on success and NfcStatus::FAILED on error.
     */
    @callflow(next={"write", "coreInitialized", "prediscover", "controlGranted", "close"})
    powerCycle() generates (NfcStatus status);
};