rte_event_timer_adapter.h

       Generated automatically by Doxygen for DPDK from the source code.

DPDK                                             Version 24.11.2                    rte_event_timer_adapter.h(3)

       RTE Event Timer Adapter

       An event timer adapter has the following abstract working model:

                                 timer_tick_ns
                                     +
                        +-------+    |
                        |       |    |
                +-------+ bkt 0 +----v---+
                |       |       |        |
                |       +-------+        |
            +---+---+                +---+---+  +---+---+---+---+
            |       |                |       |  |   |   |   |   |
            | bkt n |                | bkt 1 |<-> t0| t1| t2| tn|
            |       |                |       |  |   |   |   |   |
            +---+---+                +---+---+  +---+---+---+---+
                |     Timer adapter      |
            +---+---+                +---+---+
            |       |                |       |
            | bkt 4 |                | bkt 2 |<--- Current bucket
            |       |                |       |
            +---+---+                +---+---+
                 |      +-------+       |
                 |      |       |       |
                 +------+ bkt 3 +-------+
                        |       |
                        +-------+

       • It   has   a   virtual   monotonically   increasing   64-bit   timer   adapter   clock  based  on  enumrte_event_timer_adapter_clk_src clock source. The clock source could be a  CPU  clock,  or  a  platform
         dependent external clock.

       • The application creates a timer adapter instance with given the clock source, the total number of event
         timers, and a resolution(expressed in ns) to traverse between the buckets.

       • Each  timer  adapter  may  have  0  to  n  buckets  based on the configured max timeout(max_tmo_ns) and
         resolution(timer_tick_ns). Upon starting the timer adapter, the adapter starts ticking at timer_tick_ns
         resolution.

       • The application arms an event timer that will expire timer_tick_ns from now.

       • The application can cancel an armed timer and no timer expiry event will be generated.

       • If a timer expires then the library injects the timer expiry event in the designated event queue.

       • The timer expiry event will be received through rte_event_dequeue_burst.

       • The application frees the timer adapter instance.

       Multiple timer adapters can be created with a varying level of resolution for various  expiry  use  cases
       that run in parallel.

       Before  using  the  timer adapter, the application has to create and configure an event device along with
       the event port. Based on the event device capability it might require creating an additional  event  port
       to be used by the timer adapter.

       The  application  creates  the  event timer adapter using the rte_event_timer_adapter_create().Theeventdeviceidispassedtothisfunction,insidethisfunctiontheeventdevicecapabilityischecked,andifanin-builtportisabsenttheapplicationusesthedefaultfunctiontocreateanewproducerport.

       The application may also use the function rte_event_timer_adapter_create_ext()tohavegranularcontroloverproducerportcreationinacasewherethein-builtportisabsent.

       After  creating the timer adapter, the application has to start it using rte_event_timer_adapter_start().Thebucketsaretraversedfrom0ton;whentheadapterticks,thenextbucketisvisited.Eachtime,thelistperbucketisprocessed,andtimerexpiryeventsaresenttothedesignatedeventqueue.

       The application can arm one or more event timers using the rte_event_timer_arm_burst().Thetimeout_ticksrepresentsthenumberoftimer_tick_nsafterwhichthetimerhastoexpire.Thetimeoutatwhichthetimersexpirecanbegroupedorbeindependentofeacheventtimerinstance.rte_event_timer_arm_tmo_tick_burst()addressestheformercaseandrte_event_timer_arm_burst()addressesthelattercase.

       The application can cancel the timers from expiring using the rte_event_timer_cancel_burst().

       On  the  secondary process, rte_event_timer_adapter_lookup()canbeusedtogetthetimeradapterpointerfromitsidanduseittoinvokefastpathoperationssuchasarmandcancel.

       Some of the use cases of event timer  adapter  are  Beacon  Timers,  Generic  SW  Timeout,  Wireless  MAC
       Scheduling,  3G  Frame  Protocols, Packet Scheduling, Protocol Retransmission Timers, Supervision Timers.
       All these use cases require high resolution and low time drift.

       Definition in file rte_event_timer_adapter.h.

