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 */ 253