[dpdk-dev] [PATCH 1/3] examples/skeleton: minor refactoring to help documentation

[John McNamara]

Minor refactoring and comments to make the sample app and
code examples clearer for the sample app guide.

Signed-off-by: John McNamara <john.mcnamara at intel.com>
---
 examples/skeleton/basicfwd.c |   77 +++++++++++++++++++++++++++++++-----------
 1 files changed, 57 insertions(+), 20 deletions(-)

diff --git a/examples/skeleton/basicfwd.c b/examples/skeleton/basicfwd.c
index 6aa931e..1bce6e7 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;
 }
-- 
1.7.4.1