Skip to contentSkip to conversation

platform/chrome: wilco_ec: Standardize mailbox interface

PATCH In review Nick Crews 2 participants 5 messages Apr 5, 2019

Subsystems (2)
lore
Share & tools
lore

Nick Crews

author
#0 lore raw

PATCH 1/3 platform/chrome: wilco_ec: Standardize mailbox interface

The current API for the wilco EC mailbox interface is bad.

It assumes that most messages sent to the EC follow a similar structure, with a command byte in MBOX[0], followed by a junk byte, followed by actual data. This doesn't happen in several cases, such as setting the RTC time, using the raw debugfs interface, and reading or writing properties such as the Peak Shift policy (this last to be submitted soon).

Similarly for the response message from the EC, the current interface assumes that the first byte of data is always 0, and the second byte is unused. However, in both setting and getting the RTC time, in the debugfs interface, and for reading and writing properties, this isn't true.

The current way to resolve this is to use WILCO_EC_FLAG_RAW* flags to specify when and when not to skip these initial bytes in the sent and received message. They are confusing and used so much that they are normal, and not exceptions. In addition, the first byte of response in the debugfs interface is still always skipped, which is weird, since this raw interface should be giving the entire result.

Additionally, sent messages assume the first byte is a command, and so struct wilco_ec_message contains the "command" field. In setting or getting properties however, the first byte is not a command, and so this field has to be filled with a byte that isn't actually a command. This is again inconsistent.

wilco_ec_message contains a result field as well, copied from wilco_ec_response->result. The message result field should be removed:
if the message fails, the cause is already logged, and the callers are alerted. They will never care about the actual state of the result flag.

These flags and different cases make the wilco_ec_transfer() function, used in wilco_ec_mailbox(), really gross, dealing with a bunch of different cases. It's difficult to figure out what it is doing.

Finally, making these assumptions about the structure of a message make it so that the messages do not correspond well with the specification for the EC's mailbox interface. For instance, this interface specification may say that MBOX[9] in the received message contains some information, but the calling code needs to remember that the first byte of response is always skipped, and because it didn't set the RESPONSE_RAW flag, the next byte is also skipped, so this information is actually contained within wilco_ec_message->response_data[7]. This makes it difficult to maintain this code in the future.

To fix these problems this patch standardizes the mailbox interface by:
- Removing the WILCO_EC_FLAG_RAW* flags
- Removing the command and reserved_raw bytes from wilco_ec_request
- Removing the mbox0 byte from wilco_ec_response
- Simplifying wilco_ec_transfer() because of these changes
- Gives the callers of wilco_ec_mailbox() the responsibility of exactly and consistently defining the structure of the mailbox request and response
- Removing command and result from wilco_ec_message.

This results in the reduction of total code, and makes it much more maintainable and understandable.

---
 drivers/platform/chrome/wilco_ec/debugfs.c | 43 ++++++++-------
 drivers/platform/chrome/wilco_ec/mailbox.c | 53 ++++++++----------
 drivers/rtc/rtc-wilco-ec.c                 | 63 +++++++++++++---------
 include/linux/platform_data/wilco-ec.h     | 22 +-------
 4 files changed, 83 insertions(+), 98 deletions(-)
drivers/platform/chrome/wilco_ec/debugfs.c +21 -22
index c090db2cd5be..17c4c9068aaf 100644
@@ -10,25 +10,26 @@
  * by reading from raw.
  *
  * 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
+ * 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]
  *
- * When referencing the EC interface spec, byte 2 corresponds to MBOX[0],
- * byte 3 corresponds to MBOX[1], etc.
- *
- * At least three bytes are required, for the msg type and command,
- * with additional bytes optional for additional data.
+ * 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, ...]
+ * $ 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.
  */
 
 #include <linux/ctype.h>
