Amiga ROM Kernel Reference Manual Devices 3rd Edition

597 Pages·1991·97.1 MB·English

by  Commodore-Amiga Inc.

AMIGA ROM Kernel
Reference M anual
DEVICES
A M I G A T E C H N I C A L R E F E R E N C E S E R I E S
COMMODORE-AMIGA, INC.
T H I R D E D I T I O N

AMIGA
ROM Kernel Reference Manual
Devices
Third Edition
Commodore-Amiga, Inc.
AMIGA TECHNICAL REFERENCE SERIES
▼▼
Addison-Wesley Publishing Company, Inc.
Reading, Massachusetts Menlo Park, California New York
Don Mills, Ontario Wokingham, England Amsterdam Bonn
Sydney Singapore Tokyo Madrid San Juan
Paris Seoul Milan Mexico City Taipei
Contributors:
Dan Baker, Bruce Barrett, Mark Barton, Steve Beats, Dave Berezowski, Ray Brand, Bob Bums, Peter Cherna, Eric Cotton, Susan Deyl,
Sam Dicker, Ken Farinsky, Stuart Ferguson, Andy Finkel, Darren Greenwald, Paul Higginbottom, Larry Hildenbrand, Randell Jesup,
David Junod, Neil Katin, Joe Katz, Kevin Klop, Adam Levin, Dave Lucas, Dale Luck, Jim Mackraz, R.J. Mical, Bryce Nesbitt,
John Orr, Bob Pariseau, Rob Peck, Tom Pohorsky, Carl Sassenrath, Stan Shepard, Michael Sinz, Nancy Rains, Chris Raymond,
Tom Rokidd, Jez San, Carolyn Scheppner, Leo Schwab, Darius Taghavy, Ewout Walraven, Bart Whitebook and Rob Wyesham.
Third edition by:
Mark Ricci
Cover designer:
Hannus Design Associates
Copyright © 1991 by Commodore Electronics Limited.
Many of the designations used by manufacturers and sellers to distinguish their products are claimed as trademarks. Where those designations appear in this book and
Addison-Wes ley was aware of a trademark claim, the designations have been printed in initial caps. Amiga is a registered trademark of Commodore-Amiga, Inc Amiga 500,
Amiga 1000, Amiga 2000, Amiga 3000, AmlgaDOS, Amiga Workbench, and Amiga Kickstart are trademarks of Commodore-Amiga, Inc AUTOCONFIG is a trademark of Com­
modore Electronics Limited. Commodore and the Commodore logo are registered trademarks of Commodore Electronics Limited. Motorola is a registered trademark and
68000, 68010, 68020, 68030, and 68040 are trademarks of Motorola, Inc. CAPE and Inovatronics are trademarks of Inovatronics, Inc. Centronics is a registered trademark of Cen­
tronics Data Computer Carp. Epson is a registered trademark of Epson America, Inc Hewlett-Packard is a trademark and HP LaserJet is a registered trademark of Hewlett-
Packard, Co. Hisoft and Devpac Amiga are trademarks of Hi Soft. IBM is a registered trademark of International Business Machines Corp. Macintosh is a registered trademark
of Apple Computer, Inc. UNIX is a registered trademark of AT&T.
All rights reserved. No part of this publication may be reproduced, stored in a retrieval systenv or transmitted, in any form or by any means, electronic, mechanical, photocopy­
ing, recording or otherwise, without the prior written permission of the publisher. Printed in the United States of America. Published simultaneously in Canada.
Commodore item number: 363099-02
12345678 9-AL-9594939291
First printing, September 1991
ISBN 0-201-56775-X
WARNING: The information described in this manual may contain errors or bugs, and may not function as described. All information is subject to enhancement or upgrade for
any reason including to fix bugs, add features, or change performance. As with all software upgrades, full compatibility, although a goal, cannot be guaranteed, and is in fact
unlikely.
DISCLAIMER: COMMODORE-AMIGA, INC., ("COMMODORE') MAKES NO WARRANTIES, EITHER EXPRESSED OR IMPLIED, OR REPESENTATIONS WITH RESPECT
TO THE INFORMATION DESCRIBED HEREIN. SUCH INFORMATION IS PROVIDED ON AN "AS IS" BASIS AND IS EXPRESSLY SUBJECT TO CHANGE WITHOUT
NOTICE IN NO EVENT WILL COMMODORE BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL DAMAGES RESULTING FROM ANY
CLAIM ARISING OUT OF THE INFORMATION PRESENTED HEREIN, EVEN IF IT HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. SOME STATES DO
NOT ALLOW THE EXCLUSION OR LIMITATION OF IMPLIED WARRANTIES OR LIABILITIES FOR INCIDENTAL OR CONSEQUENTIAL DAMAGES, SO THE ABOVE
LIMITATION OR EXCLUSION MAY NOT APPLY.
C
o n t e n t s
Chapter 1 INTRODUCTION TO AMIGA SYSTEM DEVICES.........................................1
What is a Device?.............................................................................................................................2
Accessing a Device...........................................................................................................................2
Using a Device..................................................................................................................................4
Synchronous vs. Asynchronous Requests....................................................... 5
I/O Request Completion...................................................................................................................6
Ending Device Access......................................................................................................................7
Devices With Functions....................................................................................................................8
Example Device Programs...............................................................................................................9
Chapter 2 AUDIO DEVICE...............................................................................................13
About Amiga Audio........................................................................................................................13
Audio Device Commands and Functions......................................................................................15
Device Interface...............................................................................................................................16
A Simple Audio Example...............................................................................................................19
Audio Allocation and Arbitration..................................................................................................21
Allocation and Arbitration Commands.........................................................................................22
Hardware Control Commands.......................................................................................................25
Double Buffered Sound Example..................................................................................................28
Additional Information on the Audio Device...............................................................................34
Chapter 3 CLIPBOARD DEVICE.....................................................................................35
Clipboard Device Commands and Functions...............................................................................36
Device Interface...............................................................................................................................37
Monitoring Clipboard Changes.....................................................................................................42
Example Clipboard Programs........................................................................................................43
Support Functions Called from Example Programs.....................................................................50
Include File for the Example Programs.........................................................................................58
Additional Information on the Clipboard Device.........................................................................59
Chapter 4 CONSOLE DEVICE........................................................................................61
Console Device Commands and Functions..................................................................................62
Device Interface...............................................................................................................................63
About Console I/O..........................................................................................................................66
Writing to the Console Device.......................................................................................................67
Reading from the Console Device..................................................................................................74
Copy and Paste Support..................................................................................................................76
Selecting Raw Input Events............................................................................................................77
Input Event Reports........................................................................................................................78
Using the Console Device Without a Window.............................................................................79
i
Where Is All the Keymap Information?........................................................................................81
Console Device Caveats.................................................................................................................81
Console Device Example Code.....................................................................................................81
Additional Information on the Console Device............................................................................86
Chapters GAMEPORT DEVICE.....................................................................................87
Gameport Device Commands and Functions...............................................................................88
Device Interface...............................................................................................................................89
Gameport Events.............................................................................................................................91
Setting and Reading the Controller Type......................................................................................94
Joystick Example Program.............................................................................................................95
Additional Information on the Gameport Device.......................................................................100
Chapter 6 INPUT DEVICE..............................................................................................101
Input Device Commands and Functions......................................................................................102
Device Interface.............................................................................................................................103
Using the Mouse Port With the Input Device..............................................................................107
Adding an Input Handler..............................................................................................................108
Writing Events to the Input Device Stream.................................................................................109
Setting the Key Repeat Threshold...............................................................................................112
Setting the Key Repeat Interval....................................................................................................113
Determining the Current Qualifiers.............................................................................................113
Input Device and Intuition............................................................................................................114
Example Input Device Program...................................................................................................115
Additional Information on the Input Device...............................................................................118
Chapter 7 KEYBOARD DEVICE...................................................................................119
Keyboard Device Commands and Functions..............................................................................120
Device Interface.............................................................................................................................121
Reading the Keyboard Matrix......................................................................................................122
Amiga Reset Handling..................................................................................................................124
Reading Keyboard Events............................................................................................................128
Additional Information on the Keyboard Device.......................................................................130
Chapter 8 NARRATOR DEVICE...................................................................................131
Narrator Device Commands and Functions................................................................................132
Device Interface.............................................................................................................................133
Writing to the Narrator Device.....................................................................................................136
Reading from the Narrator Device...............................................................................................141
How to Write Phonetically for Narrator......................................................................................143
A More Technical Explanation....................................................................................................149
Example Speech and Mouth Movement Program.......................................................................151
Additional Information on the Narrator Device..........................................................................158
Chapter 9 PARALLEL DEVICE.....................................................................................159
Parallel Device Commands and Functions.................................................................................160
Device Interface.............................................................................................................................161
Ending A Read or Write with Termination Characters...............................................................163
u
Setting Parallel Parameters...........................................................................................................165
Querying the Parallel Device.......................................................................................................166
Additional Information on the Parallel Device...........................................................................169
Chapter 10 PRINTER DEVICE......................................................................................171
Printer Device Commands and Functions...................................................................................172
Printer Device Access...................................................................................................................173
Device Interface.............................................................................................................................175
Sending Printer Commands to a Printer......................................................................................178
Obtaining Printer Specific Data...................................................................................................181
Reading and Changing the Printer Preferences Settings............................................................182
Querying the Printer Device.........................................................................................................186
Error Codes from the Printer Device...........................................................................................187
Dumping a Rastport to a Printer..................................................................................................187
Creating a Printer Driver..............................................................................................................196
Example Printer Driver Source Code..........................................................................................210
Additional Information on the Printer Device............................................................................246
Chapter 11 SCSI DEVICE.............................................................................................247
SCSI Device Commands and Functions.....................................................................................248
Device Interface............................................................................................................................249
SCSI-Direct....................................................................................................................................250
RigidDiskBlock - Fields and Implementation...........................................................................253
Amiga Bootstrap..........................................................................................................................257
SCSI-Direct Example...................................................................................................................260
Additional Information on the SCSI Device...............................................................................263
Chapter 12 SERIAL DEVICE.........................................................................................265
Serial Device Commands and Functions....................................................................................266
Device Interface............................................................................................................................267
A Simple Serial Port Example.....................................................................................................269
Alternative Modes for Serial Input or Output.............................................................................270
Setting Serial Parameters (SDCMD_SETPARAMS)................................................................275
Querying the Serial Device..........................................................................................................278
Sending the Break Command......................................................................................................279
Error Codes from the Serial Device............................................................................................279
Multiple Serial Port Support........................................................................................................280
Taking Over the Hardware...........................................................................................................280
Advanced Example of Serial Device Usage...............................................................................281
Additional Information on the Serial Device..............................................................................284
Chapter 13 TIMER DEVICE...........................................................................................285
Timer Device Commands and Functions....................................................................................286
Device Interface............................................................................................................................287
System Time..................................................................................................................................290
Adding a Time Request...............................................................................................................292
Using the Time Arithmetic Functions.........................................................................................295
E-dock Time and Its Relationship to Actual Time...................................................................298
iii
Example Timer Program..............................................................................................................299
Additional Information on the Timer Device..............................................................................302
Chapter 14 TRACKDISK DEVICE................................................................................303
Trackdisk Device Commands and Functions..............................................................................304
Device Interface.............................................................................................................................305
Advanced Commands...................................................................................................................309
Disk Status Commands.................................................................................................................312
Commands for Diagnostics and Repair.......................................................................................314
Notification of Disk Changes.......................................................................................................314
Commands for Low-Level Access...............................................................................................315
Trackdisk Device Errors................................................................................................................317
Example Trackdisk Program.........................................................................................................318
Additional Information on the Trackdisk Device.......................................................................322
Chapter 15 RESOURCES..............................................................................................323
The Amiga Resources...................................................................................................................324
Resource Interface.........................................................................................................................324
BattQock Resource.......................................................................................................................325
BattMem Resource........................................................................................................................327
CIA Resource.................................................................................................................................328
Disk Resource...............................................................................................................................336
FileSystem Resource.....................................................................................................................337
Misc Resource...............................................................................................................................339
Potgo Resource..............................................................................................................................343
Appendix A IFF: INTERCHANGE FILE FORMAT......................................................347
A Quick Introduction to IFF.........................................................................................................349
"EA IFF 85" Standard for Interchange Format Files..................................................................355
"ILBM" IFF Interleaved Bitmap..................................................................................................381
"FTXT" IFF Formatted Text.........................................................................................................393
"SMUS" IFF Simple Musical Score.............................................................................................401
"8SVX" IFF 8-Bit Sampled Voice...............................................................................................419
IFF FORM and Chunk Registry..................................................................................................429
IFF Source Code...........................................................................................................................489
Appendix B EXAMPLE DEVICE...................................................................................557
Appendix C AMIGA FLOPPY BOOT PROCESS AND PHYSICAL LAYOUT.........571
Preface
The Amiga® Technical Reference Series is the official guide to programming Commodore’s Amiga
computers. This revised edition of the Amiga ROM Kernel Reference Manual: Devices provides
detailed information about the Amiga’s I/O subsystems. It has been updated for Release 2 (Kickstart
V36 and up) of the Amiga operating system, however, most of the material and example programs
are also compatible with version 1.3.
This book is intended for the following audiences:
• Novice Amiga programmers who want to try out features of the Amiga devices without writing
full-blown applications.
• Experienced programmers new to the Amiga.
• Amiga programmers and developers who want to use the devices in an application.
It is assumed that the reader can program in C or at least understand it.
Here is a brief overview of the contents:
Chapter 1, Introduction to Amiga System Devices. An introduction to the concept of an
Amiga system device, the device interface, and how to perform I/O using the devices.
Chapter 2, Audio Device. The Amiga audio device allows you to play music and make
sounds. Two example programs are included.
Chapter 3, Clipboard Device. The clipboard device is a central facility for sharing in­
formation between applications. The chapter covers the types of clipboard data and the
proper ways to use the clipboard. Two example programs are included plus an extensively
commented module of support functions for the programs.
Chapter 4, Console Device. The console device is the text-oriented interface for Amiga
windows. The chapter lists the escape sequences used for console windows and the types
of console windows. An example program is included.
Chapter 5, Gameport Device. The gameport device manages the various pointing devices
you plug into the mouse/joystick connectors. The chapter discusses the types of pointing
devices, the protocol for using the device and includes an example program.
Chapter 6, Input Device. The input device collects input event information and passes this
on to the operating system. The chapter covers this interaction between the various input
sources of the system, tells how to create your own input events and includes two example
programs.
v
Chapter 7, Keyboard Device. The keyboard device is the Amiga keyboard manager. The
chapter covers how to read the keyboard at a low level and also how to program system
reset (Ctrl-Amiga-Amiga) handlers. Three example programs are included.
Chapter 8, Narrator Device. The narrator device is the voice of the Amiga. This chapter
explains how to use the narrator device and the translator library, how to write phonetic
strings for the device, and discusses the technical aspects of computer generated speech in
thorough, but understandable terms. Two example programs are included.
Chapter 9, Parallel Device. The parallel device manages the Amiga parallel port. Two
example programs are included.
Chapter 10, Printer Device. The printer device translates character streams into printer
specific sequences. The chapter covers how to use the printer device and how to write your
own printer driver. It contains two example programs and two complete printer drivers.
Chapter 11, SCSI Device. The SCSI device provides the Small Computer System Interface
for the Amiga. The chapter covers how to send Amiga specific and SCSI specific commands
to SCSI devices. An example program is included.
Chapter 12, Serial Device. The serial device manages the Amiga serial port. Three
example programs are included.
Chapter 13, Timer Device. The timer device an interface to the Amiga’s internal clocks.
The chapter explains the types of clocks and clock units. Four example programs are
included.
Chapter 14, Trackdisk Device. The trackdisk device controls the Amiga disk drives. The
chapter covers how to use the drives at a high-level (formatted reads and writes) and
low-level (raw reads and writes). An example program is included.
Chapter 15, Resources. The Amiga resources are a collection of low-level interfaces to
special Amiga hardware. The chapter covers the general resource interface and how to use
all seven resources. Example code is included for all but one of the resources.
Appendix A, IFF, Interchange File Format. IFF is the standardized file format of the
Amiga. This appendix introduces IFF, covers five of the IFF types, lists the official FORM
and Chunk names that are reserved and in use and how to register new ones. IFF include
files, link modules, example programs and utilities are included.
Appendix B, Example Device. This appendix contains the assembly code for an Amiga
device for all those who want to create their own custom software I/O device.
Appendix C, Amiga Floppy Boot Process and Physical Layout. This appendix lists the
method used to read the boot block of a floppy and how the data is arranged in the boot
block.
The other manuals in this series are the Amiga User Interface Style Guide, an application design
specification and reference work for Amiga programmers, the Amiga ROM Kernel Reference Manual:
Includes and Autodocs, an alphabetically organized reference of ROM function summaries and
Amiga system include files, the Amiga ROM Kernel Reference Manual: Libraries, a work consisting
of tutorial-style chapters on the use of each Amiga system library, and the Amiga Hardware Reference
Manual, a detailed description of the Amiga’s hardware components.
vi