Devpac 3 for the Atari ST/STE/TT/Falcon030 By HiSoft Copyright © 1992 HiSoft. All rights reserved. Program: designed and programmed by HiSoft. Manual: written by Alex Kiernan, David Nutkins and Keith Wilson. This guide and the Devpac 3 program diskettes contain proprietary information which is protected by copyright. No part of the software or the documentation may be reproduced, transcribed, stored in a retrieval system, translated into any language or transmitted in any form without express prior written consent of the publisher and copyright holder(s). HiSoft shall not be liable for errors contained in the software or the documentation or for incidental or consequential damages in connection with the furnishing, performance or use of the software or the documentation. HiSoft reserves the right to revise the software and/or the documentation from time to time and to make changes in the content thereof without the obligation to notify any person of such changes. Published by HiSoft The Old School, Greenfield, Bedford MK45 5DE UK First Edition, August 1992-ISBN 0 948517 59 X CHAPTER I - INTRODUCTION 9 Introduction 9 Devpac 3 Disk Contents 9 Making a Working Copy 10 Registration Card 11 The README File 11 Installation 11 How to use the Manual 12 A Course for the Beginner 12 A Course for Seasoned Assembler Programmers 12 Devpac Version 2 Users 13 System Requirements 13 Typography 13 Acknowledgements 14 A Quick Tutorial 15 CHAPTER 2 - USING THE EDITOR 18 Introduction 18 A word about pop-up menus and dialogs 18 The Editor's windows 22 Switching Windows 22 Entering text and moving the cursor 23 Cursor keys 23 Tab key 23 Backspace key 24 Delete key 24 The Edit menu 24 Go to top of file 24 Go to end of file 24 Goto line 24 Block Commands 25 Marking a block 25 The Clipboard: Copy, Cut & Paste 25 Saving a block 26 Copying a block 26 Deleting a block 26 Copy block to block buffer 26 Pasting a block 26 Page i Hisoft Devpac 3 Contents Printing a block 26 Deleting text 27 Searching and Replacing Text 27 Bookmarks 28 Disk Operations 29 New 29 Loading Text 29 Revert 29 Save As... 30 Save 30 Inserting Text 30 Delete File 30 Close 30 Change Directory 31 Quitting HiSoft Devpac 31 Configuring the editor 31 Auto-indent lines 32 Auto-save configuration 32 Cursor mode numeric pad 32 Hide mouse when typing 32 Make backups 32 Show matching parentheses 33 Stop at end of line 33 Save files on Quit 33 Save files on run other 33 Tab setting 33 Text Buffer 33 Cursor 34 Load... 34 Saving preferences 34 Reset 34 Running other programs 34 Run with Shell... 37 Setting the Path 38 Environment... 38 Miscellaneous Commands 39 Fonts... 39 About Devpac-3... 39 ASCII Table... 40 Help Screen 40 Desk Accessories 40 Page ii Hisoft Devpac 3 Contents Automatic Launching 41 The Program Menu 41 Assemble 41 Check 42 Output Symbols 42 Running Programs 42 Run with GEM 42 Run Directory 43 Debug 43 Mon 43 Debugger options 43 Assembly Errors 45 Resident Tools 46 CHAPTER 3 - THE ASSEMBLER 47 Introduction 47 Invoking the Assembler 47 From the Editor 47 The Control dialog 47 Running the assembler 50 Assembly Process 53 Return Codes 53 Binary file types 53 Types of code 55 Assembler Statement Format 55 Label field 56 Mnemonic Field 56 Operand Field 56 Comment Field 57 Expressions 57 Local Labels 64 Instruction Set 65 Word Alignment 65 Assembler Directives 66 Assembly Control 67 Assembler Directives 75 Repeat Loops 78 Listing Control 78 Label Directives 80 Floating Point Directives 83 Page iii Hisoft Devpac 3 Contents Conditional Assembly 84 Macro Operations 86 Output File Directives 92 Atari Executable (ATARI, L0) 92 GST Linkable (GST, L1) 94 DRI Linkable (DRI, L2) 97 Motorola S-records (SREC, 16) 98 Lattice C linkable (LATTICE, 17) 99 Directive Summary 102 CHAPTER 4 - THE DEBUGGER 105 Introduction 105 Mon Concepts 105 Exceptions 105 Front Panel Display 107 Symbolic Debugging 108 Mon Dialogs 109 Command Input 109 Mon Overview 110 Mon Reference 112 Numeric Expressions 112 Window Types 114 Cursor Keys 117 Window Commands 118 Other Alt- Commands 121 Screen Switching 122 Breaking into Programs 123 Breakpoints 123 History 125 Quitting Mon 126 Loading & Saving 126 Searching Memory 129 Miscellaneous 130 Auto-Resident Mon 135 Command Summary 135 Debugging Stratagem 137 Hints & Tips 137 Bug Hunting 137 AUTO-folder programs 138 Desk Accessories 138 Page iv Hisoft Devpac 3 Contents Exception Analysis 139 CHAPTER 5 – CLINK THE LINKER 141 A simple CLink command line 141 Concepts 141 ALVs 141 Near DATA/BSS 141 Directives 142 Input directives 142 Output directives 142 Map files 144 Options 145 'WITH' files 146 CLINKWITH; the Clink environment variable 147 Reserved symbols 148 CLink Messages 149 CLink Warnings/messages 149 Clink Errors 149 CHAPTER 6 - OTHER TOOLS 154 S-record Splitter 154 Command line examples 154 Ramdisk 155 Symbol Strip Utility 156 APPENDIX A - GEMDOS ERROR CODES 157 APPENDIX B - DEVPAC ERROR MESSAGES 158 Errors 158 Warnings 163 APPENDIX C - TOS MEMORY MAP 165 The Different Sorts of RAM 165 Processor Dump Area 165 Base Page Layout 165 Page v Hisoft Devpac 3 Contents Hardware Memory Map 167 APPENDIX D - GST SUPPORT 168 LinkST, The GST format linker 168 Introduction 168 Invoking LinkST 168 LinkST Running 169 GSTlib, The GST format librarian 174 APPENDIX D - CALLING THE OPERATING SYSTEM 177 GEMDOS - Disk and Screen I/O 177 Program Startup and Termination 178 GEMDOS Summary 179 BIOS - Basic I/O System 190 XBIOS Extended BIOS 194 GEM Libraries 208 GEM AES Library 209 Application Library 210 Event Library 210 Menu Library 211 Object Library 211 Form Library 212 Graphics Library 212 Scrap Library 213 File Selector Library 213 Window Library 214 Resource Library 214 Shell Library 214 GEM VDI Library 216 Control Functions 216 Output Functions 217 Attribute Functions 218 Raster Operations 219 Input Functions 220 Inquire Functions 220 AES & VDI Program Skeleton 221 Desk Accessories 221 Page vi Hisoft Devpac 3 Contents Linking with AES & VDI Libraries 222 Menu Compiler 222 VT52 Screen Codes 223 Cookie Jar 224 Operating system version numbers 226 The OS header 226 Changing window colours 228 APPENDIX E - THE FLOATING POINT CO- PROCESSOR 229 Extended precision 229 Double precision 229 Single Precision 230 Packed Decimal 230 FPCR Floating point control register 231 FPSR Floating point status register 231 FPIAR Floating point instruction address register 232 APPENDIX F - CONVERTING FROM OTHER ASSEMBLERS 234 Atari MadMAC 234 GST-ASM 234 MCC Assembler 234 K-Seka 235 Fast ASM 235 APPENDIX G - NEW FEATURES 236 Summary of Version 3 Improvements 236 The Editor 236 The Assembler 236 The Debugger 237 Integration 237 New tools 237 Features added to Devpac ST 2 237 APPENDIX H - TECHNICAL SUPPORT 239 Page vii Hisoft Devpac 3 Contents APPENDIX I - 240 BIBLIOGRAPHY 240 Atari 240 680x0 241 Algorithms & Data Structures 242 Page viii Hisoft Devpac 3 Contents Chapter I - Introduction Introduction HiSoft Devpac 3 (called simply HiSoft Devpac from now on) is a complete package for the production of fast, efficient assembly language programs on your Atari computer. There is an editor for the creation and editing of your assembler source code, a linker for building your programs together with other object files, a debugger for helping you to stamp out those nasty bugs and, of course, an assembler to turn your source code into speedy, compact machine code. This chapter is an introduction to this manual which aims to cover all aspects of installing and using HiSoft Devpac on your Atari computer - it does not attempt to teach you 680x0 programming although the accompanying 68000 pocket book and the examples should be of assistance in this regard. For further reading, you should consult the Bibliography. Please spend some time and effort getting to know and learning how to use the manual so that you can gain the maximum benefit from HiSoft Devpac. The rest of this section explains how to use the manual, whether you are a beginner or an expert, how to use your computer to best effect with HiSoft Devpac and, finally, we outline the different type styles that we have used throughout the manual to (hopefully) make it easy and enjoyable to use. Devpac 3 Disk Contents Devpac 3 is supplied on one double-sided 3.5" disk. Please note that the following list of files is intended as a guide only; subsequent versions of Devpac may contain extra files. DEVINST.RSC,DEVINST.PRG,DEVINST.DIR,DEVINST.INF The installation program and its support files. DEVPAC.PRG The multi-window editor and control program. HISOFTED.INF The editor preferences file. READ.ME A text file including latest details about Devpac 3; please read this file carefully before contacting our technical support department with any queries. AMON \ Auto-resident versions of Mon, the debugger. Introduction Hisoft Devpac 3 Page 9 BINXCUNK.TTP Lattice C format linker. BINXGEN.TTP 68000 version of Gen, the assembler. BIN\MON.PRG 68000 version of Mon, the debugger BINXSRSPLIT.TTP A utility program for users of Motorola format S-records which splits an S-record file into its high and low byte components. BINXSTRIP.TTP Symbol table stripper. BIN030N 68030 specific versions of Gen, the assembler, and Mon, the debugger. EXAMPLES\ Some example programs including the short tutorial for this manual. EXTRAS\ ,EXTRAS\ AESPATH,EXTRAS\ FSEL\ A number of 'freebies'; please see the text files within these subdirectories for more details. EXTRAS\MENU2ASM\ Devpac 2 compatible menu compiler. INCDIR\AESUB.S AES library source. INCDIR\BIOS.I BIOS definitions include file.