Go to main content

man pages section 3: Library Interfaces and Headers

Exit Print View

Updated: Thursday, June 13, 2019
 
 

ibv_get_async_event (3)

Name

ibv_get_async_event - nous events

Synopsis

#include <infiniband/verbs.h>

int ibv_get_async_event(struct ibv_context *context,
struct ibv_async_event *event);

void ibv_ack_async_event(struct ibv_async_event *event);

Description

Libibverbs Programmer's Manual                          IBV_GET_ASYNC_EVENT(3)



NAME
       ibv_get_async_event, ibv_ack_async_event - get or acknowledge asynchro-
       nous events

SYNOPSIS
       #include <infiniband/verbs.h>

       int ibv_get_async_event(struct ibv_context *context,
                               struct ibv_async_event *event);

       void ibv_ack_async_event(struct ibv_async_event *event);

DESCRIPTION
       ibv_get_async_event() waits for the next async event of the  InfiniBand
       device  context context and returns it through the pointer event, which
       is an ibv_async_event struct, as defined in <infiniband/verbs.h>.

       struct ibv_async_event {
               union {
                       struct ibv_cq  *cq;             /* CQ that got the event */
                       struct ibv_qp  *qp;             /* QP that got the event */
                       struct ibv_srq *srq;            /* SRQ that got the event */
                       int             port_num;       /* port number that got the event */
                       uint32_t        xrc_qp_num;     /* XRC QP that got the event */
                       union ibv_gid   gid;            /* list of guids that got the event */
               } element;
               enum ibv_event_type     event_type;     /* type of the event */
       };

       One member of the  element  union  will  be  valid,  depending  on  the
       event_type member of the structure.  event_type will be one of the fol-
       lowing events:

       QP events:

       IBV_EVENT_QP_FATAL  Error occurred on a QP and it transitioned to error
       state

       IBV_EVENT_QP_REQ_ERR  Invalid Request Local Work Queue Error

       IBV_EVENT_QP_ACCESS_ERR  Local access violation error

       IBV_EVENT_COMM_EST  Communication was established on a QP

       IBV_EVENT_SQ_DRAINED  Send Queue was drained of outstanding messages in
       progress

       IBV_EVENT_PATH_MIG  A connection has migrated to the alternate path

       IBV_EVENT_PATH_MIG_ERR  A connection failed to migrate to the alternate
       path

       IBV_EVENT_QP_LAST_WQE_REACHED  Last WQE Reached on a QP associated with
       an SRQ

       CQ events:

       IBV_EVENT_CQ_ERR  CQ is in error (CQ overrun)

       SRQ events:

       IBV_EVENT_SRQ_ERR  Error occurred on an SRQ

       IBV_EVENT_SRQ_LIMIT_REACHED  SRQ limit was reached

       Port events:

       IBV_EVENT_PORT_ACTIVE  Link became active on a port

       IBV_EVENT_PORT_ERR  Link became unavailable on a port

       IBV_EVENT_LID_CHANGE  LID was changed on a port

       IBV_EVENT_PKEY_CHANGE  P_Key table was changed on a port

       IBV_EVENT_SM_CHANGE  SM was changed on a port

       IBV_EVENT_CLIENT_REREGISTER  SM sent a CLIENT_REREGISTER request  to  a
       port

       IBV_EVENT_GID_CHANGE  GID table was changed on a port

       CA events:

       IBV_EVENT_DEVICE_FATAL  CA is in FATAL state

       Subnet events:

       IBV_SM_EVENT_MCG_CREATED  notification of MCG creation

       IBV_SM_EVENT_MCG_DELETED  notification of MCG deletion

       IBV_SM_EVENT_GID_AVAIL  notification of GID available events

       IBV_SM_EVENT_GID_UNAVAIL  notification of GID unavailable events

       ibv_ack_async_event() acknowledge the async event event.

RETURN VALUE
       ibv_get_async_event() returns 0 on success, and -1 on error.

       ibv_ack_async_event() returns no value.


