From 250639e3da531dd91a99950614f95b7227bc84c0 Mon Sep 17 00:00:00 2001
From: Aleksander Morgado <aleksander@aleksander.es>
Date: Wed, 7 Aug 2019 14:35:31 +0200
Subject: udev: repurpose ID_MM_DEVICE_IGNORE and new
 MM_FILTER_RULE_EXPLICIT_BLACKLIST

Until now the ID_MM_DEVICE_IGNORE udev tag was being used in the
internal blacklist of devices shipped by ModemManager when running in
either DEFAULT or PARANOID filter modes. The name of the tag is
extremely misleading because it doesn't really make the full device be
ignored, the tag only applied to TTY ports.

This commit repurposes the tag so that it applies to ANY kind of
port (e.g. TTY, NET, cdc-wdm...) and also to any kind of filter type
(i.e. also applicable in STRICT mode).

The internal blacklist shipped by ModemManager, which should NOT be
used in STRICT mode, uses a new tag name, ID_MM_TTY_BLACKLIST.

The new ID_MM_DEVICE_IGNORE tag is therefore much more usable and its
name is really meaningful. If there are users or third-party projects
adding their own udev rules with the ID_MM_DEVICE_IGNORE tag name,
they should have no problem as the new rule is more restrictive than
the old one.
---
 docs/reference/api/ModemManager-overview.xml | 23 ++++++++++++++++++++++-
 docs/reference/api/ModemManager-sections.txt |  3 ++-
 2 files changed, 24 insertions(+), 2 deletions(-)

(limited to 'docs/reference')

diff --git a/docs/reference/api/ModemManager-overview.xml b/docs/reference/api/ModemManager-overview.xml
index 963c0df2..f9d8dc22 100644
--- a/docs/reference/api/ModemManager-overview.xml
+++ b/docs/reference/api/ModemManager-overview.xml
@@ -121,6 +121,24 @@ $ sudo vim /lib/udev/rules.d/78-mm-whitelist-internal-modem.rules
     LABEL="mm_whitelist_internal_modem_end"
 // Apply new rules without reboot
 $ sudo udevadm control --reload
+$ sudo udevadm trigger
+            </programlisting>
+          </listitem>
+          <listitem>
+            <para><emphasis>MM_FILTER_RULE_EXPLICIT_BLACKLIST</emphasis></para>
+            <para>
+              This filter allows users to manually tag devices and/or device ports with the
+              <emphasis>ID_MM_DEVICE_IGNORE</emphasis> udev tag. If the filter finds this tag,
+              the device and/or device ports will be automatically ignored and port probing
+              will be never run on them.
+            </para>
+            <programlisting>
+$ sudo vim /lib/udev/rules.d/78-mm-blacklist-internal-modem.rules
+    ACTION!="add|change|move", GOTO="mm_blacklist_internal_modem_end"
+    ATTRS{idVendor}=="1199", ATTRS{idProduct}=="a001", ENV{ID_MM_DEVICE_IGNORE}="1"
+    LABEL="mm_blacklist_internal_modem_end"
+// Apply new rules without reboot
+$ sudo udevadm control --reload
 $ sudo udevadm trigger
             </programlisting>
           </listitem>
@@ -167,7 +185,7 @@ $ sudo udevadm trigger
             <para><emphasis>MM_FILTER_RULE_TTY_BLACKLIST</emphasis></para>
             <para>
               This filter will not allow probing any of the devices flagged as
-              <emphasis>ID_MM_DEVICE_IGNORE</emphasis>, like the ones in the default blacklist
+              <emphasis>ID_MM_TTY_BLACKLIST</emphasis>, like the ones in the default blacklist
               shipped by ModemManager.
             </para>
           </listitem>
@@ -239,6 +257,7 @@ $ sudo udevadm trigger
               This is a policy where the following rules are enabled:
               <itemizedlist>
                 <listitem>MM_FILTER_RULE_EXPLICIT_WHITELIST</listitem>
+                <listitem>MM_FILTER_RULE_EXPLICIT_BLACKLIST</listitem>
                 <listitem>MM_FILTER_RULE_VIRTUAL</listitem>
                 <listitem>MM_FILTER_RULE_NET</listitem>
                 <listitem>MM_FILTER_RULE_CDC_WDM</listitem>
@@ -264,6 +283,7 @@ $ sudo udevadm trigger
               This is a policy where the following rules are enabled:
               <itemizedlist>
                 <listitem>MM_FILTER_RULE_EXPLICIT_WHITELIST</listitem>
+                <listitem>MM_FILTER_RULE_EXPLICIT_BLACKLIST</listitem>
                 <listitem>MM_FILTER_RULE_VIRTUAL</listitem>
                 <listitem>MM_FILTER_RULE_NET</listitem>
                 <listitem>MM_FILTER_RULE_CDC_WDM</listitem>
@@ -290,6 +310,7 @@ $ sudo udevadm trigger
               This policy is a mix of the Default and Strict ones:
               <itemizedlist>
                 <listitem>MM_FILTER_RULE_EXPLICIT_WHITELIST</listitem>
+                <listitem>MM_FILTER_RULE_EXPLICIT_BLACKLIST</listitem>
                 <listitem>MM_FILTER_RULE_VIRTUAL</listitem>
                 <listitem>MM_FILTER_RULE_NET</listitem>
                 <listitem>MM_FILTER_RULE_CDC_WDM</listitem>
diff --git a/docs/reference/api/ModemManager-sections.txt b/docs/reference/api/ModemManager-sections.txt
index 577da27e..cdefe11d 100644
--- a/docs/reference/api/ModemManager-sections.txt
+++ b/docs/reference/api/ModemManager-sections.txt
@@ -151,9 +151,10 @@ MM_DEPRECATED
 <TITLE>Common udev tags</TITLE>
 ID_MM_CANDIDATE
 ID_MM_PHYSDEV_UID
-ID_MM_PORT_IGNORE
 ID_MM_DEVICE_PROCESS
 ID_MM_DEVICE_IGNORE
+ID_MM_PORT_IGNORE
+ID_MM_TTY_BLACKLIST
 ID_MM_DEVICE_MANUAL_SCAN_ONLY
 ID_MM_PLATFORM_DRIVER_PROBE
 ID_MM_PORT_TYPE_AT_PPP
-- 
cgit v1.2.3-70-g09d2