diff --git a/docs/reference/api/ModemManager-overview.xml b/docs/reference/api/ModemManager-overview.xml
index d55beef9..fcd9d625 100644
--- a/docs/reference/api/ModemManager-overview.xml
+++ b/docs/reference/api/ModemManager-overview.xml
@@ -70,285 +70,286 @@
connected, not about the RS232 modem connected to the adapter, if any.
+
+
+
+ Port 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.
+
- Probing
+ Pre-probing filters
- 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.
+ Pre-probing filters are those which control whether the probing, as
+ requested by the specific plugin, takes place.
-
- 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_ALLOWED_VENDOR_IDS
- property in the MMPlugin object provided
- by the plugin.
-
-
-
- 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 of 'allowed' pairs 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.
-
-
- If the vendor ID and product ID pair reported by the device via udev is
- found in the list of 'forbidden' pairs provided by the plugin, port probing
- will not be launched by this plugin. This additional filter
- should be used when the plugin supports all devices of a given vendor
- except for some specific ones.
-
-
- These filters are specified by the MM_PLUGIN_ALLOWED_PRODUCT_IDS
- and MM_PLUGIN_FORBIDDEN_PRODUCT_IDS properties in the
- MMPlugin 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_ALLOWED_SUBSYSTEMS
- property in the MMPlugin 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.
-
-
- Plugins can also specify which drivers they do not expect, so that we
- filter out any port detected being managed by a driver listed by the plugin.
-
-
- These filters are specified by the MM_PLUGIN_ALLOWED_DRIVERS
- and MM_PLUGIN_FORBIDDEN_DRIVERS properties in the
- MMPlugin 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_ALLOWED_UDEV_TAGS
- property in the MMPlugin 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 initialization
-
- This property allows plugins to provide an asynchronous method which will get
- executed as soon as the AT port gets opened. This method may be used for any
- purpose, like running an early command in the ports as soon as possible, or
- querying the modem for info about the port layout.
-
-
- This configuration is specified by the MM_PLUGIN_CUSTOM_INIT
- property in the MMPlugin 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_ALLOWED_AT
- property in the MMPlugin object provided
- by the plugin.
-
-
-
- Single AT expected
-
- This boolean property allows plugins to specify that they only expect and support
- one AT serial port. Whenever the first AT port is grabbed, any remaining AT probing
- in ports of the same device will get cancelled.
-
-
- This configuration is specified by the MM_PLUGIN_ALLOWED_SINGLE_AT
- property in the MMPlugin object provided
- by the plugin.
-
-
-
- Custom AT probing
-
- This property allows plugins to specify custom commands to check whether a port
- is AT or not. By default, the 'AT' command will be used if no custom one specified.
-
-
- This configuration is specified by the MM_PLUGIN_CUSTOM_AT_PROBE
- property in the MMPlugin 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_ALLOWED_QCDM
- property in the MMPlugin object provided
- by the plugin.
-
-
-
- Check Icera support
-
- This boolean property allows plugins to specify that they want to have the Icera
- support checks included in the probing sequence. They can afterwards get the result
- of the support check to decide whether they want to create a Icera-based modem
- object or not.
-
-
- This configuration is specified by the MM_PLUGIN_ICERA_PROBE
- property in the MMPlugin 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_ALLOWED_VENDOR_STRINGS
- property in the MMPlugin object provided
- by the plugin.
-
-
-
- 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 'allowed' 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.
-
-
- If the vendor and product string pair reported by the device via AT
- commands is found in the 'forbidden list provided by the plugin, the
- plugin will report that it cannot handle this modem. This additional filter
- should be used when the plugin supports all devices of a given vendor, except for some specific ones.
-
-
- These filters are specified by the MM_PLUGIN_ALLOWED_PRODUCT_STRINGS
- and MM_PLUGIN_FORBIDDEN_PRODUCT_STRINGS properties in the
- MMPlugin object provided by the plugin.
-
-
-
- Icera support
-
- Plugins can specify that they only support Icera-based modems, or that they
- do not support any Icera-based modem. When either of this configurations is
- enabled, the Icera support checks will be included in the
- probing sequence, and the result of the check will help to determine whether
- the plugin supports the modem or not.
-
-
- This filter is specified by the MM_PLUGIN_ALLOWED_ICERA and
- MM_PLUGIN_FORBIDDEN_ICERA properties in the
- MMPlugin object provided by the plugin.
-
-
-
-
-
+
+
+ Allowed vendor IDs
- 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.
+ 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_ALLOWED_VENDOR_IDS
+ property in the MMPlugin object provided
+ by the plugin.
+
+
+
+ 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 of 'allowed' pairs 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.
+
+
+ If the vendor ID and product ID pair reported by the device via udev is
+ found in the list of 'forbidden' pairs provided by the plugin, port probing
+ will not be launched by this plugin. This additional filter
+ should be used when the plugin supports all devices of a given vendor
+ except for some specific ones.
+
+
+ These filters are specified by the MM_PLUGIN_ALLOWED_PRODUCT_IDS
+ and MM_PLUGIN_FORBIDDEN_PRODUCT_IDS properties in the
+ MMPlugin 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_ALLOWED_SUBSYSTEMS
+ property in the MMPlugin 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.
+
+
+ Plugins can also specify which drivers they do not expect, so that we
+ filter out any port detected being managed by a driver listed by the plugin.
+
+
+ These filters are specified by the MM_PLUGIN_ALLOWED_DRIVERS
+ and MM_PLUGIN_FORBIDDEN_DRIVERS properties in the
+ MMPlugin 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_ALLOWED_UDEV_TAGS
+ property in the MMPlugin object provided
+ by the plugin.
+
+
+
+
-
- Probing setup examples
-
- Probing setup for a plugin requiring udev-based vendor/product checks
-
+
+ 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 initialization
+
+ This property allows plugins to provide an asynchronous method which will get
+ executed as soon as the AT port gets opened. This method may be used for any
+ purpose, like running an early command in the ports as soon as possible, or
+ querying the modem for info about the port layout.
+
+
+ This configuration is specified by the MM_PLUGIN_CUSTOM_INIT
+ property in the MMPlugin 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_ALLOWED_AT
+ property in the MMPlugin object provided
+ by the plugin.
+
+
+
+ Single AT expected
+
+ This boolean property allows plugins to specify that they only expect and support
+ one AT serial port. Whenever the first AT port is grabbed, any remaining AT probing
+ in ports of the same device will get cancelled.
+
+
+ This configuration is specified by the MM_PLUGIN_ALLOWED_SINGLE_AT
+ property in the MMPlugin object provided
+ by the plugin.
+
+
+
+ Custom AT probing
+
+ This property allows plugins to specify custom commands to check whether a port
+ is AT or not. By default, the 'AT' command will be used if no custom one specified.
+
+
+ This configuration is specified by the MM_PLUGIN_CUSTOM_AT_PROBE
+ property in the MMPlugin 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_ALLOWED_QCDM
+ property in the MMPlugin object provided
+ by the plugin.
+
+
+
+ Check Icera support
+
+ This boolean property allows plugins to specify that they want to have the Icera
+ support checks included in the probing sequence. They can afterwards get the result
+ of the support check to decide whether they want to create a Icera-based modem
+ object or not.
+
+
+ This configuration is specified by the MM_PLUGIN_ICERA_PROBE
+ property in the MMPlugin 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_ALLOWED_VENDOR_STRINGS
+ property in the MMPlugin object provided
+ by the plugin.
+
+
+
+ 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 'allowed' 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.
+
+
+ If the vendor and product string pair reported by the device via AT
+ commands is found in the 'forbidden list provided by the plugin, the
+ plugin will report that it cannot handle this modem. This additional filter
+ should be used when the plugin supports all devices of a given vendor, except for some specific ones.
+
+
+ These filters are specified by the MM_PLUGIN_ALLOWED_PRODUCT_STRINGS
+ and MM_PLUGIN_FORBIDDEN_PRODUCT_STRINGS properties in the
+ MMPlugin object provided by the plugin.
+
+
+
+ Icera support
+
+ Plugins can specify that they only support Icera-based modems, or that they
+ do not support any Icera-based modem. When either of this configurations is
+ enabled, the Icera support checks will be included in the
+ probing sequence, and the result of the check will help to determine whether
+ the plugin supports the modem or not.
+
+
+ This filter is specified by the MM_PLUGIN_ALLOWED_ICERA and
+ MM_PLUGIN_FORBIDDEN_ICERA properties in the
+ MMPlugin 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)
{
@@ -374,12 +375,12 @@ mm_plugin_create (void)
/* No post-probing filters */
NULL));
}
-
-
+
+
-
- Probing setup for a plugin requiring AT-probed vendor/product checks
-
+
+ Probing setup for a plugin requiring AT-probed vendor/product checks
+
G_MODULE_EXPORT MMPlugin *
mm_plugin_create (void)
{
@@ -402,12 +403,12 @@ mm_plugin_create (void)
MM_PLUGIN_PRODUCT_STRINGS, product_strings,
NULL));
}
-
-
+
+
-
- Probing setup for a plugin with custom initialization requirements
-
+
+ Probing setup for a plugin with custom initialization requirements
+
static gboolean
parse_custom_at (const gchar *response,
const GError *error,
@@ -451,25 +452,23 @@ mm_plugin_create (void)
/* 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 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).
+