

              Watch your daughters, SCYNACORE prod. is back!


                                 DSPdit

                        -THE devkit for the DSP-



# This software may not be sold or published on CDs, via PDL etc without 
# written permission of the authors. QDSP-ASM is (c) by Gilles Audoly and 
# DSPdit is (c) by Andreas John, Achim Settelmeier.
# The authors must not be made responsible for anything!
#
# Read the manual carefully and don't misunderstand the jokes, ok?! ;-)


***** -Release *****


=> DSPdit is a fast DSP devkit for your ATARI Falcon030, consisting of an 
=> assembler and an editor. 


------------------------------------------------------------------------------
Content:

1.      General informations
 1.1    Files needed


2.      Getting started


3.      The editor
 3.1    Cursor movement
 3.2    Special functions
  3.2.1 PART
  3.2.2 (Un-)Splitline
  3.2.3 (Un-)rem line
  3.2.4 Define
  3.2.5 Force token
 3.3    Mouse


4.      The menu
 4.1    About DSPdit
 4.2    File
 4.3    Assembler
 4.4    Editor
 4.5    Search
 4.6    Block
 4.7    Options

5. 	Various
 5.1    Addresses
 5.2    Thanks
------------------------------------------------------------------------------


1. General information
======================

This comfortable DSPd(evk)it/DSP(e)dit was written because we had none ;-)
It  looks  very   much  like  TurboAss  because  TAss is our beloved Assembler
(believe it or not, DSPdit is completely written with TurboAss).
DSPdit  consists  of  two  parts, an assembler (coded by Gilles Audoly) and an
editor  (done by TSCC).  As QDSP-ASM is originally done to process ASCII-Files
(like  Motorola's assembler), it can be used for ASCII-Files as well but then,
you don't have all those nice features of this devkit.


DSPdit is PD. This means, that it is allowed to copy and spread the program as 
long as you copy all the files listed in 1.1 (but of course it is allowed to
copy QDSP-ASM separatly, read the DSP_ASM.DOC for more info)! 
The files may not be altered!

We don't expect large donations for our work but at least you should say thanks, 
if you like DSPdit :-)



1.1 Files needed
================

    DSPDIT.PRG - the program (commandline accepted)
    DSPDIT.TXT - this text
    DSPDIT.SET - the settings (not really required; see 4.7 Options)

  QDSP_ASM.TTP - the assembler (can be used without DSPdit)
   DSP_ASM.DOC - the manual for QDSP-ASM




2. Getting started
==================

To  install DSPdit, format your harddisk and copy DSPdit to the AUTO-folder of
your  boot  partition so that is available everytime you boot up. Then install
MutliTos  and  thousands of accessories to slow down your Falcon 'cause DSPdit
is too fast for you ;-)


Ok, now for the serious part:

Just  copy  the  whole  folder  to  any path on your harddisk you want and run
DSPDIT.PRG.   You'll   get   a message saying, that no settings are available,
meaning, the DSPDIT.SET-file is missing and and default settings will be used.

First,     you   should   locate   all  the applications you need. Use 'LOCATE
APPLICATIONS' in the Options-menu to do so. Here, you select the path and name
of  QDSP-ASM,  which  may be located in another folder as well as your beloved
debugger and up to 4 'external' applications (you don't really need to use all
four entries, ok?).

Now,  you  can  set  up  the  editor  if you want. Try 'Settings' (^S) in menu
Options and see chapter 4.7 Options for further informations.

Don't forget to save your settings using 'Save Settings' in menu Options!




3. The editor
=============

The  editor  was  especally  desinged to allow fast and comfortable editing of
DSP-Sources. It features syntaxcheck (ok, still a bit buggy but it gets better
;-)), autoformat (meaning evertime, your HD is full, it is wiped out ;-)   Ha!
Just   kidding,   it's   only   the  autoformatting  of  the  lines  entered),
keyboardmacros (to allow fast linedelete everytime you hit return ;-)), direct
support of the great QDSP-ASM and easy call of external programs.

Of  course,  such  simple functions like cursormovement and tabulator jump are
included, too (for the guys, who need that).



3.1 Cursor movement
===================

To control this little  box that inverts letters (some call it cursor) use the
four  arrowkeys.  For special moves try control to jump wordwise left/right or
pagewise  up/down  and  use  shift to jump to the begining/end of a line or to
scroll  the  source and let the cursor stand, where it is. For finishing moves
use  ClrHome  to  access the top line on the current page or Shift ClrHome for 
the  top  line  of  the  source. Hitting ClrHome twice will jump to the bottom 
line.  Tab  will  jump  to  the  next  and Shift-Tab will jump to the previous 
tabulator.

