From 42f4e975c9a22ecde9f4971e014358238dcfe975 Mon Sep 17 00:00:00 2001 From: Aleksander Morgado Date: Tue, 17 Oct 2017 14:42:26 +0200 Subject: docs: port probing reference in its own chapter --- docs/reference/api/ModemManager-overview.xml | 589 +++++++++++++-------------- 1 file changed, 294 insertions(+), 295 deletions(-) (limited to 'docs/reference') 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. + + + 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 - 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. + 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. + + + +
-
- 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. - - - -
+
+ 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. + + + -
- 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. + 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. - - - 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 - +
+ 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). + -- cgit v1.2.3-70-g09d2