From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mga07.intel.com (mga07.intel.com [134.134.136.100]) by dpdk.org (Postfix) with ESMTP id 952232C0C for ; Wed, 2 Nov 2016 06:27:55 +0100 (CET) Received: from fmsmga001.fm.intel.com ([10.253.24.23]) by orsmga105.jf.intel.com with ESMTP; 01 Nov 2016 22:27:54 -0700 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.31,583,1473145200"; d="scan'208";a="1062682327" Received: from kmsmsx152.gar.corp.intel.com ([172.21.73.87]) by fmsmga001.fm.intel.com with ESMTP; 01 Nov 2016 22:27:53 -0700 Received: from pgsmsx103.gar.corp.intel.com ([169.254.2.194]) by KMSMSX152.gar.corp.intel.com ([169.254.11.109]) with mapi id 14.03.0248.002; Wed, 2 Nov 2016 13:27:52 +0800 From: "Zhao1, Wei" To: "dev@dpdk.org" Thread-Topic: [dpdk-dev][RFC]Generic flow filtering API Sample Application Thread-Index: AdI0ydjTDJhAbzhLRLGVu8HTcMt+Aw== Date: Wed, 2 Nov 2016 05:27:50 +0000 Message-ID: Accept-Language: en-US Content-Language: en-US X-MS-Has-Attach: X-MS-TNEF-Correlator: x-titus-metadata-40: eyJDYXRlZ29yeUxhYmVscyI6IiIsIk1ldGFkYXRhIjp7Im5zIjoiaHR0cDpcL1wvd3d3LnRpdHVzLmNvbVwvbnNcL0ludGVsMyIsImlkIjoiNzdlZDVkNTItN2JkMy00YmQ5LWI2YTQtYzk5ZTk3OWRmMjE1IiwicHJvcHMiOlt7Im4iOiJDVFBDbGFzc2lmaWNhdGlvbiIsInZhbHMiOlt7InZhbHVlIjoiQ1RQX0lDIn1dfV19LCJTdWJqZWN0TGFiZWxzIjpbXSwiVE1DVmVyc2lvbiI6IjE1LjkuNi42IiwiVHJ1c3RlZExhYmVsSGFzaCI6IlpwdVM0aDhMSzUybW5FZXBSS2FyNmRHdFZ6dnp5TE9sbVNyUUhscHhyaDQ9In0= x-ctpclassification: CTP_IC x-originating-ip: [172.30.20.205] Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: quoted-printable MIME-Version: 1.0 Subject: [dpdk-dev] [RFC]Generic flow filtering API Sample Application X-BeenThere: dev@dpdk.org X-Mailman-Version: 2.1.15 Precedence: list List-Id: patches and discussions about DPDK List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Wed, 02 Nov 2016 05:27:56 -0000 Hi All, Now we are planning for an sample application for Generic flow=20 filtering API feature, and I have finished the RFC for this example app. Now Adrien Mazarguil has send v2 version of Generic flow=20 filtering API, this sample application RFC is based on that. Thank you. Generic flow filtering API Sample Application =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D The application is a simple example of generic flow filtering API using the= DPDK. The application performs flow director/filtering/classification in packet p= rocessing. Overview -------- The application demonstrates the use of generic flow director/filtering/cla= ssification API=20 in the DPDK to implement packet forwarding.And this document focus on the g= uide line of writing rules configuration=20 files and prompt commands usage. It also supply the definition of the avail= able EAL options arguments which is useful in DPDK packet forwarding processing. Compiling the Application ------------------------- To compile the application: #. Go to the sample application directory: .. code-block:: console export RTE_SDK=3D/path/to/rte_sdk cd ${RTE_SDK}/examples/gen_filter #. Set the target (a default target is used if not specified). For example: .. code-block:: console export RTE_TARGET=3Dx86_64-native-linuxapp-gcc See the *DPDK Getting Started Guide* for possible RTE_TARGET values. #. Build the application: .. code-block:: console make Running the Application ----------------------- The application has a number of EAL options:: ./gen_filter [EAL options] -- EAL options: * -c Codemask, set the hexadecimal bitmask of the cores to run on. * -n Num, set the number of memory channels to use. APP PARAMS: The following are the application options parameters, they must be separat= ed from the EAL options with a "--" separator. * -i Interactive, run this app in interactive mode. In this mode, the app start= s with a prompt that can be used to start and stop forwarding, then manage generic filters rule con= figure in the application, reference to the following description for more details.In non-interactive= mode, the application starts with the configuration specified on the command-line and immediately enters forwarding mode. * --portmask=3D0xXX Set the hexadecimal bitmask of the ports which can be used by the generic = flow director test in packet forwarding. =09 * --coremask=3D0xXX Set the hexadecimal bitmask of the cores running the packet forwarding tes= t. The master lcore is reserved for command line parsing only and cannot be masked on fo= r packet forwarding. * --nb-ports=3DN=20 Set the number of forwarding ports, where 1 <=3D N <=3D "number of ports" = on the board or CONFIG_RTE_MAX_ETHPORTS from the configuration file. The default value = is the number of ports on the board. * --rxq=3DN Set the number of RX queues per port to N, where 1 <=3D N <=3D 65535. The = default value is 1. * --txq=3DN Set the number of TX queues per port to N, where 1 <=3D N <=3D 65535. The = default value is 1. ###this part need to complete later after decision of which EAL commands ar= guments need to be support in this application### Interactive mode ---------------- * when the gen_filter application is started in interactive mode, (-i|--i= nteractive), it displays a prompt=20 that can be used to start and stop forwarding, and configure the applicati= on to set the Flow Director, display statistics, set the Flow Director and other tasks. The application= has a number of commands line options: gen_filter>[Commands] * There is a prompt "gen_filter> " before cursor, command can be enter afte= r that position, also a space bar between configuration file name and command. These are the commands that are currently working under the command line in= terface: * Control Commands help: show the following commands which are currently available in this ap= plication and their usage gen_filter>help =20 quit: quits the application. gen_filter>quit start: start the application, start packet forwarding gen_filter>start stop: stop the application, stop packet forwarding gen_filter>stop showcfg: print configuration infomation about EAL parameters, for example = mapping of cores, rx queue, tx queues and so on. gen_filter>showcfg * General Commands to add/remove/query an filter rule: App will print reminder message for user about whether this rule command = is SUCESS or FAIL after user type in the commmand. add: add filter rules from configuration file gen_filter>add port_id filename.txt (port_id is the port index that user want to add filter rules, it can be = any uint8_t integer. filename.txt is the rule configuration file name from which app read and= paser port rules) del: remove filter rules from configuration file gen_filter>del port_id (port_id is the port index that user want to remove filter rules, it can = be any uint8_t integer.) query: query filter statistics of rules from configuration file and dump r= esults output to log file or printf gen_filter>query port_id query_reset action_name (port_id is the port index that user want to query statistics, it can be = any uint8_t integer. query_reset is used for reset counters after query act= ion,=20 it must be integer 1 if youwant to reset counters after query, else 0. a= ction_name is abbreviation of rte_flow_action_type which user want to query= ) display: display rules applying to that port gen_filter>display port_id (port_id is the port index that user want to add filter rules, it can be = any uint8_t integer.) =09 =09 The rule configuration file=20 --------------------------- 1.There is a mapping between rte_flow_item_type and configuration item type= abbreviation for the convenience of writing: RTE_FLOW_ITEM_TYPE_END end RTE_FLOW_ITEM_TYPE_VOID void RTE_FLOW_ITEM_TYPE_INVERT invert RTE_FLOW_ITEM_TYPE_ANY any RTE_FLOW_ITEM_TYPE_PF pf RTE_FLOW_ITEM_TYPE_VF vf RTE_FLOW_ITEM_TYPE_PORT port RTE_FLOW_ITEM_TYPE_RAW raw RTE_FLOW_ITEM_TYPE_ETH eth RTE_FLOW_ITEM_TYPE_IPV4 ipv4 RTE_FLOW_ITEM_TYPE_IPV6 ipv6 RTE_FLOW_ITEM_TYPE_ICMP icmp RTE_FLOW_ITEM_TYPE_UDP udp RTE_FLOW_ITEM_TYPE_TCP tcp RTE_FLOW_ITEM_TYPE_SCTP sctp RTE_FLOW_ITEM_TYPE_VXLAN vxlan 2.There is a mapping between rte_flow_action_type and configuration action = type abbreviation for the convenience of writing: RTE_FLOW_ACTION_TYPE_END ac_end RTE_FLOW_ACTION_TYPE_VOID ac_void RTE_FLOW_ACTION_TYPE_PASSTHRU ac_passthru RTE_FLOW_ACTION_TYPE_MARK ac_mark RTE_FLOW_ACTION_TYPE_FLAG ac_flag RTE_FLOW_ACTION_TYPE_QUEUE ac_queue RTE_FLOW_ACTION_TYPE_DROP ac_drop RTE_FLOW_ACTION_TYPE_COUNT ac_count RTE_FLOW_ACTION_TYPE_DUP ac_dup RTE_FLOW_ACTION_TYPE_RSS ac_rss RTE_FLOW_ACTION_TYPE_PF ac_pf RTE_FLOW_ACTION_TYPE_VF ac_vf 3.There is a mapping between struct rte_flow_attr and abbreviation for that= configuration of writing: rte_flow_attr attr 4.Writing format of configuration file * write in one line for each rule * writing a "#" at the beginnning of line shows that it is a comment line, = for example: ##########this is a comment line######### * flow pattern item name and action name should be as abbreviation as above * configuration file member has the same name as associated specification s= tructure member, such as dst_addr/src_addr/type_of_service/time_to_live struct members of ipv4_hdr in specification rte_flow_item_ipv4 * there should be a dash('/') between the structure member and its mask if = it has a mask demand, mask format is XX...XX (where X - is a hexadecimal or decimal digit, case= insensitive), and the number of X is according to the length of structure = member, for example: rte_flow_item_ipv4 member time_to_live type is uint8_t, so i= ts mask is also uint8_t such as time_to_live=3D20/0xf0, "f0" is its mask. And the user had better to provide every byte of the mask, for example, f= or a uint16 mask, abbreviative 0xf0 is also ok for mask 0x00f0,=20 but the user must write IPv4/IPV6/Ethernet address mask explicitly and no= t use abbreviative style. * All these config element members such as time_to_live in rte_flow_item_ip= v4, vtc_flow in rte_flow_item_ipv6 should be write in decimal or hexadecima= l format, except for IPv6 and eth address list below.And pay attention to that all = mask is using decimal or hexadecimal format. For example type_of_service= =3D20/0xf0(or 0x14/0xf0) are both ok. * there should be an space bar(' ') between item name or action name and it= s structure member * there should be an equality sign('=3D') between structure member and assi= gnment value, an space bar(' ') between two structure members * there should be an comma(',') between item names or action names * each IPv4 address input number should be decimal or hexadecimal in config= uration file, > IPv4 address expected format:=20 > src_addr (or dst_addr)=3D'/' =20 > src_ipv4_addr format is xxx.xxx.xxx.xxx (where x - is a decimal or hex= adecimal digit) > mask format is XX.XX.XX.XX (where X - is a decimal or hexadecimal digi= t, case insensitive) > can be negligible, the default mask is 0xff.0xff.0xff.0xff or 2= 55.255.255.255 such as IPv4 address 192.168.0.3(0xC0.0xA8.0.0x3), if there is a mask ff= ffff00 for that IPv4 address,there should be a dash before the mask, for example: src_addr=3D192.168.0.3/0xff.0xff.0xff.0x00 or src_addr=3D0x= C0.0xA8.0x0.0x3/0xff.0xff.0xff.0x00 * each IPv6 address input number should be hexadecimal in configuration fil= e, > IPv6 address expected format: > src_addr (or dst_addr)=3D'/' =20 > src_ipv6_addr and mask format is XXXX:XXXX:XXXX:XXXX:XXXX:XXXX:XXXX:XX= XX (where X - is hexadecimal digit, case insensitive). > mask format is XXXX:XXXX:XXXX:XXXX:XXXX:XXXX:XXXX:XXXX (where X - is a= decimal or hexadecimal digit, case insensitive), it don't support the brie= f style of IPv6 address. > can be negligible, the default mask is 0xffff:0xffff:0xffff:0xf= fff:0xffff:0xffff:0xffff:0xffff such as IPv6 address 2001:0000:3238:DFE1:0063:0000:0000:FEFB,if there is= a prefix length or mask for that IPv6 address, there should be a dash befo= re the prefix length, for example: src_addr=3D2001:0000:3238:DFE1:0063:0000:0000:FEFB/0x0000:0= xFFFF:0xFFFF:0x0000:0x0000:0x0000:0x0000 * each ethernet address input number should be hexadecimal in configuration= file, > Ethernet address expected format: > src (or dst)=3D'/' =20 > src_eth_addr_addr and mask format is XX-XX-XX-XX-XX-XX (where X - is a= hexadecimal digit, case insensitive). > mask format is XX:XX:XX:XX:XX:XX (where X - is a decimal or hexadecima= l digit, case insensitive) > can be negligible, the default mask is 0xff:0xff:0xff:0xff:0xff= :0xff such as ethernet address a0:14:ff:36:95:b1, if there is a mask for that = eth address, there should be a dash before the mask, for example: src=3Da0:14:ff:36:95:b1/0xff:0xff:0x00:0x00:0x00:0xff * item pattern or action structure containing array member need to assign e= ach member of the array with the array name before value, for example: rte_flow_item_raw has array member pattern[], if it has 3 el= ements which are 10 11 20,so the configuration expected format is pattern= =3D{10&11&20} * item pattern or action structure containing structure array member or str= ucture need to assign each member of the structure with the structure membe= r name before value, for example: rte_flow_item_eth has structure array mem= ber tag[], if it has 2 elements which are tag[0]=3D{10, 11} tag[1]=3D{20, 2= 1},=20 so the configuration expected format is tag=3D{{10&11}{20&21}} * Flow rule attributes should be configured if necessary for this rule, wri= ting key word "attr" at first, configuration file member has the same name= =20 as struct rte_flow_attr member, for example: attr group=3D1 priority=3D0 = ingress=3D1 egress=3D0 Take the following 6 rules configuration as example: (a)Assign an IPv4 flow with specific source and destination IP address to Q= ueue 8: rte_flow_item_type is RTE_FLOW_ITEM_TYPE_IPV4, source address 192.1= 68.100.15, subnet mask is 0xff.0xff.0xff.0x0,=20 destination address 192.168.3.20, type_of_service is 20 with mask 0xf0, = time_to_live 32, rte_flow_item_type is RTE_FLOW_ACTION_TYPE_QUEUE and queue= index is 8, and Flow rule attributes is group in 1, priority is 0, ingress is 1 and egress is 0(apply noly to inbound traffi= c but not outbound traffic). There are attribute description and 2 items in= flow pattern and 1 flow action. attr group=3D1 priority=3D0 ingress=3D1 egress=3D0, void, ipv4 src_addr= =3D192.168.0.3/0xff.0xff.0xff.0x0 dst_addr=3D192.168.0.4 type_of_service=3D= 20/0xf0 time_to_live=3D32, ac_queue queue=3D8 (b)Assign an IPv6 flow with the certain packet length from and to specific = IP address to the certain vf: rte_flow_item_type is RTE_FLOW_ITEM_TYPE_IPV6= , source address is 2001:0000:3238:DFE1:0063:0000:0000:FEFB, the mask is 0= x0000:0xFFFF:0xFFFF:0x0000:0x0000:0x0000:0x0000, destination address is 200= 1:0000:3238:DFE1:0063:0000:0000:0A23, payload_len 1024,rte_flow_action_type is RTE_FLOW_ACTION_TYPE_VF and RTE= _FLOW_ACTION_TYPE_COUNT, redirect the packet to a vf and enables counters f= or this rule, there is 1 item in flow pattern and 2 flow action. ipv6 src_addr=3D2001:0000:3238:DFE1:0063:0000:0000:FEFB/0x0000:0xFFFF:0x= FFFF:0x0000:0x0000:0x0000:0x0000 dst_addr=3D2001:0000:3238:DFE1:0063:0000:0= 000:0A23 payload_len=3D1024 vtc_flow=3D255/0xff, ac_vf original=3D1 vf=3D2,= ac_count (c)A flow with RSS usage for specific MAC address Ethernet packets redirect= ed to Queue 0 and 3: rte_flow_item_type is RTE_FLOW_ITEM_TYPE_ETH, source a= ddress is a0:14:ff:36:95:b1 and its mask is 0xff:0xff:0x00:0x00:0x00:0xff,= =20 destination address is b0:24:ff:36:95:f2 and its mask is default 0xff:0x= ff:0xff:0xff:0xff:0xff, 2 tag elements is tag[0]=3D{10, 11} tag[1]=3D{20, 2= 1}, rte_flow_action_type is RTE_FLOW_ACTION_TYPE_RSS, queue index is 0 and 3 eth src=3Da0:14:ff:36:95:b1/0xff:0xff:0x00:0x00:0x00:0xff dst=3Db0:24:ff= :36:95:f2 tag=3D{{10&11}{20&21}}, ac_rss queue=3D{0&3} (d)Add a 32 bit value to a VLAN packet to return with that mark: rte_flow_i= tem_type is RTE_FLOW_ITEM_TYPE_VXLAN, VXLAN network identifier index is 11,= flags is 0x8 and the 32 bit value is 0x1a2b3c4d rte_flow_action_type is RTE_FLOW_ACTION_TYPE_MARK=20 vxlan flags=3D0x8 vni=3D11, ac_mark mark=3D0x1a2b3c4d (e)Drop cerstain specific TCP packets: rte_flow_item_type is RTE_FLOW_ITEM_= TYPE_TCP, src_port is 80, sent_seq is 726, tcp_flags is 2 rte_flow_action_type is RTE_FLOW_ACTION_TYPE_DROP tcp src_port=3D80 sent_seq=3D726 tcp_flags=3D2, ac_drop (f)Redirect some UDP packets into a specific queue: rte_flow_item_type is R= TE_FLOW_ITEM_TYPE_UDP, src_port is 21, dst_port is 21, rte_flow_action_type is RTE_FLOW_ACTION_TYPE_QUEUE, queue index is 1 udp src_port=3D21 dst_port=3D21, ac_queue queue=3D1 Explanation ----------- The following sections provide an explanation of the main components of the= app code: main function ------------- * open configuration file and parser the simple rules, then call a few rule= management functions in order to fully manage flows. Each created flow rule is associated with an opaque, = PMD-specific handle pointer. The application is responsible for keeping it until the rule is destroyed= . packet forward function -----------------------=20 * Forwards packets "as-is" in I/O mode. This is the fastest possible forwar= ding operation as it does not access packets data. This is the default mode of this exam= ple. rule management function ------------------------ * Check whether a flow rule can be created on a given port * Create a flow rule on a given port. * Query an existing flow rule on a given port. * Destroy a flow rule on a given port. * Destroy all flow rules associated with a port.