看看有趣的P4 BMv2 Ⅱ：runtime_CLI.md

说明：翻译自runtime_CLI，学习自用

此处的大多数命令对于runtime_CLI和simple_switch_CLI是通用的，但只有少数几个仅存在于simple_switch_CLI中。这些标记为[仅simple_switch_CLI]。

TODO: act_prof_add_member_to_group
TODO: act_prof_create_group
TODO: act_prof_create_member
TODO: act_prof_delete_group
TODO: act_prof_delete_member
TODO: act_prof_dump
TODO: act_prof_dump_group
TODO: act_prof_dump_member
TODO: act_prof_modify_member
TODO: act_prof_remove_member_from_group
TODO: counter_read
TODO: counter_reset
TODO: counter_write
TODO: get_time_elapsed [simple_switch_CLI only]
TODO: get_time_since_epoch [simple_switch_CLI only]
TODO: help
TODO: load_new_config_file

mc_dump，mc_mgrp_create，mc_mgrp_destroy，mc_node_associate，mc_node_create，mc_node_destroy，mc_node_dissociate

在v1model架构中完成ingress processing后，ingress P4代码可以将值分配给standard_metadata中的几个字段，这些字段控制数据包是丢弃、通过单播发送到一个输出端口还是将多播复制到0或多个输出列表端口。有关simple_switch如何在这些替代方案之间进行决策的详细信息，请参见此处。

数据包缓冲区包含一个PRE（Packet Replication "Engine" （数据包复制“引擎”））。

所述v1model.p4的standard_metadata字段mcast_grp在范围[1, 65535]指定65535个多播组ID值中的一个。mcast_grp等于0表示不组播复制数据包。simple_switch可以使用更大范围的多播组ID。此处给出的范围受p4c的v1model.p4包含文件中类型为bit<16>的standard_metadata字段mcast_grp的定义所限制。

对于应该多播复制的数据包，PRE会在表中查找该数据包的mcast_grp值，然后获取要进行复制的(egress_port, egress_rid)的0对或多对列表。每个副本随后将使用初始化为该对值的那两个standard_metadata字段独立地开始进行出口处理。

注意：上述多播表不是您在P4程序中定义的P4表。这里的“table”是指该词更一般的意义。它与P4表相似，因为该mcast_grp字段是唯一的搜索关键字字段，并且始终是完全匹配的。区别在于：

• 您没有在程序中声明该表。无论您加载到哪个P4程序中，以及是否使用它，它都存在于simple_switch中。
• 与P4表相比，控制平面软件使用不同的API调用来读取和写入多播组表。
• 查找的结果是一对可变长度列表，而P4语言没有直接的方法来表示运行时可变长度值的列表。

实际上，管理多播复制列表涉及两个“level”的对象：

• 每个多播组都是一组多播nodes。
• 您创建的每个多播节点都有一个egress_rid值和一组egress_port值，这些值可能不包含任何重复项。

假设您要配置simple_switch，以便将要组播的mcast_grp值为1113的数据包复制到此(egress_port, egress_rid)对列表中：

• (egress_port = 0, egress_rid = 5)
• (egress_port = 7, egress_rid = 10)
• (egress_port = 3, egress_rid = 5)

由于第一个副本和最后一个副本都具有相同的egress_rid值5，因此它们可以位于同一个多播节点中，这就是我们在此示例中所做的。使用以下mc_node_create命令创建一个多播节点：

RuntimeCmd: help mc_node_create
Create multicast node: mc_node_create <rid> <space-separated port list> [ | <space-separated lag list> ]

RuntimeCmd: mc_node_create 5 0 3
Creating node with rid 5 , port map 1001 and lag map
node was created with handle 0

注意输出中的handle 0。每次创建多播节点时，运行时simple_switch都会选择一个整数ID或句柄来“命名”它，并且在下面的其他命令中引用该节点时，必须使用该节点句柄。通常在创建新节点时从0开始分配值，但是最好不要使用此细节。

为要创建的副本创建另一个多播节点，其egress_rid为10，在此示例中该节点仅为端口7：

