udev: define all generic tags as symbols

This prevents errors due to nasty typos in the strings.

We define all symbols in a single header file that is NOT considered
part of the API, as there is no need for MM clients to know about
these tags code-wise. These tags are only meaningful when associated
to devices in udev.

Information of each tag is included in the general API documentation.

https://gitlab.freedesktop.org/mobile-broadband/ModemManager/issues/88

2 files changed, 211 insertions, 0 deletions

diff --git a/include/Makefile.am b/include/Makefile.am
index 237ee6bde..c0f3117cf 100644
--- a/include/Makefile.am
+++ b/include/Makefile.am
@@ -19,4 +19,5 @@ CLEANFILES = \
 	ModemManager-names.h
 
 EXTRA_DIST = \
+	ModemManager-tags.h \
 	ModemManager-version.h.in
diff --git a/include/ModemManager-tags.h b/include/ModemManager-tags.h
new file mode 100644
index 000000000..4be1e7918
--- /dev/null
+++ b/include/ModemManager-tags.h
@@ -0,0 +1,210 @@
+/* -*- Mode: C; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
+/*
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation; either version 2 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details:
+ *
+ * Copyright (C) 2018 Aleksander Morgado <aleksander@aleksander.es>
+ */
+
+/*
+ * NOTE! this file is NOT part of the installed ModemManager API.
+ *
+ * We keep this file under include/ because we want to build and
+ * expose the associated documentation.
+ */
+
+#ifndef MM_TAGS_H
+#define MM_TAGS_H
+
+/**
+ * SECTION:mm-tags
+ * @short_description: generic udev tags supported
+ *
+ * This section defines generic udev tags that are used by ModemManager,
+ * associated to full devices or to specific ports in a given device.
+ */
+
+/**
+ * ID_MM_CANDIDATE:
+ *
+ * This is a port-specific tag added automatically when all other
+ * ModemManager related tags have already been set.
+ */
+#define ID_MM_CANDIDATE "ID_MM_CANDIDATE"
+
+/**
+ * ID_MM_PHYSDEV_UID:
+ *
+ * This is a device-specific tag that allows users to 'name' modem
+ * devices with a predefined 'unique ID' string.
+ *
+ * When this tag is given per-port, the daemon will consider that all
+ * ports with the same UID value are associated to the same device.
+ * This is useful for e.g. modems that expose multiple RS232 ports
+ * connected to the system via different platform ports (or USB to
+ * RS232 adapters).
+ *
+ * This UID is exposed in
+ * the '<link linkend="gdbus-property-org-freedesktop-ModemManager1-Modem.Device">Device</link>'
+ * property and can then be used in mmcli calls to refer unequivocally
+ * to a specific device, regardless of its modem index, e.g.:
+ *  $ mmcli --modem=UID ...
+ */
+#define ID_MM_PHYSDEV_UID "ID_MM_PHYSDEV_UID"
+
+/**
+ * ID_MM_DEVICE_PROCESS:
+ *
+ * This is a device-specific tag that allows explicitly requesting the
+ * processing of all ports exposed by the device. This tag is usually
+ * used by users when the daemon runs with WHITELIST-ONLY filter policy
+ * type, and is associated to the MM_FILTER_RULE_EXPLICIT_WHITELIST rule.
+ *
+ * This tag may also be specified in specific ports, e.g. when the modem
+ * exposes a single platform port without any parent device.
+ */
+#define ID_MM_DEVICE_PROCESS "ID_MM_DEVICE_PROCESS"
+
+/**
+ * ID_MM_PORT_IGNORE:
+ *
+ * This is a port-specific tag that allows explicitly ignoring a given port
+ * in a device.
+ *
+ * This tag applies to all types of ports.
+ */
+#define ID_MM_PORT_IGNORE "ID_MM_PORT_IGNORE"
+
+/**
+ * ID_MM_DEVICE_IGNORE:
+ *
+ * This is a device-specific tag that allows explicitly blacklisting
+ * devices that expose TTY devices so that they are never probed.
+ *
+ * This tag is used when the daemon runs with DEFAULT or PARANOID
+ * filter policy type, and is associated to the MM_FILTER_RULE_TTY_BLACKLIST
+ * rule.
+ *
+ * This tag is ignored when the STRICT filter policy is used.
+ */
+#define ID_MM_DEVICE_IGNORE "ID_MM_DEVICE_IGNORE"
+
+/**
+ * ID_MM_DEVICE_MANUAL_SCAN_ONLY:
+ *
+ * This is a device-specific tag that allows explicitly greylisting
+ * devices that expose TTY devices so that they are never probed
+ * automatically. Instead, an explicit manual scan request may be sent
+ * to the daemon so that the TTY ports exposed by the device are
+ * probed.
+ *
+ * This tag is used when the daemon runs with DEFAULT or PARANOID
+ * filter policy type, and is associated to the MM_FILTER_RULE_TTY_MANUAL_SCAN_ONLY
+ * rule.
+ *
+ * This tag is ignored when the STRICT filter policy is used.
+ */
+#define ID_MM_DEVICE_MANUAL_SCAN_ONLY "ID_MM_DEVICE_MANUAL_SCAN_ONLY"
+
+/**
+ * ID_MM_PLATFORM_DRIVER_PROBE:
+ *
+ * This is a port-specific tag applied to platform ports so that they
+ * are probed automatically by the daemon. Platform ports that don't
+ * have this tag will never probed. This tag is a bit redundant, as
+ * the user could also use ID_MM_DEVICE_PROCESS for the same purpose.
+ *
+ * This tag is associated to the MM_FILTER_RULE_TTY_PLATFORM_DRIVER
+ * rule, which is only meaningful when the daemon runs with the
+ * DEFAULT filter policy type, as that is the only one that would
+ * allow probing all ports not explicitly forbidden before the last
+ * MM_FILTER_RULE_TTY_DEFAULT_ALLOWED rule.
+ */
+#define ID_MM_PLATFORM_DRIVER_PROBE "ID_MM_PLATFORM_DRIVER_PROBE"
+
+/**
+ * ID_MM_PORT_TYPE_AT_PRIMARY:
+ *
+ * This is a port-specific tag applied to TTYs that we know in advance
+ * are AT ports to be used as primary control ports.
+ *
+ * This tag will also prevent QCDM probing on the port.
+ */
+#define ID_MM_PORT_TYPE_AT_PRIMARY "ID_MM_PORT_TYPE_AT_PRIMARY"
+
+/**
+ * ID_MM_PORT_TYPE_AT_SECONDARY:
+ *
+ * This is a port-specific tag applied to TTYs that we know in advance
+ * are AT ports to be used as secondary control ports.
+ *
+ * This tag will also prevent QCDM probing on the port.
+ */
+#define ID_MM_PORT_TYPE_AT_SECONDARY "ID_MM_PORT_TYPE_AT_SECONDARY"
+
+/**
+ * ID_MM_PORT_TYPE_AT_PPP:
+ *
+ * This is a port-specific tag applied to TTYs that we know in advance
+ * are AT ports to be used as data ports exclusively.
+ *
+ * This tag will also prevent QCDM probing on the port.
+ */
+#define ID_MM_PORT_TYPE_AT_PPP "ID_MM_PORT_TYPE_AT_PPP"
+
+/**
+ * ID_MM_PORT_TYPE_QCDM:
+ *
+ * This is a port-specific tag applied to TTYs that we know in advance
+ * are QCDM ports.
+ *
+ * The only purpose of this tag is to prevent AT probing in the port.
+ */
+#define ID_MM_PORT_TYPE_QCDM "ID_MM_PORT_TYPE_QCDM"
+
+/**
+ * ID_MM_PORT_TYPE_GPS:
+ *
+ * This is a port-specific tag applied to TTYs that we know in advance
+ * are GPS data ports where we expect to receive NMEA traces.
+ *
+ * This tag also prevents AT and QCDM probing in the port.
+ */
+#define ID_MM_PORT_TYPE_GPS "ID_MM_PORT_TYPE_GPS"
+
+/**
+ * ID_MM_TTY_BAUDRATE:
+ *
+ * This is a port-specific tag applied to TTYs that require a specific
+ * baudrate to work. USB modems will usually allow auto-bauding
+ * configuration, so this tag is really only meaningful to true RS232
+ * devices.
+ *
+ * The value of the tag should be the number of bauds per second to
+ * use when talking to the port, e.g. "115200". If not given, the
+ * default of 57600bps is assumed.
+ */
+#define ID_MM_TTY_BAUDRATE "ID_MM_TTY_BAUDRATE"
+
+/**
+ * ID_MM_TTY_FLOW_CONTROL:
+ *
+ * This is a port-specific tag applied to TTYs that require a specific
+ * flow control mechanism to work not only in data mode but also in
+ * control mode.
+ *
+ * The value of the tag should be either 'none', 'xon-xoff' or
+ * 'rts-cts', and must be a flow control value supported by the device
+ * where it's configured. If not given, it is assumed that the TTYs
+ * don't require any specific flow control setting in command mode.
+ */
+#define ID_MM_TTY_FLOW_CONTROL "ID_MM_TTY_FLOW_CONTROL"
+
+#endif /* MM_TAGS_H */