fix subdoc

.gitignore

@@ -8,27 +8,27 @@ repos
 .DS_Store
 
 # subrepos
-sdran-in-a-box
-onos-operator
-onos-e2t
-onos-a1t
-onos-e2-sm
-onos-api
-onos-ric-sdk-go
-onos-kpimon
-onos-pci
-onos-config
-onos-topo
-onos-uenib
-onos-cli
-onos-exporter
-onos-mlb
-onos-mho
-onos-rsm
-onos-proxy
-ran-simulator
-openairinterface5g
-onos-ric-python-apps
-onos-ric-sdk-py
+#sdran-in-a-box
+#onos-operator
+#onos-e2t
+#onos-a1t
+#onos-e2-sm
+#onos-api
+#onos-ric-sdk-go
+#onos-kpimon
+#onos-pci
+#onos-config
+#onos-topo
+#onos-uenib
+#onos-cli
+#onos-exporter
+#onos-mlb
+#onos-mho
+#onos-rsm
+#onos-proxy
+#ran-simulator
+#openairinterface5g
+#onos-ric-python-apps
+#onos-ric-sdk-py
 .idea
 

Makefile

@@ -65,6 +65,7 @@ clean-all: clean
 # checkout the repos inside repos/ dir
 repos:
 	mkdir repos
+	mkdir -p subdocs
 
 # build directory paths in repos/* to perform 'git clone <repo>' into
 CHECKOUT_REPOS   = $(foreach repo,$(OTHER_REPO_DOCS),repos/$(repo))
@@ -90,7 +91,9 @@ $(OTHER_REPO_DOCS): | $(CHECKOUT_REPOS)
     cd "repos/$@" && git fetch && git checkout $$GIT_REF ;\
   fi
 	GIT_SUBDIR=`grep '^$@ ' git_refs | awk '{print $$2}'` ;\
-  cp -r repos/$(@)$$GIT_SUBDIR $@ ;\
+  mkdir -p $(@) ;\
+  cp repos/$(@)$$GIT_SUBDIR*.md $@/ ;\
+  cp -r repos/$(@)$$GIT_SUBDIRdocs $@/ ;\
 
 # generate a list of git checksums suitable for updating git_refs
 freeze: repos
@@ -108,7 +111,7 @@ prep: | $(OTHER_REPO_DOCS)
 # build multiple versions
 multiversion: $(VENV_NAME) Makefile | prep $(OTHER_REPO_DOCS)
 	source $</bin/activate ; set -u ;\
-  sphinx-multiversion "$(SOURCEDIR)" "$(BUILDDIR)/multiversion" $(SPHINXOPTS)
+  	sphinx-multiversion "$(SOURCEDIR)" "$(BUILDDIR)/multiversion" $(SPHINXOPTS)
 	cp "$(SOURCEDIR)/_templates/meta_refresh.html" "$(BUILDDIR)/multiversion/index.html"
 
 # Catch-all target: route all unknown targets to Sphinx using the new

conf.py

@@ -45,7 +45,7 @@ def get_version():
 # needs_sphinx = '1.0'
 
 # make all warnings errors
-warning_is_error = True
+warning_is_error = False
 
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom

index.rst

@@ -31,24 +31,24 @@ can be found on the `ONF Wiki <https://wiki.opennetworking.org/>`_.
    :hidden:
    :caption: Components
 
-   repos/onos-api/README
-   repos/onos-ric-sdk-go/README
-   repos/onos-operator/README
-   repos/onos-e2t/README
-   repos/onos-a1t/README
-   repos/onos-e2-sm/README
-   repos/onos-kpimon/README
-   repos/onos-pci/README
-   repos/onos-config/README
-   repos/onos-topo/README
-   repos/onos-uenib/README
-   repos/onos-proxy/README
-   repos/onos-cli/README
-   repos/onos-exporter/README
-   repos/onos-mlb/README
-   repos/onos-mho/README
-   repos/onos-rsm/README
-   repos/ran-simulator/README
+   onos-api/README
+   onos-ric-sdk-go/README
+   onos-operator/README
+   onos-e2t/README
+   onos-a1t/README
+   onos-e2-sm/README
+   onos-kpimon/README
+   onos-pci/README
+   onos-config/README
+   onos-topo/README
+   onos-uenib/README
+   onos-proxy/README
+   onos-cli/README
+   onos-exporter/README
+   onos-mlb/README
+   onos-mho/README
+   onos-rsm/README
+   ran-simulator/README
    oai_cu_cp
 
 .. toctree::

