Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Psa Extern Development Guide #779

Open
wants to merge 5 commits into
base: main
Choose a base branch
from
Open

Psa Extern Development Guide #779

Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
47a4a78
adding docs for how to develop externs in psa switch
May 16, 2019
190d692
added helpful background knowledge
May 16, 2019
d830e52
grammar fixes
May 16, 2019
5c92bd7
added common issues
May 16, 2019
e6797b8
grammar and spelling
May 16, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
82 changes: 82 additions & 0 deletions docs/psa_switch-dev.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,82 @@
# Implementing Externs in PSA Switch
Externs in PSA Switch are different than those in Simple Switch.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this would be more accurate as "The implementation of P4 externs in PSA Switch is different..."

Simple Switch uses externs baked into the BMV2 model where as PSA Switch
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

whereas?

uses externs specific to its own architecture. To understand what this
translates to in code, look at the counter used in
[Simple Switch](https://github.com/p4lang/behavioral-model/tree/master/src/bm_sim)
and the one in
[PSA Switch](https://github.com/p4lang/behavioral-model/tree/master/targets/psa_switch/externs).
The Simple Switch counter lives inside of `src/bm_sim` where as the
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

whereas?

counter for PSA Switch lives inside of the target specific directory.
This doc is meant to provide guidance for developers on how to develop
new externs in PSA Switch.

## Background Knowledge
For those who are familiar with the internals of BMV2 feel free
to skip this section. For those who are new/less familiar with how BMV2
operates, consider reading `P4Objects.cpp` as a starting point
as this is where externs will be created. From here you can also see
what the expected JSON for externs should be. Next, read the changes
in the following [commit](https://github.com/p4lang/behavioral-model/pull/767).
It details all the changes made to support the counter extern in PSA.
It will also be useful to understand on a high level how P4 Runtime
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

s/P4 Runtime/P4Runtime

interacts with PSA Switch. Briefly skimming `runtime_CLI.py` will do.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That is incorrect, runtime_CLI.py does not use P4Runtime. runtime_CLI.py uses the Thrift RPC service defined in https://github.com/p4lang/behavioral-model/blob/master/thrift_src/standard.thrift. P4Runtime is a gRPC service. It is implemented over the PI C library (https://github.com/p4lang/PI) which is then itself implemented (for bmv2) in this repository (https://github.com/p4lang/behavioral-model/tree/master/PI).
Both implementations converge at bm::RuntimeInterface (https://github.com/p4lang/behavioral-model/blob/master/include/bm/bm_sim/runtime_interface.h).

runtime_CLI --- Thrift service ---> Thrift service implementation --- RuntimeInterface ---> bmv2 built-in objects + target-specific objects

[any P4Runtime client] --- P4Runtime service ---> P4Runtime implementation (DeviceMgr) --- PI API ---> PI bmv2 implementation ---> RuntimeInterface ---> bmv2 built-in objects + target-specific objects

"Target-specific objects" include your PSA extern implementations (you added an override implementation of read_counters and write_counters to PSASwitch).


## High-Level Process
The following process is meant to serve as a general guide on how
to develop new externs in PSA Switch.

1. Provide support for emitting the extern in p4c. Currently, only
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Something that is worth mentioning because it explains the design we came up with: IIRC p4c is still generating "built-in" objects as part of the JSON (they are unused by PSASwitch) in order to make sure that runtime tools which consume the bmv2 JSON (such as the runtime_CLI) still work. This is temporary until such tools can be updated. Please correct me if I'm wrong.

counters declared in P4 are translated to JSON in the p4c for PSA
Switch.
This [commit](https://github.com/p4lang/p4c/commit/6d97bcf42f034ca113fa7a654fa998a7e10cba17)
is an example for how to emit an extern object to JSON, and
this [commit](https://github.com/p4lang/p4c/commit/bd6f231f7e6f24164f5d5156e0fad7a0680f2fa2)
is an example for how to emit extern methods to JSON.
If the examples aren't clear, one can always refer back to the JSON
spec defined
[here](https://github.com/p4lang/behavioral-model/blob/master/docs/JSON_format.md).
As for internals of how to the compiler works, check out its docs
[here](https://github.com/p4lang/p4c/tree/master/docs).
2. Create the extern type in PSA Switch. There are several important
things to note.
1. The extern type must sub-class `bm::ExternType`.
2. The extern should live within the `bm::psa` namespace.
3. You must register the newly created extern type to the
extern factory used by BMV2 to create externs from JSON
using `BM_REGISTER_EXTERN_W_NAME`.
4. You must also register any extern methods used by P4 using
`BM_REGISTER_EXTERN_W_NAME_METHOD`.
5. Create an `import_yourExternNameHere` dummy method and call
it within `psa_switch.cpp`.
3. Provide P4 Runtime support if necessary. This means overriding
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Same as above. "P4 Runtime" is misleading. If you mean "P4Runtime", then it is incorrect. If you mean "P4 runtime", then it is better, but maybe could use some clarification.

parts of the PSA Switch/P4 Runtime interface as necessary so
that P4 Runtime can configure/monitor the newly developed extern.


Refer to [this](https://github.com/p4lang/behavioral-model/pull/767)
as a complete example.

## Common Issues
Here is a list of all the bugs encountered during the development of
counters and might serve as a helpful resource for others.
* The extern can't be created.
* Most likely a mis-match between the supplied and expected JSON format.
* Did you remember to register the extern into the extern factory?
* The extern method is not being called inside of an action.
* Did you remember to register the extern method? These must be done
by the programmer.
* P4 Runtime can't interact with my extern.
* Did you remember to override necessary methods in the P4 Runtime
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

bm::RuntimeInterface would be less misleading

interface?
* I created a new extern, added it to the Makefile, but it isn't
being linked.
* Dont forget step 2.5 from above.
* Everything in BMV2 looks good, but it seems that P4c is
failing.
* Supporting additional externs might have allowed previous tests
marked as XFAIL to pass which will cause P4c to fail. Double
check the test cases that have failed and see if this was the
issue.