Method Name Request / Response Type Description
Create CreateRequest
CreateResponse

Create will dispatch a create operation for each interface and return.
The rpc will only return an error in the case that gNOI service cannot
handle the RPC request. Create will return an error on failure to
create the qualification.

Get GetRequest
GetResponse

Get will return the status for the provided qualification ids.

Capabilities CapabilitiesRequest
CapabilitiesResponse

Capabilities will return the capabilities of the gnoi.LinkQualification
service implementation. This RPC is used to allow the caller to
orchestrate the peer requirements of the service to complete a link
qualification between two devices.

Delete DeleteRequest
DeleteResponse

Delete will remove the qualification results for the provided ids.
If the qualification is not in QUALIFICATION_STATE_COMPLETED
or QUALIFICATION_STATE_ERROR, the qualification will be canceled then
deleted as requested.
If the qualification cannot be stopped or deleted a status will be returned
with the error.
If the id is not found NOT_FOUND will be returned.

List ListRequest
ListResponse

List qualifications currently on the target.

Field Type Description
min_setup_duration google.protobuf.Duration

The minimum time required to set up the ASIC loopback mode.

min_teardown_duration google.protobuf.Duration

The minimum time required to return the interfaces to their pre-test state
following a qualification.

fields (repeated) HeaderMatchField

AsicLoopbackConfiguration

This is where any l2/l3/l4 match criteria would be described.

Empty message

Empty message

Field Type Description
time google.protobuf.Timestamp

Current timestamp on the service.

ntp_synced bool

Indicates that the device's time is currently synchronised via NTP.

generator GeneratorCapabilities

Capabilities that the generator and reflect support on the
service. If the top level field is unset the service cannot act
as any defined generator or reflector.

reflector ReflectorCapabilities

max_historical_results_per_interface uint64

Maximum number of results allowed to be stored per interface.
The minimum supported just be 2 or greater.

CreateRequest

CreateRequest contains the list of interfaces to be Qualified.
Each interface must only appear once and all IDs to be used
by qualification must be unique on the device.

Field Type Description
interfaces (repeated) QualificationConfiguration

CreateResponse

CreateResponse will return a map of the status of each CreateRequest.
The map key is the qualification id requested in the CreateRequest.
Valid Status responses are:
OK: create has been accepted.
NOT_FOUND: interface_name could not be found on the service.
INVALID_ARGUMENT: if any of the configuration is not supported.
ALREADY_EXISTS: if the qualification id is already in use.

Field Type Description
status (repeated) CreateResponse.StatusEntry

Field Type Description
key string

value google.rpc.Status

DeleteRequest

DeleteRequest will delete the qualification results for the provided id.

Field Type Description
ids (repeated) string

DeleteResponse

Delete response will contain a list of all id's in the request to be deleted.
If the id was not found NOT_FOUND will be returned.

Field Type Description
results (repeated) DeleteResponse.ResultsEntry

Field Type Description
key string

value google.rpc.Status

GeneratorCapabilities

If the service does not support any of the defined
modes then the message should be unset.

Field Type Description
packet_generator PacketGeneratorCapabilities

packet_injector PacketInjectorCapabilities

GetRequest

GetRequest returns the status for the provided ids.

Field Type Description
ids (repeated) string

GetResponse

GetResponse returns a map containing the values for all requested
Qualification results. If the QualificationResult state is
QUALIFICATION_STATE_ERROR the caller should inspect the status field for
the exact error code and message.
Expected errors codes:
NOT_FOUND when the requested id was not found by the service.
INVALID_ARGUMENT for any configuration parameter which is unsupported.

Field Type Description
results (repeated) GetResponse.ResultsEntry

Field Type Description
key string

value QualificationResult

Empty message

Field Type Description
results (repeated) ListResult

The results that have not yet been deleted from the device.

Field Type Description
id string

state QualificationState

interface_name string

Field Type Description
start_time google.protobuf.Timestamp

The timestamp for the start of the qualification. Based on the
provided configuration the qualification setup must
at least start at (start_time - min_setup_time).

end_time google.protobuf.Timestamp

The timestamp for the end of qualification.

teardown_time google.protobuf.Timestamp

Timestamp to begin teardown. If unset teardown will start
immediately after end_time.
This value allows for a peer to wait for before tearing down
the port under test.
teardown_time must occur after end_time.