onos-a1t/README.md

@@ -0,0 +1,29 @@
+<!--
+SPDX-FileCopyrightText: 2019-present Open Networking Foundation <[email protected]>
+
+SPDX-License-Identifier: Apache-2.0
+-->
+
+# onos-a1t
+A1 AP Termination module for ONOS SD-RAN (µONOS Architecture)
+
+## Overview
+The `onos-a1t` is the A1 termination node in the near-RT RIC for A1 interface to communicate the near-RT RIC with the non-RT RIC.
+It is the proxy that forwards incoming A1 messages from the non-RT RIC to appropriate xApps or outgoing A1 messages from xApps to the non-RT RIC.
+As per the O-RAN Working Group 2 specification, `onos-a1t` should support A1 messages for (i) the policy management, (ii) the enrichment information, and (iii) the machine learning model management.
+As of today, since the O-RAN A1 specification only defines the policy management data model, `onos-a1t` only supports the policy management service.
+
+Regarding O-RAN specifications, `onos-a1t` supports A1 Application Protocol v03.01 and A1 Type Definitions v02.00.
+
+## Interaction
+The `onos-a1t` interacts with at least three nodes: (i) `onos-topo`, (ii) `A1-enabled xApps` and (iii) `non-RT RIC`.
+To begin with, `onos-a1t` keeps listening the `onos-topo` to check if there is new `A1-enabled xApps` deployed and if there are `A1-enabled xApps` already running.
+Basically, the A1-enabled `xApps` initially stores its A1 interface information, such as supported A1 services (i.e., the policy management, the enrichment information, and the machine learning model management) and A1 interface endpoint (i.e., IP address and port number).
+Listening `onos-topo`, `onos-a1t` scrapes the A1 interface information and store it into the `onos-a1t` local store.
+With the A1 interface information, `onos-a1t` starts creating the gRPC session with appropriate xApps to communicate with each other.
+A gRPC server is the `A1-enabled xApp`, whereas `onos-a1t` acts as the gRPC client (Note that this design is able to support the high availability and reliability by using the replicas for the near future).
+In order to communicate with the non-RT RIC, `onos-a1t` has both an HTTP server and an HTTP client.
+And of course, the non-RT RIC has to have both the HTTP server and the HTTP client for the bi-directional communication over HTTP.
+The HTTP server in `onos-a1t` receives the JSON formatted A1 interface message from the non-RT RIC.
+The HTTP client in `onos-a1t` is the client that sends the JSON formatted outgoing A1 interface messages to the non-RT RIC.
+The HTTP client and server implementations are auto generated from the OpenAPI definitions provided by the A1 Application Protocol specifications.

onos-api/CODE_OF_CONDUCT.md

