home *** CD-ROM | disk | FTP | other *** search
/ Amiga ISO Collection / AmigaDemoCD1.iso / DEMOS / ?-DoomCloneDMCLN20.LHA / backstab.txt < prev    next >
Encoding:
Text File  |  1993-02-16  |  14.7 KB  |  393 lines
  1.                            BACKSTAB LIBRARY V2.0
  2.                            ---------------------
  3.  
  4.  
  5. DISCLAIMER     I accept no responsibility of ANY kind of
  6.          damage caused by the usage of this library.
  7.  
  8.          If you use this library in your programs,
  9.          you should either include this library
  10.          package or notify about the usage to be
  11.          free of responsibility.
  12.  
  13.          If the user knows about the usage of this
  14.          library s/he accepts responsibility for
  15.          all damages caused by the library directly
  16.          or consequently or by any other way.
  17.  
  18.  
  19. DISTRIBUTION      The library is freely distributable.
  20.  
  21.          All public domain / shareware programs using
  22.          this library should notify about the usage or
  23.          include the newest available version of the
  24.          library with their program(s).
  25.  
  26.          Commercial products using this library need
  27.          to notify about the usage in the documentation
  28.          at minimum!
  29.  
  30.  
  31.  
  32.                               Brief description
  33.  
  34. Backstab.library is quite a small library that will help you take over the
  35. machine in OS legal ways. You call a function and you have a right to hit
  36. the Amiga hardware. And when you're done, you call another routine to turn
  37. the system back on again.
  38.  
  39.  
  40.  
  41.                                    History
  42.  
  43. The first version of backstab.library was finished in 6.12.1993. The idea for
  44. the library was taken from a message in InterNet where the writer asked why
  45. there wasn't a library like this circulating. I am working on a hardware
  46. hitting game that needed to access all possible devices to be able to use hard
  47. drives as well. There is a way to do that but then you need to downgrade on
  48. the speed of your code. The alternate way was to take over the system and
  49. return back when system was needed. The routines I had for takeover were
  50. quite ideal to the purpose, but they were a bit buggy and incomplete. I began
  51. to rewrite and now after 3 days the routines are working quite OK. 
  52.  
  53. Version history:
  54.  
  55. V1.0  -  Routines are working, no bugs noticed yet. Much room to
  56.       improve.
  57.  
  58.  
  59.                                   The Idea
  60.  
  61. Many coders in the Amiga scene are able to take over the machine in a fairly
  62. legal way, although I've seen *AGA* intros that won't work if I don't use
  63. an utility fixing the bug (for example 'runshit'). What can backstab.library
  64. offer other than system takeover, which can be done by many coders nowadays?
  65.  
  66. The idea is *not only* to help people take over the machine, but also give
  67. them a sort of a 'guarantee' that the code will work in the future generation
  68. OS's as well. This should be the case because the library functions can be
  69. updated if there's need to do so. And even the oldest demos using
  70. backstab.library should work on the future machines.
  71.  
  72. To face the fact, hardware and machines change. There's *no* way to make a
  73. demo or an intro OS legal in the future, I think. The only logical solution
  74. is to be able to upgrade the takeover routines and that's exactly what the
  75. library does.
  76.  
  77. Shortly: backstab.library = future compatibility :).
  78.  
  79.  
  80.                             The library routines
  81.  
  82. The routines that are used in the library V1.0 are almost exactly the same as
  83. my previous OS takeover routines. They are ofcourse improved, and at the
  84. moment the only real bad point I see is the CIA handling. This is a bug that
  85. should be corrected as quickly as possible, so anyone with a CIA
  86. store/restore knowledge, bring your info to the public! Ofcourse there are
  87. minor bad points (like master int. always disabled), but they are a very
  88. small price compared to compatibility!
  89.  
  90. The library is quite small at the moment, ~3 kb and after running it will take
  91. around 4 kb, I think. So the size shouldn't be a problem for your demo/intro.
  92. Here a list of the current library routines. If there will be a future
  93. version of the backstab.library, it should be downwards compatible. For
  94. example if people needed more input regs, the 31st bit of the D0 should
  95. indicate that all regs from D1-D7 are used for input etc...
  96.  
  97. The thumb rule is that the routines should work under any configuration and
  98. be downwards compatible (not bug compatible though ;-).
  99.  
  100. For a better understanding on how the routine really work, check the
  101. source code!
  102.  
  103.  
  104. --- D0-D4 = TakeOverSystem(Flags, D0)  -30
  105.  
  106. Takes over system in as legal way as possible. Things that happen (no order):
  107.    .   (AGA) hardware register flush
  108.    .   (AGA) sprite resolution fix (>= V39)
  109.    .   VBR is reset to zero, the zeropage will always be in $000-$400
  110.    .   Stores and resets as many chipregs as possible (DMACON, INTENA,
  111.        INTREQ, ADKCON). All possible bits in these registers are zeroed!
  112.    .   Blitter is stolen from OS: OwnBlitter(), WaitBlit()*2 and own
  113.        illegal waitblit for .maximum. certainty!
  114.    .   Sound channels are reserved (OS resets them as well. good for
  115.        future compatibility)
  116.    .   Caches are disabled if the 'nocache' flag is set (>KS2)
  117.  
  118.    All possible bits from regs DMACON, INTENA, INTREQ and ADKCON are
  119.    cleared as you return from this routine !!!
  120.  
  121.  
  122. Input:      D0 flags
  123.  
  124.       Bit   Function
  125.       ----------------
  126.       0  nocaches - disables all types of caches (for time
  127.          during program)
  128.       1  supervisor - returns in supervisor mode
  129.  
  130.       Rest of the bits are reserved, do NOT rely on them being
  131.            zero because of the possible future flags. Be sure to have
  132.       all the unused flags cleared.
  133.  
  134. Output:     All are full longword values.
  135.  
  136.       D0 zero if takeover ok, nonzero if error occurred.
  137.       D1 chipset type (0 = ocs, 1 = ecs, 2 = aga)
  138.       D2 kickstart version number (e.g. V39 = 39)
  139.       D3 CPU type (0...4: 000, 010, 020, 030, 040)
  140.       D4 math co-processor types:
  141.             bit 0 68881 commands are available
  142.             bit 1 68882 commands are available
  143.             bit 2 68040 math commands are available
  144.  
  145.  
  146. --- ReturnToSystem()       -36
  147.  
  148. Returns system to the original state:
  149.  
  150.    .   View (=copper) is fixed back
  151.    .   AGA sprite resolutions are restored
  152.    .   $000-$400 is returned to the pre-takeover state, VBR is set back
  153.        to the original value
  154.    .   Chipregs are restored
  155.    .   Blitter is released: illegal waitblit, WaitBlit()*2,
  156.        DisOwnBlitter().
  157.    .   Illegal sound reset: DMAs are turned off and volumes are set to
  158.        zero. Sound channels are released
  159.  
  160.  
  161.  
  162. --- ActivateSystem()       -42
  163.  
  164. Swaps back to system without restoring the system view (copper 1 intact).
  165. Allows user to use DOS loading routines to load extra files etc...
  166.  
  167.  
  168.  
  169. --- DeactivateSystem()        -48
  170.  
  171. Back to program after ActivateSystem().
  172.  
  173. NOTE! Master interrupt bit (bit 14 of INTENA) will ALWAYS be disabled after
  174. coming back from this routine!!
  175.  
  176.  
  177. --- D0-D4 = FullTakeOver(flags, D0) -54
  178.  
  179. Takes over the system storing nothing, used for a demo/intro that will reset
  180. afterwards. The things that the routine handles are the same as
  181. TakeOverSystem(), as well as the outputs.
  182.  
  183. [the library 1.0 stores some 'unnecessary' things but that is only done
  184.  for memory saving]
  185.  
  186.  
  187. --- DoReset()           -60
  188.  
  189. Reset the system. The reason this routine is included is that the A1200 Exec
  190. reset routine is _not_ fully working. This routine should be able to 'patch'
  191. the Exec routine to work under any config. Ofcourse a patch routine for Exec
  192. might be better, but I thought that why not include the routine here? Will be
  193. easier for the user.
  194.  
  195.  
  196. [the routine in 1.0 is *not* patched, I don't have info on how to make a legal
  197.  reset under older (hardware bugged?) versions of A1200]
  198.  
  199.  
  200. --- FlushCaches()       -66
  201.  
  202. Flushes caches (if KS higher or same than V37 = KS2.04). If the flush fails,
  203. returns -1 in D0 as error code. A succesful flush will return 0 in D0.
  204.  
  205. [Will find a way how to fix these under 1.2/1.3 as well, most probably a copy
  206.  from KS3.0 routines...]
  207.  
  208.  
  209.                        What are you allowed to trash?
  210.  
  211.  
  212. METHOD I
  213.    TakeOverSystem() - [ ActivateSystem() - DeactivateSystem() ] - ReturnToSystem()
  214.  
  215.    .   All graphics hardware
  216.    .   Blitter hardware
  217.    .   Sounds
  218.    .   Diskloaders - with some reservations, like it would be nice if
  219.        you returned the head, side and direction to the original state.
  220.        The trackdisk might get some r/w errors after this otherwise.
  221.        Ofcourse the ReturnToSystem() could fix this...
  222.    -   CIA is a problem at the moment, cannot really store them either.
  223.        Anyone know how to fix?
  224.  
  225.  
  226. METHOD II
  227.    FullTakeOver() - Reset()
  228.  
  229.    .   all above
  230.    .   CIA trash is ok
  231.    .   disk drives can be really trashed, no need to restore
  232.  
  233.    trash _whatever_ you want :-)
  234.  
  235.  
  236. I suggest that if you are uncertain about returning to DOS, don't return.
  237. Most people don't mind having to reboot after a demo, and this will give you
  238. a chance to trash CIAs even with this version of the library. But it would
  239. be nice if you mentioned about resetting afterwards in a textfile.
  240.  
  241. A big limitation is also that _always_ when you call backstab.library from your
  242. program, the interrupt master bit (bit 14 of INTENA) will return cleared. The
  243. library will force it down at the beginning to take care of possible
  244. interrupts and it's impossible to get the value without having a chance
  245. for an interrupt in the middle of reading.
  246.  
  247. A possibility would be to use the 'longword vacuum' in the 68000 family, i.e.
  248. two word instructions are executed before any interrupts are checked for. Placing
  249. commands <move.w $dff01c,d0> and <move.w #$4000,$dff09a> in the same longword
  250. could do the trick. Ofcourse you need to preload regs to make it fit in one long,
  251. but it is possible. The thing is that I don't know if this works on all CPUs
  252. that exist, so I haven't used it. Setting the master interrupt bit shouldn't be
  253. too demanding in any case :-).
  254.  
  255.  
  256.                     Example code using backstab.library
  257.  
  258.    incdir   include:
  259.    include  backstab.i
  260.    include  exec/exec_lib.i
  261.  
  262.    move.l   4.w,a6         ;Open backstab.library. If fails, exit
  263.    lea   bks_n(pc),a1      ;the whole program
  264.    moveq #0,d0       ;
  265.    jsr   _LVOOpenLibrary(a6)  ;
  266.    tst.l d0       ;
  267.    beq.s .error         ;
  268.  
  269.    move.l   d0,a6       ;TakeOverSystem(D0)
  270.    moveq #1<<bs_nocache,d0 ;(flags in the example; NoCache)
  271.    jsr   _LVOSystemTakeOver(a6)  ;
  272.    tst.l d0       ;
  273.    bne.s .error_takeover      ;
  274.  
  275.    move.l   a6,-(sp)    ;run the program
  276.    jsr   actual_program    ;
  277.    move.l   (sp)+,a6    ;
  278.                ;
  279.    jsr   _LVOReturnToSystem(a6)  ;ReturnToSystem()
  280. .error_takeover:
  281.    move.l   a6,a1       ;Close backstab.library
  282.    move.l   4.w,a6         ;
  283.    jsr   _LVOCloseLibrary(a6) ;
  284. .error:
  285.    rts            ;
  286.  
  287. bks_n:   dc.b  'backstab.library',0 ;
  288.    even
  289.  
  290. actual_program:
  291.    ... write your own hardware hitting program here ...
  292.  
  293.  
  294. It's actually that easy. If you copy that piece of code you'll be able to hit
  295. the hardware in almost any way you want. And it won't take you more than 5
  296. minutes to fix a program to work with backstab.library, either.
  297.  
  298.  
  299. Be warned, though. Using programs that use backstab.library without device
  300. waiting might corrupt your disk if you had a write operation going on as you
  301. ran the program. Always run from a state where a write operation is not
  302. possible. Also, don't run two programs using backstab.library at the exactly
  303. same time, this might cause some problems.
  304.  
  305.  
  306.                                     Notes
  307.  
  308. If you have any ideas or knowledge of how to develop this library further,
  309. contact me and I will do what I can.
  310.  
  311. Much of the OS knowledge has come from HowToCode7 (Comrade J/SAE, Carl-Henrik
  312. Skårstedt [Asterix/Movement]) and Jukka Marin.
  313.  
  314. The Commodore has done a *great* job with the OS, especially > 2.04. But I
  315. think Commodore made a mistake when they didn't include some sort of routines
  316. to allow demos hit the hardware. Ofcourse it fights against the basic idea of
  317. multitasking, but it's almost impossible to squeeze the last drop of power out
  318. of the Amiga without taking over the OS...
  319.  
  320. In any case, a slight inconvenience calling the backstab.library is certainly
  321. worth the effort because your code will be compatible, I'm sick and tired of
  322. intros (even the AGA intros!) not working on my A1200, or then I need AGA
  323. program fixer to make it work, ReloKick etc... This solution is quite simple
  324. and quite effective.
  325.  
  326. Also, if you make a demo and use this library, please include the library and
  327. sources/includes in the package as well (for the people who don't have the
  328. library, and also for disclaimer. you don't want to be responsible for my code,
  329. right ? :-).
  330.  
  331.  
  332.                         Possible future improvements
  333.  
  334. .   Devices should be waited for. At the moment there's no waiting as I
  335.     didn't know how to do it really legally. An option would be a 2-3 sec
  336.     delay but that began to irritate me later on.. A solution for trackdisk
  337.     drives would be to force the motor off as taking over, but that won't
  338.     do with the more advanced devices?
  339.  
  340.  
  341. .   CIA storing! If someone is able to do this, I'd really preciate if he
  342.     could write a letter to me and tell me how to do it. This is a problem
  343.     I've had for a long time, and CIA resources didn't help me. The idea
  344.     would be to be able to take over the timers even if they were in use, not
  345.     allocating them! Ofcourse programs can be run, but the CIA hitting ones
  346.     will not come back correctly.
  347.  
  348.  
  349. .   No interrupt master bit requirement. Any guarantees for the longword
  350.     'suck-in' to be working in future as well?
  351.  
  352.  
  353. .   SystemTakeOver() could preferably return the CPU and math co-proc
  354.     speeds (in MHz) in some regs as well. Not very essential, though.
  355.  
  356.  
  357. .   2 new flag bits: require PAL, require NTSC. If the user is running from
  358.     the wrong frequency it would be best to ask for him to quit or run
  359.     anyway. If the user had ECS-chipset or higher, there should be an
  360.     option for $dff1dc hack to force PAL or NTSC. However, if PAL/NTSC
  361.     was not _required_, the program should be run no matter what chipset
  362.     he had.
  363.  
  364.  
  365. .   ReturnToSystem() resets trackdisk so that drive DMA access becomes legal
  366.     once again. A more legal drive DMA wait would be great as well!
  367.  
  368.  
  369.  
  370.                                     The end
  371.  
  372. The library may be spread as Public Domain as long as no files are missing.
  373. The archive should include following files:
  374.  
  375.    backstab.library     ;the library itself
  376.    backstab_lib.i       ;include files for some assemblers
  377.    backstab_lib.s       ;source code for a 680x0 assembler
  378.    backstab.txt         ;this text file
  379.  
  380. INCLUDE ATLEAST THE backstab.txt or the DISCLAIMER part of it in any productions
  381. you do! As the library takes packed (with LHA) around 17kb, it shouldn't be
  382. a big problem to include it in any case. If you _really_ need to cut down on
  383. the size, don't leave out the disclaimer or you accept the responsibility of
  384. all damages your program might do, even if the bug might be in the
  385. backstab.library.
  386.  
  387.          To contact me:    Sami Vaarala
  388.                   Sotkapolku 4
  389.                   96910  ROVANIEMI
  390.                   Finland
  391.  
  392.                   tel. +358 60 62084
  393.