ONOS-6559 P4Runtime protocol library
Change-Id: I7070b69507dcf2ca47ee1c446bcc2505ca868fb1
diff --git a/protocols/p4runtime/api/src/main/java/org/onosproject/p4runtime/api/P4RuntimeClient.java b/protocols/p4runtime/api/src/main/java/org/onosproject/p4runtime/api/P4RuntimeClient.java
new file mode 100644
index 0000000..ee622cb
--- /dev/null
+++ b/protocols/p4runtime/api/src/main/java/org/onosproject/p4runtime/api/P4RuntimeClient.java
@@ -0,0 +1,83 @@
+/*
+ * Copyright 2017-present Open Networking Laboratory
+ *
+ * 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.
+ */
+
+package org.onosproject.p4runtime.api;
+
+import com.google.common.annotations.Beta;
+import org.onosproject.net.pi.runtime.PiTableEntry;
+import org.onosproject.net.pi.runtime.PiTableId;
+
+import java.io.InputStream;
+import java.util.Collection;
+import java.util.concurrent.CompletableFuture;
+
+/**
+ * Client to control a P4Runtime device.
+ */
+@Beta
+public interface P4RuntimeClient {
+
+ /**
+ * Type of write operation.
+ */
+ enum WriteOperationType {
+ UNSPECIFIED,
+ INSERT,
+ UPDATE,
+ DELETE
+ }
+
+ /**
+ * Sets the pipeline configuration. This method should be called before any other method of this client.
+ *
+ * @param p4Info input stream of a P4Info message in text format
+ * @param targetConfig input stream of the target-specific configuration (e.g. BMv2 JSON)
+ * @return a completable future of a boolean, true if the operations was successful, false otherwise.
+ */
+ CompletableFuture<Boolean> setPipelineConfig(InputStream p4Info, InputStream targetConfig);
+
+ /**
+ * Initializes the stream channel, after which all messages received from the device will be notified using the
+ * {@link P4RuntimeController} event listener.
+ *
+ * @return a completable future of a boolean, true if the operations was successful, false otherwise.
+ */
+ CompletableFuture<Boolean> initStreamChannel();
+
+ /**
+ * Performs the given write operation for the given table entries.
+ *
+ * @param entries table entries
+ * @param opType operation type.
+ * @return true if the operation was successful, false otherwise.
+ */
+ boolean writeTableEntries(Collection<PiTableEntry> entries, WriteOperationType opType);
+
+ /**
+ * Dumps all entries currently installed in the given table.
+ *
+ * @param tableId table identifier
+ * @return completable future of a collection of table entries
+ */
+ CompletableFuture<Collection<PiTableEntry>> dumpTable(PiTableId tableId);
+
+ /**
+ * Shutdown the client by terminating any active RPC such as the stream channel.
+ */
+ void shutdown();
+
+ // TODO: work in progress.
+}
diff --git a/protocols/p4runtime/api/src/main/java/org/onosproject/p4runtime/api/P4RuntimeController.java b/protocols/p4runtime/api/src/main/java/org/onosproject/p4runtime/api/P4RuntimeController.java
new file mode 100644
index 0000000..3b8074f
--- /dev/null
+++ b/protocols/p4runtime/api/src/main/java/org/onosproject/p4runtime/api/P4RuntimeController.java
@@ -0,0 +1,68 @@
+/*
+ * Copyright 2017-present Open Networking Laboratory
+ *
+ * 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.
+ */
+
+package org.onosproject.p4runtime.api;
+
+import com.google.common.annotations.Beta;
+import io.grpc.ManagedChannelBuilder;
+import org.onosproject.event.ListenerService;
+import org.onosproject.net.DeviceId;
+
+/**
+ * Controller of P4Runtime devices.
+ */
+@Beta
+public interface P4RuntimeController extends ListenerService<P4RuntimeEvent, P4RuntimeEventListener> {
+
+ /**
+ * Instantiates a new client to operate on the device identified by the given information and reachable using the
+ * given gRPC channel builder. As a result of this method, a {@link P4RuntimeClient} can be later obtained by
+ * invoking {@link #getClient(DeviceId)}. Only one client can exist for the same device identifier. Returns true if
+ * the client was created and the channel to the device is open, false otherwise.
+ *
+ * @param deviceId device identifier
+ * @param p4DeviceId P4Runtime-specific device identifier
+ * @param channelBuilder gRPC channel builder pointing at the P4Runtime server in execution on the device
+ * @return true if the client was created and the channel to the device is open
+ * @throws IllegalStateException if a client already exists for the given device identifier
+ */
+ boolean createClient(DeviceId deviceId, int p4DeviceId, ManagedChannelBuilder channelBuilder);
+
+ /**
+ * Returns a client to operate on the given device.
+ *
+ * @param deviceId device identifier
+ * @return client instance
+ * @throws IllegalStateException if no client exists for the given device identifier
+ */
+ P4RuntimeClient getClient(DeviceId deviceId);
+
+ /**
+ * Removes the client for the given device. If no client exists for the given device identifier, the
+ * result is a no-op.
+ *
+ * @param deviceId device identifier
+ */
+ void removeClient(DeviceId deviceId);
+
+ /**
+ * Returns true if a client exists for the given device identifier, false otherwise.
+ *
+ * @param deviceId device identifier
+ * @return true if client exists, false otherwise.
+ */
+ boolean hasClient(DeviceId deviceId);
+}
diff --git a/protocols/p4runtime/api/src/main/java/org/onosproject/p4runtime/api/P4RuntimeEvent.java b/protocols/p4runtime/api/src/main/java/org/onosproject/p4runtime/api/P4RuntimeEvent.java
new file mode 100644
index 0000000..9ba3d58
--- /dev/null
+++ b/protocols/p4runtime/api/src/main/java/org/onosproject/p4runtime/api/P4RuntimeEvent.java
@@ -0,0 +1,28 @@
+/*
+ * Copyright 2017-present Open Networking Laboratory
+ *
+ * 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.
+ */
+
+package org.onosproject.p4runtime.api;
+
+import com.google.common.annotations.Beta;
+import org.onosproject.event.Event;
+
+/**
+ * Representation of an event received from a P4Runtime device.
+ */
+@Beta
+public interface P4RuntimeEvent extends Event<P4RuntimeEventListener.Type, P4RuntimeEventSubject> {
+
+}
diff --git a/protocols/p4runtime/api/src/main/java/org/onosproject/p4runtime/api/P4RuntimeEventListener.java b/protocols/p4runtime/api/src/main/java/org/onosproject/p4runtime/api/P4RuntimeEventListener.java
new file mode 100644
index 0000000..0a63355
--- /dev/null
+++ b/protocols/p4runtime/api/src/main/java/org/onosproject/p4runtime/api/P4RuntimeEventListener.java
@@ -0,0 +1,38 @@
+/*
+ * Copyright 2017-present Open Networking Laboratory
+ *
+ * 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.
+ */
+
+package org.onosproject.p4runtime.api;
+
+import com.google.common.annotations.Beta;
+import org.onosproject.event.EventListener;
+
+/**
+ * A listener of events received from P4Runtime devices.
+ */
+@Beta
+public interface P4RuntimeEventListener extends EventListener<P4RuntimeEvent> {
+
+ /**
+ * Type of event.
+ */
+ enum Type {
+ /**
+ * A packet-in.
+ */
+ PACKET_IN,
+ // TODO: add mastership, device as soon as we define those.
+ }
+}
diff --git a/protocols/p4runtime/api/src/main/java/org/onosproject/p4runtime/api/P4RuntimeEventSubject.java b/protocols/p4runtime/api/src/main/java/org/onosproject/p4runtime/api/P4RuntimeEventSubject.java
new file mode 100644
index 0000000..23b6540
--- /dev/null
+++ b/protocols/p4runtime/api/src/main/java/org/onosproject/p4runtime/api/P4RuntimeEventSubject.java
@@ -0,0 +1,27 @@
+/*
+ * Copyright 2017-present Open Networking Laboratory
+ *
+ * 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.
+ */
+
+package org.onosproject.p4runtime.api;
+
+import com.google.common.annotations.Beta;
+
+/**
+ * Information about an event generated by a P4Runtime device .
+ */
+@Beta
+public interface P4RuntimeEventSubject {
+
+}
diff --git a/protocols/p4runtime/api/src/main/java/org/onosproject/p4runtime/api/P4RuntimePacketIn.java b/protocols/p4runtime/api/src/main/java/org/onosproject/p4runtime/api/P4RuntimePacketIn.java
new file mode 100644
index 0000000..338b19a
--- /dev/null
+++ b/protocols/p4runtime/api/src/main/java/org/onosproject/p4runtime/api/P4RuntimePacketIn.java
@@ -0,0 +1,52 @@
+/*
+ * Copyright 2017-present Open Networking Laboratory
+ *
+ * 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.
+ */
+
+package org.onosproject.p4runtime.api;
+
+import com.google.common.annotations.Beta;
+import org.onlab.util.ImmutableByteSequence;
+import org.onosproject.net.DeviceId;
+
+import java.util.List;
+
+/**
+ * Information about a packet-in received from a P4Runtime device.
+ */
+@Beta
+public interface P4RuntimePacketIn extends P4RuntimeEventSubject {
+
+ /**
+ * Returns the identifier of the device that generated this packet-in.
+ *
+ * @return device identifier
+ */
+ DeviceId deviceId();
+
+ /**
+ * Returns the packet raw data.
+ *
+ * @return byte sequence
+ */
+ ImmutableByteSequence data();
+
+ /**
+ * Returns the list of metadata associated with this packet-in, to be parsed by a
+ * {@link org.onosproject.net.pi.model.PiPipelineInterpreter}.
+ *
+ * @return list of byte sequences
+ */
+ List<ImmutableByteSequence> metadata();
+}
diff --git a/protocols/p4runtime/api/src/main/java/org/onosproject/p4runtime/api/package-info.java b/protocols/p4runtime/api/src/main/java/org/onosproject/p4runtime/api/package-info.java
new file mode 100644
index 0000000..c5d10ca
--- /dev/null
+++ b/protocols/p4runtime/api/src/main/java/org/onosproject/p4runtime/api/package-info.java
@@ -0,0 +1,20 @@
+/*
+ * Copyright 2017-present Open Networking Laboratory
+ *
+ * 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.
+ */
+
+/**
+ * P4Runtime protocol API.
+ */
+package org.onosproject.p4runtime.api;
\ No newline at end of file