RuntimeCmd: mc_node_create 10 7
Creating node with rid 10 , port map 10000000 and lag map
node was created with handle 1

输出显示此节点的节点handle分配为1。

使用以下mc_mgrp_create命令为组ID为1113创建多播组：

RuntimeCmd: help mc_mgrp_create
Create multicast group: mc_mgrp_create <group id>

RuntimeCmd: mc_mgrp_create 1113
Creating multicast group 1113

没有多播组的handle ID。Groups始终由您选择的多播组ID命名，在本示例中为1113。

我们可以使用mc_dump命令查看所有创建的组：

RuntimeCmd: mc_dump
==========
MC ENTRIES
**********
mgrp(1113)
==========
LAGS
==========

我们看到ID为1113的组存在，但是没有与之关联的多播节点。以下后面的示例显示了当多播组确实具有与之关联的节点时的输出结果。在simple_switch的当前配置中，发送要使用mcast_grp为1113复制的数据包将导致该数据包被复制0次，这实际上与丢弃它相同。

要将多播节点添加到多播组，请使用以下mc_node_associate命令：

RuntimeCmd: help mc_node_associate
Associate node to multicast group: mc_node_associate <group handle> <node handle>

RuntimeCmd: mc_node_associate 1113 0
Associating node 0 to multicast group 1113

RuntimeCmd: mc_dump
==========
MC ENTRIES
**********
mgrp(1113)
  -> (L1h=0, rid=5) -> (ports=[0, 3], lags=[])
==========
LAGS
==========

在这里，我们看到组1113有一个与其关联的节点。L1h是L1 handle的缩写，您可能会在simple_switch日志消息中看到它，它的含义与节点handle相同。我们看到rid值为5，其中rid是的缩写egress_rid，我们看到了端口0和3的列表。

在当前的simple_switch配置中，发送要用mcast_grp为1113复制的数据包将导致该数据包被复制2次，并(egress_port, egress_rid)在它们开始出口处理时具有以下值：

• (egress_port = 0, egress_rid = 5)
• (egress_port = 3, egress_rid = 5)

为了实现最初为自己设置的目标，现在将第二个节点添加到组1113中：

RuntimeCmd: mc_node_associate 1113 1
Associating node 1 to multicast group 1113

RuntimeCmd: mc_dump
==========
MC ENTRIES
**********
mgrp(1113)
  -> (L1h=0, rid=5) -> (ports=[0, 3], lags=[])
  -> (L1h=1, rid=10) -> (ports=[7], lags=[])
==========
LAGS
==========

在当前的simple_switch配置中，发送要使用mcast_grp为1113复制的数据包将导致该数据包被复制3次，并(egress_port, egress_rid)在开始出口处理时具有以下值：

• (egress_port = 0, egress_rid = 5)
• (egress_port = 3, egress_rid = 5)
• (egress_port = 7, egress_rid = 10)

我们可以使用以下mc_node_dissociate命令将节点从组中分离：

RuntimeCmd: help mc_node_dissociate
Dissociate node from multicast group: mc_node_associate <group handle> <node handle>

RuntimeCmd: mc_node_dissociate 1113 0
Dissociating node 0 from multicast group 1113

RuntimeCmd: mc_dump
==========
MC ENTRIES
**********
mgrp(1113)
  -> (L1h=1, rid=10) -> (ports=[7], lags=[])
==========
LAGS
==========

在当前的simple_switch配置中，发送要用mcast_grp1113 复制的数据包将导致该数据包被复制1次，这些(egress_port, egress_rid)值在它们开始进行出口处理时具有以下值：

• (egress_port = 7, egress_rid = 10)

如果然后将节点1与组1113分离，它将返回到其初始创建状态，在该状态下将导致进行0份复制。

RuntimeCmd: mc_node_dissociate 1113 1
Dissociating node 1 from multicast group 1113

RuntimeCmd: mc_dump
==========
MC ENTRIES
**********
mgrp(1113)
==========
LAGS
==========

您可以使用以下mc_mgrp_destroy命令销毁多播组：

