xref: /aosp_15_r20/system/nfc/tools/casimir/src/rf_packets.pdl (revision 7eba2f3b06c51ae21384f6a4f14577b668a869b3)

little_endian_packets

/// The specification of RF packets is based on the following specifications:
/// - [DIGITAL] Digital Protocol Technical Specification Version 2.3
/// - [ACTIVITY] Activity Technical Specification Version 2.2
/// - [NCI] NFC Controller Interface Technical Specification Version 2.2
///
/// [ACTIVITY] describes the state machines for compliant NFC devices in Poll
/// or Listen mode. [DIGITAL] provides the format for packet exchanged
/// during the device Discovery and Activation as defined in [ACTIVITY].

/// Technology used for this message.
/// The values are taken from [NCI] Table 130: RF Technologies.
enum Technology : 8 {
    NFC_A = 0,
    NFC_B = 1,
    NFC_F = 2,
    NFC_V = 3,
    RAW = 0x7,
}

/// Protocol used for data exchange.
/// The values are taken from [NCI] Table 133: RF Protocol.
/// The following table presents the compatible protocols
/// for the technology and platform being used.
///
///    | Technology | Platform | Protocol |
///    +------------+----------+----------+
///    | NFC-A      | T2T      | T2T      |
///    |            | T4AT     | ISO-DEP  |
///    |            | -        | NFC-DEP  |
///    | NFC-B      | T4BT     | ISO-DEP  |
///    | NFC-F      | T3T      | T3T      |
///    | NFC-V      | T5T      | T5T      |
enum Protocol : 8 {
    UNDETERMINED = 0,
    T1T = 1,
    T2T = 2,
    T3T = 3,
    ISO_DEP = 4,
    NFC_DEP = 5,
    T5T = 6,
    NDEF = 7,
}

/// Type of packets being sent.
/// These packet types abstract the frames specified in [DIGITAL]
/// for each technology and protocol. Packets are grouped by activity
/// as specified by [ACTIVITY]:
/// - DATA is used for the Data Exchange activity
/// - POLL_COMMAND, POLL_RESPONSE are used for the Technology Detection and
///   Collision Resolution activities
/// - SELECT_COMMAND, SELECT_RESPONSE are used for the Device Activation activity
/// - DEACTIVATE_NOTIFICATION is used for the Device Deactivation activity
enum RfPacketType : 8 {
    DATA = 0,
    POLL_COMMAND = 1,
    POLL_RESPONSE = 2,
    SELECT_COMMAND = 3,
    SELECT_RESPONSE = 4,
    DEACTIVATE_NOTIFICATION = 5,
    FIELD_INFO = 6,
}

/// The definition of packets does not aim to reproduce the exact protocol
/// frames from [DIGITAL] or the exact state machines from [ACTIVITY],
/// but summarizes the information for singular activities that will be visible
/// to the Device Host.
packet RfPacket {
    sender: 16,
    receiver: 16,
    technology: Technology,
    protocol : Protocol,
    packet_type: RfPacketType,
    // Power level from 0-12 with higher numbers representing stronger field strength.
    // OxFF represents an unknown or invalid value.
    power_level: 8,
    _payload_,
}

/// Command to probe for Listeners:
/// - ALL_REQ Command or SENS_REQ Command for NFC-A
/// - ALLB_REQ Command or SENSB_REQ Command for NFC-B
/// - SENSF_REQ Command for NFC-F
/// - INVENTORY_REQ Command for NFC-V
/// - ATR_REQ Command for NFC-ACM
packet PollCommand : RfPacket (packet_type = POLL_COMMAND) {
    _payload_,
}

/// Whether the RF field of the tag is currently on or off
/// as defined by RF_FIELD_INFO_NTF
enum FieldStatus : 8 {
    FieldOff = 0,
    FieldOn = 1,
}

packet FieldInfo : RfPacket (packet_type = FIELD_INFO) {
    field_status: FieldStatus,
}

