docs: port probing reference in its own chapter

1 files changed, 294 insertions, 295 deletions

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.
       </para>
     </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>
-      <title>Probing</title>
+      <title>Pre-probing filters</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.
+        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>
-        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.
       </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>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>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>
 
-      <section>
-        <title>Probing sequence</title>
+      <note>
         <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.
+          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>
-        <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>
+      </note>
+    </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>
+    <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)
 {
@@ -374,12 +375,12 @@ mm_plugin_create (void)
                       /* No post-probing filters */
                       NULL));
 }
-          </programlisting>
-        </example>
+        </programlisting>
+      </example>
 
-        <example>
-          <title>Probing setup for a plugin requiring AT-probed vendor/product checks</title>
-          <programlisting>
+      <example>
+        <title>Probing setup for a plugin requiring AT-probed vendor/product checks</title>
+        <programlisting>
 G_MODULE_EXPORT MMPlugin *
 mm_plugin_create (void)
 {
@@ -402,12 +403,12 @@ mm_plugin_create (void)
                       MM_PLUGIN_PRODUCT_STRINGS, product_strings,
                       NULL));
 }
-          </programlisting>
-        </example>
+        </programlisting>
+      </example>
 
-        <example>
-          <title>Probing setup for a plugin with custom initialization requirements</title>
-          <programlisting>
+      <example>
+        <title>Probing setup for a plugin with custom initialization requirements</title>
+        <programlisting>
 static gboolean
 parse_custom_at (const gchar *response,
                  const GError *error,
@@ -451,25 +452,23 @@ mm_plugin_create (void)
                       /* 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>
+        </programlisting>
+      </example>
     </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 id="ref-overview-modem-state-machine">