From: Sandeep Singh <[email protected]> Add Maintainers for AMD SFH(SENSOR FUSION HUB) Solution and work flow document.
Co-developed-by: Nehal Shah <[email protected]> Signed-off-by: Nehal Shah <[email protected]> Signed-off-by: Sandeep Singh <[email protected]> --- Documentation/hid/amd-sfh-hid.rst | 145 ++++++++++++++++++++++++++++++ Documentation/hid/index.rst | 1 + MAINTAINERS | 8 ++ 3 files changed, 154 insertions(+) create mode 100644 Documentation/hid/amd-sfh-hid.rst diff --git a/Documentation/hid/amd-sfh-hid.rst b/Documentation/hid/amd-sfh-hid.rst new file mode 100644 index 000000000000..1f2fe29ccd4f --- /dev/null +++ b/Documentation/hid/amd-sfh-hid.rst @@ -0,0 +1,145 @@ +.. SPDX-License-Identifier: GPL-2.0 + + +AMD Sensor Fusion Hub +===================== +AMD Sensor Fusion Hub (SFH) is part of an SOC starting from Ryzen based platforms. +The solution is working well on several OEM products. AMD SFH uses HID over PCIe bus. +In terms of architecture it resembles ISH, however the major difference is all +the HID reports are generated as part of the kernel driver. + +1. Block Diagram +================ + +:: + + --------------------------------- + | HID User Space Applications | + - ------------------------------- + + --------------------------------------------- + --------------------------------- + | HID Core | + --------------------------------- + + --------------------------------- + | AMD HID Transport | + --------------------------------- + + -------------------------------- + | AMD HID Client | + | with HID Report Generator| + -------------------------------- + + -------------------------------- + | AMD MP2 PCIe Driver | + -------------------------------- + OS + --------------------------------------------- + Hardware + Firmware + -------------------------------- + | SFH MP2 Processor | + -------------------------------- + + +AMD HID Transport Layer +----------------------- +AMD SFH transport is also implemented as a bus. Each client application executing in the AMD MP2 is +registered as a device on this bus. Here: MP2 which is an ARM core connected to x86 for processing +sensor data. The layer, which binds each device (AMD SFH HID driver) identifies the device type and +registers with the hid core. Transport layer attach a constant "struct hid_ll_driver" object with +each device. Once a device is registered with HID core, the callbacks provided via this struct are +used by HID core to communicate with the device. AMD HID Transport layer implements the synchronous calls. + +AMD HID Client Layer +-------------------- +This layer is responsible to implement HID request and descriptors. As firmware is OS agnostic, HID +client layer fills the HID request structure and descriptors. HID client layer is complex as it is +interface between MP2 PCIe layer and HID. HID client layer initialized the MP2 PCIe layer and holds +the instance of MP2 layer. It identifies the number of sensors connected using MP2-PCIe layer. Base +on that allocates the DRAM address for each and every sensor and pass it to MP2-PCIe driver.On +enumeration of each the sensor, client layer fills the HID Descriptor structure and HID input repor +structure. HID Feature report structure is optional. The report descriptor structure varies from +sensor to sensor. + +AMD MP2 PCIe layer +------------------ +MP2 PCIe Layer is responsible for making all transactions with the firmware over PCIe. +The connection establishment between firmware and PCIe happens here. + +The communication between X86 and MP2 is split into three parts. +1. Command transfer via the C2P mailbox registers. +2. Data transfer via DRAM. +3. Supported sensor info via P2C registers. + +Commands are sent to MP2 using C2P Mailbox registers. Writing into C2P Message registers generate +interrupt to MP2. The client layer allocates the physical memory and the same is sent to MP2 via +the PCI layer. MP2 firmware writes the command output to the access DRAM memory which the client +layer has allocated. Firmware always writes minimum of 32 bytes into DRAM. So as a protocol driver +shall allocate minimum of 32 bytes DRAM space. + +Enumeration and Probing flow +---------------------------- +:: + + HID AMD AMD AMD -PCIe MP2 + Core Transport Client layer layer FW + | | | | | + | | | on Boot Driver Loaded | + | | | | | + | | | MP2-PCIe Int | + | | | | | + | | |---Get Number of sensors-> | | + | | | Read P2C | + | | | Register | + | | | | | + | | | Loop(for No of Sensors) | | + | | |----------------------| | | + | | | Create HID Descriptor| | | + | | | Create Input report | | | + | | | Descriptor Map | | | + | | | the MP2 FW Index to | | | + | | | HID Index | | | + | | | Allocate the DRAM | Enable | + | | | address | Sensors | + | | |----------------------| | | + | | HID transport| | Enable | + | |<--Probe------| |---Sensor CMD--> | + | | Create the | | | + | | HID device | | | + | | (MFD) | | | + | | by Populating| | | + | | the HID | | | + | | ll_driver | | | + | HID | | | | + | add | | | | + |Device | | | | + |<------------- | | | | + + +Data Flow from Application to the AMD SFH Driver +------------------------------------------------ + +:: + + | | | | | + | | | | | + | | | | | + | | | | | + | | | | | + |HID_req | | | | + |get_report | | | | + |------------->| | | | + | | HID_get_input| | | + | | report | | | + | |------------->|------------------------| | | + | | | Read the DRAM data for| | | + | | | requested sensor and | | | + | | | create the HID input | | | + | | | report | | | + | | |------------------------| | | + | |Data received | | | + | | in HID report| | | + To |<-------------|<-------------| | | + Applications| | | | | + <-------| | | | | diff --git a/Documentation/hid/index.rst b/Documentation/hid/index.rst index 737d66dc16a1..e50f513c579c 100644 --- a/Documentation/hid/index.rst +++ b/Documentation/hid/index.rst @@ -16,3 +16,4 @@ Human Interface Devices (HID) hid-alps intel-ish-hid + amd-sfh-hid diff --git a/MAINTAINERS b/MAINTAINERS index 0d0862b19ce5..a3d3115939b4 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -943,6 +943,14 @@ S: Supported F: arch/arm64/boot/dts/amd/amd-seattle-xgbe*.dtsi F: drivers/net/ethernet/amd/xgbe/ +AMD SENSOR FUSION HUB DRIVER +M: Nehal Shah <[email protected]> +M: Sandeep Singh <[email protected]> +L: [email protected] +S: Maintained +F: Documentation/hid/amd-sfh* +F: drivers/hid/amd-sfh-hid/ + ANALOG DEVICES INC AD5686 DRIVER M: Michael Hennerich <[email protected]> L: [email protected] -- 2.25.1
