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

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

On Fri, Mar 17, 2017 at 05:52:28PM +0530, Jerin Jacob wrote:
> 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>

Applied to dpdk-next-eventdev/master. Thanks.

> 
> > 
> > ---
> > 
> > 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
> >