## Controlling the switch

The [BMv2 repository](https://github.com/p4lang/behavioral-model) implements two different versions of the *Simple Switch* that have different control plane interfaces.

| Target                                                                                                  | Control Plane         |
|:--------------------------------------------------------------------------------------------------------|:----------------------|
| [`simple_switch`](https://github.com/p4lang/behavioral-model/tree/main/targets/simple_switch)           | `Thrift`              |
| [`simple_switch_grpc`](https://github.com/p4lang/behavioral-model/tree/main/targets/simple_switch_grpc) | `P4Runtime`, `Thrift` |

The following table shows different methods to configure the *Simple Switch* that will be covered in more detail in the subsequent paragraphs. Thanks to the [recent update](./Migrate-to-the-new-version#whats-new) of *P4-Utils*, *P4Runtime* is now available with a new control plane API. Notice that the APIs (i.e. `SimpleSwitchThriftAPI` and `SimpleSwitchP4RuntimeAPI`) are provided by [*P4-Utils*](https://github.com/nsg-ethz/p4-utils), whereas the client (i.e. `simple_switch_CLI`) it is directly implemented by BMv2.

| Control Plane | Methods                                     |
|:--------------|:--------------------------------------------|
| `Thrift`      | [`SimpleSwitchThriftAPI`](#thrift-api), [`simple_switch_CLI`](#simple-switch-client)|
| `P4Runtime`   | [`SimpleSwitchP4RuntimeAPI`](#p4runtime-api)|


## *Simple Switch* Client

We can use the `simple_switch_CLI` to configure the switch and populate match-action tables.


### Running the client

To get the switch client simply run:

```bash
simple_switch_CLI --thrift-port <port>
```

The client connect to the *Thrift* server running in each switch process. `9090` is the default port number but of course if you are running several devices on your machine, you will need to provide a different port for each. One client instance can only connect to one switch device.


### Filling tables

The most used commands to modify table contents are the following.

- `table_set_default <table_name> <action_name> <action_parameters>` is used to set the default action (i.e. the action executed when no match is found) of a table.
- `table_add <table_name> <action_name> <match_fields> => <action_parameters>` is used to set the action related to a specific match in a table.

For example if we have the following table:

```
action drop(){
    // drops packet
    mark_to_drop(standard_metadata);
}

action action_name(bit<8> action_parameter){
    ...
}

table table_name {
    key = {
        standard_metadata.ingress_port: exact;
    }
    actions = {
        drop;
        action_name;
    }
}
```

```
table_set_default table_name drop
table_add table_name action_name 1 => 5
```

The first command would set the default action, and action parameters (none in this case) for table `table_name`. Thus, when using the `table_name` table if there is no match, the drop action will be called. In the second example command adds an entry that matches if the `standard_metadata.ingress_port` is equal to 1 and executes the action `action_name` with `action_parameter` set to `5`.

### Writing the client input in a file

You can also populate the table writing the commands directly in a text file and then feeding the client:

```bash
simple_switch_CLI --thrift-port <port> < command_file.txt
```

### Using *P4-Utils* configuration file

Alternatively, you can use the *P4-Utils* configuration file (i.e `p4app.json`) to set a `cli` configuration file for each switch. When creating the topology, or rebooting switches, *P4-Utils* will automatically use the file to populate and configure switches.

To set default client configuration files you need to define your switches like:

```json
    "switches": {
      "s1": {
        "cli_input": "<path_to_cli_commands_file>"
      }
    }
```

You can find all the documentation about `p4app.json` in the [**official *P4-Utils* documentation**](https://nsg-ethz.github.io/p4-utils/usage.html#json).


## *Thrift* API

You can find a wrapper of the *Simple Switch* Client as one of the features of *P4-Utils*. It is called [`SimpleSwitchThriftAPI`](https://nsg-ethz.github.io/p4-utils/p4utils.utils.sswitch_thrift_API.html#p4utils.utils.sswitch_thrift_API.SimpleSwitchThriftAPI) and basically allows the user to perform the same opertations but, instead of using text sent to the client, one can use the power of a scripting language such as Python. You can read more about this API [here](https://nsg-ethz.github.io/p4-utils/advanced_usage.html#thrift-api).

## *P4Runtime* API

The P4 language consortium has recently defined [*P4Runtime*](https://p4.org/p4-spec/p4runtime/v1.3.0/P4Runtime-Spec.html), a control plane specification for controlling the data plane elements of a device defined or described by a P4 program. This new protocol aims at being the standard for P4 devices so that even control plane programs can be target-independent.

In response to this need, in the last update of *P4-Utils* a P4Runtime API was introduced. It is called [`SimpleSwitchP4RuntimeAPI`](https://nsg-ethz.github.io/p4-utils/p4utils.utils.sswitch_p4runtime_API.html#p4utils.utils.sswitch_p4runtime_API.SimpleSwitchP4RuntimeAPI) and was designed to provide methods similar, in functioning and naming, to those of [`SimpleSwitchThriftAPI`](https://nsg-ethz.github.io/p4-utils/p4utils.utils.sswitch_thrift_API.html#p4utils.utils.sswitch_thrift_API.SimpleSwitchThriftAPI) so that migrating from one to another is easier. You can read more about this API [here](https://nsg-ethz.github.io/p4-utils/advanced_usage.html#p4runtime-api).