[ONOS-7003] Policer implementation
Changes:
- Introduce trafficcontrol package
- Add policer
- Add policer id
- Add policing resource
- Add token bucket
- Add unit tests
Change-Id: I70065d58d3df7033e67a81943ebf60187c33c3e2
diff --git a/core/api/src/main/java/org/onosproject/net/behaviour/trafficcontrol/Policer.java b/core/api/src/main/java/org/onosproject/net/behaviour/trafficcontrol/Policer.java
new file mode 100644
index 0000000..af17050
--- /dev/null
+++ b/core/api/src/main/java/org/onosproject/net/behaviour/trafficcontrol/Policer.java
@@ -0,0 +1,262 @@
+/*
+ * Copyright 2017-present Open Networking Foundation
+ *
+ * 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.net.behaviour.trafficcontrol;
+
+import com.google.common.annotations.Beta;
+import org.onosproject.core.ApplicationId;
+import org.onosproject.net.DeviceId;
+
+import java.util.Collection;
+
+/**
+ * Generic abstraction for a policer which can mark and/or discard ingress
+ * traffic. Each policer is made up of an identifier and a set of attributes
+ * which defines the type of policer.
+ * <p>
+ * For example a policer specifying only a single token bucket, it will model
+ * a simple drop policer or a marker policer. For the former, the traffic in
+ * profile is green or red if it is out-of-profile. The latter envisages green
+ * or yellow traffic. Currently there is no RFC for this kind of policer but
+ * some vendors implement this model.
+ * <p>
+ * RFC 2697 can be modelled creating a policer with a collection of two
+ * token buckets: [0] CIR + CBS; [1] CIR + EBS. In this way, it is possible
+ * to create a policer single rate three color marker.
+ * <p>
+ * RFC 2698 and P4 meter are modelled in the same way but different attributes
+ * for the token buckets: [0] PIR + PBS; [2] CIR + CBS. In this way, we can
+ * create a policer two rate three color marker.
+ * <p>
+ * How these policers will be implemented depends on the specific technology
+ * used in the device. For an OF device, the single rate two color marker it
+ * could be implemented with a simple meter with a drop band.
+ * <p>
+ * Following abstraction has been designed to cover several types of policing
+ * that have been specified during the years. However, this does not assure that
+ * used technology will support all possible scenarios. For example, OF limitations
+ * are well known in this field and implementations are even worse.
+ */
+@Beta
+public interface Policer {
+
+ /**
+ * Unit of traffic used by this policer.
+ */
+ enum Unit {
+ /**
+ * Packets per second.
+ */
+ PKTS_PER_SEC,
+ /**
+ * Byte per second.
+ */
+ B_PER_SEC,
+ /**
+ * KByte per second.
+ */
+ KB_PER_SEC,
+ /**
+ * MByte per second.
+ */
+ MB_PER_SEC
+ }
+
+ /**
+ * The device of this policer, where policing
+ * is applied.
+ *
+ * @return the device id
+ */
+ DeviceId deviceId();
+
+ /**
+ * The id of the application which created this policer.
+ *
+ * @return the identifier of the application
+ */
+ ApplicationId applicationId();
+
+ /**
+ * Returns how many are referencing this policer.
+ *
+ * Availability of this information depends on the
+ * technology used for the implementation of this policer.
+ *
+ * @return the reference count
+ */
+ long referenceCount();
+
+ /**
+ * Stats which reports how many packets have been
+ * processed so far.
+ *
+ * Availability of this information depends on the
+ * technology used for the implementation of this policer.
+ *
+ * @return the processed packets
+ */
+ long processedPackets();
+
+ /**
+ * Stats which reports how many bytes have been
+ * processed so far.
+ *
+ * Availability of this information depends on the
+ * technology used for the implementation of this policer.
+ *
+ * @return the processed bytes
+ */
+ long processedBytes();
+
+ /**
+ * The id of this policer.
+ *
+ * @return the policer id
+ */
+ PolicerId policerId();
+
+ /**
+ * Indicates if this policer is aware of the marking indication
+ * in the ethernet frames.
+ *
+ * TODO Understand for the future how it is implemented by the vendors
+ *
+ * @return true if this policer is color aware.
+ */
+ boolean isColorAware();
+
+ /**
+ * The lifetime in seconds of this policer.
+ *
+ * Availability of this information depends on the
+ * technology used for the implementation of this policer.
+ *
+ * @return number of seconds
+ */
+ long life();
+
+ /**
+ * The unit used within this policer.
+ *
+ * @return the unit
+ */
+ Unit unit();
+
+ /**
+ * The token buckets used within this policer.
+ *
+ * @return the list of the token buckets
+ */
+ Collection<TokenBucket> tokenBuckets();
+
+ /**
+ * Brief description of this policer.
+ *
+ * @return human readable description
+ */
+ String description();
+
+ /**
+ * A policer builder.
+ */
+ interface Builder {
+
+ /**
+ * Assigns the device for this policer.
+ * <p>
+ * Note: mandatory setter for this builder
+ * </p>
+ * @param deviceId a device id
+ * @return this
+ */
+ Builder forDeviceId(DeviceId deviceId);
+
+ /**
+ * Assigns the application that built this policer.
+ * <p>
+ * Note: mandatory setter for this builder
+ * </p>
+ * @param appId an application id
+ * @return this
+ */
+ Builder fromApp(ApplicationId appId);
+
+ /**
+ * Assigns the id to this policer.
+ * <p>
+ * Note: mandatory setter for this builder
+ * </p>
+ * @param id an identifier
+ * @return this
+ */
+ Builder withId(PolicerId id);
+
+ /**
+ * Sets this policer to be color aware.
+ * Defaults to false.
+ *
+ * @param isColorAware if it is color aware or not
+ * @return this
+ */
+ Builder colorAware(boolean isColorAware);
+
+ /**
+ * Assigns the unit to use for this policer.
+ * Defaults to MB/s.
+ *
+ * @param unit a unit
+ * @return this
+ */
+ Builder withUnit(Unit unit);
+
+ /**
+ * Assigns policer id and device id for this policer.
+ *
+ * @param policingResource the policing resource
+ * @return this
+ */
+ Builder withPolicingResource(PolicingResource policingResource);
+
+ /**
+ * Assigns token buckets for this policer.
+ * <p>
+ * Note: at least one token bucket
+ * </p>
+ * @param tokenBuckets the collection of token buckets
+ * @return this
+ */
+ Builder withTokenBuckets(Collection<TokenBucket> tokenBuckets);
+
+ /**
+ * Assigns description for this policer.
+ * Default is empty description.
+ *
+ * @param description the description
+ * @return this
+ */
+ Builder withDescription(String description);
+
+ /**
+ * Builds the policer based on the specified parameters
+ * when possible.
+ *
+ * @return a policer
+ */
+ Policer build();
+ }
+
+}