From patchwork Mon Dec 28 20:53:20 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Randy Dunlap X-Patchwork-Id: 11991721 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-18.8 required=3.0 tests=BAYES_00,DKIM_SIGNED, DKIM_VALID,DKIM_VALID_AU,HEADER_FROM_DIFFERENT_DOMAINS,INCLUDES_CR_TRAILER, INCLUDES_PATCH,MAILING_LIST_MULTI,SPF_HELO_NONE,SPF_PASS,USER_AGENT_GIT autolearn=unavailable autolearn_force=no version=3.4.0 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id 5D3A9C00454 for ; Mon, 28 Dec 2020 23:13:16 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id 4794B223E8 for ; Mon, 28 Dec 2020 23:13:16 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1730823AbgL1Wzz (ORCPT ); Mon, 28 Dec 2020 17:55:55 -0500 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:37382 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1729467AbgL1UyV (ORCPT ); Mon, 28 Dec 2020 15:54:21 -0500 Received: from merlin.infradead.org (merlin.infradead.org [IPv6:2001:8b0:10b:1231::1]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 39D11C061793; Mon, 28 Dec 2020 12:53:41 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=infradead.org; s=merlin.20170209; h=Content-Transfer-Encoding:MIME-Version: References:In-Reply-To:Message-Id:Date:Subject:Cc:To:From:Sender:Reply-To: Content-Type:Content-ID:Content-Description; bh=+rwsPNKVBMsHPuzlmKq794q1bunkBRLuFJTK5VEEMG0=; b=Iuebx5jXtKym2o10SIBJ4sVe4a RT5SfT0TnwtfeaB7aW17oh2E9JA+2G11JWNGwS8gGPAHh8mFoc3oXaozrw5f5XAi6r4BGEr/P8Nq2 OXyx6hR1DCaP4ro32Z5i8ZeD40y8PGKTdRSCDwCKo/lJDfB+OJLEPRp1n57Eg9ow27rs9Zk5B6YAK bk7qjelrUUU73Ityncxu4yu5BxdY95BCOt8vKlEl/mq3pON/Q1Bjzvy43645IafL7M6I7uBCvud8m H5Bb42czwMYx5rEyXjM4KphXrx2usW6KifofdfxTdqVU9If4QMm6nAa18zTDLCWUP3dfcrhDaLSw4 gXqFJu5w==; Received: from [2601:1c0:6280:3f0::64ea] (helo=smtpauth.infradead.org) by merlin.infradead.org with esmtpsa (Exim 4.92.3 #3 (Red Hat Linux)) id 1ktzWM-0002ml-SL; Mon, 28 Dec 2020 20:53:39 +0000 From: Randy Dunlap To: linux-kernel@vger.kernel.org Cc: Randy Dunlap , Jiri Kosina , Benjamin Tissoires , linux-input@vger.kernel.org, Jonathan Cameron , Srinivas Pandruvada , linux-iio@vger.kernel.org, Jonathan Corbet , linux-doc@vger.kernel.org Subject: [PATCH v2 1/8] Documentation: HID: hid-alps editing & corrections Date: Mon, 28 Dec 2020 12:53:20 -0800 Message-Id: <20201228205327.1063-2-rdunlap@infradead.org> X-Mailer: git-send-email 2.26.2 In-Reply-To: <20201228205327.1063-1-rdunlap@infradead.org> References: <20201228205327.1063-1-rdunlap@infradead.org> MIME-Version: 1.0 Precedence: bulk List-ID: X-Mailing-List: linux-input@vger.kernel.org Do basic editing & correction to hid-alps.rst: - fix grammar - fix punctuation spacing Signed-off-by: Randy Dunlap Cc: Jiri Kosina Cc: Benjamin Tissoires Cc: linux-input@vger.kernel.org Cc: Jonathan Corbet Cc: Jonathan Cameron Cc: linux-doc@vger.kernel.org --- v2: rebase & resend Documentation/hid/hid-alps.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) --- linux-next-20201201.orig/Documentation/hid/hid-alps.rst +++ linux-next-20201201/Documentation/hid/hid-alps.rst @@ -64,7 +64,7 @@ Case2 ReportID_3 TP Absolute 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. @@ -80,7 +80,7 @@ Byte6 Value Byte Byte7 Checksum ===== ====================== -Command Byte is read=0xD1/write=0xD2 . +Command Byte is read=0xD1/write=0xD2. Address is read/write RAM address. From patchwork Mon Dec 28 20:53:21 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Randy Dunlap X-Patchwork-Id: 11991727 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-18.8 required=3.0 tests=BAYES_00,DKIM_SIGNED, DKIM_VALID,DKIM_VALID_AU,HEADER_FROM_DIFFERENT_DOMAINS,INCLUDES_CR_TRAILER, INCLUDES_PATCH,MAILING_LIST_MULTI,SPF_HELO_NONE,SPF_PASS,USER_AGENT_GIT autolearn=unavailable autolearn_force=no version=3.4.0 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id 17637C41621 for ; Mon, 28 Dec 2020 23:13:16 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id F2A8522AEC for ; Mon, 28 Dec 2020 23:13:15 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1730827AbgL1Wzz (ORCPT ); Mon, 28 Dec 2020 17:55:55 -0500 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:37390 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1729470AbgL1UyZ (ORCPT ); Mon, 28 Dec 2020 15:54:25 -0500 Received: from merlin.infradead.org (merlin.infradead.org [IPv6:2001:8b0:10b:1231::1]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id C5E97C061796; Mon, 28 Dec 2020 12:53:44 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=infradead.org; s=merlin.20170209; h=Content-Transfer-Encoding:MIME-Version: References:In-Reply-To:Message-Id:Date:Subject:Cc:To:From:Sender:Reply-To: Content-Type:Content-ID:Content-Description; bh=oC3WoNQlCXM7MybD3s/7U20d1WcH+cpXtHVbLSWjUK0=; b=wHFZt7Liyl33Qa9GjKF/hHVXzT 0L0fe6l8/gYx6wfdTBAzsXn2h+a6etKUfsC31Dbzq0VlJky87uS3NVX6XMnndu/LPX2fFuWiy2d1K GICr1BPvasvMugOeEFYd+dCuLvcthDZZLoeKX8OmsyRpeiFoTWtWIN7NSzeAWZbzZXM2uqtgnw0pr GT9B+lD1Ax4aEVuqFB/tkiEwxqrHonStwMbDOd0inGFxtKsvjGfs65dnZmoNNfYaXi2LgoDgM4YUB Khuiuu3QB3fVRKReYNOAyuPcJ2Is4HOOP0ivxzGWgEPV1D0RaU1e7w3Binnlp+7GKWcyFXQ2RxPfr ncN6NTkA==; Received: from [2601:1c0:6280:3f0::64ea] (helo=smtpauth.infradead.org) by merlin.infradead.org with esmtpsa (Exim 4.92.3 #3 (Red Hat Linux)) id 1ktzWQ-0002ml-EJ; Mon, 28 Dec 2020 20:53:42 +0000 From: Randy Dunlap To: linux-kernel@vger.kernel.org Cc: Randy Dunlap , Jiri Kosina , Benjamin Tissoires , linux-input@vger.kernel.org, Jonathan Cameron , Srinivas Pandruvada , linux-iio@vger.kernel.org, Jonathan Corbet , linux-doc@vger.kernel.org Subject: [PATCH v2 2/8] Documentation: HID: amd-sfh-hid editing & corrections Date: Mon, 28 Dec 2020 12:53:21 -0800 Message-Id: <20201228205327.1063-3-rdunlap@infradead.org> X-Mailer: git-send-email 2.26.2 In-Reply-To: <20201228205327.1063-1-rdunlap@infradead.org> References: <20201228205327.1063-1-rdunlap@infradead.org> MIME-Version: 1.0 Precedence: bulk List-ID: X-Mailing-List: linux-input@vger.kernel.org Do basic editing & correction to amd-sfh-hid.rst: - fix punctuation - use HID instead of hid consistently - fix grammar, verb tense - fix Block Diagram heading Signed-off-by: Randy Dunlap Cc: Jiri Kosina Cc: Jonathan Cameron Cc: Srinivas Pandruvada Cc: linux-input@vger.kernel.org Cc: linux-iio@vger.kernel.org Cc: Jonathan Corbet Cc: linux-doc@vger.kernel.org --- v2: Base -> Based (Jonathan Cameron) Change "1. Block Diagram" from a chapter heading to a section heading and remove its numbering. Documentation/hid/amd-sfh-hid.rst | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) --- lnx-511-rc1.orig/Documentation/hid/amd-sfh-hid.rst +++ lnx-511-rc1/Documentation/hid/amd-sfh-hid.rst @@ -3,13 +3,13 @@ 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 +------------- :: @@ -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 -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. @@ -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 From patchwork Mon Dec 28 20:53:22 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Randy Dunlap X-Patchwork-Id: 11991719 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-18.8 required=3.0 tests=BAYES_00,DKIM_SIGNED, DKIM_VALID,DKIM_VALID_AU,HEADER_FROM_DIFFERENT_DOMAINS,INCLUDES_CR_TRAILER, INCLUDES_PATCH,MAILING_LIST_MULTI,SPF_HELO_NONE,SPF_PASS,USER_AGENT_GIT autolearn=unavailable autolearn_force=no version=3.4.0 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id E62E4C433DB for ; Mon, 28 Dec 2020 23:13:15 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id C18662222A for ; Mon, 28 Dec 2020 23:13:15 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1729399AbgL1Wzz (ORCPT ); Mon, 28 Dec 2020 17:55:55 -0500 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:37404 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1729472AbgL1Uy2 (ORCPT ); Mon, 28 Dec 2020 15:54:28 -0500 Received: from merlin.infradead.org (merlin.infradead.org [IPv6:2001:8b0:10b:1231::1]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 554D3C061799; Mon, 28 Dec 2020 12:53:48 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=infradead.org; s=merlin.20170209; h=Content-Transfer-Encoding:MIME-Version: References:In-Reply-To:Message-Id:Date:Subject:Cc:To:From:Sender:Reply-To: Content-Type:Content-ID:Content-Description; bh=n2g1QeXFiuQZHIxa1jA2LknOcIv8elO1uDDgK0+qeTE=; b=2U1h3avIPKjzpeaYoIAzGsdkqY sD5/R41qG90WAojcpvzDVCP1gEqPgJCJgOXyZ9s13aqhD7/pGGWgtG87oANhHfnL3Q14mQoJEDTTY JyBZ2dScassFgqWvppDNgI77XPdClTDcJY8gLvBscpRp30zGG9XecRRFJCqegj3927QE4+L5amcTa CskUAmCNBKaCU0IsS9T6NMOHfC//l9IYezDTKiP1JN5OP0f4TuMUaUOgjnT7USs+ceVHuyWRBftLO kWtlqOfffD8AY487i8OoCvp27MY7XueOzU6feJHlUZdzS5aOsYl1LNhrWFbRS7eU92Y0wr9DaF7yV tLwaD01g==; Received: from [2601:1c0:6280:3f0::64ea] (helo=smtpauth.infradead.org) by merlin.infradead.org with esmtpsa (Exim 4.92.3 #3 (Red Hat Linux)) id 1ktzWT-0002ml-Vf; Mon, 28 Dec 2020 20:53:46 +0000 From: Randy Dunlap To: linux-kernel@vger.kernel.org Cc: Randy Dunlap , Jiri Kosina , Benjamin Tissoires , linux-input@vger.kernel.org, Jonathan Cameron , Srinivas Pandruvada , linux-iio@vger.kernel.org, Jonathan Corbet , linux-doc@vger.kernel.org Subject: [PATCH v2 3/8] Documentation: HID: hiddev editing & corrections Date: Mon, 28 Dec 2020 12:53:22 -0800 Message-Id: <20201228205327.1063-4-rdunlap@infradead.org> X-Mailer: git-send-email 2.26.2 In-Reply-To: <20201228205327.1063-1-rdunlap@infradead.org> References: <20201228205327.1063-1-rdunlap@infradead.org> MIME-Version: 1.0 Precedence: bulk List-ID: X-Mailing-List: linux-input@vger.kernel.org Do basic editing & correction to hiddev.rst: - use HID instead of hid consistently - add hyphenation of multi-word adjectives - drop a duplicate word - unhyphenate "a priori" Signed-off-by: Randy Dunlap Cc: Jiri Kosina Cc: Benjamin Tissoires Cc: linux-input@vger.kernel.org Cc: Jonathan Corbet Cc: linux-doc@vger.kernel.org Cc: Jonathan Cameron --- v2: leave hid-core in one place where it might be deliberate. (Jonathan=jic23) Documentation/hid/hiddev.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) --- lnx-511-rc1.orig/Documentation/hid/hiddev.rst +++ lnx-511-rc1/Documentation/hid/hiddev.rst @@ -27,7 +27,7 @@ the following:: --> hiddev.c ----> POWER / MONITOR CONTROL In addition, other subsystems (apart from USB) can potentially feed -events into the input subsystem, but these have no effect on the hid +events into the input subsystem, but these have no effect on the HID device interface. Using the HID Device Interface @@ -73,7 +73,7 @@ The hiddev API uses a read() interface, HID devices exchange data with the host computer using data bundles called "reports". Each report is divided into "fields", each of which can have one or more "usages". In the hid-core, -each one of these usages has a single signed 32 bit value. +each one of these usages has a single signed 32-bit value. read(): ------- @@ -113,7 +113,7 @@ HIDIOCAPPLICATION - (none) This ioctl call returns the HID application usage associated with the -hid device. The third argument to ioctl() specifies which application +HID device. The third argument to ioctl() specifies which application index to get. This is useful when the device has more than one application collection. If the index is invalid (greater or equal to the number of application collections this device has) the ioctl @@ -181,7 +181,7 @@ looked up by type (input, output or feat must be filled in by the user. The ID can be absolute -- the actual report id as reported by the device -- or relative -- HID_REPORT_ID_FIRST for the first report, and (HID_REPORT_ID_NEXT | -report_id) for the next report after report_id. Without a-priori +report_id) for the next report after report_id. Without a priori information about report ids, the right way to use this ioctl is to use the relative IDs above to enumerate the valid IDs. The ioctl returns non-zero when there is no more next ID. The real report ID is @@ -200,7 +200,7 @@ HIDIOCGUCODE - struct hiddev_usage_ref (read/write) Returns the usage_code in a hiddev_usage_ref structure, given that -given its report type, report id, field index, and index within the +its report type, report id, field index, and index within the field have already been filled into the structure. HIDIOCGUSAGE From patchwork Mon Dec 28 20:53:23 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Randy Dunlap X-Patchwork-Id: 11991723 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-18.8 required=3.0 tests=BAYES_00,DKIM_SIGNED, DKIM_VALID,DKIM_VALID_AU,HEADER_FROM_DIFFERENT_DOMAINS,INCLUDES_CR_TRAILER, INCLUDES_PATCH,MAILING_LIST_MULTI,SPF_HELO_NONE,SPF_PASS,USER_AGENT_GIT autolearn=unavailable autolearn_force=no version=3.4.0 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id 52572C4361B for ; Mon, 28 Dec 2020 23:13:15 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id 3845E22472 for ; Mon, 28 Dec 2020 23:13:15 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1730849AbgL1Wzz (ORCPT ); Mon, 28 Dec 2020 17:55:55 -0500 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:37486 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1729473AbgL1UzA (ORCPT ); Mon, 28 Dec 2020 15:55:00 -0500 Received: from merlin.infradead.org (merlin.infradead.org [IPv6:2001:8b0:10b:1231::1]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 24947C06179A; Mon, 28 Dec 2020 12:53:52 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=infradead.org; s=merlin.20170209; h=Content-Transfer-Encoding:Content-Type: MIME-Version:References:In-Reply-To:Message-Id:Date:Subject:Cc:To:From:Sender :Reply-To:Content-ID:Content-Description; bh=bm2bYWK54ciX6pTzTTOhAgf9duAyDKKypj0cfl6XYxg=; b=RbxN9ybFl8xZsAGAa7xFXs0zIG GkCYpbUiGtGOP1B5xCxWAzxa2cg3kth/kqqad8WeFMOCorP6LJq7tOdGsNdfbqQ7lmLKkL3RrAHMB MwYsBguQKmpVNStMXt1aj4BgNjM5awZL5m6cTjwfXjq5K/5mipOdvWX8Z90n4rPUsiR2j8yQogZj7 TKyLv3+5ArS2Kk7/7CWCpVvusdCDz4MWcIE55DRVECWyyRDWkyeaz3pp4GsrCLWmqZ71SuwnF3J6S Om2aSw3F4IEszlg7KxqD1/ABESkgVtVbcjQKfi41LUcNxJTAnTM609QzOEq8i2LlaF/AgCpd9U7Iq Gu8tuGeQ==; Received: from [2601:1c0:6280:3f0::64ea] (helo=smtpauth.infradead.org) by merlin.infradead.org with esmtpsa (Exim 4.92.3 #3 (Red Hat Linux)) id 1ktzWX-0002ml-HG; Mon, 28 Dec 2020 20:53:50 +0000 From: Randy Dunlap To: linux-kernel@vger.kernel.org Cc: Randy Dunlap , Jiri Kosina , Benjamin Tissoires , linux-input@vger.kernel.org, Jonathan Cameron , Srinivas Pandruvada , linux-iio@vger.kernel.org, Jonathan Corbet , linux-doc@vger.kernel.org Subject: [PATCH v2 4/8] Documentation: HID: intel-ish-hid editing & corrections Date: Mon, 28 Dec 2020 12:53:23 -0800 Message-Id: <20201228205327.1063-5-rdunlap@infradead.org> X-Mailer: git-send-email 2.26.2 In-Reply-To: <20201228205327.1063-1-rdunlap@infradead.org> References: <20201228205327.1063-1-rdunlap@infradead.org> MIME-Version: 1.0 Precedence: bulk List-ID: X-Mailing-List: linux-input@vger.kernel.org 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 Cc: Jiri Kosina Cc: Jonathan Cameron Cc: Srinivas Pandruvada Cc: linux-input@vger.kernel.org Cc: linux-iio@vger.kernel.org Cc: Jonathan Corbet Cc: linux-doc@vger.kernel.org --- v2: reword one sentence & use plural "applications" consistently in one paragraph. (thanks, Jonathan=jic32) Documentation/hid/intel-ish-hid.rst | 78 +++++++++++++------------- 1 file changed, 40 insertions(+), 38 deletions(-) --- lnx-511-rc1.orig/Documentation/hid/intel-ish-hid.rst +++ lnx-511-rc1/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 -and embedded products. Linux had this support since Linux 3.9. +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 has 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 -update application. +HID sensor applications, sensor calibration applications or sensor firmware +update applications. 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 ----------------------------------------------------- From patchwork Mon Dec 28 20:53:24 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Randy Dunlap X-Patchwork-Id: 11991717 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-18.8 required=3.0 tests=BAYES_00,DKIM_SIGNED, DKIM_VALID,DKIM_VALID_AU,HEADER_FROM_DIFFERENT_DOMAINS,INCLUDES_CR_TRAILER, INCLUDES_PATCH,MAILING_LIST_MULTI,SPF_HELO_NONE,SPF_PASS,USER_AGENT_GIT autolearn=unavailable autolearn_force=no version=3.4.0 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id 87A56C43142 for ; Mon, 28 Dec 2020 23:13:15 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id 64BA8222F9 for ; Mon, 28 Dec 2020 23:13:15 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1729537AbgL1Wzz (ORCPT ); Mon, 28 Dec 2020 17:55:55 -0500 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:37488 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1729474AbgL1UzA (ORCPT ); Mon, 28 Dec 2020 15:55:00 -0500 Received: from merlin.infradead.org (merlin.infradead.org [IPv6:2001:8b0:10b:1231::1]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id E9557C06179B; Mon, 28 Dec 2020 12:53:55 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=infradead.org; s=merlin.20170209; h=Content-Transfer-Encoding:MIME-Version: References:In-Reply-To:Message-Id:Date:Subject:Cc:To:From:Sender:Reply-To: Content-Type:Content-ID:Content-Description; bh=Ut9bABGWC1jsjzFpFRlCDxYQtxee7nxj5/jV/VNYK7Y=; b=VWj1smeQ7GlF5YUGH1riVLDy7g aJFaZUrwRBO0SFc7ClDV38IffzNz0VD9mTC4WdDtenQfNmWBCUFqsLmpFmeFW56pe1qa6KgU/fQG7 5hyJ4cl3k1koHfnSRLdbYHgvn0D8XXhdDTXZZo8KDAsspScD77Sz8nBRsrIizAoWsNFcuBlprf16n JAaUgsXi5fp01xf15CW/aGg13ICXliMQQVq40hvIS0c7UYBHuKTvmzkJAC4R17DJURZKxTLNYIDS2 h/99b+i7ajybvkYGaHGkeuhW0hvHeGtjth6XE7oWprizsGOinuKFZiIXQFj/e8zVLW2Iuy85jYsIU 2MnrPYUQ==; Received: from [2601:1c0:6280:3f0::64ea] (helo=smtpauth.infradead.org) by merlin.infradead.org with esmtpsa (Exim 4.92.3 #3 (Red Hat Linux)) id 1ktzWb-0002ml-IZ; Mon, 28 Dec 2020 20:53:54 +0000 From: Randy Dunlap To: linux-kernel@vger.kernel.org Cc: Randy Dunlap , Jiri Kosina , Benjamin Tissoires , linux-input@vger.kernel.org, Jonathan Cameron , Srinivas Pandruvada , linux-iio@vger.kernel.org, Jonathan Corbet , linux-doc@vger.kernel.org, Alan Ott Subject: [PATCH v2 5/8] Documentation: HID: hidraw editing & corrections Date: Mon, 28 Dec 2020 12:53:24 -0800 Message-Id: <20201228205327.1063-6-rdunlap@infradead.org> X-Mailer: git-send-email 2.26.2 In-Reply-To: <20201228205327.1063-1-rdunlap@infradead.org> References: <20201228205327.1063-1-rdunlap@infradead.org> MIME-Version: 1.0 Precedence: bulk List-ID: X-Mailing-List: linux-input@vger.kernel.org Do basic editing & correction to hidraw.rst: - use "hidraw" consistently except at the beginning of a sentence - add archive.org URL for signal11.us since the latter seems to be MIA - use a list for 2 URLs so that they don't run together Signed-off-by: Randy Dunlap Cc: Jiri Kosina Cc: Benjamin Tissoires Cc: linux-input@vger.kernel.org Cc: Alan Ott Cc: Jonathan Corbet Cc: linux-doc@vger.kernel.org Cc: Jonathan Cameron --- v2: rebase & resend Documentation/hid/hidraw.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) --- linux-next-20201201.orig/Documentation/hid/hidraw.rst +++ linux-next-20201201/Documentation/hid/hidraw.rst @@ -21,7 +21,7 @@ Hidraw is the only alternative, short of these non-conformant devices. A benefit of hidraw is that its use by userspace applications is independent -of the underlying hardware type. Currently, Hidraw is implemented for USB +of the underlying hardware type. Currently, hidraw is implemented for USB and Bluetooth. In the future, as new hardware bus types are developed which use the HID specification, hidraw will be expanded to add support for these new bus types. @@ -31,9 +31,10 @@ create hidraw device nodes. Udev will t directly under /dev (eg: /dev/hidraw0). As this location is distribution- and udev rule-dependent, applications should use libudev to locate hidraw devices attached to the system. There is a tutorial on libudev with a -working example at: +working example at:: http://www.signal11.us/oss/udev/ + https://web.archive.org/web/2019*/www.signal11.us The HIDRAW API --------------- From patchwork Mon Dec 28 20:53:25 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Randy Dunlap X-Patchwork-Id: 11991715 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-18.8 required=3.0 tests=BAYES_00,DKIM_SIGNED, DKIM_VALID,DKIM_VALID_AU,HEADER_FROM_DIFFERENT_DOMAINS,INCLUDES_CR_TRAILER, INCLUDES_PATCH,MAILING_LIST_MULTI,SPF_HELO_NONE,SPF_PASS,USER_AGENT_GIT autolearn=unavailable autolearn_force=no version=3.4.0 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id 345DCC4321A for ; Mon, 28 Dec 2020 23:13:15 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id 0E65B207BC for ; Mon, 28 Dec 2020 23:13:15 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1730854AbgL1Wzz (ORCPT ); Mon, 28 Dec 2020 17:55:55 -0500 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:37494 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1729479AbgL1UzB (ORCPT ); Mon, 28 Dec 2020 15:55:01 -0500 Received: from merlin.infradead.org (merlin.infradead.org [IPv6:2001:8b0:10b:1231::1]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 783C4C06179C; Mon, 28 Dec 2020 12:53:59 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=infradead.org; s=merlin.20170209; h=Content-Transfer-Encoding:Content-Type: MIME-Version:References:In-Reply-To:Message-Id:Date:Subject:Cc:To:From:Sender :Reply-To:Content-ID:Content-Description; bh=jxcoirwNsws6Zv9ld1/PoV2C86xILuKjmcTb6I37tFA=; b=tRb51Nvl8tN/RsYHQb6r6vCrKj JA85LVcBx7PMPnFiK1SP1YH0Og7aza5wDsDno0Ox9ssdfEBSXUcWwK0YUbVIIHQA41HiNQMr8sg/D RvIvM1mg76dGFqjqF2OCj/69FPpAIQTdAzcvoJlr+pMLSrjTavY5hbaTBp8b5nmEf75amTTOaLPm2 6t0iJ8esNJTvQryf/XD6yl/VZl+Z6ZJ7iTOskREUgOOOKMj2YLCoXhlywH8WWG9D/dVKHP9gKpxWG NL6DPXf+F43Ra/hjtKV77FHNO4T2goUMpWSoEIbRv14Dtfp0HILKdZmZdUxQmen1Q782hp6jTbTf3 z4LZtHjg==; Received: from [2601:1c0:6280:3f0::64ea] (helo=smtpauth.infradead.org) by merlin.infradead.org with esmtpsa (Exim 4.92.3 #3 (Red Hat Linux)) id 1ktzWf-0002ml-3r; Mon, 28 Dec 2020 20:53:57 +0000 From: Randy Dunlap To: linux-kernel@vger.kernel.org Cc: Randy Dunlap , Jiri Kosina , Benjamin Tissoires , linux-input@vger.kernel.org, Jonathan Cameron , Srinivas Pandruvada , linux-iio@vger.kernel.org, Jonathan Corbet , linux-doc@vger.kernel.org Subject: [PATCH v2 6/8] Documentation: HID: hid-sensor editing & corrections Date: Mon, 28 Dec 2020 12:53:25 -0800 Message-Id: <20201228205327.1063-7-rdunlap@infradead.org> X-Mailer: git-send-email 2.26.2 In-Reply-To: <20201228205327.1063-1-rdunlap@infradead.org> References: <20201228205327.1063-1-rdunlap@infradead.org> MIME-Version: 1.0 Precedence: bulk List-ID: X-Mailing-List: linux-input@vger.kernel.org Do basic editing & correction to hid-sensor.rst: - use HID consistently instead of hid - drop a duplicate word - change article adjective an -> a - fix grammar & punctuation - spell out RW -> read-write - hyphenate multi-word adjectives Signed-off-by: Randy Dunlap Cc: Jiri Kosina Cc: Jonathan Cameron Cc: Srinivas Pandruvada Cc: linux-input@vger.kernel.org Cc: linux-iio@vger.kernel.org Cc: Jonathan Corbet Cc: linux-doc@vger.kernel.org --- v2: rebase & resend Documentation/hid/hid-sensor.rst | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) --- linux-next-20201201.orig/Documentation/hid/hid-sensor.rst +++ linux-next-20201201/Documentation/hid/hid-sensor.rst @@ -48,12 +48,12 @@ for different sensors. For example an ac 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). @@ -95,14 +95,14 @@ Registration functions:: 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:: @@ -166,7 +166,7 @@ This allows some differentiating use cas 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:: @@ -207,9 +207,9 @@ An example of this representation on sys │   │   │   ├── 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:: @@ -237,6 +237,6 @@ These reports are pushed using misc devi │   │   │   ├── 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. From patchwork Mon Dec 28 20:53:26 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Randy Dunlap X-Patchwork-Id: 11991729 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-18.8 required=3.0 tests=BAYES_00,DKIM_SIGNED, DKIM_VALID,DKIM_VALID_AU,HEADER_FROM_DIFFERENT_DOMAINS,INCLUDES_CR_TRAILER, INCLUDES_PATCH,MAILING_LIST_MULTI,SPF_HELO_NONE,SPF_PASS,USER_AGENT_GIT autolearn=unavailable autolearn_force=no version=3.4.0 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id DF69CC064F9 for ; Mon, 28 Dec 2020 23:13:16 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id B6B78207BC for ; Mon, 28 Dec 2020 23:13:16 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1730860AbgL1Wz4 (ORCPT ); Mon, 28 Dec 2020 17:55:56 -0500 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:37496 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1729480AbgL1UzC (ORCPT ); Mon, 28 Dec 2020 15:55:02 -0500 Received: from merlin.infradead.org (merlin.infradead.org [IPv6:2001:8b0:10b:1231::1]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 4E7B7C06179E; Mon, 28 Dec 2020 12:54:03 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=infradead.org; s=merlin.20170209; h=Content-Transfer-Encoding:MIME-Version: References:In-Reply-To:Message-Id:Date:Subject:Cc:To:From:Sender:Reply-To: Content-Type:Content-ID:Content-Description; bh=8CMWYsMwMNJcHOJEqyPOEiHxBkh09c3+kBqMOFU54lQ=; b=ZDbK5UtbsiPhwP/bG0qzhJ2cDP fEdBRksLxERWnNTvtOuslAtaLL2M3SkjKG2hB2FsAQYd7ns+lquPrYC0f1RjukqWrcRN8MTqZ7/m2 lKTfSyHMM0bZJRBEKmtzfpu++RPFk3mriWb9YUKukC4zACj+xllud797/IZ0hsetzjLgqD7Dlog3q GTQyOWuLuXSM2+IXgASykZaynBf5m0N52vDizRP5GikZ/3cXdnLOZaueIUFBX+Bgb+uBYaXQldplq vBtIj7vZ8YRfhFKnLW/EgA19eQyUBlUACeLrHrU7KjvyOItUQaR3VQ6ZPDNCI9K3lzLMToKVuIiRm QX8MAEqg==; Received: from [2601:1c0:6280:3f0::64ea] (helo=smtpauth.infradead.org) by merlin.infradead.org with esmtpsa (Exim 4.92.3 #3 (Red Hat Linux)) id 1ktzWi-0002ml-Tq; Mon, 28 Dec 2020 20:54:01 +0000 From: Randy Dunlap To: linux-kernel@vger.kernel.org Cc: Randy Dunlap , Jiri Kosina , Benjamin Tissoires , linux-input@vger.kernel.org, Jonathan Cameron , Srinivas Pandruvada , linux-iio@vger.kernel.org, Jonathan Corbet , linux-doc@vger.kernel.org, David Herrmann Subject: [PATCH v2 7/8] Documentation: HID: hid-transport editing & corrections Date: Mon, 28 Dec 2020 12:53:26 -0800 Message-Id: <20201228205327.1063-8-rdunlap@infradead.org> X-Mailer: git-send-email 2.26.2 In-Reply-To: <20201228205327.1063-1-rdunlap@infradead.org> References: <20201228205327.1063-1-rdunlap@infradead.org> MIME-Version: 1.0 Precedence: bulk List-ID: X-Mailing-List: linux-input@vger.kernel.org Do basic editing & correction to hid-transport.rst: - s/responsible of/responsible for/ - fix grammar & punctuation Signed-off-by: Randy Dunlap Cc: Jiri Kosina Cc: Benjamin Tissoires Cc: linux-input@vger.kernel.org Cc: David Herrmann Cc: Jonathan Corbet Cc: linux-doc@vger.kernel.org Cc: Jonathan Cameron --- v2: rebase & resend Documentation/hid/hid-transport.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) --- linux-next-20201201.orig/Documentation/hid/hid-transport.rst +++ linux-next-20201201/Documentation/hid/hid-transport.rst @@ -12,8 +12,8 @@ Bluetooth, I2C and user-space I/O driver 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. @@ -67,7 +67,7 @@ Transport drivers attach a constant "str 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 @@ -101,7 +101,7 @@ properties in common. 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 @@ -161,7 +161,7 @@ allowed on the intr channel and are the 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. @@ -294,7 +294,7 @@ The available HID callbacks are: 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. From patchwork Mon Dec 28 20:53:27 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Randy Dunlap X-Patchwork-Id: 11991713 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-18.8 required=3.0 tests=BAYES_00,DKIM_SIGNED, DKIM_VALID,DKIM_VALID_AU,HEADER_FROM_DIFFERENT_DOMAINS,INCLUDES_CR_TRAILER, INCLUDES_PATCH,MAILING_LIST_MULTI,SPF_HELO_NONE,SPF_PASS,USER_AGENT_GIT autolearn=unavailable autolearn_force=no version=3.4.0 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id 525D5C4332E for ; Mon, 28 Dec 2020 23:12:26 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id 181162222A for ; Mon, 28 Dec 2020 23:12:26 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1729400AbgL1Wz4 (ORCPT ); Mon, 28 Dec 2020 17:55:56 -0500 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:37504 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1729481AbgL1UzF (ORCPT ); Mon, 28 Dec 2020 15:55:05 -0500 Received: from merlin.infradead.org (merlin.infradead.org [IPv6:2001:8b0:10b:1231::1]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 0E076C06179F; Mon, 28 Dec 2020 12:54:07 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=infradead.org; s=merlin.20170209; h=Content-Transfer-Encoding:MIME-Version: References:In-Reply-To:Message-Id:Date:Subject:Cc:To:From:Sender:Reply-To: Content-Type:Content-ID:Content-Description; bh=ppRSnb5Uz4jIDnyS28Gp9E63hTbg6xv1tyWfwaISO2E=; b=aaRSuaaT0OUxbLka9O/IWIfosq 9feyWDp5ilTRnODWdjvuQFzQeQoWWurQdYN3NJ0sgB519+MJD6GeHo0hyB+sILQYlyOCg3IQvl4dk NMGpaEKhSLOkPWsH0CDWReXxsRJmGFwGJxn9dkWs04dmckUOn4dI8rF60EmLqQPmulM3Z7h3Madn0 hjpLZPZ/EP8zYNtTx/n6rkVnsT6iSSwOx01+xLV20G0uSD2xU2S8iPbUV/cm/AD8ccecg18rBGSnh Dray8JDH1B7PlejrGT/0f6/6M7ouTAYHOi1mR+JunbWzkwctpbCNERBewGK8ZoRKpPRoBacHqufDs z52O4mYA==; Received: from [2601:1c0:6280:3f0::64ea] (helo=smtpauth.infradead.org) by merlin.infradead.org with esmtpsa (Exim 4.92.3 #3 (Red Hat Linux)) id 1ktzWm-0002ml-MW; Mon, 28 Dec 2020 20:54:05 +0000 From: Randy Dunlap To: linux-kernel@vger.kernel.org Cc: Randy Dunlap , Jiri Kosina , Benjamin Tissoires , linux-input@vger.kernel.org, Jonathan Cameron , Srinivas Pandruvada , linux-iio@vger.kernel.org, Jonathan Corbet , linux-doc@vger.kernel.org, David Herrmann Subject: [PATCH v2 8/8] Documentation: HID: uhid editing & corrections Date: Mon, 28 Dec 2020 12:53:27 -0800 Message-Id: <20201228205327.1063-9-rdunlap@infradead.org> X-Mailer: git-send-email 2.26.2 In-Reply-To: <20201228205327.1063-1-rdunlap@infradead.org> References: <20201228205327.1063-1-rdunlap@infradead.org> MIME-Version: 1.0 Precedence: bulk List-ID: X-Mailing-List: linux-input@vger.kernel.org Do basic editing & correction to hid-alps.rst: - correct a file name (.txt -> .rst) - use less hyphenation when not needed - fix grammar & punctuation - fix article adjectives - fix typos/spellos - use HID instead of hid consistently Signed-off-by: Randy Dunlap Cc: Jiri Kosina Cc: Benjamin Tissoires Cc: linux-input@vger.kernel.org Cc: David Herrmann Cc: Jonathan Corbet Cc: linux-doc@vger.kernel.org Cc: Jonathan Cameron --- v2: rebase & resend Documentation/hid/uhid.rst | 34 +++++++++++++++++----------------- 1 file changed, 17 insertions(+), 17 deletions(-) --- linux-next-20201201.orig/Documentation/hid/uhid.rst +++ linux-next-20201201/Documentation/hid/uhid.rst @@ -3,7 +3,7 @@ UHID - User-space I/O driver support for ====================================================== UHID allows user-space to implement HID transport drivers. Please see -hid-transport.txt for an introduction into HID transport drivers. This document +hid-transport.rst for an introduction into HID transport drivers. This document relies heavily on the definitions declared there. With UHID, a user-space transport driver can create kernel hid-devices for each @@ -15,7 +15,7 @@ There is an example user-space applicati The UHID API ------------ -UHID is accessed through a character misc-device. The minor-number is allocated +UHID is accessed through a character misc-device. The minor number is allocated dynamically so you need to rely on udev (or similar) to create the device node. This is /dev/uhid by default. @@ -45,23 +45,23 @@ The "type" field defines the payload. Fo payload-structure available in the union "u" (except for empty payloads). This payload contains management and/or device data. -The first thing you should do is sending an UHID_CREATE2 event. This will -register the device. UHID will respond with an UHID_START event. You can now +The first thing you should do is send a UHID_CREATE2 event. This will +register the device. UHID will respond with a UHID_START event. You can now start sending data to and reading data from UHID. However, unless UHID sends the UHID_OPEN event, the internally attached HID Device Driver has no user attached. That is, you might put your device asleep unless you receive the UHID_OPEN event. If you receive the UHID_OPEN event, you should start I/O. If the last -user closes the HID device, you will receive an UHID_CLOSE event. This may be -followed by an UHID_OPEN event again and so on. There is no need to perform +user closes the HID device, you will receive a UHID_CLOSE event. This may be +followed by a UHID_OPEN event again and so on. There is no need to perform reference-counting in user-space. That is, you will never receive multiple -UHID_OPEN events without an UHID_CLOSE event. The HID subsystem performs +UHID_OPEN events without a UHID_CLOSE event. The HID subsystem performs ref-counting for you. You may decide to ignore UHID_OPEN/UHID_CLOSE, though. I/O is allowed even though the device may have no users. If you want to send data on the interrupt channel to the HID subsystem, you send -an HID_INPUT2 event with your raw data payload. If the kernel wants to send data -on the interrupt channel to the device, you will read an UHID_OUTPUT event. +a HID_INPUT2 event with your raw data payload. If the kernel wants to send data +on the interrupt channel to the device, you will read a UHID_OUTPUT event. Data requests on the control channel are currently limited to GET_REPORT and SET_REPORT (no other data reports on the control channel are defined so far). Those requests are always synchronous. That means, the kernel sends @@ -71,7 +71,7 @@ the response via UHID_GET_REPORT_REPLY a The kernel blocks internal driver-execution during such round-trips (times out after a hard-coded period). -If your device disconnects, you should send an UHID_DESTROY event. This will +If your device disconnects, you should send a UHID_DESTROY event. This will unregister the device. You can now send UHID_CREATE2 again to register a new device. If you close() the fd, the device is automatically unregistered and destroyed @@ -125,7 +125,7 @@ UHID_START: This is sent when the HID device is started. Consider this as an answer to UHID_CREATE2. This is always the first event that is sent. Note that this event might not be available immediately after write(UHID_CREATE2) returns. - Device drivers might required delayed setups. + Device drivers might require delayed setups. This event contains a payload of type uhid_start_req. The "dev_flags" field describes special behaviors of a device. The following flags are defined: @@ -149,7 +149,7 @@ UHID_STOP: reloaded/changed the device driver loaded on your HID device (or some other maintenance actions happened). - You can usually ignored any UHID_STOP events safely. + You can usually ignore any UHID_STOP events safely. UHID_OPEN: This is sent when the HID device is opened. That is, the data that the HID @@ -166,17 +166,17 @@ UHID_OUTPUT: This is sent if the HID device driver wants to send raw data to the I/O device on the interrupt channel. You should read the payload and forward it to the device. The payload is of type "struct uhid_output_req". - This may be received even though you haven't received UHID_OPEN, yet. + This may be received even though you haven't received UHID_OPEN yet. UHID_GET_REPORT: This event is sent if the kernel driver wants to perform a GET_REPORT request - on the control channeld as described in the HID specs. The report-type and + on the control channel as described in the HID specs. The report-type and report-number are available in the payload. The kernel serializes GET_REPORT requests so there will never be two in parallel. However, if you fail to respond with a UHID_GET_REPORT_REPLY, the request might silently time out. - Once you read a GET_REPORT request, you shall forward it to the hid device and - remember the "id" field in the payload. Once your hid device responds to the + Once you read a GET_REPORT request, you shall forward it to the HID device and + remember the "id" field in the payload. Once your HID device responds to the GET_REPORT (or if it fails), you must send a UHID_GET_REPORT_REPLY to the kernel with the exact same "id" as in the request. If the request already timed out, the kernel will ignore the response silently. The "id" field is @@ -184,7 +184,7 @@ UHID_GET_REPORT: UHID_SET_REPORT: This is the SET_REPORT equivalent of UHID_GET_REPORT. On receipt, you shall - send a SET_REPORT request to your hid device. Once it replies, you must tell + send a SET_REPORT request to your HID device. Once it replies, you must tell the kernel about it via UHID_SET_REPORT_REPLY. The same restrictions as for UHID_GET_REPORT apply.