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

  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@intel.com>
---
 examples/skeleton/basicfwd.c |   77 +++++++++++++++++++++++++++++++-----------
 1 files changed, 57 insertions(+), 20 deletions(-)
  

> -----Original Message-----
> From: dev [mailto:dev-bounces@dpdk.org] On Behalf Of John McNamara
> Sent: Wednesday, February 25, 2015 7:46 PM
> To: dev@dpdk.org
> Subject: [dpdk-dev] [PATCH 1/3] examples/skeleton: minor refactoring to
> help documentation
> 
> 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@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
Acked-by: Siobhan Butler <siobhan.a.butler@intel.com>