/// Poll response for an NFC-A Listener.
/// Combines information from the SENS_RES Response and the SEL_RES Response.
/// Cf [DIGITAL] 6.6.3 SENS_RES Response, [DIGITAL] 6.8.2 SEL_RES Response.
packet NfcAPollResponse : RfPacket (technology = NFC_A, packet_type = POLL_RESPONSE) {
    // Cf [DIGITAL] Requirements 25: NFCID1
    // - **6.7.2.2** _The NFCID1 can be dynamically generated by the NFC Forum
    //      Device. If it is dynamically generated by the NFC Forum
    //      Device, the length of the NFCID1 SHALL be limited to 4 bytes._
    // - **6.7.2.3** _A dynamically generated NFCID1 SHALL be generated whenever
    //      the NFC Forum Device enters the IDLE State of the Listen Mode state
    //      machine (specified in [ACTIVITY]) from any of the following States:
    //      NO_REMOTE_FIELD, ATR_READY_A, ATR_READY_F, TARGET_A, TARGET_F._
    // - **6.7.2.4** _The nfcid1[0] for a single-size NFCID1 SHALL be coded as
    //      specified in Table 17._
    // - **6.7.2.5** _The Listener SHALL set nfcid1[0] of a single-size NFCID1
    //      and nfcid1[3] of a double-size NFCID1 to a value not equal to 88h._
    _size_ (nfcid1) : 8,
    nfcid1 : 8[],
    // Cf [DIGITAL] Table 20: SEL_RES Response Format
    // - `00b`: Configured for Type 2 Tag Platform
    // - `01b`: Configured for Type 4A Tag Platform
    // - `10b`: Configured for the NFC-DEP Protocol
    // - `11b`: Configured for the NFC-DEP Protocol and Type 4A Tag Platform
    int_protocol : 2,
    _reserved_ : 6,
    // Cf [DIGITAL] Table 10: Byte 1 of SENS_RES (Anticollision Information)
    bit_frame_sdd: 8,
}

/// Select command for an NFC-A Listener using ISO-DEP protocol (Type-4A Tag platform).
/// Contains information from the RATS Command.
/// Cf [DIGITAL] 14.6.1 RATS Command.
packet T4ATSelectCommand : RfPacket (technology = NFC_A, protocol = ISO_DEP, packet_type = SELECT_COMMAND) {
    // Cf [DIGITAL] Table 55: RATS Parameter Byte (PARAM) Format
    param : 8,
}

/// Select response for an NFC-A Listener using ISO-DEP protocol (Type-4A Tag platform).
/// Contains information from the RATS Response.
/// Cf [DIGITAL] 14.6.2 RATS Response (Answer To Select).
packet T4ATSelectResponse : RfPacket (technology = NFC_A, protocol = ISO_DEP, packet_type = SELECT_RESPONSE) {
    // Cf [DIGITAL] Table 58: RATS Response Format
    // `rats_response` contains all the bytes from the RATS Response, starting
    // from and including Byte 2.
    _size_(rats_response) : 8,
    rats_response : 8[],
}

/// Select command for an NFC-A Listener using NFC-DEP protocol.
/// Contains information from the PSL_REQ Command.
/// Cf [DIGITAL] 17.7.1 PSL_REQ Command.
packet NfcDepSelectCommand : RfPacket (protocol = NFC_DEP, packet_type = SELECT_COMMAND) {
    // Cf [DIGITAL] Table 95: FSL Format
    lr : 2,
    _reserved_ : 6,
}

/// Select response for an NFC-A Listener using NFC-DEP protocol.
/// Contains information from the ATR_RES Response and PSL_RES Response.
/// Cf [DIGITAL] 17.6.3 ATR_RES Response, [DIGITAL] 17.7.2 PSL_RES Response.
packet NfcDepSelectResponse : RfPacket (protocol = NFC_DEP, packet_type = SELECT_RESPONSE) {
    // Cf [DIGITAL] Table 87: ATR_RES Response Format
    _size_(atr_response) : 8,
    atr_response : 8[],
}

/// Command to select and activate a polled Listener.
/// The Listener is uniquely identified by the `sender` identifier
/// of the PollResponse packet.
/// The protocol field selects the activated protocol. Valid protocols are
/// determined by the technology and supported protocols of the Listener.
///
/// TODO: this command combines device selection and protocol activation.
/// When using the RF Frame interface the protocol activation is handled
/// by the DH. This interface will need to be changed to support DH protocol
/// activation.
packet SelectCommand : RfPacket (packet_type = SELECT_COMMAND) {
}

/// Deactivation types.
/// The values are taken from [NCI] Table 80: Deactivation Types.
enum DeactivateType : 8 {
    IDLE_MODE = 0x00,
    SLEEP_MODE = 0x01,
    SLEEP_AF_MODE = 0x02,
    DISCOVERY = 0x03,
}

/// Deactivation reason.
/// The values are taken from [NCI] Table 81: Deactivation Reasons.
enum DeactivateReason : 8 {
    DH_REQUEST = 0,
    ENDPOINT_REQUEST = 1,
    RF_LINK_LOSS = 2,
    NFC_B_BAD_AFI = 3,
    DH_REQUEST_FAILED = 4,
}

/// Command to deactivate a selected Listener:
/// - RLS_REQ Command or DSL_REQ Command for NFC-DEP
/// - DESELECT Command for ISO-DEP
/// - SLP_REQ Command for T2T
/// This command may also be sent spuriously by the emulator to notify
/// of a loss of link.
packet DeactivateNotification : RfPacket (packet_type = DEACTIVATE_NOTIFICATION) {
    type_ : DeactivateType,
    reason : DeactivateReason,
}

/// Transmit data packets of the selected protocol.
/// Valid protocols are determined by the technology and supported
/// protocols of the Listener.
packet Data : RfPacket (packet_type = DATA) {
    data : 8[],
}