1 files changed, 110 insertions, 0 deletions
diff --git a/Documentation/mboxctl.md b/Documentation/mboxctl.md
new file mode 100644
index 0000000..49bf90e
--- /dev/null
+++ b/Documentation/mboxctl.md
@@ -0,0 +1,110 @@
+Copyright 2017 IBM
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+  http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+
+## Intro
+
+This document describes the reference mailbox control program contained in this
+repository.
+
+The mailbox control program is a program which can be used to generate dbus
+messages to control the operation of the mailbox daemon.
+
+## Files
+
+The mailbox control program is implemented entirely in the mboxctl.c file.
+
+## Operation
+
+### Invocation
+
+The mailbox control program is invoked with a command and any arguments which
+that command takes.
+
+### Sending Command
+
+The appropriate dbus message is then generated and sent on the dbus.
+
+### Receiving Commands
+
+After sending a command mboxctl then waits for a response from the daemon on
+the dbus and processes the response.
+
+A message is printed to convey the response provided by the daemon. It mboxctl
+is run in silent mode then no output is generated and the exit code reflects
+the response.
+
+## DBUS Protocol
+
+### Commands
+
+```
+0x00: Ping		- Ping the daemon
+			- Args: NONE
+			- Resp: NONE
+0x01: Daemon State	- Get the daemon status
+			- Args: NONE
+			- Resp[0]: Daemon Status:
+				0x00 - Active
+				0x01 - Suspended
+0x02: Reset		- Reset the daemon (same as the reset mbox command)
+			- Args: NONE
+			- Resp: NONE
+0x03: Suspend		- Suspend the daemon
+				- Allow the BMC to manage concurrent flash
+				  access
+				- The daemon will return BUSY to mbox window
+				  commands
+				- Will return Success if daemon successfully
+				  of already suspended
+			- Args: NONE
+			- Resp: NONE
+0x04: Resume		- Resume the daemon
+				- Will return Sucess if daemon successfully
+				  or already resumed
+			- Args[0]: Flash Modified:
+					"clean" - Not Modified (daemon won't
+						  clear its cache)
+					"modified" - Modified (daemon will clear
+						     its cache)
+			- Resp: NONE
+0x05: Clear Cache	- Tell the daemon its data source has been modified
+				- Causes the daemon to clear its cache
+			- Args: NONE
+			- Resp: NONE
+0x06: Kill		- Terminates the daemon
+			- Args: NONE
+			- Resp: NONE
+0x07: LPC State		- Query the state of the lpc mapping
+			- Args: NONE
+			- Resp[0]: LPC Bus Mapping State:
+					0x00 - Invalid (implies internal daemon
+					       error)
+					0x01 - Flash (LPC bus maps flash)
+					0x02 - Memory (LPC bus maps reserved
+					       memory)
+```
+
+### Return Values
+
+```
+0x00: Success	- Command succeeded
+0x01: Internal	- Internal DBUS Error
+0x02: Invalid	- Invalid command or parameters
+0x03: Rejected	- Daemon rejected the request
+			- If this occurs on a suspend command then the BMC must
+			  not access the flash device until a suspend command
+			  succeeds
+0x04: Hardware	- BMC Hardware Error
+0x05: Memory	- Memory Allocation Failed
+```