api: notify in the interface about the reason why the modem is FAILED

We currently implement 'SIM missing' and 'SIM error', which are probably the
most common ones.

cli/mmcli-common.c

@@ -1063,6 +1063,8 @@ mmcli_get_state_reason_string (MMModemStateChangeReason reason)
         return "User request";
     case MM_MODEM_STATE_CHANGE_REASON_SUSPEND:
         return "Suspend";
+    case MM_MODEM_STATE_CHANGE_REASON_FAILURE:
+        return "Failure";
     }
 
     g_warn_if_reached ();

cli/mmcli-modem.c

@@ -351,13 +351,18 @@ print_modem_info (void)
     g_print ("  -------------------------\n"
              "  Status   |           lock: '%s'\n"
              "           | unlock retries: '%s'\n"
-             "           |          state: '%s'\n"
+             "           |          state: '%s'\n",
-             "           |    power state: '%s'\n"
-             "           |    access tech: '%s'\n"
-             "           | signal quality: '%u' (%s)\n",
              mm_modem_lock_get_string (mm_modem_get_unlock_required (ctx->modem)),
              VALIDATE_UNKNOWN (unlock_retries_string),
-             VALIDATE_UNKNOWN (mm_modem_state_get_string (mm_modem_get_state (ctx->modem))),
+             VALIDATE_UNKNOWN (mm_modem_state_get_string (mm_modem_get_state (ctx->modem))));
+
+    if (mm_modem_get_state (ctx->modem) == MM_MODEM_STATE_FAILED)
+        g_print ("           |  failed reason: '%s'\n",
+                 VALIDATE_UNKNOWN (mm_modem_state_failed_reason_get_string (mm_modem_get_state_failed_reason (ctx->modem))));
+
+    g_print ("           |    power state: '%s'\n"
+             "           |    access tech: '%s'\n"
+             "           | signal quality: '%u' (%s)\n",
              VALIDATE_UNKNOWN (mm_modem_power_state_get_string (mm_modem_get_power_state (ctx->modem))),
              VALIDATE_UNKNOWN (access_technologies_string),
              signal_quality, signal_quality_recent ? "recent" : "cached");

docs/reference/api/ModemManager-sections.txt

@@ -20,6 +20,7 @@ MMModemLocationSource
 MMModemLock
 MMModemMode
 MMModemState
+MMModemStateFailedReason
 MMModemStateChangeReason
 MMModemPowerState
 MMSmsPduType

docs/reference/libmm-glib/libmm-glib-sections.txt

@@ -77,6 +77,7 @@ MMModem
 mm_modem_get_path
 mm_modem_dup_path
 mm_modem_get_state
+mm_modem_get_state_failed_reason
 mm_modem_get_power_state
 mm_modem_get_modem_capabilities
 mm_modem_get_current_capabilities
@@ -957,6 +958,7 @@ mm_bearer_ip_family_get_string
 mm_bearer_allowed_auth_build_string_from_mask
 mm_modem_capability_build_string_from_mask
 mm_modem_state_get_string
+mm_modem_state_failed_reason_get_string
 mm_modem_state_change_reason_get_string
 mm_modem_power_state_get_string
 mm_modem_lock_get_string
@@ -981,6 +983,7 @@ mm_firmware_image_type_get_string
 mm_modem_capability_get_string
 mm_modem_lock_build_string_from_mask
 mm_modem_state_build_string_from_mask
+mm_modem_state_failed_reason_build_string_from_mask
 mm_modem_state_change_reason_build_string_from_mask
 mm_modem_power_state_build_string_from_mask
 mm_modem_access_technology_get_string
@@ -1023,6 +1026,7 @@ MM_TYPE_MODEM_LOCATION_SOURCE
 MM_TYPE_MODEM_LOCK
 MM_TYPE_MODEM_MODE
 MM_TYPE_MODEM_STATE
+MM_TYPE_MODEM_STATE_FAILED_REASON
 MM_TYPE_MODEM_STATE_CHANGE_REASON
 MM_TYPE_MODEM_POWER_STATE
 MM_TYPE_SMS_DELIVERY_STATE
