Club Amiga de Montreal

home *** CD-ROM | disk | FTP | other *** search

/ Club Amiga de Montreal - CAM / CAM_CD_1.iso / files / 224b.lha / A4th.doc < prev next >

Wrap

Text File | 1989-04-08 | 29.5 KB | 679 lines

A4TH.DOC Notes on.. ------------------- A4TH. A Public Domain Forth system for Amiga's. (based on Laxen & Perry's F83) This Forth system is Public Domain. You may freely distribute, copy and use it, for any legal purposes. I cannot be held responsible for any errors and/or omissions, I do not warrant this system. I bear no responsibility for any use or abuse, with or without intend. The system is composed of three 'arced' files: ( Arc program: AmigArc version 0.23, compatible with ARC v 5.0 ) A4THSYS.ARC The system and system source files. A4th The executable kernel. Akernel.blk The source for the kernel. Util.blk The Utilities to extend the kernel. Cpu68k.blk Assembler and debugger support Meta.blk The Meta compiler source. Include.blk The Amiga structures support source Tasks.blk Task support source. README Small warning that the file Util.blk has to be renamed to Utilities.blk before using the system. A4THINC.ARC The compressed and include files to be used with Include.blk D1.ARC The Dx.ARC files are 'arced' directories. D2.ARC D3.ARC D4.ARC D5.ARC D6.ARC D7.ARC D8.ARC names A note on naming the romcalls and structures. readme Instructions on how to create the include files. unpack.bat Execute this batch file to recreate the include files. A4THDOC.ARC Documentation and examples. A4th.doc This file. metavocs.txt Multiple vocabularies using Meta compiler. infix.txt How the infix parser works. hello.world example from intuition manual. dotty.blk dotty window as in demo dotty.c the example for dotty.blk gad.blk gadget example gad.c the example for gad.blk Small.blk A real small hello How to 'un-arc' the system. --------------------------- I'll describe the way I have my system set up. It could work for you also. Start off with a Workbench disk, with some room on it. Discard what you think will not be usefull. You will need minimally 25% space on it. That is what it will take for the include files. Please leave most of the files in the c directory, enough to execute a batch file. Create a directory on it, I call mine Includes, but you can use any name. Move the file A4THINC.ARC to that directory. Copy your favorite arc utility to your C: directory and name it 'arc'. Unarc A4THINC.ARC. One of the files will be unpack.bat, which will restore all the directories and files in the directories for you. Execute it and let it go. In your startup-sequence routine enter the following: assign i: df0:includes or the directory name you have chosen. That will make access to the include files simple from anywhere. ( example: tload i:exec/ports ) Format a new diskette and move the files A4THSYS.ARC and A4THDOC.ARC to it. Unarc the files, they are simple arced files, not directories. The file Util.blk in the A4THSYS.ARC file must be renamed to Utilities.blk before you run A4th. In my setup (Amiga1000, 2drives, 512k) I use an interlaced screen (640x400). That way I can have two A4th systems going at the same time, or run A4th with a text editor, behind which Dos resides of course. Several advantages, the biggest one is that I have twice the information in front of me. I have been using an interlaced screen for some time now, and when I switch back to a 640x200 display I feel hemmed in. If I enlarge the A4th window to cover 640x400, I can dump more at the same time, see more words at the same time etc. I did not change the editor to take advantage of the large screen, it still expects 640x200, but will work in 640x400. I also copy some commonly used routines to a ram: disk in order to speed up some operations. My startup-sequence is as follows: echo "A4th disk. Release 1.2 version 33.47" echo " " echo "current date" date echo "enter correct date" date ? date date to df0:s/last-date stack 8000 addbuffers df0: 25 addbuffers df1: 25 makedir ram:c copy c:dir ram:c copy c:type ram:c copy c:cd ram:c path ram:c BindDrivers assign i: df0:includes cd df1:forth Starting the kernel. -------------------- FROM THE CLI, of course, you can start it by entering: A4th by itself, and the kernel will execute. After it is loaded, you can load the Utilities by entering, in the forth window: open Utilities.blk ok which will load the extension as listed on screen 1 in the file Utilities.blk. Doing it this way will give you 64k bytes of space to use for anything defined. The utilities will be located in that area, and take about 32k if the distributed version is loaded as is. Another problem is that you will loose the services of Amiga Dos. This system does not have a directory utility for instance. It relies on the Amiga multitasking capabilities for that. Better to start A4th as a seperate task: run A4th 18000 open Utilities.blk ok That will open a 96k byte usable space and load the Utilities in. Make a batch file out of it if you like. The number is a hex number. About the system. ----------------- GENERAL. Although the excellent Public Domain system from Laxen & Perry was a starting point, this system is NOT the same NOR is it F-83 standard. A lot of the utilities present in F83 are also present in A4th. If you expect lightning speed or super compactness, you will be disappointed. It does not crawl, on the contrary, I find it responsive. But then I might be a little prejudiced. :) Try it out. If you want support, or more speed, or compactness, or all of these, I would suggest you part with (about) $100 and buy one (or both) of the commercially available systems: JFORTH Multi-Forth for Amiga Box 1051 Creative Solutions Inc. San Rafael, CA 94915 4701 Randolph Road, Suite 12 415-485-6867 Rockville, MD 20852 301-984-0262 Both of these are excellent systems and well worth the (just under) $100. Why did I write this, if the above commercially available systems are so good? Well, first of all, I like to be in control of the entire system. Secondly I cut my Forth teeth on L&P F83, like so many others, and was looking for something similar. The above mentioned systems use different threading schemes then the L&P. ( If you are not entirely in agreement with the way this turned out, you can always change it! And if you think the idea is good, share it with the rest of the Forth community. ) The system features: Indirect threaded All numbers default to the address size of 32 bits. Stack works on 32 bits at a time. Uses two section, a precompiled kernel loaded by Dos, and a usable user dictionary, size of which can be specified at startup. Word dictionary is inline, same as L&P, with 32 bit links. Since the Amiga is multitasking and has no hardware memory management, each program that is to be run must be in a special loader format. It will not be run in the same location, and therefore needs relocation information with the file. That makes it impossible (well not really, nothing in Forth is impossible) to save the current version from within the system. In order to create a new kernel, you will have to Meta compile the kernel. The Meta compiler saves the system in the proper format. There are ways around this of course, but I chose not to use any of them. For instance, use your own loader, or use a different threading scheme. Finally I tried to make a system that doesn't use all of the cpu's registers. Naturally I set aside the Forth register: SP(a7) RP(a6) IP(a5) W(a4) The only additional register I used is >next(a3) which is the address of the next routine. All other registers are available. To add to that, another 'goal' of mine was to make it possible to read some program in one of the Amiga Manuals and convert it for Forth. Since most of the published stuff for Amiga is in C, I made some moves towards that area, instead of staying more on the Forth track. (see the infix parser in the include.blk file.) KERNEL - This kernel supports multitasking, using Amiga Exec, see also TASKS. Some variables need to be different for each task. This kernel puts these task or as they were called in L&P, user variables ahead of the next routine. The advantage is that no additional register needs to be used. In L&P UP was used as the base address for the tasks. Here I use >next which is cpu register a3 as a base register. The variables are located ahead of the next routine. The disadvantage is that each task needs its own next routine, as it turns out that is exactly what I wanted. One has to metacompile in order to increase the number of 'user' variables. The 'rcall' routine is now (as opposed to version 1.0) right after the next routine. It is the bases for calling Amiga Rom routines. It is a bit of self modifying code (heavens!). Because of that it cannot be used by any other tasks. Each task will need its own copy. Since it is now directly after next, it can be copied to any new task, together with 'next' and task, or 'user', variables. All that the new task will have to do is change the >next register to point to its own 'next' routine. (Of course the other registers must also be set). The 'callrom' routine on screen 81 is the routine that sets the code in rcall. It uses relative addressing (relative to >next), each task will thus use their own rcall, but can use the common callrom. Calculating the address of a task variable is a matter of adding the >next register to the offset. The same is true for task deferred words. - You realize that having Exec provide the task switching releaves the kernel of the 'pause' word, that was used in L&P. - The cmove and cmove> and also fill routines are limited to 64k bytes. - In the previous version, I used a stdbuffer for output of single characters and multiple characters, such as spaces. In this version I use pad for this purpose. Stdbuffer is no longer. - Note that the common character output routine is 'type', not 'emit' as in L&P. In other words, emit calls type, in L&P type called emit. - In the kernel you will find, on screen 67, 68 and 75 some references to words having brackets around them. For example <find>. These words are a way to Meta compile in different vocabularies, see Meta compiler explanation for more info. Normally these have no effect on finding and defining words. - Doubles are really 64 bits wide. */mod is internally 64 bits. Large enough to not need floating point? But you can use Amiga Rom math if you want to. - Defined is now deferred, and defaults to (defined). It is used in structure support. - Of course I have added support for the task variables. Screen 79. - In the previous version I had a linked list, linking all the declared Amiga Library bases together. When the system was exited the list was traversed and each library was closed. That caused some complications when defining a library base. In this version I have made an array of opened library bases, or devices for that matter. When the system is exited the array is checked and each open library is closed. Access to each base is via an index, which are constants with names referring to the library, such as >Exec, >Dos and >Intuition. These three are opened by the kernel,as they are needed to run the kernel. One more is defined, >Graphics, but is opened in the Utilities.blk file: it is not required by the kernel, or the Utilities for that matter. It is opened as a convenience. (screen 81) - These library base indices are used to define an Amiga Rom routine. On screen 83 are some examples. The registers used in each call are defined between (r and r), which simply sets the base to hex and treats the registers as hex numbers. It then calculates the mask. No specific order of registers is required, I put them in the order they will be filled from the stack. In the first call defined, OpenLibrary, the name will be stuck in the a1 register, the version in d0. The offset and the flag indicating a return value (^) are assembled into three words, as tight as I could make it. In the Utilities.blk is support in the decompiler to 'see' these defined rom call entry points. - The change in (type), screen 88, was to accomodate the task variable #out. Before it was not a task variable. Now it is, so it needs to be calculated at run time. It could be used by any task. This is easily done in high level. At the end of (type) you can see I switch from code to high level using 'c:' but I don't return to code, I simply end the word as if it was a colon definition. Works ok. Similarily, here and pad are now also in high level, to let the system calculate the proper address at runtime. - To see an example of opening a library look at screen 91, or screen 98. That is the only time you need to be concerned with the library base. Most of the routines are already declared in the include files, later. - In the Intuition vocabulary I have added the romcalls, AllocRemember and FreeRemember. They support allocating memory and freeing it again. A linked list pointer, mem-link, helps to find them. When forgetting the list is traversed and any allocated memory, about to be forgotten will be released before access to the RememberKey is lost. Tasks use them. This method is available to any. When exiting A4th close-mem will release all. - Some new stuff in screens 99-101. The first bunch is some bitfiddling, used in Meta, but available for any bitarray. The words >> and << are here to make it a little easier to translate programs from 'C' to forth. Next is a random number generator. I am no statistician, works ok for me, if you have a better one, let me 'ave it.(pleese). Randomseed is there to be used, if you need variety. Tinit is a small code routine used by tasks. I put it here, in order to be able to not include Cpu68k.blk. That would leave out the assembler and the debugger. Still enough of the system to be usefull, but significantly smaller. The last ones are some C like string support, that is strings without the length byte and with an ending null byte. - I have added a 'fence' variable. You can set it to prevent forgetting by mistake. Forgetting now traverses the file linked list, the mem linked list and the vocabulary linked list. - The window declared in the Intuition screen is now called 4thw, previous version was Window, which collided with the Window structure declaration in the Intuition include file. - There are now dp0 a variable holding the address of the start of the usable dictionary, and dpsize a variable holding the size of the usable dictionary area. Before they were simple stored in some 'unnamed' cells. - The cold start routine now sets the task variable dp, which has to be the first task variable. - User or task variables are set by temporarily setting the (meta) dp to the user area, then filling the locations. This requires that all the task variables are set. Screen 111 - All variables are now set in screen 113, again when meta compiling. META - Gone is the dump utility, use the kernel's by not forgetting it. Forget 'out' should be sufficient. - This Meta compiler supports vocabularies in the target. An additional file, METAVOCS.TXT, explains it more. What the end result is, is that you are now able to declare vocabularies in the target, and declare the same word in different vocabularies. You will get the one you want if you control the target search order correctly. This is particularily important if you intend to Meta compile more then just the kernel. For instance, you could compile the assembler in the kernel and make it part of the kernel. The system will load faster. Enlarging the target buffer (now 32k in Akernel.blk screen 1) you could compile a lot, possibly an application. The only hitch is that defining words ( create..does> ) must be handled when compiling. The assembler has a few of them. To handle that I made: h: ado (s n1 n2 -- n1 ) \ used after does> word is defined target-create over ,-tr ,-t ; Then to use the above, eg with sz screen 3 Cpu68k.blk : sz (s n -- ) does> @ size @ and or ; 00300 ado sz3 00400 ado sz4 30000 ado sz300 drop Since does> in Meta leaves the address for patching, it works. There are other problems, all solvable. Don't forget the width, setting it to 0 will create a headerless system, or manipulate it while compiling, and make words disappear. - A user vocabulary is added to Meta. - Removed the bitfiddlers, they exist in the kernel. - Removed .relocations, wasn't very usefull. - Made saving the target system a little more readable. Created some words to take the noise out of it. But more importantly, block storage section or bss is now optional. Before you had to declare some, even if you didn't need it. The target is saved with the proper header, and relocation information. - Vocabulary creates a vocabulary in the target (no kidding). It also creates a vocabulary with the same name in the symbol table. Symbols are linked to the last one, depending on the vocabulary in <current> - The Meta compiler determines the size of the task variable area, see screen 23. - Screen 24 allows target symbol table vocabulary manipulation. Gone is .symbols, it's not needed, use <words> to see the symbols. UTILITIES - Screen 1 determines the utilities to be loaded, change as required. - Open the Graphics library, screen 13. - The editor is unchanged from the previous version. See the alternate or help screens for more information. - The decompiler has been extended to show a" strings, or amiga compatible strings. It also shows each library rom call if you want. Typing 'see OpenLibrary' gives some detailed information about the call. User or task variables and deferred words are also decompiled. - I did not implement any printing by pressing control-P, not in the previous version or this one. I hate noisy printers, I love laser printers, but they to expensive. So I very rarely print. If you want to, take a look at how the printer is intialized. 'init-pr' is deferred and is right now set to some control characters that initialize my printer to 132 columns. You will have to set this. Also the deferred p-name determines where the printer is connected to. Normally it is PRT: for my setup it is SER:. Change it accordingly. ASSEMBLER - The assembler is not changed. A small correction in one of the words. Take a look at the Akernel.blk for example usage of the assembler. - The debugger is changed. Since >next must not change in each task, the debugger had to be changed. (Before I changed >next). Now a jump to debnext is put in the place of the next routine. Unbug will fix the next routine. You will invite problems if you declare a new task when debug is in effect. INCLUDE - The first part of the utility to load the predefined structures and definitions for the Amiga, is a parser. This one is infix, and is extensively used in the Include files, which are text files. It also has some use in filling structures, see {fill. The text file INFIX.TXT explains the parser in more detail. The parser is in screens 4 to 8. - The next part, screens 12-18, are textfile loading. I prefer regular Forth blocks. The textfile loading does not support nesting. It was not intended to be the principal method of loading programs. I wrote it to load the Include files, outside of the Forth blocks. These are left alone, the text file loading opens a buffer for its own use, and when done, releases it. In screen 14 some additional Dos words are defined. I load these prior to any Include files, as a result these definitions are commented out in the include file libraries/dos. The same goes for all the words already defined in the kernel. Intuition calls, Exec calls etc defined in the kernel are all commented out. The text file loading obtains a Lock before it opens the file. Once the files has been opened it maintains some pointers into the buffer. It scans for LineFeeds as line terminators. Getline gets the next line. The line start will be returned by the word 'line' and the length is returned by the word 'llen'. The above three words are in the 'text' vocabulary, hidden normally. The words visible are: more?, ttype, tload. More? is a small keyboard pause word while listing a file via ttype. Ttype, or text-type, takes a file name and lists it. Any key will pause, and a return key will stop listing. Tload takes the next word in the input stream as a text file and loads it. It must be loadable, if it is not the system will not be forgiving; it will hang. See the examples and Tasks.blk for some example text file loading. - I tried to keep Include files small. They do not rely on other include files, with the exception of libraries/dos and libraries/dosextens. The intuition file that comes with the assembler or a C compiler is large. I made it a collection of files, each with ROM calls defined at the end. My model for these include files was Draco. Present on FredFish #76/77. It is a compiled language in C and Pascal spirit written by Chris Gray. - The last part of the Include.blk file is the structures. - Structures are defined with a {s..s} pair. The field names for the structure are hidden in a single linked list of words. The start of that word list is put in a variable, scontext, when a structure defined with the template, is used. An example is probably a better explanation.. In the file i:exec/lists is the List structure defined: {s List APTR lh_Head APTR lh_Tail APTR lh_TailPred BYTE lh_Type BYTE l_pad s} The opening {s takes the next word and makes it a defining word. This word will have the pointer to the linked list of field words and the total size of the structure in the parameter field. (The size of a structure is <=64k ). To make a definition using the List word: List MemEntry In this case List creates an actual structure, List is just a template. The structure has the name MemEntry, and when it is executed it will put the address of the structure on the stack and stick the pointer to the linked list of field words in scontext. The search order, which was made deferred in the kernel, is now altered so that the field words are checked FIRST. Then the rest of the search order as set in 'context' is searched. For instance, if you want to get the value from the lh_Type field: MemEntry lh_Type s@ That would return the type byte on the stack. What happens, MemEntry puts the address of the structure on the stack. Next lh_Type is found and executed. It alters the address by the offset of lh_Type to the start of the structure and sets the deferred word s@ and s! to that of a character fetch and store. Executing s@ will get the byte from that address. - Another example is in i:exec/ports, there the structure for MsgPort is defined as follows: {s MsgPort struct 14 mp_Node ( { Node=14;exec/nodes ) BYTE mp_Flags BYTE mp_SigBit APTR mp_SigTask -4 soffset +! APTR mp_SoftInt ( union ) struct 14 mp_MsgList ( { List=14;exec/lists ) s} The field defining word 'struct' is actually a synonym for BYTES, but in this case it indicates that the next 14 bytes are a nested structure with the name mp_Node. At first I concidered nesting of substructures, but rejected it. As a compromise I added the reference after the field definition in the Include file. Here the nested structure is a Node, is 14 bytes large and the defininition is in the file exec/nodes. If you require access to the nested structure in mp_Node you must load the include file i:exec/nodes also. For example if you require the list type of mp_MsgList which is a List in the occurance of a MsgPort called e.g. myport: myport mp_MsgList { List lh_Type s@ The sequence { List forces the field names for a List structure to become available. The '{' is immediate, and must be used in colon definitions, because if the occurance of a structure is compiled, it does not set the scontext variable to point to its field words. : ........... myport { MsgPort mp_Flags s@ ......... ; The MsgPort field words will be available until the next '{'. Examples of its use are in the examples provided. ( The major objection to this way of accessing structures ) - Another peculiarity is the -4 soffset +! sequence. That sequence resets 'soffset' to what it was before APRT mp_SigTask was defined. The next line APTR mp_SoftInt will point to the same offset as mp_SigTask. This is the way I handled unions as they are called in C. Not many are present in the include files. - The field defining words are: BYTE BYTES WORD WORDS LONG LONGS STRUCT APTR is a synonym for LONG. The plurals expect a value before the actual field name. The infix parser is used to get the number. STRUCT is used if the structure is defined and known. The next word will be the structure template that provides the number of bytes to reserve as the fieldsize for the word following. These field definitions, when used, set the structured fetch/store words, s@/s!, to the appropriate size. If you do not know what the field size is you can use s@/s!, or if you do know use the regular Forth fetch/store. - After using a structure word or after setting scontext to a specific structure you can see the names of the fields using 'swords'. It will print a list of field names, backwards. For instance when the system is loaded, as distributed, enter: Exec { Task swords This will print all the fieldnames, use any keypress to stop/start the listing. Another way of showing what a structure consists of is: .{ Task This will show the fieldname and what type it is. And this time in the declared order, again use key to stop/start. The last aid is {?}. It takes an address of the stack and uses the structure which is currently in scontext to show each field, the type, the offset and the contents of it in hex. The use of that? Try: Exec definitions tload i:exec/execbase { ExecBase 4 @ {?} And the execbase is visible. - An additional help word is {fill. It is used in one of the example files. It uses the infix parser to fill the structure, and all of it, from the input. See the example file Gad.blk for its usage. - As a final note on structures; I had to redefine 'forget' since 'defined' would get messed up. The new forget will work properly and can even forget itself. TASKS - Tasks use Exec as scheduler. They are simple tasks and require their own stack and return stack and task area. Task area is taken from the dictionary, in which the task local variables, the next routine and the rcall routine are copied. The stacks are obtained from Exec and kept in an Intuition Remember key, which is linked into the mem-link so the task can be forgotten. - Tasks can be given parameters, they will be copied to the task stack before the task is started. No parameters are expected in return. - Tasks should not use the A4th console input and output, they should define their own input and output file or device. A tasks output file could be a window of course. - Tasks should also have one entrance and one means of exit. If you use an abort, things will not work properly. - Priority of tasks are set at -25 that puts them below any system task. This makes sure it behaves as a background task. A4th will continue running at full speed, and when time is available the background task will run. As it should. If for some reason the task must execute at a different priority, you can alter it at any time, using 'priority'. - Tasks cannot compile or do any interpreting, the dp for the task is mainly used for number conversion and to find pad which is needed for emit. - The example on screen 17 shows how tasks can be used. - Each task needs a 'stop', and 'activate' requires the task on the stack under which should be the parameter count (0 for none) and the parameters under that. Tasks can be reassigned on the fly. But be carefull the resources allocated by the task will not be released; if a window was opened it will stay open. That could be exactly what you want of course. - The tasks are a minimal approach and it's up to you to make it better and/or more fool proof. I appologize for any mistakes I have made that might haunt you, I do hope you will be able to use this system as a tool and have some fun with Forth. Peter Appelman 05Oct88