Field Type Description
max_bps uint64

bits per second

max_pps uint64

packets per second

min_mtu uint32

minimum MTU supported.

max_mtu uint32

max MTU supported.

min_setup_duration google.protobuf.Duration

The minimum duration required to set up a packet generator-based
qualification.

min_teardown_duration google.protobuf.Duration

The minimum time required to return the affected interface to the
pre-test state.

min_sample_interval google.protobuf.Duration

The minimum interval between samples for statistics relating to the
qualification.

PacketGeneratorConfiguration

A packet generator implementation defines that the generator of the side of
the link will be responsible for generating a stream of packets at the
provided rate and size.

Field Type Description
packet_rate uint64

Packet per second rate to use for this test.

packet_size uint32

Size of packets to inject.
if unspecified, the default value is 1500 bytes.

Field Type Description
min_mtu uint32

The definitions of fields 1-7 are the same as those described in the
PacketGeneratorCapabilities message.

max_mtu uint32

min_injected_packets uint32

max_injected_packets uint32

min_setup_duration google.protobuf.Duration

min_teardown_duration google.protobuf.Duration

min_sample_interval google.protobuf.Duration

loopback_modes (repeated) PacketInjectorLoopbackMode

Loopback modes that are supported by the device when using the packet
injector mode.

PacketInjectorConfiguration

A packet injector implementation defines that the generator side of the link
will be responsible for both setting the interface into a loopback as well
as injecting individual packets up to packet_count into the closed loop at
the packet_size. These packets will form a closed loop as both sides of the
loop will forward the same set of packets for the duration of the
qualification.

Field Type Description
packet_count uint32

Number of packets to inject into the closed loop.

packet_size uint32

Size of packets to inject.
if unspecified, the default value is 1500 bytes.

loopback_mode (one of)
pmd_loopback PmdLoopbackConfiguration

PMD based loopback encompasses either PHY based port
loopbacks or port based ASIC loopbacks which do
use forwarding engine processing.
Their use may limit the stats available for the
qualification.

asic_loopback AsicLoopbackConfiguration

ASIC based loops are done inside the forwarding
engine and must have stats available to the
qualification.

PmdLoopbackCapabilities

PMD or port based loopbacks are expect to have limited ability
to report packet counters. Packet rate/errors/transmitted/received
may not be available on the remote side for these types of loopbacks.

Field Type Description
min_setup_duration google.protobuf.Duration

min_teardown_duration google.protobuf.Duration

Empty message

Field Type Description
id string

Id to be used for this interface qualification run.

interface_name string

interface name on the device must be unique to the device.

timing (one of)
ntp NTPSyncedTiming

rpc RPCSyncedTiming

endpoint_type (one of)
packet_generator PacketGeneratorConfiguration

packet_injector PacketInjectorConfiguration

pmd_loopback PmdLoopbackConfiguration

asic_loopback AsicLoopbackConfiguration

Field Type Description
id string

ID of the qualification.

interface_name string

Interface name of the qualification.

state QualificationState

The state the test was in when the results were snapshotted.

packets_sent uint64

The number of qualification packets sent.

packets_received uint64

The number of qualification packets received.

packets_error uint64

The number of packets transmitted that experienced corruption.

packets_dropped uint64

The number of packets dropped by the device due to internal drop,
lookup or forwarding errors.

start_time google.protobuf.Timestamp

The qualification start time. Also when the first snapshot of
results are taken.

end_time google.protobuf.Timestamp

The qualification end time or the current snapshot time since epoch.

expected_rate_bytes_per_second uint64

Expected rate for the qualification. This is the computed or
observed rate that the service expected to be maintained
throughout the qualification duration.

qualification_rate_bytes_per_second uint64

The qualification rate observed during the qualification.
It is updated every min_sample_interval in bytes per second.

status google.rpc.Status

Status response for the Qualification result. Will only be set if the
state is QUALIFICATION_STATE_ERROR.

RPCSyncedTiming

RPCSyncedTiming will be all synchronization by assuming the start rpc's are
sent very close temporally with enough overlap in duration to get valid
results.
The pre_qual_wait will allow the caller to adjust any setup timing
differences between peers. The post_qual_wait will allow for the caller to
adjust any teardown differences in timing between peers.
pre_qual_wait cannot be less than selected endpoint type's min_setup_time.
post_qual_wait cannot be less than the selected endpoint type's
min_teardown_time.

