Merge branch 'for-linus' of git://git.kernel.org/pub/scm/linux/kernel/git/hid/hid

# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)

%YAML 1.2

---

$id: http://devicetree.org/schemas/input/goodix,gt7375p.yaml#

$schema: http://devicetree.org/meta-schemas/core.yaml#

title: Goodix GT7375P touchscreen

maintainers:

  - Douglas Anderson <dianders@chromium.org>

description:

  Supports the Goodix GT7375P touchscreen.

  This touchscreen uses the i2c-hid protocol but has some non-standard

  power sequencing required.

properties:

  compatible:

    items:

      - const: goodix,gt7375p

  reg:

    enum:

      - 0x5d

      - 0x14

  interrupts:

    maxItems: 1

  reset-gpios:

    true

  vdd-supply:

    description: The 3.3V supply to the touchscreen.

required:

  - compatible

  - reg

  - interrupts

  - reset-gpios

  - vdd-supply

additionalProperties: false

examples:

  - |

    #include <dt-bindings/clock/qcom,rpmh.h>

    #include <dt-bindings/gpio/gpio.h>

    #include <dt-bindings/interrupt-controller/irq.h>

    i2c {

      #address-cells = <1>;

      #size-cells = <0>;

      ap_ts: touchscreen@5d {

        compatible = "goodix,gt7375p";

        reg = <0x5d>;

        interrupt-parent = <&tlmm>;

        interrupts = <9 IRQ_TYPE_LEVEL_LOW>;

        reset-gpios = <&tlmm 8 GPIO_ACTIVE_LOW>;

        vdd-supply = <&pp3300_ts>;

      };

    };

AMD Sensor Fusion Hub

=====================

AMD Sensor Fusion Hub (SFH) is part of an SOC starting from Ryzen based platforms.

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

================

Block Diagram

-------------

::

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

registered as a device on this bus. Here, MP2 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

registers with the HID core. Transport layer attaches 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

This layer is responsible to implement HID requests 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

interface between MP2 PCIe layer and HID. HID client layer initializes the MP2 PCIe layer and holds

the instance of MP2 layer. It identifies the number of sensors connected using MP2-PCIe layer. Based

on that allocates the DRAM address for each and every sensor and passes it to MP2-PCIe driver. On

enumeration of each sensor, client layer fills the HID Descriptor structure and HID input report

structure. HID Feature report structure is optional. The report descriptor structure varies from

sensor to sensor.

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

Commands are sent to MP2 using C2P Mailbox registers. Writing into C2P Message registers generates

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

Command Read/Write

------------------

To read/write to RAM, need to send a commands to the device.

To read/write to RAM, need to send a command to the device.

The command format is as below.

an ambient light sensor can send illumination data.

So the implementation has two parts:

- Core hid driver

- Core HID driver

- Individual sensor processing part (sensor drivers)

Core driver

-----------

The core driver registers (hid-sensor-hub) registers as a HID driver. It parses

The core driver (hid-sensor-hub) registers as a HID driver. It parses

report descriptors and identifies all the sensors present. It adds an MFD device

with name HID-SENSOR-xxxx (where xxxx is usage id from the specification).

			u32 usage_id,

			struct hid_sensor_hub_callbacks *usage_callback):

Registers callbacks for an usage id. The callback functions are not allowed

Registers callbacks for a usage id. The callback functions are not allowed

to sleep::

  int sensor_hub_remove_callback(struct hid_sensor_hub_device *hsdev,

			u32 usage_id):

Removes callbacks for an usage id.

Removes callbacks for a usage id.

Parsing function::

Some common use cases are debug other sensors or to provide some events like

keyboard attached/detached or lid open/close.

To allow application to utilize these sensors, here they are exported uses sysfs

To allow application to utilize these sensors, here they are exported using sysfs

attribute groups, attributes and misc device interface.

An example of this representation on sysfs::

  │   │   │   ├── input-1-200202-units

  │   │   │   ├── input-1-200202-value

Here there is a custom sensors with four fields, two feature and two inputs.

Here there is a custom sensor with four fields: two feature and two inputs.

Each field is represented by a set of attributes. All fields except the "value"

are read only. The value field is a RW field.

are read only. The value field is a read-write field.

Example::

	│   │   │   ├── 10:53 -> ../HID-SENSOR-2000e1.6.auto

	│   ├──  HID-SENSOR-2000e1.6.auto

Each reports can be of variable length preceded by a header. This header

consist of a 32 bit usage id, 64 bit time stamp and 32 bit length field of raw

Each report can be of variable length preceded by a header. This header

consists of a 32-bit usage id, 64-bit time stamp and 32-bit length field of raw

data.

The HID subsystem is designed as a bus. Any I/O subsystem may provide HID

devices and register them with the HID bus. HID core then loads generic device

drivers on top of it. The transport drivers are responsible of raw data

transport and device setup/management. HID core is responsible of

drivers on top of it. The transport drivers are responsible for raw data

transport and device setup/management. HID core is responsible for

report-parsing, report interpretation and the user-space API. Device specifics

and quirks are handled by all layers depending on the quirk.

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.

Transport drivers are responsible of detecting device failures and unplugging.

Transport drivers are responsible for detecting device failures and unplugging.

HID core will operate a device as long as it is registered regardless of any

device failures. Once transport drivers detect unplug or failure events, they

must unregister the device from HID core and HID core will stop using the

   channel. Any unrequested incoming or outgoing data report must be sent on

   this channel and is never acknowledged by the remote side. Devices usually

   send their input events on this channel. Outgoing events are normally

   not send via intr, except if high throughput is required.

   not sent via intr, except if high throughput is required.

 - Control Channel (ctrl): The ctrl channel is used for synchronous requests and

   device management. Unrequested data input events must not be sent on this

   channel and are normally ignored. Instead, devices only send management

   payload may be blocked by the underlying transport driver if the

   specification does not allow them.

 - SET_REPORT: A SET_REPORT request has a report ID plus data as payload. It is

   sent from host to device and a device must update it's current report state

   sent from host to device and a device must update its current report state

   according to the given data. Any of the 3 report types can be used. However,

   INPUT reports as payload might be blocked by the underlying transport driver

   if the specification does not allow them.

      void (*request) (struct hid_device *hdev, struct hid_report *report,

		       int reqtype)

   Send an HID request on the ctrl channel. "report" contains the report that

   Send a HID request on the ctrl channel. "report" contains the report that

   should be sent and "reqtype" the request type. Request-type can be

   HID_REQ_SET_REPORT or HID_REQ_GET_REPORT.