From 2d0b6e380be3acec05f4acea9e4f1b9bb730ee88 Mon Sep 17 00:00:00 2001 From: Billy McFall Date: Wed, 11 Jan 2017 08:44:52 -0500 Subject: VPP-279: Document changes for vnet/vnet/devices Add doxygen documentation for netmap CLI commands. Change-Id: I8d3ce12b1cfa5af30ddcd31cb476ca4652cfc2f3 Signed-off-by: Billy McFall --- src/vnet/devices/af_packet/cli.c | 5 +++ src/vnet/devices/netmap/cli.c | 68 ++++++++++++++++++++++++++++++++++++++-- src/vnet/devices/netmap/dir.dox | 27 ++++++++++++++++ 3 files changed, 97 insertions(+), 3 deletions(-) create mode 100644 src/vnet/devices/netmap/dir.dox diff --git a/src/vnet/devices/af_packet/cli.c b/src/vnet/devices/af_packet/cli.c index 5c55cb4f10e..6baa26e1720 100644 --- a/src/vnet/devices/af_packet/cli.c +++ b/src/vnet/devices/af_packet/cli.c @@ -96,6 +96,11 @@ af_packet_create_command_fn (vlib_main_t * vm, unformat_input_t * input, * is the name of the specified veth pair. Use the * 'show interfaces' command to display host interface details. * + * This command has the following optional parameters: + * + * - hw-addr - Optional ethernet address, can be in either + * X:X:X:X:X:X unix or X.X.X cisco format. + * * @cliexpar * Example of how to create a host interface tied to one side of an * existing linux veth pair named vpp1: diff --git a/src/vnet/devices/netmap/cli.c b/src/vnet/devices/netmap/cli.c index 68695250506..6157f27c77f 100644 --- a/src/vnet/devices/netmap/cli.c +++ b/src/vnet/devices/netmap/cli.c @@ -83,11 +83,57 @@ netmap_create_command_fn (vlib_main_t * vm, unformat_input_t * input, return 0; } +/*? + * 'netmap' is a framework for very fast packet I/O from userspace. + * 'VALE' is an equally fast in-kernel software switch using the + * netmap API. 'netmap' includes 'netmap pipes', a shared + * memory packet transport channel. Together, they provide a high speed + * user-space interface that allows VPP to patch into a linux namespace, a + * linux container, or a physical NIC without the use of DPDK. Netmap/VALE + * generates the 'netmap.ko' kernel module that needs to be loaded + * before netmap interfaces can be created. + * - https://github.com/luigirizzo/netmap - Netmap/VALE repo. + * - https://github.com/vpp-dev/netmap - VPP development package for Netmap/VALE, + * which is a snapshot of the Netmap/VALE repo with minor changes to work + * with containers and modified kernel drivers to work with NICs. + * + * Create a netmap interface that will attach to a linux interface. + * The interface must already exist. Once created, a new netmap interface + * will exist in VPP with the name 'netmap-', where + * '' takes one of two forms: + * - ifname - Linux interface to bind too. + * - valeXXX:YYY - + * - Where 'valeXXX' is an arbitrary name for a VALE + * interface that must start with 'vale' and is less + * than 16 characters. + * - Where 'YYY' is an existing linux namespace. + * + * This command has the following optional parameters: + * + * - hw-addr - Optional ethernet address, can be in either + * X:X:X:X:X:X unix or X.X.X cisco format. + * + * - pipe - Optional flag to indicate that a 'netmap pipe' + * instance should be created. + * + * - master | slave - Optional flag to indicate whether VPP should + * be the master or slave of the 'netmap pipe'. Only considered + * if 'pipe' is entered. Defaults to 'slave' if not entered. + * + * @cliexpar + * Example of how to create a netmap interface tied to the linux + * namespace 'vpp1': + * @cliexstart{create netmap name vale00:vpp1 hw-addr 02:FE:3F:34:15:9B pipe master} + * netmap-vale00:vpp1 + * @cliexend + * Once the netmap interface is created, enable the interface using: + * @cliexcmd{set interface state netmap-vale00:vpp1 up} +?*/ /* *INDENT-OFF* */ VLIB_CLI_COMMAND (netmap_create_command, static) = { .path = "create netmap", - .short_help = "create netmap name [|valeXXX:YYY] " - "[hw-addr ] [pipe] [master|slave]", + .short_help = "create netmap name |valeXXX:YYY " + "[hw-addr ] [pipe] [master|slave]", .function = netmap_create_command_fn, }; /* *INDENT-ON* */ @@ -121,10 +167,26 @@ netmap_delete_command_fn (vlib_main_t * vm, unformat_input_t * input, return 0; } +/*? + * Delete a netmap interface. Use the '' to identify + * the netmap interface to be deleted. In VPP, netmap interfaces are + * named as 'netmap-', where '' + * takes one of two forms: + * - ifname - Linux interface to bind too. + * - valeXXX:YYY - + * - Where 'valeXXX' is an arbitrary name for a VALE + * interface that must start with 'vale' and is less + * than 16 characters. + * - Where 'YYY' is an existing linux namespace. + * + * @cliexpar + * Example of how to delete a netmap interface named 'netmap-vale00:vpp1': + * @cliexcmd{delete netmap name vale00:vpp1} +?*/ /* *INDENT-OFF* */ VLIB_CLI_COMMAND (netmap_delete_command, static) = { .path = "delete netmap", - .short_help = "delete netmap name ", + .short_help = "delete netmap name |valeXXX:YYY", .function = netmap_delete_command_fn, }; /* *INDENT-ON* */ diff --git a/src/vnet/devices/netmap/dir.dox b/src/vnet/devices/netmap/dir.dox new file mode 100644 index 00000000000..7ddbf947c29 --- /dev/null +++ b/src/vnet/devices/netmap/dir.dox @@ -0,0 +1,27 @@ +/* + * Copyright (c) 2017 Cisco and/or its affiliates. + * + * 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. + */ + +/* Doxygen directory documentation */ + +/** +@dir +@brief netmap Interface Implementation. + +This directory contains the source code for the netmap driver. + +*/ +/*? %%clicmd:group_label netmap %% ?*/ +/*? %%syscfg:group_label netmap %% ?*/ -- cgit 1.2.3-korg