Field Type Description
pre_sync_duration google.protobuf.Duration

pre_sync_duration is the time the service should wait before starting
setup.
For generators this would be the time the remote side needs to put itself
into loopback before generating packets.
For loopbacks this value would be expected to be zero or unset.

setup_duration google.protobuf.Duration

The requested setup time for the endpoint. setup_duration must be >=
min_setup_duration in the service capabilities. If the service
completes setup before setup_duration it must wait setup_duration
before moving to qualification.

duration google.protobuf.Duration

duration is the length of the qualification.

post_sync_duration google.protobuf.Duration

post_sync_duration is the amount time a side should wait before starting
its teardown.
For generators this value would be expected to be zero or unset.
For loopbacks this would be the duration it takes for the generator
to stop sending packets before starting a teardown.

teardown_duration google.protobuf.Duration

This requested teardown duration for the endpoint. teardown_duration
must be >= min_teardown_duration in the service capabilities. If the
service completes before the teardown_duration it must wait teardown
duration before completing.

ReflectorCapabilities

If the service does not support any of the defined
modes then the message should be unset.

Field Type Description
pmd_loopback PmdLoopbackCapabilities

asic_loopback AsicLoopbackCapabilities

Name Number Description
HEADER_MATCH_FIELD_UNSPECIFIED 0

HEADER_MATCH_FIELD_L2 1

HEADER_MATCH_FIELD_L3 2

HEADER_MATCH_FIELD_L4 3

Name Number Description
PACKET_INJECTOR_LOOPBACK_MODE_UNSPECIFIED 0

PACKET_INJECTOR_LOOPBACK_MODE_PMD 1

PACKET_INJECTOR_LOOPBACK_MODE_ASIC 2

QualificationState

States of qualification.

Name Number Description
QUALIFICATION_STATE_UNSPECIFIED 0

QUALIFICATION_STATE_ERROR 1

The qualification has errored.

QUALIFICATION_STATE_IDLE 2

Initial state for the qualification.

QUALIFICATION_STATE_SETUP 3

Interface is being configured.

QUALIFICATION_STATE_RUNNING 4

Qualification underway.

QUALIFICATION_STATE_TEARDOWN 5

Interface is being reset.

QUALIFICATION_STATE_COMPLETED 6

Qualification is complete.

Duration

A Duration represents a signed, fixed-length span of time represented
as a count of seconds and fractions of seconds at nanosecond
resolution. It is independent of any calendar and concepts like "day"
or "month". It is related to Timestamp in that the difference between
two Timestamp values is a Duration and it can be added or subtracted
from a Timestamp. Range is approximately +-10,000 years.

# Examples

Example 1: Compute Duration from two Timestamps in pseudo code.

Timestamp start = ...;
Timestamp end = ...;
Duration duration = ...;

duration.seconds = end.seconds - start.seconds;
duration.nanos = end.nanos - start.nanos;

if (duration.seconds < 0 && duration.nanos > 0) {
duration.seconds += 1;
duration.nanos -= 1000000000;
} else if (duration.seconds > 0 && duration.nanos < 0) {
duration.seconds -= 1;
duration.nanos += 1000000000;
}

Example 2: Compute Timestamp from Timestamp + Duration in pseudo code.

Timestamp start = ...;
Duration duration = ...;
Timestamp end = ...;

end.seconds = start.seconds + duration.seconds;
end.nanos = start.nanos + duration.nanos;

if (end.nanos < 0) {
end.seconds -= 1;
end.nanos += 1000000000;
} else if (end.nanos >= 1000000000) {
end.seconds += 1;
end.nanos -= 1000000000;
}

Example 3: Compute Duration from datetime.timedelta in Python.

td = datetime.timedelta(days=3, minutes=10)
duration = Duration()
duration.FromTimedelta(td)

# JSON Mapping

In JSON format, the Duration type is encoded as a string rather than an
object, where the string ends in the suffix "s" (indicating seconds) and
is preceded by the number of seconds, with nanoseconds expressed as
fractional seconds. For example, 3 seconds with 0 nanoseconds should be
encoded in JSON format as "3s", while 3 seconds and 1 nanosecond should
be expressed in JSON format as "3.000000001s", and 3 seconds and 1
microsecond should be expressed in JSON format as "3.000001s".

