docs: port probing reference in its own chapter
This commit is contained in:
Aleksander Morgado
@@ -70,285 +70,286 @@
|
|||||||
connected, not about the RS232 modem connected to the adapter, if any.
|
connected, not about the RS232 modem connected to the adapter, if any.
|
||||||
</para>
|
</para>
|
||||||
</section>
|
</section>
|
||||||
|
</chapter>
|
||||||
|
|
||||||
|
<chapter id="ref-overview-modem-port-probing">
|
||||||
|
<title>Port 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>
|
<section>
|
||||||
<title>Probing</title>
|
<title>Pre-probing filters</title>
|
||||||
<para>
|
<para>
|
||||||
Whenever a new device is detected by ModemManager, port probing process will
|
Pre-probing filters are those which control whether the probing, as
|
||||||
get started, so that we can determine which kind of ports we have, and also
|
requested by the specific plugin, takes place.
|
||||||
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>
|
||||||
<para>
|
<itemizedlist>
|
||||||
The whole probing process, including pre-probing and post-probing filters, is
|
<listitem>
|
||||||
implemented in the core ModemManager daemon. Plugins will just configure their
|
<para><emphasis>Allowed vendor IDs</emphasis></para>
|
||||||
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_ALLOWED_VENDOR_IDS</type>
|
|
||||||
property in the <structname>MMPlugin</structname> object provided
|
|
||||||
by the plugin.
|
|
||||||
</para>
|
|
||||||
</listitem>
|
|
||||||
<listitem>
|
|
||||||
<para><emphasis>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.
|
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
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.
|
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
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.
|
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
These filters are specified by the <type>MM_PLUGIN_ALLOWED_PRODUCT_IDS</type>
|
|
||||||
and <type>MM_PLUGIN_FORBIDDEN_PRODUCT_IDS</type> properties in the
|
|
||||||
<structname>MMPlugin</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_ALLOWED_SUBSYSTEMS</type>
|
|
||||||
property in the <structname>MMPlugin</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>
|
|
||||||
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.
|
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
These filters are specified by the <type>MM_PLUGIN_ALLOWED_DRIVERS</type>
|
|
||||||
and <type>MM_PLUGIN_FORBIDDEN_DRIVERS</type> properties in the
|
|
||||||
<structname>MMPlugin</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_ALLOWED_UDEV_TAGS</type>
|
|
||||||
property in the <structname>MMPlugin</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 initialization</emphasis></para>
|
|
||||||
<para>
|
|
||||||
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.
|
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
This configuration is specified by the <type>MM_PLUGIN_CUSTOM_INIT</type>
|
|
||||||
property in the <structname>MMPlugin</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_ALLOWED_AT</type>
|
|
||||||
property in the <structname>MMPlugin</structname> object provided
|
|
||||||
by the plugin.
|
|
||||||
</para>
|
|
||||||
</listitem>
|
|
||||||
<listitem>
|
|
||||||
<para><emphasis>Single AT expected</emphasis></para>
|
|
||||||
<para>
|
|
||||||
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.
|
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
This configuration is specified by the <type>MM_PLUGIN_ALLOWED_SINGLE_AT</type>
|
|
||||||
property in the <structname>MMPlugin</structname> object provided
|
|
||||||
by the plugin.
|
|
||||||
</para>
|
|
||||||
</listitem>
|
|
||||||
<listitem>
|
|
||||||
<para><emphasis>Custom AT probing</emphasis></para>
|
|
||||||
<para>
|
|
||||||
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.
|
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
This configuration is specified by the <type>MM_PLUGIN_CUSTOM_AT_PROBE</type>
|
|
||||||
property in the <structname>MMPlugin</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_ALLOWED_QCDM</type>
|
|
||||||
property in the <structname>MMPlugin</structname> object provided
|
|
||||||
by the plugin.
|
|
||||||
</para>
|
|
||||||
</listitem>
|
|
||||||
<listitem>
|
|
||||||
<para><emphasis>Check Icera support</emphasis></para>
|
|
||||||
<para>
|
|
||||||
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.
|
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
This configuration is specified by the <type>MM_PLUGIN_ICERA_PROBE</type>
|
|
||||||
property in the <structname>MMPlugin</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_ALLOWED_VENDOR_STRINGS</type>
|
|
||||||
property in the <structname>MMPlugin</structname> object provided
|
|
||||||
by the plugin.
|
|
||||||
</para>
|
|
||||||
</listitem>
|
|
||||||
<listitem>
|
|
||||||
<para><emphasis>Product strings</emphasis></para>
|
|
||||||
<para>
|
|
||||||
Plugins can provide a list of pairs of vendor and product
|
|
||||||
strings to be used as post-probing filters.
|
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
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.
|
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
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.
|
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
These filters are specified by the <type>MM_PLUGIN_ALLOWED_PRODUCT_STRINGS</type>
|
|
||||||
and <type>MM_PLUGIN_FORBIDDEN_PRODUCT_STRINGS</type> properties in the
|
|
||||||
<structname>MMPlugin</structname> object provided by the plugin.
|
|
||||||
</para>
|
|
||||||
</listitem>
|
|
||||||
<listitem>
|
|
||||||
<para><emphasis>Icera support</emphasis></para>
|
|
||||||
<para>
|
|
||||||
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.
|
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
This filter is specified by the <type>MM_PLUGIN_ALLOWED_ICERA</type> and
|
|
||||||
<type>MM_PLUGIN_FORBIDDEN_ICERA</type> properties in the
|
|
||||||
<structname>MMPlugin</structname> object provided by the plugin.
|
|
||||||
</para>
|
|
||||||
</listitem>
|
|
||||||
</itemizedlist>
|
|
||||||
|
|
||||||
<note>
|
|
||||||
<para>
|
<para>
|
||||||
Plugins which require post-probing filters will always be sorted last, and
|
Plugins can provide a list of udev-reported vendor IDs to be used as
|
||||||
therefore they will be the last ones being checked for pre-probing filters. This
|
pre-probing filters. If the vendor ID reported by the device via udev
|
||||||
is due to the fact that we need to assume that these plugins aren't able to
|
is found in the list provided by the plugin, port probing will be
|
||||||
determine port support just with pre-probing filters, as we want to avoid
|
launched as requested by the given plugin.
|
||||||
unnecessary probing sequences launched. Also note that the Generic plugin is
|
|
||||||
anyway always the last one in the list.
|
|
||||||
</para>
|
</para>
|
||||||
</note>
|
<para>
|
||||||
</section>
|
This filter is specified by the <type>MM_PLUGIN_ALLOWED_VENDOR_IDS</type>
|
||||||
|
property in the <structname>MMPlugin</structname> object provided
|
||||||
|
by the plugin.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
<listitem>
|
||||||
|
<para><emphasis>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.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
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.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
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.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
These filters are specified by the <type>MM_PLUGIN_ALLOWED_PRODUCT_IDS</type>
|
||||||
|
and <type>MM_PLUGIN_FORBIDDEN_PRODUCT_IDS</type> properties in the
|
||||||
|
<structname>MMPlugin</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_ALLOWED_SUBSYSTEMS</type>
|
||||||
|
property in the <structname>MMPlugin</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>
|
||||||
|
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.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
These filters are specified by the <type>MM_PLUGIN_ALLOWED_DRIVERS</type>
|
||||||
|
and <type>MM_PLUGIN_FORBIDDEN_DRIVERS</type> properties in the
|
||||||
|
<structname>MMPlugin</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_ALLOWED_UDEV_TAGS</type>
|
||||||
|
property in the <structname>MMPlugin</structname> object provided
|
||||||
|
by the plugin.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
</itemizedlist>
|
||||||
|
</section>
|
||||||
|
|
||||||
<section>
|
<section>
|
||||||
<title>Probing setup examples</title>
|
<title>Probing sequence</title>
|
||||||
<example>
|
<para>
|
||||||
<title>Probing setup for a plugin requiring udev-based vendor/product checks</title>
|
Whenever all pre-probing filters of a given plugin pass, ModemManager will run
|
||||||
<programlisting>
|
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 initialization</emphasis></para>
|
||||||
|
<para>
|
||||||
|
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.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
This configuration is specified by the <type>MM_PLUGIN_CUSTOM_INIT</type>
|
||||||
|
property in the <structname>MMPlugin</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_ALLOWED_AT</type>
|
||||||
|
property in the <structname>MMPlugin</structname> object provided
|
||||||
|
by the plugin.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
<listitem>
|
||||||
|
<para><emphasis>Single AT expected</emphasis></para>
|
||||||
|
<para>
|
||||||
|
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.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
This configuration is specified by the <type>MM_PLUGIN_ALLOWED_SINGLE_AT</type>
|
||||||
|
property in the <structname>MMPlugin</structname> object provided
|
||||||
|
by the plugin.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
<listitem>
|
||||||
|
<para><emphasis>Custom AT probing</emphasis></para>
|
||||||
|
<para>
|
||||||
|
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.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
This configuration is specified by the <type>MM_PLUGIN_CUSTOM_AT_PROBE</type>
|
||||||
|
property in the <structname>MMPlugin</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_ALLOWED_QCDM</type>
|
||||||
|
property in the <structname>MMPlugin</structname> object provided
|
||||||
|
by the plugin.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
<listitem>
|
||||||
|
<para><emphasis>Check Icera support</emphasis></para>
|
||||||
|
<para>
|
||||||
|
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.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
This configuration is specified by the <type>MM_PLUGIN_ICERA_PROBE</type>
|
||||||
|
property in the <structname>MMPlugin</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_ALLOWED_VENDOR_STRINGS</type>
|
||||||
|
property in the <structname>MMPlugin</structname> object provided
|
||||||
|
by the plugin.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
<listitem>
|
||||||
|
<para><emphasis>Product strings</emphasis></para>
|
||||||
|
<para>
|
||||||
|
Plugins can provide a list of pairs of vendor and product
|
||||||
|
strings to be used as post-probing filters.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
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.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
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.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
These filters are specified by the <type>MM_PLUGIN_ALLOWED_PRODUCT_STRINGS</type>
|
||||||
|
and <type>MM_PLUGIN_FORBIDDEN_PRODUCT_STRINGS</type> properties in the
|
||||||
|
<structname>MMPlugin</structname> object provided by the plugin.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
<listitem>
|
||||||
|
<para><emphasis>Icera support</emphasis></para>
|
||||||
|
<para>
|
||||||
|
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.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
This filter is specified by the <type>MM_PLUGIN_ALLOWED_ICERA</type> and
|
||||||
|
<type>MM_PLUGIN_FORBIDDEN_ICERA</type> properties in the
|
||||||
|
<structname>MMPlugin</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 *
|
G_MODULE_EXPORT MMPlugin *
|
||||||
mm_plugin_create (void)
|
mm_plugin_create (void)
|
||||||
{
|
{
|
||||||
@@ -374,12 +375,12 @@ mm_plugin_create (void)
|
|||||||
/* No post-probing filters */
|
/* No post-probing filters */
|
||||||
NULL));
|
NULL));
|
||||||
}
|
}
|
||||||
</programlisting>
|
</programlisting>
|
||||||
</example>
|
</example>
|
||||||
|
|
||||||
<example>
|
<example>
|
||||||
<title>Probing setup for a plugin requiring AT-probed vendor/product checks</title>
|
<title>Probing setup for a plugin requiring AT-probed vendor/product checks</title>
|
||||||
<programlisting>
|
<programlisting>
|
||||||
G_MODULE_EXPORT MMPlugin *
|
G_MODULE_EXPORT MMPlugin *
|
||||||
mm_plugin_create (void)
|
mm_plugin_create (void)
|
||||||
{
|
{
|
||||||
@@ -402,12 +403,12 @@ mm_plugin_create (void)
|
|||||||
MM_PLUGIN_PRODUCT_STRINGS, product_strings,
|
MM_PLUGIN_PRODUCT_STRINGS, product_strings,
|
||||||
NULL));
|
NULL));
|
||||||
}
|
}
|
||||||
</programlisting>
|
</programlisting>
|
||||||
</example>
|
</example>
|
||||||
|
|
||||||
<example>
|
<example>
|
||||||
<title>Probing setup for a plugin with custom initialization requirements</title>
|
<title>Probing setup for a plugin with custom initialization requirements</title>
|
||||||
<programlisting>
|
<programlisting>
|
||||||
static gboolean
|
static gboolean
|
||||||
parse_custom_at (const gchar *response,
|
parse_custom_at (const gchar *response,
|
||||||
const GError *error,
|
const GError *error,
|
||||||
@@ -451,25 +452,23 @@ mm_plugin_create (void)
|
|||||||
/* No post-probing filters */
|
/* No post-probing filters */
|
||||||
NULL));
|
NULL));
|
||||||
}
|
}
|
||||||
</programlisting>
|
</programlisting>
|
||||||
</example>
|
</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>
|
</section>
|
||||||
|
</chapter>
|
||||||
|
|
||||||
|
<chapter id="ref-overview-modem-object-creation">
|
||||||
|
<title>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>
|
||||||
</chapter>
|
</chapter>
|
||||||
|
|
||||||
<chapter id="ref-overview-modem-state-machine">
|
<chapter id="ref-overview-modem-state-machine">
|
||||||
|
|||||||
Reference in New Issue
Block a user