fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * CDDL HEADER START
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * The contents of this file are subject to the terms of the
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * Common Development and Distribution License (the "License").
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * You may not use this file except in compliance with the License.
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * See the License for the specific language governing permissions
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * and limitations under the License.
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * When distributing Covered Code, include this CDDL HEADER in each
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * file and include the License file at usr/src/OPENSOLARIS.LICENSE.
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * If applicable, add the following below this CDDL HEADER, with the
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * fields enclosed by brackets "[]" replaced with your own identifying
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * information: Portions Copyright [yyyy] [name of copyright owner]
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * CDDL HEADER END
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * Copyright 2008 Sun Microsystems, Inc. All rights reserved.
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * Use is subject to license terms.
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * Public SPCS uniform status details
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * KERNEL level status support utilities
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * Create and initialize local status. Call this at entry to topmost
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * operation (e.g. the start of ioctl service)
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * @return The allocated and initialized status info or NULL if no memory
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * Initialize existing status. Call this at entry to topmost operation
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * (e.g. the start of ioctl service)
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * @param kstatus The status info.
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * Add a status code and optional support information to status
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * @param kstatus The status info pointer
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * @param stcode The status code to be added (.e.g. DSW_EEMPTY)
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * <BR>Supplemental value parameters may be supplied as needed. There
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * should be one supplemental info parameter corresponding
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * to each edit specification (e.g. %s) in the message text for a
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * given code.
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * <BR>If there is no additional room to insert everything the code
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * SPCS_EOVERFLOW is inserted instead of stcode, possibly replacing an
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * a previously inserted status code.
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Fortespcs_s_add(spcs_s_info_t kstatus, spcs_s_status_t stcode, ...);
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * Copy status info to userspace
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * @param kstatus_a is The address of the local (kernel) status info
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * @param ustatus The userspace status info
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Fortespcs_s_copyout(spcs_s_info_t *kstatus_a, spcs_s_info_t ustatus);
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * Copy status info to userspace and free status info storage
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * @param kstatus_a is The address of the local (kernel) status info
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * @param ustatus The userspace status info
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Fortespcs_s_copyoutf(spcs_s_info_t *kstatus_a, spcs_s_info_t ustatus);
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * Return the oldest status code from the status info or SPCS_S_OK if
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * there is none. This is the status code that was inserted first (i.e.
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * @param kstatus The local (kernel level) status info
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * @return The oldest status code value
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * Return the youngest status code from the status info or SPCS_S_OK if
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * there is none. This is the status code that was inserted last (i.e.
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * @param kstatus The local (kernel level) status info
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * @return The youngest status code value
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * Copy status info to userspace and provide return value.
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * <BR>This is a one-step means of returning from a kernel function. It is
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * identical to spcs_s_fcopyout except that the kernel status storage is
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * not released.
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * @param kstatus_a The address of the local kernel status info.
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * @param ustatus The user status info
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * @param stcode A status code. If the status code is NULL it is ignored.
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * <BR>Supplemental value parameters may be supplied as needed. There
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * should be one supplemental info parameter corresponding
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * to each edit specification (e.g. %s) in the message text for a
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * given code.
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * <BR>If there is no additional room to insert everything the code
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * SPCS_EOVERFLOW is inserted instead of stcode, possibly replacing an
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * a previously inserted status code.
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * @return If stcode is NULL and there is no status info present,
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * SPCS_S_OK, else SPCS_S_ERROR.
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte spcs_s_info_t ustatus, spcs_s_status_t stcode, ...);
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * Copy status info to userspace, free it and provide a return value
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * <BR>This is a one-step means of returning from a kernel function. It is
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * identical to spcs_s_fcopyout except that the kernel status storage is
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * <BR>Return a value to use as a function result (SPCS_S_OK or ERROR)
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * <BR>This is a one-step means of returning from an operation. It is
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * identical to spcs_s_copyout except that the kernel status information
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * storage is released.
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * @param kstatus_a The address of the local kernel status info.
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * @param ustatus The user status info
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * @param stcode A status code. If the status code is NULL it is ignored.
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * @param stcode A status code. If the status code is NULL it is ignored.
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * <BR>Supplemental value parameters may be supplied as needed. There
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * should be one supplemental info parameter corresponding
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * to each edit specification (e.g. %s) in the message text for a
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * <BR>If there is no additional room to insert everything the code
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * SPCS_EOVERFLOW is inserted instead of stcode, possibly replacing an
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * a previously inserted status code.
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * @return If stcode is NULL and there is no status info present,
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * SPCS_S_OK, else SPCS_S_ERROR.
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte spcs_s_info_t ustatus, spcs_s_status_t stcode, ...);
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * Release (free) status storage.
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * @param status The status information to release (kmem_free)
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * Test a status code and return true if it is a Solaris error code
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * @return B_TRUE if the code is a Solaris code (module == 0), else
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * Edit an value into a decimal or hexidecimal string.
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * Note that if multiple calls to this function are used to develop the
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * parameters for spcs_s_add() the character arrays must be distinct.
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * @param val The value to edit
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * @param buf Pointer to the start of a char array for conversion
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * @param buflen The size of the char array (minimum 2)
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * @param hex If nonzero "0x" is prepended to generated string and
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * it is edited as hexidecimal.
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * @return The numeric string or "***" if an error is detected
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Fortespcs_s_inttostring(int val, char *buf, int buflen, int hex);
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * Initialize the bytestream mechanism.
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * This function initializes the Unistat mechanism for transporting
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * status information with or without bytestream data to userspace.
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * @return SPCS_S_OK for normal completion, SPCS_S_ERROR otherwise
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * Specification TBD. Not in 10/22 commitment
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * Stop (shut off) the bytestream mechanism.
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * This function terminates the Unistat mechanism for transporting
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * status information with or without bytestream data to userspace.
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * @return SPCS_S_OK for normal completion, SPCS_S_ERROR otherwise
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * Specification TBD. Not in 10/22 commitment
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * Add a status code and the address and length of arbitrary binary
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * data to be held (possibly with other status) for later transmission to
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * userspace via a pipe facility (i.e. NOT via ioctl return). This is a
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * means of getting arbitrary information with or without other status
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * info shipped out as an alternative to cmn_err and/or trace file
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * mechanisms.
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * @param kstatus The status info pointer
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * @param stcode The status code to annotate the data
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * @param data The starting address of the data
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * @param size The byte length of the data
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * Specification TBD. Not in the 10/22/98 unistat commitment
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Fortespcs_s_add_bytestream(spcs_s_info_t kstatus, spcs_s_status_t stcode,
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * Asynchronously output unistat info and possibly bytestreams to
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * userspace. The bytestream mechanism must have been initialized.
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * @param kstatus The status info pointer
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * @return SPCS_S_OK for normal completion, SPCS_S_ERROR otherwise
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * Specification TBD. Not in the 10/22/98 unistat commitment
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte#endif /* _SPCS_S_K_H */