SymbX/ModemManager
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: document Modem probing and global state machine

Browse Source
This commit is contained in:
Aleksander Morgado
2012-03-16 14:53:18 +01:00
parent 5f85cfc352
commit 36fbfab3e6
1 changed files with 562 additions and 13 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/reference/api/ModemManager-overview.xml
+562 -13
View File
@@ -47,11 +47,367 @@
</formalpara>
</chapter>
<chapter id="ref-overview-states">
<title>State machine</title>
<chapter id="ref-overview-modem-detection-and-setup">
<title>Modem detection and setup</title>
<section>
<title>Detection mechanisms</title>
<para>
ModemManager requires <emphasis>udev</emphasis>-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 <emphasis>ID_MM_CANDIDATE</emphasis> tag in udev. This includes both "tty"
and "net" ports.
</para>
<para>
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.
</para>
</section>
<section>
<title>Probing</title>
<para>
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.
</para>
<para>
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.
</para>
<section>
<title>Pre-probing filters</title>
<para>
Pre-probing filters are those which control whether the probing, as
requested by the specific plugin, takes place.
</para>
<itemizedlist>
<listitem>
<para><emphasis>Allowed vendor IDs</emphasis></para>
<para>
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.
</para>
<para>
This filter is specified by the <type>MM_PLUGIN_BASE_ALLOWED_VENDOR_IDS</type>
property in the <structname>MMPluginBase</structname> object provided
by the plugin.
</para>
</listitem>
<listitem>
<para><emphasis>Allowed product IDs</emphasis></para>
<para>
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.
</para>
<para>
This additional filter should be used when the plugin is
expected to work only with a given specific product of a given vendor.
</para>
<para>
This filter is specified by the <type>MM_PLUGIN_BASE_ALLOWED_PRODUCT_IDS</type>
property in the <structname>MMPluginBase</structname> object provided
by the plugin.
</para>
</listitem>
<listitem>
<para><emphasis>Subsystems</emphasis></para>
<para>
Plugins can specify which subsystems they expect, so that we filter out
any port detected with a subsystem not listed by the plugin.
</para>
<para>
This filter is specified by the <type>MM_PLUGIN_BASE_ALLOWED_SUBSYSTEMS</type>
property in the <structname>MMPluginBase</structname> object provided
by the plugin.
</para>
</listitem>
<listitem>
<para><emphasis>Drivers</emphasis></para>
<para>
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.
</para>
<para>
This filter is specified by the <type>MM_PLUGIN_BASE_ALLOWED_DRIVERS</type>
property in the <structname>MMPluginBase</structname> object provided
by the plugin.
</para>
</listitem>
<listitem>
<para><emphasis>udev tags</emphasis></para>
<para>
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.
</para>
<para>
This filter is specified by the <type>MM_PLUGIN_BASE_ALLOWED_UDEV_TAGS</type>
property in the <structname>MMPluginBase</structname> object provided
by the plugin.
</para>
</listitem>
</itemizedlist>
</section>
<section>
<title>Probing sequence</title>
<para>
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.
</para>
<itemizedlist>
<listitem>
<para><emphasis>Custom AT initialization</emphasis></para>
<para>
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.
</para>
<para>
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.
</para>
<para>
This configuration is specified by the <type>MM_PLUGIN_BASE_CUSTOM_INIT</type>
property in the <structname>MMPluginBase</structname> object provided
by the plugin.
</para>
</listitem>
<listitem>
<para><emphasis>AT Allowed</emphasis></para>
<para>
This boolean property allows plugins to specify that they expect and support
AT serial ports.
</para>
<para>
This configuration is specified by the <type>MM_PLUGIN_BASE_ALLOWED_AT</type>
property in the <structname>MMPluginBase</structname> object provided
by the plugin.
</para>
</listitem>
<listitem>
<para><emphasis>QCDM Allowed</emphasis></para>
<para>
This boolean property allows plugins to specify that they expect and support
QCDM serial ports.
</para>
<para>
This configuration is specified by the <type>MM_PLUGIN_BASE_ALLOWED_QCDM</type>
property in the <structname>MMPluginBase</structname> object provided
by the plugin.
</para>
</listitem>
</itemizedlist>
</section>
<section>
<title>Post-probing filters</title>
<para>
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.
</para>
<itemizedlist>
<listitem>
<para><emphasis>Allowed vendor strings</emphasis></para>
<para>
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.
</para>
<para>
This filter is specified by the <type>MM_PLUGIN_BASE_ALLOWED_VENDOR_STRINGS</type>
property in the <structname>MMPluginBase</structname> object provided
by the plugin.
</para>
</listitem>
<listitem>
<para><emphasis>Allowed product strings</emphasis></para>
<para>
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.
</para>
<para>
This additional filter should be used when the plugin is
expected to work only with a given specific product of a given vendor.
</para>
<para>
This filter is specified by the <type>MM_PLUGIN_BASE_ALLOWED_PRODUCT_STRINGS</type>
property in the <structname>MMPluginBase</structname> object provided
by the plugin.
</para>
</listitem>
</itemizedlist>
<note>
<para>
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.
</para>
</note>
</section>
<section>
<title>Probing setup examples</title>
<example>
<title>Probing setup for a plugin requiring udev-based vendor/product checks</title>
<programlisting>
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));
}
</programlisting>
</example>
<example>
<title>Probing setup for a plugin requiring AT-probed vendor/product checks</title>
<programlisting>
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));
}
</programlisting>
</example>
<example>
<title>Probing setup for a plugin with custom initialization requirements</title>
<programlisting>
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));
}
</programlisting>
</example>
</section>
</section>
<section>
<title>Port grabbing and Modem object creation</title>
<para>
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.
</para>
<para>
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).
</para>
</section>
</chapter>
<chapter id="ref-overview-modem-state-machine">
<title>Modem state machine</title>
<para>
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.
</para>
<figure id="mm-modemmanager-states">
<title>ModemManager states</title>
@@ -61,35 +417,228 @@
The state machine of a modem can be summarized in 5 main sequences:
initialization, enabling, connection, disconnection and disabling.
</para>
<section>
<title>Initialization</title>
<para>
<!-- TODO -->
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.
</para>
<para>
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.
</para>
<itemizedlist>
<listitem>
<emphasis>Modem interface initialization</emphasis>
<para>
The <link linkend="gdbus-org.freedesktop.ModemManager1.Modem">Modem interface</link>
provides common actions and information available in the majority of the modems
(including Broadband-specific items which won't be implemented by POTS modems).
</para>
<para>
One of the key things done during the initialization of this interface is the
<emphasis>checking of supported capabilities</emphasis>. 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.
</para>
<para>
The other key step in this sequence involves <emphasis>checking the lock status
of the modem and/or SIM </emphasis>. 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.
</para>
<note>
<para>
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.
</para>
</note>
</listitem>
<listitem>
<emphasis>3GPP interface initialization</emphasis>
<para>
The <link linkend="gdbus-org.freedesktop.ModemManager1.Modem.Modem3gpp">3GPP interface</link>
provides common actions and setup for modems which provide 3GPP capabilities. Therefore,
this interface initialization sequence will only be run in 3GPP-enabled modems.
</para>
</listitem>
<listitem>
<emphasis>CDMA interface initialization</emphasis>
<para>
The <link linkend="gdbus-org.freedesktop.ModemManager1.Modem.ModemCdma">CDMA interface</link>
provides common actions and setup for modems which provide CDMA capabilities. Therefore,
this interface initialization sequence will only be run in CDMA-enabled modems.
</para>
</listitem>
<listitem>
<para><emphasis>Additional feature-specific interface initializations</emphasis></para>
<para>
Modems with additional features will export feature-specific interfaces, such as
the <link linkend="gdbus-org.freedesktop.ModemManager1.Modem.Location">Location</link> or
the <link linkend="gdbus-org.freedesktop.ModemManager1.Modem.Location">Messaging</link>
ones.
</para>
<para>
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.
</para>
</listitem>
</itemizedlist>
</section>
<section>
<title>Enabling</title>
<para>
<!-- TODO -->
Modem enabling is the user-requested sequence with the sole purpose of bringing
the modem to a state where it can get connected.
</para>
</section>
<section>
<title>Connection</title>
<para>
<!-- TODO -->
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.
</para>
<itemizedlist>
<listitem>
<para><emphasis>Modem interface enabling</emphasis></para>
<para>
The sequence to enable the
<link linkend="gdbus-org.freedesktop.ModemManager1.Modem">Modem interface</link>
takes care of different important steps, such as <emphasis>powering up the
radio interface</emphasis> or <emphasis>configuring</emphasis> the best charset
to use.
</para>
</listitem>
<listitem>
<para><emphasis>3GPP interface enabling</emphasis></para>
<para>
Modems with 3GPP capabilities will enable the
<link linkend="gdbus-org.freedesktop.ModemManager1.Modem.Modem3gpp">3GPP interface</link>
as part of the global enabling sequence. This sequence involves setting up the
<emphasis>automatic registration</emphasis> of the device in the network, as well
as configuring 3GPP specific <emphasis>indicators and unsolicited message
handlers</emphasis>.
</para>
</listitem>
<listitem>
<para><emphasis>CDMA interface enabling</emphasis></para>
<para>
Modems with CDMA capabilities will enable the
<link linkend="gdbus-org.freedesktop.ModemManager1.Modem.ModemCdma">CDMA interface</link>
as part of the global enabling sequence. This sequence involves setting up the
<emphasis>periodic checks of registration</emphasis> in the CDMA network.
</para>
</listitem>
<listitem>
<para><emphasis>Additional feature-specific interface enablings</emphasis></para>
<para>
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
<link linkend="gdbus-org.freedesktop.ModemManager1.Modem.Location">Location</link>
interface will involve setting up the initial location information; and enabling the
<link linkend="gdbus-org.freedesktop.ModemManager1.Modem.Location">Messaging</link>
interface will involve loading the initial list of SMS available in the SIM or Modem.
</para>
</listitem>
</itemizedlist>
</section>
<section>
<title>Disconnection</title>
<title>Connection &amp; disconnection</title>
<para>
<!-- TODO -->
Connecting the Modem is done through the <emphasis>Bearer</emphasis> objects. Once such an
object is created, the user can request to get the given bearer connected.
</para>
<para>
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.
</para>
<note>
<para>
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.
</para>
</note>
</section>
<section>
<title>Disabling</title>
<para>
<!-- TODO -->
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.
</para>
<para>
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.
</para>
<note>
<para>
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
<link linkend="gdbus-org.freedesktop.ModemManager1.Modem">Modem interface</link>
gets disabled last.
</para>
</note>
<itemizedlist>
<listitem>
<para><emphasis>Additional feature-specific interface disablings</emphasis></para>
<para>
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
<link linkend="gdbus-org.freedesktop.ModemManager1.Modem.Location">Location</link>
interface will involve shutting down the location gathering; and disabling the
<link linkend="gdbus-org.freedesktop.ModemManager1.Modem.Location">Messaging</link>
interface will involve unexporting all SMS objects from DBus.
</para>
</listitem>
<listitem>
<para><emphasis>CDMA interface disabling</emphasis></para>
<para>
Modems with CDMA capabilities will disable the
<link linkend="gdbus-org.freedesktop.ModemManager1.Modem.ModemCdma">CDMA interface</link>
as part of the global disabling sequence. This sequence involves cancelling the
<emphasis>periodic checks of registration</emphasis> in the CDMA network.
</para>
</listitem>
<listitem>
<para><emphasis>3GPP interface disabling</emphasis></para>
<para>
Modems with 3GPP capabilities will disable the
<link linkend="gdbus-org.freedesktop.ModemManager1.Modem.Modem3gpp">3GPP interface</link>
as part of the global disabling sequence. This sequence involves, among other things,
cleaning up 3GPP specific <emphasis>indicators and unsolicited message handlers</emphasis>.
</para>
</listitem>
<listitem>
<para><emphasis>Modem interface disabling</emphasis></para>
<para>
The sequence to disable the
<link linkend="gdbus-org.freedesktop.ModemManager1.Modem">Modem interface</link>
takes care of different important steps, such as <emphasis>powering down the
radio interface</emphasis>.
</para>
</listitem>
</itemizedlist>
</section>
</chapter>
</part>