@@ -1049,6 +1053,7 @@ mm_modem_lock_get_type
 mm_modem_mode_get_type
 mm_modem_state_change_reason_get_type
 mm_modem_state_get_type
+mm_modem_state_failed_reason_get_type
 mm_modem_power_state_get_type
 mm_sms_delivery_state_get_type
 mm_sms_pdu_type_get_type
@@ -1437,6 +1442,7 @@ mm_gdbus_modem_dup_signal_quality
 mm_gdbus_modem_get_sim
 mm_gdbus_modem_dup_sim
 mm_gdbus_modem_get_state
+mm_gdbus_modem_get_state_failed_reason
 mm_gdbus_modem_get_supported_bands
 mm_gdbus_modem_dup_supported_bands
 mm_gdbus_modem_get_supported_modes
@@ -1496,6 +1502,7 @@ mm_gdbus_modem_set_revision
 mm_gdbus_modem_set_signal_quality
 mm_gdbus_modem_set_sim
 mm_gdbus_modem_set_state
+mm_gdbus_modem_set_state_failed_reason
 mm_gdbus_modem_set_power_state
 mm_gdbus_modem_set_supported_bands
 mm_gdbus_modem_set_supported_modes

include/ModemManager-enums.h

@@ -128,6 +128,22 @@ typedef enum { /*< underscore_name=mm_modem_state >*/
     MM_MODEM_STATE_CONNECTED     = 11
 } MMModemState;
 
+/**
+ * MMModemStateFailedReason:
+ * @MM_MODEM_STATE_FAILED_REASON_NONE: No error.
+ * @MM_MODEM_STATE_FAILED_REASON_UNKNOWN: Unknown error.
+ * @MM_MODEM_STATE_FAILED_REASON_SIM_MISSING: SIM is required but missing.
+ * @MM_MODEM_STATE_FAILED_REASON_SIM_ERROR: SIM is available, but unusable (e.g. permanently locked).
+ *
+ * Enumeration of possible errors when the modem is in @MM_MODEM_STATE_FAILED.
+ */
+typedef enum { /*< underscore_name=mm_modem_state_failed_reason >*/
+    MM_MODEM_STATE_FAILED_REASON_NONE        = 0,
+    MM_MODEM_STATE_FAILED_REASON_UNKNOWN     = 1,
+    MM_MODEM_STATE_FAILED_REASON_SIM_MISSING = 2,
+    MM_MODEM_STATE_FAILED_REASON_SIM_ERROR   = 3,
+} MMModemStateFailedReason;
+
 /**
  * MMModemPowerState:
  * @MM_MODEM_POWER_STATE_UNKNOWN: Unknown power state.
@@ -149,6 +165,7 @@ typedef enum { /*< underscore_name=mm_modem_power_state >*/
  * @MM_MODEM_STATE_CHANGE_REASON_UNKNOWN: Reason unknown or not reportable.
  * @MM_MODEM_STATE_CHANGE_REASON_USER_REQUESTED: State change was requested by an interface user.
  * @MM_MODEM_STATE_CHANGE_REASON_SUSPEND: State change was caused by a system suspend.
+ * @MM_MODEM_STATE_CHANGE_REASON_FAILURE: State change was caused by an unrecoverable error.
  *
  * Enumeration of possible reasons to have changed the modem state.
  */
