xref: /illumos-gate/usr/src/cmd/fm/fmd/common/fmd_ckpt.h (revision 2a8bcb4efb45d99ac41c94a75c396b362c414f7f)
1 /*
2  * CDDL HEADER START
3  *
4  * The contents of this file are subject to the terms of the
5  * Common Development and Distribution License, Version 1.0 only
6  * (the "License").  You may not use this file except in compliance
7  * with the License.
8  *
9  * You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
10  * or http://www.opensolaris.org/os/licensing.
11  * See the License for the specific language governing permissions
12  * and limitations under the License.
13  *
14  * When distributing Covered Code, include this CDDL HEADER in each
15  * file and include the License file at usr/src/OPENSOLARIS.LICENSE.
16  * If applicable, add the following below this CDDL HEADER, with the
17  * fields enclosed by brackets "[]" replaced with your own identifying
18  * information: Portions Copyright [yyyy] [name of copyright owner]
19  *
20  * CDDL HEADER END
21  */
22 
23 /*
24  * Copyright 2005 Sun Microsystems, Inc.  All rights reserved.
25  * Use is subject to license terms.
26  */
27 
28 #ifndef	_FMD_CKPT_H
29 #define	_FMD_CKPT_H
30 
31 #include <sys/types.h>
32 
33 #ifdef	__cplusplus
34 extern "C" {
35 #endif
36 
37 /*
38  * Fault Manager Checkpoint Format (FCF)
39  *
40  * Fault manager modules can checkpoint state in the FCF format so that they
41  * can survive restarts, module failures, and reboots.  The FCF format is
42  * versioned and extensible so that it can be revised and so that internal data
43  * structures can be modified or extended compatibly.  It is also specified as
44  * a Project Private interface so that incompatible changes can occur as we see
45  * fit.  All FCF structures use fixed-size types so that the 32-bit and 64-bit
46  * forms are identical and consumers can use either data model transparently.
47  *
48  * The file layout is structured as follows:
49  *
50  * +---------------+-------------------+----- ... ----+---- ... ------+
51  * |   fcf_hdr_t   |  fcf_sec_t[ ... ] |   section    |   section     |
52  * | (file header) | (section headers) |   #1 data    |   #N data     |
53  * +---------------+-------------------+----- ... ----+---- ... ------+
54  * |<------------ fcf_hdr.fcfh_filesz ------------------------------->|
55  *
56  * The file header stores meta-data including a magic number, data model for
57  * the checkpointed module, data encoding, and other miscellaneous properties.
58  * The header describes its own size and the size of the section headers.  By
59  * convention, an array of section headers follows the file header, and then
60  * the data for all the individual sections listed in the section header table.
61  *
62  * The section headers describe the size, offset, alignment, and section type
63  * for each section.  Sections are described using a set of #defines that tell
64  * the consumer what kind of data is expected.  Sections can contain links to
65  * other sections by storing a fcf_secidx_t, an index into the section header
66  * array, inside of the section data structures.  The section header includes
67  * an entry size so that sections with data arrays can grow their structures.
68  *
69  * Finally, strings are always stored in ELF-style string tables along with a
70  * string table section index and string table offset.  Therefore strings in
71  * FCF are always arbitrary-length and not bound to the current implementation.
72  */
73 
74 #define	FCF_ID_SIZE	16	/* total size of fcfh_ident[] in bytes */
75 
76 typedef struct fcf_hdr {
77 	uint8_t fcfh_ident[FCF_ID_SIZE]; /* identification bytes (see below) */
78 	uint32_t fcfh_flags;		/* file attribute flags (if any) */
79 	uint32_t fcfh_hdrsize;		/* size of file header in bytes */
80 	uint32_t fcfh_secsize;		/* size of section header in bytes */
81 	uint32_t fcfh_secnum;		/* number of section headers */
82 	uint64_t fcfh_secoff;		/* file offset of section headers */
83 	uint64_t fcfh_filesz;		/* file size of entire FCF file */
84 	uint64_t fcfh_cgen;		/* checkpoint generation number */
85 	uint64_t fcfh_pad;		/* reserved for future use */
86 } fcf_hdr_t;
87 
88 #define	FCF_ID_MAG0	0	/* first byte of magic number */
89 #define	FCF_ID_MAG1	1	/* second byte of magic number */
90 #define	FCF_ID_MAG2	2	/* third byte of magic number */
91 #define	FCF_ID_MAG3	3	/* fourth byte of magic number */
92 #define	FCF_ID_MODEL	4	/* FCF data model (see below) */
93 #define	FCF_ID_ENCODING	5	/* FCF data encoding (see below) */
94 #define	FCF_ID_VERSION	6	/* FCF file format major version (see below) */
95 #define	FCF_ID_PAD	7	/* start of padding bytes (all zeroes) */
96 
97 #define	FCF_MAG_MAG0	0x7F	/* FCF_ID_MAG[0-3] */
98 #define	FCF_MAG_MAG1	'F'
99 #define	FCF_MAG_MAG2	'C'
100 #define	FCF_MAG_MAG3	'F'
101 
102 #define	FCF_MAG_STRING	"\177FCF"
103 #define	FCF_MAG_STRLEN	4
104 
105 #define	FCF_MODEL_NONE	0	/* FCF_ID_MODEL */
106 #define	FCF_MODEL_ILP32	1
107 #define	FCF_MODEL_LP64	2
108 
109 #ifdef _LP64
110 #define	FCF_MODEL_NATIVE	FCF_MODEL_LP64
111 #else
112 #define	FCF_MODEL_NATIVE	FCF_MODEL_ILP32
113 #endif
114 
115 #define	FCF_ENCODE_NONE	0	/* FCF_ID_ENCODING */
116 #define	FCF_ENCODE_LSB	1
117 #define	FCF_ENCODE_MSB	2
118 
119 #ifdef _BIG_ENDIAN
120 #define	FCF_ENCODE_NATIVE	FCF_ENCODE_MSB
121 #else
122 #define	FCF_ENCODE_NATIVE	FCF_ENCODE_LSB
123 #endif
124 
125 #define	FCF_VERSION_1	1	/* FCF_ID_VERSION */
126 #define	FCF_VERSION	FCF_VERSION_1
127 
128 #define	FCF_FL_VALID	0	/* mask of all valid fcfh_flags bits */
129 
130 typedef uint32_t fcf_secidx_t;	/* section header table index type */
131 typedef uint32_t fcf_stridx_t;	/* string table index type */
132 
133 #define	FCF_SECIDX_NONE	0	/* null value for section indices */
134 #define	FCF_STRIDX_NONE	0	/* null value for string indices */
135 
136 typedef struct fcf_sec {
137 	uint32_t fcfs_type;	/* section type (see below) */
138 	uint32_t fcfs_align;	/* section data memory alignment */
139 	uint32_t fcfs_flags;	/* section flags (if any) */
140 	uint32_t fcfs_entsize;	/* size of section entry (if table) */
141 	uint64_t fcfs_offset;	/* offset of section data within file */
142 	uint64_t fcfs_size;	/* size of section data in bytes */
143 } fcf_sec_t;
144 
145 /*
146  * Section types (fcfs_type values).  These #defines should be kept in sync
147  * with the decoding table declared in fmd_mdb.c in the fcf_sec() dcmd, and
148  * with the size and alignment table declared at the top of fmd_ckpt.c.
149  */
150 #define	FCF_SECT_NONE		0	/* null section */
151 #define	FCF_SECT_STRTAB		1	/* string table */
152 #define	FCF_SECT_MODULE		2	/* module meta-data (fcf_mod_t) */
153 #define	FCF_SECT_CASE		3	/* case meta-data (fcf_case_t) */
154 #define	FCF_SECT_BUFS		4	/* buffer list (fcf_buf_t) */
155 #define	FCF_SECT_BUFFER		5	/* module data buffer */
156 #define	FCF_SECT_SERD		6	/* serd list (fcf_serd_t) */
157 #define	FCF_SECT_EVENTS		7	/* event list (fcf_event_t) */
158 #define	FCF_SECT_NVLISTS	8	/* nvlist list (fcf_nvl_t) */
159 
160 typedef struct fcf_module {
161 	fcf_stridx_t fcfm_name;	/* module basename */
162 	fcf_stridx_t fcfm_path;	/* module path */
163 	fcf_stridx_t fcfm_desc;	/* description */
164 	fcf_stridx_t fcfm_vers;	/* version */
165 	fcf_secidx_t fcfm_bufs; /* FCF_SECT_BUFS containing global buffers */
166 } fcf_module_t;
167 
168 typedef struct fcf_case {
169 	fcf_stridx_t fcfc_uuid;	/* case uuid */
170 	uint32_t fcfc_state;	/* case state (see below) */
171 	fcf_secidx_t fcfc_bufs;	/* FCF_SECT_BUFS containing buffers */
172 	fcf_secidx_t fcfc_principal; /* FCF_SECT_EVENTS containing principal */
173 	fcf_secidx_t fcfc_events; /* FCF_SECT_EVENTS containing events */
174 	fcf_secidx_t fcfc_suspects; /* FCF_SECT_NVLISTS containing suspects */
175 } fcf_case_t;
176 
177 #define	FCF_CASE_UNSOLVED	0
178 #define	FCF_CASE_SOLVED		1
179 #define	FCF_CASE_CLOSE_WAIT	2
180 
181 typedef struct fcf_buf {
182 	fcf_stridx_t fcfb_name;	/* buffer name */
183 	fcf_secidx_t fcfb_data;	/* FCF_SECT_BUFFER containing data */
184 } fcf_buf_t;
185 
186 typedef struct fcf_serd {
187 	fcf_stridx_t fcfd_name;	/* engine name */
188 	fcf_secidx_t fcfd_events; /* FCF_SECT_EVENTS containing events */
189 	uint32_t fcfd_pad;	/* reserved for future use */
190 	uint32_t fcfd_n;	/* engine N parameter */
191 	uint64_t fcfd_t;	/* engine T parameter */
192 } fcf_serd_t;
193 
194 typedef struct fcf_event {
195 	uint64_t fcfe_todsec;	/* seconds since gettimeofday(3C) epoch */
196 	uint64_t fcfe_todnsec;	/* nanoseconds past value of fcfe_todsec */
197 	uint32_t fcfe_major;	/* major number from log file st_dev */
198 	uint32_t fcfe_minor;	/* minor number from log file st_rdev */
199 	uint64_t fcfe_inode;	/* inode number from log file st_ino */
200 	uint64_t fcfe_offset;	/* event offset within log file */
201 } fcf_event_t;
202 
203 typedef struct fcf_nvlist {
204 	uint64_t fcfn_size;	/* size of packed nvlist after this header */
205 } fcf_nvl_t;
206 
207 /*
208  * The checkpoint subsystem provides a very simple set of interfaces to the
209  * reset of fmd: namely, checkpoints can be saved, restored, or deleted by mod.
210  * In the reference implementation, these are implemented to use FCF files.
211  */
212 
213 struct fmd_module;		/* see <fmd_module.h> */
214 
215 extern void fmd_ckpt_save(struct fmd_module *);
216 extern void fmd_ckpt_restore(struct fmd_module *);
217 extern void fmd_ckpt_delete(struct fmd_module *);
218 extern void fmd_ckpt_rename(struct fmd_module *);
219 
220 #ifdef	__cplusplus
221 }
222 #endif
223 
224 #endif	/* _FMD_CKPT_H */
225