[PSA] count() operation on counters

[hanw]

For a 'bytes' or 'packets_and_bytes' counter type, count() having a
second parameter 'increment' that specifies how much to add to the
byte counter is a very good thing. It is best if the P4 program has
the flexibility to choose the length in bytes it wants to use for the
packet, e.g. in case it is increasing or decreasing the received
packet's size before transmitting it.

For counters that have type 'packets', presumably every call to
'count' will add exactly 1, yes? In that case, having a separate
method call that only takes an 'index' parameter would be best, since
the 'increment' parameter value would be ignored, anyway.

[jafingerhut]

Proposal:

• For direct counters, allow the counter_type to be 'packets' only -- do not support counter_type 'bytes', nor 'packets_and_bytes'. If you want those counter types, use a regular counter instead of a direct counter. (If someone wants to allow those counter types for direct counters, then they must define what value will be added to the 'bytes' counter when a packet searches the table.) Remove method 'count()' from the extern object definition, if there is no reason for it, e.g. if it is automatically called whenever the corresponding table is searched, and should not be called from the user's P4 program directly, then having such a method only leads to confusion for why it is there.

• For 'regular' counters (i.e. not direct counters), only support the existing 'void count(in S index, in W increment);' method if the counter_type is 'bytes' or 'packets_and_bytes'. The value 'increment' is the value added to the bytes counter updated, and 1 is always added to the packets counter. If the counter_type is 'packets', add a new method 'void count(in S index);' that always adds 1 to the counter specified by 'index'.

• Do we want to specify that hardware counters are all saturating, i.e. 'stick' at their maximum values rather than wrap around? If we want the option to have either saturating or wrapping options, it would be good to put that in the PSA spec.

[vgurevich]

I would make even a stronger statement -- we should probably start defining packet counters only.

Byte counters (or packet-and-byte) should be defined separately and they will probably be quite restricted, based on what we know about high-speed pipelines and their implementations. The reason I am saying that is because more often than not, packet length is not even available during packet processing (especially at the ingress). Also, it can change when headers are added or removed. Usually, HW uses special mechanisms to account for that that are not necessarily flexible or compatible across multiple different implementations.

[jafingerhut]

@jnfoster @vgurevich @cc10512 (others welcome to answer -- I just want to call attention to the questions below to these people, who expressed interest in this topic)

Before the PSA working group meeting on 2017-Jul-10, I had previously believed (perhaps mistakenly) that having a direct counter associated with a table meant that even if the P4 program had no explicit count() update method calls in the code, they would automatically occur whenever the table had an apply() method call performed on it.

During the meeting, someone mentioned that this was not the case. Even if you have a direct counter associated with a table, the counter state is only updated via an explicit method call in the actions for that table. If an action for that table does not call the count() method, then no state for that direct counter extern will be updated when table entries with that action associated with them are matched.

If this is true, what is the intended distinction between a direct counter, vs. a 'normal' counter? Is it that a direct counter can only be updated in the actions for the table that it is associated with, whereas for a normal counter, it can be updated in the actions of more than one distinct table?

Is that distinction considered sufficient reason to have a separate notion of a direct counter vs. normal counter? Or would only having a 'normal' counter be enough, and we can dispose with the idea of direct counter, for simplification of the PSA spec and implementations of it?

If there is an advantage to having a separate direct counter extern, someone mentioned during the meeting that the intended way to 'associate' a direct counter with a table is by assigning a value to a table attribute with a particular name. Does anyone have an example snippet of P4_16 code for a table and an associated direct counter that shows how this is intended to be done? I would like to include such an example in the PSA spec.

[ChrisDodd]

For a direct counter, the count method has no index parameter -- there's one counter associated with each action and that counter is bumped when the action calls ctr.count(). On some hardware it might be possible to do that conditionally.

For a normal counter, the count method has an index parameter that specifies which counter in the counter array gets bumped. So you call ctr.count(idx) where idx might come from packet data or might be an action parameter. Sometimes one refers to these as indirect counters.

A direct_counter extern has no size -- the number of counters is the same as the size of the table it is used in. It doesn't really make sense for such a counter to be accessed by more than one table, and I think we should disallow that.

A counter extern has a size -- the number of counters in the array (valid indexes are 0 .. size-1). Using the counter in more than one table seems well defined, though some hardware might not allow it, or might only allow it for mutually exclusive tables.

It could be argued (and has been) that direct_counter need not really exist -- you could instead have a way of accessing the implicit action index and using that as the count index.

[jafingerhut]

@ChrisDodd Thanks for the distinctions you gave. I feel like slapping my forehead due to forgetting such basic distinctions. Will include brief reminders of these facts in my proposed changes to the PSA.

Still hoping someone has a P4_16 code snippet giving proposed syntax for instantiating a direct counter, with a proposed table attribute, if one is intended to be involved.

I will assume for now that the count() method must be explicitly invoked in the P4_16 source code in order for any update to occur, i.e. some actions for a table with an associated direct counter are permitted to make no such counter update, if the P4 program writer wishes.

[hanw]

How about something along this line?

extern counter<I> {
  counter(counter_type_t type, @optional I instance_count);
  void count(@optional I index);
}

control ingress() {
    counter() cntr;
    action call_count() {
         cntr.count();
    }
    table test {
         actions = { call_count; }
         key = {...}
         implementation = cntr;
    }

[jafingerhut]

@hanw Thanks. @optional is a relatively recent addition to the p4c compiler, as far as I know. It is definitely not mentioned in the P4_16 v1.0.0 spec. Are you proposing that @optional should be supported by all P4_16 implementations that support the PSA?

[hanw]

The @optional annotation is a stop-gap until we can have named parameter in p4-16. I am not proposing @optional should be used in PSA. A better solution is to support named parameter in the language. With @optional or named parameter, we can use the same counter extern for both direct and indirect counters. Without @optional, we will need to define two separate externs, as in the current PSA draft.

What I am trying to show in the example is how to instantiate a direct counter in a table (regardless how direct counter extern is defined.)

[jafingerhut]

This PR proposes relevant changes: #348

[cc10512]

@jafingerhut AFAIK the current BMv2 implementation requires explicitly calling count in an action(). @antoninbas should confirm.

[mihaibudiu]

Optional is not the same, since it allows both calls with and without argument for the same instance.
You could consider a countBytes() method.