fsp_plms_RegisterNotificationEvent()

QNX SDP8.0PLMS User's GuideAPIConfigurationDeveloper

Register to get notification from PLMS

Synopsis:

#include <fsp/plms.h>

fsp_ResultType fsp_plms_RegisterNotificationEvent( fsp_plms_HandleType *plms_hdl,
                                                   sigevent *se,
                                                   uint64_t flags );

Arguments:

plms_hdl
The PLMS handle returned in fsp_plms_Connect().
se
The sigevent that PLMS returns with the notification.
flags
An ORed value of the following options:
  • FSP_PLMS_NOTIFY_ALL — Notify all events.
  • FSP_PLMS_NOTIFY_STARTED — Notify the registered client that a component has started.
  • FSP_PLMS_NOTIFY_STOPPED — Notify the registered client that a component has stopped.
  • FSP_PLMS_NOTIFY_FAULT — Notify the registered client that a component has faulted.
  • FSP_PLMS_NOTIFY_FAIL_HB — Notify the registered client that a component has failed to send a heartbeat.
  • FSP_PLMS_NOTIFY_FAIL — Notify the registered client that a component has failed.

Library:

libplms

Use the -l plms option to qcc to link against this library.

Description:

The fsp_plms_RegisterNotificationEvent() call registers with plms to receive a notification when a component reaches one of the states specified in the flags argument. The caller must have the plms/query ability to use this call.

It's recommended to keep the number of notifications to a minimum to reduce the resources used to send notifications during system startup. Each successful fsp_plms_RegisterNotificationEvent() call consumes a slot in the plms notification table. The number of slots is controlled by the -n option. Attempting to register more than the available slots will return an error. If there is already a notification registered for the matching connection for the given plms_fd and flags, then the registration will return an error.

plms will send a notification to the registered client for all the components that have the coptions specified with NOTIFY_ALL in the configuration.

When a component with NOTIFY_ALL has reached the state specified in the fsp_plms_RegisterNotificationEvent(), plms sends the sigevent se to the registered client. plms updates the sigval of the received sigevent with the component hash and the actual event. The client should register the sigevent as updatable with SIGEV_MAKE_UPDATEABLE() to receive the component hash and the actual event that triggered this notification. After receiving the sigevent, the client can compare the hash with its local hash to identify the component. The client can use the following algorithm to calculate the hash. 

static unsigned component_hash( const unsigned char *str ) {
    unsigned hash, x;
    for (x = hash = 0 ; *str ; ++str) {
        hash = (hash << 4) + *str;
        if ((x = hash & 0xf0000000u) != 0) {
            hash ^= (x >> 24);
            hash &= ~x;
        }
    }
    // Modification from standard ELFHash so that client can tell that the
    // sigev_value field contains a hash if it's non-zero
    return hash | 0x80000000u;
}

Since the hash can have collisions, you should test to ensure that there are no collisions on the hash for the given components. You can also call fsp_plms_GetComponentStatus() to get the current status of the component.

QPLMS provides the following helper macros to decode the sigevent received from plms:

  • FSP_PLMS_GET_COMPONENT_HASH(se) — returns the hash from the sigevent’s sigval.
  • FSP_PLMS_GET_COMPONENT_NOTIFICATION(se) — returns the event from sigevent’s sigval that triggered the notification.

Returns:

Returns FSP_PLMS_STATUS_EOK on success, or FSP_PLMS_STATUS_FAIL on error and sets errno.

Errors:

ENOSYS
The resource manager ID is incorrect.
EBADMSG
The resource manager received an incomplete or combined client message.

Example:

fsp_plms_RegisterNotificationEvent(plms_hdl, &se, flags);
Page updated: