/* usb/lib/devmgr.h
 *
 * (c) 2002 Simtec Electronics
 *
 * Ben Dooks
 *
 * USB Library: interface to device management messages
 *
 * $Id: devmgr.h,v 1.11 2003/09/26 13:12:54 vince Exp $
 *
 * This Library file is part of the Simtec Electronics USB stack development
 *   suite.
 * Specific licence is granted to use this file by third parties for the
 *   development of USB device drivers.
*/

#ifndef __USB_LIB_DEVMGR_H
#define __USB_LIB_DEVMGR_H "$Id: devmgr.h,v 1.11 2003/09/26 13:12:54 vince Exp $"

/* functions to interface to the device management functions within the
 * usbcore / usbhub drivers. These use the relevant message calls, so
 * you must have a running usb message system at this point. You do not,
 * however, need to have any capability for receiving messages for these
 * to work.
*/

/** device manager: drop an device from the pool of registered devices
 *
 *
 *
 * @see USB_DEVMGR_RESULT_INVALID_ARGUMENT
 * @see USB_DEVMGR_RESULT_OK
 * @see USB_DEVMGR_RESULT_NOT_AVAILABLE
 */

extern int usb_devmgr_drop(struct usbmsg_new_device *dev);

/** device manager: release a claim of a device
 *
 * release the claim on the device, so that other drives may use it
 *
 * @see USB_DEVMGR_RESULT_INVALID_ARGUMENT
 * @see USB_DEVMGR_RESULT_OK
 * @see USB_DEVMGR_RESULT_NOT_AVAILABLE
 */

extern int usb_devmgr_release(struct usbmsg_new_device *dev, int advertise);

/** device manager: claim a device
 *
 * this will remove a device from the pool of available devices for
 * drivers to attach to
 *
 * @see USB_DEVMGR_RESULT_INVALID_ARGUMENT
 * @see USB_DEVMGR_RESULT_OK
 * @see USB_DEVMGR_RESULT_NOT_AVAILABLE
 * @see USB_DEVMGR_RESULT_ALREADYCLAIMED
 */

extern int usb_devmgr_claim(struct usbmsg_new_device *dev);

/** device manager: find unclaimed devices
 *
 * this will search the pool of devices and return a list of
 * free devices matching the given specification
 *
 * note, the function returns a negative form of the error codes on
 * failure. Any negative return codes should be considered an error,
 * and therefore any error code should be returned to a positive value
 * before checking against the result codes.
 *
 * @param done will be set to a non-zero value if done
 *
 * @see USB_DEVMGR_RESULT_INVALID_ARGUMENT
 * @see USB_DEVMGR_RESULT_OK
 * @see USB_DEVMGR_RESULT_NOT_AVAILABLE
 */

extern int usb_devmgr_find_free(int skip,
				int size,
				int *done,
				struct usbmsg_device_filter **filters,
				struct usbmsg_new_device    **newdev);

/* macros to put these back to the original defs */

#define usb_unclaimed_dev_drop(_a) usb_devmgr_drop(_a)
#define usb_unclaimed_dev_release(_a,_b) usb_devmgr_release(_a,_b)
#define usb_unclaimed_dev_claim(_a) usb_devmgr_claim(_a)
#define usb_unclaimed_dev_find(_a,_b,_c,_d,_e) usb_devmgr_find_free(_a,_b,_c,_d,_e)


/* utilities to go with these functions */

/** library function to find other interfaces on the same device
 *
 * This function takes a new device message, and looks for other free
 * interfaces on the same device.
 *
 * An negative result code is a negative version of the USB_DEVMGR_RESULT
 * error codes
 *
 * @return number of devices found, or negative for an error
 *
 * @param dev original new device message
 * @param results array of results
 * @param result_size maximum number of results to return
*/

int usblib_devmgr_findrelated(struct usbmsg_new_device *dev,
                              struct usbmsg_new_device **results,
                              int result_size);


#endif /* __USB_LIB_DEVMGR_H */
