The Examples ~~~~~~~~~~~~ All the examples provided will assemble 'as is' using the assembler provided. Full notes on the use of this assembler are presented in the file 'ACC_Manual.doc' file. Where applicable, any raw data files associated with an example are located in the same directory as the example. The include files used by the majority of examples are all located in the 'Include' directory of the first disk in the set, 'M1:'. See below for an explanation of include files and raw data files. Assembling The Examples Using Supplied Assembler (A68K). ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The assembler supplied uses a fixed search path when attempting to locate include files, wether source or raw data. First the current directory is scanned for the file, if not located there then 'M1:Include' is scanned and should the required file still not be located then 'Inc:' is scanned. If the file cannot be located in one of these directories, the assembler will abort and issue an error message! As the raw data files associated with each example are located in the same directory as the source, it makes sense to launch the assembler from within the source directory. For that reason an icon named 'Assembler' can be found in every directory containing examples. This icon used IconX to launch the assembler from the M1: disk. Using this icon will assure that A68K can find any raw data files required by the example. When the assembler is launched from within the displayer, the current directory will already be the one containing the example source so there will be no problems assembling. If you are launching the assembler by some other means, you will need to assign 'Inc:' to the directory containing any files to be included that are not located in the 'M1:Include' directory. For example, you launch the assembler from the CLI after booting 'M1:' and now wish to assemble the examples. The following line must be typed into the CLI: assign Inc: ACM_2:Display Assembling the Examples Using Devpac2 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ If you own Devpac, some example will require modification to assemble. This is due to the different format of the 'Section' directive and the search path used to located include files. A68K uses the following Section format: section {,chip} where allowed types are: data - a data section code - a code section bss - a bss section eg. All data that is to be accessed by the custom chips must be located in chip memory. The section directive is used to instruct the assembler that all source following it is to be assembled into chip memory: section data graphics,chip - data section in chip memory called 'graphics'. Devpac, however, uses the following format: section , where allowed types are: data - a data section in any memory data_c - a data section in chip memory data_f - a data section in fast memory code - a code section in any memory code_c - a code section in chip memory code_f - a code section in fast memory bss - a bss section bss_c - a bss section in chip memory bss_f - a bss section in fast memory so a suitable substitute for the A68K format given above would be: section graphics,data_c All examples containing a section directive also contain the equivalent Devpac format, but it is commented out. Simply remove the semi-colon from the start of the line and remove the A68K line. The path of include files must be specified within the source for Devpac2 users. This is achieved using the 'incdir' directive. The incdir should be placed before any other files to be included, so to correctly assemble the examples the following line will be required: incdir M1:Include/ Devpac3 users need add this line to each example since the Include path can be defined from the Assembler Control panel. Consult your manual for more information on doing this. There now follows a brief explanation of some assembler techniques used in the examples. More details can be found in the file 'Assembler Usage'. Equates ~~~~~~~ An equate is a constant that can be referred to by name in a source file. An equate must be declared at some point in the source, this is done using the EQU assembler directive. For example, suppose the constant WIDTH was to be declared as 320: WIDTH EQU 320 At any point in a program, this constant can be referred to by name. This makes source easier to read and modify. The assembler will replace all occurrences of the constant with the value declared. The following fragment, move.l #WIDTH,d0 would be expanded by the assembler to, move.l #320,d0 The file 'hardware.i' contains a number of equates constantly used when directly programming the hardware. The contents of this file are covered in the first chapter of the manual. Macros ~~~~~~ Macros are a means of abreviation. For example if, during the course of a program, you constantly used the following fragment of code: move.l d0,a0 beq error jsr (a0) programming would be easier if you could type just one instruction that had the same result. This is what macros are for. A macro is identified by it's name. Whenever the assembler encounters a macro, it replaces it with the source attached to the macro. Source is attached to a macro when the macro is declared. Taking the above example, we may choose to name the macro GOSUB and would declare it as follows: GOSUB macro - tell assembler this is a macro declaration move.l d0,a0 | this is the source that will replace the beq error -| macro name when encountered from now on. jsr (a0) | endm - tell assembler this is the end of declaration Notice how the source attached to the macro is enclosed by the 'macro' and 'endm' assembler directives. Below is an example of how this macro may be used in a program: move.l _sys,d0 get subroutine address GOSUB call subroutine When assembled, the macro will be expanded ( ie replaced by the source attached to it ) and the result is shown below: move.l _sys,d0 move.l d0,a0 beq error jsr (a0) The file 'HW_Macros.i' contains a number of macro declarations that simplify certain areas of hardware programming. These macros and their useage will be introduced to you throughout the manual. You are advised to take advantage of them, they make programs easier to read and easier to code. An explanation of all the macros contained in this file can be found in Appendix 1, The Include Files, for quick reference. Include Files ~~~~~~~~~~~~~ Include is an assembler directive that should be followed by a filename: include 'df0:file1.i' | | the directive example filename ( It is conventional to give all include files a '.i' extension ) When a source file is assembled and the assembler reaches an include directive, the file specified will be loaded in and will be treated as source to assemble. Text from the file specified is inserted into the source being assembled at the point where the include directive was encountered: Source Being Assembled ---------------------------------- include 'normal.i' Start moveq.l #SEED,d0 rts ---------------------------------- The File 'normal.i' ---------------------------------- SEED equ 50 ---------------------------------- What The Assembler See's ---------------------------------- SEED equ 50 Start moveq.l #SEED,d0 rts ---------------------------------- Include files normally contain equates, macros and subroutines used on a regular basis. To save having to re-type the source, or physically insert it into a program being developed, the relevant file can simply be included. To make programming the hardware that much easier, a number of include files are supplied with this manual, two of these have been mentioned already. These files contain equates, macros and subroutines that you can use in your own programs. The contents of the include files are explained in relevant chapters of this manual, before being introduced to the routines available in one of the include files you will be shown how to do the job yourself. This method will make you appreciate the use of include files and why it makes sense to develop your own files as you become more proficient. Raw Data File ~~~~~~~~~~~~~ A raw data file, often called a binary file, does not contain source code. Instead it contains bytes of information. For example, a raw graphics file will contain all the data for an image that was created using Deluxe Paint or similar. A raw sample file will contain a series of bytes that if passed to the audio hardware, will produce a sound. Most productivity packages for the Amiga save data in IFF format. This means that information is stored with the raw data that describes what the raw data is. To strip all the surplus data from an IFF file, a utility called an IFF converter is used. This will load an IFF file and save only the raw data in a new file. Raw data can be included into a source file using the 'incbin' ( INClude BINary ) assembler directive. Data included into a source file using this directive will not be assembled, the assembler simply skips over it ensuring that the data is not corrupt. For example, suppose you have converted an IFF picture drawn using Deluxe Paint into the raw file 'pic.bm'. You would load this into your program using the following: graphics incbin 'pic.bm' Your program may then use the label to access the start of the graphics data. Incbin is used in a number of the examples to get raw graphic and audio data into a program. Taking Control Of The Amiga ~~~~~~~~~~~~~~~~~~~~~~~~~~~ Taking control of the Amiga away from the operating system, as is required for direct hardware programming, is a tricky affair. Considerable knowledge of the Amiga is required before this task can be accomplished. For this reason a general purpose start-up file has been supplied, 'HW_Start.i'. Just about all the examples in this manual rely on the code in this file for gaining control of the system at the start of a program, and then restoring the system at the end of a program. Full details of what the start-up code does can be found in Appendix 1, The Include Files, which details use of all the include files supplied with this manual. The source in the start-up file relies on equates and macros defined in two other files, 'hardware.i' and 'HW_Macros.i'. For this reason all three files must be included into a program. The files should be included at the very start of a source file, this ensures that the code in 'HW_Start.i' executes before your own code. If 'HW_Start.i' is used, your program must start at the label 'Main'. The code in 'HW_Start.i' takes control of the Amiga and then calls the routine at the label 'Main', your code. When your program finishes, control passes back to the code in 'HW_Start.i' which will restore the Amiga to it's original state. The basic starting point for a program that is going to take advantage of the start-up code is shown below. ***************************************** include hardware.i hardware equates include HW_Macros.i hardware macros include HW_Start.i start-up code Main rts end of program! end MUST HAVE THIS! ***************************************** More information on using the start-up code and other include files is presented during the course of the manual. You are again urged to make use of these files in your own programs, it's why they were supplied! *** Format for Devpac users: ***************************************** incdir M1:Include/ FOR DEVPAC ONLY! include hardware.i hardware equates include HW_Macros.i hardware macros include HW_Start.i start-up code Main rts end of program! ***************************************** -- End Of File --