From d77d13f6d72d67de42b679486ae34502f3136b9a Mon Sep 17 00:00:00 2001 From: Anand B Jyoti Date: Tue, 17 Oct 2017 10:01:49 +0530 Subject: Docs: Developer guide review and update Review and update teh Developer guide for E-Release. Change-Id: I5bb2626cb3f69953b741cd46ea584423756786f2 Signed-off-by: Anand B Jyoti --- docs/testing/developer/design/01-Overview.rst | 42 ++- .../developer/design/02-Get_started_Guide.rst | 128 ++++++--- .../developer/design/04-SampleVNF_Design.rst | 309 +++++++++++---------- .../developer/requirements/03-Requirements.rst | 20 +- 4 files changed, 290 insertions(+), 209 deletions(-) diff --git a/docs/testing/developer/design/01-Overview.rst b/docs/testing/developer/design/01-Overview.rst index a1ae66af..5cd22bb1 100644 --- a/docs/testing/developer/design/01-Overview.rst +++ b/docs/testing/developer/design/01-Overview.rst @@ -14,7 +14,8 @@ Introduction .. _SampleVNF: https://wiki.opnfv.org/samplevnf .. _Technical_Briefs: https://wiki.opnfv.org/display/SAM/Technical+Briefs+of+VNFs -Overview: + +Overview --------- This project provides a placeholder for various sample VNF (Virtual Network Function) @@ -23,10 +24,17 @@ related to VNF/Network service for high performance VNFs. This project provides benefits to other OPNFV projects like Functest, Models, yardstick etc to perform real life use-case based testing and NFVi characterization for the same. -The sample VNFs are Open Source approximations* of Telco grade VNF’s using optimized -VNF + NFVi Infrastructure libraries, with Performance Characterization of Sample† Traffic Flows. - * * Not a commercial product. Encourage the community to contribute and close the feature gaps. - * † No Vendor/Proprietary Workloads +The sample VNFs are Open Source approximations* of Telco grade VNF’s using +optimized VNF + NFVi Infrastructure libraries, with Performance Characterization +of Sample† Traffic Flows. + +The purpose is to encourage the community to contribute and close the feature gaps. + + :: + + * Not a commercial product. + † No Vendor/Proprietary Workloads + It helps to facilitate deterministic & repeatable bench-marking on Industry standard high volume Servers. It augments well with a Test Infrastructure @@ -35,15 +43,25 @@ the sample VNFs through OPEN SOURCE VNF approximations and test tools. The VNFs belongs to this project are never meant for field deployment. All the VNF source code part of this project requires Apache License Version 2.0. -Scope: +Scope ----- -The Scope of samplevnf project as follows" -To create a repository of sample VNFs to help VNF benchmarking and NFVi -characterization with real world traffic. -Host a common development environment for developing the VNF using optimized libraries -Integrate into CI tool chain and existing test frameworks for VNF feature and deployment testing +The Scope of samplevnf project is to create a repository of sample VNFs +to help VNF benchmarking and NFVi characterization with real world traffic. + +Also to host a common development environment for developing the VNF using +optimized libraries and integrate into CI tool chain and existing test +frameworks for VNF feature and deployment testing. + +About DPDK +---------- +The DPDK IP Pipeline Framework provides set of libraries to build a pipeline +application. + +This document assumes the reader possess the knowledge of DPDK concepts and IP +Pipeline Framework. For more details, read DPDK Getting Started Guide, DPDK +Programmers Guide, DPDK Sample Applications Guide. -Testability: +Testability ----------- Network Service Testing framework added into the Yardstick will be used as a test tool for Functional/Performance verification of all the sample VNFs. diff --git a/docs/testing/developer/design/02-Get_started_Guide.rst b/docs/testing/developer/design/02-Get_started_Guide.rst index 995a2270..c8f35ed3 100644 --- a/docs/testing/developer/design/02-Get_started_Guide.rst +++ b/docs/testing/developer/design/02-Get_started_Guide.rst @@ -14,62 +14,79 @@ Get started as a SampleVNF developer .. _Technical_Briefs: https://wiki.opnfv.org/display/SAM/Technical+Briefs+of+VNFs Prerequisite knowledge ------------------------ -Development/Contribution to SampleVNF requires knowledge of networking technologies including -knowledge of network protocols and hands-on experience with relevant open-source -software, such as Linux*, SDN, NFVI and the DPDK (if VNF is based on DPDK libraries). -Developer needs debugging and benchmarking skils, as well as understanding of NFVi -infrastructure across multiple domains. +====================== + +Development/Contribution to SampleVNF requires knowledge of networking +technologies including knowledge of network protocols and hands-on experience +with relevant open-source software, such as Linux*, SDN, NFVI and the DPDK (if +VNF is based on DPDK libraries). +Developer needs debugging and benchmarking skills, as well as understanding of +NFVi infrastructure across multiple domains. There are many ways to contribute to samplevnf. + * Develop new test cases in samplevnf * Review code changes * Develop/contribute to existing VNFs or new VNFs * Write samplevnf documentation -Techical Briefs of existsin VNFs in Technical_Briefs_ +Technical Briefs of exists in VNFs in Technical_Briefs_ + +Get Started +=========== -Get Started: ----------- Where can I find some help to start? -You can also directly contact us by mail with [SampleVNF] prefix in the title at -opnfv-tech-discuss@lists.opnfv.org or on the IRC chan #opnfv-samplevnf. + +You can also directly contact us by mail with [SampleVNF] prefix in the title +at opnfv-tech-discuss@lists.opnfv.org or on the IRC chan #opnfv-samplevnf. How TOs +------- + How can I contribute to SampleVNF? -If you are already a contributor of any OPNFV project, you can contribute to samplevnf. -If you are totally new to OPNFV, you must first create your Linux Foundation account, -then contact us in order to declare you in the repository database. + +If you are already a contributor of any OPNFV project, you can contribute to +samplevnf. +If you are totally new to OPNFV, you must first create your Linux Foundation +account, then contact us in order to declare you in the repository database. We distinguish 2 levels of contributors: -the standard contributor can push patch and vote +1/0/-1 on any samplevnf patch -The commitor can vote -2/-1/0/+1/+2 and merge -SampleVNF commitors are promoted by the samplevnf contributors. +The standard contributor can push patch and vote +1/0/-1 on any samplevnf patch +The committer can vote -2/-1/0/+1/+2 and merge. +SampleVNF committers are promoted by the samplevnf contributors. Gerrit & JIRA +------------- + OPNFV uses Gerrit_ for web based code review and repository management for the Git Version Control System. You can access OPNFV Gerrit from this link. -Please note that you need to have Linux Foundation ID in order to use OPNFV Gerrit. +Please note that you need to have Linux Foundation ID in order to use OPNFV +Gerrit. You can get one from this link. -OPNFV uses JIRA_ for issue management. An important principle of change management -is to have two-way trace-ability between issue management (i.e. JIRA_) and the code repository (via Gerrit). -In this way, individual commits can be traced to JIRA issues and we also know which -commits were used to resolve a JIRA issue. +OPNFV uses JIRA_ for issue management. An important principle of change +management is to have two-way traceability between issue management (i.e. JIRA_)and the code repository (via Gerrit). +In this way, individual commits can be traced to JIRA issues and we also know +which commits were used to resolve a JIRA issue. If you want to contribute to samplevnf, you can pick a issue from SampleVNF's JIRA dashboard or you can create you own issue and submit it to JIRA. Submitting code to Gerrit -Installing and configuring Git and Git-Review is necessary in order to submit code to Gerrit. +------------------------- + +Installing and configuring Git and Git-Review is necessary in order to submit +code to Gerrit. The Getting to the code page will provide you with some help for that. Comitting the code with Git -Open a terminal window and set the project's directory to the working directory using the cd command. -In this case "/home/opnfv/samplevnf" is the path to the samplevnf project folder on my computer. +Open a terminal window and set the project's directory to the working directory +using the cd command. +In this case "/home/opnfv/samplevnf" is the path to samplevnf project folder. Replace this with the path of your own project. :: + cd /home/opnfv/samplevnf Tell Git which files you would like to take into account for the next commit. @@ -77,25 +94,34 @@ This is called 'staging' the files, by placing them into the staging area, using the 'git add' command (or the synonym 'git stage' command). :: + git add samplevnf/samples/sample.yaml ... Alternatively, you can choose to stage all files that have been modified -(that is the files you have worked on) since the last time you generated a commit, by using the -a argument. +(that is the files you have worked on) since the last time you generated a +commit, by using the -a argument. :: + git add -a -Git won't let you push (upload) any code to Gerrit if you haven't pulled the latest changes first. -So the next step is to pull (download) the latest changes made to the project by other collaborators using the 'pull' command. +Git won't let you push (upload) any code to Gerrit if you haven't pulled +the latest changes first. +So the next step is to pull (download) the latest changes made to the project +by other collaborators using the 'pull' command. :: + git pull -Now that you have the latest version of the project and you have staged the files you wish to push, -it is time to actually commit your work to your local Git repository. + +Now that you have the latest version of the project and you have staged the +files you wish to push, it is time to actually commit your work to your local +Git repository. :: + git commit --signoff -m "Title of change Test of change that describes in high level what @@ -104,20 +130,24 @@ it is time to actually commit your work to your local Git repository. JIRA: SAMPLEVNF-XXX" -The message that is required for the commit should follow a specific set of rules. -This practice allows to standardize the description messages attached to the commits, -and eventually navigate among the latter more easily. +The message that is required for the commit should follow a specific set of +rules. This practice allows to standardize the description messages attached +to the commits, and eventually navigate among the latter more easily. Verify your patch locally before submitting Once you finish a patch, you can submit it to Gerrit for code review. -A developer sends a new patch to Gerrit will trigger patch verify job on Jenkins CI. +A developer sends a new patch to Gerrit will trigger patch verify job on +Jenkins CI. Pushing the code to Gerrit for review -Now that the code has been comitted into your local Git repository the following -step is to push it online to Gerrit for it to be reviewed. The command we will use is 'git review'. +Now that the code has been comitted into your local Git repository the +following step is to push it online to Gerrit for it to be reviewed. The +command we will use is 'git review'. :: + git review + This will automatically push your local commit into Gerrit. Code review @@ -125,21 +155,30 @@ You can add Samplevnf committers and contributors to review your codes. Modifying the code under review in Gerrit At the same time the code is being reviewed in Gerrit, you may need to edit it to -make some changes and then send it back for review. The following steps go through the procedure. -Once you have modified/edited your code files under your IDE, you will have to stage them. -The 'status' command is very helpful at this point as it provides an overview of Git's current state. +make some changes and then send it back for review. The following steps go +through the procedure. +Once you have modified/edited your code files under your IDE, you will have to +stage them. +The 'status' command is very helpful at this point as it provides an overview +of Git's current state. :: + git status -The output of the command provides us with the files that have been modified after the latest commit. -You can now stage the files that have been modified as part of the Gerrit code review -edition/modification/improvement using git add command. -It is now time to commit the newly modified files, but the objective here is not to -create a new commit, we simply want to inject the new changes into the previous commit. +The output of the command provides us with the files that have been modified +after the latest commit. + +You can now stage the files that have been modified as part of the Gerrit code +review edition/modification/improvement using git add command. +It is now time to commit the newly modified files, but the objective here is +not to create a new commit, we simply want to inject the new changes into the +previous commit. + You can achieve that with the '--amend' option on the 'commit' command: :: + git commit --amend If the commit was successful, the 'status' command should not return the updated @@ -148,6 +187,7 @@ files as about to be commited. The final step consists in pushing the newly modified commit to Gerrit. :: + git review References diff --git a/docs/testing/developer/design/04-SampleVNF_Design.rst b/docs/testing/developer/design/04-SampleVNF_Design.rst index dff8d535..2bcf6252 100644 --- a/docs/testing/developer/design/04-SampleVNF_Design.rst +++ b/docs/testing/developer/design/04-SampleVNF_Design.rst @@ -4,60 +4,33 @@ .. OPNFV SAMPLEVNF Documentation design file. -=================================== +========================== SampleVNF Highlevel Design -=================================== - -Introduction --------------- -This project provides a placeholder for various sample VNF (Virtual Network Function) -development which includes example reference architecture and optimization methods -related to VNF/Network service for high performance VNFs. This project provides benefits -to other OPNFV projects like Functest, Models, yardstick etc to perform real life -use-case based testing and NFVi characterization for the same. -The sample VNFs are Open Source approximations* of Telco grade VNF’s using optimized -VNF + NFVi Infrastructure libraries, with Performance Characterization of Sample† Traffic Flows. - • * Not a commercial product. Encourage the community to contribute and close the feature gaps. - • † No Vendor/Proprietary Workloads - -About DPDK -^^^^^^^^^^^ -The DPDK IP Pipeline Framework provides set of libraries to build a pipeline -application. In this document, CG-NAT application will be explained with its -own building blocks. - -This document assumes the reader possess the knowledge of DPDK concepts and IP -Pipeline Framework. For more details, read DPDK Getting Started Guide, DPDK -Programmers Guide, DPDK Sample Applications Guide. - -Scope --------- -These application provides a standalone DPDK based high performance different -Virtual Network Function implementation. +========================== +The high level design of the VNF and common code is explained here. Common Code - L2L3 stack -------------------------- +======================== Introduction -^^^^^^^^^^^^^^^ -L2L3 stack comprises of a set of libraries which are commonly used by all -other VNF's. The different components of this stack is shown in the picture -below. +------------ -.. image:: l2l3-components.png +L2L3 stack comprises of a set of libraries which are commonly used by all +other VNF's. It comprises of following components. - (i) Interface Manager - (ii) RTM Lock Library - (iii) ARP/ND & L2 adjacency Library - (iv) L3 stack components + * Interface Manager + * RTM Lock Library + * ARP/ND & L2 adjacency Library + * L3 stack components Interface Manager -^^^^^^^^^^^^^^^^^ +----------------- + Interface manager is a set of API's which acts as a wrapper for the physical interfaces initialization & population. This set of api's assists in configuring an ethernet device, setting up TX & RX queues & starting of the devices. It @@ -68,17 +41,18 @@ components who wants to listen to interface status. It Maintains table of all the interfaces present. It provides API for getting interface statistics. It Provides wrapper APIs on top of DPDKs LAG(link Aggregation) APIs, This -includes creating/deleting BOND interfaces, knowing the properties like Bond mode, -xmit policy, link up delay, link monitor frequency. +includes creating/deleting BOND interfaces, knowing the properties like Bond +mode, xmit policy, link up delay, link monitor frequency. RTM Lock Library -^^^^^^^^^^^^^^^^^ +---------------- + It provides basic lock & unlock functions which should be used for synchronization purposes. ARP/ND & L2 adjacency Library -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +----------------------------- The ARP/ND state machine is given in the following diagram. @@ -102,17 +76,18 @@ retrieval based on nexthop & port_id. It handles Gratuitous ARP. L3 stack Library -^^^^^^^^^^^^^^^^^ +---------------- This library provides API for taking decision of whether pkt belongs to local system or to forwarding.It Provides API for IPv4/IPv6 local packet out send function. It Provides API for packet forwarding - LPM lookup function. + Common Code - Gateway routing ------------------------------ +============================= Introduction -^^^^^^^^^^^^ +------------ Gateway common code is created to support routing functionality for both network and direct attached interfaces. It is supported for both IPv4 and @@ -129,7 +104,8 @@ allocated only for the nb_ports which is configured as per the VNF application configuration. Design -^^^^^^ +------ + The next hop IP and Port numbers are retrieved from the routing table based on the destinantion IP addreess. The destination IP address anded with mask is looked in the routing table for the match. The port/interface number which @@ -144,31 +120,30 @@ of parameters provide in the commands are not valied. Example the if port number is bigger than the supported number ports/interface per application configuration. - Reference routeadd command -^^^^^^^^^^^^^^^^^^^^^^^^^^ +-------------------------- Following are typical reference commands and syntax for adding routes using the CLI. :: -;routeadd -routeadd net 0 202.16.100.20 0xffff0000 -routeadd net 1 172.16.40.20 0xffff0000 -routeadd host 0 202.16.100.20 -routeadd host 1 172.16.40.20 + ;routeadd + routeadd net 0 202.16.100.20 0xffff0000 + routeadd net 1 172.16.40.20 0xffff0000 + routeadd host 0 202.16.100.20 + routeadd host 1 172.16.40.20 -;routeadd -routeadd net 0 fec0::6a05:caff:fe30:21b0 64 -routeadd net 1 2012::6a05:caff:fe30:2081 64 -routeadd host 0 fec0::6a05:caff:fe30:21b0 -routeadd host 1 2012::6a05:caff:fe30:2081 + ;routeadd + routeadd net 0 fec0::6a05:caff:fe30:21b0 64 + routeadd net 1 2012::6a05:caff:fe30:2081 64 + routeadd host 0 fec0::6a05:caff:fe30:21b0 + routeadd host 1 2012::6a05:caff:fe30:2081 vFW - Design -============= +============ Requirements -------------- +------------ Following are the design requierments of the vFW. @@ -188,7 +163,7 @@ Following are the design requierments of the vFW. performance. High Level Design -------------------- +----------------- The Firewall performs basic filtering for malformed packets and dynamic packet filtering incoming packets using the connection tracker library. @@ -274,10 +249,11 @@ connection. The ACL library integrated to firewall provide rule based filtering. vCGNAPT - Design -================= +================ Introduction -^^^^^^^^^^^^^^ +------------ + This application implements vCGNAPT. The idea of vCGNAPT is to extend the life of the service providers IPv4 network infrastructure and mitigate IPv4 address exhaustion by using address and port translation in large scale. It processes the @@ -287,12 +263,14 @@ It also supports the connectivity between the IPv6 access network to IPv4 data n using the IPv6 to IPv4 address translation and vice versa. Scope -^^^^^^ +----- + This application provides a standalone DPDK based high performance vCGNAPT Virtual Network Function implementation. Features -^^^^^^^^^ +-------- + The vCGNAPT VNF currently supports the following functionality: • Static NAT • Dynamic NAT @@ -308,9 +286,9 @@ The vCGNAPT VNF currently supports the following functionality: • Live Session tracking to NAT flow • NAT64 - High Level Design -^^^^^^^^^^^^^^^^^^^ +----------------- + The Upstream path defines the traffic from Private to Public and the downstream path defines the traffic from Public to Private. The vCGNAPT has same set of components to process Upstream and Downstream traffic. @@ -327,46 +305,51 @@ information from which side packet is arrived. The actions can be forwarding to output port (either egress or ingress) or to drop the packet. vCGNAPT Background -^^^^^^^^^^^^^^^^^^^ +------------------ The idea of vCGNAPT is to extend the life of the service providers IPv4 network infrastructure and mitigate IPv4 address exhaustion by using address and port translation in large scale. -It processes the traffic in both the directions. :: -+------------------+ -| +-----+ -| Private consumer | CPE ---- -| IPv4 traffic +-----+ | -+------------------+ | +It processes the traffic in both the directions. + +:: + + +------------------+ + | +-----+ + | Private consumer | CPE ---- + | IPv4 traffic +-----+ | + +------------------+ | | +-------------------+ +------------------+ | | +------------+ - |-> - Private IPv4 - vCGNAPT - Public - |-> - access network - NAT44 - IPv4 traffic - | | +------------+ - | +-------------------+ +------------------+ -+------------------+ | -| +-----+ | -| Private consumer - CPE ---- -| IPv4 traffic +-----+ -+------------------+ + +------------------+ | + | +-----+ | + | Private consumer - CPE ---- + | IPv4 traffic +-----+ + +------------------+ Figure: vCGNAPT deployment in Service provider network Components of vCGNAPT --------------------- -In vCGNAPT, each component is constructed as a packet framework. It includes Master pipeline -component, driver, load balancer pipeline component and vCGNAPT worker pipeline component. A -pipeline framework is a collection of input ports, table(s), output ports and actions -(functions). +In vCGNAPT, each component is constructed as a packet framework. It includes +Master pipeline component, driver, load balancer pipeline component and +vCGNAPT worker pipeline component. A pipeline framework is a collection of +input ports, table(s), output ports and actions (functions). Receive and transmit driver -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Packets will be received in bulk and provided to load balancer thread. The transmit takes -packets from worker thread in a dedicated ring and sent to the hardware queue. +^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Packets will be received in bulk and provided to load balancer thread. The +transmit takes packets from worker thread in a dedicated ring and sent to the +hardware queue. Master pipeline ^^^^^^^^^^^^^^^^ This component does not process any packets and should configure with Core 0, to save cores for other components which processes traffic. The component is responsible for: + 1. Initializing each component of the Pipeline application in different threads 2. Providing CLI shell for the user 3. Propagating the commands from user to the corresponding components. @@ -386,6 +369,7 @@ Tuple can be modified/configured using configuration file vCGNAPT - Static ------------------ + The vCGNAPT component performs translation of private IP & port to public IP & port at egress side and public IP & port to private IP & port at Ingress side based on the NAT rules added to the pipeline Hash table. The NAT rules are @@ -397,94 +381,114 @@ the packets. vCGNAPT- Dynamic ----------------- -The vCGNAPT component performs translation of private IP & port to public IP & port -at egress side and public IP & port to private IP & port at Ingress side based on the -NAT rules added to the pipeline Hash table. Dynamic nature of vCGNAPT refers to the -addition of NAT entries in the Hash table dynamically when new packet arrives. The NAT -rules will be added to the Hash table automatically when there is no matching entry in -the table and the packet is circulated through software queue. The packets that have a -matching egress key or ingress key in the NAT table will be processed to change IP & + +The vCGNAPT component performs translation of private IP & port to public IP & +port at egress side and public IP & port to private IP & port at Ingress side +based on the NAT rules added to the pipeline Hash table. Dynamic nature of +vCGNAPT refers to the addition of NAT entries in the Hash table dynamically +when new packet arrives. The NAT rules will be added to the Hash table +automatically when there is no matching entry in the table and the packet is +circulated through software queue. The packets that have a matching egress +key or ingress key in the NAT table will be processed to change IP & port and will be forwarded to the output port defined in the entry. -Dynamic vCGNAPT acts as static one too, we can do NAT entries statically. Static NAT -entries port range must not conflict to dynamic NAT port range. +Dynamic vCGNAPT acts as static one too, we can do NAT entries statically. +Static NAT entries port range must not conflict to dynamic NAT port range. + +vCGNAPT Static Topology +---------------------- -vCGNAPT Static Topology: --------------------------- IXIA(Port 0)-->(Port 0)VNF(Port 1)-->(Port 1) IXIA operation: Egress --> The packets sent out from ixia(port 0) will be CGNAPTed to ixia(port 1). Igress --> The packets sent out from ixia(port 1) will be CGNAPTed to ixia(port 0). -vCGNAPT Dynamic Topology (UDP_REPLAY): --------------------------------------- +vCGNAPT Dynamic Topology (UDP_REPLAY) +------------------------------------- + IXIA(Port 0)-->(Port 0)VNF(Port 1)-->(Port 0)UDP_REPLAY operation: Egress --> The packets sent out from ixia will be CGNAPTed to L3FWD/L4REPLAY. Ingress --> The L4REPLAY upon reception of packets (Private to Public Network), will immediately replay back the traffic to IXIA interface. (Pub -->Priv). -How to run L4Replay: --------------------- - 1. After the installation of ISB on L4Replay server - go to /opt/isb_bin - 2. ./UDP_Replay -c core_mask -n no_of_channels(let it be as 2) -- -p PORT_MASK --config="(port,queue,lcore)" - eg: ./UDP_Replay -c 0xf -n 4 -- -p 0x3 --config="(0,0,1)" +How to run L4Replay +------------------- + +After the installation of ISB on L4Replay server go to /opt/isb_bin and run the +following command. + +:: + + ./UDP_Replay -c core_mask -n no_of_channels(let it be as 2) -- -p PORT_MASK --config="(port,queue,lcore)" + eg: ./UDP_Replay -c 0xf -n 4 -- -p 0x3 --config="(0,0,1)" vACL - Design -================= +============= Introduction -------------- -This application implements Access Control List (ACL). ACL is typically used for rule -based policy enforcement. It restricts access to a destination IP address/port based -on various header fields, such as source IP address/port, destination IP address/port -and protocol. It is built on top of DPDK and uses the packet framework infrastructure. +This application implements Access Control List (ACL). ACL is typically used +for rule based policy enforcement. It restricts access to a destination IP +address/port based on various header fields, such as source IP address/port, +destination IP address/port and protocol. It is built on top of DPDK and uses +the packet framework infrastructure. Scope ------ -This application provides a standalone DPDK based high performance ACL Virtual Network -Function implementation. +This application provides a standalone DPDK based high performance ACL Virtual +Network Function implementation. High Level Design ------------------ -The ACL Filter performs bulk filtering of incoming packets based on rules in current ruleset, -discarding any packets not permitted by the rules. The mechanisms needed for building the -rule database and performing lookups are provided by the DPDK API. +The ACL Filter performs bulk filtering of incoming packets based on rules in +current ruleset, discarding any packets not permitted by the rules. The +mechanisms needed for building the rule database and performing lookups are +provided by the DPDK API. + http://dpdk.org/doc/api/rte__acl_8h.html -The Input FIFO contains all the incoming packets for ACL filtering. Packets will be dequeued -from the FIFO in bulk for processing by the ACL. Packets will be enqueued to the output FIFO. +The Input FIFO contains all the incoming packets for ACL filtering. Packets +will be dequeued from the FIFO in bulk for processing by the ACL. Packets will +be enqueued to the output FIFO. + The Input and Output FIFOs will be implemented using DPDK Ring Buffers. -The DPDK ACL example: http://dpdk.org/doc/guides/sample_app_ug/l3_forward_access_ctrl.html +The DPDK ACL example: + +http://dpdk.org/doc/guides/sample_app_ug/l3_forward_access_ctrl.html + #figure-ipv4-acl-rule contains a suitable syntax and parser for ACL rules. Components of ACL ------------------ -In ACL, each component is constructed as a packet framework. It includes Master pipeline -component, driver, load balancer pipeline component and ACL worker pipeline component. A -pipeline framework is a collection of input ports, table(s), output ports and actions -(functions). +In ACL, each component is constructed as a packet framework. It includes +Master pipeline component, driver, load balancer pipeline component and ACL +worker pipeline component. A pipeline framework is a collection of input ports, +table(s), output ports and actions (functions). Receive and transmit driver ---------------------------- -Packets will be received in bulk and provided to load balancer thread. The transmit takes -packets from worker thread in a dedicated ring and it is sent to the hardware queue. +^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Packets will be received in bulk and provided to load balancer thread. The +transmit takes packets from worker thread in a dedicated ring and it is sent +to the hardware queue. Master -------- +^^^^^^ This component does not process any packets and should configure with Core 0, -to save cores for other components which processes traffic. The component -is responsible for: +to save cores for other components which processes traffic. + +The component is responsible for + 1. Initializing each component of the Pipeline application in different threads 2. Providing CLI shell for the user 3. Propagating the commands from user to the corresponding components. 4. ARP and ICMP are handled here. Load Balancer --------------- +^^^^^^^^^^^^^ + Load balancer is part of the Multi-Threaded ACL release which distributes the flows to Multiple ACL worker threads. @@ -493,9 +497,11 @@ address, destination port and protocol) applying an XOR logic distributing the load to active worker threads, thereby maintaining an affinity of flows to worker threads. -ACL ---- +ACL Pipeline +^^^^^^^^^^^^ + Visit the following link for DPDK ACL library implementation. + http://dpdk.org/doc/api/rte__acl_8h.html http://dpdk.org/doc/guides/prog_guide/packet_classif_access_ctrl.html @@ -504,10 +510,11 @@ Provides shadow copy for runtime rule configuration support Implements policy based packet forwarding vPE - Design -============= +============ Introduction ---------------- +------------ + An Edge Router typically sits between two networks such as the provider core network and the provider access network. In the below diagram, Customer Edge (CE) Router sits in the provider access network and MPLS cloud network @@ -529,12 +536,14 @@ IP Pipeline Framework. For more details, read DPDK Getting Started Guide, DPDK Programmers Guide, DPDK Sample Applications Guide. Scope ------- +----- + This application provides a standalone DPDK based high performance Provide Edge Router Network Function implementation. High Level Design -------------------- +----------------- + The Edge Router application processes the traffic between Customer and the core network. The Upstream path defines the traffic from Customer to Core and the downstream @@ -596,6 +605,7 @@ Edge Router has the following functionalities in Upstream. Components of vPE ------------------- + The vPE has downstream and upstream pipelines controlled by Master component. Edge router processes two different types of traffic through pipelines I. Downstream (Core-to-Customer) @@ -617,7 +627,8 @@ II. Upstream (Customer-to-Core) 5. Appends two MPLS labels in each outgoing packet. Master Component ------------------ +^^^^^^^^^^^^^^^^ + The Master component is part of all the IP Pipeline applications. This component does not process any packets and should configure with Core0, to save cores for other components which processes traffic. The component @@ -627,20 +638,26 @@ is responsible for 3. Propagating the commands from user to the corresponding components. Upstream and Downstream Pipelines ----------------------------------- +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + The downstream will have Firewall, Pass-through, Metering and Routing pipelines. The upstream will have Pass-through and Routing pipelines. To run the VNF, execute the following: -isb_root/VNFs/vPE$ ./build/ip_pipeline -p 0x3 \ + +:: + + isb_root/VNFs/vPE$ ./build/ip_pipeline -p 0x3 \ -f config/auto_combo_1_instances_1_queues_2_ports_v2.cfg \ -s config/auto_combo_1_instances_1_queues_2_ports_v2.txt + Prox - Packet pROcessing eXecution engine ========================================== -Overview: ----------- +Introduction +------------ + Packet pROcessing eXecution Engine (PROX) which is a DPDK application. PROX can do operations on packets in a highly configurable manner. The PROX application is also displaying performance statistics that can @@ -653,6 +670,7 @@ configuration files. The figure shows that each core is executing a set of tasks. Currently, a task can be any one of the following: + 1. Classify 2. Drop 3. Basic Forwarding (no touch) @@ -669,14 +687,15 @@ a task can be any one of the following: 14. ACL ... One of the example configurations that is distributed with the source code is a -Proof of Concept (PoC) implementation of a Broadband Network Gateway (BNG) with Quality of Service (QoS). +Proof of Concept (PoC) implementation of a Broadband Network Gateway (BNG) +with Quality of Service (QoS). The software architecture for this PoC is presented below. .. image:: images/prox-qo-img02.png The display shows per task statistics through an ncurses interface. -Statistics include: estimated idleness; per second statistics for packets received, -transmitted or dropped; per core cache occupancy; cycles per packet. +Statistics include: estimated idleness; per second statistics for packets +received, transmitted or dropped; per core cache occupancy; cycles per packet. These statistics can help pinpoint bottlenecks in the system. This information can then be used to optimize the configuration. Other features include debugging support, scripting, diff --git a/docs/testing/developer/requirements/03-Requirements.rst b/docs/testing/developer/requirements/03-Requirements.rst index dab07a6e..25798606 100644 --- a/docs/testing/developer/requirements/03-Requirements.rst +++ b/docs/testing/developer/requirements/03-Requirements.rst @@ -15,24 +15,25 @@ Requirements Supported Test setup: -------------------- -The device under test (DUT) consists of a system following; + +The device under test (DUT) consists of a system following + * A single or dual processor and PCH chip, except for System on Chip (SoC) cases * DRAM memory size and frequency (normally single DIMM per channel) * Specific Intel Network Interface Cards (NICs) * BIOS settings noting those that updated from the basic settings * DPDK build configuration settings, and commands used for tests + Connected to the DUT is an IXIA* or Software Traffic generator like pktgen or TRex, simulation platform to generate packet traffic to the DUT ports and determine the throughput/latency at the tester side. -Below are the supported/tested (:term:`VNF`) deployment type. -.. image:: images/deploy_type.png - :width: 800px - :alt: SampleVNF supported topology Hardware & Software Ingredients ------------------------------- -.. code-block:: console + +:: + +---------------+------------------+ | Item | Description | +---------------+------------------+ @@ -75,19 +76,22 @@ The connectivity could be - Single port pair : One pair ports used for traffic -:: + :: + e.g. Single port pair link0 and link1 of VNF are used TG:port 0 <------> VNF:Port 0 TG:port 1 <------> VNF:Port 1 + - Multi port pair : More than one pair of traffic -:: + :: e.g. Two port pair link 0, link1, link2 and link3 of VNF are used TG:port 0 <------> VNF:Port 0 TG:port 1 <------> VNF:Port 1 TG:port 2 <------> VNF:Port 2 TG:port 3 <------> VNF:Port 3 + For openstack/Standalone virtualization, installation please refer the openstack guide and ovs-dpdk/sriov github. (TBA - Add link to guide) -- cgit 1.2.3-korg