@@ -136,18 +137,15 @@ static ssize_t raw_write(struct file *file, const char __user *user_buf,
 	ret = parse_hex_sentence(buf, kcount, request_data, TYPE_AND_DATA_SIZE);
 	if (ret < 0)
 		return ret;
-	/* Need at least two bytes for message type and one for command */
+	/* Need at least two bytes for message type and one byte of data */
 	if (ret < 3)
 		return -EINVAL;
 
-	/* Clear response data buffer */
-	memset(debug_info->raw_data, '\0', EC_MAILBOX_DATA_SIZE_EXTENDED);
-
 	msg.type = request_data[0] << 8 | request_data[1];
-	msg.flags = WILCO_EC_FLAG_RAW;
-	msg.command = request_data[2];
-	msg.request_data = ret > 3 ? request_data + 3 : 0;
-	msg.request_size = ret - 3;
+	msg.flags = 0;
+	msg.request_data = request_data + 2;
+	msg.request_size = ret - 2;
+	memset(debug_info->raw_data, 0, sizeof(debug_info->raw_data));
 	msg.response_data = debug_info->raw_data;
 	msg.response_size = EC_MAILBOX_DATA_SIZE;
 
@@ -174,7 +172,8 @@ static ssize_t raw_read(struct file *file, char __user *user_buf, size_t count,
 		fmt_len = hex_dump_to_buffer(debug_info->raw_data,
 					     debug_info->response_size,
 					     16, 1, debug_info->formatted_data,
-					     FORMATTED_BUFFER_SIZE, true);
+					     sizeof(debug_info->formatted_data),
+					     true);
 		/* Only return response the first time it is read */
 		debug_info->response_size = 0;
 	}
drivers/platform/chrome/wilco_ec/mailbox.c +21 -32

100 lines not on this page · raw message

drivers/rtc/rtc-wilco-ec.c +39 -24

114 lines not on this page · raw message

include/linux/platform_data/wilco-ec.h +2 -20
index 446473a46b88..1ff224793c99 100644
@@ -14,10 +14,6 @@
 /* Message flags for using the mailbox() interface */
 #define WILCO_EC_FLAG_NO_RESPONSE	BIT(0) /* EC does not respond */
 #define WILCO_EC_FLAG_EXTENDED_DATA	BIT(1) /* EC returns 256 data bytes */
-#define WILCO_EC_FLAG_RAW_REQUEST	BIT(2) /* Do not trim request data */
-#define WILCO_EC_FLAG_RAW_RESPONSE	BIT(3) /* Do not trim response data */
-#define WILCO_EC_FLAG_RAW		(WILCO_EC_FLAG_RAW_REQUEST | \
-					 WILCO_EC_FLAG_RAW_RESPONSE)
 
 /* Normal commands have a maximum 32 bytes of data */
 #define EC_MAILBOX_DATA_SIZE		32
