Re: [dpdk-dev] [PATCH v4 04/17] eventdev: add APIs for extended stats

[Jerin Jacob <jerin.jacob@caviumnetworks.com>]

On Fri, Mar 10, 2017 at 07:43:19PM +0000, Harry van Haaren wrote:
> From: Bruce Richardson <bruce.richardson@intel.com>
> 
> Add in APIs for extended stats so that eventdev implementations can report
> out information on their internal state. The APIs are based on, but not
> identical to, the equivalent ethdev functions.
> 
> Signed-off-by: Bruce Richardson <bruce.richardson@intel.com>
> Signed-off-by: Harry van Haaren <harry.van.haaren@intel.com>

Acked-by: Jerin Jacob <jerin.jacob@caviumnetworks.com>

> 
> ---
> 
> v3 -> v4:
> - xstats API reset allows selection of device/port/queue to reset
> ---
>  lib/librte_eventdev/rte_eventdev.c           |  83 ++++++++++++++++
>  lib/librte_eventdev/rte_eventdev.h           | 142 +++++++++++++++++++++++++++
>  lib/librte_eventdev/rte_eventdev_pmd.h       |  74 ++++++++++++++
>  lib/librte_eventdev/rte_eventdev_version.map |   4 +
>  4 files changed, 303 insertions(+)
> 
> diff --git a/lib/librte_eventdev/rte_eventdev.c b/lib/librte_eventdev/rte_eventdev.c
> index 68bfc3b..0280ef0 100644
> --- a/lib/librte_eventdev/rte_eventdev.c
> +++ b/lib/librte_eventdev/rte_eventdev.c
> @@ -920,6 +920,89 @@ rte_event_dev_dump(uint8_t dev_id, FILE *f)
>  
>  }
>  
> +static int
> +xstats_get_count(uint8_t dev_id, enum rte_event_dev_xstats_mode mode,
> +		uint8_t queue_port_id)
> +{
> +	struct rte_eventdev *dev = &rte_eventdevs[dev_id];
> +	if (dev->dev_ops->xstats_get_names != NULL)
> +		return (*dev->dev_ops->xstats_get_names)(dev, mode,
> +							queue_port_id,
> +							NULL, NULL, 0);
> +	return 0;
> +}
> +
> +int
> +rte_event_dev_xstats_names_get(uint8_t dev_id,
> +		enum rte_event_dev_xstats_mode mode, uint8_t queue_port_id,
> +		struct rte_event_dev_xstats_name *xstats_names,
> +		unsigned int *ids, unsigned int size)
> +{
> +	RTE_EVENTDEV_VALID_DEVID_OR_ERR_RET(dev_id, -ENODEV);
> +	const int cnt_expected_entries = xstats_get_count(dev_id, mode,
> +							  queue_port_id);
> +	if (xstats_names == NULL || cnt_expected_entries < 0 ||
> +			(int)size < cnt_expected_entries)
> +		return cnt_expected_entries;
> +
> +	/* dev_id checked above */
> +	const struct rte_eventdev *dev = &rte_eventdevs[dev_id];
> +
> +	if (dev->dev_ops->xstats_get_names != NULL)
> +		return (*dev->dev_ops->xstats_get_names)(dev, mode,
> +				queue_port_id, xstats_names, ids, size);
> +
> +	return -ENOTSUP;
> +}
> +
> +/* retrieve eventdev extended statistics */
> +int
> +rte_event_dev_xstats_get(uint8_t dev_id, enum rte_event_dev_xstats_mode mode,
> +		uint8_t queue_port_id, const unsigned int ids[],
> +		uint64_t values[], unsigned int n)
> +{
> +	RTE_EVENTDEV_VALID_DEVID_OR_ERR_RET(dev_id, -ENODEV);
> +	const struct rte_eventdev *dev = &rte_eventdevs[dev_id];
> +
> +	/* implemented by the driver */
> +	if (dev->dev_ops->xstats_get != NULL)
> +		return (*dev->dev_ops->xstats_get)(dev, mode, queue_port_id,
> +				ids, values, n);
> +	return -ENOTSUP;
> +}
> +
> +uint64_t
> +rte_event_dev_xstats_by_name_get(uint8_t dev_id, const char *name,
> +		unsigned int *id)
> +{
> +	RTE_EVENTDEV_VALID_DEVID_OR_ERR_RET(dev_id, 0);
> +	const struct rte_eventdev *dev = &rte_eventdevs[dev_id];
> +	unsigned int temp = -1;
> +
> +	if (id != NULL)
> +		*id = (unsigned int)-1;
> +	else
> +		id = &temp; /* ensure driver never gets a NULL value */
> +
> +	/* implemented by driver */
> +	if (dev->dev_ops->xstats_get_by_name != NULL)
> +		return (*dev->dev_ops->xstats_get_by_name)(dev, name, id);
> +	return -ENOTSUP;
> +}
> +
> +int rte_event_dev_xstats_reset(uint8_t dev_id,
> +		enum rte_event_dev_xstats_mode mode, int16_t queue_port_id,
> +		const uint32_t ids[], uint32_t nb_ids)
> +{
> +	RTE_EVENTDEV_VALID_DEVID_OR_ERR_RET(dev_id, -EINVAL);
> +	struct rte_eventdev *dev = &rte_eventdevs[dev_id];
> +
> +	if (dev->dev_ops->xstats_reset != NULL)
> +		return (*dev->dev_ops->xstats_reset)(dev, mode, queue_port_id,
> +							ids, nb_ids);
> +	return -ENOTSUP;
> +}
> +
>  int
>  rte_event_dev_start(uint8_t dev_id)
>  {
> diff --git a/lib/librte_eventdev/rte_eventdev.h b/lib/librte_eventdev/rte_eventdev.h
> index 4876353..d462047 100644
> --- a/lib/librte_eventdev/rte_eventdev.h
> +++ b/lib/librte_eventdev/rte_eventdev.h
> @@ -1405,6 +1405,148 @@ rte_event_port_links_get(uint8_t dev_id, uint8_t port_id,
>  int
>  rte_event_dev_dump(uint8_t dev_id, FILE *f);
>  
> +/** Maximum name length for extended statistics counters */
> +#define RTE_EVENT_DEV_XSTATS_NAME_SIZE 64
> +
> +/**
> + * Selects the component of the eventdev to retrieve statistics from.
> + */
> +enum rte_event_dev_xstats_mode {
> +	RTE_EVENT_DEV_XSTATS_DEVICE,
> +	RTE_EVENT_DEV_XSTATS_PORT,
> +	RTE_EVENT_DEV_XSTATS_QUEUE,
> +};
> +
> +/**
> + * A name-key lookup element for extended statistics.
> + *
> + * This structure is used to map between names and ID numbers
> + * for extended ethdev statistics.
> + */
> +struct rte_event_dev_xstats_name {
> +	char name[RTE_EVENT_DEV_XSTATS_NAME_SIZE];
> +};
> +
> +/**
> + * Retrieve names of extended statistics of an event device.
> + *
> + * @param dev_id
> + *   The identifier of the event device.
> + * @param mode
> + *   The mode of statistics to retrieve. Choices include the device statistics,
> + *   port statistics or queue statistics.
> + * @param queue_port_id
> + *   Used to specify the port or queue number in queue or port mode, and is
> + *   ignored in device mode.
> + * @param[out] xstats_names
> + *   Block of memory to insert names into. Must be at least size in capacity.
> + *   If set to NULL, function returns required capacity.
> + * @param[out] ids
> + *   Block of memory to insert ids into. Must be at least size in capacity.
> + *   If set to NULL, function returns required capacity. The id values returned
> + *   can be passed to *rte_event_dev_xstats_get* to select statistics.
> + * @param size
> + *   Capacity of xstats_names (number of names).
> + * @return
> + *   - positive value lower or equal to size: success. The return value
> + *     is the number of entries filled in the stats table.
> + *   - positive value higher than size: error, the given statistics table
> + *     is too small. The return value corresponds to the size that should
> + *     be given to succeed. The entries in the table are not valid and
> + *     shall not be used by the caller.
> + *   - negative value on error:
> + *        -ENODEV for invalid *dev_id*
> + *        -EINVAL for invalid mode, queue port or id parameters
> + *        -ENOTSUP if the device doesn't support this function.
> + */
> +int
> +rte_event_dev_xstats_names_get(uint8_t dev_id,
> +			       enum rte_event_dev_xstats_mode mode,
> +			       uint8_t queue_port_id,
> +			       struct rte_event_dev_xstats_name *xstats_names,
> +			       unsigned int *ids,
> +			       unsigned int size);
> +
> +/**
> + * Retrieve extended statistics of an event device.
> + *
> + * @param dev_id
> + *   The identifier of the device.
> + * @param mode
> + *  The mode of statistics to retrieve. Choices include the device statistics,
> + *  port statistics or queue statistics.
> + * @param queue_port_id
> + *   Used to specify the port or queue number in queue or port mode, and is
> + *   ignored in device mode.
> + * @param ids
> + *   The id numbers of the stats to get. The ids can be got from the stat
> + *   position in the stat list from rte_event_dev_get_xstats_names(), or
> + *   by using rte_eventdev_get_xstats_by_name()
> + * @param[out] values
> + *   The values for each stats request by ID.
> + * @param n
> + *   The number of stats requested
> + * @return
> + *   - positive value: number of stat entries filled into the values array
> + *   - negative value on error:
> + *        -ENODEV for invalid *dev_id*
> + *        -EINVAL for invalid mode, queue port or id parameters
> + *        -ENOTSUP if the device doesn't support this function.
> + */
> +int
> +rte_event_dev_xstats_get(uint8_t dev_id,
> +			 enum rte_event_dev_xstats_mode mode,
> +			 uint8_t queue_port_id,
> +			 const unsigned int ids[],
> +			 uint64_t values[], unsigned int n);
> +
> +/**
> + * Retrieve the value of a single stat by requesting it by name.
> + *
> + * @param dev_id
> + *   The identifier of the device
> + * @param name
> + *   The stat name to retrieve
> + * @param[out] id
> + *   If non-NULL, the numerical id of the stat will be returned, so that further
> + *   requests for the stat can be got using rte_eventdev_xstats_get, which will
> + *   be faster as it doesn't need to scan a list of names for the stat.
> + *   If the stat cannot be found, the id returned will be (unsigned)-1.
> + * @return
> + *   - positive value or zero: the stat value
> + *   - negative value: -EINVAL if stat not found, -ENOTSUP if not supported.
> + */
> +uint64_t
> +rte_event_dev_xstats_by_name_get(uint8_t dev_id, const char *name,
> +				 unsigned int *id);
> +
> +/**
> + * Reset the values of the xstats of the selected component in the device.
> + *
> + * @param dev_id
> + *   The identifier of the device
> + * @param mode
> + *   The mode of the statistics to reset. Choose from device, queue or port.
> + * @param queue_port_id
> + *   The queue or port to reset. 0 and positive values select ports and queues,
> + *   while -1 indicates all ports or queues.
> + * @param ids
> + *   Selects specific statistics to be reset. When NULL, all statistics selected
> + *   by *mode* will be reset. If non-NULL, must point to array of at least
> + *   *nb_ids* size.
> + * @param nb_ids
> + *   The number of ids available from the *ids* array. Ignored when ids is NULL.
> + * @return
> + *   - zero: successfully reset the statistics to zero
> + *   - negative value: -EINVAL invalid parameters, -ENOTSUP if not supported.
> + */
> +int
> +rte_event_dev_xstats_reset(uint8_t dev_id,
> +			   enum rte_event_dev_xstats_mode mode,
> +			   int16_t queue_port_id,
> +			   const uint32_t ids[],
> +			   uint32_t nb_ids);
> +
>  #ifdef __cplusplus
>  }
>  #endif
> diff --git a/lib/librte_eventdev/rte_eventdev_pmd.h b/lib/librte_eventdev/rte_eventdev_pmd.h
> index 828dfce..86e0076 100644
> --- a/lib/librte_eventdev/rte_eventdev_pmd.h
> +++ b/lib/librte_eventdev/rte_eventdev_pmd.h
> @@ -421,6 +421,71 @@ typedef void (*eventdev_dequeue_timeout_ticks_t)(struct rte_eventdev *dev,
>   */
>  typedef void (*eventdev_dump_t)(struct rte_eventdev *dev, FILE *f);
>  
> +/**
> + * Retrieve a set of statistics from device
> + *
> + * @param dev
> + *   Event device pointer
> + * @param ids
> + *   The stat ids to retrieve
> + * @param values
> + *   The returned stat values
> + * @param n
> + *   The number of id values and entries in the values array
> + * @return
> + *   The number of stat values successfully filled into the values array
> + */
> +typedef int (*eventdev_xstats_get_t)(const struct rte_eventdev *dev,
> +		enum rte_event_dev_xstats_mode mode, uint8_t queue_port_id,
> +		const unsigned int ids[], uint64_t values[], unsigned int n);
> +
> +/**
> + * Resets the statistic values in xstats for the device, based on mode.
> + */
> +typedef int (*eventdev_xstats_reset_t)(struct rte_eventdev *dev,
> +		enum rte_event_dev_xstats_mode mode,
> +		int16_t queue_port_id,
> +		const uint32_t ids[],
> +		uint32_t nb_ids);
> +
> +/**
> + * Get names of extended stats of an event device
> + *
> + * @param dev
> + *   Event device pointer
> + * @param xstats_names
> + *   Array of name values to be filled in
> + * @param size
> + *   Number of values in the xstats_names array
> + * @return
> + *   When size >= the number of stats, return the number of stat values filled
> + *   into the array.
> + *   When size < the number of available stats, return the number of stats
> + *   values, and do not fill in any data into xstats_names.
> + */
> +typedef int (*eventdev_xstats_get_names_t)(const struct rte_eventdev *dev,
> +		enum rte_event_dev_xstats_mode mode, uint8_t queue_port_id,
> +		struct rte_event_dev_xstats_name *xstats_names,
> +		unsigned int *ids, unsigned int size);
> +
> +/**
> + * Get value of one stats and optionally return its id
> + *
> + * @param dev
> + *   Event device pointer
> + * @param name
> + *   The name of the stat to retrieve
> + * @param id
> + *   Pointer to an unsigned int where we store the stat-id for future reference.
> + *   This pointer may be null if the id is not required.
> + * @return
> + *   The value of the stat, or (uint64_t)-1 if the stat is not found.
> + *   If the stat is not found, the id value will be returned as (unsigned)-1,
> + *   if id pointer is non-NULL
> + */
> +typedef uint64_t (*eventdev_xstats_get_by_name)(const struct rte_eventdev *dev,
> +		const char *name, unsigned int *id);
> +
>  /** Event device operations function pointer table */
>  struct rte_eventdev_ops {
>  	eventdev_info_get_t dev_infos_get;	/**< Get device info. */
> @@ -451,6 +516,15 @@ struct rte_eventdev_ops {
>  	/**< Converts ns to *timeout_ticks* value for rte_event_dequeue() */
>  	eventdev_dump_t dump;
>  	/* Dump internal information */
> +
> +	eventdev_xstats_get_t xstats_get;
> +	/**< Get extended device statistics. */
> +	eventdev_xstats_get_names_t xstats_get_names;
> +	/**< Get names of extended stats. */
> +	eventdev_xstats_get_by_name xstats_get_by_name;
> +	/**< Get one value by name. */
> +	eventdev_xstats_reset_t xstats_reset;
> +	/**< Reset the statistics values in xstats. */
>  };
>  
>  /**
> diff --git a/lib/librte_eventdev/rte_eventdev_version.map b/lib/librte_eventdev/rte_eventdev_version.map
> index 7a6921c..1fa6b33 100644
> --- a/lib/librte_eventdev/rte_eventdev_version.map
> +++ b/lib/librte_eventdev/rte_eventdev_version.map
> @@ -12,6 +12,10 @@ DPDK_17.05 {
>  	rte_event_dev_stop;
>  	rte_event_dev_close;
>  	rte_event_dev_dump;
> +	rte_event_dev_xstats_by_name_get;
> +	rte_event_dev_xstats_get;
> +	rte_event_dev_xstats_names_get;
> +	rte_event_dev_xstats_reset;
>  
>  	rte_event_port_default_conf_get;
>  	rte_event_port_setup;
> -- 
> 2.7.4
>