README.md
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..2b6943f
--- /dev/null
+++ b/README.md
@@ -0,0 +1,148 @@
+Copyright 2016 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
+The autotools of this requires the autotools-archive package for your
+system
+
+---
+
+Notes on messages:
+
+## Layout
+```
+Byte 0: COMMAND
+Byte 1: Sequence
+Byte 2-12: Data
+Byte 13: Response code
+Byte 14: Host controlled status reg
+Byte 15: BMC controlled status reg
+```
+## Commands
+```
+RESET_STATE
+GET_MBOX_INFO
+GET_FLASH_INFO
+READ_WINDOW
+CLOSE_WINDOW
+WRITE_WINDOW
+WRITE_DIRTY
+WRITE_FENCE
+COMPLETED_COMMANDS
+ACK
+```
+## Sequence
+Unique message sequence number
+
+## Responses
+```
+SUCCESS
+PARAM_ERROR
+WRITE_ERROR
+SYSTEM_ERROR
+TIMEOUT
+```
+
+## Information
+- Interrupts via control regs
+- Block size 4K
+- All multibyte messages are little endian
+
+### Commands in detail
+```
+ Command:
+ RESET_STATE
+ Data:
+ -
+ Response:
+ -
+
+ Command:
+ GET_MBOX_INFO
+ Data:
+ Data 0: API version
+ Response:
+ Data 0: API version
+ Data 1-2: read window size in blk size
+ Data 3-4: write window size in blk size
+
+ Command:
+ CLOSE_WINDOW
+ Data:
+ -
+ Response:
+ -
+ Command:
+ GET_FLASH_INFO
+ Data:
+ -
+ Response:
+ Data 0-3: Flash size
+ Data 4-7: Erase granule
+
+ Command:
+ READ_WINDOW
+ Data:
+ Data 0-1: Read window offset in blk size
+ Response:
+ Data 0-1: Read window pos in blk size
+
+ Command:
+ WRITE_WINDOW
+ Data:
+ Data 0-1: Write window offset in blk size
+ Response:
+ Data 0-1: Write window pos in blk size
+
+ Command:
+ WRITE_DIRTY
+ Data:
+ Data 0-1: Offset within window in blk size
+ Data 2-5: Number of dirty bytes
+ Response:
+ -
+
+ Command
+ WRITE_FENCE
+ Data:
+ Data 0-1: Offset within window in blk size
+ Data 2-5: Number of dirty bytes
+ Response:
+ -
+
+ Command:
+ ACK
+ Data:
+ Bits in the BMC reg to ack
+ Response:
+ *clears the bits*
+ -
+
+ Command:
+ COMPLETED_COMMANDS
+ Data:
+ -
+ Response:
+ Data 0: Number of seq numbers to follow
+ Data 1-N: Completed sequence numbers
+
+ BMC notifications:
+ If the BMC needs to tell the host something then it simply
+ writes to Byte 15. The host should have interrupts enabled
+ on that register, or otherwise be checking it regularly.
+ - BMC reboot
+ - Command complete
+ The host should issue a command complete request to find
+ out the sequence numbers to commands which have completed
+```