xref: /aosp_15_r20/system/nfc/tools/casimir/src/rf_packets.pdl (revision 7eba2f3b06c51ae21384f6a4f14577b668a869b3) 
1little_endian_packets
2
3/// The specification of RF packets is based on the following specifications:
4/// - [DIGITAL] Digital Protocol Technical Specification Version 2.3
5/// - [ACTIVITY] Activity Technical Specification Version 2.2
6/// - [NCI] NFC Controller Interface Technical Specification Version 2.2
7///
8/// [ACTIVITY] describes the state machines for compliant NFC devices in Poll
9/// or Listen mode. [DIGITAL] provides the format for packet exchanged
10/// during the device Discovery and Activation as defined in [ACTIVITY].
11
12/// Technology used for this message.
13/// The values are taken from [NCI] Table 130: RF Technologies.
14enum Technology : 8 {
15    NFC_A = 0,
16    NFC_B = 1,
17    NFC_F = 2,
18    NFC_V = 3,
19    RAW = 0x7,
20}
21
22/// Protocol used for data exchange.
23/// The values are taken from [NCI] Table 133: RF Protocol.
24/// The following table presents the compatible protocols
25/// for the technology and platform being used.
26///
27///    | Technology | Platform | Protocol |
28///    +------------+----------+----------+
29///    | NFC-A      | T2T      | T2T      |
30///    |            | T4AT     | ISO-DEP  |
31///    |            | -        | NFC-DEP  |
32///    | NFC-B      | T4BT     | ISO-DEP  |
33///    | NFC-F      | T3T      | T3T      |
34///    | NFC-V      | T5T      | T5T      |
35enum Protocol : 8 {
36    UNDETERMINED = 0,
37    T1T = 1,
38    T2T = 2,
39    T3T = 3,
40    ISO_DEP = 4,
41    NFC_DEP = 5,
42    T5T = 6,
43    NDEF = 7,
44}
45
46/// Type of packets being sent.
47/// These packet types abstract the frames specified in [DIGITAL]
48/// for each technology and protocol. Packets are grouped by activity
49/// as specified by [ACTIVITY]:
50/// - DATA is used for the Data Exchange activity
51/// - POLL_COMMAND, POLL_RESPONSE are used for the Technology Detection and
52///   Collision Resolution activities
53/// - SELECT_COMMAND, SELECT_RESPONSE are used for the Device Activation activity
54/// - DEACTIVATE_NOTIFICATION is used for the Device Deactivation activity
55enum RfPacketType : 8 {
56    DATA = 0,
57    POLL_COMMAND = 1,
58    POLL_RESPONSE = 2,
59    SELECT_COMMAND = 3,
60    SELECT_RESPONSE = 4,
61    DEACTIVATE_NOTIFICATION = 5,
62    FIELD_INFO = 6,
63}
64
65/// The definition of packets does not aim to reproduce the exact protocol
66/// frames from [DIGITAL] or the exact state machines from [ACTIVITY],
67/// but summarizes the information for singular activities that will be visible
68/// to the Device Host.
69packet RfPacket {
70    sender: 16,
71    receiver: 16,
72    technology: Technology,
73    protocol : Protocol,
74    packet_type: RfPacketType,
75    // Power level from 0-12 with higher numbers representing stronger field strength.
76    // OxFF represents an unknown or invalid value.
77    power_level: 8,
78    _payload_,
79}
80
81/// Command to probe for Listeners:
82/// - ALL_REQ Command or SENS_REQ Command for NFC-A
83/// - ALLB_REQ Command or SENSB_REQ Command for NFC-B
84/// - SENSF_REQ Command for NFC-F
85/// - INVENTORY_REQ Command for NFC-V
86/// - ATR_REQ Command for NFC-ACM
87packet PollCommand : RfPacket (packet_type = POLL_COMMAND) {
88    _payload_,
89}
90
91/// Whether the RF field of the tag is currently on or off
92/// as defined by RF_FIELD_INFO_NTF
93enum FieldStatus : 8 {
94    FieldOff = 0,
95    FieldOn = 1,
96}
97
98packet FieldInfo : RfPacket (packet_type = FIELD_INFO) {
99    field_status: FieldStatus,
100}
101
102/// Poll response for an NFC-A Listener.
103/// Combines information from the SENS_RES Response and the SEL_RES Response.
104/// Cf [DIGITAL] 6.6.3 SENS_RES Response, [DIGITAL] 6.8.2 SEL_RES Response.
105packet NfcAPollResponse : RfPacket (technology = NFC_A, packet_type = POLL_RESPONSE) {
106    // Cf [DIGITAL] Requirements 25: NFCID1
107    // - **6.7.2.2** _The NFCID1 can be dynamically generated by the NFC Forum
108    //      Device. If it is dynamically generated by the NFC Forum
109    //      Device, the length of the NFCID1 SHALL be limited to 4 bytes._
110    // - **6.7.2.3** _A dynamically generated NFCID1 SHALL be generated whenever
111    //      the NFC Forum Device enters the IDLE State of the Listen Mode state
112    //      machine (specified in [ACTIVITY]) from any of the following States:
113    //      NO_REMOTE_FIELD, ATR_READY_A, ATR_READY_F, TARGET_A, TARGET_F._
114    // - **6.7.2.4** _The nfcid1[0] for a single-size NFCID1 SHALL be coded as
115    //      specified in Table 17._
116    // - **6.7.2.5** _The Listener SHALL set nfcid1[0] of a single-size NFCID1
117    //      and nfcid1[3] of a double-size NFCID1 to a value not equal to 88h._
118    _size_ (nfcid1) : 8,
119    nfcid1 : 8[],
120    // Cf [DIGITAL] Table 20: SEL_RES Response Format
121    // - `00b`: Configured for Type 2 Tag Platform
122    // - `01b`: Configured for Type 4A Tag Platform
123    // - `10b`: Configured for the NFC-DEP Protocol
124    // - `11b`: Configured for the NFC-DEP Protocol and Type 4A Tag Platform
125    int_protocol : 2,
126    _reserved_ : 6,
127    // Cf [DIGITAL] Table 10: Byte 1 of SENS_RES (Anticollision Information)
128    bit_frame_sdd: 8,
129}
130
131/// Select command for an NFC-A Listener using ISO-DEP protocol (Type-4A Tag platform).
132/// Contains information from the RATS Command.
133/// Cf [DIGITAL] 14.6.1 RATS Command.
134packet T4ATSelectCommand : RfPacket (technology = NFC_A, protocol = ISO_DEP, packet_type = SELECT_COMMAND) {
135    // Cf [DIGITAL] Table 55: RATS Parameter Byte (PARAM) Format
136    param : 8,
137}
138
139/// Select response for an NFC-A Listener using ISO-DEP protocol (Type-4A Tag platform).
140/// Contains information from the RATS Response.
141/// Cf [DIGITAL] 14.6.2 RATS Response (Answer To Select).
142packet T4ATSelectResponse : RfPacket (technology = NFC_A, protocol = ISO_DEP, packet_type = SELECT_RESPONSE) {
143    // Cf [DIGITAL] Table 58: RATS Response Format
144    // `rats_response` contains all the bytes from the RATS Response, starting
145    // from and including Byte 2.
146    _size_(rats_response) : 8,
147    rats_response : 8[],
148}
149
150/// Select command for an NFC-A Listener using NFC-DEP protocol.
151/// Contains information from the PSL_REQ Command.
152/// Cf [DIGITAL] 17.7.1 PSL_REQ Command.
153packet NfcDepSelectCommand : RfPacket (protocol = NFC_DEP, packet_type = SELECT_COMMAND) {
154    // Cf [DIGITAL] Table 95: FSL Format
155    lr : 2,
156    _reserved_ : 6,
157}
158
159/// Select response for an NFC-A Listener using NFC-DEP protocol.
160/// Contains information from the ATR_RES Response and PSL_RES Response.
161/// Cf [DIGITAL] 17.6.3 ATR_RES Response, [DIGITAL] 17.7.2 PSL_RES Response.
162packet NfcDepSelectResponse : RfPacket (protocol = NFC_DEP, packet_type = SELECT_RESPONSE) {
163    // Cf [DIGITAL] Table 87: ATR_RES Response Format
164    _size_(atr_response) : 8,
165    atr_response : 8[],
166}
167
168/// Command to select and activate a polled Listener.
169/// The Listener is uniquely identified by the `sender` identifier
170/// of the PollResponse packet.
171/// The protocol field selects the activated protocol. Valid protocols are
172/// determined by the technology and supported protocols of the Listener.
173///
174/// TODO: this command combines device selection and protocol activation.
175/// When using the RF Frame interface the protocol activation is handled
176/// by the DH. This interface will need to be changed to support DH protocol
177/// activation.
178packet SelectCommand : RfPacket (packet_type = SELECT_COMMAND) {
179}
180
181/// Deactivation types.
182/// The values are taken from [NCI] Table 80: Deactivation Types.
183enum DeactivateType : 8 {
184    IDLE_MODE = 0x00,
185    SLEEP_MODE = 0x01,
186    SLEEP_AF_MODE = 0x02,
187    DISCOVERY = 0x03,
188}
189
190/// Deactivation reason.
191/// The values are taken from [NCI] Table 81: Deactivation Reasons.
192enum DeactivateReason : 8 {
193    DH_REQUEST = 0,
194    ENDPOINT_REQUEST = 1,
195    RF_LINK_LOSS = 2,
196    NFC_B_BAD_AFI = 3,
197    DH_REQUEST_FAILED = 4,
198}
199
200/// Command to deactivate a selected Listener:
201/// - RLS_REQ Command or DSL_REQ Command for NFC-DEP
202/// - DESELECT Command for ISO-DEP
203/// - SLP_REQ Command for T2T
204/// This command may also be sent spuriously by the emulator to notify
205/// of a loss of link.
206packet DeactivateNotification : RfPacket (packet_type = DEACTIVATE_NOTIFICATION) {
207    type_ : DeactivateType,
208    reason : DeactivateReason,
209}
210
211/// Transmit data packets of the selected protocol.
212/// Valid protocols are determined by the technology and supported
213/// protocols of the Listener.
214packet Data : RfPacket (packet_type = DATA) {
215    data : 8[],
216}
217