From: John McNamara Date: Wed, 25 Feb 2015 19:46:00 +0000 (+0000) Subject: examples/skeleton: improve documentation X-Git-Tag: spdx-start~9427 X-Git-Url: http://git.droids-corp.org/?a=commitdiff_plain;h=0f91352cff9a793805f5144f9589ffe211876b34;p=dpdk.git examples/skeleton: improve documentation Minor refactoring and comments to make the sample app and code examples clearer for the sample app guide. Signed-off-by: John McNamara Acked-by: Siobhan Butler Acked-by: Pablo de Lara --- diff --git a/examples/skeleton/basicfwd.c b/examples/skeleton/basicfwd.c index 6aa931e2c1..1bce6e779f 100644 --- a/examples/skeleton/basicfwd.c +++ b/examples/skeleton/basicfwd.c @@ -1,7 +1,7 @@ /*- * BSD LICENSE * - * Copyright(c) 2010-2014 Intel Corporation. All rights reserved. + * Copyright(c) 2010-2015 Intel Corporation. All rights reserved. * All rights reserved. * * Redistribution and use in source and binary forms, with or without @@ -48,12 +48,14 @@ #define BURST_SIZE 32 static const struct rte_eth_conf port_conf_default = { - .rxmode = { .max_rx_pkt_len = ETHER_MAX_LEN, }, + .rxmode = { .max_rx_pkt_len = ETHER_MAX_LEN } }; +/* basicfwd.c: Basic DPDK skeleton forwarding example. */ + /* - * Initialises a given port using global settings and with the rx buffers - * coming from the mbuf_pool passed as parameter + * Initializes a given port using global settings and with the RX buffers + * coming from the mbuf_pool passed as a parameter. */ static inline int port_init(uint8_t port, struct rte_mempool *mbuf_pool) @@ -66,10 +68,12 @@ port_init(uint8_t port, struct rte_mempool *mbuf_pool) if (port >= rte_eth_dev_count()) return -1; + /* Configure the Ethernet device. */ retval = rte_eth_dev_configure(port, rx_rings, tx_rings, &port_conf); if (retval != 0) return retval; + /* Allocate and set up 1 RX queue per Ethernet port. */ for (q = 0; q < rx_rings; q++) { retval = rte_eth_rx_queue_setup(port, q, RX_RING_SIZE, rte_eth_dev_socket_id(port), NULL, mbuf_pool); @@ -77,6 +81,7 @@ port_init(uint8_t port, struct rte_mempool *mbuf_pool) return retval; } + /* Allocate and set up 1 TX queue per Ethernet port. */ for (q = 0; q < tx_rings; q++) { retval = rte_eth_tx_queue_setup(port, q, TX_RING_SIZE, rte_eth_dev_socket_id(port), NULL); @@ -84,33 +89,41 @@ port_init(uint8_t port, struct rte_mempool *mbuf_pool) return retval; } - retval = rte_eth_dev_start(port); + /* Start the Ethernet port. */ + retval = rte_eth_dev_start(port); if (retval < 0) return retval; + /* Display the port MAC address. */ struct ether_addr addr; rte_eth_macaddr_get(port, &addr); - printf("Port %u MAC: %02"PRIx8" %02"PRIx8" %02"PRIx8 - " %02"PRIx8" %02"PRIx8" %02"PRIx8"\n", + printf("Port %u MAC: %02" PRIx8 " %02" PRIx8 " %02" PRIx8 + " %02" PRIx8 " %02" PRIx8 " %02" PRIx8 "\n", (unsigned)port, addr.addr_bytes[0], addr.addr_bytes[1], addr.addr_bytes[2], addr.addr_bytes[3], addr.addr_bytes[4], addr.addr_bytes[5]); + /* Enable RX in promiscuous mode for the Ethernet device. */ rte_eth_promiscuous_enable(port); return 0; } /* - * Main thread that does the work, reading from INPUT_PORT - * and writing to OUTPUT_PORT + * The lcore main. This is the main thread that does the work, reading from + * an input port and writing to an output port. */ -static __attribute__((noreturn)) void +static __attribute__((noreturn)) void lcore_main(void) { const uint8_t nb_ports = rte_eth_dev_count(); uint8_t port; + + /* + * Check that the port is on the same NUMA node as the polling thread + * for best performance. + */ for (port = 0; port < nb_ports; port++) if (rte_eth_dev_socket_id(port) > 0 && rte_eth_dev_socket_id(port) != @@ -121,15 +134,28 @@ lcore_main(void) printf("\nCore %u forwarding packets. [Ctrl+C to quit]\n", rte_lcore_id()); + + /* Run until the application is quit or killed. */ for (;;) { + /* + * Receive packets on a port and forward them on the paired + * port. The mapping is 0 -> 1, 1 -> 0, 2 -> 3, 3 -> 2, etc. + */ for (port = 0; port < nb_ports; port++) { + + /* Get burst of RX packets, from first port of pair. */ struct rte_mbuf *bufs[BURST_SIZE]; const uint16_t nb_rx = rte_eth_rx_burst(port, 0, bufs, BURST_SIZE); + if (unlikely(nb_rx == 0)) continue; + + /* Send burst of TX packets, to second port of pair. */ const uint16_t nb_tx = rte_eth_tx_burst(port ^ 1, 0, bufs, nb_rx); + + /* Free any unsent packets. */ if (unlikely(nb_tx < nb_rx)) { uint16_t buf; for (buf = nb_tx; buf < nb_rx; buf++) @@ -139,7 +165,10 @@ lcore_main(void) } } -/* Main function, does initialisation and calls the per-lcore functions */ +/* + * The main function, which does initialization and calls the per-lcore + * functions. + */ int main(int argc, char *argv[]) { @@ -147,36 +176,44 @@ main(int argc, char *argv[]) unsigned nb_ports; uint8_t portid; - /* init EAL */ + /* Initialize the Environment Abstraction Layer (EAL). */ int ret = rte_eal_init(argc, argv); if (ret < 0) rte_exit(EXIT_FAILURE, "Error with EAL initialization\n"); + argc -= ret; argv += ret; + /* Check that there is an even number of ports to send/receive on. */ nb_ports = rte_eth_dev_count(); if (nb_ports < 2 || (nb_ports & 1)) rte_exit(EXIT_FAILURE, "Error: number of ports must be even\n"); - mbuf_pool = rte_mempool_create("MBUF_POOL", NUM_MBUFS * nb_ports, - MBUF_SIZE, MBUF_CACHE_SIZE, + /* Creates a new mempool in memory to hold the mbufs. */ + mbuf_pool = rte_mempool_create("MBUF_POOL", + NUM_MBUFS * nb_ports, + MBUF_SIZE, + MBUF_CACHE_SIZE, sizeof(struct rte_pktmbuf_pool_private), rte_pktmbuf_pool_init, NULL, - rte_pktmbuf_init, NULL, - rte_socket_id(), 0); + rte_pktmbuf_init, NULL, + rte_socket_id(), + 0); + if (mbuf_pool == NULL) rte_exit(EXIT_FAILURE, "Cannot create mbuf pool\n"); - /* initialize all ports */ + /* Initialize all ports. */ for (portid = 0; portid < nb_ports; portid++) if (port_init(portid, mbuf_pool) != 0) - rte_exit(EXIT_FAILURE, "Cannot init port %"PRIu8"\n", + rte_exit(EXIT_FAILURE, "Cannot init port %"PRIu8 "\n", portid); if (rte_lcore_count() > 1) - printf("\nWARNING: Too much enabled lcores - App uses only 1 lcore\n"); + printf("\nWARNING: Too many lcores enabled. Only 1 used.\n"); - /* call lcore_main on master core only */ + /* Call lcore_main on the master core only. */ lcore_main(); + return 0; }