[dpdk-dev] [PATCH v4 1/6] eventdev: introduce event driven programming model

[Eads, Gage]

>  -----Original Message-----
>  From: Richardson, Bruce
>  Sent: Wednesday, January 25, 2017 10:36 AM
>  To: Eads, Gage <gage.eads at intel.com>; Jerin Jacob
>  <jerin.jacob at caviumnetworks.com>; dev at dpdk.org
>  Cc: thomas.monjalon at 6wind.com; hemant.agrawal at nxp.com; Van Haaren,
>  Harry <harry.van.haaren at intel.com>; McDaniel, Timothy
>  <timothy.mcdaniel at intel.com>
>  Subject: RE: [dpdk-dev] [PATCH v4 1/6] eventdev: introduce event driven
>  programming model
>  
>  
>  
>  > -----Original Message-----
>  > From: Eads, Gage
>  > Sent: Wednesday, January 25, 2017 4:32 PM
>  > To: Jerin Jacob <jerin.jacob at caviumnetworks.com>; dev at dpdk.org
>  > Cc: thomas.monjalon at 6wind.com; Richardson, Bruce
>  > <bruce.richardson at intel.com>; hemant.agrawal at nxp.com; Van Haaren,
>  > Harry <harry.van.haaren at intel.com>; McDaniel, Timothy
>  > <timothy.mcdaniel at intel.com>
>  > Subject: RE: [dpdk-dev] [PATCH v4 1/6] eventdev: introduce event
>  > driven programming model
>  >
>  > Hi Jerin,
>  >
>  > See the bottom of this email for a proposed tweak to the
>  > rte_event_enqueue_burst() return value.
>  >
>  > >  -----Original Message-----
>  > >  From: Jerin Jacob [mailto:jerin.jacob at caviumnetworks.com]
>  > >  Sent: Wednesday, December 21, 2016 3:25 AM
>  > >  To: dev at dpdk.org
>  > >  Cc: thomas.monjalon at 6wind.com; Richardson, Bruce
>  > > <bruce.richardson at intel.com>; hemant.agrawal at nxp.com; Eads, Gage
>  > > <gage.eads at intel.com>; Van Haaren, Harry
>  > > <harry.van.haaren at intel.com>; Jerin Jacob
>  > > <jerin.jacob at caviumnetworks.com>
>  > >  Subject: [dpdk-dev] [PATCH v4 1/6] eventdev: introduce event driven
>  > > programming model
>  > >
>  <message truncated for brevity>
>  > >  +/**
>  > >  + * Enqueue a burst of events objects or an event object supplied
>  > > in
>  > >  *rte_event*
>  > >  + * structure on an  event device designated by its *dev_id*
>  > > through the event  + * port specified by *port_id*. Each event
>  > > object specifies the event queue on  + * which it will be enqueued.
>  > >  + *
>  > >  + * The *nb_events* parameter is the number of event objects to
>  > > enqueue  which are  + * supplied in the *ev* array of *rte_event*
>  > > structure.
>  > >  + *
>  > >  + * The rte_event_enqueue_burst() function returns the number of  +
>  > > * events objects it actually enqueued. A return value equal to
>  > > *nb_events*  + * means that all event objects have been enqueued.
>  > >  + *
>  > >  + * @param dev_id
>  > >  + *   The identifier of the device.
>  > >  + * @param port_id
>  > >  + *   The identifier of the event port.
>  > >  + * @param ev
>  > >  + *   Points to an array of *nb_events* objects of type *rte_event*
>  > structure
>  > >  + *   which contain the event object enqueue operations to be
>  > processed.
>  > >  + * @param nb_events
>  > >  + *   The number of event objects to enqueue, typically number of
>  > >  + *   rte_event_port_enqueue_depth() available for this port.
>  > >  + *
>  > >  + * @return
>  > >  + *   The number of event objects actually enqueued on the event
>  > device. The
>  > >  + *   return value can be less than the value of the *nb_events*
>  > parameter
>  > >  when
>  > >  + *   the event devices queue is full or if invalid parameters are
>  > specified in a
>  > >  + *   *rte_event*. If return value is less than *nb_events*, the
>  > remaining events
>  > >  + *   at the end of ev[] are not consumed,and the caller has to take
>  > care of
>  > >  them
>  > >  + *
>  > >  + * @see rte_event_port_enqueue_depth()  + */  +uint16_t
>  > > +rte_event_enqueue_burst(uint8_t dev_id, uint8_t port_id,
>  > >  +			const struct rte_event ev[], uint16_t nb_events);
>  >
>  > There are a number of reasons this operation could fail to enqueue all
>  > the events, including:
>  > - Backpressure
>  > - Invalid port ID
>  > - Invalid queue ID
>  > - Invalid sched type when a queue is configured for ATOMIC_ONLY,
>  > ORDERED_ONLY, or PARALLEL_ONLY
>  > - ...
>  >
>  > The current API doesn't provide a straightforward way to determine the
>  > cause of a failure. This is a particular issue on event PMDs that can
>  > backpressure, where the app may want to treat that case differently
>  > than the other failure cases.
>  >
>  > Could we change the return type to int16_t, and define a set of error
>  > cases (e.g. -ENOSPC for backpressure, -EINVAL for an invalid argument)?
>  > (With corresponding changes needed in the PMD API) Similarly we could
>  > change rte_event_dequeue_burst() to return an int16_t, with -EINVAL as
>  > a possible error case.
>  
>  Use rte_errno instead, I suggest. That's what it's there for.
>  
>  /Bruce

That makes sense. In that case, the API comment could be tweaked like so:

  * If the return value is less than *nb_events*, the remaining events at the
  * end of ev[] are not consumed and the caller has to take care of them, and
  * rte_errno is set accordingly. Possible errno values include:
  * - EINVAL - The port ID is invalid, an event's queue ID is invalid, or an
  *            event's sched type doesn't match the capabilities of the
  *            destination queue.
  * - ENOSPC - The event port was backpressured and unable to enqueue one or
  *            more events.