#
# fmd_api.txt 1.1 08/09/18
#

############
Introduction
############

This document describes new FMD APIs introduced by the LDOMs IO FMA project.
These interfaces were needed by the event transport in order to improve RAS.

An API was needed to save ereports in the error log without also posting
them to the FMD event queue.  This allows ereports destined for a root
domain to be saved in the control domain's error log.  This way there
would be a log of all ereports coming from the SP and we would have a
record of them in case they could not be delivered to the root domain.

An API was needed to checkpoint module data on demand. This allows event
transport queues to be saved as new events come in from the SP. The existing
mechanism where FMD saves checkpoint buffers on event delivery to a module
was not sufficient since these events do not come from FMD.


###############
API Description
###############

1. New interface to log ereports without also dispatching them.
   
   void fmd_xprt_log(fmd_hdl_t *hdl, fmd_xprt_t *xp, nvlist_t *nvl,
	hrtime_t hrt)

	This interface is similar to the existing fmd_xprt_post() interface,
	but only logs the event to the ereport log if it is an ereport, and
	does not post it to the fault manager dispatch queue.

	Log the newly received event for transport "xp" whose payload is
	specified by the  name-value pair list "nvl" to the error log if
	it is of the class "ereport.*".

	The fault manager assumes responsibility for deallocating "nvl"
	when it has completed the logging operation.

	If the event is ivalid (i.e. not an ereport), the fault manager
	will automatically discard the event and update the transport
	statistics appropriately.

	If the transport has some mechanism to determine a high-resolution
	time at which the event was originally queued for the transport,
	this time can be specified as the "hrt" parameter; otherwise zero
	should be specified. See the FMD PRM for more verbage on this.



2. New interface for a module to request a checkpoint.
   
   void fmd_hdl_checkpoint(fmd_hdl_t *hdl)

	Request the fault manager to save a checkpoint for the module
	associated with the handle "hdl".

	Refer to the FMD PRM section 7 for more info on checkpointing.