diff options
author | Aleksander Morgado <aleksander@aleksander.es> | 2018-09-13 11:47:10 +0200 |
---|---|---|
committer | Dan Williams <dcbw@redhat.com> | 2018-09-25 17:55:53 +0000 |
commit | 2a1a0b88fbaafbe3862e1b9130a9a484e84d752f (patch) | |
tree | 0619d8f967e7dd3ea03a729a682679fe28e8fef3 | |
parent | a2705abb247f0f141d41ad8f34d99ce6133073af (diff) | |
download | ModemManager-2a1a0b88fbaafbe3862e1b9130a9a484e84d752f.tar.gz |
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
-rw-r--r-- | docs/reference/api/ModemManager-docs.xml | 6 | ||||
-rw-r--r-- | docs/reference/api/ModemManager-sections.txt | 19 | ||||
-rw-r--r-- | include/Makefile.am | 1 | ||||
-rw-r--r-- | include/ModemManager-tags.h | 210 | ||||
-rw-r--r-- | src/kerneldevice/mm-kernel-device-generic.c | 4 | ||||
-rw-r--r-- | src/kerneldevice/mm-kernel-device-udev.c | 4 | ||||
-rw-r--r-- | src/mm-base-manager.c | 6 | ||||
-rw-r--r-- | src/mm-base-modem.c | 14 | ||||
-rw-r--r-- | src/mm-filter.c | 13 | ||||
-rw-r--r-- | src/mm-port-probe.c | 20 |
10 files changed, 273 insertions, 24 deletions
diff --git a/docs/reference/api/ModemManager-docs.xml b/docs/reference/api/ModemManager-docs.xml index 57e333843..156b6ff6d 100644 --- a/docs/reference/api/ModemManager-docs.xml +++ b/docs/reference/api/ModemManager-docs.xml @@ -49,6 +49,7 @@ <year>2015</year> <year>2016</year> <year>2017</year> + <year>2018</year> <holder>The ModemManager Authors</holder> </copyright> @@ -84,6 +85,11 @@ <xi:include href="xml/mm-errors.xml"/> </part> + <part id="ref-udev"> + <title>Common udev tag definitions</title> + <xi:include href="xml/mm-tags.xml"/> + </part> + <!-- Part 2, DBus reference --> <xi:include href="xml/ModemManager-dbus-reference.xml"/> diff --git a/docs/reference/api/ModemManager-sections.txt b/docs/reference/api/ModemManager-sections.txt index 5ec728db8..6da6a3360 100644 --- a/docs/reference/api/ModemManager-sections.txt +++ b/docs/reference/api/ModemManager-sections.txt @@ -140,3 +140,22 @@ MM_MODEM_BAND_CDMA_BC19_US_LOWER_700 <SUBSECTION Private> MMModemBandDeprecated </SECTION> + +<SECTION> +<FILE>mm-tags</FILE> +<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_DEVICE_MANUAL_SCAN_ONLY +ID_MM_PLATFORM_DRIVER_PROBE +ID_MM_PORT_TYPE_AT_PPP +ID_MM_PORT_TYPE_AT_PRIMARY +ID_MM_PORT_TYPE_AT_SECONDARY +ID_MM_PORT_TYPE_GPS +ID_MM_PORT_TYPE_QCDM +ID_MM_TTY_BAUDRATE +ID_MM_TTY_FLOW_CONTROL +</SECTION> 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 */ diff --git a/src/kerneldevice/mm-kernel-device-generic.c b/src/kerneldevice/mm-kernel-device-generic.c index 34987e9d4..9d956bc37 100644 --- a/src/kerneldevice/mm-kernel-device-generic.c +++ b/src/kerneldevice/mm-kernel-device-generic.c @@ -21,6 +21,8 @@ #define _LIBMM_INSIDE_MM #include <libmm-glib.h> +#include <ModemManager-tags.h> + #include "mm-kernel-device-generic.h" #include "mm-kernel-device-generic-rules.h" #include "mm-log.h" @@ -486,7 +488,7 @@ kernel_device_get_physdev_uid (MMKernelDevice *self) return uid; /* Try to load from properties set */ - if ((uid = mm_kernel_device_get_property (self, "ID_MM_PHYSDEV_UID")) != NULL) + if ((uid = mm_kernel_device_get_property (self, ID_MM_PHYSDEV_UID)) != NULL) return uid; /* Use physical device path, if any */ diff --git a/src/kerneldevice/mm-kernel-device-udev.c b/src/kerneldevice/mm-kernel-device-udev.c index 730de98ef..da668f3c5 100644 --- a/src/kerneldevice/mm-kernel-device-udev.c +++ b/src/kerneldevice/mm-kernel-device-udev.c @@ -18,6 +18,8 @@ #define _LIBMM_INSIDE_MM #include <libmm-glib.h> +#include <ModemManager-tags.h> + #include "mm-kernel-device-udev.h" #include "mm-log.h" @@ -358,7 +360,7 @@ kernel_device_get_physdev_uid (MMKernelDevice *_self) } /* Try to load from properties set on the physical device */ - if ((uid = mm_kernel_device_get_global_property (MM_KERNEL_DEVICE (self), "ID_MM_PHYSDEV_UID")) != NULL) + if ((uid = mm_kernel_device_get_global_property (MM_KERNEL_DEVICE (self), ID_MM_PHYSDEV_UID)) != NULL) return uid; /* Use physical device sysfs path, if any */ diff --git a/src/mm-base-manager.c b/src/mm-base-manager.c index 3c09089cd..be92b5e2e 100644 --- a/src/mm-base-manager.c +++ b/src/mm-base-manager.c @@ -30,6 +30,8 @@ #include "mm-kernel-device-generic.h" #include <ModemManager.h> +#include <ModemManager-tags.h> + #include <mm-errors-types.h> #include <mm-gdbus-manager.h> #include <mm-gdbus-test.h> @@ -303,8 +305,8 @@ device_added (MMBaseManager *manager, * * This udev tag applies to each port in a device. In other words, the flag * may be set in some ports, but not in others */ - if (!mm_kernel_device_get_property_as_boolean (port, "ID_MM_CANDIDATE")) { - /* This could mean that device changed, losing its ID_MM_CANDIDATE + if (!mm_kernel_device_get_property_as_boolean (port, ID_MM_CANDIDATE)) { + /* This could mean that device changed, losing its candidate * flags (such as Bluetooth RFCOMM devices upon disconnect. * Try to forget it. */ device_removed (manager, port); diff --git a/src/mm-base-modem.c b/src/mm-base-modem.c index c0ebb7f12..d748b3742 100644 --- a/src/mm-base-modem.c +++ b/src/mm-base-modem.c @@ -23,6 +23,8 @@ #include <string.h> #include <ModemManager.h> +#include <ModemManager-tags.h> + #include <mm-errors-types.h> #include <mm-gdbus-modem.h> @@ -215,13 +217,13 @@ mm_base_modem_grab_port (MMBaseModem *self, mm_serial_parser_v1_destroy); /* Prefer plugin-provided flags to the generic ones */ if (at_pflags == MM_PORT_SERIAL_AT_FLAG_NONE) { - if (mm_kernel_device_get_property_as_boolean (kernel_device, "ID_MM_PORT_TYPE_AT_PRIMARY")) { + if (mm_kernel_device_get_property_as_boolean (kernel_device, ID_MM_PORT_TYPE_AT_PRIMARY)) { mm_dbg ("AT port '%s/%s' flagged as primary", subsys, name); at_pflags = MM_PORT_SERIAL_AT_FLAG_PRIMARY; - } else if (mm_kernel_device_get_property_as_boolean (kernel_device, "ID_MM_PORT_TYPE_AT_SECONDARY")) { + } else if (mm_kernel_device_get_property_as_boolean (kernel_device, ID_MM_PORT_TYPE_AT_SECONDARY)) { mm_dbg ("AT port '%s/%s' flagged as secondary", subsys, name); at_pflags = MM_PORT_SERIAL_AT_FLAG_SECONDARY; - } else if (mm_kernel_device_get_property_as_boolean (kernel_device, "ID_MM_PORT_TYPE_AT_PPP")) { + } else if (mm_kernel_device_get_property_as_boolean (kernel_device, ID_MM_PORT_TYPE_AT_PPP)) { mm_dbg ("AT port '%s/%s' flagged as PPP", subsys, name); at_pflags = MM_PORT_SERIAL_AT_FLAG_PPP; } @@ -249,12 +251,12 @@ mm_base_modem_grab_port (MMBaseModem *self, self); /* For serial ports, optionally use a specific baudrate and flow control */ - if (mm_kernel_device_has_property (kernel_device, "ID_MM_TTY_BAUDRATE")) + if (mm_kernel_device_has_property (kernel_device, ID_MM_TTY_BAUDRATE)) g_object_set (port, - MM_PORT_SERIAL_BAUD, mm_kernel_device_get_property_as_int (kernel_device, "ID_MM_TTY_BAUDRATE"), + MM_PORT_SERIAL_BAUD, mm_kernel_device_get_property_as_int (kernel_device, ID_MM_TTY_BAUDRATE), NULL); - flow_control_tag = mm_kernel_device_get_property (kernel_device, "ID_MM_TTY_FLOW_CONTROL"); + flow_control_tag = mm_kernel_device_get_property (kernel_device, ID_MM_TTY_FLOW_CONTROL); if (flow_control_tag) { MMFlowControl flow_control; GError *inner_error = NULL; diff --git a/src/mm-filter.c b/src/mm-filter.c index cf877b7e1..e65a628ca 100644 --- a/src/mm-filter.c +++ b/src/mm-filter.c @@ -16,6 +16,9 @@ #include <config.h> #include <string.h> +#include <ModemManager.h> +#include <ModemManager-tags.h> + #include "mm-daemon-enums-types.h" #include "mm-filter.h" #include "mm-log.h" @@ -51,8 +54,8 @@ mm_filter_port (MMFilter *self, * allow specifying this flag per-port instead of for the full device, e.g. * for platform tty ports where there's only one port anyway. */ if ((self->priv->enabled_rules & MM_FILTER_RULE_EXPLICIT_WHITELIST) && - (mm_kernel_device_get_global_property_as_boolean (port, "ID_MM_DEVICE_PROCESS") || - mm_kernel_device_get_property_as_boolean (port, "ID_MM_DEVICE_PROCESS"))) { + (mm_kernel_device_get_global_property_as_boolean (port, ID_MM_DEVICE_PROCESS) || + mm_kernel_device_get_property_as_boolean (port, ID_MM_DEVICE_PROCESS))) { mm_dbg ("[filter] (%s/%s) port allowed: device is whitelisted", subsystem, name); return TRUE; } @@ -89,7 +92,7 @@ mm_filter_port (MMFilter *self, /* Ignore blacklisted tty devices. */ if ((self->priv->enabled_rules & MM_FILTER_RULE_TTY_BLACKLIST) && - (mm_kernel_device_get_global_property_as_boolean (port, "ID_MM_DEVICE_IGNORE"))) { + (mm_kernel_device_get_global_property_as_boolean (port, ID_MM_DEVICE_IGNORE))) { mm_dbg ("[filter] (%s/%s): port filtered: device is blacklisted", subsystem, name); return FALSE; } @@ -97,7 +100,7 @@ mm_filter_port (MMFilter *self, /* Is the device in the manual-only greylist? If so, return if this is an * automatic scan. */ if ((self->priv->enabled_rules & MM_FILTER_RULE_TTY_MANUAL_SCAN_ONLY) && - (!manual_scan && mm_kernel_device_get_global_property_as_boolean (port, "ID_MM_DEVICE_MANUAL_SCAN_ONLY"))) { + (!manual_scan && mm_kernel_device_get_global_property_as_boolean (port, ID_MM_DEVICE_MANUAL_SCAN_ONLY))) { mm_dbg ("[filter] (%s/%s): port filtered: device probed only in manual scan", subsystem, name); return FALSE; } @@ -111,7 +114,7 @@ mm_filter_port (MMFilter *self, !g_strcmp0 (physdev_subsystem, "pci") || !g_strcmp0 (physdev_subsystem, "pnp") || !g_strcmp0 (physdev_subsystem, "sdio"))) { - if (!mm_kernel_device_get_global_property_as_boolean (port, "ID_MM_PLATFORM_DRIVER_PROBE")) { + if (!mm_kernel_device_get_global_property_as_boolean (port, ID_MM_PLATFORM_DRIVER_PROBE)) { mm_dbg ("[filter] (%s/%s): port filtered: port's parent platform driver is not whitelisted", subsystem, name); return FALSE; } diff --git a/src/mm-port-probe.c b/src/mm-port-probe.c index fd66d20a7..9913001b3 100644 --- a/src/mm-port-probe.c +++ b/src/mm-port-probe.c @@ -22,6 +22,8 @@ #include <string.h> #include <ModemManager.h> +#include <ModemManager-tags.h> + #include <mm-errors-types.h> #include "mm-port-probe.h" @@ -637,12 +639,12 @@ common_serial_port_setup (MMPortProbe *self, { const gchar *flow_control_tag; - if (mm_kernel_device_has_property (self->priv->port, "ID_MM_TTY_BAUDRATE")) + if (mm_kernel_device_has_property (self->priv->port, ID_MM_TTY_BAUDRATE)) g_object_set (serial, - MM_PORT_SERIAL_BAUD, mm_kernel_device_get_property_as_int (self->priv->port, "ID_MM_TTY_BAUDRATE"), + MM_PORT_SERIAL_BAUD, mm_kernel_device_get_property_as_int (self->priv->port, ID_MM_TTY_BAUDRATE), NULL); - flow_control_tag = mm_kernel_device_get_property (self->priv->port, "ID_MM_TTY_FLOW_CONTROL"); + flow_control_tag = mm_kernel_device_get_property (self->priv->port, ID_MM_TTY_FLOW_CONTROL); if (flow_control_tag) { MMFlowControl flow_control; GError *error = NULL; @@ -1896,12 +1898,12 @@ set_property (GObject *object, case PROP_PORT: /* construct only */ self->priv->port = g_value_dup_object (value); - self->priv->is_ignored = mm_kernel_device_get_property_as_boolean (self->priv->port, "ID_MM_PORT_IGNORE"); - self->priv->is_gps = mm_kernel_device_get_property_as_boolean (self->priv->port, "ID_MM_PORT_TYPE_GPS"); - self->priv->maybe_at_primary = mm_kernel_device_get_property_as_boolean (self->priv->port, "ID_MM_PORT_TYPE_AT_PRIMARY"); - self->priv->maybe_at_secondary = mm_kernel_device_get_property_as_boolean (self->priv->port, "ID_MM_PORT_TYPE_AT_SECONDARY"); - self->priv->maybe_at_ppp = mm_kernel_device_get_property_as_boolean (self->priv->port, "ID_MM_PORT_TYPE_AT_PPP"); - self->priv->maybe_qcdm = mm_kernel_device_get_property_as_boolean (self->priv->port, "ID_MM_PORT_TYPE_QCDM"); + self->priv->is_ignored = mm_kernel_device_get_property_as_boolean (self->priv->port, ID_MM_PORT_IGNORE); + self->priv->is_gps = mm_kernel_device_get_property_as_boolean (self->priv->port, ID_MM_PORT_TYPE_GPS); + self->priv->maybe_at_primary = mm_kernel_device_get_property_as_boolean (self->priv->port, ID_MM_PORT_TYPE_AT_PRIMARY); + self->priv->maybe_at_secondary = mm_kernel_device_get_property_as_boolean (self->priv->port, ID_MM_PORT_TYPE_AT_SECONDARY); + self->priv->maybe_at_ppp = mm_kernel_device_get_property_as_boolean (self->priv->port, ID_MM_PORT_TYPE_AT_PPP); + self->priv->maybe_qcdm = mm_kernel_device_get_property_as_boolean (self->priv->port, ID_MM_PORT_TYPE_QCDM); break; default: G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec); |