ATTRIBUTES
       See attributes(7) for descriptions of the following attributes:


       +---------------+-----------------------+
       |ATTRIBUTE TYPE |   ATTRIBUTE VALUE     |
       +---------------+-----------------------+
       |Availability   | network/open-fabrics  |
       +---------------+-----------------------+
       |Stability      | Pass-through volatile |
       +---------------+-----------------------+
NOTES
       All  async  events  that ibv_get_async_event() returns must be acknowl-
       edged using  ibv_ack_async_event().   To  avoid  races,  destroying  an
       object  (CQ,  SRQ  or  QP)  will wait for all affiliated events for the
       object to be acknowledged; this avoids  an  application  retrieving  an
       affiliated  event  after  the  corresponding  object  has  already been
       destroyed.

       ibv_get_async_event() is a blocking function.  If multiple threads call
       this function simultaneously, then when an async event occurs, only one
       thread will receive it, and it is not possible to predict which  thread
       will receive it.

EXAMPLES
       The  following  code example demonstrates one possible way to work with
       async events in non-blocking mode.  It performs the following steps:

       1. Set the async events queue work mode to be non-blocked
       2. Poll the queue until it has an async event
       3. Get the async event and ack it

       /* change the blocking mode of the async event queue */
       flags = fcntl(ctx->async_fd, F_GETFL);
       rc = fcntl(ctx->async_fd, F_SETFL, flags | O_NONBLOCK);
       if (rc < 0) {
               fprintf(stderr, "Failed to change file descriptor of async event queue\n");
               return 1;
       }

       /*
        * poll the queue until it has an event and sleep ms_timeout
        * milliseconds between any iteration
        */
       my_pollfd.fd      = ctx->async_fd;
       my_pollfd.events  = POLLIN;
       my_pollfd.revents = 0;

       do {
               rc = poll(&my_pollfd, 1, ms_timeout);
       } while (rc == 0);
       if (rc < 0) {
               fprintf(stderr, "poll failed\n");
               return 1;
       }

       /* Get the async event */
       if (ibv_get_async_event(ctx, &async_event)) {
               fprintf(stderr, "Failed to get async_event\n");
               return 1;
       }

       /* Ack the event */
       ibv_ack_async_event(&async_event);


SEE ALSO
       ibv_open_device(3)

AUTHORS
       Dotan Barak <dotanba@gmail.com>


              This   software   was   built   from   source    available    at
              https://github.com/oracle/solaris-userland.  The original commu-
              nity  source   was   downloaded   from    ['https://www.openfab-
              rics.org/downloads/ibutils/ibutils-1.5.7-0.2.gbd7e502.tar.gz',
              'https://www.openfabrics.org/downloads/libibverbs/libib-
              verbs-1.1.8.tar.gz',          'https://www.openfabrics.org/down-
              loads/libmlx4/libmlx4-1.0.6.tar.gz',       'https://www.openfab-
              rics.org/downloads/libsdp/libsdp-1.1.108-0.15.gd7fdb72.tar.gz',
              'https://www.openfabrics.org/downloads/management/infiniband-
              diags-1.6.5.tar.gz', 'https://www.openfabrics.org/downloads/man-
              agement/libibmad-1.3.12.tar.gz',           'https://www.openfab-
              rics.org/downloads/management/libibumad-1.3.10.2.tar.gz',
              'https://www.openfabrics.org/downloads/manage-
              ment/opensm-3.3.19.tar.gz',   'https://www.openfabrics.org/down-
              loads/perftest/perftest-1.3.0-0.42.gf350d3d.tar.gz',
              'https://www.openfabrics.org/down-
              loads/qperf/qperf-0.4.9.tar.gz',           'https://www.openfab-
              rics.org/downloads/rdmacm/librdmacm-1.0.21.tar.gz',
              'https://www.openfabrics.org/downloads/rds-tools/rds-
              tools-2.0.4.tar.gz']

              Further information about this software can be found on the open
              source community website at http://www.openfabrics.org/.



libibverbs                        2006-10-31            IBV_GET_ASYNC_EVENT(3)