tjh.dev
Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
1/*
2 * ChromeOS EC multi-function device
3 *
4 * Copyright (C) 2012 Google, Inc
5 *
6 * This software is licensed under the terms of the GNU General Public
7 * License version 2, as published by the Free Software Foundation, and
8 * may be copied, distributed, and modified under those terms.
9 *
10 * This program is distributed in the hope that it will be useful,
11 * but WITHOUT ANY WARRANTY; without even the implied warranty of
12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13 * GNU General Public License for more details.
14 */
15
16#ifndef __LINUX_MFD_CROS_EC_H
17#define __LINUX_MFD_CROS_EC_H
18
19#include <linux/notifier.h>
20#include <linux/mfd/cros_ec_commands.h>
21#include <linux/mutex.h>
22
23/*
24 * Command interface between EC and AP, for LPC, I2C and SPI interfaces.
25 */
26enum {
27 EC_MSG_TX_HEADER_BYTES = 3,
28 EC_MSG_TX_TRAILER_BYTES = 1,
29 EC_MSG_TX_PROTO_BYTES = EC_MSG_TX_HEADER_BYTES +
30 EC_MSG_TX_TRAILER_BYTES,
31 EC_MSG_RX_PROTO_BYTES = 3,
32
33 /* Max length of messages */
34 EC_MSG_BYTES = EC_PROTO2_MAX_PARAM_SIZE +
35 EC_MSG_TX_PROTO_BYTES,
36};
37
38/*
39 * @version: Command version number (often 0)
40 * @command: Command to send (EC_CMD_...)
41 * @outdata: Outgoing data to EC
42 * @outsize: Outgoing length in bytes
43 * @indata: Where to put the incoming data from EC
44 * @insize: Max number of bytes to accept from EC
45 * @result: EC's response to the command (separate from communication failure)
46 */
47struct cros_ec_command {
48 uint32_t version;
49 uint32_t command;
50 uint8_t *outdata;
51 uint32_t outsize;
52 uint8_t *indata;
53 uint32_t insize;
54 uint32_t result;
55};
56
57/**
58 * struct cros_ec_device - Information about a ChromeOS EC device
59 *
60 * @ec_name: name of EC device (e.g. 'chromeos-ec')
61 * @phys_name: name of physical comms layer (e.g. 'i2c-4')
62 * @dev: Device pointer
63 * @was_wake_device: true if this device was set to wake the system from
64 * sleep at the last suspend
65 * @cmd_xfer: send command to EC and get response
66 * Returns the number of bytes received if the communication succeeded, but
67 * that doesn't mean the EC was happy with the command. The caller
68 * should check msg.result for the EC's result code.
69 *
70 * @priv: Private data
71 * @irq: Interrupt to use
72 * @din: input buffer (for data from EC)
73 * @dout: output buffer (for data to EC)
74 * \note
75 * These two buffers will always be dword-aligned and include enough
76 * space for up to 7 word-alignment bytes also, so we can ensure that
77 * the body of the message is always dword-aligned (64-bit).
78 * We use this alignment to keep ARM and x86 happy. Probably word
79 * alignment would be OK, there might be a small performance advantage
80 * to using dword.
81 * @din_size: size of din buffer to allocate (zero to use static din)
82 * @dout_size: size of dout buffer to allocate (zero to use static dout)
83 * @parent: pointer to parent device (e.g. i2c or spi device)
84 * @wake_enabled: true if this device can wake the system from sleep
85 * @lock: one transaction at a time
86 */
87struct cros_ec_device {
88
89 /* These are used by other drivers that want to talk to the EC */
90 const char *ec_name;
91 const char *phys_name;
92 struct device *dev;
93 bool was_wake_device;
94 struct class *cros_class;
95 int (*cmd_xfer)(struct cros_ec_device *ec,
96 struct cros_ec_command *msg);
97
98 /* These are used to implement the platform-specific interface */
99 void *priv;
100 int irq;
101 uint8_t *din;
102 uint8_t *dout;
103 int din_size;
104 int dout_size;
105 struct device *parent;
106 bool wake_enabled;
107 struct mutex lock;
108};
109
110/**
111 * cros_ec_suspend - Handle a suspend operation for the ChromeOS EC device
112 *
113 * This can be called by drivers to handle a suspend event.
114 *
115 * ec_dev: Device to suspend
116 * @return 0 if ok, -ve on error
117 */
118int cros_ec_suspend(struct cros_ec_device *ec_dev);
119
120/**
121 * cros_ec_resume - Handle a resume operation for the ChromeOS EC device
122 *
123 * This can be called by drivers to handle a resume event.
124 *
125 * @ec_dev: Device to resume
126 * @return 0 if ok, -ve on error
127 */
128int cros_ec_resume(struct cros_ec_device *ec_dev);
129
130/**
131 * cros_ec_prepare_tx - Prepare an outgoing message in the output buffer
132 *
133 * This is intended to be used by all ChromeOS EC drivers, but at present
134 * only SPI uses it. Once LPC uses the same protocol it can start using it.
135 * I2C could use it now, with a refactor of the existing code.
136 *
137 * @ec_dev: Device to register
138 * @msg: Message to write
139 */
140int cros_ec_prepare_tx(struct cros_ec_device *ec_dev,
141 struct cros_ec_command *msg);
142
143/**
144 * cros_ec_check_result - Check ec_msg->result
145 *
146 * This is used by ChromeOS EC drivers to check the ec_msg->result for
147 * errors and to warn about them.
148 *
149 * @ec_dev: EC device
150 * @msg: Message to check
151 */
152int cros_ec_check_result(struct cros_ec_device *ec_dev,
153 struct cros_ec_command *msg);
154
155/**
156 * cros_ec_remove - Remove a ChromeOS EC
157 *
158 * Call this to deregister a ChromeOS EC, then clean up any private data.
159 *
160 * @ec_dev: Device to register
161 * @return 0 if ok, -ve on error
162 */
163int cros_ec_remove(struct cros_ec_device *ec_dev);
164
165/**
166 * cros_ec_register - Register a new ChromeOS EC, using the provided info
167 *
168 * Before calling this, allocate a pointer to a new device and then fill
169 * in all the fields up to the --private-- marker.
170 *
171 * @ec_dev: Device to register
172 * @return 0 if ok, -ve on error
173 */
174int cros_ec_register(struct cros_ec_device *ec_dev);
175
176#endif /* __LINUX_MFD_CROS_EC_H */