Intel North Mux-Agent

Intel North Mux-Agent 개요

North Mux-Agent는 Intel PMC microcontroller가 있는 대부분의 Intel platform에서 지원되는 PMC firmware 기능이다. System의 여러 USB multiplexer와 demultiplexer를 설정하는 데 사용한다.

Operating system에서 mux-agent 설정을 허용하는 platform은 이를 나타내는 ACPI device object를 제공하며, 해당 node의 HID는 `INTC105C`다.

North Mux-Agent는 Intel PMC Mux Control 또는 간단히 mux-agent라고도 부른다. Driver는 PMC IPC method를 사용해 PMC microcontroller와 통신하며, 관련 IPC 구현은 `drivers/platform/x86/intel_scu_ipc.c`에 있다.

Driver는 USB Type-C Mux Class에 등록한다. 이를 통해 USB Type-C Controller 및 Interface driver가 cable plug orientation과 Alternate Mode를 포함한 mode를 설정할 수 있다.

또한 USB Host와 Device mode를 모두 지원하기 위해 USB Role Class에도 등록한다. Mux-agent driver source는 `drivers/usb/typec/mux/intel_pmc_mux.c`다.

.. 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 channel node와 _PLD

System에서 mux-agent가 제어하는 USB Type-C connector마다 PMC mux-agent device node 아래에 별도의 child node를 둔다. 이 child는 실제 connector 자체를 나타내지 않고, connector와 연관된 mux-agent 내부 channel을 나타낸다.

예제 `Scope (_SB.PCI0.PMC.MUX)` 아래에는 `Device (CH0)`과 `Device (CH1)`이 있다. CH0의 `_ADR`은 0, CH1의 `_ADR`은 1이며 이 값이 mux-agent channel number를 식별한다.

Port, 즉 channel node에는 선택적인 `_PLD` Physical Location of Device object를 사용할 수 있다. `_PLD`를 제공한다면 대응 connector node의 `_PLD`와 일치해야 한다.

예제의 CH0 `_PLD` method는 pseudocode로 `Return (\_SB.USBC.CON0._PLD())`를 수행한다. 이는 channel 0이 connector CON0과 같은 physical location을 가리키게 한다.

따라서 `_ADR`은 firmware 제어 channel을, `_PLD`는 사용자가 볼 수 있는 실제 connector의 위치를 각각 나타낸다. 두 object의 역할을 혼동하거나 channel node를 connector object 자체로 취급해서는 안 된다.

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())
                }
            }
        }

Port number와 고정 orientation property

USB Type-C connector 뒤의 mux를 설정하려면 PMC firmware가 connector에 연관된 USB2 port와 USB3 port를 알아야 한다. Driver는 `_DSD`의 `usb2-port-number`와 `usb3-port-number` device property에서 올바른 port number를 읽는다.

두 property 값은 port index를 뜻하는 integer다. Index는 1-based이므로 첫 port가 1이며 값 0은 불법이다. Driver는 추출한 값을 변환하지 않고 mux-agent 전용 PMC message에 그대로 사용한다.

예제 `_DSD`는 Device Properties UUID `daffd814-6eba-4d8c-8a91-bc9bbf4aa301` 아래 `usb2-port-number=6`, `usb3-port-number=3`을 선언한다.

Platform에 따라 connector에서 오는 data line과 SBU line이 mux-agent 관점에서 fixed일 수 있다. 이는 mux-agent driver가 cable plug orientation에 따라 해당 line을 전환해서는 안 된다는 뜻이다. 예를 들어 platform의 retimer가 cable orientation을 직접 처리하는 경우가 있다.

Driver는 SBU line에 대한 `sbu-orientation`과 data 또는 high-speed line에 대한 `hsl-orientation` property로 line이 fixed인지, 어느 orientation에 고정됐는지 확인한다.

두 orientation property는 문자열이며 USB Type-C connector orientation에 정의된 `normal` 또는 `reversed` 값 중 하나를 사용한다. 예제는 두 property를 모두 `normal`로 설정한다.

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"},
            },
        })

두 connector channel의 전체 ASL

전체 ASL 예제는 `Scope (_SB.PCI0.PMC)` 아래 `Device (MUX)`를 만들고 `_HID="INTC105C"`로 mux-agent를 식별한다. MUX 아래에는 두 connector에 대응하는 channel node CH0과 CH1이 있다.

CH0은 `_ADR=0`이고 Device Properties UUID package에 `usb2-port-number=6`, `usb3-port-number=3`, `sbu-orientation="normal"`, `hsl-orientation="normal"`을 제공한다.

CH1은 `_ADR=1`이며 `usb2-port-number=5`, `usb3-port-number=2`를 사용한다. Orientation property는 CH0과 마찬가지로 SBU와 high-speed line 모두 `normal`이다.

두 channel의 `_ADR`과 port number는 서로 다른 namespace를 사용한다. `_ADR`은 mux-agent channel을 0부터 식별하지만 USB2·USB3 port property는 1-based라 0을 사용할 수 없다. Review할 때 이 기준 차이를 반드시 확인해야 한다.

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"},
                        },
                    })
                }
            }
        }