Of  course,  there're  lotsa  hidden  special moves as well but as no mag will
publish  them  in  the near future (they're too complex to find out), here's a
list (a=alternate, s=shift, ^=control):


         ^DEL - delete line
	   ^U - undelte line (same as undo but can be used several times)
   (^) Insert - insert line
       Return - delete source
           ^Z - jump to last edited line
           aZ - jump to line or label
         Undo - Guess it! (Yes! It's harddisk quickformatting ;-))
           ^L - search
           aL - continue search
       ^(1-9) - set bookmark 1-9
       a(1-9) - jump to bookmark 1-9
         HELP - fold part/macro (see 3.2 Special functions)
        ^HELP - fold all following parts/macros (see 3.2 Special functions)
      sRETURN - split line (see 3.2 Special functions)
   sBACKSPACE - unsplit line (see 3.2 Special functions)
      ^RETURN - rem line (see 3.2 ...)
     s^RETURN - unrem line (yeah, I think, ya know where to find that)
          ESC - call menu
	   ^W - changes valuebase or jumps to the label (see also 3.3 Mouse)
	   

3.2 Special functions
=====================

 3.2.1 PART
 ----------
 To  provide a better readability of the sources, it can be devided into parts
 indicated  by  PART  and ENDPART. If you're inside a part and press HELP, the
 part  is  folded  to one single line. To reopen it, press HELP once again.  A
 closed part is indicated by >PART. You may even enter a string behind PART to
 remember, what's inside it! Yeah, that's comfortable!
 Press  ^HELP to open all FOLLOWING parts. Of course, you may also fold macros
 indicated by MACRO and ENDM.


 3.2.2 (un-)split line
 ---------------------
 From  your  texteditor  you  know,  that  (s)RETURN  cuts  the  line  at  the
 cursorposition  and  moves  the  rest into the next line. So far so good. but
 does  cutting  move X0,A into pieces like mov ~ e X0,A make sense to you???
 Well,  not  all  guys know it doesn't and that's why DSPdit only splits where
 it's  possible!  You  may  split  the  line  between label and instruction or
 between instruction and remark. To confuse you even more, we also allowed you
 to  split  the  line  between parallelmoves! DSPdit then automatically adds a
 move  to  the  next  line  where the former parallelmove stands! Of course we
 included  the  other  way round, too. This means, you can make a parallelmove
 out of a normal move (of course only, if it's allowed).


 3.2.3 (un-)rem line
 -------------------
 By  pressing  ^RETURN, the current line can be quickly deactivated (a ;> will
 be  added  to  the  beginning  of  the  line).  s^RETURN  removes  those  two
 characters.


 3.2.4 Define
 ------------
 [Erm,  somehow it's damn difficult to explain, how defines work, so enjoy this 
 ;-)] Defines are a nice method to include non-concrete code into your programs 
 [Do  you  know,  what I mean with difficult to explain? ;-)], eg. if you often 
 change  the registers in your program or if you want to give registers a name.
 If you want to use defines, you'll have to put a @ before the name.
 Let's have an expample:

 r_register  DEFINE  'R0'
 n_register  DEFINE  'N0'
 
             move    X:(@r_register)+,X0
	     move    Y1,Y:(@r_register)+@n_register            
 
 This feature was included especally for Michael & Bjrn ;-)
 
 3.2.5 Force token
 -----------------
 In case the tokenizer fails to accept a correct line, you can force it to 
 accept the line if you write a # at the start of the line. 
 Example:   # PSEUDOOP-THAT-DSPDIT-DOESN'T-KNOW
		


3.3 Mouse
=========

The mouse (or trackball) is usually used to control the good old mousecursor.
But  how  can this help me developping a source, you ask? Well, a single click
with  the  left  button  will  set  the  normal  cursor to this position. This
provides  extremly  fast access for all three-hand-humanoids (two hands on the
keyboard  and  one  hand on the mouse). A doubleclick on a Symbol will jump to
the  line  in  which  this  symbol is defined. A doublclick on Label opens the
search  box,  so by hitting return, you can search for the lines in which this
label  is  used.  A  doubleclick on a Number will change it from Hex to Bin to
Deci to Hex etc...   This function is also accessable via keyboard. Just press 
^W.

