home *** CD-ROM | disk | FTP | other *** search
/ Amiga MA Magazine 1998 #6 / amigamamagazinepolishissue1998.iso / coders / jËzyki_programowania / amigae / e_v3.2a / rkrmsrc / readme_useful < prev    next >
Text File  |  1977-12-31  |  5KB  |  139 lines
  1. Short: JRH's useful E modules
  2. Type: dev/e
  3. Author: m88jrh@ecs.ox.ac.uk (Jason R. Hulance)
  4. Uploader: m88jrh@ecs.ox.ac.uk (Jason R. Hulance)
  5.  
  6. JRH's Useful Modules
  7. ====================
  8.  
  9. These modules are Copyright (C) 1995, Jason R. Hulance.
  10.  
  11. You are free to use these modules in your programs, whether they are freeware
  12. or commercial.  However, if you want to distribute any of this archive you
  13. must include it all, unmodified, together with this file.
  14.  
  15. Contents
  16. --------
  17.  
  18. Various modules:
  19.  
  20.   ecode.m:
  21.     PROC eCode(func)
  22.     PROC eCodePreserve(func)
  23.     PROC eCodeTask(func)
  24.     PROC eCodeASLHook(func)
  25.     PROC eCodeCxCustom(func)
  26.     PROC eCodeIntHandler(func)
  27.     PROC eCodeIntServer(func)
  28.     PROC eCodeSoftInt(func)
  29.     PROC eCodeDispose(addr)
  30.  
  31.   split.m:
  32.     PROC argSplit(str=0)
  33.  
  34.  
  35. Amiga E does not support Resources (at least, not up to v3.1a, anyway).
  36. These modules rectify this.
  37.  
  38.   battclock.m:
  39.     DEF battclockbase
  40.     PROC readBattClock()
  41.     PROC resetBattClock()
  42.     PROC writeBattClock(time)
  43.  
  44.   battmem.m:
  45.     DEF battmembase
  46.     PROC obtainBattSemaphore()
  47.     PROC readBattMem(buffer,offset,length)
  48.     PROC releaseBattSemaphore()
  49.     PROC writeBattMem(buffer,offset,length)
  50.  
  51.   cia.m:
  52.     PROC ableICR(resource,mask)
  53.     PROC addICRVector(resource,iCRBit,interrupt)
  54.     PROC remICRVector(resource,iCRBit,interrupt)
  55.     PROC setICR(resource,mask)
  56.  
  57.   disk.m:
  58.     DEF diskbase
  59.     PROC allocUnit(unitNum)
  60.     PROC freeUnit(unitNum)
  61.     PROC getUnit(unitPointer)
  62.     PROC getUnitID(unitNum)
  63.     PROC giveUnit()
  64.     PROC readUnitID(unitNum)
  65.  
  66.   misc.m:
  67.     DEF miscbase
  68.     PROC allocMiscResource(unitNum,name)
  69.     PROC freeMiscResource(unitNum)
  70.  
  71.   potgo.m:
  72.     DEF potgobase
  73.     PROC allocPotBits(bits)
  74.     PROC freePotBits(bits)
  75.     PROC writePotgo(word,mask)
  76.  
  77.  
  78. Documentation
  79. -------------
  80.  
  81. The standard documentation on the Resource functions suffices for the
  82. Resource modules.  All the other functions (eCodeXXX and split) return NIL
  83. if an error occurred, which is normally "out of memory".
  84.  
  85.   ecode.m:
  86.     o   eCode() takes the address of an E function (or a label) and wraps it
  87.       so that it can be called from other tasks/processes and still access
  88.       the global variables of the main program.  This function was created
  89.       for use with createTask(), but has other uses.
  90.     o   eCodePreserve() is similar, but it also protects the function by
  91.       preserving the non-scratch registers on the stack.  This means the
  92.       function can retrieve (and change) registers D2-D7/A2-A6 as local
  93.       variables.  For instance,
  94.         PROC fun(a6,a5,a4,a3,a2,d7,d6,d5,d4,d3,d2) IS d2:=d3+a3
  95.       will have the effect of changing register D2 (and D0) when the
  96.       function returns.  Note: you do not need to specify all registers,
  97.       just the suffix of the above that you are actually interested in.
  98.         PROC fun(a3,a2,d7,d6,d5,d4,d3,d2) IS d2:=d3+a3
  99.       would have done...
  100.     o   eCodeTask() is just eCode() with a more suggestive name.
  101.     o   eCodeASLHook() takes the address of an E function (or a label) and
  102.       returns something usable as an ASL hook function (nothing to do with
  103.       the utility library hooks, more's the pity).
  104.     o   eCodeCxCustom() does the same for CX custom functions.
  105.     o   eCodeIntHandler() is for interrupt handlers: you get A1 and D1 as
  106.       arguments (in that order) to your function.  (A1 is the data element
  107.       of your interrupt, and D1 contains the interrupt flags.)
  108.     o   eCodeIntServer() is for interrupt servers: you get A1 (the data
  109.       element of your interrupt) as an argument.
  110.     o   eCodeSoftInt() is the same, but for software interrupts.
  111.     o   eCodeDispose() is passed the result of the one of the above
  112.       functions, and will to dispose the memory used by the special wrapper.
  113.       You will rarely need to use this, as the memory will be freed
  114.       automatically at the end of the program.
  115.     o   eCodeASLHook(), eCodeCxCustom(), eCodeIntHandler(), eCodeIntServer()
  116.       and eCodeSoftInt() all use their own private scratch area to preserve
  117.       registers, thus saving crucial stack space.  This has the disadvantage
  118.       of making the code non-reentrant, so if you need to use the same
  119.       function as multiple interrupt servers you must use eCodeIntServer()
  120.       multiple times.  Apart from that they should be OK, since they do
  121.       not get called from multiple tasks.  (If you find this a problem then
  122.       you can use eCodePreserve()...)
  123.     o   eCodePreserve() uses a big bit of stack to store registers, so be
  124.       careful...
  125.  
  126.   split.m:
  127.     o   argSplit(str=NIL) splits a string of arguments like "arg" (which is
  128.       the default), handling quoted arguments correctly.  The result is an
  129.       E-list of strings, or NIL if an error occurred.  The list is also
  130.       NIL-terminated so you have a choice of ways to manipulate it.  The
  131.       string passed to this function (or "arg" by default) is *altered* by
  132.       this function, so you shouldn't try using it directly.  You can
  133.       DisposeLink() the resulting list if you want to free it before the end
  134.       of the program.  (You are also responsible for freeing the string when
  135.       you are done with it, unless it was the default "arg", of course.)
  136.  
  137. The main reason for the creation of these modules was my translations of the
  138. RKRM examples.  These provide many examples of the use of these functions.
  139.