First cut of Diag gNOI micro service

Author: aghaffarkhah

diag/BUILD.bazel

@@ -0,0 +1,14 @@
+load("@io_bazel_rules_go//proto:go_proto_library.bzl", "go_proto_library")
+
+proto_library(
+  name = "diag_proto",
+  srcs = ["diag.proto"],
+)
+
+go_proto_library(
+    name = "go_default_library",
+    srcs = ["diag.proto"],
+    visibility = ["//visibility:public"],
+    rules_go_repo_only_for_internal_use = "@",
+    has_services = 1,
+)

diag/diag.proto

@@ -0,0 +1,236 @@
+//
+// Copyright 2017 Google Inc. All Rights Reserved.
+//
+// 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.
+//
+
+// This file defines the gNOI APIs used to perform diagnostic operations on a
+// switching box.
+syntax = "proto3";
+
+package gnoi.diag;
+
+// The Diag service exports to main set of RPCs:
+// 1- BERT related RPCs: Used to perform Bit Error Rate Test (BERT)
+//    operation on a set of ports.
+// 2- BURNING related RPCs: Used to perform a vendor-provide Burnin test on the
+//    switch to ensure the box is ready to start serving traffic. Burnin tests
+//    are typically run by HwOps in the datacenter, as part of turnup or repair
+//    workflow.
+service Diag {
+  // Starts BERT operation on a set of ports. Each BERT operation is uniquely
+  // identified by an ID, which is given by the caller. The caller can then
+  // use this ID (as well as the list of the ports) to stop the BERT operation
+  // and/or get the BERT results. This RPC is expected to return an error status
+  // in the the following situations:
+  // - When BERT operation is not supported on any of the ports specified by
+  //   the request.
+  // - When BERT is already in progress on any port specified by the request.
+  // - In case of any low-level HW/SW internal errors.
+  // The RPC returns an OK status of none of these situations is encountered.
+  rpc StartBERT(StartBERTRequest) returns(StartBERTResponse) {}
+
+  // Stops an already in-progress BERT operation on a set of ports. The caller
+  // uses the BERT operation ID it previously used when starting the operation
+  // to stop it. The RPC is expected to return an error status in the following
+  // situations:
+  // - When there is at least one BERT operation in progress on a port which
+  //   cannot be stopped in the middle of the operation (either due to lack of
+  //   support or internal problems).
+  // - When no BERT operation, which matches the given BERT operation ID, is in
+  //   progress or completed on any of the ports specified by the request.
+  // - When the BERT operation ID does not match the in progress or completed
+  //   BERT operation on any of the ports specified by the request.
+  // The RPC returns an OK status of none of these situations is encountered.
+  // Note that a BERT operation is considered completed if switch has a
+  // record of it. Also note that it is OK to receive a stop request for a port
+  // which has completed BERT, as long as the recorded BERT operation ID matches
+  // the one specified by the request.
+  rpc StopBERT(StopBERTRequest) returns(StopBERTResponse) {}
+
+  // Gets BERT results during the BERT operation or after it completes. The
+  // caller uses the BERT operation ID it previously used when starting the
+  // operation to query it. The switch is expected to keep the results for
+  // last N BERT operations for some amount of time, as specified by the
+  // product requirement. This RPC is expected to return error status in the
+  // following situations:
+  // - When no BERT operation, which matches the given BERT operation ID, is in
+  //   progress or completed on any of the ports specified by the request.
+  // - When the BERT operation ID does not match the in progress or completed
+  //   BERT operation on any of the ports specified by the request.
+  // The RPC returns an OK status of none of these situations is encountered.
+  // Note that a BERT operation is considered completed if switch has a
+  // record of it.
+  rpc GetBERTResult(GetBERTResultRequest) returns(GetBERTResultResponse) {}
+
+  // TODO(aghaffar): Add BURNIN related RPCs.
+}
+
+// Common sequence generating monic polynomials used for PRBS.
+enum PrbsPolynomial {
+  PRBS_POLYNOMIAL_UNKNOWN = 0;  // default invalid choice.
+  PRBS_POLYNOMIAL_PRBS7 = 1;
+  PRBS_POLYNOMIAL_PRBS9 = 2;
+  PRBS_POLYNOMIAL_PRBS15 = 3;
+  PRBS_POLYNOMIAL_PRBS20 = 4;
+  PRBS_POLYNOMIAL_PRBS23 = 5;
+  PRBS_POLYNOMIAL_PRBS31 = 6;
+}
+
+// Status returned for each per-port BERT request.
+enum BertStatus {
+  // default invalid choice.
+  BERT_STATUS_UNKNOWN = 0;
+  // BERT requests (Start, Stop, GetStatus) were processed successfully.
+  BERT_STATUS_OK = 1;
+  // The specified port was not found.
+  BERT_STATUS_NON_EXISTENT_PORT = 2;
+  // HW error was encountered while performing BERT operation.
+  BERT_STATUS_HARDWARE_ACCESS_ERROR = 3;
+  // PRBS generating polynomial is not supported by the target.
+  BERT_STATUS_UNSUPPORTED_PRBS_POLYNOMIAL = 4;
+  // There is already a BERT running on the specified port. Returned when
+  // `StartBert` RPC tries to add run BERT on an already in-use port.
+  BERT_STATUS_PORT_ALREADY_IN_BERT = 5;
+  // There is no BERT running on the specified port. Returned when `StopBert`
+  // or `GetBertResult` RPC was called for an idle port.
+  BERT_STATUS_PORT_NOT_RUNNING_BERT = 6;
+  // The specified test duration is too small.
+  BERT_STATUS_TEST_DURATION_TOO_SHORT = 7;
+  // The specified test duration is larger than maximum allowed.
+  BERT_STATUS_TEST_DURATION_TOO_LONG = 8;
+  // The given BERT operation ID is not known. Returned for `StopBert` and
+  // `GetBertResult` RPCs.
+  BERT_STATUS_BERT_OPERATION_ID_NOT_FOUND = 9;
+  // The given BERT operation ID is already in use. Returned when `StartBert`
+  // RPC uses an ID which is already memorized for a BERT operation.
+  BERT_STATUS_BERT_OPERATION_ID_ALREADY_IN_USE = 10;
+  // Failure to get the peer lock.
+  BERT_STATUS_PEER_LOCK_FAILURE = 11;
+  // Lost the peer lock after locking once.
+  BERT_STATUS_PEER_LOCK_LOST = 12;
+  // Misc internal errors that cannot be categorized by any of the previous
+  // error codes.
+  BERT_STATUS_INTERNAL_ERROR = 13;
+}
+
+message StartBERTRequest {
+  // Per port BERT start requests.
+  message PerPortRequest {
+    // Path to the interface corresponding to the port.
+    gnoi.Path interface = 1;  // required
+    // The selected PRBS generating polynomial for BERT.
+    PrbsPolynomial prbs_polynomial = 2;
+    // BERT duration in mins. Must be a positive number.
+    uint32 test_duration_in_mins = 3;  // required
+  }
+  // Unique BERT operation ID specified by the client. Multiple BERTs run on
+  // different ports can have the same BERT operation ID. This ID will be used
+  // later to stop the operation and/or get its results.
+  string bert_operation_id = 1;
+  // All the per-port BERTs that are considered one BERT operation and have the
+  // same BERT operation ID.
+  repeated PerPortRequest per_port_requests = 2;
+}
+
+message StartBERTResponse {
+  // Per-port BERT start responses.
+  message PerPortResponse {
+    // Path to the interface corresponding to the port.
+    gnoi.Path interface = 1;
+    // BERT start status for this port.
+    BertStatus status = 2;
+  }
+  // The same BERT operation ID given by the request.
+  string bert_operation_id = 1;
+  // Captures the results of starting BERT on a per-port basis.
+  repeated PerPortResponse per_port_responses = 2;
+}
+
+message StopBERTRequest {
+  // Per-port BERT stop requests.
+  message PerPortRequest {
+    // Path to the interface corresponding to the port.
+    gnoi.Path interface = 1;
+  }
+  // The same BERT operation ID given when BERT operation was started.
+  string bert_operation_id = 1;
+  // All the per-port BERTs that need to be stopped. Must be part of the BERT
+  // operation specified by the `bert_operation_id` above.
+  repeated PerPortRequest per_port_requests = 2;
+}
+
+message StopBERTResponse {
+  // Per-port BERT stop responses.
+  message PerPortResponse {
+    // Path to the interface corresponding to the port.
+    gnoi.Path interface = 1;
+    // BERT stop status for this port.
+    BertStatus status = 2;
+  }
+  // The same BERT operation ID given by the request.
+  string bert_operation_id = 1;
+  // Captures the results of stopping BERT on a per-port basis.
+  repeated PerPortResponse per_port_responses = 2;
+}
+
+message GetBERTResultRequest {
+  // Per-port BERT get result requests.
+  message PerPortRequest {
+    // Path to the interface corresponding to the port.
+    gnoi.Path interface = 1;
+  }
+  // The same BERT operation ID given when BERT operation was started.
+  string bert_operation_id = 1;
+  // All the per-port BERTs result of which we want to query. Must be part of
+  // the BERT operation specified by the `bert_operation_id` above.
+  repeated PerPortRequest per_port_requests = 2;
+  // If set to true, the results for all the per-port BERTs will be returned.
+  // `bert_operation_id` and `per_port_requests` will be ignored will be
+  // ignored in that case.
+  bool result_from_all_ports = 3;
+}
+
+message GetBERTResultResponse {
+  // Per-port BERT results/status.
+  message PerPortResponse {
+    // Path to the interface corresponding to the port.
+    gnoi.Path interface = 1;
+    // BERT result get status for this port. Only if the status is
+    // BERT_STATUS_OK the rest of the fields below are meaningful.
+    BertStatus status = 2;
+    // The ID of the BERT operation running on this port. Since the caller
+    // can query the BERT results for all the ports, ID can potentially be
+    // different for different ports.
+    string bert_operation_id = 3;
+    // The selected PRBS generating polynomial for BERT on this port.
+    PrbsPolynomial prbs_polynomial = 4;
+    // The last time BERT started on this port.
+    uint64 last_bert_start_timestamp = 5;
+    // The last time BERT results were read for this port.
+    uint64 last_bert_get_result_timestamp = 6;
+    // Indicate whether BERT peer lock has was established. If false,
+    // `bert_lock_lost`, `error_count_per_minute`, and `total_errors` will not
+    // be meaningful.
+    bool peer_lock_established = 7;
+    // Indicate whether BERT peer lock was lost after being established
+    // once.
+    bool peer_lock_lost = 8;
+    // Sequence of bit errors per min since lock was established.
+    repeated uint32 error_count_per_minute = 9;
+    // Total number of bit errors accumulated since lock was established.
+    uint64 total_errors = 10;
+  }
+  // Captures the BERT results on a per-port basis.
+  repeated PerPortResponse per_port_responses = 1;
+}