#
#
# 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 2004 Sun Microsystems, Inc.	 All rights reserved.
# Use is subject to license terms.
#
# pragma ident	"@(#)README	1.4	06/03/18 SMI"
#

To Build:  make -f Makefile.sfw


------------
Bugid#: 5010373:
Need libusb library implementation in s10 freeware gate

Plugin Notes:
---------------

- Plugins implement the usb interfaces
  For interfaces that are not supported return ENOTSUP

- Implement bus / device support locally.
  Wrapper is responsible for presenting a unified global view

- There are two ways that interfaces can be handled.
  Either use the same symbol names as the usb.h interfaces
  or use a prefixed symbol
	Eg. usb_init
		ut_usb_init where the prefix is ut_
  The prefix info is read by the wrapper using a libusb_prefix
  symbol. This variable needs to be initialized by the plugin.

- If prefixed symbol is not being used please use the
  -B direct flag to ensure that symbol collision does not
  take place. i.e usb_xx symbol of the plugin does not collide
  with the usb_xx of the wrapper

- All plugin errors are simply passed up by the wrapper to the app.

- wrapper makes use of the following and these need to be implemented
  by the plugins
	- libusb_prefix
	- libusb_version
	- libusb_init
	- libusb_fini

	libusb_prefix:
	discussed earlier

	libusb_version:
	 will be  a const char * and initialzied by the
	plugin to following the ON library/module format of major
	# / minor #. So we will start with 1.1. Note that this has
	nothing to do with the libusb API version. The libusb
	API being implemented will occur in only two places.
	The version of the library will be reflected in the mapfiles
	of the wrapper and the plugin libraries.

	- DESC string of the package for the plugin
	- libusb-config file shipped with the wrapper

	Other than this the versioning of the wrapper and the packages
	and the versioning of the plugins will following the ON model.
	For minor changes to the interface 1.x -> 1.y. For interface
	changes that are not backward compatible (eg libusb 1.0) the
	versioning wil be changed to 2.x to reflect this.

	libusb_init:
	Return values are as follows:
		SUCCESS	- 	0
		FAILURE	-	-1
		PLUGIN_EXCLUSIVE	-2
	(Note: initial ARC case only specified the 0 and -1)
	The plugin exclusive will need to be added as closed fast
	track approved.

	PLUGIN_EXCLUSIVE is used to indicate to the wrapper that this
	plugin desires exclusive use and no other bus support will be
	visible to the application. This is a user settable feature
	and plugins can return SUCCESS/PLUGIN_EXCLUSIVE depending 
	upon the environment.

	libusb_fini:
		called by the wrapper when a plugin is unloaded.
		wrapper will not check the return values for this
	
wrapper notes:
----------------

wrapper is responsibe for the following:

	- loading the plugins
	- supporting alternate load dirs
	- loading all the plugin symbols
	- passing app calls to plugin calls.

The wrapper is also responsible for the following:

	- if multiple plugins are loaded and they are all active
	  then link up a busses pointer for each plugin to give the
	  app a unified view of the busses and the devices hanging off
	  of these busses.
	  This is done by the wrapper when the usb_find_busess is called
	  by the app and the wrapper makes successive find_busses calls
	  into each plugin

	-  The wrapper needs to be able to map a function call to the
	   correct plugin. For this reason it maintains a list of 
	   device handles for each plugin. When an app makes a call
	   and passes in the usb_dev_handle call the wrapper searches its
	   list of open device handles and finds the matching plugin to
	   use. For this reason add and delete of device handles is implemented
	   in the wrapper.

	- usb_strerror() - since we cannot tell which plugins error
	should be returned. not good to return all so we keep track
	of the last plugin that was called and return the strerror
	for the plugin.


Building the library:
	Since we are in the sfw gate the recommended approach 
	of ON library builds is not possible. One of the big departures
	is the use of mapfiles as opposed to spec files since there is
	no support for spec files in sfw gate. The approach taken
	is to use the sfw gate model of doing the top level builds
	(Makefile.sfw and installs) and using the ON model of doing
	the platforms specific builds (Makefile.com and sparc/Makefile ..)
	ON flags and environments are used for this.
	No support for lint and msg are provided in this build
	packaging follows the SFW gate model of packages

Indexes created Wed Nov 25 06:54:36 UTC 2009

Terms of Use | Privacy | Trademarks | Copyright Policy | Site Guidelines | Help
Your use of this web site or any of its content or software indicates your agreement to be bound by these Terms of Use.
Copyright © 1995-2008 Sun Microsystems, Inc.