RuntimeCmd: help mc_mgrp_destroy
Destroy multicast group: mc_mgrp_destroy <group id>

RuntimeCmd: mc_mgrp_destroy 1113
Destroying multicast group 1113

RuntimeCmd: mc_dump
==========
MC ENTRIES
==========
LAGS
==========

这些操作有一些限制：

• 要将节点关联到组，必须同时创建该组和该节点。首先创建哪个无关紧要。
• simple_switch仅允许一个节点一次与一个组关联。您可以根据需要从一个组中分离一个节点，然后将其与另一个组相关联。
• 建议如果要销毁一个组，请首先从该组中分离所有节点。
• 单个节点不能将多个副本发送到同一egress_port。如果希望复制以使用相同的egress_port创建多个副本，请使用多个节点。在这些节点上使用不同的egress_rid值可使您的出口P4代码将副本彼此区分开，以防您需要不同地处理它们。

mc_dump命令显示有关已与组关联的多播节点的详细信息。没有simple_switch_CLI命令显示有关尚未与组关联的多播节点的详细信息。

注意：simple_switch_CLI帮助文档和mc_dump的输出也提到了lag和lag lists，但是此处未进行记录。没有它们，您可以很好地使用多播复制。

TODO: mc_node_update
TODO: mc_set_lag_membership
TODO: meter_array_set_rates
TODO: meter_get_rates

meter_set_rates

下面提供了CLI的语法。

RuntimeCmd: help meter_set_rates
Configure rates for a meter: meter_set_rates <name> <index> <rate_1>:<burst_1> <rate_2>:<burst_2> ...

Meter behavior在RFC 2697和RFC 2698中指定。

用户以字节/微秒为单位输入meter速率，以字节为单位输入burst_size。如果meter类型是数据包，则以数据包/微秒为单位输入速率，并且burst_size是数据包的数量。

mirroring_add，mirroring_add_mc，mirroring_delete，mirroring_get

[仅限simple_switch_CLI]

在数据包处理期间发生以下任何事件时：

• 您的v1model体系结构P4_16程序在入口或出口处理期间调用clone或clone3外部函数，现在入口或出口处理已完成
• 您的P4_14程序clone_ingress_pkt_to_egress在入口处理期间已调用，现已完成
• 您的P4_14程序clone_egress_pkt_to_egress在出口处理期间已调用，现已完成

那么，不仅当前的“原始”数据包将继续正常运行，就像您的程序未调用克隆操作一样，而且PRE（数据包复制引擎）部分simple_switch还将创建零个或多个副本或克隆。当前数据包，并使它们排队入数据包缓冲区，以便稍后每个克隆的数据包都将执行出口处理。每个克隆都彼此独立并且独立于原始数据包进行处理。

在本文中搜索单词“clone”，以获取有关如何simple_switch处理克隆数据包的更多详细信息。

simple_switch支持32,768个独立的克隆会话，从0到32,767，也称为镜像会话。克隆数据包后，可以在克隆操作的P4程序调用中指定要使用的克隆会话。

该mirroring命令的目的是配置将克隆的数据包发送到哪个端口。为每个克隆会话数字ID独立配置此状态。

默认情况下，simple_switch启动时，每个克隆会话ID均处于未配置状态。对于处于此未配置状态的克隆会话ID进行的任何克隆操作都将创建0个克隆数据包，即，数据包处理行为与完全不调用克隆操作的情况相同。

如果使用此命令mirroring_add 5 7，则会更改克隆会话标识号5的配置，以便将来使用克隆会话5的克隆操作将创建一个发往出口7的单个克隆数据包。

RuntimeCmd: help mirroring_add
Add mirroring session to unicast port: mirroring_add <mirror_id> <egress_port>

RuntimeCmd: mirroring_add 5 7

RuntimeCmd: mirroring_get 5
MirroringSessionConfig(mgid=None, port=7)

使用该命令可以mirroring_add_mc 5 22修改克隆会话ID为5的配置，以便将来使用克隆会话5的克隆操作将创建与配置为创建多播组ID为22一样多的克隆。有关mc_mgrp_create如何配置多播组的信息，请参阅和相关的多播组配置命令。

