diff options
Diffstat (limited to 'doc/guides/sample_app_ug')
| -rw-r--r-- | doc/guides/sample_app_ug/flow_filtering.rst | 2 | ||||
| -rw-r--r-- | doc/guides/sample_app_ug/img/master_slave_proc.png | bin | 195232 -> 0 bytes | |||
| -rw-r--r-- | doc/guides/sample_app_ug/img/slave_proc_recov.png | bin | 85287 -> 0 bytes | |||
| -rw-r--r-- | doc/guides/sample_app_ug/index.rst | 4 | ||||
| -rw-r--r-- | doc/guides/sample_app_ug/ip_pipeline.rst | 2 | ||||
| -rw-r--r-- | doc/guides/sample_app_ug/kernel_nic_interface.rst | 353 | ||||
| -rw-r--r-- | doc/guides/sample_app_ug/l2_forward_job_stats.rst | 19 | ||||
| -rw-r--r-- | doc/guides/sample_app_ug/l2_forward_real_virtual.rst | 19 | ||||
| -rw-r--r-- | doc/guides/sample_app_ug/link_status_intr.rst | 5 | ||||
| -rw-r--r-- | doc/guides/sample_app_ug/multi_process.rst | 406 | ||||
| -rw-r--r-- | doc/guides/sample_app_ug/vhost.rst | 9 | ||||
| -rw-r--r-- | doc/guides/sample_app_ug/vm_power_management.rst | 165 | ||||
| -rw-r--r-- | doc/guides/sample_app_ug/vmdq_dcb_forwarding.rst | 4 |
13 files changed, 170 insertions, 818 deletions
diff --git a/doc/guides/sample_app_ug/flow_filtering.rst b/doc/guides/sample_app_ug/flow_filtering.rst index bbf8af0e..bd0ae1e2 100644 --- a/doc/guides/sample_app_ug/flow_filtering.rst +++ b/doc/guides/sample_app_ug/flow_filtering.rst @@ -139,7 +139,6 @@ application is shown below: struct rte_eth_conf port_conf = { .rxmode = { .split_hdr_size = 0, - .ignore_offload_bitfield = 1, .offloads = DEV_RX_OFFLOAD_CRC_STRIP, }, .txmode = { @@ -216,7 +215,6 @@ The Ethernet port is configured with default settings using the struct rte_eth_conf port_conf = { .rxmode = { .split_hdr_size = 0, - .ignore_offload_bitfield = 1, .offloads = DEV_RX_OFFLOAD_CRC_STRIP, }, .txmode = { diff --git a/doc/guides/sample_app_ug/img/master_slave_proc.png b/doc/guides/sample_app_ug/img/master_slave_proc.png Binary files differdeleted file mode 100644 index a0065e85..00000000 --- a/doc/guides/sample_app_ug/img/master_slave_proc.png +++ /dev/null diff --git a/doc/guides/sample_app_ug/img/slave_proc_recov.png b/doc/guides/sample_app_ug/img/slave_proc_recov.png Binary files differdeleted file mode 100644 index 62f1f088..00000000 --- a/doc/guides/sample_app_ug/img/slave_proc_recov.png +++ /dev/null diff --git a/doc/guides/sample_app_ug/index.rst b/doc/guides/sample_app_ug/index.rst index 57e8354d..5bedf4f6 100644 --- a/doc/guides/sample_app_ug/index.rst +++ b/doc/guides/sample_app_ug/index.rst @@ -83,10 +83,6 @@ Sample Applications User Guides :numref:`figure_client_svr_sym_multi_proc_app` :ref:`figure_client_svr_sym_multi_proc_app` -:numref:`figure_master_slave_proc` :ref:`figure_master_slave_proc` - -:numref:`figure_slave_proc_recov` :ref:`figure_slave_proc_recov` - :numref:`figure_qos_sched_app_arch` :ref:`figure_qos_sched_app_arch` :numref:`figure_pipeline_overview` :ref:`figure_pipeline_overview` diff --git a/doc/guides/sample_app_ug/ip_pipeline.rst b/doc/guides/sample_app_ug/ip_pipeline.rst index 660798d5..b75509a0 100644 --- a/doc/guides/sample_app_ug/ip_pipeline.rst +++ b/doc/guides/sample_app_ug/ip_pipeline.rst @@ -222,6 +222,8 @@ Link txq <n_queues> <queue_size> promiscuous on | off [rss <qid_0> ... <qid_n>] + Note: The PCI device name must be specified in the Domain:Bus:Device.Function format. + Mempool ~~~~~~~ diff --git a/doc/guides/sample_app_ug/kernel_nic_interface.rst b/doc/guides/sample_app_ug/kernel_nic_interface.rst index fc110997..1b3ee9a5 100644 --- a/doc/guides/sample_app_ug/kernel_nic_interface.rst +++ b/doc/guides/sample_app_ug/kernel_nic_interface.rst @@ -202,74 +202,8 @@ Setup of mbuf pool, driver and queues is similar to the setup done in the :doc:` In addition, one or more kernel NIC interfaces are allocated for each of the configured ports according to the command line parameters. -The code for allocating the kernel NIC interfaces for a specific port is as follows: - -.. code-block:: c - - static int - kni_alloc(uint16_t port_id) - { - uint8_t i; - struct rte_kni *kni; - struct rte_kni_conf conf; - struct kni_port_params **params = kni_port_params_array; - - if (port_id >= RTE_MAX_ETHPORTS || !params[port_id]) - return -1; - - params[port_id]->nb_kni = params[port_id]->nb_lcore_k ? params[port_id]->nb_lcore_k : 1; - - for (i = 0; i < params[port_id]->nb_kni; i++) { - - /* Clear conf at first */ - - memset(&conf, 0, sizeof(conf)); - if (params[port_id]->nb_lcore_k) { - snprintf(conf.name, RTE_KNI_NAMESIZE, "vEth%u_%u", port_id, i); - conf.core_id = params[port_id]->lcore_k[i]; - conf.force_bind = 1; - } else - snprintf(conf.name, RTE_KNI_NAMESIZE, "vEth%u", port_id); - conf.group_id = (uint16_t)port_id; - conf.mbuf_size = MAX_PACKET_SZ; - - /* - * The first KNI device associated to a port - * is the master, for multiple kernel thread - * environment. - */ - - if (i == 0) { - struct rte_kni_ops ops; - struct rte_eth_dev_info dev_info; - - memset(&dev_info, 0, sizeof(dev_info)); rte_eth_dev_info_get(port_id, &dev_info); - - conf.addr = dev_info.pci_dev->addr; - conf.id = dev_info.pci_dev->id; - - /* Get the interface default mac address */ - rte_eth_macaddr_get(port_id, (struct ether_addr *)&conf.mac_addr); - - memset(&ops, 0, sizeof(ops)); - - ops.port_id = port_id; - ops.change_mtu = kni_change_mtu; - ops.config_network_if = kni_config_network_interface; - ops.config_mac_address = kni_config_mac_address; - - kni = rte_kni_alloc(pktmbuf_pool, &conf, &ops); - } else - kni = rte_kni_alloc(pktmbuf_pool, &conf, NULL); - - if (!kni) - rte_exit(EXIT_FAILURE, "Fail to create kni for " - "port: %d\n", port_id); - - params[port_id]->kni[i] = kni; - } - return 0; - } +The code for allocating the kernel NIC interfaces for a specific port is +in the function ``kni_alloc``. The other step in the initialization process that is unique to this sample application is the association of each port with lcores for RX, TX and kernel threads. @@ -280,105 +214,8 @@ is the association of each port with lcores for RX, TX and kernel threads. * Other lcores for pinning the kernel threads on one by one -This is done by using the`kni_port_params_array[]` array, which is indexed by the port ID. -The code is as follows: - -.. code-block:: console - - static int - parse_config(const char *arg) - { - const char *p, *p0 = arg; - char s[256], *end; - unsigned size; - enum fieldnames { - FLD_PORT = 0, - FLD_LCORE_RX, - FLD_LCORE_TX, - _NUM_FLD = KNI_MAX_KTHREAD + 3, - }; - int i, j, nb_token; - char *str_fld[_NUM_FLD]; - unsigned long int_fld[_NUM_FLD]; - uint16_t port_id, nb_kni_port_params = 0; - - memset(&kni_port_params_array, 0, sizeof(kni_port_params_array)); - - while (((p = strchr(p0, '(')) != NULL) && nb_kni_port_params < RTE_MAX_ETHPORTS) { - p++; - if ((p0 = strchr(p, ')')) == NULL) - goto fail; - - size = p0 - p; - - if (size >= sizeof(s)) { - printf("Invalid config parameters\n"); - goto fail; - } - - snprintf(s, sizeof(s), "%.*s", size, p); - nb_token = rte_strsplit(s, sizeof(s), str_fld, _NUM_FLD, ','); - - if (nb_token <= FLD_LCORE_TX) { - printf("Invalid config parameters\n"); - goto fail; - } - - for (i = 0; i < nb_token; i++) { - errno = 0; - int_fld[i] = strtoul(str_fld[i], &end, 0); - if (errno != 0 || end == str_fld[i]) { - printf("Invalid config parameters\n"); - goto fail; - } - } - - i = 0; - port_id = (uint8_t)int_fld[i++]; - - if (port_id >= RTE_MAX_ETHPORTS) { - printf("Port ID %u could not exceed the maximum %u\n", port_id, RTE_MAX_ETHPORTS); - goto fail; - } - - if (kni_port_params_array[port_id]) { - printf("Port %u has been configured\n", port_id); - goto fail; - } - - kni_port_params_array[port_id] = (struct kni_port_params*)rte_zmalloc("KNI_port_params", sizeof(struct kni_port_params), RTE_CACHE_LINE_SIZE); - kni_port_params_array[port_id]->port_id = port_id; - kni_port_params_array[port_id]->lcore_rx = (uint8_t)int_fld[i++]; - kni_port_params_array[port_id]->lcore_tx = (uint8_t)int_fld[i++]; - - if (kni_port_params_array[port_id]->lcore_rx >= RTE_MAX_LCORE || kni_port_params_array[port_id]->lcore_tx >= RTE_MAX_LCORE) { - printf("lcore_rx %u or lcore_tx %u ID could not " - "exceed the maximum %u\n", - kni_port_params_array[port_id]->lcore_rx, kni_port_params_array[port_id]->lcore_tx, RTE_MAX_LCORE); - goto fail; - } - - for (j = 0; i < nb_token && j < KNI_MAX_KTHREAD; i++, j++) - kni_port_params_array[port_id]->lcore_k[j] = (uint8_t)int_fld[i]; - kni_port_params_array[port_id]->nb_lcore_k = j; - } - - print_config(); - - return 0; - - fail: - - for (i = 0; i < RTE_MAX_ETHPORTS; i++) { - if (kni_port_params_array[i]) { - rte_free(kni_port_params_array[i]); - kni_port_params_array[i] = NULL; - } - } - - return -1; - - } +This is done by using the ``kni_port_params_array[]`` array, which is indexed by the port ID. +The code is in the function ``parse_config``. Packet Forwarding ~~~~~~~~~~~~~~~~~ @@ -387,99 +224,18 @@ After the initialization steps are completed, the main_loop() function is run on This function first checks the lcore_id against the user provided lcore_rx and lcore_tx to see if this lcore is reading from or writing to kernel NIC interfaces. -For the case that reads from a NIC port and writes to the kernel NIC interfaces, +For the case that reads from a NIC port and writes to the kernel NIC interfaces (``kni_ingress``), the packet reception is the same as in L2 Forwarding sample application (see :ref:`l2_fwd_app_rx_tx_packets`). The packet transmission is done by sending mbufs into the kernel NIC interfaces by rte_kni_tx_burst(). The KNI library automatically frees the mbufs after the kernel successfully copied the mbufs. -.. code-block:: c - - /** - * Interface to burst rx and enqueue mbufs into rx_q - */ - - static void - kni_ingress(struct kni_port_params *p) - { - uint8_t i, nb_kni, port_id; - unsigned nb_rx, num; - struct rte_mbuf *pkts_burst[PKT_BURST_SZ]; - - if (p == NULL) - return; - - nb_kni = p->nb_kni; - port_id = p->port_id; - - for (i = 0; i < nb_kni; i++) { - /* Burst rx from eth */ - nb_rx = rte_eth_rx_burst(port_id, 0, pkts_burst, PKT_BURST_SZ); - if (unlikely(nb_rx > PKT_BURST_SZ)) { - RTE_LOG(ERR, APP, "Error receiving from eth\n"); - return; - } - - /* Burst tx to kni */ - num = rte_kni_tx_burst(p->kni[i], pkts_burst, nb_rx); - kni_stats[port_id].rx_packets += num; - rte_kni_handle_request(p->kni[i]); - - if (unlikely(num < nb_rx)) { - /* Free mbufs not tx to kni interface */ - kni_burst_free_mbufs(&pkts_burst[num], nb_rx - num); - kni_stats[port_id].rx_dropped += nb_rx - num; - } - } - } - -For the other case that reads from kernel NIC interfaces and writes to a physical NIC port, packets are retrieved by reading -mbufs from kernel NIC interfaces by `rte_kni_rx_burst()`. +For the other case that reads from kernel NIC interfaces +and writes to a physical NIC port (``kni_egress``), +packets are retrieved by reading mbufs from kernel NIC interfaces by ``rte_kni_rx_burst()``. The packet transmission is the same as in the L2 Forwarding sample application (see :ref:`l2_fwd_app_rx_tx_packets`). -.. code-block:: c - - /** - * Interface to dequeue mbufs from tx_q and burst tx - */ - - static void - - kni_egress(struct kni_port_params *p) - { - uint8_t i, nb_kni, port_id; - unsigned nb_tx, num; - struct rte_mbuf *pkts_burst[PKT_BURST_SZ]; - - if (p == NULL) - return; - - nb_kni = p->nb_kni; - port_id = p->port_id; - - for (i = 0; i < nb_kni; i++) { - /* Burst rx from kni */ - num = rte_kni_rx_burst(p->kni[i], pkts_burst, PKT_BURST_SZ); - if (unlikely(num > PKT_BURST_SZ)) { - RTE_LOG(ERR, APP, "Error receiving from KNI\n"); - return; - } - - /* Burst tx to eth */ - - nb_tx = rte_eth_tx_burst(port_id, 0, pkts_burst, (uint16_t)num); - - kni_stats[port_id].tx_packets += nb_tx; - - if (unlikely(nb_tx < num)) { - /* Free mbufs not tx to NIC */ - kni_burst_free_mbufs(&pkts_burst[nb_tx], num - nb_tx); - kni_stats[port_id].tx_dropped += num - nb_tx; - } - } - } - Callbacks for Kernel Requests ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -492,96 +248,3 @@ Application may choose to not implement following callbacks: - ``config_mac_address`` - ``config_promiscusity`` - - -.. code-block:: c - - static struct rte_kni_ops kni_ops = { - .change_mtu = kni_change_mtu, - .config_network_if = kni_config_network_interface, - .config_mac_address = kni_config_mac_address, - .config_promiscusity = kni_config_promiscusity, - }; - - /* Callback for request of changing MTU */ - - static int - kni_change_mtu(uint16_t port_id, unsigned new_mtu) - { - int ret; - struct rte_eth_conf conf; - - RTE_LOG(INFO, APP, "Change MTU of port %d to %u\n", port_id, new_mtu); - - /* Stop specific port */ - - rte_eth_dev_stop(port_id); - - memcpy(&conf, &port_conf, sizeof(conf)); - - /* Set new MTU */ - - if (new_mtu > ETHER_MAX_LEN) - conf.rxmode.jumbo_frame = 1; - else - conf.rxmode.jumbo_frame = 0; - - /* mtu + length of header + length of FCS = max pkt length */ - - conf.rxmode.max_rx_pkt_len = new_mtu + KNI_ENET_HEADER_SIZE + KNI_ENET_FCS_SIZE; - - ret = rte_eth_dev_configure(port_id, 1, 1, &conf); - if (ret < 0) { - RTE_LOG(ERR, APP, "Fail to reconfigure port %d\n", port_id); - return ret; - } - - /* Restart specific port */ - - ret = rte_eth_dev_start(port_id); - if (ret < 0) { - RTE_LOG(ERR, APP, "Fail to restart port %d\n", port_id); - return ret; - } - - return 0; - } - - /* Callback for request of configuring network interface up/down */ - - static int - kni_config_network_interface(uint16_t port_id, uint8_t if_up) - { - int ret = 0; - - RTE_LOG(INFO, APP, "Configure network interface of %d %s\n", - - port_id, if_up ? "up" : "down"); - - if (if_up != 0) { - /* Configure network interface up */ - rte_eth_dev_stop(port_id); - ret = rte_eth_dev_start(port_id); - } else /* Configure network interface down */ - rte_eth_dev_stop(port_id); - - if (ret < 0) - RTE_LOG(ERR, APP, "Failed to start port %d\n", port_id); - return ret; - } - - /* Callback for request of configuring device mac address */ - - static int - kni_config_mac_address(uint16_t port_id, uint8_t mac_addr[]) - { - ..... - } - - /* Callback for request of configuring promiscuous mode */ - - static int - kni_config_promiscusity(uint16_t port_id, uint8_t to_on) - { - ..... - } diff --git a/doc/guides/sample_app_ug/l2_forward_job_stats.rst b/doc/guides/sample_app_ug/l2_forward_job_stats.rst index d7219a29..ba73d855 100644 --- a/doc/guides/sample_app_ug/l2_forward_job_stats.rst +++ b/doc/guides/sample_app_ug/l2_forward_job_stats.rst @@ -218,25 +218,6 @@ The rte_eth_dev_configure() function is used to configure the number of queues f "err=%d, port=%u\n", ret, portid); -The global configuration is stored in a static structure: - -.. code-block:: c - - static const struct rte_eth_conf port_conf = { - .rxmode = { - .split_hdr_size = 0, - .header_split = 0, /**< Header Split disabled */ - .hw_ip_checksum = 0, /**< IP checksum offload disabled */ - .hw_vlan_filter = 0, /**< VLAN filtering disabled */ - .jumbo_frame = 0, /**< Jumbo Frame Support disabled */ - .hw_strip_crc= 0, /**< CRC stripped by hardware */ - }, - - .txmode = { - .mq_mode = ETH_DCB_NONE - }, - }; - RX Queue Initialization ~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/doc/guides/sample_app_ug/l2_forward_real_virtual.rst b/doc/guides/sample_app_ug/l2_forward_real_virtual.rst index b459d4ef..2b2d5afa 100644 --- a/doc/guides/sample_app_ug/l2_forward_real_virtual.rst +++ b/doc/guides/sample_app_ug/l2_forward_real_virtual.rst @@ -245,25 +245,6 @@ The rte_eth_dev_configure() function is used to configure the number of queues f "err=%d, port=%u\n", ret, portid); -The global configuration is stored in a static structure: - -.. code-block:: c - - static const struct rte_eth_conf port_conf = { - .rxmode = { - .split_hdr_size = 0, - .header_split = 0, /**< Header Split disabled */ - .hw_ip_checksum = 0, /**< IP checksum offload disabled */ - .hw_vlan_filter = 0, /**< VLAN filtering disabled */ - .jumbo_frame = 0, /**< Jumbo Frame Support disabled */ - .hw_strip_crc= 0, /**< CRC stripped by hardware */ - }, - - .txmode = { - .mq_mode = ETH_DCB_NONE - }, - }; - .. _l2_fwd_app_rx_init: RX Queue Initialization diff --git a/doc/guides/sample_app_ug/link_status_intr.rst b/doc/guides/sample_app_ug/link_status_intr.rst index 8c11ba4a..c7665fe5 100644 --- a/doc/guides/sample_app_ug/link_status_intr.rst +++ b/doc/guides/sample_app_ug/link_status_intr.rst @@ -137,10 +137,7 @@ The global configuration is stored in a static structure: static const struct rte_eth_conf port_conf = { .rxmode = { .split_hdr_size = 0, - .header_split = 0, /**< Header Split disabled */ - .hw_ip_checksum = 0, /**< IP checksum offload disabled */ - .hw_vlan_filter = 0, /**< VLAN filtering disabled */ - .hw_strip_crc= 0, /**< CRC stripped by hardware */ + .offloads = DEV_RX_OFFLOAD_CRC_STRIP, }, .txmode = {}, .intr_conf = { diff --git a/doc/guides/sample_app_ug/multi_process.rst b/doc/guides/sample_app_ug/multi_process.rst index b84e9a74..9c374da6 100644 --- a/doc/guides/sample_app_ug/multi_process.rst +++ b/doc/guides/sample_app_ug/multi_process.rst @@ -321,409 +321,3 @@ In both the server and the client processes, outgoing packets are buffered befor so as to allow the sending of multiple packets in a single burst to improve efficiency. For example, the client process will buffer packets to send, until either the buffer is full or until we receive no further packets from the server. - -Master-slave Multi-process Example -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The fourth example of DPDK multi-process support demonstrates a master-slave model that -provide the capability of application recovery if a slave process crashes or meets unexpected conditions. -In addition, it also demonstrates the floating process, -which can run among different cores in contrast to the traditional way of binding a process/thread to a specific CPU core, -using the local cache mechanism of mempool structures. - -This application performs the same functionality as the L2 Forwarding sample application, -therefore this chapter does not cover that part but describes functionality that is introduced in this multi-process example only. -Please refer to :doc:`l2_forward_real_virtual` for more information. - -Unlike previous examples where all processes are started from the command line with input arguments, in this example, -only one process is spawned from the command line and that process creates other processes. -The following section describes this in more detail. - -Master-slave Process Models -^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -The process spawned from the command line is called the *master process* in this document. -A process created by the master is called a *slave process*. -The application has only one master process, but could have multiple slave processes. - -Once the master process begins to run, it tries to initialize all the resources such as -memory, CPU cores, driver, ports, and so on, as the other examples do. -Thereafter, it creates slave processes, as shown in the following figure. - -.. _figure_master_slave_proc: - -.. figure:: img/master_slave_proc.* - - Master-slave Process Workflow - - -The master process calls the rte_eal_mp_remote_launch() EAL function to launch an application function for each pinned thread through the pipe. -Then, it waits to check if any slave processes have exited. -If so, the process tries to re-initialize the resources that belong to that slave and launch them in the pinned thread entry again. -The following section describes the recovery procedures in more detail. - -For each pinned thread in EAL, after reading any data from the pipe, it tries to call the function that the application specified. -In this master specified function, a fork() call creates a slave process that performs the L2 forwarding task. -Then, the function waits until the slave exits, is killed or crashes. Thereafter, it notifies the master of this event and returns. -Finally, the EAL pinned thread waits until the new function is launched. - -After discussing the master-slave model, it is necessary to mention another issue, global and static variables. - -For multiple-thread cases, all global and static variables have only one copy and they can be accessed by any thread if applicable. -So, they can be used to sync or share data among threads. - -In the previous examples, each process has separate global and static variables in memory and are independent of each other. -If it is necessary to share the knowledge, some communication mechanism should be deployed, such as, memzone, ring, shared memory, and so on. -The global or static variables are not a valid approach to share data among processes. -For variables in this example, on the one hand, the slave process inherits all the knowledge of these variables after being created by the master. -On the other hand, other processes cannot know if one or more processes modifies them after slave creation since that -is the nature of a multiple process address space. -But this does not mean that these variables cannot be used to share or sync data; it depends on the use case. -The following are the possible use cases: - -#. The master process starts and initializes a variable and it will never be changed after slave processes created. This case is OK. - -#. After the slave processes are created, the master or slave cores need to change a variable, but other processes do not need to know the change. - This case is also OK. - -#. After the slave processes are created, the master or a slave needs to change a variable. - In the meantime, one or more other process needs to be aware of the change. - In this case, global and static variables cannot be used to share knowledge. Another communication mechanism is needed. - A simple approach without lock protection can be a heap buffer allocated by rte_malloc or mem zone. - -Slave Process Recovery Mechanism -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Before talking about the recovery mechanism, it is necessary to know what is needed before a new slave instance can run if a previous one exited. - -When a slave process exits, the system returns all the resources allocated for this process automatically. -However, this does not include the resources that were allocated by the DPDK. All the hardware resources are shared among the processes, -which include memzone, mempool, ring, a heap buffer allocated by the rte_malloc library, and so on. -If the new instance runs and the allocated resource is not returned, either resource allocation failed or the hardware resource is lost forever. - -When a slave process runs, it may have dependencies on other processes. -They could have execution sequence orders; they could share the ring to communicate; they could share the same port for reception and forwarding; -they could use lock structures to do exclusive access in some critical path. -What happens to the dependent process(es) if the peer leaves? -The consequence are varied since the dependency cases are complex. -It depends on what the processed had shared. -However, it is necessary to notify the peer(s) if one slave exited. -Then, the peer(s) will be aware of that and wait until the new instance begins to run. - -Therefore, to provide the capability to resume the new slave instance if the previous one exited, it is necessary to provide several mechanisms: - -#. Keep a resource list for each slave process. - Before a slave process run, the master should prepare a resource list. - After it exits, the master could either delete the allocated resources and create new ones, - or re-initialize those for use by the new instance. - -#. Set up a notification mechanism for slave process exit cases. After the specific slave leaves, - the master should be notified and then help to create a new instance. - This mechanism is provided in Section `Master-slave Process Models`_. - -#. Use a synchronization mechanism among dependent processes. - The master should have the capability to stop or kill slave processes that have a dependency on the one that has exited. - Then, after the new instance of exited slave process begins to run, the dependency ones could resume or run from the start. - The example sends a STOP command to slave processes dependent on the exited one, then they will exit. - Thereafter, the master creates new instances for the exited slave processes. - -The following diagram describes slave process recovery. - -.. _figure_slave_proc_recov: - -.. figure:: img/slave_proc_recov.* - - Slave Process Recovery Process Flow - - -Floating Process Support -^^^^^^^^^^^^^^^^^^^^^^^^ - -When the DPDK application runs, there is always a -c option passed in to indicate the cores that are enabled. -Then, the DPDK creates a thread for each enabled core. -By doing so, it creates a 1:1 mapping between the enabled core and each thread. -The enabled core always has an ID, therefore, each thread has a unique core ID in the DPDK execution environment. -With the ID, each thread can easily access the structures or resources exclusively belonging to it without using function parameter passing. -It can easily use the rte_lcore_id() function to get the value in every function that is called. - -For threads/processes not created in that way, either pinned to a core or not, they will not own a unique ID and the -rte_lcore_id() function will not work in the correct way. -However, sometimes these threads/processes still need the unique ID mechanism to do easy access on structures or resources. -For example, the DPDK mempool library provides a local cache mechanism -(refer to :ref:`mempool_local_cache`) -for fast element allocation and freeing. -If using a non-unique ID or a fake one, -a race condition occurs if two or more threads/ processes with the same core ID try to use the local cache. - -Therefore, unused core IDs from the passing of parameters with the -c option are used to organize the core ID allocation array. -Once the floating process is spawned, it tries to allocate a unique core ID from the array and release it on exit. - -A natural way to spawn a floating process is to use the fork() function and allocate a unique core ID from the unused core ID array. -However, it is necessary to write new code to provide a notification mechanism for slave exit -and make sure the process recovery mechanism can work with it. - -To avoid producing redundant code, the Master-Slave process model is still used to spawn floating processes, -then cancel the affinity to specific cores. -Besides that, clear the core ID assigned to the DPDK spawning a thread that has a 1:1 mapping with the core mask. -Thereafter, get a new core ID from the unused core ID allocation array. - -Run the Application -^^^^^^^^^^^^^^^^^^^ - -This example has a command line similar to the L2 Forwarding sample application with a few differences. - -To run the application, start one copy of the l2fwd_fork binary in one terminal. -Unlike the L2 Forwarding example, -this example requires at least three cores since the master process will wait and be accountable for slave process recovery. -The command is as follows: - -.. code-block:: console - - #./build/l2fwd_fork -l 2-4 -n 4 -- -p 3 -f - -This example provides another -f option to specify the use of floating process. -If not specified, the example will use a pinned process to perform the L2 forwarding task. - -To verify the recovery mechanism, proceed as follows: First, check the PID of the slave processes: - -.. code-block:: console - - #ps -fe | grep l2fwd_fork - root 5136 4843 29 11:11 pts/1 00:00:05 ./build/l2fwd_fork - root 5145 5136 98 11:11 pts/1 00:00:11 ./build/l2fwd_fork - root 5146 5136 98 11:11 pts/1 00:00:11 ./build/l2fwd_fork - -Then, kill one of the slaves: - -.. code-block:: console - - #kill -9 5145 - -After 1 or 2 seconds, check whether the slave has resumed: - -.. code-block:: console - - #ps -fe | grep l2fwd_fork - root 5136 4843 3 11:11 pts/1 00:00:06 ./build/l2fwd_fork - root 5247 5136 99 11:14 pts/1 00:00:01 ./build/l2fwd_fork - root 5248 5136 99 11:14 pts/1 00:00:01 ./build/l2fwd_fork - -It can also monitor the traffic generator statics to see whether slave processes have resumed. - -Explanation -^^^^^^^^^^^ - -As described in previous sections, -not all global and static variables need to change to be accessible in multiple processes; -it depends on how they are used. -In this example, -the statics info on packets dropped/forwarded/received count needs to be updated by the slave process, -and the master needs to see the update and print them out. -So, it needs to allocate a heap buffer using rte_zmalloc. -In addition, if the -f option is specified, -an array is needed to store the allocated core ID for the floating process so that the master can return it -after a slave has exited accidentally. - -.. code-block:: c - - static int - l2fwd_malloc_shared_struct(void) - { - port_statistics = rte_zmalloc("port_stat", sizeof(struct l2fwd_port_statistics) * RTE_MAX_ETHPORTS, 0); - - if (port_statistics == NULL) - return -1; - - /* allocate mapping_id array */ - - if (float_proc) { - int i; - - mapping_id = rte_malloc("mapping_id", sizeof(unsigned) * RTE_MAX_LCORE, 0); - if (mapping_id == NULL) - return -1; - - for (i = 0 ;i < RTE_MAX_LCORE; i++) - mapping_id[i] = INVALID_MAPPING_ID; - - } - return 0; - } - -For each slave process, packets are received from one port and forwarded to another port that another slave is operating on. -If the other slave exits accidentally, the port it is operating on may not work normally, -so the first slave cannot forward packets to that port. -There is a dependency on the port in this case. So, the master should recognize the dependency. -The following is the code to detect this dependency: - -.. code-block:: c - - for (portid = 0; portid < nb_ports; portid++) { - /* skip ports that are not enabled */ - - if ((l2fwd_enabled_port_mask & (1 << portid)) == 0) - continue; - - /* Find pair ports' lcores */ - - find_lcore = find_pair_lcore = 0; - pair_port = l2fwd_dst_ports[portid]; - - for (i = 0; i < RTE_MAX_LCORE; i++) { - if (!rte_lcore_is_enabled(i)) - continue; - - for (j = 0; j < lcore_queue_conf[i].n_rx_port;j++) { - if (lcore_queue_conf[i].rx_port_list[j] == portid) { - lcore = i; - find_lcore = 1; - break; - } - - if (lcore_queue_conf[i].rx_port_list[j] == pair_port) { - pair_lcore = i; - find_pair_lcore = 1; - break; - } - } - - if (find_lcore && find_pair_lcore) - break; - } - - if (!find_lcore || !find_pair_lcore) - rte_exit(EXIT_FAILURE, "Not find port=%d pair\\n", portid); - - printf("lcore %u and %u paired\\n", lcore, pair_lcore); - - lcore_resource[lcore].pair_id = pair_lcore; - lcore_resource[pair_lcore].pair_id = lcore; - } - -Before launching the slave process, -it is necessary to set up the communication channel between the master and slave so that -the master can notify the slave if its peer process with the dependency exited. -In addition, the master needs to register a callback function in the case where a specific slave exited. - -.. code-block:: c - - for (i = 0; i < RTE_MAX_LCORE; i++) { - if (lcore_resource[i].enabled) { - /* Create ring for master and slave communication */ - - ret = create_ms_ring(i); - if (ret != 0) - rte_exit(EXIT_FAILURE, "Create ring for lcore=%u failed",i); - - if (flib_register_slave_exit_notify(i,slave_exit_cb) != 0) - rte_exit(EXIT_FAILURE, "Register master_trace_slave_exit failed"); - } - } - -After launching the slave process, the master waits and prints out the port statics periodically. -If an event indicating that a slave process exited is detected, -it sends the STOP command to the peer and waits until it has also exited. -Then, it tries to clean up the execution environment and prepare new resources. -Finally, the new slave instance is launched. - -.. code-block:: c - - while (1) { - sleep(1); - cur_tsc = rte_rdtsc(); - diff_tsc = cur_tsc - prev_tsc; - - /* if timer is enabled */ - - if (timer_period > 0) { - /* advance the timer */ - timer_tsc += diff_tsc; - - /* if timer has reached its timeout */ - if (unlikely(timer_tsc >= (uint64_t) timer_period)) { - print_stats(); - - /* reset the timer */ - timer_tsc = 0; - } - } - - prev_tsc = cur_tsc; - - /* Check any slave need restart or recreate */ - - rte_spinlock_lock(&res_lock); - - for (i = 0; i < RTE_MAX_LCORE; i++) { - struct lcore_resource_struct *res = &lcore_resource[i]; - struct lcore_resource_struct *pair = &lcore_resource[res->pair_id]; - - /* If find slave exited, try to reset pair */ - - if (res->enabled && res->flags && pair->enabled) { - if (!pair->flags) { - master_sendcmd_with_ack(pair->lcore_id, CMD_STOP); - rte_spinlock_unlock(&res_lock); - sleep(1); - rte_spinlock_lock(&res_lock); - if (pair->flags) - continue; - } - - if (reset_pair(res->lcore_id, pair->lcore_id) != 0) - rte_exit(EXIT_FAILURE, "failed to reset slave"); - - res->flags = 0; - pair->flags = 0; - } - } - rte_spinlock_unlock(&res_lock); - } - -When the slave process is spawned and starts to run, it checks whether the floating process option is applied. -If so, it clears the affinity to a specific core and also sets the unique core ID to 0. -Then, it tries to allocate a new core ID. -Since the core ID has changed, the resource allocated by the master cannot work, -so it remaps the resource to the new core ID slot. - -.. code-block:: c - - static int - l2fwd_launch_one_lcore( attribute ((unused)) void *dummy) - { - unsigned lcore_id = rte_lcore_id(); - - if (float_proc) { - unsigned flcore_id; - - /* Change it to floating process, also change it's lcore_id */ - - clear_cpu_affinity(); - - RTE_PER_LCORE(_lcore_id) = 0; - - /* Get a lcore_id */ - - if (flib_assign_lcore_id() < 0 ) { - printf("flib_assign_lcore_id failed\n"); - return -1; - } - - flcore_id = rte_lcore_id(); - - /* Set mapping id, so master can return it after slave exited */ - - mapping_id[lcore_id] = flcore_id; - printf("Org lcore_id = %u, cur lcore_id = %u\n",lcore_id, flcore_id); - remapping_slave_resource(lcore_id, flcore_id); - } - - l2fwd_main_loop(); - - /* return lcore_id before return */ - if (float_proc) { - flib_free_lcore_id(rte_lcore_id()); - mapping_id[lcore_id] = INVALID_MAPPING_ID; - } - return 0; - } diff --git a/doc/guides/sample_app_ug/vhost.rst b/doc/guides/sample_app_ug/vhost.rst index 9112e789..fd42cb3f 100644 --- a/doc/guides/sample_app_ug/vhost.rst +++ b/doc/guides/sample_app_ug/vhost.rst @@ -158,6 +158,10 @@ when disabling VLAN strip. Such feature, which heavily depends on hardware, should be removed from this example to reduce confusion. Now, VLAN strip is enabled and cannot be disabled. +**--builtin-net-driver** +A very simple vhost-user net driver which demonstrates how to use the generic +vhost APIs will be used when this option is given. It is disabled by default. + Common Issues ------------- @@ -192,3 +196,8 @@ Common Issues according to the NIC's property. :: make EXTRA_CFLAGS="-DMAX_QUEUES=320" + +* Option "builtin-net-driver" is incompatible with QEMU + + QEMU vhost net device start will fail if protocol feature is not negotiated. + DPDK virtio-user pmd can be the replacement of QEMU. diff --git a/doc/guides/sample_app_ug/vm_power_management.rst b/doc/guides/sample_app_ug/vm_power_management.rst index cd7c7f34..855570d6 100644 --- a/doc/guides/sample_app_ug/vm_power_management.rst +++ b/doc/guides/sample_app_ug/vm_power_management.rst @@ -20,7 +20,7 @@ running on Virtual Machines(VMs). The Virtual Machine Power Management solution shows an example of how a DPDK application can indicate its processing requirements using VM local -only information(vCPU/lcore) to a Host based Monitor which is responsible +only information(vCPU/lcore, etc.) to a Host based Monitor which is responsible for accepting requests for frequency changes for a vCPU, translating the vCPU to a pCPU via libvirt and affecting the change in frequency. @@ -38,6 +38,26 @@ The solution is comprised of two high-level components: to the librte_power ACPI cpufreq sysfs based library. The Host Application relies on both qemu-kvm and libvirt to function. + This monitoring application is responsible for: + + - Accepting requests from client applications: Client applications can + request frequency changes for a vCPU, translating + the vCPU to a pCPU via libvirt and affecting the change in frequency. + + - Accepting policies from client applications: Client application can + send a policy to the host application. The + host application will then apply the rules of the policy independent + of the application. For example, the policy can contain time-of-day + information for busy/quiet periods, and the host application can scale + up/down the relevant cores when required. See the details of the guest + application below for more information on setting the policy values. + + - Out-of-band monitoring of workloads via cores hardware event counters: + The host application can manage power for an application in a virtualised + OR non-virtualised environment by looking at the event counters of the + cores and taking action based on the branch hit/miss ratio. See the host + application '--core-list' command line parameter below. + #. librte_power for Virtual Machines Using an alternate implementation for the librte_power API, requests for @@ -174,13 +194,20 @@ Compiling and Running the Host Application Compiling ~~~~~~~~~ -Compiling the Application -------------------------- - -To compile the sample application see :doc:`compiling`. +For information on compiling DPDK and the sample applications +see :doc:`compiling`. The application is located in the ``vm_power_manager`` sub-directory. +To build just the ``vm_power_manager`` application: + +.. code-block:: console + + export RTE_SDK=/path/to/rte_sdk + export RTE_TARGET=build + cd ${RTE_SDK}/examples/vm_power_manager/ + make + Running ~~~~~~~ @@ -287,38 +314,129 @@ Manual control and inspection can also be carried in relation CPU frequency scal set_cpu_freq {core_num} up|down|min|max +There are also some command line parameters for enabling the out-of-band +monitoring of branch ratio on cores doing busy polling via PMDs. + + .. code-block:: console + + --core-list {list of cores} + + When this parameter is used, the list of cores specified will monitor the ratio + between branch hits and branch misses. A tightly polling PMD thread will have a + very low branch ratio, so the core frequency will be scaled down to the minimim + allowed value. When packets are received, the code path will alter, causing the + branch ratio to increase. When the ratio goes above the ratio threshold, the + core frequency will be scaled up to the maximum allowed value. + + .. code-block:: console + + --branch-ratio {ratio} + + The branch ratio is a floating point number that specifies the threshold at which + to scale up or down for the given workload. The default branch ratio is 0.01, + and will need to be adjusted for different workloads. + + Compiling and Running the Guest Applications -------------------------------------------- -For compiling and running l3fwd-power, see :doc:`l3_forward_power_man`. +l3fwd-power is one sample application that can be used with vm_power_manager. A guest CLI is also provided for validating the setup. For both l3fwd-power and guest CLI, the channels for the VM must be monitored by the -host application using the *add_channels* command on the host. +host application using the *add_channels* command on the host. This typically uses +the following commands in the host application: + +.. code-block:: console + + vm_power> add_vm vmname + vm_power> add_channels vmname all + vm_power> set_channel_status vmname all enabled + vm_power> show_vm vmname + Compiling ~~~~~~~~~ -#. export RTE_SDK=/path/to/rte_sdk -#. cd ${RTE_SDK}/examples/vm_power_manager/guest_cli -#. make +For information on compiling DPDK and the sample applications +see :doc:`compiling`. + +For compiling and running l3fwd-power, see :doc:`l3_forward_power_man`. + +The application is located in the ``guest_cli`` sub-directory under ``vm_power_manager``. + +To build just the ``guest_vm_power_manager`` application: + +.. code-block:: console + + export RTE_SDK=/path/to/rte_sdk + export RTE_TARGET=build + cd ${RTE_SDK}/examples/vm_power_manager/guest_cli/ + make Running ~~~~~~~ -The application does not have any specific command line options other than *EAL*: +The standard *EAL* command line parameters are required: .. code-block:: console - ./build/vm_power_mgr [EAL options] + ./build/guest_vm_power_mgr [EAL options] -- [guest options] -The application for example purposes uses a channel for each lcore enabled, -for example to run on cores 0,1,2,3 on a system with 4 memory channels: +The guest example uses a channel for each lcore enabled. For example, +to run on cores 0,1,2,3: .. code-block:: console - ./build/guest_vm_power_mgr -l 0-3 -n 4 + ./build/guest_vm_power_mgr -l 0-3 + +Optionally, there is a list of command line parameter should the user wish to send a power +policy down to the host application. These parameters are as follows: + + .. code-block:: console + + --vm-name {name of guest vm} + + This parameter allows the user to change the Virtual Machine name passed down to the + host application via the power policy. The default is "ubuntu2" + + .. code-block:: console + + --vcpu-list {list vm cores} + + A comma-separated list of cores in the VM that the user wants the host application to + monitor. The list of cores in any vm starts at zero, and these are mapped to the + physical cores by the host application once the policy is passed down. + Valid syntax includes individial cores '2,3,4', or a range of cores '2-4', or a + combination of both '1,3,5-7' + + .. code-block:: console + + --busy-hours {list of busy hours} + + A comma-separated list of hours within which to set the core frequency to maximum. + Valid syntax includes individial hours '2,3,4', or a range of hours '2-4', or a + combination of both '1,3,5-7'. Valid hours are 0 to 23. + + .. code-block:: console + + --quiet-hours {list of quiet hours} + + A comma-separated list of hours within which to set the core frequency to minimum. + Valid syntax includes individial hours '2,3,4', or a range of hours '2-4', or a + combination of both '1,3,5-7'. Valid hours are 0 to 23. + + .. code-block:: console + + --policy {policy type} + + The type of policy. This can be one of the following values: + TRAFFIC - based on incoming traffic rates on the NIC. + TIME - busy/quiet hours policy. + BRANCH_RATIO - uses branch ratio counters to determine core busyness. + Not all parameters are needed for all policy types. For example, BRANCH_RATIO + only needs the vcpu-list parameter, not any of the hours. After successful initialization the user is presented with VM Power Manager Guest CLI: @@ -333,3 +451,20 @@ Where {core_num} is the lcore and channel to change frequency by scaling up/down .. code-block:: console set_cpu_freq {core_num} up|down|min|max + +To start the application and configure the power policy, and send it to the host: + +.. code-block:: console + + ./build/guest_vm_power_mgr -l 0-3 -n 4 -- --vm-name=ubuntu --policy=BRANCH_RATIO --vcpu-list=2-4 + +Once the VM Power Manager Guest CLI appears, issuing the 'send_policy now' command +will send the policy to the host: + +.. code-block:: console + + send_policy now + +Once the policy is sent to the host, the host application takes over the power monitoring +of the specified cores in the policy. + diff --git a/doc/guides/sample_app_ug/vmdq_dcb_forwarding.rst b/doc/guides/sample_app_ug/vmdq_dcb_forwarding.rst index 83fcdf63..0e9da970 100644 --- a/doc/guides/sample_app_ug/vmdq_dcb_forwarding.rst +++ b/doc/guides/sample_app_ug/vmdq_dcb_forwarding.rst @@ -102,10 +102,6 @@ a default structure is provided for VMDQ and DCB configuration to be filled in l .rxmode = { .mq_mode = ETH_MQ_RX_VMDQ_DCB, .split_hdr_size = 0, - .header_split = 0, /**< Header Split disabled */ - .hw_ip_checksum = 0, /**< IP checksum offload disabled */ - .hw_vlan_filter = 0, /**< VLAN filtering disabled */ - .jumbo_frame = 0, /**< Jumbo Frame Support disabled */ }, .txmode = { .mq_mode = ETH_MQ_TX_VMDQ_DCB, |