Field Type Description
seconds int64

Signed seconds of the span of time. Must be from -315,576,000,000
to +315,576,000,000 inclusive. Note: these bounds are computed from:
60 sec/min * 60 min/hr * 24 hr/day * 365.25 days/year * 10000 years

nanos int32

Signed fractions of a second at nanosecond resolution of the span
of time. Durations less than one second are represented with a 0
`seconds` field and a positive or negative `nanos` field. For durations
of one second or more, a non-zero value for the `nanos` field must be
of the same sign as the `seconds` field. Must be from -999,999,999
to +999,999,999 inclusive.

Timestamp

A Timestamp represents a point in time independent of any time zone or local
calendar, encoded as a count of seconds and fractions of seconds at
nanosecond resolution. The count is relative to an epoch at UTC midnight on
January 1, 1970, in the proleptic Gregorian calendar which extends the
Gregorian calendar backwards to year one.

All minutes are 60 seconds long. Leap seconds are "smeared" so that no leap
second table is needed for interpretation, using a [24-hour linear
smear](https://developers.google.com/time/smear).

The range is from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z. By
restricting to that range, we ensure that we can convert to and from [RFC
3339](https://www.ietf.org/rfc/rfc3339.txt) date strings.

# Examples

Example 1: Compute Timestamp from POSIX `time()`.

Timestamp timestamp;
timestamp.set_seconds(time(NULL));
timestamp.set_nanos(0);

Example 2: Compute Timestamp from POSIX `gettimeofday()`.

struct timeval tv;
gettimeofday(&tv, NULL);

Timestamp timestamp;
timestamp.set_seconds(tv.tv_sec);
timestamp.set_nanos(tv.tv_usec * 1000);

Example 3: Compute Timestamp from Win32 `GetSystemTimeAsFileTime()`.

FILETIME ft;
GetSystemTimeAsFileTime(&ft);
UINT64 ticks = (((UINT64)ft.dwHighDateTime) << 32) | ft.dwLowDateTime;

// A Windows tick is 100 nanoseconds. Windows epoch 1601-01-01T00:00:00Z
// is 11644473600 seconds before Unix epoch 1970-01-01T00:00:00Z.
Timestamp timestamp;
timestamp.set_seconds((INT64) ((ticks / 10000000) - 11644473600LL));
timestamp.set_nanos((INT32) ((ticks % 10000000) * 100));

Example 4: Compute Timestamp from Java `System.currentTimeMillis()`.

long millis = System.currentTimeMillis();

Timestamp timestamp = Timestamp.newBuilder().setSeconds(millis / 1000)
.setNanos((int) ((millis % 1000) * 1000000)).build();

Example 5: Compute Timestamp from Java `Instant.now()`.

Instant now = Instant.now();

Timestamp timestamp =
Timestamp.newBuilder().setSeconds(now.getEpochSecond())
.setNanos(now.getNano()).build();

Example 6: Compute Timestamp from current time in Python.

timestamp = Timestamp()
timestamp.GetCurrentTime()

# JSON Mapping

In JSON format, the Timestamp type is encoded as a string in the
[RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) format. That is, the
format is "{year}-{month}-{day}T{hour}:{min}:{sec}[.{frac_sec}]Z"
where {year} is always expressed using four digits while {month}, {day},
{hour}, {min}, and {sec} are zero-padded to two digits each. The fractional
seconds, which can go up to 9 digits (i.e. up to 1 nanosecond resolution),
are optional. The "Z" suffix indicates the timezone ("UTC"); the timezone
is required. A proto3 JSON serializer should always use UTC (as indicated by
"Z") when printing the Timestamp type and a proto3 JSON parser should be
able to accept both UTC and other timezones (as indicated by an offset).

For example, "2017-01-15T01:30:15.01Z" encodes 15.01 seconds past
01:30 UTC on January 15, 2017.

In JavaScript, one can convert a Date object to this format using the
standard
[toISOString()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString)
method. In Python, a standard `datetime.datetime` object can be converted
to this format using
[`strftime`](https://docs.python.org/2/library/time.html#time.strftime) with
the time format spec '%Y-%m-%dT%H:%M:%S.%fZ'. Likewise, in Java, one can use
the Joda Time's [`ISODateTimeFormat.dateTime()`](
http://www.joda.org/joda-time/apidocs/org/joda/time/format/ISODateTimeFormat.html#dateTime%2D%2D
) to obtain a formatter capable of generating timestamps in this format.

Field Type Description
seconds int64

Represents seconds of UTC time since Unix epoch
1970-01-01T00:00:00Z. Must be from 0001-01-01T00:00:00Z to
9999-12-31T23:59:59Z inclusive.

nanos int32

Non-negative fractions of a second at nanosecond resolution. Negative
second values with fractions must still have non-negative nanos values
that count forward in time. Must be from 0 to 999,999,999
inclusive.

Status

The `Status` type defines a logical error model that is suitable for
different programming environments, including REST APIs and RPC APIs. It is
used by [gRPC](https://github.com/grpc). Each `Status` message contains
three pieces of data: error code, error message, and error details.

You can find out more about this error model and how to work with it in the
[API Design Guide](https://cloud.google.com/apis/design/errors).

Field Type Description
code int32

The status code, which should be an enum value of
[google.rpc.Code][google.rpc.Code].

message string

A developer-facing error message, which should be in English. Any
user-facing error message should be localized and sent in the
[google.rpc.Status.details][google.rpc.Status.details] field, or localized
by the client.

details (repeated) google.protobuf.Any

A list of messages that carry the error details. There is a common set of
message types for APIs to use.

Credentials

Credentials defines credentials needed to perform authentication on a device.

Field Type Description
username string

password (one of)
cleartext string

hashed HashType

HashType

HashType defines the valid hash methods for data verification. UNSPECIFIED
should be treated an error.

Field Type Description
method HashType.HashMethod

hash bytes

Path

Path encodes a data tree path as a series of repeated strings, with
each element of the path representing a data tree node name and the
associated attributes.
Reference: gNMI Specification Section 2.2.2.

Field Type Description
origin string

Label to disambiguate path.

elem (repeated) PathElem

Elements of the path.

PathElem

PathElem encodes an element of a gNMI path, along with any attributes (keys)
that may be associated with it.
Reference: gNMI Specification Section 2.2.2.

Field Type Description
name string

The name of the element in the path.

key (repeated) PathElem.KeyEntry

Map of key (attribute) name to value.

Field Type Description
key string

value string

Name Number Description
UNSPECIFIED 0

SHA256 1

SHA512 2

MD5 3

L3Protocol

Generic Layer 3 Protocol enumeration.

Name Number Description
UNSPECIFIED 0

IPV4 1

IPV6 2

.google.protobuf.FileOptions.gnoi_version

The gNOI service semantic version.

Extension Type Base Number Description
gnoi_version string .google.protobuf.FileOptions 1002

The gNOI service semantic version.

Proto Type Notes C++ Java Python Go C# PHP Ruby
double double double float float64 double float Float
float float float float float32 float float Float
int32 Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead. int32 int int int32 int integer Bignum or Fixnum (as required)
int64 Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead. int64 long int/long int64 long integer/string Bignum
uint32 Uses variable-length encoding. uint32 int int/long uint32 uint integer Bignum or Fixnum (as required)
uint64 Uses variable-length encoding. uint64 long int/long uint64 ulong integer/string Bignum or Fixnum (as required)
sint32 Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. int32 int int int32 int integer Bignum or Fixnum (as required)
sint64 Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. int64 long int/long int64 long integer/string Bignum
fixed32 Always four bytes. More efficient than uint32 if values are often greater than 2^28. uint32 int int uint32 uint integer Bignum or Fixnum (as required)
fixed64 Always eight bytes. More efficient than uint64 if values are often greater than 2^56. uint64 long int/long uint64 ulong integer/string Bignum
sfixed32 Always four bytes. int32 int int int32 int integer Bignum or Fixnum (as required)
sfixed64 Always eight bytes. int64 long int/long int64 long integer/string Bignum
bool bool boolean boolean bool bool boolean TrueClass/FalseClass
string A string must always contain UTF-8 encoded or 7-bit ASCII text. string String str/unicode string string string String (UTF-8)
bytes May contain any arbitrary sequence of bytes. string ByteString str []byte ByteString string String (ASCII-8BIT)

Created by Siva Sivakumar / Roman Dodin / srl-labs