Add mailbox interface definition.

BUG=None
TEST=None

Change-Id: I6f91fa0ae352bb421fe7cce010cfbf14b93037b4

1 files changed, 61 insertions, 7 deletions

diff --git a/host_interface/ec_command.h b/host_interface/ec_command.h
index c868918019..3d42a87c53 100644
--- a/host_interface/ec_command.h
+++ b/host_interface/ec_command.h
@@ -1,13 +1,16 @@
-/* lid.h - handle lid open/close
+/* Copyright (c) 2011 The Chromium OS Authors. All rights reserved.
+ * Use of this source code is governed by a BSD-style license that can be
+ * found in the LICENSE file.
  *
- * (Chromium license) */
+ * This file defines the EC commands used in mailbox between host and EC.
+ *
+ * This file is included by both BIOS/OS and EC firmware.
+ */
 
 #ifndef __HOST_INTERFACE_EC_COMMAND_H
 #define __HOST_INTERFACE_EC_COMMAND_H
 
-#include <stdint.h>
-
-/* This file is included by BIOS/OS and EC firmware. */
+#include "cros_ec/include/ec_common.h"
 
 
 enum EcCommand {
@@ -103,10 +106,61 @@ enum EcCommand {
   EC_COMMAND_DEBUG_GET_EC_BOOT_REASON = 0x81,
   EC_COMMAND_DEBUG_GET_LAST_CRASH_INFO = 0x82,
   EC_COMMAND_DEBUG_GET_GPIO_VALUE = 0x83,
+};
 
-  /*------------------------------------------------------------------------*/
-  /* 0xe0~0xff are reserved for return value */
+
+/*
+ * To be as portable as possible between EC chips, we employ the follwoing
+ * mechanism for mailbox:
+ *
+ *   - define MB_EC (0xEF) for port 0x66 (ACPI).
+ *   - define 2 port ranges for half-duplex channels, i.e.
+ *       to_EC: port 0x800-0x9ff
+ *       to_host: port 0xa00-0xbff
+ *   - the process flow:
+ *     - host writes parameters into to_EC range.
+ *     - outp(0x62, EC_SET_FAN_RPM);
+ *     - outp(0x66, 0xEF);
+ *     - EC invokes callback function to handle the corresponding EC command.
+ *     - EC writes return parameters into to_host range.
+ *     - EC writes return value to port 0x62 so that port 0x66 IBF is set
+ *     - host gets the return value and reads parameters from to_host range.
+ */
+
+
+/* When host writes this value to port 0x66 (ACPI command port),
+ * the EC firmware would read the EcCommand in port 0x62 and execute
+ * the corresponding function.
+ */
+#define EC_MAILBOX_ACPI_COMMAND 0xEF
+
+
+/* Mailbox I/O port range: to_EC:   0x800-0x9FF
+ *                         to_host: 0xA00-0xBFF
+ */
+#define EC_MAILBOX_TO_EC_PORT_OFFSET 0x800  /* Host writes. EC reads */
+#define EC_MAILBOX_TO_EC_PORT_SIZE 0x200
+#define EC_MAILBOX_TO_HOST_PORT_OFFSET 0xA00  /* EC writes. Host reads */
+#define EC_MAILBOX_TO_HOST_PORT_SIZE 0x200
+
+
+/* The meta level of return value from EC command. Every EC command can
+ * return extra parameters via to_host range. */
+enum EcMailboxError {
+  EC_MAILBOX_ERROR_SUCCESS = 0,
+  EC_MAILBOX_ERROR_GENERIC = 1,  /* generic error */
+  EC_MAILBOX_ERROR_UNIMPLEMENTED = 2,
 };
 
+/* The callback function can return a value which will be put at port 0x62. */
+typedef enum EcMailboxError (*EcMailboxCallback)(
+    uint8_t ec_command,
+    uint8_t *to_ec,  /* pointer to input parameter */
+    uint8_t *to_host  /* pointer to output buffer */);
+
+
+/* Registering NULL can remove any registered callback. */
+EcError EcMailboxRegisterCallback(EcMailboxCallback callback);
+
 
 #endif  /* __HOST_INTERFACE_EC_COMMAND_H */