@@ -156,6 +173,7 @@ typedef enum { /*< underscore_name=mm_modem_state_change_reason >*/
     MM_MODEM_STATE_CHANGE_REASON_UNKNOWN        = 0,
     MM_MODEM_STATE_CHANGE_REASON_USER_REQUESTED = 1,
     MM_MODEM_STATE_CHANGE_REASON_SUSPEND        = 2,
+    MM_MODEM_STATE_CHANGE_REASON_FAILURE        = 3,
 } MMModemStateChangeReason;
 
 /**

introspection/org.freedesktop.ModemManager1.Modem.xml

@@ -356,6 +356,16 @@
     -->
     <property name="State" type="i" access="read" />
 
+    <!--
+        StateFailedReason:
+
+        Error specifying why the modem is in
+	<link linkend="MM-MODEM-STATE-FAILED:CAPS"><constant>MM_MODEM_STATE_FAILED</constant></link>
+	state, given as a
+	<link linkend="MMModemStateFailedReason">MMModemStateFailedReason</link> value.
+    -->
+    <property name="StateFailedReason" type="u" access="read" />
+
     <!--
         AccessTechnologies:
 

libmm-glib/mm-modem.c

@@ -816,6 +816,24 @@ mm_modem_get_state (MMModem *self)
 
 /*****************************************************************************/
 
