Short:        JRH's useful E modules (version 2)
Author:       jason@fsel.com (Jason R. Hulance)
Uploader:     jason fsel com (Jason R  Hulance)
Type:         dev/e
Architecture: m68k-amigaos

JRH's Useful Modules (Version 2)
================================

These modules are Copyright (C) 1995, Jason R. Hulance.

You are free to use these modules in your programs, whether they are freeware
or commercial.  However, if you want to distribute any of this archive you
must include it all, unmodified, together with this file.

Contents
--------

[This version is mainly a bug-fix: the eCodeXXX() routines did not flush the
CPU caches so could fail on a 68040, and the resource modules have been
simplified thanks to a bug-fixed EC v3.2a.]

Various modules:

  ecode.m:
    PROC eCode(func)
    PROC eCodePreserve(func)
    PROC eCodeTask(func)
    PROC eCodeASLHook(func)
    PROC eCodeCxCustom(func)
    PROC eCodeCollision(func)
    PROC eCodeIntHandler(func)
    PROC eCodeIntServer(func)
    PROC eCodeSoftInt(func)
    PROC eCodeSwapArgs(func)
    PROC eCodeDispose(addr)

  split.m:
    PROC argSplit(str=0)


Amiga E does not support Resources (at least, not up to v3.1a, anyway).
These modules rectify this.

  battclock.m:
    DEF battclockbase
    PROC readBattClock()
    PROC resetBattClock()
    PROC writeBattClock(time)

  battmem.m:
    DEF battmembase
    PROC obtainBattSemaphore()
    PROC readBattMem(buffer,offset,length)
    PROC releaseBattSemaphore()
    PROC writeBattMem(buffer,offset,length)

  cia.m:
    PROC ableICR(resource,mask)
    PROC addICRVector(resource,iCRBit,interrupt)
    PROC remICRVector(resource,iCRBit,interrupt)
    PROC setICR(resource,mask)

  disk.m:
    DEF diskbase
    PROC allocUnit(unitNum)
    PROC freeUnit(unitNum)
    PROC getUnit(unitPointer)
    PROC getUnitID(unitNum)
    PROC giveUnit()
    PROC readUnitID(unitNum)

  misc.m:
    DEF miscbase
    PROC allocMiscResource(unitNum,name)
    PROC freeMiscResource(unitNum)

  potgo.m:
    DEF potgobase
    PROC allocPotBits(bits)
    PROC freePotBits(bits)
    PROC writePotgo(word,mask)


Documentation
-------------

The standard documentation on the Resource functions suffices for the
Resource modules.  All the other functions (eCodeXXX and split) return NIL
if an error occurred, which is normally "out of memory".

  ecode.m:
    o   eCode() takes the address of an E function (or a label) and wraps it
      so that it can be called from other tasks/processes and still access
      the global variables of the main program.  This function was created
      for use with createTask(), but has other uses.
    o   eCodePreserve() is similar, but it also protects the function by
      preserving the non-scratch registers on the stack.  This means the
      function can retrieve (and change) registers D2-D7/A2-A6 as local
      variables.  For instance,
        PROC fun(a6,a5,a4,a3,a2,d7,d6,d5,d4,d3,d2) IS d2:=d3+a3
      will have the effect of changing register D2 (and D0) when the
      function returns.  Note: you do not need to specify all registers,
      just the suffix of the above that you are actually interested in.
        PROC fun(a3,a2,d7,d6,d5,d4,d3,d2) IS d2:=d3+a3
      would have done...
    o   eCodeTask() is just eCode() with a more suggestive name.
    o   eCodeASLHook() takes the address of an E function (or a label) and
      returns something usable as an ASL hook function (nothing to do with
      the utility library hooks, more's the pity).
    o   eCodeCxCustom() does the same for CX custom functions.
    o   eCodeCollision() does the same for GEL collision functions.
    o   eCodeIntHandler() is for interrupt handlers: you get A1 and D1 as
      arguments (in that order) to your function.  (A1 is the data element
      of your interrupt, and D1 contains the interrupt flags.)
    o   eCodeIntServer() is for interrupt servers: you get A1 (the data
      element of your interrupt) as an argument.
    o   eCodeSoftInt() is the same, but for software interrupts.
    o   eCodeSwapArgs() is like eCode() except it swaps the order of two
      arguments on the stack.  This means the E function can have its
      arguments in the same order as a similar C function.  For example,
      you can use this instead of eCodeCollision() if your collision code is
      simple (i.e., doesn't use PrintF() and the like).
    o   eCodeDispose() is passed the result of the one of the above
      functions, and will to dispose the memory used by the special wrapper.
      You will rarely need to use this, as the memory will be freed
      automatically at the end of the program.
    o   eCodeASLHook(), eCodeCxCustom(), eCodeIntHandler(), eCodeIntServer()
      and eCodeSoftInt() all use their own private scratch area to preserve
      registers, thus saving crucial stack space.  This has the disadvantage
      of making the code non-reentrant, so if you need to use the same
      function as multiple interrupt servers you must use eCodeIntServer()
      multiple times.  Apart from that they should be OK, since they do
      not get called from multiple tasks.  (If you find this a problem then
      you can use eCodePreserve()...)
    o   eCodePreserve() uses a big bit of STACK to store registers, so be
      careful...

  split.m:
    o   argSplit(str=NIL) splits a string of arguments like "arg" (which is
      the default), handling quoted arguments correctly.  The result is an
      E-list of strings, or NIL if an error occurred.  The list is also
      NIL-terminated so you have a choice of ways to manipulate it.  The
      string passed to this function (or "arg" by default) is *altered* by
      this function, so you shouldn't try using it directly.  You can
      DisposeLink() the resulting list if you want to free it before the end
      of the program.  (You are also responsible for freeing the string when
      you are done with it, unless it was the default "arg", of course.)

The main reason for the creation of these modules was my translations of the
RKRM examples.  These provide many examples of the use of these functions.