RuntimeCmd: help mirroring_add_mc
Add mirroring session to multicast group: mirroring_add_mc <mirror_id> <mgrp>

RuntimeCmd: mirroring_add_mc 5 22

RuntimeCmd: mirroring_get 5
MirroringSessionConfig(mgid=22, port=None)

该命令mirroring_delete 5将克隆会话标识号5返回到其原始未配置状态。

RuntimeCmd: help mirroring_delete
Delete mirroring session: mirroring_delete <mirror_id>

RuntimeCmd: mirroring_delete 5

RuntimeCmd: mirroring_get 5
Invalid mirroring operation (SESSION_NOT_FOUND)

该mirroring_get命令可用于显示克隆会话的当前配置。

TODO: port_add
TODO: port_remove

pvs_add，pvs_clear，pvs_get，pvs_remove

这些命令用于控制P4解析器值集的实例。pvs_add用于将条目添加到值集，pvs_remove用于删除条目，pvs_clear用于删除所有条目以及pvs_get用于列出所有条目。

P4允许value_set以struct作为类型参数，例如以下示例：

struct vsk_t {
    bit<16> f1;
    bit<7> f2;
}
value_set<vsk_t>(4) pvs;
select (<X>) {
    pvs: accept;
    _: reject;
}

添加或删除条目时，必须提供一个整数值，该值必须适合值集的“压缩位宽”，否则CLI会显示错误。当值集的条目由多个单独的字段组成时（如上例所示），“compressed bitwidth”定义为所有这些单独字段的位宽之和，不带填充。当值集的类型参数是整数（有符号或无符号）或具有单个字段的结构时，“compressed bitwidth”就是整数/字段的位宽。

将来，CLI可能会提供更直观的界面，并使您能够为构成值集条目的不同字段提供单独的整数值。但是，此刻，您需要自己连接它们。

请注意，pvs_add如果要添加的值已经存在，则不会警告您，如果pvs_remove要删除的值在值集中不存在，也不会警告您。

该BMV2值集实现不支持比其他匹配精确的类型。

TODO: register_read
TODO: register_reset
TODO: register_write
TODO: reset_state
TODO: serialize_state
TODO: set_crc16_parameters
TODO: set_crc32_parameters
TODO: set_queue_depth [simple_switch_CLI only]
TODO: set_queue_rate [simple_switch_CLI only]
TODO: shell

show_actions

没有参数。对于当前加载的P4程序中的每个动作，显示名称和参数列表。对于每个参数，以位为单位显示名称和宽度。

show_ports

没有参数。显示端口号，与之关联的接口名称及其状态（例如，向上或向下）。

show_pvs

没有参数。对于当前加载的P4程序中设置的每个解析器值，将显示条目的名称和预期的位宽。使用pvs_add命令添加条目时，用户必须提供不大于此位宽的整数值。

show_tables

没有参数。对于当前加载的P4程序中的每个表，显示名称，实现（通常是None，但可以是使用这些选项创建的表的操作配置文件或操作选择器），以及表搜索关键字字段的列表，为每个此类字段提供名，匹配种类（例如exact，lpm，ternary，range），和宽度在比特。请注意，在BMv2 JSON文件中，P4源代码中具有match kind optional字段的字段表示为ternary。

TODO: swap_configs
TODO: switch_info

table_add

RuntimeCmd: help table_add
Add entry to a match table: table_add <table name> <action name> <match fields> => <action parameters> [priority]

您可以通过命令show_tables和show_actions找到所有表和动作名称列表。如果不使用P4程序中@name注释指定的一个默认名称，则创建的默认名称通常是分层的，从表或操作在其中定义的控件的名称开始。

匹配字段必须表达为P4程序中指定的table search key fields的顺序，不需要加field的名称。show_tables的输出还会在mk =字符串之后显示每个表的名称，匹配类型（ternary，range，lpm或exact）以及bit宽度。匹配类型为optional的字段在BMv2 JSON文件中表示为ternary，就一切匹配而言，simple_switch_CLI都有与ternary相同的方式。

