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 (the "License").
6 * You may not use this file except in compliance with the License.
7 *
8 * You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
9 * or http://www.opensolaris.org/os/licensing.
10 * See the License for the specific language governing permissions
11 * and limitations under the License.
12 *
13 * When distributing Covered Code, include this CDDL HEADER in each
14 * file and include the License file at usr/src/OPENSOLARIS.LICENSE.
15 * If applicable, add the following below this CDDL HEADER, with the
16 * fields enclosed by brackets "[]" replaced with your own identifying
17 * information: Portions Copyright [yyyy] [name of copyright owner]
18 *
19 * CDDL HEADER END
20 */
21 /*
22 * Copyright 2008 Sun Microsystems, Inc. All rights reserved.
23 * Use is subject to license terms.
24 */
25
26 #ifndef _SPCS_S_K_H
27 #define _SPCS_S_K_H
28
29 #ifdef __cplusplus
30 extern "C" {
31 #endif
32
33 /*
34 * Public SPCS uniform status details
35 */
36
37 /*
38 * KERNEL level status support utilities
39 */
40
41
42 /*
43 * Create and initialize local status. Call this at entry to topmost
44 * operation (e.g. the start of ioctl service)
45 * @return The allocated and initialized status info or NULL if no memory
46 * available
47 */
48 spcs_s_info_t
49 spcs_s_kcreate();
50
51 /*
52 * Initialize existing status. Call this at entry to topmost operation
53 * (e.g. the start of ioctl service)
54 * @param kstatus The status info.
55 */
56 void
57 spcs_s_kinit(spcs_s_info_t kstatus);
58
59 /*
60 * Add a status code and optional support information to status
61 * @param kstatus The status info pointer
62 * @param stcode The status code to be added (.e.g. DSW_EEMPTY)
63 * <BR>Supplemental value parameters may be supplied as needed. There
64 * should be one supplemental info parameter corresponding
65 * to each edit specification (e.g. %s) in the message text for a
66 * given code.
67 * <BR>If there is no additional room to insert everything the code
68 * SPCS_EOVERFLOW is inserted instead of stcode, possibly replacing an
69 * a previously inserted status code.
70 */
71 void
72 spcs_s_add(spcs_s_info_t kstatus, spcs_s_status_t stcode, ...);
73
74 /*
75 * Copy status info to userspace
76 * @param kstatus_a is The address of the local (kernel) status info
77 * @param ustatus The userspace status info
78 */
79 void
80 spcs_s_copyout(spcs_s_info_t *kstatus_a, spcs_s_info_t ustatus);
81
82 /*
83 * Copy status info to userspace and free status info storage
84 * @param kstatus_a is The address of the local (kernel) status info
85 * @param ustatus The userspace status info
86 */
87 void
88 spcs_s_copyoutf(spcs_s_info_t *kstatus_a, spcs_s_info_t ustatus);
89
90 /*
91 * Return the oldest status code from the status info or SPCS_S_OK if
92 * there is none. This is the status code that was inserted first (i.e.
93 * LIFO).
94 * @param kstatus The local (kernel level) status info
95 * @return The oldest status code value
96 */
97
98 spcs_s_status_t
99 spcs_s_oldest_status(spcs_s_info_t kstatus);
100
101 /*
102 * Return the youngest status code from the status info or SPCS_S_OK if
103 * there is none. This is the status code that was inserted last (i.e.
104 * LIFO).
105 * @param kstatus The local (kernel level) status info
106 * @return The youngest status code value
107 */
108
109 spcs_s_status_t
110 spcs_s_youngest_status(spcs_s_info_t kstatus);
111
112 /*
113 * Copy status info to userspace and provide return value.
114 * <BR>This is a one-step means of returning from a kernel function. It is
115 * identical to spcs_s_fcopyout except that the kernel status storage is
116 * not released.
117 * @param kstatus_a The address of the local kernel status info.
118 * @param ustatus The user status info
119 * @param stcode A status code. If the status code is NULL it is ignored.
120 * <BR>Supplemental value parameters may be supplied as needed. There
121 * should be one supplemental info parameter corresponding
122 * to each edit specification (e.g. %s) in the message text for a
123 * given code.
124 * <BR>If there is no additional room to insert everything the code
125 * SPCS_EOVERFLOW is inserted instead of stcode, possibly replacing an
126 * a previously inserted status code.
127 * @return If stcode is NULL and there is no status info present,
128 * SPCS_S_OK, else SPCS_S_ERROR.
129 */
130 spcs_s_status_t
131 spcs_s_ocopyout(spcs_s_info_t *kstatus_a,
132 spcs_s_info_t ustatus, spcs_s_status_t stcode, ...);
133
134 /*
135 * Copy status info to userspace, free it and provide a return value
136 * <BR>This is a one-step means of returning from a kernel function. It is
137 * identical to spcs_s_fcopyout except that the kernel status storage is
138 * released.
139 * <BR>Return a value to use as a function result (SPCS_S_OK or ERROR)
140 * <BR>This is a one-step means of returning from an operation. It is
141 * identical to spcs_s_copyout except that the kernel status information
142 * storage is released.
143 * @param kstatus_a The address of the local kernel status info.
144 * @param ustatus The user status info
145 * @param stcode A status code. If the status code is NULL it is ignored.
146 * @param stcode A status code. If the status code is NULL it is ignored.
147 * <BR>Supplemental value parameters may be supplied as needed. There
148 * should be one supplemental info parameter corresponding
149 * to each edit specification (e.g. %s) in the message text for a
150 * <BR>If there is no additional room to insert everything the code
151 * SPCS_EOVERFLOW is inserted instead of stcode, possibly replacing an
152 * a previously inserted status code.
153 * @return If stcode is NULL and there is no status info present,
154 * SPCS_S_OK, else SPCS_S_ERROR.
155 */
156 spcs_s_status_t
157 spcs_s_ocopyoutf(spcs_s_info_t *kstatus_a,
158 spcs_s_info_t ustatus, spcs_s_status_t stcode, ...);
159
160 /*
161 * Release (free) status storage.
162 * @param status The status information to release (kmem_free)
163 */
164 void
165 spcs_s_kfree(spcs_s_info_t status);
166
167 /*
168 * Test a status code and return true if it is a Solaris error code
169 * @return B_TRUE if the code is a Solaris code (module == 0), else
170 * B_FALSE
171 */
172 boolean_t
173 spcs_s_is_solaris(spcs_s_status_t error);
174
175 /*
176 *
177 * Edit an value into a decimal or hexidecimal string.
178 * Note that if multiple calls to this function are used to develop the
179 * parameters for spcs_s_add() the character arrays must be distinct.
180 * @param val The value to edit
181 * @param buf Pointer to the start of a char array for conversion
182 * @param buflen The size of the char array (minimum 2)
183 * @param hex If nonzero "0x" is prepended to generated string and
184 * it is edited as hexidecimal.
185 * @return The numeric string or "***" if an error is detected
186 */
187
188 char *
189 spcs_s_inttostring(int val, char *buf, int buflen, int hex);
190
191 /*
192 * Initialize the bytestream mechanism.
193 *
194 * This function initializes the Unistat mechanism for transporting
195 * status information with or without bytestream data to userspace.
196 *
197 * @return SPCS_S_OK for normal completion, SPCS_S_ERROR otherwise
198 *
199 * Specification TBD. Not in 10/22 commitment
200 */
201
202 int
203 spcs_s_start_bytestream();
204
205 /*
206 * Stop (shut off) the bytestream mechanism.
207 *
208 * This function terminates the Unistat mechanism for transporting
209 * status information with or without bytestream data to userspace.
210 *
211 * @return SPCS_S_OK for normal completion, SPCS_S_ERROR otherwise
212 *
213 * Specification TBD. Not in 10/22 commitment
214 */
215
216 int
217 spcs_s_stop_bytestream();
218
219 /*
220 * Add a status code and the address and length of arbitrary binary
221 * data to be held (possibly with other status) for later transmission to
222 * userspace via a pipe facility (i.e. NOT via ioctl return). This is a
223 * means of getting arbitrary information with or without other status
224 * info shipped out as an alternative to cmn_err and/or trace file
225 * mechanisms.
226 * @param kstatus The status info pointer
227 * @param stcode The status code to annotate the data
228 * @param data The starting address of the data
229 * @param size The byte length of the data
230 * Specification TBD. Not in the 10/22/98 unistat commitment
231 */
232
233 void
234 spcs_s_add_bytestream(spcs_s_info_t kstatus, spcs_s_status_t stcode,
235 spcs_s_bytestream_ptr_t data, int size);
236
237 /*
238 * Asynchronously output unistat info and possibly bytestreams to
239 * userspace. The bytestream mechanism must have been initialized.
240 * @param kstatus The status info pointer
241 * @return SPCS_S_OK for normal completion, SPCS_S_ERROR otherwise
242 * Specification TBD. Not in the 10/22/98 unistat commitment
243 */
244
245 int
246 spcs_s_asynch_status(spcs_s_info_t kstatus);
247
248 #ifdef __cplusplus
249 }
250 #endif
251
252 #endif /* _SPCS_S_K_H */