linux-kernel - [PATCH v4 1/2] platform/chrome: wilco_ec: Fix documentation for debugfs raw attribute

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [thread-next>] [day] [month] [year] [list]

Message-Id: <20190412181443.239166-1-ncrews@chromium.org>
Date:   Fri, 12 Apr 2019 12:14:42 -0600
From:   Nick Crews <ncrews@...omium.org>
To:     enric.balletbo@...labora.com, bleung@...omium.org
Cc:     linux-kernel@...r.kernel.org, dlaurie@...omium.org,
        derat@...gle.com, groeck@...gle.com, dtor@...gle.com,
        sjg@...omium.org, alevkoy@...omium.org, keithshort@...omium.org,
        Nick Crews <ncrews@...omium.org>
Subject: [PATCH v4 1/2] platform/chrome: wilco_ec: Fix documentation for debugfs raw attribute

In a previous refactor [repo chrome-platform, branch for-next,
commit 9cced499d6fdb60434ffa94f8f4b5087ad35802b
("platform/chrome: wilco_ec: Standardize mailbox interface")], the
documentation for the raw debugfs attribute became incorrect, but I
forgot to fix it. This patch fixes it, as well as de-duplicates
the documentation by removing it from the source file header comment.

Signed-off-by: Nick Crews <ncrews@...omium.org>
---
 Documentation/ABI/testing/debugfs-wilco-ec | 32 ++++++++++++++--------
 drivers/platform/chrome/wilco_ec/debugfs.c | 27 +-----------------
 2 files changed, 22 insertions(+), 37 deletions(-)

diff --git a/Documentation/ABI/testing/debugfs-wilco-ec b/Documentation/ABI/testing/debugfs-wilco-ec
index f814f112e213..7ff6b45be703 100644
--- a/Documentation/ABI/testing/debugfs-wilco-ec
+++ b/Documentation/ABI/testing/debugfs-wilco-ec
@@ -4,20 +4,30 @@ KernelVersion:	5.1
 Description:
 		Write and read raw mailbox commands to the EC.
 
-		For writing:
-		Bytes 0-1 indicate the message type:
-			00 F0 = Execute Legacy Command
-			00 F2 = Read/Write NVRAM Property
-		Byte 2 provides the command code
-		Bytes 3+ consist of the data passed in the request
+		You can write a hexadecimal sentence to raw, and that series of
+		bytes will be sent to the EC. Then, you can read the bytes of
+		response by reading from raw.
 
-		At least three bytes are required, for the msg type and command,
-		with additional bytes optional for additional data.
+		For writing, bytes 0-1 indicate the message type, one of enum
+		wilco_ec_msg_type. Byte 2+ consist of the data passed in the
+		request, starting at MBOX[0]
+
+		At least three bytes are required for writing, two for the type
+		and at least a single byte of data. Only the first
+		EC_MAILBOX_DATA_SIZE bytes of MBOX will be used.
 
 		Example:
 		// Request EC info type 3 (EC firmware build date)
-		$ echo 00 f0 38 00 03 00 > raw
+		// Corresponds with sending type 0x00f0 with
+		// MBOX = [38, 00, 03, 00]
+		$ echo 00 f0 38 00 03 00 > /sys/kernel/debug/wilco_ec/raw
 		// View the result. The decoded ASCII result "12/21/18" is
 		// included after the raw hex.
-		$ cat raw
-		00 31 32 2f 32 31 2f 31 38 00 38 00 01 00 2f 00  .12/21/18.8...
+		// Corresponds with MBOX = [00, 00, 31, 32, 2f, 32, 31, 38, ...]
+		$ cat /sys/kernel/debug/wilco_ec/raw
+		00 00 31 32 2f 32 31 2f 31 38 00 38 00 01 00 2f 00  ..12/21/18.8...
+
+		Note that the first 32 bytes of the received MBOX[] will be
+		printed, even if some of the data is junk. It is up to you to
+		know how many of the first bytes of data are the actual
+		response.
diff --git a/drivers/platform/chrome/wilco_ec/debugfs.c b/drivers/platform/chrome/wilco_ec/debugfs.c
index 17c4c9068aaf..8d307378c1cb 100644
--- a/drivers/platform/chrome/wilco_ec/debugfs.c
+++ b/drivers/platform/chrome/wilco_ec/debugfs.c
@@ -4,32 +4,7 @@
  *
  * Copyright 2019 Google LLC
  *
- * There is only one attribute used for debugging, called raw.
- * You can write a hexadecimal sentence to raw, and that series of bytes
- * will be sent to the EC. Then, you can read the bytes of response
- * by reading from raw.
- *
- * For writing:
- * Bytes 0-1 indicate the message type, one of enum wilco_ec_msg_type
- * Byte 2+ consist of the data passed in the request, starting at MBOX[0]
- *
- * At least three bytes are required for writing, two for the type and at
- * least a single byte of data. Only the first EC_MAILBOX_DATA_SIZE bytes
- * of MBOX will be used.
- *
- * Example:
- * // Request EC info type 3 (EC firmware build date)
- * // Corresponds with sending type 0x00f0 with MBOX = [38, 00, 03, 00]
- * $ echo 00 f0 38 00 03 00 > /sys/kernel/debug/wilco_ec/raw
- * // View the result. The decoded ASCII result "12/21/18" is
- * // included after the raw hex.
- * // Corresponds with MBOX = [00, 00, 31, 32, 2f, 32, 31, ...]
- * $ cat /sys/kernel/debug/wilco_ec/raw
- * 00 00 31 32 2f 32 31 2f 31 38 00 38 00 01 00 2f 00  ..12/21/18.8...
- *
- * Note that the first 32 bytes of the received MBOX[] will be printed,
- * even if some of the data is junk. It is up to you to know how many of
- * the first bytes of data are the actual response.
+ * See Documentation/ABI/testing/debugfs-wilco-ec for usage.
  */
 
 #include <linux/ctype.h>
-- 
2.20.1