On Thu, 3 Dec 2020 22:20:18 -0800 Randy Dunlap <rdunlap@xxxxxxxxxxxxx> 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@xxxxxxxxxxxxx> > Cc: Jiri Kosina <jikos@xxxxxxxxxx> > Cc: Jonathan Cameron <jic23@xxxxxxxxxx> > Cc: Srinivas Pandruvada <srinivas.pandruvada@xxxxxxxxxxxxxxx> > Cc: linux-input@xxxxxxxxxxxxxxx > Cc: linux-iio@xxxxxxxxxxxxxxx > Cc: Jonathan Corbet <corbet@xxxxxxx> > Cc: linux-doc@xxxxxxxxxxxxxxx > --- > 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 > -----------------------------------------------------
