README file for 5600x disassembly library, version 1.2
=======================================================


Before you start.
=================

Both the code and this readme are quite old and it shows. If someone would
be willing to improve either or all of: build system, library design (er, is
there any?) or this doc -- please feel free. The project is now available on
SourceForge (https://sourceforge.net/projects/lib5600x/).


What?
=====

This archive contains source code of DSP5600x disassembly library. Examples
of usage and test files are also included.


Why?
====

The project was started because I needed a tool to help me explore the
firmware of my DSP-featuring sound board.  It evolved into ANSI-C link
library that may be useful to someone, so I am releasing it with BSD-style
license -- basically, you can do everything with it (including making
money), just remember to give credit where it's due.  For details see the
source code.


How?
====

As usual, I lack time to write big and nice doc file, but I hope that the
API is simple and clear enough to make up for this.  Let's see what you
have to do to disassemble some 5600x code:

1. First you call two initialization functions in the library. This step
is mandatory:

	make_masks();
	make_masks2();             NO LONGER NEEDED - FUNCTIONS REMOVED

You pass nothing and check for no results -- these functions are guaranteed
to succeed.

2. Now you have to allocate memory for a structure that will be used for
passing data to/from the library. You may do that on the stack

	struct disasm_data dis, *d = &dis;

Yes, the pointer will be useful, too. The disasm_data structure is defined
in 5600x_disasm.h file. Let's take a closer look:


#define LINE_SIZE	256

struct disasm_data
{
	unsigned char *memory;
	char line_buf[LINE_SIZE];
	char *line_ptr;
	char words;
};


First member -- "memory" -- should point to the opcode you want
disassembled.  IMPORTANT!  The library expects it to be a 24-bit word, so
if your assembler creates 32-bit words, you'll have to make a simple
conversion.  Take a look at d56.c to see how it is done.  What's more, the
library may wish to evaluate two words at a time, so you have to account
for that -- this is also demonstrated in the example source.


3. After properly setting up disasm_data struct (i.e. "memory" pointer),
you call following function:

	int disassemble_opcode(struct disasm_data *);


This function takes pointer to the struct you've just prepared as an
argument. When it returns, disasm_data struct's "line_buf" member contains
the disassembled opcode as a string of ASCII characters. "line_ptr" should be
of no interest to you (it is merely a internal variable) and "words" holds
the number of 24-bit words you should advance your memory pointer by. This
variable is also available as a return value of above function. Again, I
shall refer you to the example source.


4. Repeat step 3 until you run out of code to disassemble.



TESTING
=======

First, check out the makefile and make sure it contains proper flags and
defines for your architecture. Big endian users should add -DBIGENDIAN to
CFLAGS (I'd appreciate if someone created Autoconf script to avoid such
tricks). Following that, type

make
./d56 example_dsp_binary

and compare the output (visually) with example.a56 which is a source code I
used to create example_dsp_binary and which contains all instructions and
addressing modes described in DSP56000/DSP56001 Digital Signal Processor
User's Manual.  You can also 'diff' your output and supplied example.out
file to check if there are any differences (there should be none).


WARRANTIES
==========

No way.  I compiled and ran it under NetBSD/m68k 1.3, Irix 6.2, AmigaOS
3.0 and Linux/i386.  It isn't very well optimized and badly needs some
comments.  Maybe in the future.


Author
======

Miloslaw Smyk

Email: thorgal@wfmh.org.pl
WWW (way outdated): http://wfmh.org.pl/~thorgal/