Documentation/hid/amd-sfh-hid.rst

   1 .. SPDX-License-Identifier: GPL-2.0
   2
   3
   4 AMD Sensor Fusion Hub
   5 =====================
   6 AMD Sensor Fusion Hub (SFH) is part of an SOC starting from Ryzen based platforms.
   7 The solution is working well on several OEM products. AMD SFH uses HID over PCIe bus.
   8 In terms of architecture it resembles ISH, however the major difference is all
   9 the HID reports are generated as part of the kernel driver.
  10
  11 1. Block Diagram
  12 ================
  13
  14 ::
  15
  16         ---------------------------------
  17         |  HID User Space Applications  |
  18         - -------------------------------
  19
  20     ---------------------------------------------
  21          ---------------------------------
  22         |               HID Core          |
  23          ---------------------------------
  24
  25          ---------------------------------
  26         |     AMD HID Transport           |
  27          ---------------------------------
  28
  29          --------------------------------
  30         |             AMD HID Client     |
  31         |       with HID Report Generator|
  32          --------------------------------
  33
  34          --------------------------------
  35         |     AMD MP2 PCIe Driver        |
  36          --------------------------------
  37     OS
  38     ---------------------------------------------
  39     Hardware + Firmware
  40          --------------------------------
  41          |     SFH MP2 Processor         |
  42          --------------------------------
  43
  44
  45 AMD HID Transport Layer
  46 -----------------------
  47 AMD SFH transport is also implemented as a bus. Each client application executing in the AMD MP2 is
  48 registered as a device on this bus. Here: MP2 which is an ARM core connected to x86 for processing
  49 sensor data. The layer, which binds each device (AMD SFH HID driver) identifies the device type and
  50 registers with the hid core. Transport layer attach a constant "struct hid_ll_driver" object with
  51 each device. Once a device is registered with HID core, the callbacks provided via this struct are
  52 used by HID core to communicate with the device. AMD HID Transport layer implements the synchronous calls.
  53
  54 AMD HID Client Layer
  55 --------------------
  56 This layer is responsible to implement HID request and descriptors. As firmware is OS agnostic, HID
  57 client layer fills the HID request structure and descriptors. HID client layer is complex as it is
  58 interface between MP2 PCIe layer and HID. HID client layer initialized the MP2 PCIe layer and holds
  59 the instance of MP2 layer. It identifies the number of sensors connected using MP2-PCIe layer. Base
  60 on that allocates the DRAM address for each and every sensor and pass it to MP2-PCIe driver.On
  61 enumeration of each the sensor, client layer fills the HID Descriptor structure and HID input repor
  62 structure. HID Feature report structure is optional. The report descriptor structure varies from
  63 sensor to sensor.
  64
  65 AMD MP2 PCIe layer
  66 ------------------
  67 MP2 PCIe Layer is responsible for making all transactions with the firmware over PCIe.
  68 The connection establishment between firmware and PCIe happens here.
  69
  70 The communication between X86 and MP2 is split into three parts.
  71 1. Command transfer via the C2P mailbox registers.
  72 2. Data transfer via DRAM.
  73 3. Supported sensor info via P2C registers.
  74
  75 Commands are sent to MP2 using C2P Mailbox registers. Writing into C2P Message registers generate
  76 interrupt to MP2. The client layer allocates the physical memory and the same is sent to MP2 via
  77 the PCI layer. MP2 firmware writes the command output to the access DRAM memory which the client
  78 layer has allocated. Firmware always writes minimum of 32 bytes into DRAM. So as a protocol driver
  79 shall allocate minimum of 32 bytes DRAM space.
  80
  81 Enumeration and Probing flow
  82 ----------------------------
  83 ::
  84
  85        HID             AMD            AMD                       AMD -PCIe             MP2
  86        Core         Transport      Client layer                   layer                FW
  87         |               |              |                           |                 |
  88         |               |              |                 on Boot Driver Loaded       |
  89         |               |              |                           |                 |
  90         |               |              |                        MP2-PCIe Int         |
  91         |               |              |                           |                 |
  92         |               |              |---Get Number of sensors-> |                 |
  93         |               |              |                       Read P2C              |
  94         |               |              |                        Register             |
  95         |               |              |                           |                 |
  96         |               |              | Loop(for No of Sensors)   |                 |
  97         |               |              |----------------------|    |                 |
  98         |               |              | Create HID Descriptor|    |                 |
  99         |               |              | Create Input  report |    |                 |
 100         |               |              |  Descriptor Map      |    |                 |
 101         |               |              |  the MP2 FW Index to |    |                 |
 102         |               |              |   HID Index          |    |                 |
 103         |               |              | Allocate the DRAM    |  Enable              |
 104         |               |              |        address       |  Sensors             |
 105         |               |              |----------------------|    |                 |
 106         |               | HID transport|                           |    Enable       |
 107         |               |<--Probe------|                           |---Sensor CMD--> |
 108         |               | Create the   |                           |                 |
 109         |               | HID device   |                           |                 |
 110         |               |    (MFD)     |                           |                 |
 111         |               | by Populating|                           |                 |
 112         |               |  the HID     |                           |                 |
 113         |               |  ll_driver   |                           |                 |
 114         | HID           |              |                           |                 |
 115         |  add          |              |                           |                 |
 116         |Device         |              |                           |                 |
 117         |<------------- |              |                           |                 |
 118
 119
 120 Data Flow from Application to the AMD SFH Driver
 121 ------------------------------------------------
 122
 123 ::
 124
 125                 |              |              |                           |                 |
 126                 |              |              |                           |                 |
 127                 |              |              |                           |                 |
 128                 |              |              |                           |                 |
 129                 |              |              |                           |                 |
 130                 |HID_req       |              |                           |                 |
 131                 |get_report    |              |                           |                 |
 132                 |------------->|              |                           |                 |
 133                 |              | HID_get_input|                           |                 |
 134                 |              |  report      |                           |                 |
 135                 |              |------------->|------------------------|  |                 |
 136                 |              |              |  Read the DRAM data for|  |                 |
 137                 |              |              |  requested sensor and  |  |                 |
 138                 |              |              |  create the HID input  |  |                 |
 139                 |              |              |  report                |  |                 |
 140                 |              |              |------------------------|  |                 |
 141                 |              |Data received |                           |                 |
 142                 |              | in HID report|                           |                 |
 143     To          |<-------------|<-------------|                           |                 |
 144     Applications|              |              |                           |                 |
 145         <-------|              |              |                           |                 |