You  can  mark a block using the mouse by holding the button for a longer time 
and move up'n'down.

For those of you, who think, GEM is great, we also included a nice menu, which
can be accessed using the mouse (of course it's no GEM, because, WE don't like
GEM).


4. Menu
=======

The menu can be used by two methods: You can select a drop down menu using the
mouse  and  then  click on the submenu. Or you may press ESC and scroll though
the  menu  with  the  cursorkeys  or  numbers.  This  allows  you  to  have  a
keyboardmacro that selects a menu that can't be reached with shortcuts.


4.1    About DSPdit
===================

Click  and  see  (much  better  than  plug'n play on PC ;-) - besides that: It
really is the truth ;-)))


4.2 File
========

Just those standard save/load-functions...
But to explain some in more detail:

 4.2.1 Save ASCII
 ----------------
 Saves the source just like it is shown on the screen (except, that all closed
 PARTs are saved open.
 If  a block is marked you are asked if you want to save just the block or the
 whole source.

 4.2.2 Save ASM
 --------------
 Saves  the  source as ASCII-Text with all PARTs/ENDPARTs mutated to comments,
 so  that  you  can use any assembler (e.g. the one from Motorola) to assemble
 your (with DSPdit edited) sources...
 If you think, we or Gilles have another bug in the code and you want to 
 go sure, that it really is not your code that doesn't work...
 Or if you want to see some warnings that QDSP-ASM doesn't feature...

4.3 Assembler
=============

 4.3.1 Assemble
 --------------
 Look  4.3.2  (silly, but it's a 'forward' declaration ;-)). This one does the
 same, but without dialog.

 
 4.3.2 Assemble...
 -----------------
 The  output-filename  can  be  chosen  (with  paths  and  anything  that  the
 MS-DOS-Filesystem  features,  which is not much). This name is saved with the
 source, so don't think, you will always get 'NONAME.P56'.
 You  can  also  decide,  if   you   want to select an output-file anytime you
 assemble  your  source  or just use the fixed one (in our mind better than to
 have an 'OUTPUT'-pseudoop).
 And  you can suppress the wait-for-a-key-when-assembling-is-finished-function
 if  you  want.  This  can be done because DSPdit automatically takes over all
 errors from QDSP-ASM so there's no real need to see all the messages.

 And then it is possible to change the assemble-modes:
        Outputfile is a P56-file,
                      a LOD-file or,
                      a LOD-file with a yell for the debugger afterwards
                                 (only, if no syntax errors are left over!)

 As QDSP-ASM features an pseudoop called 'PRINTVAL' (see documentation 
 of QDSP-ASM), we support that as well. Just play around with the button 
 and you surely see what it effects ;-)

 There is also the possibility included to start one of the apllications 
 (which DSPdit offers 4 slots for!) after assembling was successful. This 
 makes coding a bit faster, as DSPdit is it's own develop-shell.
 You can suppress the commandline-box with the button offered in that 
 box as well.

 Not to forget that it is possible to choose cancel.


4.4 Editor
==========

 4.4.1 Calculator
 ----------------
 Just to look like TAss ;-))
 No,  it really calcs formulas! But no symbols allowed to calc with (in a deep
 mood of being bored this will maybe change but it's hard to do).
 Please remember that this calculator can calc fractionals!!



4.5 Search
==========
 The standard search/replace-functions (and even more ;-))


 4.5.1 Replace
 -------------
 Ok,  you  surely  know, how replacling works, so we won't bore you with that.
 But  this  replacefunction  can  do more than just replace explicit words! To
 completely  confuse you, we included not one of those simple allquantors, no!
 We have multiquantors, yeah!

 Ok, what the fuck is a multiquantor?
 You  can  define  which letters can be used instead of the multiquantor. This
 allows  you  to  replace  only what you really want to replace. Let's have an
 example: Multiquantors are k and d, the string to search for is mo*e.
 This will replace mode or smoke but not move!

 If  you  select exclude multiquantor, all letters except the ones you entered
 will be used instead of the multiquantor.

 The multiquantor has no effect on the replacestring.


 4.5.2 Jump to line
 ------------------
 Set  cursor  to  the line you entered, or jumps to the label you want to jump
 to. Just that easy.


 4.5.3 Next error
 ----------------
 Moves  cursor  to  the line with the next error.  The warnig is cleared after
 the line is changed.


 4.5.4 Underline errors
 ----------------------
 This flag forces DSPdit to underline the lines with errors in them. 
 Errors are updated everytime you assemble the source.
 (Gives a rather nice overview of the Errors ;-))

