| /* |
| * 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(); |
| } |
| |
| } |