/*
 * CDDL HEADER START
 *
 * The contents of this file are subject to the terms of the
 * Common Development and Distribution License (the "License").
 * You may not use this file except in compliance with the License.
 *
 * You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
 * or http://www.opensolaris.org/os/licensing.
 * See the License for the specific language governing permissions
 * and limitations under the License.
 *
 * When distributing Covered Code, include this CDDL HEADER in each
 * file and include the License file at usr/src/OPENSOLARIS.LICENSE.
 * If applicable, add the following below this CDDL HEADER, with the
 * fields enclosed by brackets "[]" replaced with your own identifying
 * information: Portions Copyright [yyyy] [name of copyright owner]
 *
 * CDDL HEADER END
 */

/*
 * Copyright (c) 2010, Oracle and/or its affiliates. All rights reserved.
 */

#ifndef	_SW_H
#define	_SW_H

#ifdef	__cplusplus
extern "C" {
#endif

#include <sys/fm/protocol.h>
#include <fm/fmd_api.h>
#include <libnvpair.h>
#include <pthread.h>
#include <libuutil.h>

/*
 * We have two real fmd modules - software-diagnosis and software-response.
 * Each hosts a number of subsidiary diagnosis engines and response agents,
 * although these are not fmd modules as such (the intention is to avoid
 * a proliferation of small C diagnosis and response modules).
 *
 * Subsidiary "modules" are not loaded as normal fmd modules are.  Instead
 * each of the real modules software-diagnosis and software-response includes
 * an array listing the subsidiaries it hosts, and when the real module
 * is loaded by fmd it iterates over this list to "load" subsidiaries by
 * calling their nominated init function.
 */

/* Maximum number of subsidiary "modules" */
#define	SW_SUB_MAX	10

/* Maximum number of supported timers across all subsidiaries */
#define	SW_TIMER_MAX	20

/*
 * A subsidiary must perform fmd_hdl_subscribe calls for all events of
 * interest to it.  These are typically performed during its init
 * function.  All subscription callbacks funnel through the shared
 * fmdo_recv entry point; that function walks through the dispatch list
 * for each subsidiary and performs a callback for the first matching entry of
 * each subsidiary.  The init entry point for each subsidiary
 * returns a pointer to an array of struct sw_disp applicable for that
 * entity.
 *
 * Note that the framework does *not* perform any fmd_hdl_subscribe calls
 * on behalf of the subsidiary - the swd_classpat member below is used
 * in routing events, not in establishing subscriptions for them.  A
 * subsidiary can subscribe to say "ireport.foo.a" and "ireport.foo.b"
 * but could elect to nominate a common handler for those via a single
 * struct sw_disp with swd_classpat of "ireport.foo.*".
 */
typedef void sw_dispfunc_t(fmd_hdl_t *, fmd_event_t *, nvlist_t *,
    const char *, void *);

struct sw_disp {
	const char *swd_classpat;	/* event classes to callback for */
	sw_dispfunc_t *swd_func;	/* callback function */
	void *swd_arg;			/* opaque argument to callback */
};

/*
 * A diagnosis or response subsidiary must provide a struct sw_subinfo with
 * all its pertinent information;  a pointer to this structure must be
 * included in the array of struct sw_subinfo pointers in each of
 * software-diagnosis and software-response.
 *
 * swsub_name
 *	This should be chosen to be unique to this subsidiary;
 *	by convention it should also be the name prefix used in any fmd
 *	buffers	the subsidiary creates.
 *
 * swsub_casetype
 *	A diagnosis subsidiary solves cases using swde_case_* below, and it
 *	must specify in swsub_casetype the type of case it solves.  A response
 *	subsidiary must specify SW_CASE_NONE here.  A subsidiary may only solve
 *	at most one type of case, and no two subsidiaries must solve the same
 *	case type.  We use the case type to associate a subsidiary owner of
 *	the fmd case that is really owned by the host module.
 *
 * swsub_init
 *	The initialization function for this subsidiary, akin to the
 *	_fmd_init in a traditional fmd module.  This must not be NULL.
 *
 *	 When the host diagnosis/response module initializes the _fmd_init
 *	 entry point will call the swsub_init function for each subsidiary
 *	 in turn.  The fmd handle has already been registered and timers are
 *	 available for installation (see below);  the swsub_init function must
 *	 return a pointer to a NULL-terminated array of struct sw_disp
 *	 describing the event dispatch preferences for that module, and fill
 *	 an integer we pass with the number of entries in that array (including
 *	 the terminating NULL entry).  The swsub_init function also receives
 *	 a subsidiary-unique id_t assigned by the framework that it should
 *	 keep a note of for use in timer installation (see below);  this id
 *	 should not be persisted to checkpoint data.
 *
 * swsub_fini
 *	When the host module _fmd_fini is called it will call this function
 *	for each subsidiary.  A subsidiary can specify NULL here.
 *
 * swsub_timeout
 *	This is the timeout function to call for expired timers installed by
 *	this subsidiary.  See sw_timer_{install,remove} below.  May be
 *	NULL if no timers are used by this subsidiary.
 *
 * swsub_case_close
 *	This function is called when a case "owned" by a subsidiary
 *	is the subject of an fmdo_close callback.  Can be NULL, and
 *	must be NULL for a subsidiary with case type SW_CASE_NONE (such
 *	as a response subsidiary).
 *
 * swsub_case_verify
 *	This is called during _fmd_init of the host module.  The host module
 *	iterates over all cases that it owns and calls the verify function
 *	for the real owner which may choose to close cases if they no longer
 *	apply.  Can be NULL, and must be NULL for a subsidiary with case
 *	type SW_CASE_NONE.
 */

/*
 * sw_casetype values are persisted to checkpoints - do not change values.
 */
enum sw_casetype {
	SW_CASE_NONE = 0x0ca5e000,
	SW_CASE_SMF,
	SW_CASE_PANIC
};

/*
 * Returns for swsub_init.  The swsub_fini entry point will only be
 * called for subsidiaries that returned SW_SUB_INIT_SUCCESS on init.
 */
#define	SW_SUB_INIT_SUCCESS		0
#define	SW_SUB_INIT_FAIL_VOLUNTARY	1	/* chose not to init */
#define	SW_SUB_INIT_FAIL_ERROR		2	/* error prevented init */

typedef void swsub_case_close_func_t(fmd_hdl_t *, fmd_case_t *);
typedef int sw_case_vrfy_func_t(fmd_hdl_t *, fmd_case_t *);

struct sw_subinfo {
	const char *swsub_name;
	enum sw_casetype swsub_casetype;
	int (*swsub_init)(fmd_hdl_t *, id_t, const struct sw_disp **, int *);
	void (*swsub_fini)(fmd_hdl_t *);
	void (*swsub_timeout)(fmd_hdl_t *, id_t, void *);
	swsub_case_close_func_t *swsub_case_close;
	sw_case_vrfy_func_t *swsub_case_verify;
};

/*
 * List sw_subinfo for each subsidiary diagnosis and response "module" here
 */
extern const struct sw_subinfo smf_diag_info;
extern const struct sw_subinfo smf_response_info;
extern const struct sw_subinfo panic_diag_info;

/*
 * Timers - as per the fmd module API but with an additional id_t argument
 * specifying the unique id of the subsidiary installing the timer (provided
 * to the subsidiary in its swsub_init call).
 */
extern id_t sw_timer_install(fmd_hdl_t *, id_t, void *, fmd_event_t *,
    hrtime_t);
extern void sw_timer_remove(fmd_hdl_t *, id_t, id_t);

/*
 * The software-diagnosis subsidiaries can open and solve cases; to do so
 * they must use the following wrappers to the usual fmd module API case
 * management functions.  We need this so that a subsidiary can iterate
 * over *its* cases (fmd_case_next would iterate over those of other
 * subsidiaries), receive in the subsidiary a callback when a case it opened
 * is closed, etc.  The subsidiary can use other fmd module API members
 * for case management, such as fmd_case_add_ereport.
 *
 * Each subsidiary opens cases of its own unique type, identified by
 * the sw_casetype enumeration.  The values used in this enumeration
 * must never change - they are written to checkpoint state.
 *
 * swde_case_open
 *	Opens a new case of the correct subsidiary type for the given
 *	subsidiary id.  If a uuid string is provided then open a case
 *	with that uuid using fmd_case_open_uuid, allowing case uuid
 *	to match some relevant uuid that was received in one of the
 *	events that has led us to open this case.
 *
 *	If the subsidiarywishes to associate some persistent
 *	case data with the new case thenit can fmd_hdl_alloc and complete a
 *	suitably-packed serialization structure and include a pointer to it
 *	in the call to sw_case_open together with the structure size and
 *	structure version.  The	framework will create a new fmd buffer (named
 *	for you, based on the case type) and write the structure out to disk;
 *	when the module or fmd is restarted this structure is restored from
 *	disk for you and reassociated with the case - use swde_case_data to
 *	retrieve a pointer to it.
 *
 * swde_case_first, swde_case_next
 *	A subsidiary DE can iterate over its cases using swde_case_first and
 *	swde_case_next.  For swde_case_first quote the subsidiary id;
 *	for swde_case_next quote the last case returned.
 *
 * swde_case_data
 *	Returns a pointer to the previously-serialized case data, and fills
 *	a uint32_t with the version of that serialized data.
 *
 * swde_case_data_write
 *	Whenever a subsidiary modifies its persistent data structure
 *	it must call swde_case_data_write to indicate that the associated
 *	fmd buffer is dirty and needs to be rewritten.
 *
 * swde_case_data_upgrade
 *	If the subsidiary ever revs its persistent structure it needs to call
 *	swde_case_data_upgrade to register the new version and structure size,
 *	and write the structure out to a reallocated fmd buffer;  the old
 *	case data structure (if any) will be freed.  A subsidiary may use
 *	this interface to migrate old persistence structures restored from
 *	checkpoint - swde_case_data will return a version number below the
 *	current.
 */

extern fmd_case_t *swde_case_open(fmd_hdl_t *, id_t, char *, uint32_t,
    void *, size_t);
extern fmd_case_t *swde_case_first(fmd_hdl_t *, id_t);
extern fmd_case_t *swde_case_next(fmd_hdl_t *, fmd_case_t *);
extern void *swde_case_data(fmd_hdl_t *, fmd_case_t *, uint32_t *);
extern void swde_case_data_write(fmd_hdl_t *, fmd_case_t *);
extern void swde_case_data_upgrade(fmd_hdl_t *, fmd_case_t *, uint32_t,
    void *, size_t);

#ifdef	__cplusplus
}
#endif

#endif	/* _SW_H */