;---------------------------------------------------------------
; DSKWAV.DOC
; Keith Larson
; TMS320 DSP Applications
; (C) Copyright 1996
; Texas Instruments Incorporated
;
; This is unsupported freeware with no implied warranties or
; liabilities.  See the C3x DSK disclaimer document for details
;----------------------------------------------------------------
OVERVIEW
--------
DSKWAV.ASM (DSKWAV.DSK) is the program the runs on the C31 DSK and
DSK_WAV.EXE is the program that runs on the PC to control DSKWAV.ASM

  DSK_WAV.EXE can be used concurrently with programs like MEMVIEW.EXE but
requires MEMVIEW to have the T=xxx command line option be set to 20 or
higher.

 Also, since MEMVIEW queries and modifies some C3x kernel information during
startup, you should not be playing or recording a wave file when you start
MEMVIEW.  To use MEMVIEW with DSK_WAV, start MEMVIEW as shown below.

    C:\DSKTOOLS\MEMVIEW T=20 LPT2

USING THE DMA FOR FOR COMMANDS, PLAY AND RECORD
-----------------------------------------------
  Transferring 32 bit commands and data to and from the host requires that
the data be broken into smaller chunks that can be transferred accross
either an 8 or 4 bit printer port channel.  Furthermore, it is also desired
that the mode of transfer be automatically determined from the port values
stored in the comm/debug kernel.

  The printer port readback shift value, or bit width, is read from location
0x809FFF in internal RAM.  The values are either -4 for nibble readback or
-8 for bi-directional byte readback mode.  The C3X.DSK kernel uses the value
stored at this location to determine the correct shift to apply to the data
readback bits during a DSK to host transfer.  In Host to DSK transfers the
number of bits is always 8 bits.

  For the DMA to transfer data from the host to the C31, the CPU needs to
read the data in byte wide chunks, or 4 bytes per 32 bit transfer.  When the
DMA buffer has been received it is then unpacked into a 32 bit array that
the C31 can operate on directly.

  There are two types of buffers that can be used for host to C31 DSK
transfers.  One is for receiving command packets that direct the actions to
take, and the other is for data.  Data transfers are distinguished by the
addition of a buffer interlock flag with the play and record routines.  This
flag is essentialy zero until the current play or record buffer is exhausted.
When the last value in the play/record buffer has been used, the flag is set
allowing the DMA subroutine to unpack the buffer.  This creates a double
buffer in software that prevents incoming packets from corrupting the
play/rec buffer.

  For the DMA to transfer data to the host, the CPU first needs to unpack
the data into a transmit buffer before.  The length of the DMA transfer
would then be the number 32 values to send times the number of shifts per
32 bit transfer.



NOTES
-----
  4 bit transfers require 8 DMA locations per 32 bit transfer.  The maximum
  DMA buffer that is allocated is 1024 words, which corresponds to 128 32
  bit values, or 256 analog samples.

  For the C32, 8 bit transfer modes can occur automaticly by setting the
  external bus width parameter to 8 bits.  For 4 bit nibble transfers, the
  C32 would still be required to unpack the data into a buffer before
  transmitting data to the host.

EXTENDED AND NORMAL COMMANDS
----------------------------
  DSKWAV.ASM differs from most other DSK applications in that a patch is made
to the C3X.DSK communications and debug kernel to allow the use of the DMA
for transferring data and commands.

  The patch begins by having DSKWAV initialize the DMA to receive a command
word from the host.  During this time, the INT2 is completely disabled,
allowing the DMA full uninterrupted access to the host port.  Note that in
future versions, a modified C3X.DSK kernel could use INT2 to synchronize
DMA transfers to and from the host.

  The 32 bit value which is received is then compared (similar to a C
switch statment) to determine if the command is either a DSKWAV extended
command (value=9) or a DSK kernel command.  If the command is a kernel
command, the appropriate registers corresponding to a command received by
the kernel are pushed onto the stak and then execution branches to the
kernel switch table.

  If the command is a DSKWAV extended command, a second DMA block transfer
is initiated to receive the DSKWAV setup parameters.  This block transfer is
7 32 bit words long and contains information for record/play mode,
initializing the AIC, timer and data block transfer length.

HOST SIDE APPLICATION CODE (DSK_WAV.CPP)
----------------------------------------
  The program running on the host is responsible for reading and writing
WAV file data, in the correct format, to and from the PCs hard disk drive.
In addition to this, the host application code is used to setup the AIC
and timer register values.  The commands and data are then packed into
arrays of 32 bit values which are transferred to and from the DSK target
interface.

ADC/DAC BUFFERING
-----------------
  To preserve as much on-chip memory as possible for buffering, the ADC/DAC
data is packed as two 16 bit values per 32 bit location in memory.  To
access the upper and lower 16 bit fields, the address used to lookup the
data is modified by a HILO bit that toggles with each ADC/DAC interrupt.

  When the buffer is exhausted the AICDONE flag is set, indicating to the
background DMA task that it is OK to unpack the DMA buffer to the analog
play/record buffer.  At this time, the data pointer is also reloaded to the
beginning of the buffer.

CONCLUSION
----------
DSKWAV.ASM extends the capabilities of the C3X.DSK comm/debug kernel to
greatly enhance the performance of the host interface, essentially allowing
far better control of an application from the host interface while
maintaining ease of use.  The major tradeoff is that a kernel based on DMA
transfers consumes more on-chip memory and involves a higher level of
understanding of how the kernel operates.

KEL

