ChorusOS man pages section 2MON: Monitoring Services

svSiteProbeConnect(2MON)

NAME

svSiteProbeConnect, svSiteProbeDisconnect- Connect a monitoring probe to the local site; Disconnect a monitoring probe from the local site

SYNOPSIS

#include <mon/chMon.h>

probe

API RESTRICTIONS

The function or functions documented here may not be used safely in all application contexts with all APIs provided in the ChorusOS 5.0 product.

See API(5FEA) for details.

FEATURES

MON

DESCRIPTION

The svSiteProbeConnect() and svSiteProbeDisconnect () microkernel calls respectively connect a monitoring probe to and disconnect a monitoring probe from the local site.

PARAMETERS

The probe parameter describes the monitoring probe. It is a pointer to a MonSiteProbe structure whose member is the following:

MonSiteVtbl*   vtbl;

The vtbl member specifies the notification routines associated with the probe. It is a pointer to a MonSiteVtbl structure whose members are the following:

int                  vtbl_sizeof;
Site_connection      connection;
Site_disconnection   disconnection;
Site_nextActor       nextActor;
Site_intrEnter       intrEnter;
Site_intrLeave       intrLeave;

The vtbl_sizeof member must be set to sizeof(MonSiteVtbl) . It is provided for compatibility between different releases of the microkernel.

The other members of the MonSiteVtbl structure are pointers to functions. Each member must either be NULL , or point to the implementation of a specific notification routine associated with the probe. If non NULL , the notification routine will be invoked on each occurrence of the associated event. If NULL , no invocation is made.

The data for the MonSiteProbe structure, for the MonSiteVtbl structure, and the code for the monitoring routines must belong to supervisor space and must be locked in physical memory. The notification routines are executed in supervisor execution mode. Except where stated explicitly, they must not re-enter the microkernel except via a few permitted system calls.

EXTENDED DESCRIPTION

The notification routines are the following:

void connection (probe, state)
   MonSiteProbe*   probe;
   MonSiteState*   state;

The connection() routine is invoked after the probe has been connected to the local site. The probe parameter is a pointer to the connected probe (passed as an argument to the svSiteProbeConnect() microkernel call). The state parameter is a pointer to a MonSiteState structure, which represents the local site internally within the microkernel address space (see svSiteMonConst(2MON) ). This pointer is valid for the lifetime of the system.

void disconnection (probe)
   MonSiteProbe*   probe;

The disconnection() routine is invoked after the probe has been disconnected from the local site. The probe parameter is a pointer to the probe concerned. The rationale for this notification routine is to allow the monitoring actor to free the memory allocated for the probe safely.

void nextActor (probe, state)
   MonSiteProbe*   probe;
   MonActorState*   state;

The nextActor() routine is invoked as a consequence of the svSiteActorList(2MON) microkernel call. The probe parameter points to the local site's probe. There is one invocation of nextActor() for each actor on the local site. The state parameter is a pointer to a MonActorStat structure which is the internal representation of the actor's state within the microkernel address space. This pointer is valid for the lifetime of the actor and is guaranted to remain valid while the notification routine is being executed. Finally, nextActor() is invoked a last time with a NULL state parameter to indicate that all actors have been processed.

void intrEnter (probe, intrNo, intrCtx)
   MonSiteProbe*   probe;
   int             intrNo;
   void*           intrCtx;

The intrEnter() routine is invoked after the occurrence of a processor interrupt, before that interrupt is handled by the system. The probe parameter is a pointer to the probe concerned. The intrNo parameter is the interrupt number. The intrCtx parameter is a pointer to the interrupt context.

The intrNo and intrCtx parameters are of the KnIntrSymbName and KnIntrCtx types, respectively, as defined in the platform-dependent <kbim/p_chIntr.h> header file.

void intrLeave (probe, intrNo, intrCtx)
   MonSiteProbe*   probe;
   int             intrNo;
   void*           intrCtx;

The intrLeave() routine is invoked after the occurrence of a processor's interrupt, after that interrupt has been handled by the system. The probe parameter is a pointer to the probe concerned. The intrNo parameter is the interrupt number. The intrCtx parameter is a pointer to the interrupt context.

The intrNo and intrCtx parameters belong to the KnIntrSymbName and KnIntrCtx types, respectively, as defined in the platform-dependent <kbim/p_chIntr.h> header file.

RESTRICTIONS

The callbacks intrEnter() and intrLeave() are not supported in this release.

RETURN VALUES

Upon successful completion, both microkernel calls return 0 . Otherwise, a negative error code is returned.

ERRORS

K_EBUSY: An attempt was made to connect a probe while another probe was already connected to the local site.
K_EINVAL: An attempt was made to disconnect a probe which was not connected to the local site.

ATTRIBUTES

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Interface Stability	Evolving