@@ -56,10 +52,7 @@ struct wilco_ec_device {
  * @mailbox_id: Mailbox identifier, specifies the command set.
  * @mailbox_version: Mailbox interface version %EC_MAILBOX_VERSION
  * @reserved: Set to zero.
- * @data_size: Length of request, data + last 2 bytes of the header.
- * @command: Mailbox command code, unique for each mailbox_id set.
- * @reserved_raw: Set to zero for most commands, but is used by
- *                some command types and for raw commands.
+ * @data_size: Length of following data.
  */
 struct wilco_ec_request {
 	u8 struct_version;
@@ -68,8 +61,6 @@ struct wilco_ec_request {
 	u8 mailbox_version;
 	u8 reserved;
 	u16 data_size;
-	u8 command;
-	u8 reserved_raw;
 } __packed;
 
 /**
@@ -79,8 +70,6 @@ struct wilco_ec_request {
  * @result: Result code from the EC.  Non-zero indicates an error.
  * @data_size: Length of the response data buffer.
  * @reserved: Set to zero.
- * @mbox0: EC returned data at offset 0 is unused (always 0) so this byte
- *         is treated as part of the header instead of the data.
  * @data: Response data buffer.  Max size is %EC_MAILBOX_DATA_SIZE_EXTENDED.
  */
 struct wilco_ec_response {
@@ -89,7 +78,6 @@ struct wilco_ec_response {
 	u16 result;
 	u16 data_size;
 	u8 reserved[2];
-	u8 mbox0;
 	u8 data[0];
 } __packed;
 
@@ -111,21 +99,15 @@ enum wilco_ec_msg_type {
  * struct wilco_ec_message - Request and response message.
  * @type: Mailbox message type.
  * @flags: Message flags, e.g. %WILCO_EC_FLAG_NO_RESPONSE.
- * @command: Mailbox command code.
- * @result: Result code from the EC.  Non-zero indicates an error.
  * @request_size: Number of bytes to send to the EC.
  * @request_data: Buffer containing the request data.
- * @response_size: Number of bytes expected from the EC.
- *                 This is 32 by default and 256 if the flag
- *                 is set for %WILCO_EC_FLAG_EXTENDED_DATA
+ * @response_size: Number of bytes to read from EC.
  * @response_data: Buffer containing the response data, should be
  *                 response_size bytes and allocated by caller.
  */
 struct wilco_ec_message {
 	enum wilco_ec_msg_type type;
 	u8 flags;
-	u8 command;
-	u8 result;
 	size_t request_size;
 	void *request_data;
 	size_t response_size;
Signature · 1 line
2.20.1
author
#1 lore raw

PATCH 2/3 platform/chrome: wilco_ec: Add USB PowerShare Policy control

USB PowerShare is a policy which affects charging via the special USB PowerShare port (marked with a small lightning bolt or battery icon) when in low power states:
- In S0, the port will always provide power.
- In S0ix, if power_share is enabled, then power will be supplied to the port when on AC or if battery is > 50%. Else no power is supplied.
- In S5, if power_share is enabled, then power will be supplied to the port when on AC. Else no power is supplied.

---
 drivers/platform/chrome/wilco_ec/Makefile |   2 +-
 drivers/platform/chrome/wilco_ec/core.c   |   9 ++
 drivers/platform/chrome/wilco_ec/sysfs.c  | 129 ++++++++++++++++++++++
 include/linux/platform_data/wilco-ec.h    |   3 +
 4 files changed, 142 insertions(+), 1 deletion(-)
 create mode 100644 drivers/platform/chrome/wilco_ec/sysfs.c
drivers/platform/chrome/wilco_ec/Makefile +1 -1
index 063e7fb4ea17..1281dd7737c4 100644
@@ -1,6 +1,6 @@
 # SPDX-License-Identifier: GPL-2.0
 
-wilco_ec-objs				:= core.o mailbox.o
+wilco_ec-objs				:= core.o mailbox.o sysfs.o
 obj-$(CONFIG_WILCO_EC)			+= wilco_ec.o
 wilco_ec_debugfs-objs			:= debugfs.o
 obj-$(CONFIG_WILCO_EC_DEBUGFS)		+= wilco_ec_debugfs.o
drivers/platform/chrome/wilco_ec/core.c +9 -0
index 05e1e2be1c91..abd15d04e57b 100644
@@ -89,8 +89,16 @@ static int wilco_ec_probe(struct platform_device *pdev)
 		goto unregister_debugfs;
 	}
 
+	ret = wilco_ec_add_sysfs(ec);
+	if (ret < 0) {
+		dev_err(dev, "Failed to create sysfs entries: %d", ret);
+		goto unregister_rtc;
+	}
+
 	return 0;
 
+unregister_rtc:
+	platform_device_unregister(ec->rtc_pdev);
 unregister_debugfs:
 	if (ec->debugfs_pdev)
 		platform_device_unregister(ec->debugfs_pdev);
@@ -102,6 +110,7 @@ static int wilco_ec_remove(struct platform_device *pdev)
 {
 	struct wilco_ec_device *ec = platform_get_drvdata(pdev);
 
+	wilco_ec_remove_sysfs(ec);
 	platform_device_unregister(ec->rtc_pdev);
 	if (ec->debugfs_pdev)
 		platform_device_unregister(ec->debugfs_pdev);
drivers/platform/chrome/wilco_ec/sysfs.c new file +129 -0

129 lines not on this page · raw message

include/linux/platform_data/wilco-ec.h +3 -0
index 1ff224793c99..05d011605b85 100644
@@ -123,4 +123,7 @@ struct wilco_ec_message {
  */
 int wilco_ec_mailbox(struct wilco_ec_device *ec, struct wilco_ec_message *msg);
 
+int wilco_ec_add_sysfs(struct wilco_ec_device *ec);
+void wilco_ec_remove_sysfs(struct wilco_ec_device *ec);
+
 #endif /* WILCO_EC_H */
Signature · 1 line
2.20.1
author
#2 lore raw

PATCH 3/3 platform/chrome: wilco_ec: Add Boot on AC support

In reply to Nick Crews

Boot on AC is a policy which makes the device boot from S5 when AC power is connected. This is useful for users who want to run their device headless or with a dock.

---
 drivers/platform/chrome/wilco_ec/sysfs.c | 52 ++++++++++++++++++++++++
 1 file changed, 52 insertions(+)
drivers/platform/chrome/wilco_ec/sysfs.c +52 -0
index ec5211257a58..52cbdb1f30b6 100644
@@ -5,6 +5,10 @@
  * Sysfs properties used to modify EC-controlled features on Wilco devices.
  * The entries will appear under /sys/bus/platform/devices/GOOG000C:00/
  *
+ * Boot on AC is a policy which makes the device boot from S5 when AC
+ * power is connected. This is useful for users who want to run their
+ * device headless or with a dock.
+ *
  * USB PowerShare is a policy which affects charging via the special
  * USB PowerShare port (marked with a small lightning bolt or battery icon)
  * when in low power states:
@@ -18,6 +22,18 @@
 #include <linux/platform_data/wilco-ec.h>
 #include <linux/sysfs.h>
 
+#define CMD_KB_CMOS			0x7C
+#define SUB_CMD_KB_CMOS_AUTO_ON		0x03
+
+struct boot_on_ac_request {
+	u8 cmd;			/* Always CMD_KB_CMOS */
+	u8 reserved1;
+	u8 sub_cmd;		/* Always SUB_CMD_KB_CMOS_AUTO_ON */
+	u8 reserved3to5[3];
+	u8 val;			/* Either 0 or 1*/
+	u8 reserved7;
+} __packed;
+
 #define CMD_USB_POWER_SHARE 0x39
 
 enum usb_power_share_op {
@@ -38,6 +54,41 @@ struct usb_power_share_response {
 	u8 val;		/* When getting, set by EC to either 0 or 1 */
 } __packed;
 
+static ssize_t boot_on_ac_store(struct device *dev,
+				struct device_attribute *attr,
+				const char *buf, size_t count)
+{
+	struct wilco_ec_device *ec = dev_get_drvdata(dev);
+	struct boot_on_ac_request rq;
+	struct wilco_ec_message msg;
+	int ret;
+	u8 val;
+
+	ret = kstrtou8(buf, 10, &val);
+	if (ret < 0)
+		return ret;
+
+	if (val != 0 && val != 1)
+		return -EINVAL;
+
+	memset(&rq, 0, sizeof(rq));
+	rq.cmd = CMD_KB_CMOS;
+	rq.sub_cmd = SUB_CMD_KB_CMOS_AUTO_ON;
+	rq.val = val;
+
+	memset(&msg, 0, sizeof(msg));
+	msg.type = WILCO_EC_MSG_LEGACY;
+	msg.request_data = &rq;
+	msg.request_size = sizeof(rq);
+	ret = wilco_ec_mailbox(ec, &msg);
+	if (ret < 0)
+		return ret;
+
+	return count;
+}
+
+static DEVICE_ATTR_WO(boot_on_ac);
+
 static int send_usb_power_share(struct wilco_ec_device *ec,
 				struct usb_power_share_request *rq,
 				struct usb_power_share_response *rs)
@@ -110,6 +161,7 @@ static ssize_t usb_power_share_store(struct device *dev,
 static DEVICE_ATTR_RW(usb_power_share);
 
 static struct attribute *wilco_dev_attrs[] = {
+	&dev_attr_boot_on_ac.attr,
 	&dev_attr_usb_power_share.attr,
 	NULL,
 };
Signature · 1 line
2.20.1
#3 lore raw
In reply to Nick Crews

Hi Nick,

Missatge de Nick Crews <[email protected]> del dia dv., 5 d’abr. 2019 a les 22:09:

Quoted 60 lines

The current API for the wilco EC mailbox interface is bad.

It assumes that most messages sent to the EC follow a similar structure, with a command byte in MBOX[0], followed by a junk byte, followed by actual data. This doesn't happen in several cases, such as setting the RTC time, using the raw debugfs interface, and reading or writing properties such as the Peak Shift policy (this last to be submitted soon).

Similarly for the response message from the EC, the current interface assumes that the first byte of data is always 0, and the second byte is unused. However, in both setting and getting the RTC time, in the debugfs interface, and for reading and writing properties, this isn't true.

The current way to resolve this is to use WILCO_EC_FLAG_RAW* flags to specify when and when not to skip these initial bytes in the sent and received message. They are confusing and used so much that they are normal, and not exceptions. In addition, the first byte of response in the debugfs interface is still always skipped, which is weird, since this raw interface should be giving the entire result.

Additionally, sent messages assume the first byte is a command, and so struct wilco_ec_message contains the "command" field. In setting or getting properties however, the first byte is not a command, and so this field has to be filled with a byte that isn't actually a command. This is again inconsistent.

wilco_ec_message contains a result field as well, copied from wilco_ec_response->result. The message result field should be removed:
if the message fails, the cause is already logged, and the callers are alerted. They will never care about the actual state of the result flag.

These flags and different cases make the wilco_ec_transfer() function, used in wilco_ec_mailbox(), really gross, dealing with a bunch of different cases. It's difficult to figure out what it is doing.

Finally, making these assumptions about the structure of a message make it so that the messages do not correspond well with the specification for the EC's mailbox interface. For instance, this interface specification may say that MBOX[9] in the received message contains some information, but the calling code needs to remember that the first byte of response is always skipped, and because it didn't set the RESPONSE_RAW flag, the next byte is also skipped, so this information is actually contained within wilco_ec_message->response_data[7]. This makes it difficult to maintain this code in the future.

To fix these problems this patch standardizes the mailbox interface by:
- Removing the WILCO_EC_FLAG_RAW* flags
- Removing the command and reserved_raw bytes from wilco_ec_request
- Removing the mbox0 byte from wilco_ec_response
- Simplifying wilco_ec_transfer() because of these changes
- Gives the callers of wilco_ec_mailbox() the responsibility of exactly and consistently defining the structure of the mailbox request and response
- Removing command and result from wilco_ec_message.

This results in the reduction of total code, and makes it much more maintainable and understandable.

Quoted 9 lines
---
 drivers/platform/chrome/wilco_ec/debugfs.c | 43 ++++++++-------
 drivers/platform/chrome/wilco_ec/mailbox.c | 53 ++++++++----------
 drivers/rtc/rtc-wilco-ec.c                 | 63 +++++++++++++---------
 include/linux/platform_data/wilco-ec.h     | 22 +-------
 4 files changed, 83 insertions(+), 98 deletions(-)

Now I'm confused, isn't this the same patch I picked this morning from you and is already applied in chrome-platform for-next?

[snip]

author
#4 lore raw
Quoted 4 lines

Now I'm confused, isn't this the same patch I picked this morning from you and is already applied in chrome-platform for-next?

Sorry, I didn't see that it was already applied in for-next. Just ignore this patch and assume that the next two in this series are based off the current state of for-next.