enumrte_event_timer_adapter_clk_src
       Timer adapter clock source

       EnumeratorRTE_EVENT_TIMER_ADAPTER_CPU_CLK
              Use CPU clock as the clock source.

       RTE_EVENT_TIMER_ADAPTER_EXT_CLK0
              Platform dependent external clock source 0.

       RTE_EVENT_TIMER_ADAPTER_EXT_CLK1
              Platform dependent external clock source 1.

       RTE_EVENT_TIMER_ADAPTER_EXT_CLK2
              Platform dependent external clock source 2.

       RTE_EVENT_TIMER_ADAPTER_EXT_CLK3
              Platform dependent external clock source 3.

       Definition at line 121 of file rte_event_timer_adapter.h.

   enumrte_event_timer_state
       Event timer state.

       EnumeratorRTE_EVENT_TIMER_NOT_ARMED
              Event timer not armed.

       RTE_EVENT_TIMER_ARMED
              Event timer successfully armed.

       RTE_EVENT_TIMER_CANCELED
              Event timer successfully canceled.

       RTE_EVENT_TIMER_ERROR
              Generic event timer error.

       RTE_EVENT_TIMER_ERROR_TOOEARLY
              Event  timer  timeout  tick  value  is  too  small for the adapter to handle, given its configured
              resolution.

       RTE_EVENT_TIMER_ERROR_TOOLATE
              Event timer timeout tick is greater than the maximum timeout.

       Definition at line 455 of file rte_event_timer_adapter.h.

