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.nfc@1.0;
18
19import INfcClientCallback;
20
21interface INfc {
22    /**
23     * Opens the NFC controller device and performs initialization.
24     * This may include patch download and other vendor-specific initialization.
25     *
26     * If open completes successfully, the controller should be ready to perform
27     * NCI initialization - ie accept CORE_RESET and subsequent commands through
28     * the write() call.
29     *
30     * If open() returns NfcStatus::OK, the NCI stack will wait for a
31     * NfcEvent.OPEN_CPLT before continuing.
32     *
33     * If open() returns NfcStatus::FAILED, the NCI stack will stop.
34     *
35     */
36    @entry
37    @callflow(next={"write", "coreInitialized", "prediscover", "powerCycle", "controlGranted"})
38    open(INfcClientCallback clientCallback) generates (NfcStatus status);
39
40    /**
41     * Performs an NCI write.
42     *
43     * This method may queue writes and return immediately. The only
44     * requirement is that the writes are executed in order.
45     *
46     * @return number of bytes written to the NFCC
47     */
48    @callflow(next={"write", "prediscover", "coreInitialized", "close", "powerCycle",
49                    "controlGranted"})
50    write(NfcData data) generates (uint32_t retval);
51
52    /**
53     * coreInitialized() is called after the CORE_INIT_RSP is received from the
54     * NFCC. At this time, the HAL can do any chip-specific configuration.
55     *
56     * If coreInitialized() returns NfcStatus::OK, the NCI stack will wait for a
57     * NfcEvent.POST_INIT_CPLT before continuing.
58     *
59     * If coreInitialized() returns NfcStatus::FAILED, the NCI stack will
60     * continue immediately.
61     */
62    @callflow(next={"write", "prediscover", "close"})
63    coreInitialized(NfcData data) generates (NfcStatus status);
64
65    /**
66     * prediscover is called every time before starting RF discovery.
67     * It is a good place to do vendor-specific configuration that must be
68     * performed every time RF discovery is about to be started.
69     *
70     * If prediscover() returns NfcStatus::OK, the NCI stack will wait for a
71     * NfcEvent.PREDISCOVER_CPLT before continuing.
72     *
73     * If prediscover() returns NfcStatus::FAILED, the NCI stack will start
74     * RF discovery immediately.
75     */
76    @callflow(next={"write", "close", "coreInitialized", "powerCycle", "controlGranted"})
77    prediscover() generates (NfcStatus status);
78
79    /**
80     * Close the NFC controller. Should free all resources.
81     *
82     * @return NfcStatus::OK on success and NfcStatus::FAILED on error.
83     */
84    @exit
85    close() generates (NfcStatus status);
86
87    /**
88     * Grant HAL the exclusive control to send NCI commands.
89     * Called in response to NfcEvent.REQUEST_CONTROL.
90     * Must only be called when there are no NCI commands pending.
91     * NfcEvent.RELEASE_CONTROL will notify when HAL no longer needs exclusive control.
92     *
93     * @return NfcStatus::OK on success and NfcStatus::FAILED on error.
94     */
95    @callflow(next={"write", "close", "prediscover", "coreInitialized", "powerCycle"})
96    controlGranted() generates (NfcStatus status);
97
98     /**
99     * Restart controller by power cyle;
100     * NfcEvent.OPEN_CPLT will notify when operation is complete.
101     *
102     * @return NfcStatus::OK on success and NfcStatus::FAILED on error.
103     */
104    @callflow(next={"write", "coreInitialized", "prediscover", "controlGranted", "close"})
105    powerCycle() generates (NfcStatus status);
106};
107