PC/SC CLIENT-SIDE DEBUGGING (libpcsclite.so.1):
---------------------------------------------------------------------------
libpcscshim is a library that interposes *between* a client application and
libpcsclite.so.1 (the PC/SC-lite API library) intercepting all API calls.  

+--------------------+
| Client Application |
+---------+----------+
          |
+---------+----------+
| libpcscshim.so.1   |  <-- 'interposed' via LD_PRELOAD
+---------+----------+
          |
+---------+----------+
| libpcsclite.so.1   |  PC/SC-lite API implementation
+--------------------+


If the application is Sun Ray Connector, the local PC/SC client will be uttsc,
and the end-consumer client application is remote (on the Windows machine). 
The application running on Windows might be internal to Windows, or 3rd party
middleware, or other type of application.  Different mechanisms are used to enable 
interposing depending on whether Sun Ray Windows Connector is involved or not.  
The details are explained below.

Call arguments passed from the client application to PC/SC-lite API functions
are dereferenced where possible.  For example, where an argument is the address 
of a string, the actual string passed between the client and library is displayed 
rather than the address of the string, which would be of no use to anyone reading 
the log file.  

All transactions are logged to a user-specified location in human-readable format.  
Interposing *between* the client and libpcsclite.so.1 is a good place to diagnose
disagreements in data flow between the client application and PC/SC-lite.  That
interposing position is also helpful in determining which layer a problem is occuring 
in, ie. above PC/SC-lite, or within or below PC/SC-lite.



CONFIGURING THE libpcscshim.so.1 INTERPOSER LIBRARY:

There are two basic interposing scenarios  For most server-side applications,
the mechanism to activate the 'libpcscshim' interposer is to set LD_PRELOAD 
environment variable to the full path of libpcscshim.so.1.  The other scenario
is when Sun Ray Windows Connector is the direct client of libpcsclite.so.1.
The following show the specific configurations for each of the two situation:

	---------------------------------------------------
	    Non-Sun Ray Connector Interposing instructions
	---------------------------------------------------
	For example, if libpcscshim is in the current directory you run your
	application from and you're using a bash-like shell:

	$ LD_PRELOAD=$PWD/libpcscshim.so.1

	(LD_PRELOAD should only be set for the duration of the run of the
	target application, as it might interfere with other UNIX commands
	issued beyond that).

	The shim requires some arguments to be passed through a seperate
	environment variable: "LIBPCSCSHIM". 

	Required arguments are:

		-l   Switch on API transaction logging.
		-i   Specify path of target library to interpose on
		-o   <filename>   Direct log to a file


	Example (using bash shell):

	    $ export LIBPCSCSHIM="-l -i /usr/lib/libpcsclite.so.1 -o /tmp/shim.log"
	    $ LD_PRELOAD=$PWD/libpcscshim.so.1  ./my_pcsclite_app

	   (NOTE: If libpcscshim is not in your current directory, replace 
		  $PWD with the full path of libpcscshim.so.1)


	---------------------------------------------
	  Sun Ray Connector Interposing Instructions
	---------------------------------------------
	Because Sun Ray Connector uses setgid and has other security
	measures to support Trusted Extensions, LD_PRELOAD cannot
	be used, but rather a 'backdoor' hook in Sun Ray Connector
        in must be used instead, as follows:

	   $ export LIBPCSCSHIM="-l -i /usr/lib/libpcsclite.so.1 -o /tmp/shim.log"
	   $ export SUN_LIB_PCSCLITE=$PWD/libpcscshim.so.1  

	   (NOTE: If libpcscshim is not in your current directory, replace 
	       $PWD with the full path of libpcscshim.so.1)


DISCLAIMER:

While this library has worked well for most applications tested, it has been 
known to dump core in certain (rare) circumstances.  Unfortunately we haven't 
received a reproduceable test case or any useful core dump to analyze.
To help improve the quality, if a core dump occurs when using the
interposer, please send the core dump, and clear specific reproduceable 
test case instructions, to the appropriate Sun representitive.  Along
with the log file to the point it was created before the core dump occurs.



PC/SC SERVER-SIDE DEBUGGING
----------------------------------------------------------------------------

The PC/SC daemon provided in the SUNWpcsc package runs in two complimentary
modes.  In one mode it behaves as a launcher daemon (a daemon that spawns worker 
daemons we call instances).  In launcher/instance mode the same binary is used, 
but is ssimply invoked with different flags.  The actual launching of the daemons 
is done automatically by the OS framework.  The end user never launches pcscd 
directly from the command line in launcher/instance mode.

Generally the most useful server-side debug log to acquire is the log of an instance.
Launcher problems affecting clients are rare, so generally a launcher log is not 
requested initially during diagnosis. 

It is easy to determine which pcscd processes are instances and which is the
launcher.  The launcher shows up in ps output as 'pcscd -L ...'.  Instances 
launched by the launcher appear as 'pcscd -I -x <dpy#>'  where the argument 
after the -x flag identifies the display the instance is sevicing.

An instance is created by the launcher hen a PC/SC-lite client application 
calls the SCardEstablishContext() function (part of the PC/SC-lite API), and 
the launcher determines there is no instance already running to handle 
client requests for the client's $DISPLAY number.


   ----------------------------------------------
    CONFIGURING INSTANCE DEBUGGING (pcscd -I):
   ----------------------------------------------

     Errors that involve smartcard transactions that occur in a pcscd instance
     are initially diagnosed using tools like pstack and core dumps,
     as well as by enabling instance debugging, which is not enabled
     by default.  

     Typically, the starting point of diagnosis acquiring a libpcscshim log, 
     and also a pcscd instance log.  Sometimes the latter isn't necessary,
     the answer is found in the shim log, but to request both saves time
     going back and forth between the customers and developers.

     When an application or application thread hangs or stalls,  it is always
     a good idea to run the pstack command on the associated pcscd -I process,
     and also of the client application (or uttsc if Sun Ray Windows Connector
     is being used).  This helps determine where things are hanging.  In some
     cases a gcore may also be requested.  

     To enable debug logging for the instance:

     1.  Edit /etc/smartcard/pcscd-SunRay.conf 

     2.  Uncomment the commented lines.

     NOTE:  The default value of the IFDH_SCBUS_DEBUG is usually
             the initially appropriate value, unless problems are traced
             to the IFD handler, at which time a value of logically OR'ed 
             bits might be selected, wheren a value of 7 enables full (but
             volumous) IFD handler logging.

     By default the log fill will be put in a file called /tmp/dbg.
     Any absolute path can be specified , but if the leading '/' is ommitted,
     the file will be created as a subdirectory of /tmp/SUNWut/pcsc/<dpy#>
     where <dpy#> is the number before the ":" in the $DISPLAY variable
   
     The log file is only created only after the instance is re-launched.
     If a pcscd -I instance is already running for the display, it 
     should be terminated with kill -9 (and the corresponding
     utaction script can be terinated by the user with kill -9 too).  
     The next time the instance is launched as a result of PC/SC lite 
     client activity, the log will be created.


    LAUNCHER DEBUGGING (pcscd -L)

     The launcher is generally not a debugging target, but it can
     be set up to log:

     $ svcadm disable pcscd   # Tell SMF to stop pcscd and not restart it
     $ sleep 1                # necessary only if running these cmds in a script
     $ rm -rf /tmp/SUNWut/pcscd/* /var/run/pcscd/*
     $ sh /lib/svc/method/pcscd-svc debug

    The output of this can be captured or cut and pasted.

    It is not advised to collect launcher debuggging output unless 
    requested by support, or you have a good reason to believe
    the problem experienced is directly related to launching
    or instances failing to start, etc...

