/*
 * 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 2008 Sun Microsystems, Inc.  All rights reserved.
 * Use is subject to license terms.
 */

#ifndef	_SYS_USB_USBA_USBAI_PRIVATE_H
#define	_SYS_USB_USBA_USBAI_PRIVATE_H


/*
 * Unstable interfaces not part of USBAI but used by Solaris client drivers.
 * These interfaces may not be present in future releases and are highly
 * unstable.
 *
 * Status key:
 *	C = Remove from Sun client drivers before removing from this file
 *	D = May be needed by legacy (DDK) drivers.
 */

#ifdef	__cplusplus
extern "C" {
#endif

/*
 * convenience function for getting default config index
 * as saved in usba_device structure
 *
 * Status: C
 */
uint_t usb_get_current_cfgidx(dev_info_t *);

/*
 * **************************************************************************
 * Error and status definitions, and reporting functions
 * **************************************************************************
 */


/*
 * convenience functions to get string corresponding to value
 * usb_cb_flags_name requires a workbuffer of sufficient length
 * for the concatenation of all strings as usb_cb_flags_t is a bit
 * mask
 *
 * Status: C and D
 */
const char	*usb_str_cr(usb_cr_t cr);
char		*usb_str_cb_flags(usb_cb_flags_t cb_flags,
		char *buffer, size_t length);
const char	*usb_str_pipe_state(usb_pipe_state_t state);
const char	*usb_str_dev_state(int state);
const char	*usb_str_rval(int rval);

/* function convert a USB return value to an errno */
int		usb_rval2errno(int rval);

/*
 * **************************************************************************
 * Transfer-related definitions and functions
 * **************************************************************************
 */

/* Status C and D for whole section. */

/* Serialize callbacks per interface or device. */
#define	USB_FLAGS_SERIALIZED_CB	0x8000

/* default timeout for control requests (in seconds) */
#define	USB_PIPE_TIMEOUT	3

/*
 * usb_pipe_sync_ctrl_xfer():
 *	for simple synchronous control transactions this wrapper function
 *	will perform the allocation, xfer, and deallocation.
 *	USB_ATTRS_AUTOCLEARING will be enabled
 *
 * ARGUMENTS:
 *	dip		- pointer to clients devinfo.
 *	pipe_handle	- control pipe pipehandle (obtained via usb_pipe_open().
 *	bmRequestType	- characteristics of request.
 *	bRequest	- specific request.
 *	wValue		- varies according to request.
 *	wIndex		- index or offset.
 *	wLength		- number of bytes to xfer.
 *	data		- pointer to pointer to data
 *			  IN: HCD will allocate data
 *			  OUT: clients driver allocates data.
 *	attrs		- required request attributes.
 *	completion_reason - completion status.
 *	cb_flags	- request completions flags.
 *	flags		- none.
 *
 * RETURN VALUES:
 *	USB_SUCCESS	- request successfully executed.
 *	USB_FAILURE	- request failed.
 *
 * NOTES:
 * - in the case of failure, the client should check completion_reason and
 *   and cb_flags and determine further recovery action
 * - the client should check data and if non-zero, free the data on
 *   completion
 */
int usb_pipe_sync_ctrl_xfer(
	dev_info_t	*dip,
	usb_pipe_handle_t pipe_handle,
	uchar_t 	bmRequestType,
	uchar_t 	bRequest,
	uint16_t	wValue,
	uint16_t	wIndex,
	uint16_t	wLength,
	mblk_t		**data,
	usb_req_attrs_t attrs,
	usb_cr_t	*completion_reason,
	usb_cb_flags_t	*cb_flags,
	usb_flags_t	flags);

/*
 * **************************************************************************
 * Event registration / pre-suspend and post-resume handling
 * **************************************************************************
 */

/* Status: C and D for whole section. */

/*
 * Event registration info for both hotplug and pre-suspend/post-resume
 * callbacks.  Eventually pre-suspend and post-resume callbacks will not be
 * needed, so this is for this OS release only and will go away in a
 * subsequent release.
 */
typedef struct usb_event {
	/* device disconnected/unplugged */
	int	(*disconnect_event_handler)(dev_info_t *dip);

	/* device reconnected */
	int	(*reconnect_event_handler)(dev_info_t *dip);

	/* notification that system is about to checkpoint */
	int	(*pre_suspend_event_handler)(dev_info_t *dip);

	/* notification that system resumed after a checkpoint */
	int	(*post_resume_event_handler)(dev_info_t *dip);
} usb_event_t;

/*
 * Event callbacks
 *	the callbacks should always return USB_SUCCESS.
 */
int usb_register_event_cbs(
	dev_info_t	*dip,
	usb_event_t	*usb_evt_data,
	usb_flags_t	flags);

void usb_unregister_event_cbs(
	dev_info_t	*dip,
	usb_event_t	*usb_evt_data);

/*
 * USB CPR support
 *	A client driver must call this funtion in pre-suspend event handler
 *	to inform the USBA framework that it can't suspend because
 *	driver instance or device could not be quiesced.
 */
void usb_fail_checkpoint(
	dev_info_t	*dip,
	usb_flags_t	flags);


/*
 * **************************************************************************
 * Logging functions remaining Contracted Consolidation Private
 * **************************************************************************
 */

/* Status: C and D for whole section. */

/*
 * Usb logging, debug and console message handling.
 */
typedef struct usb_log_handle *usb_log_handle_t;

#define	USB_LOG_L0	0	/* warnings, console & syslog buffer */
#define	USB_LOG_L1	1	/* errors, syslog buffer */
#define	USB_LOG_L2	2	/* recoverable errors, debug only */
#define	USB_LOG_L3	3	/* interesting data, debug only */
#define	USB_LOG_L4	4	/* tracing, debug only */

#ifdef DEBUG
#define	USB_DPRINTF_L4(...)	usb_dprintf4(__VA_ARGS__)
#define	USB_DPRINTF_L3(...)	usb_dprintf3(__VA_ARGS__)

/*PRINTFLIKE3*/
void usb_dprintf4(
	uint_t		mask,
	usb_log_handle_t handle,
	char		*fmt, ...);
/*PRINTFLIKE3*/
void usb_dprintf3(
	uint_t		mask,
	usb_log_handle_t handle,
	char		*fmt, ...);
#else
#define	USB_DPRINTF_L4(...)	((void)0)
#define	USB_DPRINTF_L3(...)	((void)0)
#endif

#define	USB_DPRINTF_L2	usb_dprintf2
#define	USB_DPRINTF_L1	usb_dprintf1
#define	USB_DPRINTF_L0	usb_dprintf0

/*PRINTFLIKE3*/
void usb_dprintf2(
	uint_t		mask,
	usb_log_handle_t handle,
	char		*fmt, ...);
/*PRINTFLIKE3*/
void usb_dprintf1(
	uint_t		mask,
	usb_log_handle_t handle,
	char		*fmt, ...);
/*PRINTFLIKE3*/
void usb_dprintf0(
	uint_t		mask,
	usb_log_handle_t handle,
	char		*fmt, ...);

usb_log_handle_t usb_alloc_log_hdl(
	dev_info_t	*dip,
	char		*name,
	uint_t		*errlevel,
	uint_t		*mask,
	uint_t		*instance_filter,
	usb_flags_t	flags);

/* free the log handle */
void usb_free_log_hdl(
	usb_log_handle_t handle);

/* log message */
/*PRINTFLIKE4*/
int usb_log(
	usb_log_handle_t handle,
	uint_t		level,
	uint_t		mask,
	char		*fmt, ...);

/*
 * usb_check_same_device:
 *	Check if the device connected to the port is the same as
 *	the previous device that was in the port.  The previous device is
 *	represented by the dip on record for the port.	Print a message
 *	if the device is different.  If device_string arg is not NULL, it is
 *	included in the message.  Can block.
 *
 * Arguments:
 *	dip			- pointer to devinfo of the client
 *	log_handle		- handle to which messages are logged
 *	log_level		- one of USB_LOG_*
 *	log_mask		- logging mask
 *	check_mask		- one mask containing things to check:
 *					USB_CHK_BASIC: empty mask;
 *						these checks are always done.
 *					USB_CHK_SERIAL: check match on device
 *						serial number.
 *					USB_CHK_CFG: compare config clouds
 *						byte by byte
 *					USB_CHK_VIDPID: compare product
 *						and vendor ID
 *					USB_CHK_ALL: perform all checks
 *
 *				NOTE: descr length and content always checked
 *	device_string		- Device string to appear in error message
 *
 * return values:
 *	USB_SUCCESS:		same device
 *	USB_INVALID_VERSION	not same device
 *	USB_FAILURE:		Failure processing request
 *	USB_INVALID_ARG:	dip is invalid
 */

/* Checking bits for checks made by usb_check_same_device */
#define	USB_CHK_BASIC	0		/* Empty mask.	Basics always done. */
#define	USB_CHK_SERIAL	0x00000001	/* Compare device serial numbers. */
#define	USB_CHK_CFG	0x00000002	/* Compare raw config clouds. */
#define	USB_CHK_VIDPID	0x00000004	/* Compare product and vendor ID. */
#define	USB_CHK_ALL	0xFFFFFFFF	/* Perform maximum checking. */

int usb_check_same_device(
	dev_info_t		*dip,
	usb_log_handle_t	log_handle,
	int			log_level,
	int			log_mask,
	uint_t			check_mask,
	char			*device_string);

/*
 * **************************************************************************
 * Power management functions remaining Contracted Consolidation Private
 * **************************************************************************
 */

/*
 * usb wrapper around pm_raise_power & pm_lower_power to allow for
 * non blocking behavior
 *
 * Arguments:
 *	dip		- pointer to devinfo node of client.
 *	comp		- component.
 *	level		- power level.
 *	flags		- USB_FLAGS_SLEEP:
 *				wait for completion.
 *	cb		- function called on completion, may be NULL.
 *	arg		- callback argument.
 *	rval		- USB_SUCCESS or USB_FAILURE.
 *
 * Return Values:
 *	USB_SUCCESS	-  if no USB_FLAGS_SLEEP has been specified, the request
 *			   has been queued for async execution. If
 *			   USB_FLAGS_SLEEP has been specified, the raising or
 *			   lowering of power
 *			   succeeded.
 *	USB_FAILURE	-  request could not be queued or raising or lowering
 *			   of power failed.
 */

/* Status: C and D */
int usb_req_raise_power(
	dev_info_t	*dip,
	int		comp,
	int		level,
	void		(*cb)(void *arg, int rval),
	void		*arg,
	usb_flags_t	flags);

/* Status: D */
int usb_req_lower_power(
	dev_info_t	*dip,
	int		comp,
	int		level,
	void		(*cb)(void *arg, int rval),
	void		*arg,
	usb_flags_t	flags);

/*
 * USB wrapper functions to set usb device power level.
 * Note : Power levels indicated here are USB power levels
 * and not OS power levels.
 *
 * Note that these were never implemented, and are noops.  However, they are
 * included here as the skeleton driver in DDK 0.8 and 0.9 mentioned them.
 *
 * Status: C and D.
 */
int usb_set_device_pwrlvl0(
	dev_info_t	*dip);
int usb_set_device_pwrlvl1(
	dev_info_t	*dip);
int usb_set_device_pwrlvl2(
	dev_info_t	*dip);
int usb_set_device_pwrlvl3(
	dev_info_t	*dip);


/*
 * **************************************************************************
 * Serialization functions remaining Contracted Consolidation Private
 * **************************************************************************
 */

/* This whole section: status: C and D. */

/*
 * opaque serialization handle.
 *	Used by all usb_serialization routines.
 *
 *	This handle is opaque to the client driver.
 */
typedef	struct usb_serialization	*usb_serialization_t;

/*
 * usb_init_serialization
 *	setup for serialization
 *
 * ARGUMENTS:
 *	s_dip		- devinfo pointer
 *	flag		- USB_INIT_SER_CHECK_SAME_THREAD
 *			  when set, usb_release_access() will
 *			  verify that the same thread releases
 *			  access. If not, a console warning will
 *			  be issued but access will be released
 *			  anyways.
 *
 * RETURNS:
 *	usb_serialization handle
 *
 */
usb_serialization_t usb_init_serialization(
	dev_info_t	*s_dip,
	uint_t		flag);

#define	USB_INIT_SER_CHECK_SAME_THREAD	1

/* fini for serialization */
void usb_fini_serialization(
	usb_serialization_t usb_serp);

/*
 * Various ways of calling usb_serialize_access.  These correspond to
 * their cv_*wait* function counterparts for usb_serialize_access.
 */
#define	USB_WAIT		0
#define	USB_WAIT_SIG		1
#define	USB_TIMEDWAIT		2
#define	USB_TIMEDWAIT_SIG	3

/*
 * usb_serialize_access:
 *	acquire serialized access
 * ARGUMENTS:
 *	usb_serp	- usb_serialization handle
 *	how_to_wait	- Which cv_*wait* function to wait for condition.
 *				USB_WAIT:		use cv_wait
 *				USB_WAIT_SIG:		use cv_wait_sig
 *				USB_TIMEDWAIT:		use cv_timedwait
 *				USB_TIMEDWAIT_SIG:	use cv_timedwait_sig
 *	delta_timeout	- Time in ms from current time to timeout.  Checked
 *			  only if USB_TIMEDWAIT or USB_TIMEDWAIT_SIG
 *			  specified in how_to_wait.
 * RETURNS:
 *	Same as values returned by cv_*wait* functions,
 *	except for when how_to_wait == USB_WAIT, where 0 is always returned.
 *	For calls where a timeout or signal could be expected, use this value
 *	to tell whether a kill(2) signal or timeout occurred.
 */
int usb_serialize_access(
	usb_serialization_t	usb_serp,
	uint_t			how_to_wait,
	uint_t			delta_timeout);

/*
 * usb_try_serialize_access:
 *	try acquiring serialized access
 *
 * ARGUMENTS:
 *	usb_serp	- usb_serialization handle
 *	flag		- unused
 *
 * RETURNS:
 *	USB_SUCCESS	- access has been acquired
 *	USB_FAILURE	- access has not been acquired
 */
int usb_try_serialize_access(usb_serialization_t usb_serp, uint_t flag);

/*
 * usb_release_access:
 *	release serialized access
 *
 * ARGUMENTS:
 *	usb_serp	- usb_serialization handle
 */
void usb_release_access(usb_serialization_t usb_serp);


/*
 * **************************************************************************
 * Asynchronous functions remaining Contracted Consolidation Private
 * **************************************************************************
 */

/* This whole section: status: C and D. */

/* For async_req functions. */
#define	USB_FLAGS_NOQUEUE	0x200

/*
 * Issue a request to the asynchronous request service
 * All async request functions return USB_SUCCESS or USB_FAILURE
 * Arguments:
 *	dip		- pointer to devinfo node
 *	func		- pointer of function to execute asynchronously
 *	arg		- argument to function
 *	flag		- USB_FLAGS_SLEEP or USB_FLAGS_NOSLEEP or
 *			  USB_FLAGS_NOQUEUE
 * Return Values:
 *	USB_SUCCESS	- function was scheduled
 *	USB_FAILURE	- function could not be scheduled
 *
 * Flag combinations:
 *	SLEEP		- block waiting for resources. always succeeds
 *	NOSLEEP		- do not wait for resources, may fail.
 *	NOSLEEP+NOQUEUE - do not wait for resources, do not queue
 *	SLEEP+NOQUEUE	- block waiting for resources but may still fail
 *			  if no thread available
 */
int usb_async_req(
	dev_info_t	*dip,
	void		(*func)(void *),
	void		*arg,
	usb_flags_t	flag);


/*
 * index for getting to usb_pipehandle_list in usba_device
 */
uchar_t usb_get_ep_index(uint8_t ep_addr);


#ifdef ALLOCB_TEST
#define	allocb(s, p) usba_test_allocb(s, p)
mblk_t *usba_test_allocb(size_t, uint_t);
#endif /* ALLOCB_TEST */

/* create an USB style M_CTL message */
mblk_t *usba_mk_mctl(struct iocblk, void *, size_t);

#ifdef __cplusplus
}
#endif

#endif	/* _SYS_USB_USBA_USBAI_PRIVATE_H */