数值可以用十进制或以0x为前缀的十六进制指定。

为了方便某些常用的网络地址格式，可以使用一些特殊的语法来指定数字值：

• 可以指定32位值，例如IPv4地址，以点分十进制表示，例如10.1.2.3
• 可以像IETF中的IPv6地址表示法一样指定128位值，例如：FEDC:BA98:7654:3210:FEDC:BA98:7654:3210或1080::8:800:200C:417A。详情请参阅RFC 2732。
• 可以指定48位值，例如以太网MAC地址，每个字节用两个十六进制数字表示，字节之间用:分隔，例如00:12:34:56:78:9a。

匹配类型为lpm的表搜索关键字字段应具有后跟斜杠字符/后的前缀长度值，例如0x0a010203/24。前缀长度必须始终为十进制，不支持十六进制。前缀长度可以使用0，这样的条目将匹配该搜索关键字字段的任何位置的值。

将具有匹配种类的表搜索关键字字段ternary指定为一个数字值，然后指定&&&一个数字掩码，数字和之间没有空格&&&。掩码的等于1的位位置是完全匹配的位位置，掩码等于0的位位置是通配符的位位置。也就是说表条目value&&&mask将与搜索关键字值匹配k其中(k & mask) == (value & mask)，按位逻辑&，如P4中所示。要匹配三元搜索关键字的任何值，您可以指定0&&&0。

P4源代码中具有匹配类型optional的表搜索关键字字段的指定方式与具有匹配类型ternary相同的指定方式，如上一段所述。请注意，在运行时CLI中没有检查掩码必须为0或全为1，因此即使不允许这样做，它也允许您执行任意ternary掩码。如果将匹配规范适当地限制为optional是很好的，但这种支持需要将behavior model代码进行重大更改。

具有匹配range种类的表搜索关键字字段被指定为最小值->最大值，数字和->之间没有空格。要匹配range搜索关键字的任何值，可以指定0->255的8位字段，或为32位字段指定0->0xffffffff，依此类推。

如果表的任何搜索关键字字段具有匹配类型ternary，optional或者range，则必须指定priority优先级数值。对于任何其他类型的表，指定priority数值都是错误的。如果搜索键与多个表条目匹配，那么在与搜索键相匹配的条目中，数字优先级值最小的条目将成为获胜者，这意味着将执行其操作。

动作参数的显示顺序必须与P4程序中显示的顺序相同，不加名称。show_actions命令的输出显示每个动作的所有参数的名称和宽度（以bit为单位）。

TODO: table_clear
TODO: table_delete
TODO: table_dump
TODO: table_dump_entry
TODO: table_dump_entry_from_key
TODO: table_dump_group
TODO: table_dump_member
TODO: table_indirect_add
TODO: table_indirect_add_member_to_group
TODO: table_indirect_add_with_group
TODO: table_indirect_create_group
TODO: table_indirect_create_member
TODO: table_indirect_delete
TODO: table_indirect_delete_group
TODO: table_indirect_delete_member
TODO: table_indirect_modify_member
TODO: table_indirect_remove_member_from_group
TODO: table_indirect_reset_default
TODO: table_indirect_set_default
TODO: table_indirect_set_default_with_group
TODO: table_info
TODO: table_modify
TODO: table_num_entries

table_reset_default

RuntimeCmd: help table_reset_default
Reset default entry for a match table: table_reset_default <table name>

如P4程序中所指定的，将发生未命中时将表执行的操作更改回其原始值。如果在P4程序中未指定默认动作，则为无操作动作，有时称为NoAction。

table_set_default

RuntimeCmd: help table_set_default
Set default action for a match table: table_set_default <table name> <action name> <action parameters>

将其他操作指定为命名表的默认操作，即应用表时执行的操作，但搜索键与表中安装的任何条目都不匹配。

有关table_add如何指定操作参数的信息，请参见该命令的文档。

TODO: table_set_timeout
TODO: table_show_actions
TODO: write_config_to_file