/*
 * 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_DCOPY_DEVICE_H
#define	_SYS_DCOPY_DEVICE_H

#ifdef __cplusplus
extern "C" {
#endif

#include <sys/types.h>
#include <sys/dcopy.h>

/*
 * private command state. Space for this structure should be allocated during
 * (*cb_cmd_alloc). The DMA driver must set dp_private in dcopy_cmd_t to point
 * to the memory it allocated. Other than pr_device_cmd_private, the DMA driver
 * should not touch any of the fields in this structure. pr_device_cmd_private
 * is a private pointer for the DMA engine to use.
 */
struct dcopy_cmd_priv_s {
	/*
	 * we only init the state used to track a command which blocks when it
	 * actually blocks. pr_block_init tells us when we need to clean it
	 * up during a cmd_free.
	 */
	boolean_t		pr_block_init;

	/* dcopy_poll blocking state */
	list_node_t		pr_poll_list_node;
	volatile boolean_t	pr_wait;
	kmutex_t		pr_mutex;
	kcondvar_t		pr_cv;

	/* back pointer to the command */
	dcopy_cmd_t		pr_cmd;

	/* shortcut to the channel we're on */
	struct dcopy_channel_s	*pr_channel;

	/* DMA driver private pointer */
	void			*pr_device_cmd_private;
};

/* cb_version */
#define	DCOPY_DEVICECB_V0	0

typedef struct dcopy_device_chaninfo_s {
	uint_t	di_chan_num;
} dcopy_device_chaninfo_t;

typedef struct dcopy_device_cb_s {
	int	cb_version;
	int	cb_res1;

	/* allocate/free a DMA channel. See dcopy.h for return status  */
	int	(*cb_channel_alloc)(void *device_private,
		    dcopy_handle_t handle, int flags, uint_t size,
		    dcopy_query_channel_t *info, void *channel_private);
	void	(*cb_channel_free)(void *channel_private);

	/* allocate/free a command. See dcopy.h for return status  */
	int	(*cb_cmd_alloc)(void *channel_private, int flags,
		    dcopy_cmd_t *cmd);
	void	(*cb_cmd_free)(void *channel_private, dcopy_cmd_t *cmd);

	/*
	 * post a command/poll for command status. See dcopy.h for return
	 * status
	 */
	int	(*cb_cmd_post)(void *channel_private, dcopy_cmd_t cmd);
	int	(*cb_cmd_poll)(void *channel_private, dcopy_cmd_t cmd);

	/*
	 * if dcopy_device_unregister() returns DCOPY_PENDING, dcopy will
	 * call this routine when all the channels are no longer being
	 * used and have been free'd up. e.g. it's safe for the DMA driver
	 * to detach.
	 *   status = DCOPY_SUCCESS || DCOPY_FAILURE
	 */
	void	(*cb_unregister_complete)(void *device_private, int status);
} dcopy_device_cb_t;


typedef struct dcopy_device_info_s {
	dev_info_t		*di_dip;
	dcopy_device_cb_t	*di_cb; /* must be a static array */
	uint_t			di_num_dma;
	uint_t			di_maxxfer;
	uint_t			di_capabilities;
	uint64_t		di_id;
} dcopy_device_info_t;

typedef struct dcopy_device_s *dcopy_device_handle_t;

/* dcopy_device_notify() status */
#define	DCOPY_COMPLETION	0

/*
 * dcopy_device_register()
 *   register the DMA device with dcopy.
 *    return status => DCOPY_FAILURE, DCOPY_SUCCESS
 */
int dcopy_device_register(void *device_private, dcopy_device_info_t *info,
    dcopy_device_handle_t *handle);

/*
 * dcopy_device_unregister()
 *   try to unregister the DMA device with dcopy. If the DMA engines are
 *   still being used by upper layer modules, DCOPY_PENDING will be returned.
 *    return status => DCOPY_FAILURE, DCOPY_SUCCESS, DCOPY_PENDING
 *      if DCOPY_PENDING, (*cb_unregister_complete)() will be called when
 *      completed.
 */
int dcopy_device_unregister(dcopy_device_handle_t *handle);

/*
 * dcopy_device_channel_notify()
 *   Notify dcopy of an event.
 *     dcopy_handle_t handle => what was passed into (*cb_alloc)()
 *     status => DCOPY_COMPLETION
 */
void dcopy_device_channel_notify(dcopy_handle_t handle, int status);

#ifdef __cplusplus
}
#endif

#endif /* _SYS_DCOPY_DEVICE_H */