2019-02-09 08:37:17 +08:00
|
|
|
/* SPDX-License-Identifier: GPL-2.0 */
|
|
|
|
|
/*
|
|
|
|
|
* ChromeOS Wilco Embedded Controller
|
|
|
|
|
*
|
|
|
|
|
* Copyright 2018 Google LLC
|
|
|
|
|
*/
|
|
|
|
|
|
|
|
|
|
#ifndef WILCO_EC_H
|
|
|
|
|
#define WILCO_EC_H
|
|
|
|
|
|
2020-02-05 17:48:28 +08:00
|
|
|
#include <linux/mutex.h>
|
|
|
|
|
#include <linux/types.h>
|
2019-02-09 08:37:17 +08:00
|
|
|
|
|
|
|
|
/* Message flags for using the mailbox() interface */
|
|
|
|
|
#define WILCO_EC_FLAG_NO_RESPONSE BIT(0) /* EC does not respond */
|
|
|
|
|
|
|
|
|
|
/* Normal commands have a maximum 32 bytes of data */
|
|
|
|
|
#define EC_MAILBOX_DATA_SIZE 32
|
|
|
|
|
|
2020-02-05 17:48:28 +08:00
|
|
|
struct device;
|
|
|
|
|
struct resource;
|
|
|
|
|
struct platform_device;
|
|
|
|
|
|
2019-02-09 08:37:17 +08:00
|
|
|
/**
|
|
|
|
|
* struct wilco_ec_device - Wilco Embedded Controller handle.
|
|
|
|
|
* @dev: Device handle.
|
|
|
|
|
* @mailbox_lock: Mutex to ensure one mailbox command at a time.
|
|
|
|
|
* @io_command: I/O port for mailbox command. Provided by ACPI.
|
|
|
|
|
* @io_data: I/O port for mailbox data. Provided by ACPI.
|
|
|
|
|
* @io_packet: I/O port for mailbox packet data. Provided by ACPI.
|
|
|
|
|
* @data_buffer: Buffer used for EC communication. The same buffer
|
|
|
|
|
* is used to hold the request and the response.
|
|
|
|
|
* @data_size: Size of the data buffer used for EC communication.
|
2019-02-09 08:37:18 +08:00
|
|
|
* @debugfs_pdev: The child platform_device used by the debugfs sub-driver.
|
2019-02-09 08:37:19 +08:00
|
|
|
* @rtc_pdev: The child platform_device used by the RTC sub-driver.
|
2019-10-25 06:28:05 +08:00
|
|
|
* @charger_pdev: Child platform_device used by the charger config sub-driver.
|
2019-05-22 03:20:45 +08:00
|
|
|
* @telem_pdev: The child platform_device used by the telemetry sub-driver.
|
2019-02-09 08:37:17 +08:00
|
|
|
*/
|
|
|
|
|
struct wilco_ec_device {
|
|
|
|
|
struct device *dev;
|
|
|
|
|
struct mutex mailbox_lock;
|
|
|
|
|
struct resource *io_command;
|
|
|
|
|
struct resource *io_data;
|
|
|
|
|
struct resource *io_packet;
|
|
|
|
|
void *data_buffer;
|
|
|
|
|
size_t data_size;
|
2019-02-09 08:37:18 +08:00
|
|
|
struct platform_device *debugfs_pdev;
|
2019-02-09 08:37:19 +08:00
|
|
|
struct platform_device *rtc_pdev;
|
2019-10-25 06:28:05 +08:00
|
|
|
struct platform_device *charger_pdev;
|
2019-05-22 03:20:45 +08:00
|
|
|
struct platform_device *telem_pdev;
|
2019-02-09 08:37:17 +08:00
|
|
|
};
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* struct wilco_ec_request - Mailbox request message format.
|
|
|
|
|
* @struct_version: Should be %EC_MAILBOX_PROTO_VERSION
|
|
|
|
|
* @checksum: Sum of all bytes must be 0.
|
|
|
|
|
* @mailbox_id: Mailbox identifier, specifies the command set.
|
|
|
|
|
* @mailbox_version: Mailbox interface version %EC_MAILBOX_VERSION
|
|
|
|
|
* @reserved: Set to zero.
|
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.
Signed-off-by: Nick Crews <ncrews@chromium.org>
Acked-by: Alexandre Belloni <alexandre.belloni@bootlin.com>
Signed-off-by: Enric Balletbo i Serra <enric.balletbo@collabora.com>
2019-04-05 06:54:15 +08:00
|
|
|
* @data_size: Length of following data.
|
2019-02-09 08:37:17 +08:00
|
|
|
*/
|
|
|
|
|
struct wilco_ec_request {
|
|
|
|
|
u8 struct_version;
|
|
|
|
|
u8 checksum;
|
|
|
|
|
u16 mailbox_id;
|
|
|
|
|
u8 mailbox_version;
|
|
|
|
|
u8 reserved;
|
|
|
|
|
u16 data_size;
|
|
|
|
|
} __packed;
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* struct wilco_ec_response - Mailbox response message format.
|
|
|
|
|
* @struct_version: Should be %EC_MAILBOX_PROTO_VERSION
|
|
|
|
|
* @checksum: Sum of all bytes must be 0.
|
|
|
|
|
* @result: Result code from the EC. Non-zero indicates an error.
|
|
|
|
|
* @data_size: Length of the response data buffer.
|
|
|
|
|
* @reserved: Set to zero.
|
|
|
|
|
* @data: Response data buffer. Max size is %EC_MAILBOX_DATA_SIZE_EXTENDED.
|
|
|
|
|
*/
|
|
|
|
|
struct wilco_ec_response {
|
|
|
|
|
u8 struct_version;
|
|
|
|
|
u8 checksum;
|
|
|
|
|
u16 result;
|
|
|
|
|
u16 data_size;
|
|
|
|
|
u8 reserved[2];
|
2020-03-24 08:07:49 +08:00
|
|
|
u8 data[];
|
2019-02-09 08:37:17 +08:00
|
|
|
} __packed;
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* enum wilco_ec_msg_type - Message type to select a set of command codes.
|
|
|
|
|
* @WILCO_EC_MSG_LEGACY: Legacy EC messages for standard EC behavior.
|
|
|
|
|
* @WILCO_EC_MSG_PROPERTY: Get/Set/Sync EC controlled NVRAM property.
|
2019-05-09 05:38:09 +08:00
|
|
|
* @WILCO_EC_MSG_TELEMETRY: Request telemetry data from the EC.
|
2019-02-09 08:37:17 +08:00
|
|
|
*/
|
|
|
|
|
enum wilco_ec_msg_type {
|
|
|
|
|
WILCO_EC_MSG_LEGACY = 0x00f0,
|
|
|
|
|
WILCO_EC_MSG_PROPERTY = 0x00f2,
|
2019-05-09 05:38:09 +08:00
|
|
|
WILCO_EC_MSG_TELEMETRY = 0x00f5,
|
2019-02-09 08:37:17 +08:00
|
|
|
};
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* struct wilco_ec_message - Request and response message.
|
|
|
|
|
* @type: Mailbox message type.
|
|
|
|
|
* @flags: Message flags, e.g. %WILCO_EC_FLAG_NO_RESPONSE.
|
|
|
|
|
* @request_size: Number of bytes to send to the EC.
|
|
|
|
|
* @request_data: Buffer containing the request data.
|
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.
Signed-off-by: Nick Crews <ncrews@chromium.org>
Acked-by: Alexandre Belloni <alexandre.belloni@bootlin.com>
Signed-off-by: Enric Balletbo i Serra <enric.balletbo@collabora.com>
2019-04-05 06:54:15 +08:00
|
|
|
* @response_size: Number of bytes to read from EC.
|
2019-02-09 08:37:17 +08:00
|
|
|
* @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;
|
|
|
|
|
size_t request_size;
|
|
|
|
|
void *request_data;
|
|
|
|
|
size_t response_size;
|
|
|
|
|
void *response_data;
|
|
|
|
|
};
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* wilco_ec_mailbox() - Send request to the EC and receive the response.
|
|
|
|
|
* @ec: Wilco EC device.
|
|
|
|
|
* @msg: Wilco EC message.
|
|
|
|
|
*
|
|
|
|
|
* Return: Number of bytes received or negative error code on failure.
|
|
|
|
|
*/
|
|
|
|
|
int wilco_ec_mailbox(struct wilco_ec_device *ec, struct wilco_ec_message *msg);
|
|
|
|
|
|
2019-11-07 00:33:19 +08:00
|
|
|
/**
|
|
|
|
|
* wilco_keyboard_leds_init() - Set up the keyboard backlight LEDs.
|
|
|
|
|
* @ec: EC device to query.
|
|
|
|
|
*
|
|
|
|
|
* After this call, the keyboard backlight will be exposed through a an LED
|
|
|
|
|
* device at /sys/class/leds.
|
|
|
|
|
*
|
|
|
|
|
* This may sleep because it uses wilco_ec_mailbox().
|
|
|
|
|
*
|
|
|
|
|
* Return: 0 on success, negative error code on failure.
|
|
|
|
|
*/
|
|
|
|
|
int wilco_keyboard_leds_init(struct wilco_ec_device *ec);
|
|
|
|
|
|
2019-04-25 00:56:50 +08:00
|
|
|
/*
|
|
|
|
|
* A Property is typically a data item that is stored to NVRAM
|
|
|
|
|
* by the EC. Each of these data items has an index associated
|
|
|
|
|
* with it, known as the Property ID (PID). Properties may have
|
|
|
|
|
* variable lengths, up to a max of WILCO_EC_PROPERTY_MAX_SIZE
|
|
|
|
|
* bytes. Properties can be simple integers, or they may be more
|
|
|
|
|
* complex binary data.
|
|
|
|
|
*/
|
|
|
|
|
|
|
|
|
|
#define WILCO_EC_PROPERTY_MAX_SIZE 4
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* struct ec_property_set_msg - Message to get or set a property.
|
|
|
|
|
* @property_id: Which property to get or set.
|
|
|
|
|
* @length: Number of bytes of |data| that are used.
|
|
|
|
|
* @data: Actual property data.
|
|
|
|
|
*/
|
|
|
|
|
struct wilco_ec_property_msg {
|
|
|
|
|
u32 property_id;
|
|
|
|
|
int length;
|
|
|
|
|
u8 data[WILCO_EC_PROPERTY_MAX_SIZE];
|
|
|
|
|
};
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* wilco_ec_get_property() - Retrieve a property from the EC.
|
|
|
|
|
* @ec: Embedded Controller device.
|
|
|
|
|
* @prop_msg: Message for request and response.
|
|
|
|
|
*
|
|
|
|
|
* The property_id field of |prop_msg| should be filled before calling this
|
|
|
|
|
* function. The result will be stored in the data and length fields.
|
|
|
|
|
*
|
|
|
|
|
* Return: 0 on success, negative error code on failure.
|
|
|
|
|
*/
|
|
|
|
|
int wilco_ec_get_property(struct wilco_ec_device *ec,
|
|
|
|
|
struct wilco_ec_property_msg *prop_msg);
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* wilco_ec_set_property() - Store a property on the EC.
|
|
|
|
|
* @ec: Embedded Controller device.
|
|
|
|
|
* @prop_msg: Message for request and response.
|
|
|
|
|
*
|
|
|
|
|
* The property_id, length, and data fields of |prop_msg| should be
|
|
|
|
|
* filled before calling this function.
|
|
|
|
|
*
|
|
|
|
|
* Return: 0 on success, negative error code on failure.
|
|
|
|
|
*/
|
|
|
|
|
int wilco_ec_set_property(struct wilco_ec_device *ec,
|
|
|
|
|
struct wilco_ec_property_msg *prop_msg);
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* wilco_ec_get_byte_property() - Retrieve a byte-size property from the EC.
|
|
|
|
|
* @ec: Embedded Controller device.
|
|
|
|
|
* @property_id: Which property to retrieve.
|
|
|
|
|
* @val: The result value, will be filled by this function.
|
|
|
|
|
*
|
|
|
|
|
* Return: 0 on success, negative error code on failure.
|
|
|
|
|
*/
|
|
|
|
|
int wilco_ec_get_byte_property(struct wilco_ec_device *ec, u32 property_id,
|
|
|
|
|
u8 *val);
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* wilco_ec_get_byte_property() - Store a byte-size property on the EC.
|
|
|
|
|
* @ec: Embedded Controller device.
|
|
|
|
|
* @property_id: Which property to store.
|
|
|
|
|
* @val: Value to store.
|
|
|
|
|
*
|
|
|
|
|
* Return: 0 on success, negative error code on failure.
|
|
|
|
|
*/
|
|
|
|
|
int wilco_ec_set_byte_property(struct wilco_ec_device *ec, u32 property_id,
|
|
|
|
|
u8 val);
|
|
|
|
|
|
2019-04-17 09:20:47 +08:00
|
|
|
/**
|
|
|
|
|
* wilco_ec_add_sysfs() - Create sysfs entries
|
|
|
|
|
* @ec: Wilco EC device
|
|
|
|
|
*
|
|
|
|
|
* wilco_ec_remove_sysfs() needs to be called afterwards
|
|
|
|
|
* to perform the necessary cleanup.
|
|
|
|
|
*
|
|
|
|
|
* Return: 0 on success or negative error code on failure.
|
|
|
|
|
*/
|
|
|
|
|
int wilco_ec_add_sysfs(struct wilco_ec_device *ec);
|
|
|
|
|
void wilco_ec_remove_sysfs(struct wilco_ec_device *ec);
|
|
|
|
|
|
2019-02-09 08:37:17 +08:00
|
|
|
#endif /* WILCO_EC_H */
|