README: Spring clean
It's not spring, but a cleanup needed to happen.
Change-Id: I3797f1c9f4fe5ff466d9fb2ec6c449c3846cd1da
Signed-off-by: Andrew Jeffery <andrew@aj.id.au>
diff --git a/README.md b/README.md
index c986e0f..af37bb9 100644
--- a/README.md
+++ b/README.md
@@ -1,29 +1,13 @@
-Copyright 2017 IBM
+HIOMAP: The Host I/O Mapping Protocol for Power-based Systems
+=============================================================
-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
+This repository contains [the specification for the Power systems Host I/O
+mapping protocol (HIOMAP)](Documentation/protocol.md) along with a reference
+implementation of the daemon and associated utilities.
- 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.
-
-MBOX
-====
-
-This repo contains the protocol definition for the host to BMC mailbox
-communication specification which can be found in
-Documentation/mbox_procotol.md.
-
-There is also a reference implementation of a BMC mailbox daemon, the details
-of which can be found in Documentation/mboxd.md.
-
-Finally there is also an implementation of a mailbox daemon control program, the
-details of which can be found in Documentation/mboxctl.md.
+For historical reasons, source and generated binaries may refer to 'mbox' or
+'the mailbox interface' in contexts that aren't completely sensible. It's
+unfortunate, but it's our current reality.
Building
========
@@ -31,11 +15,11 @@
The build system is a standard autotools setup. `bootstrap.sh` runs all the
jobs necessary to initialise autotools.
-By default mboxd is configured and built _without_ the 'virtual PNOR' feature
-discussed below. The virtual PNOR functionality is written in C++, and due to
-some autotools clunkiness even if it is disabled mboxd will still be linked
-with `CXX`. Point `CXX` to `cc` at configure time if you do not have a C++
-compiler for your target (`./configure CXX=cc`).
+By default the build is configured and built _without_ the 'virtual PNOR'
+feature discussed below. The virtual PNOR functionality is written in C++, and
+due to some autotools clunkiness even if it is disabled mboxd will still be
+linked with `CXX`. Point `CXX` to `cc` at configure time if you do not have a
+C++ compiler for your target (`./configure CXX=cc`).
If you are hacking on the reference implementation it's recommended to run
`bootstrap.sh` with the `dev` argument:
@@ -71,23 +55,25 @@
$ make check
```
-Style Guide
-===========
+Coding Style Guide
+==================
Preamble
--------
-This codebase is a mix of C (due to its heritage) and C++. This is an ugly
-split: message logging and error handling can be vastly different inside the
-same codebase. The aim is to remove the split one way or the other over time
-and have consistent approaches to solving problems.
+For not particularly good reasons the codebase is a mix of C and C++. This is
+an ugly split: message logging and error handling can be vastly different
+inside the same codebase. The aim is to remove the split one way or the other
+over time and have consistent approaches to solving problems.
-phosphor-mboxd is developed as part of the OpenBMC project, which also leads to
-integration of frameworks such as
-[phosphor-logging](https://github.com/openbmc/phosphor-logging). Specifically
-on phosphor-logging, it's noted that without care we can achieve absurd
-duplication or irritating splits in where errors are reported, as the C code is
-not capable of making use of the interfaces provided.
+However, the current reality is the codebase is developed as part of OpenBMC's
+support for Power platforms, which leads to integration of frameworks such as
+[phosphor-logging](https://github.com/openbmc/phosphor-logging). It's noted
+that with phosphor-logging we can achieve absurd duplication or irritating
+splits in where errors are reported, as the C code is not capable of making use
+of the interfaces provided.
+
+So:
Rules
-----
@@ -117,3 +103,20 @@
Note: This section specifically targets the use of phosphor-logging's
`log<T>()`. It does not prevent the use of `elog<T>()`.
+
+License and Copyright
+=====================
+
+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.