doc: add notes about Pantech UML290 and the WMC protocol

WMC is a proprietary protocol observed on various Verizon devices
and implemented by the UML290.

uml290.txt

@@ -0,0 +1,163 @@
+This document describes information about the Pantech UML290 and the WMC
+protocol observed through USB packet capture and other investigation.
+
+
+Pantech UML290 Notes
+--------------------------------------
+
+This device exposes 4 USB interfaces.  They are, in no particular order, a
+CDC-ACM compatible AT command port, a QCDM/Diag port, an WMC port, and a
+raw IP network port.  The modem's native command interface is the WMC port
+which the Windows driver uses for all normal communication.
+
+
+CDC-ACM AT Port
+----------------
+
+The modem's +GCAP response reports:
+
++GCAP: +CIS707-A, CIS-856, CIS-856-A, +CGSM, +CLTE1
+
+and with recent firmware updates (L0290VWB333F.230 [Mar 15 2011 15:03:20] or
+later) the device does, in fact, appear to support common IS-707-A and ETSI
+27.007 GSM and LTE AT commands.  This interface does support PPP data but when
+PPP is used the device does not support handoffs between LTE and EVDO.
+
+To support seamless operation of devices between LTE and EVDO Verizon has
+upgraded their network to support the eHRPD protocol.  Older, non-LTE capable
+devices usually do not include support for eHRPD and use the standard HRPD
+protocols.  LTE-capable devices support both eHRPD and standard HRPD, but at
+least with the UML290, connections to the 3G EVDO network using direct PPP over
+the AT modem port do not use eHRPD.  Thus to successfully connect to the 3G
+EVDO network, the modem must be switched into standard HRPD mode by changing
+the value of the NV_HDRSCP_FORCE_AT_CONFIG_I NVRAM item using the the QCDM/Diag
+port and the DIAG protocol.  Use of HRPD only prevents connections to the LTE
+network.  It is possible that connections initiated using the WMC port and
+utilizing the "raw IP" network interface do not have this problem.
+
+
+QCDM/Diag Port
+----------------
+
+This port is a normal QCDM/Diag port and responds to DIAG commands.
+
+
+Raw IP Network Port
+-------------------
+
+This USB interface is the normal network interface port the device uses in
+Windows for network communication.  It appears to operate in a "raw IP" mode
+where raw IP packets are sent and received over USB with no additional framing
+or encapsulation.  The IPv4 and IPv6 addresses for the interface are determined
+using WMC commands on the WMC port, not through the AT command port.  The AT
+command port only supports PPP-based communication.  More information about the
+"raw IP" mode may be available in the Qualcomm CodeAurora SMD/QMI drivers which
+implement a "raw IP" network communication mode for various MSM7xxx chipsets
+used in Android devices.
+
+
+WMC Port
+-----------
+
+This port accepts and responds to WMC protocol requests.  Instead of using plain
+WMC however, requests are prefixed with the string "AT*WMC=" and terminated with
+a newline (0x0D) character instead of the normal WMC frame termination
+character (0x7E).  The data in between is normal binary WMC data, except that
+all bytes less than 0x20 are escaped using normal HDLC/PPP escaping while a
+normal WMC request would only escape the special HDLC/PPP characters of 0x7E and
+0x7D.  Thus a UML290 request looks like this in hexadecimal:
+
+41542a574d433dc87d2a87b80d
+
+This "AT"-style framing has not been observed on other devices.
+
+
+
+WMC Protocol Framing
+--------------------
+
+The protocol is a request/response style protocol though unsolicited responses
+are sometimes sent from the modem to the host.  There does not appear to be any
+sequence numbering in either the request or response packets.  WMC packets
+always begin with the frame start marker (0xC8).  The second byte is the command
+number.  The frame ends with a three-byte trailer including a CRC-16 and a
+standard HDLC/PPP frame terminator (0x7E), though this terminator is missing in
+some cases as described below. Thus a normal WMC packet looks like this:
+
+0xC8 <command number> <data> <CRC-16> 0x7E
+
+The entire frame (exclusive of the 0x7E frame terminator) is escaped using
+standard HDLC/PPP escaping mechanisms to ensure that the bytes 0x7E and 0x7D
+never appear in the packet.
+
+
+Requests
+---------------
+
+Requests are usually short, often only 4 or 5 bytes long, including the frame
+start marker (0xC8), the command number, the CRC, and the frame termination
+marker.  Requests always receive a response from the modem containing the same
+command number.
+
+The UML290 uses different "AT"-style framing of requests, prefixing the
+request with "AT*WMC=" and using a frame termination marker of 0x0D instead
+of the standard 0x7E.  The UML290 also uses a different CRC-16 initial seed of
+0xAAFE instead of the standard 0xFFFF used on other devices and with HDLC
+framing in general.  For added lolz the UML290 HDLC-escapes all control
+characters in the request instead of only the standard 0x7D and 0x7E characters
+escaped in HDLC.
+
+Thus a normal WMC request (from a PC5740) looks like this:
+
+     c8          0a     77 a4        7e
+<frame start> <cmd no> <CRC-16> <terminator>
+
+while the same request from the UML290 looks like this:
+
+41542a574d433d       c8        7d2a    87 b8        0d
+  <AT*WMC=>    <frame start> <cmd no> <CRC-16> <terminator>
+
+Thus after removing all framing and escaping, this WMC request is a single
+byte (0x0A) which indicates the command number of the request.
+
+
+WMC Responses and Unsolicited Messages
+--------------------------------------
+
+Responses begin with the WMC frame start marker (0xC8) and end with the standard
+HDLC/PPP frame terminator (0x7E) in all observed cases, even on the UML290.
+The data in between is HDLC/PPP escaped and there is a CRC-16 before the frame
+terminator.  Not all devices use the same CRC-16 calculation however; the
+UML290 always uses a CRC-16 of 0x3030, while the PC5740 includes a valid CRC-16
+using a standard polynomial of 0x8408 and an initial seed of 0xFFFF.  Responses
+may span multiple USB packets if they are large enough, but the frame terminator
+provides a convenient mechanism for detecting when the frame is complete.
+
+A standard WMC response (from a UML290) looks like this:
+
+c80d0000000030307e
+
+which translates to:
+
+c8 0d 00 00 00 00
+
+
+WMC Command Numbers
+-------------------
+
+These command numbers have been observed and minimally investigated:
+
+0x06: request device information, including manufacturer, model, firmware
+      revision, hardware revision, MCC/MNC, serial number
+
+0x0A: request IP configuration when connected (IPv4 and IPv6) on the UML290; may
+      include elapsed connected time or traffic byte counts too.  Request has
+      been observed on the PC5740 but is significantly shorter.
+
+0x0B: get status including operator name, RSSI dBm, and possibly registration
+      status
+
+0x13: retrieve SMS messages
+
+0x4D: appears to request EPS bearer configuration; response includes the APN
+