Fixing OpenOLT docs (linting and content)
Change-Id: Iee8e9146c13cec26cdba9ab4b01480224984e4e3
diff --git a/README.md b/README.md
index bdc21c4..8eb8880 100644
--- a/README.md
+++ b/README.md
@@ -1,10 +1,10 @@
# OpenOLT driver
-**OpenOLT driver** runs on white box Optical Line Terminals (OLTs) and provides a gRPC-based management and control interface to the OLT.
+The *OpenOLT driver* runs on white box Optical Line Terminals (OLTs) and provides a gRPC-based management and control interface to OLTs.
-The **OpenOLT driver** is used by [VOLTHA](https://github.com/opencord/voltha) through the [OpenOLT adapter](https://github.com/opencord/voltha/tree/master/voltha/adapters/openolt).
+The OpenOLT driver is used by [VOLTHA](https://github.com/opencord/voltha) through the [OpenOLT adapter](https://github.com/opencord/voltha/tree/master/voltha/adapters/openolt).
-**OpenOLT driver** currently supports Broadcom's Maple/Qumran chipsets.
+OpenOLT driver currently supports Broadcom's Maple/Qumran chipsets.
```text
@@ -34,35 +34,103 @@
```
-## Supported BAL API versions
+## Hardware requirements
-- 2.4.3.6
+A list of tested devices and optics can be found in the [CORD hardware requirements](https://github.com/opencord/docs/blob/master/prereqs/hardware.md#suggested-hardware) guide, in the *R-CORD access equipment and optics* section.
-## Proprietary software requirements
+## Get the pre-built debian package
-The following proprietary source code is required to build **OpenOLT driver**.
+Currently, [EdgeCore](jeff_catlin@edge-core.com) can privately distribute the latest OpenOLT debian package to its customers. Contact [Jeff Catlin](jeff_catlin@edge-core.com) for more information.
-- `SW-BCM68620_<BAL_VER>.zip` - Broadcom BAL source and Maple SDK.
-- `sdk-all-<SDK_VER>.tar.gz` - Broadcom Qumran SDK.
-- `ACCTON_BAL_<BAL_VER>-<ACCTON_VER>.patch` - Accton/Edgecore's patch.
-- `OPENOLT_BAL_<BAL_VER>.patch` - A patch to Broadcom software to allow compilation with C++ based openolt.
+## Prerequisites
-The versions currently supported by **OpenOLT driver** are:
+The debian package has been tested on [this specific version of OpenNetworkingLinux (ONL)](https://github.com/opencord/OpenNetworkLinux/releases/download/20180124-olt-kernel-3.7.10/ONL-2.0.0_ONL-OS_2018-01-24.0118-1303f20_AMD64_INSTALLED_INSTALLER).
-- SW-BCM68620_2_4_3_6.zip
-- sdk-all-6.5.7.tar.gz
-- ACCTON_BAL_2.4.3.6-V201710131639.patch
-- OPENOLT_BAL_2.4.3.6.patch
+More info on how to install ONL can be found on the official [ONL website](https://opennetlinux.org/docs/deploy).
-Note - This repo does not contain the above four source packages. These are needed to build the **OpenOLT driver** executable. Contact Broadcom for access to these source packages.
+## Install OpenOLT
-## System Requirements
+Copy the debian package to the OLT. For example:
-**OpenOLT driver** builds on Ubuntu 14.04.
+```shell
+scp openolt.deb root@10.6.0.201:~/.
+```
-## Build
+Install the *openolt.deb* package using *dpkg*:
-- Clone this repo either from the github mirror or from opencord gerrit:
+```shell
+dpkg -i openolt.deb
+```
+
+Reboot the OLT:
+
+```shell
+reboot
+```
+
+## Run OpenOLT
+
+Open a terminal and run the Broadcom BAL software (*bal_core_dist*):
+
+```shell
+cd /broadcom
+./bal_core_dist -C 127.0.0.1:40000 -A 127.0.0.1:50000
+```
+
+While the first executable still runs (even in background), open another terminal and run *openolt*:
+
+```shell
+cd /broadcom
+./openolt -C 127.0.0.1:40000 -A 127.0.0.1:50000
+```
+
+> **NOTE**: the two executables will remain open in the terminals, unless they are put in background.
+
+### Connect from VOLTHA
+
+At the VOLTHA CLI, preprovision and enable the OLT:
+
+```shell
+(voltha) preprovision_olt -t openolt -H YOUR_OLT_MGMT_IP:9191
+(voltha) enable
+```
+
+### Additional notes
+
+* *9191* is the TCP port that the *OpenOLT* driver uses for its gRPC channel
+* In the commands above, you can either use the loopback IP address (127.0.0.1) or substitute all its occurrences with the management IP of your OLT
+
+## Build OpenOLT
+
+### Supported BAL API versions
+
+Currently, OpenOLT support the Broadcom BAL APIs, version *2.4.3.6*.
+
+### Proprietary software requirements
+
+The following proprietary source code is required to build the OpenOLT driver.
+
+* `SW-BCM68620_<BAL_VER>.zip` - Broadcom BAL source and Maple SDK
+* `sdk-all-<SDK_VER>.tar.gz` - Broadcom Qumran SDK
+* `ACCTON_BAL_<BAL_VER>-<ACCTON_VER>.patch` - Accton/Edgecore's patch
+* `OPENOLT_BAL_<BAL_VER>.patch` - A patch to Broadcom software to allow compilation with C++ based openolt
+
+The versions currently supported by the OpenOLT driver are:
+
+* SW-BCM68620_2_4_3_6.zip
+* sdk-all-6.5.7.tar.gz
+* ACCTON_BAL_2.4.3.6-V201710131639.patch
+* OPENOLT_BAL_2.4.3.6.patch
+
+> **NOTE**: the repository does not contain the above four source packages. These are needed to build the OpenOLT driver executable. Contact [Broadcom](dave.baron@broadcom.com) to access the source packages.
+
+### System Requirements
+
+OpenOLT driver builds on *Ubuntu 14.04 LTS*.
+
+### Build procedure
+
+Clone the *openolt* repository either from GitHub or from OpenCORD Gerrit:
```shell
git clone git@github.com:opencord/openolt.git
@@ -70,77 +138,40 @@
git clone https://gerrit.opencord.org/openolt
```
-- Copy Broadcom sources (and patches) to the openolt/download directory:
+Copy the Broadcom source and patch files to the openolt/download directory:
```shell
cd openolt/download
cp SW-BCM68620_2_4_3_6.zip sdk-all-6.5.7.tar.gz ACCTON_BAL_2.4.3.6-V201710131639.patch OPENOLT_BAL_2.4.3.6.zip ./download
```
-- Run "make prereq" to install package dependencies. This is usually a one-time thing (unless there is change in the dependencies).
+Run *make prereq* to install the package dependencies.
+This is usually a one-time thing, unless there is a change in the dependencies.
```shell
make prereq
```
-- Run "make" or "make all". This can take a while to complete the first time around since it builds ONL and Broadcom SDKs. Subsequent runs are much faster as they only build the **OpenOLT driver** source.
+Run *make*. This can take a while to complete the first time, since it builds ONL and the Broadcom SDKs. Following runs will be much faster, as they only build the OpenOLT driver source.
```shell
make
```
-- Finally, build the debian package that will be installed on the OLT.
+If the build process succeeds, libraries and executables will be created in the *openolt/build* directory.
+
+Optionally, build the debian package that will be installed on the OLT.
```shell
make deb
```
-- If the build succeeds, the **openolt.deb** package is created in the **openolt/build** directory. Copy **openolt.deb** to the OLT
+If the build process succeeds, the *openolt.deb* package will be created as well in the *openolt/build* directory.
+
+### Cleanup
+
+To cleanup the repository and start the build procedure again, run:
```shell
-scp openolt/build/openolt.deb root@10.6.0.201:~/.
+make clean-all
```
-
-## Install
-
-- Install the openolt.deb package on the OLT
-
-```shell
-dpkg -i openolt.deb
-```
-
-- Reboot the OLT
-
-```shell
-reboot
-```
-
-## Run
-
-- Run bal_core_dist in one terminal:
-
-```shell
-cd /broadcom
-./bal_core_dist -C 10.6.0.201:40000 -A 10.6.0.201:50000
-```
-
-- Run openolt in another terminal:
-
-```shell
-cd /broadcom
-./openolt -C 10.6.0.201:40000 -A 10.6.0.201:50000
-```
-
-## Connect from VOLTHA
-
-- In VOLTHA cli, preprovision and enable the OLT:
-
-```shell
-(voltha) preprovision_olt -t openolt -H 10.6.0.201:9191
-(voltha) enable
-```
-
-Note:
-
-- **OpenOLT driver** uses port 9191 for its gRPC channel
-- Substitute 10.6.0.201 in above steps with mgmt IP of your OLT