From: Heikki Krogerus <heikki.krogerus@linux.intel.com>
To: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
Cc: Prashant Malani <pmalani@chromium.org>,
Benson Leung <bleung@chromium.org>,
linux-usb@vger.kernel.org, linux-kernel@vger.kernel.org,
linux-acpi@vger.kernel.org,
"Rafael J. Wysocki" <rjw@rjwysocki.net>
Subject: [PATCH 3/4] usb: typec: Add firmware documentation for the Intel PMC mux control
Date: Thu, 7 May 2020 18:08:59 +0300 [thread overview]
Message-ID: <20200507150900.12102-4-heikki.krogerus@linux.intel.com> (raw)
In-Reply-To: <20200507150900.12102-1-heikki.krogerus@linux.intel.com>
Adding documentation that describes how the PMC mux-agent
function is described in the ACPI tables.
Signed-off-by: Heikki Krogerus <heikki.krogerus@linux.intel.com>
---
.../firmware-guide/acpi/intel-pmc-mux.rst | 153 ++++++++++++++++++
1 file changed, 153 insertions(+)
create mode 100644 Documentation/firmware-guide/acpi/intel-pmc-mux.rst
diff --git a/Documentation/firmware-guide/acpi/intel-pmc-mux.rst b/Documentation/firmware-guide/acpi/intel-pmc-mux.rst
new file mode 100644
index 000000000000..99b86710f02b
--- /dev/null
+++ b/Documentation/firmware-guide/acpi/intel-pmc-mux.rst
@@ -0,0 +1,153 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+=====================
+Intel North Mux-Agent
+=====================
+
+Introduction
+============
+
+North Mux-Agent is a function of the Intel PMC firmware that is supported on
+most Intel based platforms that have the PMC microcontroller. It's used for
+configuring the various USB Multiplexer/DeMultiplexers on the system. The
+platforms that allow the mux-agent to be configured from the operating system
+have an ACPI device object (node) with HID "INTC105C" that represents it.
+
+The North Mux-Agent (aka. Intel PMC Mux Control, or just mux-agent) driver
+communicates with the PMC microcontroller by using the PMC IPC method
+(drivers/platform/x86/intel_scu_ipc.c). The driver registers with the USB Type-C
+Mux Class which allows the USB Type-C Controller and Interface drivers to
+configure the cable plug orientation and mode (with Alternate Modes). The driver
+also registers with the USB Role Class in order to support both USB Host and
+Device modes. The driver is located here: drivers/usb/typec/mux/intel_pmc_mux.c.
+
+Port nodes
+==========
+
+General
+-------
+
+For every USB Type-C connector under the mux-agent control on the system, there
+is a separate child node under the PMC mux-agent device node. Those nodes do not
+represent the actual connectors, but instead the "channels" in the mux-agent
+that are associated with the connectors::
+
+ Scope (_SB.PCI0.PMC.MUX)
+ {
+ Device (CH0)
+ {
+ Name (_ADR, 0)
+ }
+
+ Device (CH1)
+ {
+ Name (_ADR, 1)
+ }
+ }
+
+_PLD (Physical Location of Device)
+----------------------------------
+
+The optional _PLD object can be used with the port (the channel) nodes. If _PLD
+is supplied, it should match the connector node _PLD::
+
+ Scope (_SB.PCI0.PMC.MUX)
+ {
+ Device (CH0)
+ {
+ Name (_ADR, 0)
+ Method (_PLD, 0, NotSerialized)
+ {
+ /* Consider this as pseudocode. */
+ Return (\_SB.USBC.CON0._PLD())
+ }
+ }
+ }
+
+Mux-agent specific _DSD Device Properties
+-----------------------------------------
+
+Port Numbers
+~~~~~~~~~~~~
+
+In order to configure the muxes behind a USB Type-C connector, the PMC firmware
+needs to know the USB2 port and the USB3 port that is associated with the
+connector. The driver extracts the correct port numbers by reading specific _DSD
+device properties named "usb2-port-number" and "usb3-port-number". These
+properties have integer value that means the port index. The port index number
+is 1's based, and value 0 is illegal. The driver uses the numbers extracted from
+these device properties as-is when sending the mux-agent specific messages to
+the PMC::
+
+ Name (_DSD, Package () {
+ ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
+ Package() {
+ Package () {"usb2-port-number", 6},
+ Package () {"usb3-port-number", 3},
+ },
+ })
+
+Orientation
+~~~~~~~~~~~
+
+Depending on the platform, the data and SBU lines coming from the connector may
+be "fixed" from the mux-agent's point of view, which means the mux-agent driver
+should not configure them according to the cable plug orientation. This can
+happen for example if a retimer on the platform handles the cable plug
+orientation. The driver uses a specific device properties "sbu-orientation"
+(SBU) and "hsl-orientation" (data) to know if those lines are "fixed", and to
+which orientation. The value that these properties have is a string value, and
+it can be one that is defined for the USB Type-C connector orientation: "normal"
+or "reversed"::
+
+ Name (_DSD, Package () {
+ ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
+ Package() {
+ Package () {"sbu-orientation", "normal"},
+ Package () {"hsl-orientation", "normal"},
+ },
+ })
+
+Example ASL
+===========
+
+The following ASL is an example that shows the mux-agent node, and two
+connectors under its control::
+
+ Scope (_SB.PCI0.PMC)
+ {
+ Device (MUX)
+ {
+ Name (_HID, "INTC105C")
+
+ Device (CH0)
+ {
+ Name (_ADR, 0)
+
+ Name (_DSD, Package () {
+ ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
+ Package() {
+ Package () {"usb2-port-number", 6},
+ Package () {"usb3-port-number", 3},
+ Package () {"sbu-orientation", "normal"},
+ Package () {"hsl-orientation", "normal"},
+ },
+ })
+ }
+
+ Device (CH1)
+ {
+ Name (_ADR, 1)
+
+ Name (_DSD, Package () {
+ ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
+ Package() {
+ Package () {"usb2-port-number", 5},
+ Package () {"usb3-port-number", 2},
+ Package () {"sbu-orientation", "normal"},
+ Package () {"hsl-orientation", "normal"},
+ },
+ })
+ }
+ }
+ }
--
2.26.2
next prev parent reply other threads:[~2020-05-07 15:09 UTC|newest]
Thread overview: 14+ messages / expand[flat|nested] mbox.gz Atom feed top
2020-05-07 15:08 [PATCH 0/4] usb: typec: Intel PMC driver changes Heikki Krogerus
2020-05-07 15:08 ` [PATCH 1/4] usb: typec: Add typec_find_orientation() Heikki Krogerus
2020-05-07 15:08 ` [PATCH 2/4] usb: typec: mux: intel_pmc_mux: Support for static SBU/HSL orientation Heikki Krogerus
2020-05-07 22:40 ` Prashant Malani
2020-05-08 11:18 ` Heikki Krogerus
2020-05-08 11:36 ` Prashant Malani
2020-05-11 13:32 ` Heikki Krogerus
2020-05-11 17:57 ` Prashant Malani
2020-05-12 14:22 ` Heikki Krogerus
2020-05-12 19:19 ` Prashant Malani
2020-05-14 20:51 ` Prashant Malani
2020-05-15 12:05 ` Heikki Krogerus
2020-05-07 15:08 ` Heikki Krogerus [this message]
2020-05-07 15:09 ` [PATCH 4/4] MAINTAINERS: Add entry for Intel PMC mux driver Heikki Krogerus
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20200507150900.12102-4-heikki.krogerus@linux.intel.com \
--to=heikki.krogerus@linux.intel.com \
--cc=bleung@chromium.org \
--cc=gregkh@linuxfoundation.org \
--cc=linux-acpi@vger.kernel.org \
--cc=linux-kernel@vger.kernel.org \
--cc=linux-usb@vger.kernel.org \
--cc=pmalani@chromium.org \
--cc=rjw@rjwysocki.net \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).