structrte_event_timer_adapter*rte_event_timer_adapter_create(conststructrte_event_timer_adapter_conf*conf)
       Create an event timer adapter.

       This function must be invoked first before any other function in the API.

       When   this   API   is  used  for  creating  adapter  instance,  rte_event_dev_config::nb_event_portsisautomaticallyincremented,andtheeventdeviceisreconfiguredwithadditionaleventportduringserviceinitialization.Thiseventdevicereconfigurelogicalsoincrementstherte_event_dev_config::nb_single_link_event_port_queuesparameteriftheadaptereventportconfigisoftypeRTE_EVENT_PORT_CFG_SINGLE_LINK.

       Application   no   longer    needs    to    account    for    rte_event_dev_config::nb_event_portsandrte_event_dev_config::nb_single_link_event_port_queuesparametersrequiredforTimeradapterineventdeviceconfigurationwhentheadapteriscreatedwiththisAPI.Parametersconf The event timer adapter configuration structure.

       Returns
           A pointer to the new allocated event timer adapter on success.  NULL  on  error  with  rte_errno  set
           appropriately. Possible rte_errno values include:

           • ERANGE: timer_tick_ns is not in supported range.

           • ENOMEM: unable to allocate sufficient memory for adapter instances

           • EINVAL: invalid event device identifier specified in config

           • ENOSPC: maximum number of adapters already created

           • EIO: event device reconfiguration and restart error. The adapter reconfigures the event device with
             an  additional  port  by default if it is required to use a service to manage timers. If the device
             had been started before this call, this error code indicates an error in restart following an error
             in reconfiguration, i.e., a combination of the two error codes.

   structrte_event_timer_adapter*rte_event_timer_adapter_create_ext(conststructrte_event_timer_adapter_conf*conf,rte_event_timer_adapter_port_conf_cb_tconf_cb,void*conf_arg)
       Create a timer adapter with the supplied callback.

       This  function can be used to have a more granular control over the timer adapter creation. If a built-in
       port is absent, then the function uses the callback provided to create and get the port id to be used  as
       a producer port.

       Parametersconf The timer adapter configuration structure
           conf_cb The port config callback function.
           conf_arg Opaque pointer to the argument for the callback function

       Returns
           A  pointer  to  the  new  allocated  event timer adapter on success. NULL on error with rte_errno set
           appropriately. Possible rte_errno values include:

           • ERANGE: timer_tick_ns is not in supported range.

           • ENOMEM: unable to allocate sufficient memory for adapter instances

           • EINVAL: invalid event device identifier specified in config

           • ENOSPC: maximum number of adapters already created

   intrte_event_timer_adapter_get_info(conststructrte_event_timer_adapter*adapter,structrte_event_timer_adapter_info*adapter_info)
       Retrieve the contextual information of an event timer adapter.

       Parametersadapter A pointer to the event timer adapter structure.
           adapter_info  A  pointer  to  a  structure of type rte_event_timer_adapter_infotobefilledwiththecontextualinformationoftheadapter.Returns

           • 0: Success, driver updates the contextual information of the timer adapter

           • <0: Error code returned by the driver info get function.

           • -EINVAL: adapter identifier invalid

       SeealsoRTE_EVENT_TIMER_ADAPTER_F_ADJUST_RES, struct rte_event_timer_adapter_infointrte_event_timer_adapter_start(conststructrte_event_timer_adapter*adapter)
       Start a timer adapter.

       The adapter start step is the last one and consists of setting the timer adapter to start  accepting  the
       timers and schedules to event queues.

       On success, all basic functions exported by the API (timer arm, timer cancel and so on) can be invoked.

       Parametersadapter A pointer to the event timer adapter structure.

       Returns

           • 0: Success, adapter started.

           • <0: Error code returned by the driver start function.

           • -EINVAL if adapter identifier invalid

           • -ENOENT if software adapter but no service core mapped

           • -ENOTSUP if software adapter and more than one service core mapped

           • -EALREADY if adapter has already been started

       Note
           The  eventdev  to  which  the  event_timer_adapter  is  connected  needs to be started before calling
           rte_event_timer_adapter_start().

   intrte_event_timer_adapter_stop(conststructrte_event_timer_adapter*adapter)
       Stop an event timer adapter.

       The adapter can be restarted with a call to rte_event_timer_adapter_start().Parametersadapter A pointer to the event timer adapter structure.

       Returns

           • 0: Success, adapter stopped.

           • <0: Error code returned by the driver stop function.

           • -EINVAL if adapter identifier invalid

   structrte_event_timer_adapter*rte_event_timer_adapter_lookup(uint16_tadapter_id)
       Lookup an event timer adapter using its identifier.

       If an event timer adapter was created in another process with the same  identifier,  this  function  will
       locate its state and set up access to it so that it can be used in this process.

       Parametersadapter_id The event timer adapter identifier.

       Returns
           A pointer to the event timer adapter matching the identifier on success. NULL on error with rte_errno
           set appropriately. Possible rte_errno values include:

           • ENOENT - requested entry not available to return.

   intrte_event_timer_adapter_free(structrte_event_timer_adapter*adapter)
       Free an event timer adapter.

       Destroy an event timer adapter, freeing all resources.

       Before invoking this function, the application must wait for all the armed timers to expire or cancel the
       outstanding armed timers.

       Parametersadapter A pointer to an event timer adapter structure.

       Returns

           • 0: Successfully freed the event timer adapter resources.

           • <0: Failed to free the event timer adapter resources.

           • -EAGAIN: adapter is busy; timers outstanding

           • -EBUSY: stop hasn't been called for this adapter yet

           • -EINVAL: adapter id invalid, or adapter invalid

   intrte_event_timer_adapter_service_id_get(structrte_event_timer_adapter*adapter,uint32_t*service_id)
       Retrieve  the  service ID of the event timer adapter. If the adapter doesn't use an rte_service function,
       this function returns -ESRCH.

       Parametersadapter A pointer to an event timer adapter.
           service_id A pointer to a uint32_t, to be filled in with the service id.

       Returns

           • 0: Success

           • <0: Error code on failure

           • -ESRCH: the adapter does not require a service to operate

   intrte_event_timer_adapter_stats_get(structrte_event_timer_adapter*adapter,structrte_event_timer_adapter_stats*stats)
       Retrieve statistics for an event timer adapter instance.

       Parametersadapter A pointer to an event timer adapter structure.
           stats A pointer to a structure to fill with statistics.

       Returns

           • 0: Successfully retrieved.

           • <0: Failure; error code returned.

   intrte_event_timer_adapter_stats_reset(structrte_event_timer_adapter*adapter)
       Reset statistics for an event timer adapter instance.

       Parametersadapter A pointer to an event timer adapter structure.

       Returns

           • 0: Successfully reset;

           • <0: Failure; error code returned.

   staticuint16_trte_event_timer_arm_burst(conststructrte_event_timer_adapter*adapter,structrte_event_timer**evtims,uint16_tnb_evtims)[inline],[static]
       Arm a burst of event timers with separate expiration timeout tick for each event timer.

       Before calling this function, the application allocates struct rte_event_timerobjectsfrommempoolorhugepagebackedapplicationbuffersofdesiredsize.Onsuccessfulallocation,applicationupdatesthestructrte_event_timer`attributessuchasexpiryeventattributes,timeoutticksfromnow.Thisfunctionsubmitstheeventtimerarmrequeststotheeventtimeradapterandonexpiry,theeventswillbeinjectedtodesignatedeventqueue.Timerexpiryeventswillbegeneratedonceorperiodicallyuntilcancellationbasedontheadaptermode.Parametersadapter A pointer to an event timer adapter structure.
           evtims Pointer to an array of objects of type rte_event_timerstructure.nb_evtimsNumberofeventtimersinthesuppliedarray.Returns
           The number of successfully armed event timers. The return value can be less than  the  value  of  the
           nb_evtims  parameter.  If  the return value is less than nb_evtims, the remaining event timers at the
           end of evtims are not consumed, and the caller has to  take  care  of  them,  and  rte_errno  is  set
           accordingly. Possible errno values include:

           • EINVAL  Invalid  timer  adapter,  expiry event queue ID is invalid, or an expiry event's sched type
             doesn't match the capabilities of the destination event queue.

           • EAGAIN Specified timer adapter is not running

           • EALREADY A timer was encountered that was already armed

       SeealsoRTE_EVENT_TIMER_ADAPTER_F_PERIODIC

       Definition at line 598 of file rte_event_timer_adapter.h.

   staticuint16_trte_event_timer_arm_tmo_tick_burst(conststructrte_event_timer_adapter*adapter,structrte_event_timer**evtims,constuint64_ttimeout_ticks,constuint16_tnb_evtims)[inline],[static]
       Arm a burst of event timers with same expiration timeout tick.

       Provides  the same functionality as rte_event_timer_arm_burst(),exceptthatapplicationcanusethisAPIwhenalltheeventtimershavethesametimeoutexpirationtick.Thisspecializedfunctioncanprovidetheadditionalhinttotheadapterimplementationandoptimizeifpossible.Parametersadapter A pointer to an event timer adapter structure.
           evtims Points to an array of objects of type rte_event_timerstructure.timeout_ticksThenumberofticksinwhichthetimersshouldexpire.nb_evtimsNumberofeventtimersinthesuppliedarray.Returns
           The  number  of  successfully  armed event timers. The return value can be less than the value of the
           nb_evtims parameter. If the return value is less than nb_evtims, the remaining event  timers  at  the
           end  of  evtims  are  not  consumed,  and  the  caller has to take care of them, and rte_errno is set
           accordingly. Possible errno values include:

           • EINVAL Invalid timer adapter, expiry event queue ID is invalid, or an  expiry  event's  sched  type
             doesn't match the capabilities of the destination event queue.

           • EAGAIN Specified event timer adapter is not running

           • EALREADY A timer was encountered that was already armed

       Definition at line 641 of file rte_event_timer_adapter.h.

   staticuint16_trte_event_timer_cancel_burst(conststructrte_event_timer_adapter*adapter,structrte_event_timer**evtims,uint16_tnb_evtims)[inline],[static]
       Cancel a burst of event timers from being scheduled to the event device.

       Parametersadapter A pointer to an event timer adapter structure.
           evtims Points to an array of objects of type rte_event_timerstructurenb_evtimsNumberofeventtimerinstancesinthesuppliedarray.Returns
           The number of successfully canceled event timers. The return value can be less than the value of  the
           nb_evtims  parameter.  If  the return value is less than nb_evtims, the remaining event timers at the
           end of evtims are not consumed, and the caller has to  take  care  of  them,  and  rte_errno  is  set
           accordingly. Possible errno values include:

           • EINVAL Invalid timer adapter identifier

           • EAGAIN Specified timer adapter is not running

           • EALREADY A timer was encountered that was already canceled

       Definition at line 678 of file rte_event_timer_adapter.h.

   __rte_experimentalintrte_event_timer_remaining_ticks_get(conststructrte_event_timer_adapter*adapter,conststructrte_event_timer*evtim,uint64_t*ticks_remaining)
       Get the number of ticks remaining until event timer expiry.

       Parametersadapter A pointer to an event timer adapter structure
           evtim A pointer to an rte_event_timer structure
           ticks_remaining Pointer to variable into which to write the number of  ticks  remaining  until  event
           timer expiry

       Returns

           • 0: Success

           • -EINVAL  Invalid  timer  adapter  identifier  or  the  event  timer  is  not  in the armed state or
             ticks_remaining is NULL

           • -ENOTSUP The timer adapter implementation does not support this API.

#defineRTE_EVENT_TIMER_ADAPTER_F_ADJUST_RES(1ULL<<0)
       The event timer adapter implementation may have constraints on the resolution (timer_tick_ns) and maximum
       timer expiry timeout(max_tmo_ns) based on the given timer adapter or system. If this  flag  is  set,  the
       implementation  adjusts  the  resolution  and  maximum  timeout  to  the  best possible configuration. On
       successful timer adapter creation, the application can get the configured resolution and max timeout with
       rte_event_timer_adapter_get_info().Seealso
           struct rte_event_timer_adapter_info::min_resolution_ns

           struct rte_event_timer_adapter_info::max_tmo_ns

       Definition at line 145 of file rte_event_timer_adapter.h.

   #defineRTE_EVENT_TIMER_ADAPTER_F_SP_PUT(1ULL<<1)rte_event_timer_arm_burst()APItobeusedinsingleproducermode.Seealso
           struct rte_event_timer_adapter_conf::flags

       Definition at line 150 of file rte_event_timer_adapter.h.

   #defineRTE_EVENT_TIMER_ADAPTER_F_PERIODIC(1ULL<<2)
       Flag to configure an event timer adapter in periodic mode; non-periodic mode is the default. A timer will
       fire once or periodically until the timer is cancelled based on the adapter mode.

       Seealso
           struct rte_event_timer_adapter_conf::flags

       Definition at line 158 of file rte_event_timer_adapter.h.

       rte_event_timer_adapter.h

       #include 'rte_eventdev.h'
       #include 'rte_eventdev_trace_fp.h'

   DataStructures
       struct rte_event_timer_adapter_conf
       struct rte_event_timer_adapter_stats
       struct rte_event_timer_adapter_info
       struct rte_event_timerMacros
       #define RTE_EVENT_TIMER_ADAPTER_F_ADJUST_RES   (1ULL << 0)
       #define RTE_EVENT_TIMER_ADAPTER_F_SP_PUT   (1ULL << 1)
       #define RTE_EVENT_TIMER_ADAPTER_F_PERIODIC   (1ULL << 2)

   Typedefstypedef int(* rte_event_timer_adapter_port_conf_cb_t) (uint16_t id, uint8_t event_dev_id, uint8_t
           *event_port_id, void *conf_arg)

   Enumerations
       enum rte_event_timer_adapter_clk_src { RTE_EVENT_TIMER_ADAPTER_CPU_CLK, RTE_EVENT_TIMER_ADAPTER_EXT_CLK0,
           RTE_EVENT_TIMER_ADAPTER_EXT_CLK1, RTE_EVENT_TIMER_ADAPTER_EXT_CLK2, RTE_EVENT_TIMER_ADAPTER_EXT_CLK3
           }
       enum rte_event_timer_state { RTE_EVENT_TIMER_NOT_ARMED = 0, RTE_EVENT_TIMER_ARMED = 1,
           RTE_EVENT_TIMER_CANCELED = 2, RTE_EVENT_TIMER_ERROR = -1, RTE_EVENT_TIMER_ERROR_TOOEARLY = -2,
           RTE_EVENT_TIMER_ERROR_TOOLATE = -3 }

   Functions
       struct rte_event_timer_adapter * rte_event_timer_adapter_create (const struct
           rte_event_timer_adapter_conf *conf)
       struct rte_event_timer_adapter * rte_event_timer_adapter_create_ext (const struct
           rte_event_timer_adapter_conf *conf, rte_event_timer_adapter_port_conf_cb_t conf_cb, void *conf_arg)
       int rte_event_timer_adapter_get_info (const struct rte_event_timer_adapter *adapter, struct
           rte_event_timer_adapter_info *adapter_info)
       int rte_event_timer_adapter_start (const struct rte_event_timer_adapter *adapter)
       int rte_event_timer_adapter_stop (const struct rte_event_timer_adapter *adapter)
       struct rte_event_timer_adapter * rte_event_timer_adapter_lookup (uint16_t adapter_id)
       int rte_event_timer_adapter_free (struct rte_event_timer_adapter *adapter)
       int rte_event_timer_adapter_service_id_get (struct rte_event_timer_adapter *adapter, uint32_t
           *service_id)
       int rte_event_timer_adapter_stats_get (struct rte_event_timer_adapter *adapter, struct
           rte_event_timer_adapter_stats *stats)
       int rte_event_timer_adapter_stats_reset (struct rte_event_timer_adapter *adapter)
       static uint16_t rte_event_timer_arm_burst (const struct rte_event_timer_adapter *adapter, struct
           rte_event_timer **evtims, uint16_t nb_evtims)
       static uint16_t rte_event_timer_arm_tmo_tick_burst (const struct rte_event_timer_adapter *adapter, struct
           rte_event_timer **evtims, const uint64_t timeout_ticks, const uint16_t nb_evtims)
       static uint16_t rte_event_timer_cancel_burst (const struct rte_event_timer_adapter *adapter, struct
           rte_event_timer **evtims, uint16_t nb_evtims)
       __rte_experimental int rte_event_timer_remaining_ticks_get (const struct rte_event_timer_adapter
           *adapter, const struct rte_event_timer *evtim, uint64_t *ticks_remaining)

typedefint(*rte_event_timer_adapter_port_conf_cb_t)(uint16_tid,uint8_tevent_dev_id,uint8_t*event_port_id,void*conf_arg)
       Callback function type for producer port creation.

       Definition at line 205 of file rte_event_timer_adapter.h.