From 36fbfab3e6c62ae7e4c7270dc55bf2d61d49bd98 Mon Sep 17 00:00:00 2001 From: Aleksander Morgado Date: Tue, 28 Feb 2012 21:33:21 +0100 Subject: docs: document Modem probing and global state machine --- docs/reference/api/ModemManager-overview.xml | 575 ++++++++++++++++++++++++++- 1 file changed, 562 insertions(+), 13 deletions(-) (limited to 'docs/reference') diff --git a/docs/reference/api/ModemManager-overview.xml b/docs/reference/api/ModemManager-overview.xml index f0d68dcc..fec56e55 100644 --- a/docs/reference/api/ModemManager-overview.xml +++ b/docs/reference/api/ModemManager-overview.xml @@ -47,11 +47,367 @@ - - State machine + + Modem detection and setup + +
+ Detection mechanisms + + ModemManager requires udev-powered Linux kernels in order + to get notified of possible available Modems. udev will report each of the ports + found in the device, and ModemManager will probe each of the ports marked with + the ID_MM_CANDIDATE tag in udev. This includes both "tty" + and "net" ports. + + + Aditionally, users of RS232-based devices may need to request additional manual + scans via DBus, in order to detect modems that may have been connected to + RS232 to USB adapters. In this case, udev just knows about the USB adapter being + connected, not about the RS232 modem connected to the adapter, if any. + +
+ +
+ Probing + + Whenever a new device is detected by ModemManager, port probing process will + get started, so that we can determine which kind of ports we have, and also + which plugin we need to use for the specific device. Devices may expose one or + more ports, and all of them will follow the same probing logic. + + + The whole probing process, including pre-probing and post-probing filters, is + implemented in the core ModemManager daemon. Plugins will just configure their + own special needs in the probing process, so that only the steps required by the + given plugin are executed. For example, plugins which do not support RS232 + devices will not need AT-based vendor or product filters. + + +
+ Pre-probing filters + + Pre-probing filters are those which control whether the probing, as + requested by the specific plugin, takes place. + + + + Allowed vendor IDs + + Plugins can provide a list of udev-reported vendor IDs to be used as + pre-probing filters. If the vendor ID reported by the device via udev + is found in the list provided by the plugin, port probing will be + launched as requested by the given plugin. + + + This filter is specified by the MM_PLUGIN_BASE_ALLOWED_VENDOR_IDS + property in the MMPluginBase object provided + by the plugin. + + + + Allowed product IDs + + Plugins can provide a list of udev-reported pairs of vendor and product + IDs to be used as pre-probing filters. If the vendor ID and product ID + pair reported by the device via udev is found in the list provided by + the plugin, port probing will be launched as requested by the given + plugin. + + + This additional filter should be used when the plugin is + expected to work only with a given specific product of a given vendor. + + + This filter is specified by the MM_PLUGIN_BASE_ALLOWED_PRODUCT_IDS + property in the MMPluginBase object provided + by the plugin. + + + + Subsystems + + Plugins can specify which subsystems they expect, so that we filter out + any port detected with a subsystem not listed by the plugin. + + + This filter is specified by the MM_PLUGIN_BASE_ALLOWED_SUBSYSTEMS + property in the MMPluginBase object provided + by the plugin. + + + + Drivers + + Plugins can specify which drivers they expect, so that we filter out + any port detected being managed by a driver not listed by the plugin. + + + This filter is specified by the MM_PLUGIN_BASE_ALLOWED_DRIVERS + property in the MMPluginBase object provided + by the plugin. + + + + udev tags + + Plugins can provide a list of udev tags, so that we filter out + any port detected which doesn't expose any of the given tags. + + + This filter is specified by the MM_PLUGIN_BASE_ALLOWED_UDEV_TAGS + property in the MMPluginBase object provided + by the plugin. + + + +
+ +
+ Probing sequence + + Whenever all pre-probing filters of a given plugin pass, ModemManager will run + the probing sequence as requested by the specific plugin. The main purpose of the + probing sequence step is to determine the type of port being probed, and also + prepare the information required in any expected post-probing filter. + + + + Custom AT initialization + + This property allows plugins to specify custom initialization sequences to + run in the modem before any additional probing happens. This helps in the cases + where modems require commands to, for example, shutdown unsolicited messages. + + + An additional benefit of the custom initialization through AT commands is that + it can already provide information on whether the port is AT or not. In other + words, a plugin with custom initialization sequence which reports that the + port being initialized is AT won't run the generic checks to see if the port is + AT or not. + + + This configuration is specified by the MM_PLUGIN_BASE_CUSTOM_INIT + property in the MMPluginBase object provided + by the plugin. + + + + AT Allowed + + This boolean property allows plugins to specify that they expect and support + AT serial ports. + + + This configuration is specified by the MM_PLUGIN_BASE_ALLOWED_AT + property in the MMPluginBase object provided + by the plugin. + + + + QCDM Allowed + + This boolean property allows plugins to specify that they expect and support + QCDM serial ports. + + + This configuration is specified by the MM_PLUGIN_BASE_ALLOWED_QCDM + property in the MMPluginBase object provided + by the plugin. + + + +
+ +
+ Post-probing filters + + Post-probing filters are required to identify whether a plugin can handle a given + modem, in special cases where the information retrieved from udev is either not + enough or wrong. This covers, for example, RS232 modems connected through a RS232 + to USB converter, where udev-reported vendor ID is that of the converter, not the + one of the modem. + + + + Allowed vendor strings + + Plugins can provide a list of vendor strings to be used as post-probing + filters. If the vendor string reported by the device via AT commands + is found in the list provided by the plugin, the plugin will report that + it can handle this modem. + + + This filter is specified by the MM_PLUGIN_BASE_ALLOWED_VENDOR_STRINGS + property in the MMPluginBase object provided + by the plugin. + + + + Allowed product strings + + Plugins can provide a list of pairs of vendor and product + strings to be used as post-probing filters. If the vendor and product string + pair reported by the device via AT commands is found in the list provided by + the plugin, the plugin will report that it can handle this modem. + + + This additional filter should be used when the plugin is + expected to work only with a given specific product of a given vendor. + + + This filter is specified by the MM_PLUGIN_BASE_ALLOWED_PRODUCT_STRINGS + property in the MMPluginBase object provided + by the plugin. + + + + + + + Plugins which require post-probing filters will always be sorted last, and + therefore they will be the last ones being checked for pre-probing filters. This + is due to the fact that we need to assume that these plugins aren't able to + determine port support just with pre-probing filters, as we want to avoid + unnecessary probing sequences launched. Also note that the Generic plugin is + anyway always the last one in the list. + + +
+ +
+ Probing setup examples + + Probing setup for a plugin requiring udev-based vendor/product checks + +G_MODULE_EXPORT MMPlugin * +mm_plugin_create (void) +{ + static const gchar *subsystems[] = { "tty", NULL }; + static const guint16 vendor_ids[] = { 0xabcd, 0 }; + static const mm_uint16_pair product_ids[] = { + { 0x1234, 0xffff } + }; + static const gchar *vendor_strings[] = { "vendor", NULL }; + + return MM_PLUGIN ( + g_object_new (MM_TYPE_PLUGIN_IRIDIUM, + MM_PLUGIN_BASE_NAME, "Example", + + /* Next items are pre-probing filters */ + MM_PLUGIN_BASE_ALLOWED_SUBSYSTEMS, subsystems, + MM_PLUGIN_BASE_ALLOWED_VENDOR_IDS, vendor_ids, + MM_PLUGIN_BASE_ALLOWED_PRODUCT_IDS, product_ids, + + /* Next items are probing sequence setup */ + MM_PLUGIN_BASE_ALLOWED_AT, TRUE, + + /* No post-probing filters */ + NULL)); +} + + + + + Probing setup for a plugin requiring AT-probed vendor/product checks + +G_MODULE_EXPORT MMPlugin * +mm_plugin_create (void) +{ + static const gchar *subsystems[] = { "tty", NULL }; + static const gchar *vendor_strings[] = { "vendor", NULL }; + static const mm_str_pair product_strings[] = { "another-vendor", "product xyz" }; + + return MM_PLUGIN ( + g_object_new (MM_TYPE_PLUGIN_IRIDIUM, + MM_PLUGIN_BASE_NAME, "Example", + + /* Next items are pre-probing filters */ + MM_PLUGIN_BASE_ALLOWED_SUBSYSTEMS, subsystems, + + /* Next items are probing sequence setup */ + MM_PLUGIN_BASE_ALLOWED_AT, TRUE, + + /* Next items are post-probing filters */ + MM_PLUGIN_BASE_VENDOR_STRINGS, vendor_strings, + MM_PLUGIN_BASE_PRODUCT_STRINGS, product_strings, + NULL)); +} + + + + + Probing setup for a plugin with custom initialization requirements + +static gboolean +parse_init (const gchar *response, + const GError *error, + GValue *result, + GError **result_error) +{ + if (error) { + *result_error = g_error_copy (error); + return FALSE; + } + + /* Otherwise, done. And also report that it's an AT port. */ + g_value_init (result, G_TYPE_BOOLEAN); + g_value_set_boolean (result, TRUE); + return TRUE; +} + +static const MMPortProbeAtCommand custom_init[] = { + { "ATE1 E0", parse_init }, + { NULL } +}; + +G_MODULE_EXPORT MMPlugin * +mm_plugin_create (void) +{ + static const gchar *subsystems[] = { "tty", NULL }; + static const guint16 vendor_ids[] = { 0xabcd, 0 }; + + return MM_PLUGIN ( + g_object_new (MM_TYPE_PLUGIN_NOKIA, + MM_PLUGIN_BASE_NAME, "Example", + + /* Next items are pre-probing filters */ + MM_PLUGIN_BASE_ALLOWED_SUBSYSTEMS, subsystems, + MM_PLUGIN_BASE_ALLOWED_VENDOR_IDS, vendor_ids, + + /* Next items are probing sequence setup */ + MM_PLUGIN_BASE_CUSTOM_INIT, custom_init, + MM_PLUGIN_BASE_ALLOWED_AT, TRUE, + + /* No post-probing filters */ + NULL)); +} + + +
+
+ +
+ Port grabbing and Modem object creation + + Once a port passes all probing filters of a given plugin, the plugin will grab + the port. When the first port of a given device is grabbed, the plugin will create + the required Modem object. + + + While preparing to get the Modem object grab the specific port probed, udev-based + port type hints can be used to specify AT port flags (e.g. if a port is to be + considered primary, secondary or for PPP). + +
+ + + + + Modem state machine - ModemManager implements support for each Modem by controlling their - behaviour following the steps given in the following state machine. + Once all ports of a given modem have been probed and grabbed by a newly created + Modem object, ModemManager will start the global state machine for the modem, as + defined in the picture below.
ModemManager states @@ -61,35 +417,228 @@ The state machine of a modem can be summarized in 5 main sequences: initialization, enabling, connection, disconnection and disabling. +
Initialization - + The modem initialization sequence starts only when all ports + have been probed and grabbed by a given plugin. This is done so that the proper + AT port (that suggested to be Primary) is used as control port. + + + The global initialization sequence is itself splitted into N per-interface + initialization steps (being N the number of interfaces implemented by the + modem object). The following list provides the steps required in the + initialization sequence of a Broadband modem object. + + + Modem interface initialization + + The Modem interface + provides common actions and information available in the majority of the modems + (including Broadband-specific items which won't be implemented by POTS modems). + + + One of the key things done during the initialization of this interface is the + checking of supported capabilities. Broadband modem objects + are able to handle 3GPP-only, CDMA-only and mixed 3GPP+CDMA modems, but in order + to properly handle the distinctions required in these, ModemManager first needs + to know exactly which is the current set of capabilities. + + + The other key step in this sequence involves checking the lock status + of the modem and/or SIM . If the modem/SIM is found to be locked, the + whole initialization sequence is halted and the modem is left in a locked state + until unlocked by the user. Note, therefore, that modems that are locked will not + expose additional feature-specific DBus interfaces until they get unlocked. + + + + It may be the case that some of the steps in the initialization of the Modem + interface require the modem itself to be unlocked. If the modem is found locked + during the first initialization attempt, as soon as it gets unlocked the + initialization sequence will be re-executed. + + + + + 3GPP interface initialization + + The 3GPP interface + provides common actions and setup for modems which provide 3GPP capabilities. Therefore, + this interface initialization sequence will only be run in 3GPP-enabled modems. + + + + CDMA interface initialization + + The CDMA interface + provides common actions and setup for modems which provide CDMA capabilities. Therefore, + this interface initialization sequence will only be run in CDMA-enabled modems. + + + + Additional feature-specific interface initializations + + Modems with additional features will export feature-specific interfaces, such as + the Location or + the Messaging + ones. + + + These interfaces also have their own initialization sequences, where the first step + in the sequence is always the check of whether the given modem supports the given feature. + In other words, modems will only end up exporting the interfaces for the features they + support. + + +
+
Enabling - + Modem enabling is the user-requested sequence with the sole purpose of bringing + the modem to a state where it can get connected. -
-
- Connection - + As with the initialization sequence, the global enabling sequence is itself + splitted into N per-interface enabling steps (being N the number of interfaces + exported by the modem). Those interfaces implemented by the object but not + supported by the modem will not be enabled. + + + Modem interface enabling + + The sequence to enable the + Modem interface + takes care of different important steps, such as powering up the + radio interface or configuring the best charset + to use. + + + + 3GPP interface enabling + + Modems with 3GPP capabilities will enable the + 3GPP interface + as part of the global enabling sequence. This sequence involves setting up the + automatic registration of the device in the network, as well + as configuring 3GPP specific indicators and unsolicited message + handlers. + + + + CDMA interface enabling + + Modems with CDMA capabilities will enable the + CDMA interface + as part of the global enabling sequence. This sequence involves setting up the + periodic checks of registration in the CDMA network. + + + + Additional feature-specific interface enablings + + Each feature-specific interface will have its own enabling sequence, with operations + which are directly related to the purpose of the interface. For example, enabling the + Location + interface will involve setting up the initial location information; and enabling the + Messaging + interface will involve loading the initial list of SMS available in the SIM or Modem. + + +
+
- Disconnection + Connection & disconnection - + Connecting the Modem is done through the Bearer objects. Once such an + object is created, the user can request to get the given bearer connected. + + Broadband Modems will usually create Broadband Bearers. This kind of bearers can run either + the CDMA connection sequence (if the modem has CDMA capabilities) or the 3GPP connection + sequence (if the modem has 3GPP capabilities). For the special case of mixed 3GPP+CDMA + modems, it is assumed that the plugin implementation needs to decide how the connection gets + done. By default, anyway, the 3GPP sequence is used in this case. + + + + Modems which are both LTE (3GPP) and CDMA can hand over from LTE to CDMA transparently and + automatically when no LTE network is available, even keeping the same IP address. When this + happens, the modem will get notified about the access technology change, and ModemManager + will update that information. + +
+
Disabling - + Users can disable the modems, which will bring them to a state where they are in low power + mode (e.g. RF switched off) and not registered in any network. + + As with the initialization or enabling sequences, the global disabling sequence is itself + splitted into N per-interface disabling steps (being N the number of interfaces + exported by the modem). Those interfaces implemented by the object but not + supported by the modem will not be disabled. + + + + The global disabling sequence will go on disabling the interfaces one by one, but + starting with the interface which was last enabled during the enabling sequence, and + backwards. This ensures that the + Modem interface + gets disabled last. + + + + + Additional feature-specific interface disablings + + Each feature-specific interface will have its own disabling sequence, with operations + which are directly related to the purpose of the interface. For example, disabling the + Location + interface will involve shutting down the location gathering; and disabling the + Messaging + interface will involve unexporting all SMS objects from DBus. + + + + CDMA interface disabling + + Modems with CDMA capabilities will disable the + CDMA interface + as part of the global disabling sequence. This sequence involves cancelling the + periodic checks of registration in the CDMA network. + + + + 3GPP interface disabling + + Modems with 3GPP capabilities will disable the + 3GPP interface + as part of the global disabling sequence. This sequence involves, among other things, + cleaning up 3GPP specific indicators and unsolicited message handlers. + + + + Modem interface disabling + + The sequence to disable the + Modem interface + takes care of different important steps, such as powering down the + radio interface. + + + +
+ -- cgit v1.2.3-70-g09d2