[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>

lib/nfc/protocols/felica/felica_poller.c

@@ -66,7 +66,7 @@ static NfcCommand felica_poller_run(NfcGenericEvent event, void* context) {
 
     if(nfc_event->type == NfcEventTypePollerReady) {
         if(instance->state != FelicaPollerStateActivated) {
-            FelicaError error = felica_poller_async_activate(instance, instance->data);
+            FelicaError error = felica_poller_activate(instance, instance->data);
             if(error == FelicaErrorNone) {
                 instance->felica_event.type = FelicaPollerEventTypeReady;
                 instance->felica_event_data.error = error;
@@ -100,7 +100,7 @@ static bool felica_poller_detect(NfcGenericEvent event, void* context) {
     furi_assert(instance->state == FelicaPollerStateIdle);
 
     if(nfc_event->type == NfcEventTypePollerReady) {
-        FelicaError error = felica_poller_async_activate(instance, instance->data);
+        FelicaError error = felica_poller_activate(instance, instance->data);
         protocol_detected = (error == FelicaErrorNone);
     }
 

lib/nfc/protocols/felica/felica_poller.h

@@ -9,22 +9,50 @@
 extern "C" {
 #endif
 
+/**
+ * @brief FelicaPoller opaque type definition.
+ */
 typedef struct FelicaPoller FelicaPoller;
 
+/**
+ * @brief Enumeration of possible Felica poller event types.
+ */
 typedef enum {
-    FelicaPollerEventTypeError,
-    FelicaPollerEventTypeReady,
+    FelicaPollerEventTypeError, /**< The card was activated by the poller. */
+    FelicaPollerEventTypeReady, /**< An error occured during activation procedure. */
 } FelicaPollerEventType;
 
-typedef struct {
-    FelicaError error;
+/**
+ * @brief Felica poller event data.
+ */
+typedef union {
+    FelicaError error; /**< Error code indicating card activation fail reason. */
 } FelicaPollerEventData;
 
+/**
+ * @brief FelicaPoller poller event structure.
+ *
+ * Upon emission of an event, an instance of this struct will be passed to the callback.
+ */
 typedef struct {
-    FelicaPollerEventType type;
-    FelicaPollerEventData* data;
+    FelicaPollerEventType type; /**< Type of emmitted event. */
+    FelicaPollerEventData* data; /**< Pointer to event specific data. */
 } FelicaPollerEvent;
 
+/**
+ * @brief Perform collision resolution procedure.
+ *
+ * Must ONLY be used inside the callback function.
+ *
+ * Perfoms the collision resolution procedure as defined in FeliCa standars. The data
+ * field will be filled with Felica data on success.
+ *
+ * @param[in, out] instance pointer to the instance to be used in the transaction.
+ * @param[out] data pointer to the Felica data structure to be filled.
+ * @return FelicaErrorNone on success, an error code on failure.
+ */
+FelicaError felica_poller_activate(FelicaPoller* instance, FelicaData* data);
+
 #ifdef __cplusplus
 }
 #endif

lib/nfc/protocols/felica/felica_poller_i.c

@@ -49,7 +49,7 @@ static FelicaError felica_poller_frame_exchange(
     return ret;
 }
 
-FelicaError felica_poller_async_polling(
+FelicaError felica_poller_polling(
     FelicaPoller* instance,
     const FelicaPollerPollingCommand* cmd,
     FelicaPollerPollingResponse* resp) {
@@ -93,7 +93,7 @@ FelicaError felica_poller_async_polling(
     return error;
 }
 
-FelicaError felica_poller_async_activate(FelicaPoller* instance, FelicaData* data) {
+FelicaError felica_poller_activate(FelicaPoller* instance, FelicaData* data) {
     furi_assert(instance);
 
     felica_reset(data);
@@ -112,7 +112,7 @@ FelicaError felica_poller_async_activate(FelicaPoller* instance, FelicaData* dat
         };
         FelicaPollerPollingResponse polling_resp = {};
 
-        ret = felica_poller_async_polling(instance, &polling_cmd, &polling_resp);
+        ret = felica_poller_polling(instance, &polling_cmd, &polling_resp);
 
         if(ret != FelicaErrorNone) {
             FURI_LOG_T(TAG, "Activation failed error: %d", ret);

lib/nfc/protocols/felica/felica_poller_i.h

@@ -48,13 +48,11 @@ typedef struct {
 
 const FelicaData* felica_poller_get_data(FelicaPoller* instance);
 
-FelicaError felica_poller_async_polling(
+FelicaError felica_poller_polling(
     FelicaPoller* instance,
     const FelicaPollerPollingCommand* cmd,
     FelicaPollerPollingResponse* resp);
 
-FelicaError felica_poller_async_activate(FelicaPoller* instance, FelicaData* data);
-
 #ifdef __cplusplus
 }
 #endif