4.6 Block
=========

I  think,  this  doesn't  need  any  explainations, except perhaps, that  this
blockfunctions  don't  work like cut'n insert via clipboard but always copy or
move  the  currently  marked block (to be honest: I hate clipboards, you never
know, what will be inserted).



4.7 Options
===========

 4.7.1 Source Settings
 ---------------------

 Click  on  Act.src  will  choose the actual source to be automatically loaded
 after  entering DSPdit. Of course, this can be turned off (guess which button
 to use ;-)).
 There's  also  a  button  to allow saving the source packed (with a damn fast
 lzwpack-routine  supplied by G. Audoly :-)). It should be on as packing takes
 no time but safes some discspace.

 We  also  included  the possibility to save your source automatically after a 
 while. It may be saved under the current source's name (Act.Src) or under the
 name  of  a temporary file (SaveSrc). The temporary file can be choosen using 
 Sel. This setting also affects minimum RAM mode savings.
 

 The  changed settings  may be saved under  the actual  settingsname using the 
 Save Set button.
 

 4.7.2 Settings
 --------------

 In this very big box you can choose your preferred settings. Some words about
 them:
 Show HEX: all hexvalues can be cut, expanded or cut bytewise.
 Capitalizing  is  provide,  too, in order to increase the readability of your
 source.
 You  may  even choose if an immediate value or adress should be short or long
 as default.
 The  settings  will  be  saved  together  with  the source AND with the other
 settings.  This  means,  you're  using  the default settings until you load a
 source. Then you use the source' settings. Clever, ne?


 4.7.3 Screen Save
 -----------------

 Hmm, nothing special about this, I think...


 4.7.4 Tabulators
 ----------------

 No need to explain, or is it to simple for your brain?


 4.7.5 Locate Applications
 -------------------------

 This nice function helps you to recover all your lost applications ;-)
 Naa,  it  just  provides  to  enter  path  and  name of your beloved programs
 (including  QDSP-ASM),  which  can  be  called  by  a  single  click on start
 application.  You  don't need to enter all for programs but at least QDSP-ASM
 and a debugger (eg the one by Brainstorm) should be entered.


 4.7.6 Memory
 ------------
 
 You  may enter the maximum amount of free memory which may be used by DSPdit.
 
 
 

 4.7.7 Minimum RAM Mode
 ----------------------

 This  mode  forces  DSPdit  to  save the actual source, deallocate the memory
 before calling an external program. Afterwards, the memory is allocated again
 and the source loaded. This allows you to use nearly the full memory for your
 external  application. The source may be saved under the actual source's name 
 or under the name of a temporary file. See 4.7.1 Source settings for more. 
 


 4.7.8 Load/Save Settings
 ------------------------

 After  you've  changed  your settings and located all applications you should
 save them. Here's a list of what will be saved:

   -autoload file
   -applications names
   -applications command line
   -tabulators
   -autoloadflag
   -packflag
   -screensaver time
   -autosave time and flags
   -some other settings

 This will be saved together with the source:
   -cursorposition
   -time and date of last change
   -time and date of creation
   -block start and end
   -insertmode
   -bookmarks
   -output filename
   -assemblemode
   -show hex setting
   -capitalizing settings



5. Various
==========

 5.1 Addresses
 -------------
 
 For bugreports, suggestions, updates etc write to:
  
  Settelmeier Achim (SCY)         or      John Andreas (Dynacore)
  Ruelzheimer Str. 39                     Schulzenstrae 36
  76756 Bellheim                          76771 Hoerdt
  GERMANY                                 GERMANY	
  Email: achim_settelmeier@ka2.maus.de    andreas_john@ka.maus.de
    (due to the limits of the Mausnet no mails >16kBytes!!!)
  
Do NOT FORGET to include a DISK for an update as well as a STAMP and an 
envelope for a quick reply. 
  

Remember that PD-Soft just lives from feedback! WRITE US!!!


 5.2 Thanks
 ----------
 
We just want to say thanks to CRAC for fixing bugs and including many features.
Thanks also go to Rebelsoft (Hi Bjrn&Michael!) for massiv betatesing and long 
bugreports :-)


 

ok, this should do.

bye
 Andreas (Dynacore) and Achim (SCY)