+/**
+ * mm_modem_get_state_failed_reason:
+ * @self: A #MMModem.
+ *
+ * Gets the reason specifying why the modem is in #MM_MODEM_STATE_FAILED state.
+ *
+ * Returns: A #MMModemStateFailedReason value.
+ */
+MMModemStateFailedReason
+mm_modem_get_state_failed_reason (MMModem *self)
+{
+    g_return_val_if_fail (MM_IS_MODEM (self), MM_MODEM_STATE_FAILED_REASON_UNKNOWN);
+
+    return (MMModemStateFailedReason) mm_gdbus_modem_get_state_failed_reason (MM_GDBUS_MODEM (self));
+}
+
+/*****************************************************************************/
+
 /**
  * mm_modem_get_power_state:
  * @self: A #MMModem.

libmm-glib/mm-modem.h

@@ -118,6 +118,8 @@ MMUnlockRetries   *mm_modem_peek_unlock_retries      (MMModem *self);
 
 MMModemState       mm_modem_get_state                (MMModem *self);
 
+MMModemStateFailedReason mm_modem_get_state_failed_reason (MMModem *self);
+
 MMModemPowerState  mm_modem_get_power_state          (MMModem *self);
 
 MMModemAccessTechnology mm_modem_get_access_technologies (MMModem *self);

src/mm-broadband-modem.c

@@ -8423,13 +8423,26 @@ iface_modem_initialize_ready (MMBroadbandModem *self,
     /* If the modem interface fails to get initialized, we will move the modem
      * to a FAILED state. Note that in this case we still export the interface. */
     if (!mm_iface_modem_initialize_finish (MM_IFACE_MODEM (self), result, &error)) {
+        MMModemStateFailedReason failed_reason = MM_MODEM_STATE_FAILED_REASON_UNKNOWN;
+
         /* Report the new FAILED state */
         mm_warn ("Modem couldn't be initialized: %s", error->message);
+
+        if (g_error_matches (error,
+                             MM_MOBILE_EQUIPMENT_ERROR,
+                             MM_MOBILE_EQUIPMENT_ERROR_SIM_NOT_INSERTED))
+            failed_reason = MM_MODEM_STATE_FAILED_REASON_SIM_MISSING;
+        else if (g_error_matches (error,
+                                  MM_MOBILE_EQUIPMENT_ERROR,
+                                  MM_MOBILE_EQUIPMENT_ERROR_SIM_FAILURE) ||
+                 g_error_matches (error,
+                                  MM_MOBILE_EQUIPMENT_ERROR,
+                                  MM_MOBILE_EQUIPMENT_ERROR_SIM_WRONG))
+            failed_reason = MM_MODEM_STATE_FAILED_REASON_SIM_MISSING;
+
         g_error_free (error);
 
-        mm_iface_modem_update_state (MM_IFACE_MODEM (self),
+        mm_iface_modem_update_failed_state (MM_IFACE_MODEM (self), failed_reason);
-                                     MM_MODEM_STATE_FAILED,
-                                     MM_MODEM_STATE_CHANGE_REASON_UNKNOWN);
 
         /* Jump to the firmware step. We allow firmware switching even in failed
          * state */
@@ -8474,9 +8487,8 @@ iface_modem_initialize_ready (MMBroadbandModem *self,
                 g_error_free (error);                                   \
                                                                         \
                 /* Report the new FAILED state */                       \
-                mm_iface_modem_update_state (MM_IFACE_MODEM (self),     \
+                mm_iface_modem_update_failed_state (MM_IFACE_MODEM (self), \
-                                             MM_MODEM_STATE_FAILED,     \
+                                                    MM_MODEM_STATE_FAILED_REASON_UNKNOWN); \
-                                             MM_MODEM_STATE_CHANGE_REASON_UNKNOWN); \
                                                                         \
                 /* Just jump to the last step */                        \
                 ctx->step = INITIALIZE_STEP_LAST;                       \

src/mm-iface-modem.c

@@ -1145,10 +1145,11 @@ bearer_list_count_connected (MMBearer *bearer,
         (*count)++;
 }
 
-void
+static void
-mm_iface_modem_update_state (MMIfaceModem *self,
+__iface_modem_update_state_internal (MMIfaceModem *self,
-                             MMModemState new_state,
+                                     MMModemState new_state,
-                             MMModemStateChangeReason reason)
+                                     MMModemStateChangeReason reason,
+                                     MMModemStateFailedReason failed_reason)
 {
     MMModemState old_state = MM_MODEM_STATE_UNKNOWN;
     MmGdbusModem *skeleton = NULL;
@@ -1207,6 +1208,10 @@ mm_iface_modem_update_state (MMIfaceModem *self,
 
         /* Signal status change */
         if (skeleton) {
+            /* Set failure reason */
+            if (failed_reason != mm_gdbus_modem_get_state_failed_reason (skeleton))
+                mm_gdbus_modem_set_state_failed_reason (skeleton, failed_reason);
+
             /* Flush current change before signaling the state change,
              * so that clients get the proper state already in the
              * state-changed callback */
@@ -1239,6 +1244,23 @@ mm_iface_modem_update_state (MMIfaceModem *self,
         g_object_unref (bearer_list);
 }
 
+void
+mm_iface_modem_update_state (MMIfaceModem *self,
+                             MMModemState new_state,
+                             MMModemStateChangeReason reason)
+{
+    g_assert (new_state != MM_MODEM_STATE_FAILED);
+
+    __iface_modem_update_state_internal (self, new_state, reason, MM_MODEM_STATE_FAILED_REASON_NONE);
+}
+
+void
+mm_iface_modem_update_failed_state (MMIfaceModem *self,
+                                    MMModemStateFailedReason failed_reason)
+{
+    __iface_modem_update_state_internal (self, MM_MODEM_STATE_FAILED, MM_MODEM_STATE_CHANGE_REASON_FAILURE, failed_reason);
+}
+
 /*****************************************************************************/
 
 typedef struct {
@@ -4092,6 +4114,7 @@ mm_iface_modem_initialize (MMIfaceModem *self,
         mm_gdbus_modem_set_supported_bands (skeleton, mm_common_build_bands_unknown ());
         mm_gdbus_modem_set_bands (skeleton, mm_common_build_bands_unknown ());
         mm_gdbus_modem_set_power_state (skeleton, MM_MODEM_POWER_STATE_UNKNOWN);
+        mm_gdbus_modem_set_state_failed_reason (skeleton, MM_MODEM_STATE_FAILED_REASON_NONE);
 
         /* Bind our State property */
         g_object_bind_property (self, MM_IFACE_MODEM_STATE,

src/mm-iface-modem.h

@@ -397,6 +397,8 @@ void mm_iface_modem_update_subsystem_state (MMIfaceModem *self,
 void mm_iface_modem_update_state (MMIfaceModem *self,
                                   MMModemState new_state,
                                   MMModemStateChangeReason reason);
+void mm_iface_modem_update_failed_state (MMIfaceModem *self,
+                                         MMModemStateFailedReason failed_reason);
 
 /* Allow reporting new access tech */
 void mm_iface_modem_update_access_technologies (MMIfaceModem *self,