documentation/ioport-trace-hints - wine - Git at Google

 cat > /dev/null <<EOF
 The above line is necessary, leave it alone!!
 --------------------------------------------------------------------

 DOING A HARDWARE TRACE IN WINE
 ------------------------------

 The primary reason to do this is to reverse engineer a hardware device
 for which you don't have documentation, but can get to work under Wine.

 This lot is aimed at parallel port devices, and in particular parallel port
 scanners which are now so cheap they are virtually being given away. The
 problem is that few manufactures will release any programming information which
 prevents drivers being written for Sane, and the traditional technique of using
 DOSemu to produce the traces does not work as the scanners invariably only have
 drivers for Windows.

 Please note that I have not been able to get my scanner working properly (a
 UMAX Astra 600P), but a couple of people have reported success with at least
 the Artec AS6e scanner. I am not in the process of developing any driver nor do
 I intend to, so don't bug me about it. My time is now spent writting programs
 to set things like battery save options under Linux on Toshiba laptops, ans as
 such I don't have any spare time for writting a driver for a parallel port
 scanner etc.

 Presuming that you have compiled and installed wine the first thing to do is is
 to enable direct hardware access to your parallel port. To do this edit
 wine.conf (usually in /usr/local/etc) and in the ports section add the
 following two lines

 read=0x378,0x379,0x37a,0x37c,0x77a
 write=0x378,x379,0x37a,0x37c,0x77a

 This adds the necessary access required for SPP/PS2/EPP/ECP parallel port on
 LPT1. You will need to adjust these number accordingly if your parallel port is
 on LPT2 or LPT0.

 When starting wine use the following command line, where XXXX is the program
 you need to run in order to access your scanner, and YYYY is the file your
 trace will be stored in:

     wine -debugmsg +io XXXX 2> >(sed 's/^[^:]*:io:[^ ]* //' > YYYY)

 You will need large amounts of hard disk space (read hundreds of megabytes if
 you do a full page scan), and for reasonable performance a really fast
 processor and lots of RAM.

 You might well find the log compression program that David Campbell
 <campbell@torque.net> wrote helpfull in reducing the size of the log files.
 This can be obtained by the following command:

     sh ioport-trace-hints

 This should extract shrink.c (which is located at the end of this file. Compile
 the log compression program by:

     cc shrink.c -o shrink

 Use the shrink program to reduce the physical size of the raw log as follows:

     cat log | shrink > log2

 The trace has the basic form of

     XXXX > YY @ ZZZZ:ZZZZ

 where XXXX is the port in hexidecimal being accessed, YY is the data written
 (or read) from the port, and ZZZZ:ZZZZ is the address in memory of the
 instruction that accessed the port. The direction of the arrow indicates
 whether the data was written or read from the port.

     > data was written to the port
     < data was read from the port


 My basic tip for interperating these logs is to pay close attention to the
 addresses of the IO instructions. There grouping and sometimes proximity should
 reveal the presence of subroutines in the driver. By studying the different
 versions you should be able to work them out. For example consider the
 following section of trace from my UMAX Astra 600P

     0x378 > 55 @ 0297:01ec
     0x37a > 05 @ 0297:01f5
     0x379 < 8f @ 0297:01fa
     0x37a > 04 @ 0297:0211
     0x378 > aa @ 0297:01ec
     0x37a > 05 @ 0297:01f5
     0x379 < 8f @ 0297:01fa
     0x37a > 04 @ 0297:0211
     0x378 > 00 @ 0297:01ec
     0x37a > 05 @ 0297:01f5
     0x379 < 8f @ 0297:01fa
     0x37a > 04 @ 0297:0211
     0x378 > 00 @ 0297:01ec
     0x37a > 05 @ 0297:01f5
     0x379 < 8f @ 0297:01fa
     0x37a > 04 @ 0297:0211
     0x378 > 00 @ 0297:01ec
     0x37a > 05 @ 0297:01f5
     0x379 < 8f @ 0297:01fa
     0x37a > 04 @ 0297:0211
     0x378 > 00 @ 0297:01ec
     0x37a > 05 @ 0297:01f5
     0x379 < 8f @ 0297:01fa
     0x37a > 04 @ 0297:0211

 As you can see their is a repeating structure starting at address 0297:01ec
 that consists of four io access on the parallel port. Looking at it the first
 io access writes a changing byte to the data port the second always writes the
 byte 0x05 to the control port, then a value which always seems to 0x8f is read
 from the status port at which point a byte 0x04 is written to the control port.
 By studying this and other sections of the trace we can write a C routine that
 emulates this, shown below with some macros to make reading/writing on the
 parallel port easier to read.


 #define r_dtr(x)        inb(x)
 #define r_str(x)        inb(x+1)
 #define r_ctr(x)        inb(x+2)
 #define w_dtr(x,y)      outb(y, x)
 #define w_str(x,y)      outb(y, x+1)
 #define w_ctr(x,y)      outb(y, x+2)

 /*
  * Seems to be sending a command byte to the scanner
  *
  */
 int udpp_put(int udpp_base, unsigned char command)
 {
         int loop,value;

         w_dtr(udpp_base, command);
         w_ctr(udpp_base, 0x05);

         for (loop=0;loop<10;loop++)
                 if (((value=r_str(udpp_base)) & 0x80)!=0x00) {
                         w_ctr(udpp_base, 0x04);
                         return value & 0xf8;
                         }

         return (value & 0xf8) | 0x01;
 }


 For the UMAX Astra 600P only seven such routines exist (well 14 really, seven
 for SPP and seven for EPP). Whether you choose to disassemble the driver at
 this point to verify the routines is your own choice. If you do, the address
 from the trace should help in locating them in the disassembly.

 You will probably then find it useful to write a script/perl/C program to
 analyse the logfile and decode them futher as this can reveal higher level
 grouping of the low level routines. For example from the logs from my UMAX
 Astra 600P when decoded futher reveal (this is a small snippet)


 start:
 put: 55 8f
 put: aa 8f
 put: 00 8f
 put: 00 8f
 put: 00 8f
 put: c2 8f
 wait: ff
 get: af,87
 wait: ff
 get: af,87
 end: cc
 start:
 put: 55 8f
 put: aa 8f
 put: 00 8f
 put: 03 8f
 put: 05 8f
 put: 84 8f
 wait: ff

 From this it is easy to see that put routine is often grouped together in five
 successive calls sending information to the scanner. Once these are understood
 it should be possible to process the logs further to show the higher level
 routines in an easy to see format. Once the highest level format that you
 can derive from this process is understood, you then need to produce a
 series of scans varying only one parameter between them, so you can
 discover how to set the various parameters for the scanner.


 Jonathan Buzzard
 <jab@hex.prestel.co.uk>


 --------------------------------------------------------------------
 The following is the shrink.c program.
 EOF
 cat > shrink.c <<EOF
 #include <stdio.h>
 #include <string.h>

 void
 main (void)
 {
   char buff[256], lastline[256];
   int count;

   count = 0;
   lastline[0] = 0;

   while (!feof (stdin))
     {
       fgets (buff, sizeof (buff), stdin);
       if (strcmp (buff, lastline) == 0)
 	{
 	  count++;
 	}
       else
 	{
 	  if (count > 1)
 	    fprintf (stdout, "# Last line repeated %i times #\n", count);
 	  fprintf (stdout, "%s", buff);
 	  strcpy (lastline, buff);
 	    count = 1;
 	}
     }
 }
 EOF
	cat > /dev/null <<EOF
	The above line is necessary, leave it alone!!
	--------------------------------------------------------------------

	DOING A HARDWARE TRACE IN WINE
	------------------------------

	The primary reason to do this is to reverse engineer a hardware device
	for which you don't have documentation, but can get to work under Wine.

	This lot is aimed at parallel port devices, and in particular parallel port
	scanners which are now so cheap they are virtually being given away. The
	problem is that few manufactures will release any programming information which
	prevents drivers being written for Sane, and the traditional technique of using
	DOSemu to produce the traces does not work as the scanners invariably only have
	drivers for Windows.

	Please note that I have not been able to get my scanner working properly (a
	UMAX Astra 600P), but a couple of people have reported success with at least
	the Artec AS6e scanner. I am not in the process of developing any driver nor do
	I intend to, so don't bug me about it. My time is now spent writting programs
	to set things like battery save options under Linux on Toshiba laptops, ans as
	such I don't have any spare time for writting a driver for a parallel port
	scanner etc.

	Presuming that you have compiled and installed wine the first thing to do is is
	to enable direct hardware access to your parallel port. To do this edit
	wine.conf (usually in /usr/local/etc) and in the ports section add the
	following two lines

	read=0x378,0x379,0x37a,0x37c,0x77a
	write=0x378,x379,0x37a,0x37c,0x77a

	This adds the necessary access required for SPP/PS2/EPP/ECP parallel port on
	LPT1. You will need to adjust these number accordingly if your parallel port is
	on LPT2 or LPT0.

	When starting wine use the following command line, where XXXX is the program
	you need to run in order to access your scanner, and YYYY is the file your
	trace will be stored in:

	wine -debugmsg +io XXXX 2> >(sed 's/^[^:]:io:[^ ] //' > YYYY)

	You will need large amounts of hard disk space (read hundreds of megabytes if
	you do a full page scan), and for reasonable performance a really fast
	processor and lots of RAM.

	You might well find the log compression program that David Campbell
	<campbell@torque.net> wrote helpfull in reducing the size of the log files.
	This can be obtained by the following command:

	sh ioport-trace-hints

	This should extract shrink.c (which is located at the end of this file. Compile
	the log compression program by:

	cc shrink.c -o shrink

	Use the shrink program to reduce the physical size of the raw log as follows:

	cat log \| shrink > log2

	The trace has the basic form of

	XXXX > YY @ ZZZZ:ZZZZ

	where XXXX is the port in hexidecimal being accessed, YY is the data written
	(or read) from the port, and ZZZZ:ZZZZ is the address in memory of the
	instruction that accessed the port. The direction of the arrow indicates
	whether the data was written or read from the port.

	> data was written to the port
	< data was read from the port


	My basic tip for interperating these logs is to pay close attention to the
	addresses of the IO instructions. There grouping and sometimes proximity should
	reveal the presence of subroutines in the driver. By studying the different
	versions you should be able to work them out. For example consider the
	following section of trace from my UMAX Astra 600P

	0x378 > 55 @ 0297:01ec
	0x37a > 05 @ 0297:01f5
	0x379 < 8f @ 0297:01fa
	0x37a > 04 @ 0297:0211
	0x378 > aa @ 0297:01ec
	0x37a > 05 @ 0297:01f5
	0x379 < 8f @ 0297:01fa
	0x37a > 04 @ 0297:0211
	0x378 > 00 @ 0297:01ec
	0x37a > 05 @ 0297:01f5
	0x379 < 8f @ 0297:01fa
	0x37a > 04 @ 0297:0211
	0x378 > 00 @ 0297:01ec
	0x37a > 05 @ 0297:01f5
	0x379 < 8f @ 0297:01fa
	0x37a > 04 @ 0297:0211
	0x378 > 00 @ 0297:01ec
	0x37a > 05 @ 0297:01f5
	0x379 < 8f @ 0297:01fa
	0x37a > 04 @ 0297:0211
	0x378 > 00 @ 0297:01ec
	0x37a > 05 @ 0297:01f5
	0x379 < 8f @ 0297:01fa
	0x37a > 04 @ 0297:0211

	As you can see their is a repeating structure starting at address 0297:01ec
	that consists of four io access on the parallel port. Looking at it the first
	io access writes a changing byte to the data port the second always writes the
	byte 0x05 to the control port, then a value which always seems to 0x8f is read
	from the status port at which point a byte 0x04 is written to the control port.
	By studying this and other sections of the trace we can write a C routine that
	emulates this, shown below with some macros to make reading/writing on the
	parallel port easier to read.


	#define r_dtr(x) inb(x)
	#define r_str(x) inb(x+1)
	#define r_ctr(x) inb(x+2)
	#define w_dtr(x,y) outb(y, x)
	#define w_str(x,y) outb(y, x+1)
	#define w_ctr(x,y) outb(y, x+2)

	/*
	* Seems to be sending a command byte to the scanner
	*
	*/
	int udpp_put(int udpp_base, unsigned char command)
	{
	int loop,value;

	w_dtr(udpp_base, command);
	w_ctr(udpp_base, 0x05);

	for (loop=0;loop<10;loop++)
	if (((value=r_str(udpp_base)) & 0x80)!=0x00) {
	w_ctr(udpp_base, 0x04);
	return value & 0xf8;
	}

	return (value & 0xf8) \| 0x01;
	}


	For the UMAX Astra 600P only seven such routines exist (well 14 really, seven
	for SPP and seven for EPP). Whether you choose to disassemble the driver at
	this point to verify the routines is your own choice. If you do, the address
	from the trace should help in locating them in the disassembly.

	You will probably then find it useful to write a script/perl/C program to
	analyse the logfile and decode them futher as this can reveal higher level
	grouping of the low level routines. For example from the logs from my UMAX
	Astra 600P when decoded futher reveal (this is a small snippet)


	start:
	put: 55 8f
	put: aa 8f
	put: 00 8f
	put: 00 8f
	put: 00 8f
	put: c2 8f
	wait: ff
	get: af,87
	wait: ff
	get: af,87
	end: cc
	start:
	put: 55 8f
	put: aa 8f
	put: 00 8f
	put: 03 8f
	put: 05 8f
	put: 84 8f
	wait: ff

	From this it is easy to see that put routine is often grouped together in five
	successive calls sending information to the scanner. Once these are understood
	it should be possible to process the logs further to show the higher level
	routines in an easy to see format. Once the highest level format that you
	can derive from this process is understood, you then need to produce a
	series of scans varying only one parameter between them, so you can
	discover how to set the various parameters for the scanner.


	Jonathan Buzzard
	<jab@hex.prestel.co.uk>


	--------------------------------------------------------------------
	The following is the shrink.c program.
	EOF
	cat > shrink.c <<EOF
	#include <stdio.h>
	#include <string.h>

	void
	main (void)
	{
	char buff[256], lastline[256];
	int count;

	count = 0;
	lastline[0] = 0;

	while (!feof (stdin))
	{
	fgets (buff, sizeof (buff), stdin);
	if (strcmp (buff, lastline) == 0)
	{
	count++;
	}
	else
	{
	if (count > 1)
	fprintf (stdout, "# Last line repeated %i times #\n", count);
	fprintf (stdout, "%s", buff);
	strcpy (lastline, buff);
	count = 1;
	}
	}
	}
	EOF