1. Introduction
   1.1. Project/Component Working Name:

	libfmevent - external subscriptions to FMA protocol events

   1.2. Name of Document Author/Supplier:

	Gavin Maltby

   1.3. Date of This Document:

	10/20/2009

   1.5. Email Aliases:
    	1.5.1. Responsible Manager: sridhar.yedunuthula@sun.com
    	1.5.2. Responsible Engineer: gavin.maltby@sun.com

4. Technical Description:
   4.1. Details:

	This case introduces a Committed interface 'libfmevent' that
	enables consumers outside of fmd (the fault management daemon)
	to subscribe to a subset of FMA protocol events.  There is today
	no Committed mechanism through which a would-be consumer can
	receive these events - the fmd module API is not Committed and,
	anyway, an fmd module is not a convenient means for hooking into
	events for a general-purpose application.

	While this case commits a subscription API, it does not document nor
	commit the event protocol or events themselves.  That will be the
	subject of follow-on work.

	The libfmevent manpage in the case materials describes
	the API in detail.  The API is versioned to permit future
	compatible evolution of the interface.  The interface file
	libfmevent.h is included in the case materials.

	Event classes that may be subscribed to are limited to problem
	lifecycle events (list.* describing problem diagnosis, update, repair,
	resolution etc) and so-called "software events" of class
	swevent.*.

	The swevent event class category is new to the event protocol.
	The first publisher of software events will be the SMF
	svc.startd which will send events describing service instance
	state transitions.  We explicitly allow subscription to the
	"raw" software event because some such events may be interesting
	to an administrator but will not produce an FMA diagnosis -
	for example with service state transitions we would not diagnose
	a problem given a transition from "online" to "disabled".
	Further details on software events in FMA will be the subject
	of a future ARC case.

	This library uses GPEC (general-purpose event channels) for the
	communication mechanism between fmd and libfmevent.  An
	fmd module forwards events out of fmd on a private GPEC channel, and
	all libfmevent consumers bind to that channel so that events
	are multiplexed out to all.  Most of the libfmevent API is
	about abstracting away the underlying GPEC nature of the
	library.

   4.5. Interfaces:

	New Exported Interface		Stability
	-------------------------------	------------
	/usr/include/fm/libfmevent.h	Committed
	/usr/lib/fm/libfmevent.so	Committed
	/usr/lib/fm/$ISA/libfmevent.so	Committed

	Imported Interface		Stability
	-------------------------------	------------
	door_xcreate			Committed (PSARC/2009/554)
	libnvpair(3LIB)			Committed (PSARC/2000/212)
	GPEC interfaces			Consolidation Private (PSARC/2004/398)

   4.6. Doc Impact:

	New manpages for libfmevent are required.

   4.11 Security Impact

	GPEC requires root to operate, hence so too does does libfmevent.

	It is envisaged that GPEC will be changed to become privilege-
	aware.  A suggestion is to introduce a new set of privileges which
	permit GPEC operation, and perhaps some resource controls
	to limit the amount of kernel memory a consumer is allowed
	to use in generating events.

   6.4. Product Approval Committee requested information:
   	6.4.1. Consolidation or Component Name:

		ON

   6.5. ARC review type:

		FastTrack

   6.6. ARC Exposure:

		open