[FL-3666] NFC API improvements (#3214)

* drivers: expose st25r3916 driver API * nfc poller: add start with custom callback * mf classic: rework sync API with poller custom start * mf ultralight: rework sync API with poller custom start * iso14443_3a poller: remove unused col res state * nfc: rework nfc poller custom start * mf ultralight: rename sync API * mf classic: rename sync API * iso14443-3a: rename sync API * nfc: remove async prefix in internal functions * nfc: expose internal API * nfc: fix sync api include and docs * targets: fix f18 build * nfc: rework NfcGenericEventEx type * nfc poller: add documentation * iso14443-3a poller: add documentation * felica poller: add documentation * iso14443_3b poller: add documentation * so14443_4a poller: add documentation * iso14443_4b poller: add documentation * iso15693 poller: add documentation * slix poller: add documentation * mf desfire poller: add documentation * mf ultralight poller: fix API and add documentation * mf classic poller: add documentation Co-authored-by: あく <alleteam@gmail.com>
2023-11-15 17:32:45 +09:00
parent d0b9a3a4ae
commit c00776ca22
62 changed files with 1708 additions and 719 deletions
@@ -50,8 +50,7 @@ static NfcCommand slix_poller_handler_idle(SlixPoller* instance) {
 }

 static NfcCommand slix_poller_handler_get_nfc_system_info(SlixPoller* instance) {
-    instance->error =
-        slix_poller_async_get_nxp_system_info(instance, &instance->data->system_info);
+    instance->error = slix_poller_get_nxp_system_info(instance, &instance->data->system_info);
    if(instance->error == SlixErrorNone) {
        instance->poller_state = SlixPollerStateReadSignature;
    } else {
@@ -62,7 +61,7 @@ static NfcCommand slix_poller_handler_get_nfc_system_info(SlixPoller* instance)
 }

 static NfcCommand slix_poller_handler_read_signature(SlixPoller* instance) {
-    instance->error = slix_poller_async_read_signature(instance, &instance->data->signature);
+    instance->error = slix_poller_read_signature(instance, &instance->data->signature);
    if(instance->error == SlixErrorNone) {
        instance->poller_state = SlixPollerStateReady;
    } else {
@@ -141,7 +140,7 @@ static bool slix_poller_detect(NfcGenericEvent event, void* context) {
    if(iso15693_3_event->type == Iso15693_3PollerEventTypeReady) {
        if(slix_get_type(instance->data) < SlixTypeCount) {
            SlixSystemInfo system_info = {};
-            SlixError error = slix_poller_async_get_nxp_system_info(instance, &system_info);
+            SlixError error = slix_poller_get_nxp_system_info(instance, &system_info);
            protocol_detected = (error == SlixErrorNone);
        }
    }
@@ -8,22 +8,78 @@
 extern "C" {
 #endif

+/**
+ * @brief SlixPoller opaque type definition.
+ */
 typedef struct SlixPoller SlixPoller;

+/**
+ * @brief Enumeration of possible Slix poller event types.
+ */
 typedef enum {
-    SlixPollerEventTypeError,
-    SlixPollerEventTypeReady,
+    SlixPollerEventTypeError, /**< An error occured while reading card. */
+    SlixPollerEventTypeReady, /**< The card was successfully read by the poller. */
 } SlixPollerEventType;

-typedef struct {
-    SlixError error;
+/**
+ * @brief Slixs poller event data.
+ */
+typedef union {
+    SlixError error; /**< Error code indicating card reaing fail reason. */
 } SlixPollerEventData;

+/**
+ * @brief Slix poller event structure.
+ *
+ * Upon emission of an event, an instance of this struct will be passed to the callback.
+ */
 typedef struct {
-    SlixPollerEventType type;
-    SlixPollerEventData* data;
+    SlixPollerEventType type; /**< Type of emmitted event. */
+    SlixPollerEventData* data; /**< Pointer to event specific data. */
 } SlixPollerEvent;

+/**
+ * @brief Transmit and receive Slix frames in poller mode.
+ *
+ * Must ONLY be used inside the callback function.
+ *
+ * The rx_buffer will be filled with any data received as a response to data
+ * sent from tx_buffer, with a timeout defined by the fwt parameter.
+ *
+ * @param[in, out] instance pointer to the instance to be used in the transaction.
+ * @param[in] tx_buffer pointer to the buffer containing the data to be transmitted.
+ * @param[out] rx_buffer pointer to the buffer to be filled with received data.
+ * @param[in] fwt frame wait time (response timeout), in carrier cycles.
+ * @return SlixErrorNone on success, an error code on failure.
+ */
+SlixError slix_poller_send_frame(
+    SlixPoller* instance,
+    const BitBuffer* tx_data,
+    BitBuffer* rx_data,
+    uint32_t fwt);
+
+/**
+ * @brief Send get nxp system info command and parse response.
+ *
+ * Must ONLY be used inside the callback function.
+ *
+ * @param[in, out] instance pointer to the instance to be used in the transaction.
+ * @param[out] data pointer to the SlixSystemInfo structure to be filled.
+ * @return SlixErrorNone on success, an error code on failure.
+ */
+SlixError slix_poller_get_nxp_system_info(SlixPoller* instance, SlixSystemInfo* data);
+
+/**
+ * @brief Read signature from card.
+ *
+ * Must ONLY be used inside the callback function.
+ *
+ * @param[in, out] instance pointer to the instance to be used in the transaction.
+ * @param[out] data pointer to the SlixSignature structure to be filled.
+ * @return SlixErrorNone on success, an error code on failure.
+ */
+SlixError slix_poller_read_signature(SlixPoller* instance, SlixSignature* data);
+
 #ifdef __cplusplus
 }
 #endif
@@ -32,7 +32,7 @@ SlixError slix_poller_send_frame(
    return slix_process_iso15693_3_error(iso15693_3_error);
 }

-SlixError slix_poller_async_get_nxp_system_info(SlixPoller* instance, SlixSystemInfo* data) {
+SlixError slix_poller_get_nxp_system_info(SlixPoller* instance, SlixSystemInfo* data) {
    furi_assert(instance);
    furi_assert(data);

@@ -50,7 +50,7 @@ SlixError slix_poller_async_get_nxp_system_info(SlixPoller* instance, SlixSystem
    return error;
 }

-SlixError slix_poller_async_read_signature(SlixPoller* instance, SlixSignature* data) {
+SlixError slix_poller_read_signature(SlixPoller* instance, SlixSignature* data) {
    furi_assert(instance);
    furi_assert(data);

@@ -33,16 +33,6 @@ struct SlixPoller {
    void* context;
 };

-SlixError slix_poller_send_frame(
-    SlixPoller* instance,
-    const BitBuffer* tx_data,
-    BitBuffer* rx_data,
-    uint32_t fwt);
-
-SlixError slix_poller_async_get_nxp_system_info(SlixPoller* instance, SlixSystemInfo* data);
-
-SlixError slix_poller_async_read_signature(SlixPoller* instance, SlixSignature* data);
-
 #ifdef __cplusplus
 }
 #endif