@@ -0,0 +1,8 @@
+<!--
+SPDX-FileCopyrightText: 2020-present Open Networking Foundation <[email protected]>
+SPDX-License-Identifier: Apache-2.0
+-->
+
+We expect all ONF employees, member companies, and participants to abide by our [Code of Conduct](https://www.opennetworking.org/wp-content/themes/onf/img/onf-code-of-conduct.pdf).
+
+If you are being harassed, notice that someone else is being harassed, or have any other concerns involving someone’s welfare, please notify a member of the ONF team or email [[email protected]]([email protected]). 

onos-api/README.md

@@ -0,0 +1,49 @@
+<!--
+SPDX-FileCopyrightText: 2020-present Open Networking Foundation <[email protected]>
+SPDX-License-Identifier: Apache-2.0
+-->
+
+# onos-api
+gRPC API definitions for the µONOS platform
+
+## Overview
+This repository houses not only the `.proto` files, but also a number of automatically generated artifacts, e.g. `.pb.go`, `.py` files and similarly for other languages that may be added in the future.
+
+The source tree structure is paritioned into `proto`, which contains the canonical protobuf definitions and a top-level directory for each of the supported languages. The structure within each of the language-specific directories reflects the idoms and conventions appropriate to each language.
+
+## Proto
+The top-level package for the protobuf definitions is `onos` and the next level subpackage is the name of the particular platform subsystem, such as `config`, `topo`, etc. This directory tree should contain exclusively the `.proto` files and not be tainted by any other artifacts, especially any language-specific ones.
+
+The proto files are compiled and processed via `build/bin/compile-protos.sh` script, which is invoked by the `Makefile`. All protofiles here should follow the established guidelines and must pass the protobuf lint checker enforcing these conventions.
+
+## Golang
+The `go` source tree holds the automatically-generated `.pb.go` artifacts and also any manually authored `.go` source files written in support of the Golang bindings. To minimize the churn and to exercise tighter control over versioning, the generated files are also versioned and maintained in the SCM repo.
+
+The root package of the module is `github.com/onosproject/onos-api/go/onos`, with subpackages being named after each of the platform subsystems, mirroring the structure of the `proto` packages. Golang projects that wish to import µONOS API packages should include the following in the requirements section of their `go.mod` file:
+
+```go
+require (
+  ...
+	github.com/onosproject/onos-api/go v0.6.1
+  ...
+)
+
+```
+
+Additionally, Go bindings are generated with mocks for testing with [gomock]. Mocks of Protobuf interfaces can be constructed via the same package as the interfaces they mock:
+
+```go
+import topoapi "github.com/onosproject/onos-api/go/onos/topo"
+...
+mockClient := topoapi.NewMockTopoClient(ctrl)
+```
+
+## Python
+
+The `python` source tree holds gRPC bindings are generated for [Python]. Pyhton bindings are generated with the [python-betterproto] protoc plugin and support Python3's `asyncio` framework.
+
+[gomock]: https://github.com/golang/mock
+[Go]: https://golang.org/
+[Protobuf]: https://developers.google.com/protocol-buffers
+[Python]: https://www.python.org
+[python-betterproto]: https://github.com/danielgtaylor/python-betterproto

onos-cli/CODE_OF_CONDUCT.md

@@ -0,0 +1,8 @@
+<!--
+SPDX-FileCopyrightText: 2019-present Open Networking Foundation <[email protected]>
+SPDX-License-Identifier: Apache-2.0
+-->
+
+We expect all ONF employees, member companies, and participants to abide by our [Code of Conduct](https://www.opennetworking.org/wp-content/themes/onf/img/onf-code-of-conduct.pdf).
+
+If you are being harassed, notice that someone else is being harassed, or have any other concerns involving someone’s welfare, please notify a member of the ONF team or email [[email protected]]([email protected]). 

onos-cli/README.md

@@ -0,0 +1,20 @@
+<!--
+SPDX-FileCopyrightText: 2019-present Open Networking Foundation <[email protected]>
+SPDX-License-Identifier: Apache-2.0
+-->
+
+# onos-cli
+[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://github.com/onosproject/onos-cli/blob/master/LICENSE)
+[![Go Report Card](https://goreportcard.com/badge/github.com/onosproject/onos-cli)](https://goreportcard.com/report/github.com/onosproject/onos-cli)
+[![GoDoc](https://godoc.org/github.com/onosproject/onos-cli?status.svg)](https://godoc.org/github.com/onosproject/onos-cli)
+
+This is the implementation of a consolidated `onos` command-line interface for ONOS (µONOS Architecture)
+
+The goal is to provide a single CLI executable that can be used as a means to access CLI functionality
+of a number of different ONOS subsystems, e.g. topo, config, control.
+
+* [Deploying onos-cli with Helm](docs/deployment.md)
+* [ONOS command line client](docs/cli/onos.md)
+
+
+

onos-config/CODE_OF_CONDUCT.md

@@ -0,0 +1,9 @@
+<!--
+SPDX-FileCopyrightText: 2019-present Open Networking Foundation <[email protected]>
+
+SPDX-License-Identifier: Apache-2.0
+-->
+
+We expect all ONF employees, member companies, and participants to abide by our [Code of Conduct](https://www.opennetworking.org/wp-content/themes/onf/img/onf-code-of-conduct.pdf).
+
+If you are being harassed, notice that someone else is being harassed, or have any other concerns involving someone’s welfare, please notify a member of the ONF team or email [[email protected]]([email protected]). 

onos-config/README.md

@@ -0,0 +1,19 @@
+<!--
+SPDX-FileCopyrightText: 2019-present Open Networking Foundation <[email protected]>
+
+SPDX-License-Identifier: Apache-2.0
+-->
+
+# onos-config
+[![Go Report Card](https://goreportcard.com/badge/github.com/onosproject/onos-config)](https://goreportcard.com/report/github.com/onosproject/onos-config)
+[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://github.com/gojp/goreportcard/blob/master/LICENSE)
+[![Coverage Status](https://img.shields.io/coveralls/github/onosproject/onos-config/badge.svg)](https://coveralls.io/github/onosproject/onos-config?branch=master)
+[![GoDoc](https://godoc.org/github.com/onosproject/onos-config?status.svg)](https://godoc.org/github.com/onosproject/onos-config)
+
+
+ONOS Configuration subsystem built using the µONOS architecture
+
+You can find all the documentation under [docs](docs) directory. 
+A good place to start is the [README](docs/README.md). 
+
+Overall µONOS documentation is also published on its own [website](https://docs.onosproject.org).

onos-e2-sm/CODE_OF_CONDUCT.md

@@ -0,0 +1,9 @@
+<!--
+SPDX-FileCopyrightText: 2019-present Open Networking Foundation <[email protected]>
+
+SPDX-License-Identifier: Apache-2.0
+-->
+
+We expect all ONF employees, member companies, and participants to abide by our [Code of Conduct](https://www.opennetworking.org/wp-content/themes/onf/img/onf-code-of-conduct.pdf).
+
+If you are being harassed, notice that someone else is being harassed, or have any other concerns involving someone’s welfare, please notify a member of the ONF team or email [[email protected]]([email protected]). 

onos-e2-sm/README.md

@@ -0,0 +1,89 @@
+<!--
+SPDX-FileCopyrightText: 2019-present Open Networking Foundation <[email protected]>
+
+SPDX-License-Identifier: Apache-2.0
+-->
+
+# onos-e2-sm
+[O-RAN] defines the **E2 Service Models** in the form of "ASN.1" specifications. 
+
+Each Service Model defines 5 top level objects:
+1. **RAN Function Description** (from the E2Node, describes the supported actions and triggers)
+1. **Event Trigger Defintion** (contained in a `RICSubscriptionRequest`, defines the conditions on which E2Node should send a `RICIndication`)
+1. **Action Definition** (contained in a `RICSubscriptionRequest`, defines the actions on an E2Node)
+1. **Indication Header** (contained in a `RICIndication`, describes general parameters of the source E2 Node)
+1. **Indication Message** (contained in a `RICIndication`, describes specific parameters requested)
+
+## Implementation in SD-RAN
+The `onos-e2-sm` project provides, for each of these Service Models:
+* A Protobuf translation of these ASN.1 specifications e.g. [e2sm_kpm_ies.proto](servicemodels/e2sm_kpm/v1beta1/e2sm_kpm_ies.proto)
+* Go code mapping between Protobuf and ASN.1 PER encoding
+
+The implementation can be accessed as either:
+* a Go module e.g. `go get github.com/onosproject/onos-e2-sm/servicemodels/[email protected]`
+  (preferred for **xApps** who only need to access the Proto defintions) or
+* as a Go **plugin** e.g. `e2sm_kpm.so.1.0.0` (allowing a loose coupling with `onos-e2t` and `ran-simulator`)
+
+> Since dynamically loaded modules in Go require being compiled in the code of the target they will plugin to, there
+> are 2 versions of the plugin docker file produced `onosproject/service-model-docker-e2sm_kpm-1.0.0`
+> and `onosproject/service-model-ransim-e2sm_kpm-1.0.0`
+
+> Third party vendors will be able to build their own Service Models and load them in to `onos-e2t` using the plugin method,
+> and will be able to access the translated Protobuf in corresponding xApps
+
+### Key Performance Metrics (E2SM_KPM)
+This is the first E2 Service Model to be handled by SD-RAN - it is for extracting statistics from the E2Node.
+
+Currently supported version is E2SM KPM v2.0.3. E2SM KPM v1 is partially implemented and not supported anymore.
+
+There is also an implementation of KPMv2 SM with Go-based APER library (produces APER bytes out of Protobuf).
+
+
+### Native Interface (E2SM_NI)
+While the Proto definitions have been created for this Service Model, the Go mapping code has not been implemented in SD-RAN yet.
+
+### RAN Control (E2SM_RC_PRE)
+Pre-standard E2 Service model with PCI and Neighbor relation table information from E2 Nodes.
+
+There is also an implementation of RC-PRE SM with Go-based APER library.
+
+### Mobile HandOver (E2SM_MHO)
+E2 Service model for handling Mobile HandOver use case.
+
+There is also an implementation of MHO SM with Go-based APER library.
+
+### RAN Slicing (E2SM_RSM)
+E2 service model for handling RAN Slicing use case. It was implemented with Go-based APER library.
+
+## Development
+Service models are created from the ASN1 models stored at:
+https://github.com/onosproject/openairinterface5g/tree/develop-onf/openair2/RIC_AGENT/MESSAGES/ASN1/R01
+
+From these:
+
+* Protobuf is generated with `asn1c -B` (requires the specially modified version of `asn1c` tool - [asn1c](https://github.com/onosproject/asn1c))
+* Go code is generated from this Protobuf as an interface/reusable layer e.g. [e2sm_kpm_ie.pb.go](servicemodels/e2sm_kpm/v1beta1/e2sm-kpm-ies/e2sm_kpm_ies.pb.go)
+* C code is generated the version of the `asn1c` tool from the [O-RAN Software Community](https://gerrit.o-ran-sc.org/r/admin/repos/com/asn1c)
+  with `asn1c -fcompound-names -fincludes-quoted -fno-include-deps -findirect-choice -gen-PER -no-gen-OER -D.` e.g. [E2SM-KPM-IndicationHeader.h](servicemodels/e2sm_kpm/kpmctypes/E2SM-KPM-IndicationHeader.h)
+* Then glue code is generated by hand (at first) using `CGO` (wrapping the C code in Go) e.g. [E2SM-KPM-IndicationHeader.go](servicemodels/e2sm_kpm/kpmctypes/E2SM-KPM-IndicationHeader.go)
+  * It's also possible to use `protoc-gen-cgo`, a `protoc` plugin that prints CGo code out of Protobuf. Some hand tweaks are still needed to be done.  
+
+> To generate the C code with the O-RAN Software Community version of the `asn1c` tool,
+> it must be installed on your system with `sudo make install`.
+> This is because it takes skeleton file from `/usr/local/share/asn1c`
+> regardless of where it is run from.
+
+### The E2AP (E2 Application Protocol) is not a Service Model, and so is kept completely inside the `onos-e2t`, see [here](https://github.com/onosproject/onos-e2t/blob/master/api/e2ap/README.md).
+
+[O-RAN]: https://www.o-ran.org/
+
+# FAQ
+### - How to create your own SM?
+[Here](docs/sm-howto.md) you can find a tutorial on how to create your own SM.
+
+### - What to do if an encoding/decoding error happens?
+A comprehensive guide on how to deal with encoding/decoding errors could be found [here](docs/encoding_issues-howto.md).
+It also describes the APER tags usage within the Protobuf.
+
+### - Is there any description of the error messages produced by the Go APER library?
+Yes, a brief description of the most common error messages can be found [here](https://github.com/onosproject/onos-lib-go/blob/master/pkg/asn1/aper/error_list.md). 

onos-e2t/CODE_OF_CONDUCT.md

@@ -0,0 +1,8 @@
+<!--
+SPDX-FileCopyrightText: 2020 Open Networking Foundation <[email protected]>
+
+SPDX-License-Identifier: Apache-2.0
+-->
+We expect all ONF employees, member companies, and participants to abide by our [Code of Conduct](https://www.opennetworking.org/wp-content/themes/onf/img/onf-code-of-conduct.pdf).
+
+If you are being harassed, notice that someone else is being harassed, or have any other concerns involving someone’s welfare, please notify a member of the ONF team or email [[email protected]]([email protected]).