| Message ID | 20201204062022.5095-1-rdunlap@infradead.org |
|---|---|
| Headers | show |
| Series | Documentation: HID: edit/correct all files | expand |
On Thu, 3 Dec 2020 22:20:16 -0800 Randy Dunlap <rdunlap@infradead.org> wrote: > Do basic editing & correction to amd-sfh-hid.rst: > - fix punctuation > - use HID instead of hid consistently > - fix grammar, verb tense > > Signed-off-by: Randy Dunlap <rdunlap@infradead.org> > Cc: Jiri Kosina <jikos@kernel.org> > Cc: Jonathan Cameron <jic23@kernel.org> > Cc: Srinivas Pandruvada <srinivas.pandruvada@linux.intel.com> > Cc: linux-input@vger.kernel.org > Cc: linux-iio@vger.kernel.org > Cc: Jonathan Corbet <corbet@lwn.net> > Cc: linux-doc@vger.kernel.org Trivial suggested addition inline. > --- > Documentation/hid/amd-sfh-hid.rst | 16 ++++++++-------- > 1 file changed, 8 insertions(+), 8 deletions(-) > > --- linux-next-20201201.orig/Documentation/hid/amd-sfh-hid.rst > +++ linux-next-20201201/Documentation/hid/amd-sfh-hid.rst > @@ -3,7 +3,7 @@ > > 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. > @@ -45,20 +45,20 @@ the HID reports are generated as part of > 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 > +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. Base Based ? (maybe) > -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 > +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. > > @@ -72,7 +72,7 @@ The communication between X86 and MP2 is > 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
On Thu, 3 Dec 2020 22:20:18 -0800 Randy Dunlap <rdunlap@infradead.org> wrote: > Do basic editing & correction to intel-ish-hid.rst: > - fix grammar, verb tense, punctutation, and word phrasing > - fix spellos > - hyphenate multi-word adjectives > - collapse 2 spaces to one space in the middle of sentences > - use "I2C" instead of lower-case letters (as Linux I2C does) > - change space indentation to tab > - use HID instead of hid consistently > - use a list so that some line items do not run together > - use "a UUID" instead of "an UUID" > > > Signed-off-by: Randy Dunlap <rdunlap@infradead.org> > Cc: Jiri Kosina <jikos@kernel.org> > Cc: Jonathan Cameron <jic23@kernel.org> > Cc: Srinivas Pandruvada <srinivas.pandruvada@linux.intel.com> > Cc: linux-input@vger.kernel.org > Cc: linux-iio@vger.kernel.org > Cc: Jonathan Corbet <corbet@lwn.net> > Cc: linux-doc@vger.kernel.org > --- > Documentation/hid/intel-ish-hid.rst | 74 +++++++++++++------------- > 1 file changed, 38 insertions(+), 36 deletions(-) > > --- linux-next-20201201.orig/Documentation/hid/intel-ish-hid.rst > +++ linux-next-20201201/Documentation/hid/intel-ish-hid.rst > @@ -4,19 +4,19 @@ Intel Integrated Sensor Hub (ISH) > > A sensor hub enables the ability to offload sensor polling and algorithm > processing to a dedicated low power co-processor. This allows the core > -processor to go into low power modes more often, resulting in the increased > +processor to go into low power modes more often, resulting in increased > battery life. > > -There are many vendors providing external sensor hubs confirming to HID > -Sensor usage tables, and used in several tablets, 2 in 1 convertible laptops > +There are many vendors providing external sensor hubs conforming to HID > +Sensor usage tables, and used in several tablets, 2-in-1 convertible laptops Does that sentence actually make sense? Perhaps.. There are many vendors providing external sensor hubs conforming to HID Sensor usage tables. These may be found in tablets, 2-in-1 convertible laptops ... > and embedded products. Linux had this support since Linux 3.9. > > Intel® introduced integrated sensor hubs as a part of the SoC starting from > Cherry Trail and now supported on multiple generations of CPU packages. There > are many commercial devices already shipped with Integrated Sensor Hubs (ISH). > -These ISH also comply to HID sensor specification, but the difference is the > +These ISH also comply to HID sensor specification, but the difference is the > transport protocol used for communication. The current external sensor hubs > -mainly use HID over i2C or USB. But ISH doesn't use either i2c or USB. > +mainly use HID over I2C or USB. But ISH doesn't use either I2C or USB. > > 1. Overview > =========== > @@ -35,7 +35,7 @@ for a very high speed communication:: > ----------------- ---------------------- > PCI PCI > ----------------- ---------------------- > - |Host controller| --> | ISH processor | > + |Host controller| --> | ISH processor | > ----------------- ---------------------- > USB Link > ----------------- ---------------------- > @@ -50,13 +50,13 @@ applications implemented in the firmware > The ISH allows multiple sensor management applications executing in the > firmware. Like USB endpoints the messaging can be to/from a client. As part of > enumeration process, these clients are identified. These clients can be simple > -HID sensor applications, sensor calibration application or senor firmware > +HID sensor applications, sensor calibration application or sensor firmware Plural vs singular messy in here. Probably just make all the applications plural. > update application. > > The implementation model is similar, like USB bus, ISH transport is also > implemented as a bus. Each client application executing in the ISH processor > is registered as a device on this bus. The driver, which binds each device > -(ISH HID driver) identifies the device type and registers with the hid core. > +(ISH HID driver) identifies the device type and registers with the HID core. > > 2. ISH Implementation: Block Diagram > ==================================== > @@ -104,7 +104,7 @@ is registered as a device on this bus. T > > The ISH is exposed as "Non-VGA unclassified PCI device" to the host. The PCI > product and vendor IDs are changed from different generations of processors. So > -the source code which enumerate drivers needs to update from generation to > +the source code which enumerates drivers needs to update from generation to > generation. > > 3.2 Inter Processor Communication (IPC) driver > @@ -112,41 +112,42 @@ generation. > > Location: drivers/hid/intel-ish-hid/ipc > > -The IPC message used memory mapped I/O. The registers are defined in > +The IPC message uses memory mapped I/O. The registers are defined in > hw-ish-regs.h. > > 3.2.1 IPC/FW message types > ^^^^^^^^^^^^^^^^^^^^^^^^^^ > > -There are two types of messages, one for management of link and other messages > -are to and from transport layers. > +There are two types of messages, one for management of link and another for > +messages to and from transport layers. > > TX and RX of Transport messages > ............................... > > -A set of memory mapped register offers support of multi byte messages TX and > -RX (E.g.IPC_REG_ISH2HOST_MSG, IPC_REG_HOST2ISH_MSG). The IPC layer maintains > -internal queues to sequence messages and send them in order to the FW. > +A set of memory mapped register offers support of multi-byte messages TX and > +RX (e.g. IPC_REG_ISH2HOST_MSG, IPC_REG_HOST2ISH_MSG). The IPC layer maintains > +internal queues to sequence messages and send them in order to the firmware. > Optionally the caller can register handler to get notification of completion. > -A door bell mechanism is used in messaging to trigger processing in host and > +A doorbell mechanism is used in messaging to trigger processing in host and > client firmware side. When ISH interrupt handler is called, the ISH2HOST > doorbell register is used by host drivers to determine that the interrupt > is for ISH. > > Each side has 32 32-bit message registers and a 32-bit doorbell. Doorbell > -register has the following format: > -Bits 0..6: fragment length (7 bits are used) > -Bits 10..13: encapsulated protocol > -Bits 16..19: management command (for IPC management protocol) > -Bit 31: doorbell trigger (signal H/W interrupt to the other side) > -Other bits are reserved, should be 0. > +register has the following format:: > + > + Bits 0..6: fragment length (7 bits are used) > + Bits 10..13: encapsulated protocol > + Bits 16..19: management command (for IPC management protocol) > + Bit 31: doorbell trigger (signal H/W interrupt to the other side) > + Other bits are reserved, should be 0. > > 3.2.2 Transport layer interface > ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ > > -To abstract HW level IPC communication, a set of callbacks are registered. > +To abstract HW level IPC communication, a set of callbacks is registered. > The transport layer uses them to send and receive messages. > -Refer to struct ishtp_hw_ops for callbacks. > +Refer to struct ishtp_hw_ops for callbacks. > > 3.3 ISH Transport layer > ----------------------- > @@ -158,7 +159,7 @@ Location: drivers/hid/intel-ish-hid/isht > > The transport layer is a bi-directional protocol, which defines: > - Set of commands to start, stop, connect, disconnect and flow control > -(ishtp/hbm.h) for details > +(see ishtp/hbm.h for details) > - A flow control mechanism to avoid buffer overflows > > This protocol resembles bus messages described in the following document: > @@ -168,14 +169,14 @@ specifications/dcmi-hi-1-0-spec.pdf "Cha > 3.3.2 Connection and Flow Control Mechanism > ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ > > -Each FW client and a protocol is identified by an UUID. In order to communicate > +Each FW client and a protocol is identified by a UUID. In order to communicate > to a FW client, a connection must be established using connect request and > response bus messages. If successful, a pair (host_client_id and fw_client_id) > will identify the connection. > > Once connection is established, peers send each other flow control bus messages > independently. Every peer may send a message only if it has received a > -flow-control credit before. Once it sent a message, it may not send another one > +flow-control credit before. Once it has sent a message, it may not send another one > before receiving the next flow control credit. > Either side can send disconnect request bus message to end communication. Also > the link will be dropped if major FW reset occurs. > @@ -209,7 +210,7 @@ and DMA_XFER_ACK act as ownership indica > At initial state all outgoing memory belongs to the sender (TX to host, RX to > FW), DMA_XFER transfers ownership on the region that contains ISHTP message to > the receiving side, DMA_XFER_ACK returns ownership to the sender. A sender > -needs not wait for previous DMA_XFER to be ack'ed, and may send another message > +need not wait for previous DMA_XFER to be ack'ed, and may send another message > as long as remaining continuous memory in its ownership is enough. > In principle, multiple DMA_XFER and DMA_XFER_ACK messages may be sent at once > (up to IPC MTU), thus allowing for interrupt throttling. > @@ -219,8 +220,8 @@ fragments and via IPC otherwise. > 3.3.4 Ring Buffers > ^^^^^^^^^^^^^^^^^^ > > -When a client initiate a connection, a ring or RX and TX buffers are allocated. > -The size of ring can be specified by the client. HID client set 16 and 32 for > +When a client initiates a connection, a ring of RX and TX buffers is allocated. > +The size of ring can be specified by the client. HID client sets 16 and 32 for > TX and RX buffers respectively. On send request from client, the data to be > sent is copied to one of the send ring buffer and scheduled to be sent using > bus message protocol. These buffers are required because the FW may have not > @@ -230,10 +231,10 @@ to send. Same thing holds true on receiv > 3.3.5 Host Enumeration > ^^^^^^^^^^^^^^^^^^^^^^ > > -The host enumeration bus command allow discovery of clients present in the FW. > +The host enumeration bus command allows discovery of clients present in the FW. > There can be multiple sensor clients and clients for calibration function. > > -To ease in implantation and allow independent driver handle each client > +To ease implementation and allow independent drivers to handle each client, > this transport layer takes advantage of Linux Bus driver model. Each > client is registered as device on the transport bus (ishtp bus). > > @@ -270,7 +271,7 @@ The ISHTP client driver is responsible f > The functionality in these drivers is the same as an external sensor hub. > Refer to > Documentation/hid/hid-sensor.rst for HID sensor > -Documentation/ABI/testing/sysfs-bus-iio for IIO ABIs to user space > +Documentation/ABI/testing/sysfs-bus-iio for IIO ABIs to user space. > > 3.6 End to End HID transport Sequence Diagram > --------------------------------------------- > @@ -341,9 +342,10 @@ Documentation/ABI/testing/sysfs-bus-iio > 3.7 ISH Debugging > ----------------- > > -To debug ISH, event tracing mechanism is used. To enable debug logs > -echo 1 > /sys/kernel/debug/tracing/events/intel_ish/enable > -cat sys/kernel/debug/tracing/trace > +To debug ISH, event tracing mechanism is used. To enable debug logs:: > + > + echo 1 > /sys/kernel/debug/tracing/events/intel_ish/enable > + cat sys/kernel/debug/tracing/trace > > 3.8 ISH IIO sysfs Example on Lenovo thinkpad Yoga 260 > -----------------------------------------------------
On 12/5/20 9:12 AM, Jonathan Cameron wrote: > On Thu, 3 Dec 2020 22:20:16 -0800 > Randy Dunlap <rdunlap@infradead.org> wrote: > >> Do basic editing & correction to amd-sfh-hid.rst: >> - fix punctuation >> - use HID instead of hid consistently >> - fix grammar, verb tense Hi Jonathan, Thanks for all the comments. I'll send a v2. -- ~Randy