[VOL-2875] Documentation update
General language (spelling, flow) fixes
Remove redundant documentation
Change protos Makefile to generate directory using dependencies
Change-Id: I24fb2c9259c1a29b7499a35fd13e50836333c58e
diff --git a/README.md b/README.md
index e37c347..cb01501 100644
--- a/README.md
+++ b/README.md
@@ -7,7 +7,9 @@
through the [OpenOLT
adapter](https://github.com/opencord/voltha/tree/master/voltha/adapters/openolt).
-OpenOLT agent uses Broadcom's BAL (Broadband Access Layer) software for Maple/Qumran chipsets based OLT such as the Edgecore/Accton ASXvOLT16.
+OpenOLT agent uses Broadcom's BAL (Broadband Access Layer) software for
+interfacing with the Maple/Qumran chipsets in OLTs such as the Edgecore/Accton
+ASXvOLT16.
```text
@@ -36,7 +38,6 @@
| |
| White box OLT |
+-------------------------------------+
-
```
## Hardware requirements
@@ -47,16 +48,20 @@
## Pre-built debian packages of OpenOLT agent for Accton/Edgecore ASFVOLT16
-Accton/Edgecore makes available pre-built debian packages of OpenOLT agent to their customers.
-Get access credentials for https://edgecore.quickconnect.to and then login and navigate to
-File_Station -> EdgecoreNAS, and then the folder /ASXvOLT16/OpenOLT_Agent/From_ONF_Distribution/
-and pick the right version of deb package required for your testing.
-voltha-2.3/openolt-2.3.0.deb is the latest version of package with support for BAL3.2.3.2
-The pre-built debian packages have been tested on ONL-4.14. The ONL Installer required for
-voltha-2.3/openolt-2.3.0.deb is also available at in the same path, i.e., voltha-2.3/.
+Accton/Edgecore makes available pre-built debian packages of OpenOLT agent to
+their customers. Get access credentials for
+[edgecore.quickconnect.to](https://edgecore.quickconnect.to) and then login and
+navigate to `File_Station -> EdgecoreNAS`, and then the folder
+`/ASXvOLT16/OpenOLT_Agent/From_ONF_Distribution/` and pick the right version of
+`.deb` package required for your testing.
-More info on how to install ONL can be found on the official [ONL
-website](https://opennetlinux.org/).
+`voltha-2.3/openolt-2.3.0.deb` is the latest version of package with support
+for BAL3.2.3.2 .
+
+The pre-built debian packages have been tested on [Open Networking Linux
+(ONL)](http://opennetlinux.org/) version 4.14. The ONL Installer required for
+voltha-2.3/openolt-2.3.0.deb is also available at in the same path, i.e.,
+voltha-2.3/.
## Install OpenOLT
@@ -72,17 +77,20 @@
dpkg -i openolt.deb
```
-Note that ONL required for BAL3.2.3.2 is ONL `4.14.109-OpenNetworkLinux`. This will be built as part of build procedure described `Build OpenOLT` section.
+The ONL version required for BAL3.2.3.2 is ONL `4.14.109-OpenNetworkLinux`. This
+will be built as part of build procedure described `Build OpenOLT` section.
## Run OpenOLT as a Linux service
-Rebooting the OLT (after the installation) will start dev_mgmt_daemon and openolt as init.d services:
+Rebooting the OLT (after the installation) will start `dev_mgmt_daemon` and
+`openolt` as system services:
-Rebooting the OLT will start the dev_mgmt_daemon and openolt services:
```shell
reboot
```
+
The services can also be stopped/started manually:
+
```shell
service dev_mgmt_daemon stop
service openolt stop
@@ -91,25 +99,35 @@
```
Check the status of the services:
+
```shell
service dev_mgmt_daemon status
service openolt status
```
-## Run OpenOLT in foreground
+## Run OpenOLT in foreground for development and debugging
-Running the dev_mgmt_daemon and/or openolt services in the forground is useful for development and debugging. Make sure to first stop the services if they are running in background.
+Running the `dev_mgmt_daemon` and/or `openolt` services in the foreground is
+useful for development and debugging. Make sure to first stop the services if
+they are running in background.
-Open a terminal and run the Broadcom BAL software (*dev_mgmt_daemon*):
+```shell
+service dev_mgmt_daemon stop
+service openolt stop
+```
+
+Open a terminal and run the Broadcom BAL software (`dev_mgmt_daemon`):
```shell
cd /broadcom
./dev_mgmt_daemon -d -pcie
```
-The `dev_mgmt_daemon` executable, when run in foreground, presents the CLI for Broadcom's BAL - Broadband Access Layer which is useful for debugging.
+
+The `dev_mgmt_daemon` executable presents the CLI for Broadcom's BAL when run
+in the foreground which is useful for debugging.
While the first executable still runs (even in background), open another
-terminal and run *openolt*:
+terminal and run `openolt`:
```shell
cd /broadcom
@@ -150,13 +168,13 @@
The versions currently supported by the OpenOLT agent are:
-* SW-BCM686OLT_3_2_3_2.tgz
-* sdk-all-6.5.13.tar.gz
-* ACCTON_BAL_3.2.3.2-V201912230101.patch
+* `SW-BCM686OLT_3_2_3_2.tgz`
+* `sdk-all-6.5.13.tar.gz`
+* `ACCTON_BAL_3.2.3.2-V201912230101.patch`
> NOTE: the repository does not contain the above three source packages. These
-> are needed to build the OpenOLT agent executable. Contact
-> [Broadcom](mailto:dave.baron@broadcom.com) to access the source packages.
+> are needed to build the OpenOLT agent executable. Contact [Dave Baron at
+> Broadcom](mailto:dave.baron@broadcom.com) to access the source packages.
### System Requirements
@@ -164,9 +182,9 @@
CPU: Dual-core (4 Threads) up.
-Memory: 6G bytes.
+Memory: 6GB
-Hard Disk: 40G of disk free space.
+Storage: 40GB of free space.
**Software** :
@@ -176,20 +194,18 @@
3. Essential tools for building packages
- `sudo apt-get install build-essential ccache`
+ `sudo apt-get install build-essential ccache`
-4. Install cmake version 3.5.0 or above. Download cmake-3.5.0.tar.gz and install it by untaring cmake tar file.
- Go to cmake-3.5.0 directory after untaring and execute
+4. Install cmake version 3.5.0 or above. Download cmake-3.5.0.tar.gz and untar
+ it, then in the cmake-3.5.0 directory install by running:
- `./bootstrap && make && make install`
+ `./bootstrap && make && make install`
### Build procedure
-Clone the *openolt* repository either from GitHub or from OpenCORD Gerrit:
+Clone the `openolt` repository either from OpenCORD Gerrit:
```shell
-git clone git@github.com:opencord/openolt.git
-or
git clone https://gerrit.opencord.org/openolt
```
@@ -200,14 +216,15 @@
cp ACCTON_BAL_3.2.3.2-V201912230101.patch SW-BCM686OLT_3_2_3_2.tgz sdk-all-6.5.13.tar.gz <cloned openolt repo path>/agent/download
```
-Run Autoconfig to generate the appropriate makefile scaffolding for the desired target
+Run the configure script to generate the appropriate Makefile scaffolding for
+the desired target:
```shell
cd openolt/agent
./configure
```
-Run *make prereq* to install the package 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
@@ -222,16 +239,21 @@
make OPENOLTDEVICE=asfvolt16
```
-Note that the required ONL vesion `4.14` is built as part of the above build procedure and is available at path `build/onl/OpenNetworkLinux/RELEASE/jessie/amd64/ONL-onl-4.14_ONL-OS8_2019-09-24.0446 b4af32e_AMD64_INSTALLED_INSTALLER`. This ONL Installer should be used to flash the OS on the OLT.
+Note that the required ONL version `4.14` is built as part of the above build
+procedure and is available at path
+`build/onl/OpenNetworkLinux/RELEASE/jessie/amd64/ONL-onl-4.14_ONL-OS8_2019-09-24.0446b4af32e_AMD64_INSTALLED_INSTALLER`.
+This ONL Installer should be used to flash the OS on the OLT.
-If you need to use a specific version of voltha-protos, then specify the git tag/branch corresponding to
-tht specific version as below. For ex:
+If you need to use a specific version of voltha-protos, then specify the git
+tag/branch corresponding to that specific version:
```shell
make OPENOLTDEVICE=asfvolt16 OPENOLT_PROTO_VER=master
```
-By default, the OPENOLT_PROTO_VER defaults to git tag *v3.1.0* of https://github.com/opencord/voltha-protos repo.
+By default, the `OPENOLT_PROTO_VER` defaults to git tag *v3.1.0* of the
+[voltha-protos](https://gerrit.opencord.org/gitweb?p=voltha-protos.git;a=summary)
+repo.
If the build process succeeds, libraries and executables will be created in the
*openolt/agent/build* directory.
@@ -242,10 +264,11 @@
make OPENOLTDEVICE=asfvolt16 deb
```
-If the build process succeeds, the *openolt.deb* package will be created as
-well in the *openolt/agent/build* directory.
+If the build process succeeds, a `.deb` package will be created as well in the
+`openolt/agent/build` directory.
-NOTE: To compile for ASGvOLT 64 port GPON OLT, set `OPENOLTDEVICE` to `asgvolt64` during build procedure like below.
+NOTE: To compile for ASGvOLT 64 port GPON OLT, set `OPENOLTDEVICE` to
+`asgvolt64` during build procedure like below.
```shell
make OPENOLTDEVICE=asgvolt64
@@ -265,26 +288,39 @@
## FAQ
-The information here may be specific to specific OLT and ONU hardware such as Edgecore ASFVOLT16 OLT and Broadcom based ONUs.
+The information here may be specific to specific OLT and ONU hardware such as
+Edgecore ASFVOLT16 OLT and Broadcom based ONUs.
### How to change speed of ASFVOLT16 NNI interface?
-Auto-negotiation on the NNI (uplink) interfaces is not tested. By default, the OpenOLT agent sets the speed of the NNI interfaces to 100G. To downgrade the network interface speed to 40G, add the following lines at the end of the qax.soc (/broadcom/qax.soc) configuration file. A restart of the dev_mgmt_daemon and openolt executables is required after the change.
+Auto-negotiation on the NNI (Network to Network Interface) uplink ports is not
+tested.
-```shell
+By default, the OpenOLT agent sets the speed of the NNI interfaces to 100G. To
+downgrade the network interface speed to 40G, add the following lines at the
+end of the `/broadcom/qax.soc` configuration file.
+
+```text
port ce128 sp=40000
```
+A restart of the `dev_mgmt_daemon` and `openolt` services is required after
+making this change.
+
+
### Why does the Broadcom ONU not forward eapol packets?
-The firmware on the ONU is likely not setup to forward 802.1x on the linux bridge. Drop down to the shell in the Broadcom ONU's console and configure the Linux bridge to forward 802.1x.
+The firmware on the ONU is likely not setup to forward 802.1x EAPOL traffic on
+the Linux bridge. Drop down to the shell in the Broadcom ONU's console and
+configure the Linux bridge to forward 802.1x.
```shell
> sh
# echo 8 > /sys/class/net/bronu513/bridge/group_fwd_mask
```
-Version 1.7 of VOLTHA has a known issue where the ONU is only able to pass EAPOL packets from a specific LAN port (e.g. LAN port 1 on ALPHA ONUs)
+Version 1.7 of VOLTHA has a known issue where the ONU is only able to pass
+EAPOL packets from a specific LAN port (e.g. LAN port 1 on ALPHA ONUs)
### How do I check packet counters on the ONU?
@@ -294,12 +330,16 @@
bs /b/e port/index=lan{0,1,2,3,4,5,6}
```
-WAN port packt counters:
+WAN port packet counters:
+
```shell
bs /b/e port/index=wan0
```
+
### How to get access to MAPLE CLI on OLT box
-To get access to the `BCM.0>` maple console please ssh into the OLT and then execute:
+
+To get access to the `BCM.0>` maple console, SSH into the OLT and then execute:
+
```shell
cd /broadcom
./example_user_appl
@@ -307,7 +347,10 @@
### How do I check packet counters on the OLT's PON interface?
-Following is an example of retrieving the interface description for PON intf_id 0 (TODO: document PON interface numbering for Edgecore OLT).
+Following is an example of retrieving the interface description for PON
+`intf_id 0`
+
+(TODO: document PON interface numbering for Edgecore OLT).
```shell
BCM.0> a/t clear=no object=pon_interface sub=itu_pon_stats pon_ni=0
@@ -361,7 +404,7 @@
### How do I check packet counters on the OLT's NNI interface?
-Following command retrieves NNI intf_id 0:
+Following command retrieves NNI `intf_id 0`:
```shell
BCM.0> a/t clear=no object=nni_interface sub=stats id=0
@@ -396,15 +439,17 @@
BCM.0> a/m max_msgs=100 filter_invert=no object=flow
```
-### How do I access device CLI when running dev_mgmt_daemon and openolt agent binary in background?
+### How do I access device CLI when running `dev_mgmt_daemon` and `openolt` agent binary as services?
-Navigate to `/opt/bcm68620` and execute the command `/broadcom/dev_mgmt_attach` to access the QAX
-diag shell. Note that you will not be able to access the QAX diag shell, you need to recompile the
-BAL SDK with `SW_UTIL_SHELL=y` option.
+Navigate to `/opt/bcm68620` and execute the command `/broadcom/dev_mgmt_attach`
+to access the QAX diagnostic shell. If you are not able to access the shell,
+you need to recompile the BAL SDK with `SW_UTIL_SHELL=y` option set.
### DBA Scheduler fail to create on the OLT with errors related to Bandwidth configuration
-Ensure that `additional_bw` indicator in the Technology Profile and the `bandwidthprofile` configured in ONOS netcfg for the subscriber are following the below guideline.
+Ensure that `additional_bw` indicator in the Technology Profile and the
+`bandwidthprofile` configured in ONOS netcfg for the subscriber are following
+the below guideline.
* When `additional_bw` is configured as `AdditionalBW_BestEffort`, ensure `cir` + `eir`
values in ONOS netcfg BW profile for the subscriber are greater than or equal to *16000*
@@ -419,8 +464,10 @@
For more details about BW profile parameters, please refer below links.
-[MEF Whitepaper - Bandwidth-Profiles-for-Ethernet-Services](https://www.mef.net/Assets/White_Papers/Bandwidth-Profiles-for-Ethernet-Services.pdf)
-[Technology Profile Implementation Note](https://www.opennetworking.org/wp-content/uploads/2019/09/2pm-Shaun-Missett-Technology-Profile-and-Speed-Profile-Implementation.pdf)
+[MEF Whitepaper -
+Bandwidth-Profiles-for-Ethernet-Services](https://www.mef.net/Assets/White_Papers/Bandwidth-Profiles-for-Ethernet-Services.pdf)
+[Technology Profile Implementation
+Note](https://www.opennetworking.org/wp-content/uploads/2019/09/2pm-Shaun-Missett-Technology-Profile-and-Speed-Profile-Implementation.pdf)
## Known Issues
@@ -428,6 +475,5 @@
* The Minimum BW that should be configured for ITU PON Alloc Object has changed from 16Kbps
to 32Kbps from BAL3.1 to BAL3.2 release if you are using ALPHA ONUs.
As per BAL3.x documents, when FEC is disabled, the minimum BW is 16Kbps on the ITU PON Alloc Object.
- This seems to be a discrepency on the ALPHA ONU. So, ensure that `cir` + `eir` value is greater than
+ This seems to be a discrepancy on the ALPHA ONU. So, ensure that `cir` + `eir` value is greater than
equal to *32000* for XGSPON use case for ALPHA ONU.
-
diff --git a/VERSION b/VERSION
index eef2640..a724a9c 100644
--- a/VERSION
+++ b/VERSION
@@ -1 +1 @@
-2.4.0-dev0
+2.4.0-dev
diff --git a/agent/download/README.md b/agent/download/README.md
deleted file mode 100644
index 4c96c2b..0000000
--- a/agent/download/README.md
+++ /dev/null
@@ -1,10 +0,0 @@
-# Broadcom proprietary src code required to build olt-brcm
-
-The following vendor proprietary source files are required to build. These files are available from Broadcom under NDA through a common CSP.
-
-- `SW-BCM68620_<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` - ONF's patch to BAL (to enable BAL to compile with C++ based openolt)
-
-Copy the above four files to this folder before running make in the top level directory.
diff --git a/agent/test/README.md b/agent/test/README.md
index 54e8168..92ec74e 100644
--- a/agent/test/README.md
+++ b/agent/test/README.md
@@ -1,16 +1,19 @@
-# OpenOLT Agent Unit Test
+# OpenOLT Agent Unit Tests
OpenOLT agent unit test framework is based on the following frameworks
-- Google Test: https://github.com/google/googletest
-- C-Mock: https://github.com/hjagodzinski/C-Mock
-
-The goal of the unit tests for OpenOLT agent is to test the OpenOLT application by stubbing and mocking the external interfaces, especially the BAL API and GRPC.
+- [Google Test](https://github.com/google/googletest)
+- [C-Mock](https://github.com/hjagodzinski/C-Mock)
+
+The goal of the unit tests for OpenOLT agent is to test the OpenOLT application
+by stubbing and mocking the external interfaces, especially the BAL API and
+GRPC.
## Building and Running Unit Test
-All the pre-requisite software for running the openolt agent unit tests are packaged, versioned
-and released as a docker container. See https://github.com/opencord/openolt-test for more details.
+All the pre-requisite software for running the openolt agent unit tests are
+packaged, versioned and released as a docker container. See
+https://github.com/opencord/openolt-test for more details.
Follow the below steps to build and run unit test
@@ -19,14 +22,15 @@
make test
```
-The openolt agent source code will be mounted to docker container, compiled and unit tests will be run.
-Note that you will need access to internet to download the voltha/openolt-test docker container for the
-first time.
+The openolt agent source code will be mounted to docker container, compiled and
+unit tests will be run. Note that you will need access to internet to download
+the voltha/openolt-test docker container for the first time.
-If you choose not to use docker conainer packaged with pre-requisite software for building and running
-unit tests, you may install the pre-requisite software directly on the host system using procedure below.
-However this procedure is NOT RECOMMENDED as software being installed via this procedure may conflict or
-overwrite the software that may already exist on the host sytem.
+If you choose not to use docker container packaged with pre-requisite software
+for building and running unit tests, you may install the pre-requisite software
+directly on the host system using procedure below. However this procedure is
+NOT RECOMMENDED as software being installed via this procedure may conflict
+or overwrite the software that may already exist on the host system.
```shell
$ cd agent/test
@@ -40,22 +44,39 @@
$ make test
```
-Once you have successfully built and run the unit-test, the test report will be available in `test_openolt_report_xunit.xml` file in `agent/test`.
-To clean all build artifacts and test reports, do `make clean` from openolt agent root directory.
+Once you have successfully built and run the unit-test, the test report will be
+available in `test_openolt_report_xunit.xml` file in `agent/test`. To clean
+all build artifacts and test reports, do `make clean` from openolt agent root
+directory.
## Adding new Unit Test Cases
-Before you add new test cases please read [GOOGLE TEST COOKBOOK](https://github.com/google/googletest/blob/master/googlemock/docs/cook_book.md) and [USING CMOCK](https://github.com/hjagodzinski/C-Mock/blob/master/README.md) to get acquainted with frameworks used for the unit-test cases.
+Before you add new test cases please read [GOOGLE TEST
+COOKBOOK](https://github.com/google/googletest/blob/master/googlemock/docs/cook_book.md)
+and [USING CMOCK](https://github.com/hjagodzinski/C-Mock/blob/master/README.md)
+to get acquainted with frameworks used for the unit-test cases.
### Create mocks, if needed
-Refer `agent/test/src/bal_mocker.cc` and `agent/test/src/bal_mocker.h` to see how mock functions are created (if needed by your test case). In the aforementioned examples, mocks are created for certain BAL APIs.
+Refer `agent/test/src/bal_mocker.cc` and `agent/test/src/bal_mocker.h` to see
+how mock functions are created (if needed by your test case). In the
+aforementioned examples, mocks are created for certain BAL APIs.
### Create Unit Test Case
Please refer example `agent/test/src/test_enable_olt.cc`.
-Tests are grouped under Test Fixtures, i.e., `TEST_F` which takes argument of Test Fixture Name and the Test Case. There will typically be many test cases under a test fixture. Also it is preferrable to create a new file for different test fixtures.
-If your test case needs mocking, you will need to instantiate the appropriate mocker class you have created and use the `ON_CALL`, `EXPECT_CALL` or other utilities from the gtest suite to produce the required behavior.
-Use the `ASSERT_XXX` utility from the gtest suite to verify the required result.
-Please refer the [GOOGLE TEST COOKBOOK](https://github.com/google/googletest/blob/master/googlemock/docs/cook_book.md) for detailed documentation.
+
+Tests are grouped under Test Fixtures, i.e., `TEST_F` which takes argument of
+Test Fixture Name and the Test Case. There will typically be many test cases
+under a test fixture. Also it is preferable to create a new file for different
+test fixtures.
+
+If your test case needs mocking, you will need to instantiate the appropriate
+mocker class you have created and use the `ON_CALL`, `EXPECT_CALL` or other
+utilities from the gtest suite to produce the required behavior.
+
+Use the `ASSERT_XXX` utility from the gtest suite to verify the required
+result. Please refer the [GOOGLE TEST
+COOKBOOK](https://github.com/google/googletest/blob/master/googlemock/docs/cook_book.md)
+for detailed documentation.
diff --git a/protos/Makefile b/protos/Makefile
index 1394778..7f5394f 100644
--- a/protos/Makefile
+++ b/protos/Makefile
@@ -34,7 +34,7 @@
.DEFAULT_GOAL := all
-all: googleapis get_openolt_proto grpc-target protobuf-target libopenoltapi.a
+all: googleapis voltha_protos grpc-target protobuf-target libopenoltapi.a
libopenoltapi.a: $(OBJS)
ar cr $@ $^
@@ -49,7 +49,8 @@
make -C googleapis LANGUAGE=cpp GRPCPLUGIN=$(GRPC_CPP_PLUGIN_PATH) all; \
fi;
-get_openolt_proto:
+voltha_protos:
+ mkdir voltha_protos
if [ ! -e "voltha_protos/openolt.proto" ]; then \
wget -O voltha_protos/openolt.proto https://raw.githubusercontent.com/opencord/voltha-protos/$(OPENOLT_PROTO_VER)/protos/voltha_protos/openolt.proto; \
fi; \
@@ -61,12 +62,12 @@
$(PROTOC) --proto_path=. -I./googleapis --grpc_out=. --plugin=protoc-gen-grpc=$(GRPC_CPP_PLUGIN_PATH) voltha_protos/openolt.proto
$(PROTOC) --proto_path=. -I./googleapis --grpc_out=. --plugin=protoc-gen-grpc=$(GRPC_CPP_PLUGIN_PATH) voltha_protos/tech_profile.proto
-protobuf-target:
+protobuf-target: voltha_protos
$(PROTOC) --proto_path=. -I./googleapis -I./ --cpp_out=. voltha_protos/openolt.proto
$(PROTOC) --proto_path=. -I./googleapis -I./ --cpp_out=. voltha_protos/tech_profile.proto
clean:
- rm -f *.a && cd voltha_protos/ && rm -f *.o *.pb.cc *.pb.h *.proto
+ rm -rf *.a voltha_protos
distclean: clean
rm -rf googleapis
diff --git a/protos/README.md b/protos/README.md
deleted file mode 100644
index 6e892c4..0000000
--- a/protos/README.md
+++ /dev/null
@@ -1,3 +0,0 @@
-# openolt-api
-
-**openolt-api** is the protobuf definition of the gRPC service implemented by [OpenOLT](https://github.com/OpenOLT). See [openolt](https://github.com/OpenOLT/openolt) and [openasf](https://github.com/OpenOLT/openasf).
diff --git a/protos/voltha_protos/README.md b/protos/voltha_protos/README.md
deleted file mode 100644
index 84c6460..0000000
--- a/protos/voltha_protos/README.md
+++ /dev/null
@@ -1,5 +0,0 @@
-# Place holder directory for openolt.proto and tech_profile.proto
-
-This is a place holder directory for openolt.proto and tech_profile.proto file downloaded
-from https://github.com/opencord/voltha-protos repo.
-