AmigaOS Documentation Wiki - User contributions [en]

Amiga Hardware Manufacturer ID Registry

2026-09-08T13:33:38Z

Costel Mincea: Added Tim Schattkowsky (45141)

__TOC__

= How to Obtain a Manufacturer Number =

Manufacturer's numbers are assigned by the AmigaOS development team. To obtain your unique manufacturer number send a support request to [mailto:support@hyperion-entertainment.com support@hyperion-entertainment.com] including these information:

1. The name of the company or person which the number is assigned to

2. Postal address/contact address

3. Name of the contact person, with a corresponding e-mail address

4. A brief description of the kind of products you want to produce

= Your Manufacturer Number =

Attention hardware manufacturers. If you are developing a hardware expansion product for the Classic Amiga (e.g. 500, 2000, 3000) then you will need to obtain a special manufacturer ID number from the AmigaOS development team to identify your product. This manufacturer number is used by the Amiga to link your hardware with its driver software at boot time.

Your manufacturer number is part of the special protocol that the Amiga uses to automatically configure all expansion devices on the bus without the user having to cut jumpers or adjust dip switches. This is called auto-config.

At start-up time, the system first polls each board in the system and assigns the board its own address space. If it is a memory board, its RAM is linked into the memory free pool. Later in the boot sequence, after DOS is initialized, the binddrivers program is run. Binddrivers will search the directory SYS:Expansion for the drivers that go with the boards.

To do this binddrivers looks in the Tool Type field of all icon files in SYS:Expansion. If the first seven bytes of the Tool Type field are "PRODUCT", then this is an icon file for a driver.

Binddrivers will then attempt to match the drivers it has found with the boards that were found earlier. This is where your manufacturer number comes in.

Your manufacturer number goes in two places. First, it is burned in hex form into the PAL which is part of ALL auto-config expansion products. Second, it appears in ASCII in the Tool Type field of the icon file for your product's driver. By matching these two numbers, the Amiga can automatically configure your board and bind it's software driver into the system as well.

The manufacturer's number is a 16-bit ID which appears in PAL offsets $10-$17. There is also an 8-bit product number which you assign. The product number is for uniquely identifying different products from the same vendor. The product number will appear in PAL offsets $04-$07. This gives you a total of 24 bits to identify each of your products.

These 24 bits of information in the PAL which identify your product are matched against the information in the Tool Type field of all icon files in the SYS:Expansion drawer. For example, suppose you are manufacturer #1019. You have two products, #1 and #2 which both use the same driver. The icon for your driver for these two products would have a Tool Type set to "PRODUCT=1019/1|1019/2". This means: I am an icon for a driver that works with product number 1 or 2 from manufacturer 1019, now bind me. Spaces are not legal. Here are two other examples:

; PRODUCT=1208/11
: is the Tool Type for a driver for product 11 from manufacturer number 1208.

; PRODUCT=1017
: is the Tool Type for a driver for any product from manufacturer number 1017.

For an informal explanation of the auto-configuration process, see the chapter on Software Expansion Architecture from the 2nd Annual Amiga Developer's Conference Notes (available on ADCD 2.1). For the details of timing, power, the PAL equations and PAL address specifications and the expansion library documentation, see sections 3.1 to 3.3 of the A500/A2000 Technical Reference Manual. The original auto-config spec appears in the A1000 Schematics and Expansion Specification.

The auto-config process makes the addition of expansion products to the system very easy. All the user has to do is put the board in any slot and copy the driver from the release disk to his own SYS:Expansion drawer. Everything else is automatic. There are no jumpers or dip switches to set. Best of all, you will get a lot less support calls asking how to make your product work with the XYZ-Corp-battery-backed-clock.

= Notes =

Some notes on hardware manufacturer ID assignment.

* Manufacturer ID numbers are assigned free of charge.
* Please provide the following information when requesting an ID:
*# Name of the company or person
*# Postal address/contact address
*# Name of the contact person, with a corresponding e-mail address
*# A brief description of the kind of products you want to produce
* All ID numbers smaller than 5000 must be considered unsafe because no information exists on which numbers exactly were taken during the time Commodore, Inc. disintegrated.
* ID numbers in the range 8192 to 18841 must be considered unsafe because some hardware developers mistook the numbers assigned to them to be given in hexadecimal format. Hence 0x2000 = 8192 and 0x4999 = 18841.

= Example code =

<syntaxhighlight lang="C" line>
/*-----------------------------------------------*/
/* Here is a short program which will tell you */
/* about the expansion boards configured in your */
/* system without you opening up the machine. */
/* Code by Bill Koester of CATS */
/*-----------------------------------------------*/
#include <libraries/configvars.h>
#include <libraries/expansion.h>

struct ExpansionBase *ExpansionBase;

void cleanup();
void printdev();

int main()
{
struct ConfigDev *MyConfigDev;

/*----------------------------------*/
/* Open the expansion library, */
/* if there is a problem then exit */
/*----------------------------------*/

ExpansionBase =(struct ExpansionBase *) OpenLibrary(EXPANSIONNAME,0);
if(ExpansionBase==NULL)
{
printf("Error opening expansion library!!\n");
cleanup();
exit(0);
}

/*--------------------------------------------*/
/* Use FindConfigDev to get info on the first */
/* expansion board on the list maintained by */
/* Exec. If there are no expansion boards in */
/* the system then exit. */
/*--------------------------------------------*/

MyConfigDev = NULL;

/*--------------------------------------------------*/
/* FindConfigDev(oldConfigDev,manufacturer,product) */
/* oldConfigDev = NULL for the top of the list */
/* manufacturer = -1 for any manufacturer */
/* product = -1 for any product */
/*--------------------------------------------------*/

MyConfigDev = FindConfigDev(NULL,-1,-1);

if(MyConfigDev==NULL)
{
printf("No Configured Devices found!!\n");
cleanup();
exit(0);
}

printdev(MyConfigDev);

/*-----------------------------------*/
/* OK, there is at least one board, */
/* so loop and get the entire list */
/* printing as we go with printdev() */
/*-----------------------------------*/

while(MyConfigDev = FindConfigDev(MyConfigDev,-1,-1))
{
printdev(MyConfigDev);
}
cleanup();
return 0;
}

/*-------------------*/
/* Close up shop... */
/*-------------------*/
void cleanup()
{
if(ExpansionBase)
CloseLibrary(ExpansionBase);
}

/*----------------------------------*/
/* Print out the contents of the */
/* dev structure for this expansion */
/* product. */
/*----------------------------------*/

void printdev(dev)
struct ConfigDev *dev;
{
char buff[200];

printf("Flags = ");
if(dev->cd_Flags==NULL)
printf("NULL ");
if(dev->cd_Flags&CDF_SHUTUP)
printf("CDF_SHUTUP ");
if(dev->cd_Flags&CDF_CONFIGME)
printf("CDF_CONFIGME ");
printf("\n");
printf("Board Address = %x\n",dev->cd_BoardAddr);
printf("Board Size = %d bytes\n",dev->cd_BoardSize);
printf("Slot Address = %d\n",dev->cd_SlotAddr);
printf("Slot Size = %d\n",dev->cd_SlotSize);
printf("Driver code at %x\n",dev->cd_Driver);

printf("er_Type = %x\n",dev->cd_Rom.er_Type);
printf("er_Product = %x\n",dev->cd_Rom.er_Product);
printf("er_Flags = %x\n",dev->cd_Rom.er_Flags);
printf("er_Reserved03 = %x\n",dev->cd_Rom.er_Reserved03);
printf("er_Manufacturer = %x\n",dev->cd_Rom.er_Manufacturer);
printf("er_SerialNumber = %x\n",dev->cd_Rom.er_SerialNumber);
printf("er_InitDiagVec = %x\n",dev->cd_Rom.er_InitDiagVec);
printf("er_Reserved0c = %x\n",dev->cd_Rom.er_Reserved0c);
printf("er_Reserved0d = %x\n",dev->cd_Rom.er_Reserved0d);
printf("er_Reserved0e = %x\n",dev->cd_Rom.er_Reserved0e);
printf("er_Reserved0f = %x\n",dev->cd_Rom.er_Reserved0f);

printf("Hit Return to continue:\n");
gets(buff);
}
</syntaxhighlight>

= Registry =

{| class="wikitable"
! ID (decimal)
! ID (hexadecimal)
! Manufacturer
! Notes
|-
| 1
| 0001
| Micronik
|-
| 211
| 00D3
| Pacific Peripherals/Profex
|-
| 221
| 00DD
| Kupke Computertechnik GmbH
|-
| 256
| 0100
| Memphis
| Originally registered to MacroSystems US
|-
| 512
| 0200
| 3-State Computertechnik
|-
| 513
| 0201
| Commodore (Braunschweig)
|-
| 514
| 0202
| Commodore (West Chester)
|-
| 515
| 0203
| Commodore (West Chester)
| Originally registered to Combitech/Macrosystem
|-
| 756
| 02F4
| Progressive Peripherals & Software
|-
| 767
| 02FF
| Kolff Computer Supplies
|-
| 1001
| 03E9
| Tecmar
|-
| 1002
| 03EA
| Telesys
|-
| 1003
| 03EB
| The Micro-Forge
|-
| 1004
| 03EC
| Kronos/C Ltd.
| Originally registered to Card Co. (Supra)
|-
| 1005
| 03ED
| A-Squared
|-
| 1006
| 03EE
| Comspec Communications
|-
| 1007
| 03EF
| HT Electronics
|-
| 1008
| 03F0
| RDS Software
|-
| 1009
| 03F1
| Anakin Research
|-
| 1010
| 03F2
| MicroBotics
|-
| 1011
| 03F3
| Bob Krauth
|-
| 1012
| 03F4
| Access Associates (Alegra)
|-
| 1013
| 03F5
| Mini Comp Systems Ltd.
|-
| 1014
| 03F6
| Cypress Technology
|-
| 1015
| 03F7
| Fuller Computers
|-
| 1016
| 03F8
| Galaxy Computers
|-
| 1017
| 03F9
| ADA Research
|-
| 1018
| 03FA
| Computer Service Italia
|-
| 1019
| 03FB
| Amigo
|-
| 1020
| 03FC
| Micro-Solutions Inc.
|-
| 1021
| 03FD
| Stacar International
|-
| 1022
| 03FE
| Video Precisions
|-
| 1023
| 03FF
| ASDG, Inc.
|-
| 1025
| 0401
| Ing. Buero Kalawsky
|-
| 1026
| 0402
| Computer Tuning
|-
| 1027
| 0403
| Interplan Unternehmensberatung
|-
| 1028
| 0404
| Imtronics/Memphis
| Originally registered to Peter Ohlich
|-
| 1030
| 0406
| Commodore (Lowell University)
| Originally registered to Productivity Center
|-
| 1041
| 0411
| Design Labs
|-
| 1042
| 0412
| MCS
|-
| 1043
| 0413
| B. J. Freeman
|-
| 1044
| 0414
| Side Effects Inc.
|-
| 1045
| 0415
| Oklahoma Personal Comp.
|-
| 1046
| 0416
| Advanced Micro Innovations
|-
| 1047
| 0417
| Industrial Support Services
|-
| 1048
| 0418
| Technisoft
|-
| 1049
| 0419
| Prolific, Inc.
|-
| 1050
| 041A
| Softeam, Inc.
|-
| 1051
| 041B
| GRC Electronics
|-
| 1052
| 041C
| David Lai
|-
| 1053
| 041D
| Ameristar Technologies
|-
| 1054
| 041E
| Cline Refrigeration
|-
| 1055
| 041F
| Cardiac Pacemakers, Inc.
|-
| 1056
| 0420
| Supra Corp. (Creative Microsystems)
|-
| 1057
| 0421
| Wayne Diener
|-
| 1058
| 0422
| Computer Systems Associates (CSA)
|-
| 1059
| 0423
| Trionix, Inc.
|-
| 1060
| 0424
| David Lucas
|-
| 1061
| 0425
| Analog Precision
| Also assigned to D & L Distributing
|-
| 1267
| 04F3
| RBM Digitaltechnik
|-
| 1282
| 0502
| M-TEC Hardware Design
|-
| 1337
| 0539
| Thomas Stenzel (DaFR34K)
|-
| 1576
| 0628
| Boris Križma
|-
| 1729
| 06C1
| Thomas Richter / OpenPCI-A1200 Mediator bridge
|-
| 1730
| 06C2
| Thomas Richter / OpenPCI-A4000 Mediator bridge
|-
| 1731
| 06C3
| Thomas Richter / OpenPCI-Prometheus bridge (Firestorm or original)
|-
| 1732
| 06C4
| Thomas Richter / OpenPCI-Reserved1
|-
| 1733
| 06C5
| Thomas Richter / OpenPCI-Grex bridge (both A1200 and A4000)
|-
| 1734
| 06C6
| Thomas Richter / OpenPCI-Reserved2
|-
| 1735
| 06C7
| Thomas Richter / OpenPCI-Reserved3
|-
| 1736
| 06C8
| Thomas Richter / OpenPCI-Reserved4
|-
| 1737
| 06C9
| Thomas Richter / OpenPCI-Reserved5
|-
| 1738
| 06CA
| Thomas Richter / OpenPCI-Reserved6
|-
| 1739
| 06CB
| Thomas Richter / OpenPCI-Reserved7
|-
| 1740
| 06CC
| Thomas Richter / OpenPCI-Reserved8
|-
| 1741
| 06CD
| Thomas Richter / OpenPCI-Reserved9
|-
| 1742
| 06CE
| Thomas Richter / OpenPCI-Reserved10
|-
| 1743
| 06CF
| Thomas Richter / OpenPCI-Reserved11
|-
| 1744
| 06D0
| Thomas Richter / OpenPCI-Reserved12
|-
| 1761
| 06E1
| Great Valley Products
|-
| 1803
| 070B
| UAE Amiga Emulator
|-
| 2002
| 07D2
| Mimetics Corp.
|-
| 2003
| 07D3
| ACDA
|-
| 2004
| 07D4
| Finn R. Jacobsen
|-
| 2005
| 07D5
| Elthen Electronics
|-
| 2006
| 07D6
| Nine Tiles Computer Systems Ltd.
|-
| 2007
| 07D7
| Analog Electronics
|-
| 2008
| 07D8
| Bell & Howell
|-
| 2009
| 07D9
| Roland Kochler
|-
| 2010
| 07DA
| Byte Corp.
|-
| 2011
| 07DB
| Reserved
|-
| 2012
| 07DC
| DKB, Inc.
| Previously named Michigan Software
|-
| 2013
| 07DD
| Pacific Peripherals
|-
| 2014
| 07DE
| Sysaphus Software
|-
| 2015
| 07DF
| Digitronics
|-
| 2016
| 07E0
| Akron Systems
|-
| 2017
| 07E1
| Great Valley Products
|-
| 2018
| 07E2
| Calmos
|-
| 2019
| 07E3
| Dover Research
|-
| 2020
| 07E4
| David Krehbiel
|-
| 2021
| 07E5
| Synergy Peripheral Systems
| Also known as California Access
|-
| 2022
| 07E6
| Xetec
|-
| 2023
| 07E7
| Micron Technology
|-
| 2024
| 07E8
| CH Electronics
|-
| 2025
| 07E9
| American Liquid Light
|-
| 2026
| 07EA
| Progressive Peripherals & Software
| Also used by Ateo
|-
| 2027
| 07EB
| Wicat Systems
|-
| 2028
| 07EC
| Applied Systems & Peripherals
|-
| 2029
| 07ED
| Delaware Valley Software
|-
| 2030
| 07EE
| Palomax
|-
| 2031
| 07EF
| Incognito Software
|-
| 2032
| 07F0
| Jadesign
|-
| 2033
| 07F1
| BVR
|-
| 2034
| 07F2
| Spirit Technology
|-
| 2035
| 07F3
| Spirit Technology
|-
| 2036
| 07F4
| Atronic
|-
| 2037
| 07F5
| Scott Karlin
|-
| 2038
| 07F6
| Howitch
|-
| 2039
| 07F7
| Sullivan Brothers Visual Engineers
|-
| 2040
| 07F8
| G I T
|-
| 2041
| 07F9
| Amigo Business Computers
|-
| 2042
| 07FA
| Micro E Ab
|-
| 2043
| 07FB
| Ralph Kruse
|-
| 2044
| 07FC
| Clearpoint Research
|-
| 2045
| 07FD
| Kodiak
|-
| 2046
| 07FE
| BSC
| Originally registered to Phoenix Electronics
|-
| 2047
| 07FF
| No Name Shown
|-
| 2048
| 0800
| Commodore Braunschweig
|-
| 2049
| 0801
| BSC
| Originally registered to Elaborate Bytes
|-
| 2050
| 0802
| Kronos/C Ltd.
|-
| 2051
| 0803
| Spartanics
|-
| 2052
| 0804
| Jochheim Computer Tuning
|-
| 2053
| 0805
| Trans Data Systems
|-
| 2054
| 0806
| Applied Systems & Peripherals Ltd.
|-
| 2055
| 0807
| Checkpoint Technologies
| Originally registered to Amiga Solutions
|-
| 2056
| 0808
| Adept Development
|-
| 2057
| 0809
| Advanced Computer Design
|-
| 2058
| 080A
| Sir Netics
|-
| 2059
| 080B
| Expert Services
|-
| 2060
| 080C
| Digital Art Systems
|-
| 2061
| 080D
| Adept Development
|-
| 2062
| 080E
| Expansion Technologies (Expansion Systems)
|-
| 2063
| 080F
| Alphatech
|-
| 2064
| 0810
| Edotronik GmbH
|-
| 2065
| 0811
| California Access/Synergy
| Originally registered to Logical Design Works
|-
| 2066
| 0812
| Bowden, Williams, Full & Assoc.
|-
| 2067
| 0813
| NES, Inc.
|-
| 2068
| 0814
| Amdev
|-
| 2069
| 0815
| Big Brother Security Systems
|-
| 2070
| 0816
| Active Circuits Inc.
|-
| 2071
| 0817
| ICD, Inc.
|-
| 2072
| 0818
| Multi-Meg Electronique
|-
| 2073
| 0819
| Kupke Computertechnik GmbH
|-
| 2074
| 081A
| The Checkered Ball
|-
| 2075
| 081B
| Hi Tension Computer Services Ltd. (UK)
|-
| 2076
| 081C
| Alfa Data
| Originally assigned to Elmtech Research, Ltd. (UK)
|-
| 2077
| 081D
| Great Valley Products
| Originally registered to Clartscreen, Ltd. (UK)
|-
| 2078
| 081E
| Interworks
|-
| 2079
| 081F
| Galysh Enterprises
|-
| 2080
| 0820
| Hardital Synthesis
| Originally registered to Realtime Games Software Ltd.
|-
| 2081
| 0821
| GBS
|-
| 2082
| 0822
| Circum Design Inc.
|-
| 2083
| 0823
| Alberta Micro Electronic Center
|-
| 2084
| 0824
| Bestech
|-
| 2085
| 0825
| Lasar Fantasy
|-
| 2086
| 0826
| Pulsar
|-
| 2087
| 0827
| Ivis
|-
| 2088
| 0828
| Applied Engineering
|-
| 2089
| 0829
| Solid-State Design & Development
|-
| 2090
| 082A
| Vison Quest
|-
| 2091
| 082B
| Seaview Software
|-
| 2092
| 082C
| BSC
| Mistakenly used by ADS (Advanced Development Software)
|-
| 2093
| 082D
| Bernd Culenfeld
|-
| 2094
| 082E
| American Liquid Light
|-
| 2095
| 082F
| CEGITES
|-
| 2096
| 0830
| Quadlite Computers Ltd.
| Originally registered to EV Industries
|-
| 2097
| 0831
| Silicon Peace
|-
| 2098
| 0832
| Black Belt Systems
|-
| 2099
| 0833
| Village Tronic
| Originally registerd to Steve Yaeger
|-
| 2100
| 0834
| ReadySoft
|-
| 2101
| 0835
| Phoenix Micro Technologies
|-
| 2102
| 0836
| Advanced Systems & Software
| Orignally assigned to Preferred Technology
|-
| 2103
| 0837
| Rombo Productions
|-
| 2104
| 0838
| Impulse Inc.
|-
| 2105
| 0839
| Beta Unlimited
|-
| 2106
| 083A
| Memory Expansion System, Ltd.
|-
| 2107
| 083B
| Vortex Computer Systems GmbH
|-
| 2108
| 083C
| Platypus Systems
|-
| 2109
| 083D
| Gigatron OHG
|-
| 2110
| 083E
| PG Electronics
|-
| 2111
| 083F
| New Technologies Group
|-
| 2112
| 0840
| Interactive Video Systems (IVS)
| Pacific Peripherals
|-
| 2113
| 0841
| Vector
| Originally registered to H. K. Computer
|-
| 2114
| 0842
| Pacific Digital
| Originally registered to C. H. Helfrich Elektronik
|-
| 2115
| 0843
| Xanadu
|-
| 2116
| 0844
| Pacific Digital
| Originally registered to AMS
|-
| 2117
| 0845
| X-Pert
|-
| 2118
| 0846
| The Amiga Centre
|-
| 2119
| 0847
| Digital Pacific
|-
| 2120
| 0848
| Solid State Leisure
|-
| 2121
| 0849
| Hydra Systems
| Originally registered to Analog Electronics
|-
| 2122
| 084A
| Cumana
|-
| 2123
| 084B
| KAPS 2C Conception
|-
| 2124
| 084C
| Mike Mason
|-
| 2125
| 084D
| For Your Eyes
|-
| 2126
| 084E
| Volkmar Breitfeld Computersysteme
|-
| 2127
| 084F
| Sunrize Industries
|-
| 2128
| 0850
| Scott Advanced Micro Designs
|-
| 2129
| 0851
| Digital Micronics
|-
| 2130
| 0852
| Alfa-Laval
|-
| 2131
| 0853
| Multigros A/S
|-
| 2132
| 0854
| Archos
|-
| 2133
| 0855
| Icom Simulations
|-
| 2134
| 0856
| Commodore Test Engineering Group
|-
| 2135
| 0857
| Microcreations
|-
| 2136
| 0858
| Shoestring Productions
|-
| 2137
| 0859
| Faberushi
|-
| 2138
| 085A
| Evesham Micro Ltd.
|-
| 2139
| 085B
| Panagolin Laser Software
|-
| 2140
| 085C
| Thomas Rudloff
|-
| 2141
| 085D
| Daniel Hohabir
|-
| 2142
| 085E
| GfxBase, Inc.
|-
| 2143
| 085F
| Axellabs
|-
| 2144
| 0860
| Roctec Electronics Inc.
|-
| 2145
| 0861
| Omega Datentechnik
|-
| 2146
| 0862
| Atlantis
|-
| 2147
| 0863
| Skytec Computers
|-
| 2148
| 0864
| Protar Electronics
|-
| 2149
| 0865
| ACS
|-
| 2150
| 0866
| Software Results Enterprises
| Originally registered to University of Illinois
|-
| 2151
| 0867
| Infinity Systems Design Group
|-
| 2152
| 0868
| Trade It
|-
| 2153
| 0869
| Suntec, Inc.
|-
| 2154
| 086A
| DJW Micro Systems
| Originally registered to Tritec Marketing
|-
| 2155
| 086B
| Power Computing Ltd.
|-
| 2156
| 086C
| MacroSystems
|-
| 2157
| 086D
| Masoboshi GmbH (DCE)
|-
| 2158
| 086E
| HAL Software Hardware Handel
|-
| 2159
| 086F
| Mainhattan Data
| Originally registered to Michael Lamm Computersysteme
|-
| 2160
| 0870
| Digital Processing System
| Originally registered to bbdp Electronics
|-
| 2161
| 0871
| Blue Ribbon Soundworks
| Originally registered to Design Computer Systems
|-
| 2162
| 0872
| XPert
| Originally registered to The Station
|-
| 2163
| 0873
| DelaComp
| Originally registered to Bryan Williams
|-
| 2164
| 0874
| Superformance Computer Engineering GmbH
|-
| 2165
| 0875
| Overland Engineering
|-
| 2166
| 0876
| Thomas Hamren
|-
| 2167
| 0877
| Village Tronic
|-
| 2168
| 0878
| Toolbox Design
|-
| 2169
| 0879
| Digital Processing System
|-
| 2170
| 087A
| Superformance
|-
| 2171
| 087B
| Utilities Unlimited
|-
| 2172
| 087C
| phase 5
|-
| 2173
| 087D
| Juergen Kommos
|-
| 2174
| 087E
| Electronic Design
|-
| 2175
| 087F
| James Cook University of North Queensland
|-
| 2176
| 0880
| AmiTrix Development
|-
| 2177
| 0881
| Ferranti
|-
| 2178
| 0882
| Leviathan Development
|-
| 2179
| 0883
| United Video Inc.
|-
| 2180
| 0884
| GPSoft Pty. Ltd.
| Originally registered to Juergen Kommos
|-
| 2181
| 0885
| ArMAX
| Oliver Bausch
|-
| 2182
| 0886
| CP Computer
|-
| 2183
| 0887
| Amiga Modula & Oberon Klub
|-
| 2184
| 0888
| ITEK Neser & Sieber GbR
|-
| 2185
| 0889
| Phillip C. Lello
|-
| 2186
| 088A
| Cyborg Design Services
|-
| 2187
| 088B
| G2 Systems
|-
| 2188
| 088C
| Pro System Computersysteme
|-
| 2189
| 088D
| ZEUS Electronic
| Originally registered to MSPI (Markt & Technik)
|-
| 2190
| 088E
| Altatech
|-
| 2191
| 088F
| NewTek
|-
| 2192
| 0890
| M-TEC Hardware Design
| Originally registered to Hardware Design Udo Neuroth
|-
| 2193
| 0891
| Great Valley Products
| Originally registered to Viona Development
|-
| 2194
| 0892
| Amitek
| Originally assigned to Marpet Developments
|-
| 2195
| 0893
| Ingenieurbuero Helfrich
|-
| 2196
| 0894
| The Neo Group
|-
| 2197
| 0895
| Cyon
|-
| 2198
| 0896
| Bob Research Group
|-
| 2199
| 0897
| Richmond Sound Design Ltd.
|-
| 2200
| 0898
| US Cybernetics
|-
| 2201
| 0899
| Fulvio Ieva
|-
| 2202
| 089A
| Silicon Studio
|-
| 2203
| 089B
| MacroSystems (USA)
| Was named Micro System Devices
|-
| 2204
| 089C
| Conspector Entertainment
|-
| 2205
| 089D
| Laserforum
|-
| 2206
| 089E
| Elbox Computer
| Mistakenly used by Index Information Ltd.
|-
| 2207
| 089F
| Applied Magic Inc.
|-
| 2208
| 08A0
| SDL Ltd.
|-
| 2560
| 0A00
| Harms
|-
| 2588
| 0A1C
| A1K.org Community
|-
| 2640
| 0A50
| Micronik
|-
| 2782
| 2782
| OA Design
|-
| 3084
| 0C0C
| Team 4
|-
| 3643
| 0E3B
| E3B
| Michael Boehmer
|-
| 3855
| 0F0F
| Micronik
|-
| 4096
| 1000
| MegaMicro
|-
| 4110
| 100E
| DigiFeX
|-
| 4136
| 1028
| Imtronics/Memphis
|-
| 4149
| 1035
| PROTAR
|-
| 4369
| 1111
| Frank Strauß Elektronik
| Also used by Kupke
|-
| 4626
| 1212
| Individual Computers
|-
| 4648
| 1228
| Flesch Hornemann Computer Elec.
|-
| 4680
| 1248
| Kupke Computertechnik GmbH
|-
| 4711
| 1267
| RBM digitaltechnik
|-
| 4754
| 1292
| MacroSystems
|-
| 5000
| 1388
| ITH
|-
| 5001
| 1389
| VMC
|-
| 5010
| 1392
| Ambience Creation Technology
|-
| 5011
| 1393
| Creative Development
|-
| 5012
| 1394
| Georg Braun
|-
| 5013
| 1395
| Swedish User Group of Amiga
|-
| 5014
| 1396
| Jakub Bednarski
|-
| 5015
| 1397
| KryoFlux, Ltd.
|-
| 5016
| 1398
| Igor Majstorovic
|-
| 5017
| 1399
| Alastair M. Robinson
|-
| 5018
| 139A
| Austex Software
|-
| 5019
| 139B
| Sören Gust
|-
| 5020
| 139C
| Rok Krajnc
|-
| 5030
| 13A6
| Tim Tashpulatov
|-
| 5040
| 13B0
| 7-bit
|-
| 5050
| 13BA
| Sakura IT
|-
| 5060
| 13C4
| FPGAArcade
|-
| 5070
| 13CE
| CancerSoft Inc.
|-
| 5080
| 13D8
| Stephen Leary
|-
| 5090
| 13E2
| DMA Softlab LLC
|-
| 5100
| 13EC
| Brookhouse Engineering
|-
| 5110
| 13F6
| Eduardo Arana
|-
| 5120
| 1400
| CS-LAB
|-
| 5130
| 140A
| Robert Miranda
|-
| 5132
| 140C
| UAS Interface Ltd.
|-
| 5140
| 1414
| RastPort
|-
| 5150
| 141E
| Amiga Kit
|-
| 5160
| 1428
| Central Texas Commodore User Group
|-
| 5170
| 1432
| Confusion Research Center
|-
| 5180
| 143C
| Solar Soyuz Zaibatsu
|-
| 5190
| 1446
| BooBip
|-
| 5191
| 1447
| Matthias Hampel
|-
| 5192
| 1448
| dec0de Consulting Ltd.
|-
| 5193
| 1449
| Puppy Concepts
|-
| 5194
| 144A
| Open Amiga Hardware Repository
|-
| 5195
| 144B
| Double H Tech
|-
| 5196
| 144C
| Retromatik
|-
| 5500
| 157C
| Inhouse Information
|-
| 5768
| 1688
| Bio Con
|-
| 6148
| 1804
| HK-Computer
|-
| 6502
| 1966
| Cloanto
|-
| 6520
| 1978
| Oliver Gantert
|-
| 7777
| 1E61
| Rafal Gabriel Chyla
|-
| 8215
| 2017
| Vortex
|-
| 8244
| 2034
| Spirit Technology
|-
| 8290
| 2062
| Expansion Systems
|-
| 8448
| 2100
| ReadySoft
|-
| 8512
| 2140
| Phase 5 Digital Products
|-
| 8553
| 2169
| Digital Processing Systems Inc.
|-
| 8704
| 2200
| ACT Elektronik
|-
| 8738
| 2222
| ACT Elektronik
|-
| 9512
| 2528
| Tower Technologies
|-
| 10676
| 29B4
| Electronic Design
|-
| 14195
| 3773
| Media-net-Point
|-
| 14501
| 38A5
| Petsoff, Finland
|-
| 16375
| 3FF7
| Uwe Gerlach
|-
| 16707
| 4143
| Ateo Concepts
|-
| 16708
| 4144
| ALiENDESiGN
|-
| 16945
| 4231
| A.C.T.
|-
| 17740
| 454C
| HK-Computer (ELSAT)
|-
| 18260
| 4754
| MacroSystems (Germany)
|-
| 19796
| 4D54
| Markt & Technik
|-
| 20480
| 5000
| François Lacombe
|-
| 22359
| 5757
| Markt & Technik
|-
| 26464
| 6760
| Combitec
|-
| 26470
| 6766
| Combitec
|-
| 28014
| 6D6E
| MNT Media and Technology UG
|-
| 28019
| 6D73
| Michal Schulz
|-
| 28020
| 6D74
| PiStorm
|-
| 32768
| 8000
| M.A.S.T.
|-
| 42240
| A500
| Aethreum Digital
|-
| 43437
| A9AD
| Reis-Ware
|-
| 43521
| AA01
| Cameron
|-
| 43537
| AA11
| Reis-Ware
|-
| 44359
| AD47
| Matay
|-
| 45141
| B055
| Tim Schattkowsky
|-
| 46504
| B5A8
| Phoenix
|-
| 48879
| BEEF
| Swiss Mountain Dog Products
|-
| 49160
| C008
| Combitec
|-
| 49374
| C0DE
| Stefan Reinauer
|-
| 61453
| F00D
| Forefront Technologies Inc.
|}

For any changes/additions to this registry see [[#How_to_Obtain_a_Manufacturer_Number|How to Obtain a Manufacturer Number]]

Amiga Hardware Manufacturer ID Registry

2026-09-08T11:23:24Z

Costel Mincea: /* Registry */

__TOC__

= How to Obtain a Manufacturer Number =

Manufacturer's numbers are assigned by the AmigaOS development team. To obtain your unique manufacturer number send a support request to [mailto:support@hyperion-entertainment.com support@hyperion-entertainment.com] including these information:

1. The name of the company or person which the number is assigned to

2. Postal address/contact address

3. Name of the contact person, with a corresponding e-mail address

4. A brief description of the kind of products you want to produce

= Your Manufacturer Number =

Attention hardware manufacturers. If you are developing a hardware expansion product for the Classic Amiga (e.g. 500, 2000, 3000) then you will need to obtain a special manufacturer ID number from the AmigaOS development team to identify your product. This manufacturer number is used by the Amiga to link your hardware with its driver software at boot time.

Your manufacturer number is part of the special protocol that the Amiga uses to automatically configure all expansion devices on the bus without the user having to cut jumpers or adjust dip switches. This is called auto-config.

At start-up time, the system first polls each board in the system and assigns the board its own address space. If it is a memory board, its RAM is linked into the memory free pool. Later in the boot sequence, after DOS is initialized, the binddrivers program is run. Binddrivers will search the directory SYS:Expansion for the drivers that go with the boards.

To do this binddrivers looks in the Tool Type field of all icon files in SYS:Expansion. If the first seven bytes of the Tool Type field are "PRODUCT", then this is an icon file for a driver.

Binddrivers will then attempt to match the drivers it has found with the boards that were found earlier. This is where your manufacturer number comes in.

Your manufacturer number goes in two places. First, it is burned in hex form into the PAL which is part of ALL auto-config expansion products. Second, it appears in ASCII in the Tool Type field of the icon file for your product's driver. By matching these two numbers, the Amiga can automatically configure your board and bind it's software driver into the system as well.

The manufacturer's number is a 16-bit ID which appears in PAL offsets $10-$17. There is also an 8-bit product number which you assign. The product number is for uniquely identifying different products from the same vendor. The product number will appear in PAL offsets $04-$07. This gives you a total of 24 bits to identify each of your products.

These 24 bits of information in the PAL which identify your product are matched against the information in the Tool Type field of all icon files in the SYS:Expansion drawer. For example, suppose you are manufacturer #1019. You have two products, #1 and #2 which both use the same driver. The icon for your driver for these two products would have a Tool Type set to "PRODUCT=1019/1|1019/2". This means: I am an icon for a driver that works with product number 1 or 2 from manufacturer 1019, now bind me. Spaces are not legal. Here are two other examples:

; PRODUCT=1208/11
: is the Tool Type for a driver for product 11 from manufacturer number 1208.

; PRODUCT=1017
: is the Tool Type for a driver for any product from manufacturer number 1017.

For an informal explanation of the auto-configuration process, see the chapter on Software Expansion Architecture from the 2nd Annual Amiga Developer's Conference Notes (available on ADCD 2.1). For the details of timing, power, the PAL equations and PAL address specifications and the expansion library documentation, see sections 3.1 to 3.3 of the A500/A2000 Technical Reference Manual. The original auto-config spec appears in the A1000 Schematics and Expansion Specification.

The auto-config process makes the addition of expansion products to the system very easy. All the user has to do is put the board in any slot and copy the driver from the release disk to his own SYS:Expansion drawer. Everything else is automatic. There are no jumpers or dip switches to set. Best of all, you will get a lot less support calls asking how to make your product work with the XYZ-Corp-battery-backed-clock.

= Notes =

Some notes on hardware manufacturer ID assignment.

* Manufacturer ID numbers are assigned free of charge.
* Please provide the following information when requesting an ID:
*# Name of the company or person
*# Postal address/contact address
*# Name of the contact person, with a corresponding e-mail address
*# A brief description of the kind of products you want to produce
* All ID numbers smaller than 5000 must be considered unsafe because no information exists on which numbers exactly were taken during the time Commodore, Inc. disintegrated.
* ID numbers in the range 8192 to 18841 must be considered unsafe because some hardware developers mistook the numbers assigned to them to be given in hexadecimal format. Hence 0x2000 = 8192 and 0x4999 = 18841.

= Example code =

<syntaxhighlight lang="C" line>
/*-----------------------------------------------*/
/* Here is a short program which will tell you */
/* about the expansion boards configured in your */
/* system without you opening up the machine. */
/* Code by Bill Koester of CATS */
/*-----------------------------------------------*/
#include <libraries/configvars.h>
#include <libraries/expansion.h>

struct ExpansionBase *ExpansionBase;

void cleanup();
void printdev();

int main()
{
struct ConfigDev *MyConfigDev;

/*----------------------------------*/
/* Open the expansion library, */
/* if there is a problem then exit */
/*----------------------------------*/

ExpansionBase =(struct ExpansionBase *) OpenLibrary(EXPANSIONNAME,0);
if(ExpansionBase==NULL)
{
printf("Error opening expansion library!!\n");
cleanup();
exit(0);
}

/*--------------------------------------------*/
/* Use FindConfigDev to get info on the first */
/* expansion board on the list maintained by */
/* Exec. If there are no expansion boards in */
/* the system then exit. */
/*--------------------------------------------*/

MyConfigDev = NULL;

/*--------------------------------------------------*/
/* FindConfigDev(oldConfigDev,manufacturer,product) */
/* oldConfigDev = NULL for the top of the list */
/* manufacturer = -1 for any manufacturer */
/* product = -1 for any product */
/*--------------------------------------------------*/

MyConfigDev = FindConfigDev(NULL,-1,-1);

if(MyConfigDev==NULL)
{
printf("No Configured Devices found!!\n");
cleanup();
exit(0);
}

printdev(MyConfigDev);

/*-----------------------------------*/
/* OK, there is at least one board, */
/* so loop and get the entire list */
/* printing as we go with printdev() */
/*-----------------------------------*/

while(MyConfigDev = FindConfigDev(MyConfigDev,-1,-1))
{
printdev(MyConfigDev);
}
cleanup();
return 0;
}

/*-------------------*/
/* Close up shop... */
/*-------------------*/
void cleanup()
{
if(ExpansionBase)
CloseLibrary(ExpansionBase);
}

/*----------------------------------*/
/* Print out the contents of the */
/* dev structure for this expansion */
/* product. */
/*----------------------------------*/

void printdev(dev)
struct ConfigDev *dev;
{
char buff[200];

printf("Flags = ");
if(dev->cd_Flags==NULL)
printf("NULL ");
if(dev->cd_Flags&CDF_SHUTUP)
printf("CDF_SHUTUP ");
if(dev->cd_Flags&CDF_CONFIGME)
printf("CDF_CONFIGME ");
printf("\n");
printf("Board Address = %x\n",dev->cd_BoardAddr);
printf("Board Size = %d bytes\n",dev->cd_BoardSize);
printf("Slot Address = %d\n",dev->cd_SlotAddr);
printf("Slot Size = %d\n",dev->cd_SlotSize);
printf("Driver code at %x\n",dev->cd_Driver);

printf("er_Type = %x\n",dev->cd_Rom.er_Type);
printf("er_Product = %x\n",dev->cd_Rom.er_Product);
printf("er_Flags = %x\n",dev->cd_Rom.er_Flags);
printf("er_Reserved03 = %x\n",dev->cd_Rom.er_Reserved03);
printf("er_Manufacturer = %x\n",dev->cd_Rom.er_Manufacturer);
printf("er_SerialNumber = %x\n",dev->cd_Rom.er_SerialNumber);
printf("er_InitDiagVec = %x\n",dev->cd_Rom.er_InitDiagVec);
printf("er_Reserved0c = %x\n",dev->cd_Rom.er_Reserved0c);
printf("er_Reserved0d = %x\n",dev->cd_Rom.er_Reserved0d);
printf("er_Reserved0e = %x\n",dev->cd_Rom.er_Reserved0e);
printf("er_Reserved0f = %x\n",dev->cd_Rom.er_Reserved0f);

printf("Hit Return to continue:\n");
gets(buff);
}
</syntaxhighlight>

= Registry =

{| class="wikitable"
! ID (decimal)
! ID (hexadecimal)
! Manufacturer
! Notes
|-
| 1
| 0001
| Micronik
|-
| 211
| 00D3
| Pacific Peripherals/Profex
|-
| 221
| 00DD
| Kupke Computertechnik GmbH
|-
| 256
| 0100
| Memphis
| Originally registered to MacroSystems US
|-
| 512
| 0200
| 3-State Computertechnik
|-
| 513
| 0201
| Commodore (Braunschweig)
|-
| 514
| 0202
| Commodore (West Chester)
|-
| 515
| 0203
| Commodore (West Chester)
| Originally registered to Combitech/Macrosystem
|-
| 756
| 02F4
| Progressive Peripherals & Software
|-
| 767
| 02FF
| Kolff Computer Supplies
|-
| 1001
| 03E9
| Tecmar
|-
| 1002
| 03EA
| Telesys
|-
| 1003
| 03EB
| The Micro-Forge
|-
| 1004
| 03EC
| Kronos/C Ltd.
| Originally registered to Card Co. (Supra)
|-
| 1005
| 03ED
| A-Squared
|-
| 1006
| 03EE
| Comspec Communications
|-
| 1007
| 03EF
| HT Electronics
|-
| 1008
| 03F0
| RDS Software
|-
| 1009
| 03F1
| Anakin Research
|-
| 1010
| 03F2
| MicroBotics
|-
| 1011
| 03F3
| Bob Krauth
|-
| 1012
| 03F4
| Access Associates (Alegra)
|-
| 1013
| 03F5
| Mini Comp Systems Ltd.
|-
| 1014
| 03F6
| Cypress Technology
|-
| 1015
| 03F7
| Fuller Computers
|-
| 1016
| 03F8
| Galaxy Computers
|-
| 1017
| 03F9
| ADA Research
|-
| 1018
| 03FA
| Computer Service Italia
|-
| 1019
| 03FB
| Amigo
|-
| 1020
| 03FC
| Micro-Solutions Inc.
|-
| 1021
| 03FD
| Stacar International
|-
| 1022
| 03FE
| Video Precisions
|-
| 1023
| 03FF
| ASDG, Inc.
|-
| 1025
| 0401
| Ing. Buero Kalawsky
|-
| 1026
| 0402
| Computer Tuning
|-
| 1027
| 0403
| Interplan Unternehmensberatung
|-
| 1028
| 0404
| Imtronics/Memphis
| Originally registered to Peter Ohlich
|-
| 1030
| 0406
| Commodore (Lowell University)
| Originally registered to Productivity Center
|-
| 1041
| 0411
| Design Labs
|-
| 1042
| 0412
| MCS
|-
| 1043
| 0413
| B. J. Freeman
|-
| 1044
| 0414
| Side Effects Inc.
|-
| 1045
| 0415
| Oklahoma Personal Comp.
|-
| 1046
| 0416
| Advanced Micro Innovations
|-
| 1047
| 0417
| Industrial Support Services
|-
| 1048
| 0418
| Technisoft
|-
| 1049
| 0419
| Prolific, Inc.
|-
| 1050
| 041A
| Softeam, Inc.
|-
| 1051
| 041B
| GRC Electronics
|-
| 1052
| 041C
| David Lai
|-
| 1053
| 041D
| Ameristar Technologies
|-
| 1054
| 041E
| Cline Refrigeration
|-
| 1055
| 041F
| Cardiac Pacemakers, Inc.
|-
| 1056
| 0420
| Supra Corp. (Creative Microsystems)
|-
| 1057
| 0421
| Wayne Diener
|-
| 1058
| 0422
| Computer Systems Associates (CSA)
|-
| 1059
| 0423
| Trionix, Inc.
|-
| 1060
| 0424
| David Lucas
|-
| 1061
| 0425
| Analog Precision
| Also assigned to D & L Distributing
|-
| 1267
| 04F3
| RBM Digitaltechnik
|-
| 1282
| 0502
| M-TEC Hardware Design
|-
| 1337
| 0539
| Thomas Stenzel (DaFR34K)
|-
| 1576
| 0628
| Boris Križma
|-
| 1729
| 06C1
| Thomas Richter / OpenPCI-A1200 Mediator bridge
|-
| 1730
| 06C2
| Thomas Richter / OpenPCI-A4000 Mediator bridge
|-
| 1731
| 06C3
| Thomas Richter / OpenPCI-Prometheus bridge (Firestorm or original)
|-
| 1732
| 06C4
| Thomas Richter / OpenPCI-Reserved1
|-
| 1733
| 06C5
| Thomas Richter / OpenPCI-Grex bridge (both A1200 and A4000)
|-
| 1734
| 06C6
| Thomas Richter / OpenPCI-Reserved2
|-
| 1735
| 06C7
| Thomas Richter / OpenPCI-Reserved3
|-
| 1736
| 06C8
| Thomas Richter / OpenPCI-Reserved4
|-
| 1737
| 06C9
| Thomas Richter / OpenPCI-Reserved5
|-
| 1738
| 06CA
| Thomas Richter / OpenPCI-Reserved6
|-
| 1739
| 06CB
| Thomas Richter / OpenPCI-Reserved7
|-
| 1740
| 06CC
| Thomas Richter / OpenPCI-Reserved8
|-
| 1741
| 06CD
| Thomas Richter / OpenPCI-Reserved9
|-
| 1742
| 06CE
| Thomas Richter / OpenPCI-Reserved10
|-
| 1743
| 06CF
| Thomas Richter / OpenPCI-Reserved11
|-
| 1744
| 06D0
| Thomas Richter / OpenPCI-Reserved12
|-
| 1761
| 06E1
| Great Valley Products
|-
| 1803
| 070B
| UAE Amiga Emulator
|-
| 2002
| 07D2
| Mimetics Corp.
|-
| 2003
| 07D3
| ACDA
|-
| 2004
| 07D4
| Finn R. Jacobsen
|-
| 2005
| 07D5
| Elthen Electronics
|-
| 2006
| 07D6
| Nine Tiles Computer Systems Ltd.
|-
| 2007
| 07D7
| Analog Electronics
|-
| 2008
| 07D8
| Bell & Howell
|-
| 2009
| 07D9
| Roland Kochler
|-
| 2010
| 07DA
| Byte Corp.
|-
| 2011
| 07DB
| Reserved
|-
| 2012
| 07DC
| DKB, Inc.
| Previously named Michigan Software
|-
| 2013
| 07DD
| Pacific Peripherals
|-
| 2014
| 07DE
| Sysaphus Software
|-
| 2015
| 07DF
| Digitronics
|-
| 2016
| 07E0
| Akron Systems
|-
| 2017
| 07E1
| Great Valley Products
|-
| 2018
| 07E2
| Calmos
|-
| 2019
| 07E3
| Dover Research
|-
| 2020
| 07E4
| David Krehbiel
|-
| 2021
| 07E5
| Synergy Peripheral Systems
| Also known as California Access
|-
| 2022
| 07E6
| Xetec
|-
| 2023
| 07E7
| Micron Technology
|-
| 2024
| 07E8
| CH Electronics
|-
| 2025
| 07E9
| American Liquid Light
|-
| 2026
| 07EA
| Progressive Peripherals & Software
| Also used by Ateo
|-
| 2027
| 07EB
| Wicat Systems
|-
| 2028
| 07EC
| Applied Systems & Peripherals
|-
| 2029
| 07ED
| Delaware Valley Software
|-
| 2030
| 07EE
| Palomax
|-
| 2031
| 07EF
| Incognito Software
|-
| 2032
| 07F0
| Jadesign
|-
| 2033
| 07F1
| BVR
|-
| 2034
| 07F2
| Spirit Technology
|-
| 2035
| 07F3
| Spirit Technology
|-
| 2036
| 07F4
| Atronic
|-
| 2037
| 07F5
| Scott Karlin
|-
| 2038
| 07F6
| Howitch
|-
| 2039
| 07F7
| Sullivan Brothers Visual Engineers
|-
| 2040
| 07F8
| G I T
|-
| 2041
| 07F9
| Amigo Business Computers
|-
| 2042
| 07FA
| Micro E Ab
|-
| 2043
| 07FB
| Ralph Kruse
|-
| 2044
| 07FC
| Clearpoint Research
|-
| 2045
| 07FD
| Kodiak
|-
| 2046
| 07FE
| BSC
| Originally registered to Phoenix Electronics
|-
| 2047
| 07FF
| No Name Shown
|-
| 2048
| 0800
| Commodore Braunschweig
|-
| 2049
| 0801
| BSC
| Originally registered to Elaborate Bytes
|-
| 2050
| 0802
| Kronos/C Ltd.
|-
| 2051
| 0803
| Spartanics
|-
| 2052
| 0804
| Jochheim Computer Tuning
|-
| 2053
| 0805
| Trans Data Systems
|-
| 2054
| 0806
| Applied Systems & Peripherals Ltd.
|-
| 2055
| 0807
| Checkpoint Technologies
| Originally registered to Amiga Solutions
|-
| 2056
| 0808
| Adept Development
|-
| 2057
| 0809
| Advanced Computer Design
|-
| 2058
| 080A
| Sir Netics
|-
| 2059
| 080B
| Expert Services
|-
| 2060
| 080C
| Digital Art Systems
|-
| 2061
| 080D
| Adept Development
|-
| 2062
| 080E
| Expansion Technologies (Expansion Systems)
|-
| 2063
| 080F
| Alphatech
|-
| 2064
| 0810
| Edotronik GmbH
|-
| 2065
| 0811
| California Access/Synergy
| Originally registered to Logical Design Works
|-
| 2066
| 0812
| Bowden, Williams, Full & Assoc.
|-
| 2067
| 0813
| NES, Inc.
|-
| 2068
| 0814
| Amdev
|-
| 2069
| 0815
| Big Brother Security Systems
|-
| 2070
| 0816
| Active Circuits Inc.
|-
| 2071
| 0817
| ICD, Inc.
|-
| 2072
| 0818
| Multi-Meg Electronique
|-
| 2073
| 0819
| Kupke Computertechnik GmbH
|-
| 2074
| 081A
| The Checkered Ball
|-
| 2075
| 081B
| Hi Tension Computer Services Ltd. (UK)
|-
| 2076
| 081C
| Alfa Data
| Originally assigned to Elmtech Research, Ltd. (UK)
|-
| 2077
| 081D
| Great Valley Products
| Originally registered to Clartscreen, Ltd. (UK)
|-
| 2078
| 081E
| Interworks
|-
| 2079
| 081F
| Galysh Enterprises
|-
| 2080
| 0820
| Hardital Synthesis
| Originally registered to Realtime Games Software Ltd.
|-
| 2081
| 0821
| GBS
|-
| 2082
| 0822
| Circum Design Inc.
|-
| 2083
| 0823
| Alberta Micro Electronic Center
|-
| 2084
| 0824
| Bestech
|-
| 2085
| 0825
| Lasar Fantasy
|-
| 2086
| 0826
| Pulsar
|-
| 2087
| 0827
| Ivis
|-
| 2088
| 0828
| Applied Engineering
|-
| 2089
| 0829
| Solid-State Design & Development
|-
| 2090
| 082A
| Vison Quest
|-
| 2091
| 082B
| Seaview Software
|-
| 2092
| 082C
| BSC
| Mistakenly used by ADS (Advanced Development Software)
|-
| 2093
| 082D
| Bernd Culenfeld
|-
| 2094
| 082E
| American Liquid Light
|-
| 2095
| 082F
| CEGITES
|-
| 2096
| 0830
| Quadlite Computers Ltd.
| Originally registered to EV Industries
|-
| 2097
| 0831
| Silicon Peace
|-
| 2098
| 0832
| Black Belt Systems
|-
| 2099
| 0833
| Village Tronic
| Originally registerd to Steve Yaeger
|-
| 2100
| 0834
| ReadySoft
|-
| 2101
| 0835
| Phoenix Micro Technologies
|-
| 2102
| 0836
| Advanced Systems & Software
| Orignally assigned to Preferred Technology
|-
| 2103
| 0837
| Rombo Productions
|-
| 2104
| 0838
| Impulse Inc.
|-
| 2105
| 0839
| Beta Unlimited
|-
| 2106
| 083A
| Memory Expansion System, Ltd.
|-
| 2107
| 083B
| Vortex Computer Systems GmbH
|-
| 2108
| 083C
| Platypus Systems
|-
| 2109
| 083D
| Gigatron OHG
|-
| 2110
| 083E
| PG Electronics
|-
| 2111
| 083F
| New Technologies Group
|-
| 2112
| 0840
| Interactive Video Systems (IVS)
| Pacific Peripherals
|-
| 2113
| 0841
| Vector
| Originally registered to H. K. Computer
|-
| 2114
| 0842
| Pacific Digital
| Originally registered to C. H. Helfrich Elektronik
|-
| 2115
| 0843
| Xanadu
|-
| 2116
| 0844
| Pacific Digital
| Originally registered to AMS
|-
| 2117
| 0845
| X-Pert
|-
| 2118
| 0846
| The Amiga Centre
|-
| 2119
| 0847
| Digital Pacific
|-
| 2120
| 0848
| Solid State Leisure
|-
| 2121
| 0849
| Hydra Systems
| Originally registered to Analog Electronics
|-
| 2122
| 084A
| Cumana
|-
| 2123
| 084B
| KAPS 2C Conception
|-
| 2124
| 084C
| Mike Mason
|-
| 2125
| 084D
| For Your Eyes
|-
| 2126
| 084E
| Volkmar Breitfeld Computersysteme
|-
| 2127
| 084F
| Sunrize Industries
|-
| 2128
| 0850
| Scott Advanced Micro Designs
|-
| 2129
| 0851
| Digital Micronics
|-
| 2130
| 0852
| Alfa-Laval
|-
| 2131
| 0853
| Multigros A/S
|-
| 2132
| 0854
| Archos
|-
| 2133
| 0855
| Icom Simulations
|-
| 2134
| 0856
| Commodore Test Engineering Group
|-
| 2135
| 0857
| Microcreations
|-
| 2136
| 0858
| Shoestring Productions
|-
| 2137
| 0859
| Faberushi
|-
| 2138
| 085A
| Evesham Micro Ltd.
|-
| 2139
| 085B
| Panagolin Laser Software
|-
| 2140
| 085C
| Thomas Rudloff
|-
| 2141
| 085D
| Daniel Hohabir
|-
| 2142
| 085E
| GfxBase, Inc.
|-
| 2143
| 085F
| Axellabs
|-
| 2144
| 0860
| Roctec Electronics Inc.
|-
| 2145
| 0861
| Omega Datentechnik
|-
| 2146
| 0862
| Atlantis
|-
| 2147
| 0863
| Skytec Computers
|-
| 2148
| 0864
| Protar Electronics
|-
| 2149
| 0865
| ACS
|-
| 2150
| 0866
| Software Results Enterprises
| Originally registered to University of Illinois
|-
| 2151
| 0867
| Infinity Systems Design Group
|-
| 2152
| 0868
| Trade It
|-
| 2153
| 0869
| Suntec, Inc.
|-
| 2154
| 086A
| DJW Micro Systems
| Originally registered to Tritec Marketing
|-
| 2155
| 086B
| Power Computing Ltd.
|-
| 2156
| 086C
| MacroSystems
|-
| 2157
| 086D
| Masoboshi GmbH (DCE)
|-
| 2158
| 086E
| HAL Software Hardware Handel
|-
| 2159
| 086F
| Mainhattan Data
| Originally registered to Michael Lamm Computersysteme
|-
| 2160
| 0870
| Digital Processing System
| Originally registered to bbdp Electronics
|-
| 2161
| 0871
| Blue Ribbon Soundworks
| Originally registered to Design Computer Systems
|-
| 2162
| 0872
| XPert
| Originally registered to The Station
|-
| 2163
| 0873
| DelaComp
| Originally registered to Bryan Williams
|-
| 2164
| 0874
| Superformance Computer Engineering GmbH
|-
| 2165
| 0875
| Overland Engineering
|-
| 2166
| 0876
| Thomas Hamren
|-
| 2167
| 0877
| Village Tronic
|-
| 2168
| 0878
| Toolbox Design
|-
| 2169
| 0879
| Digital Processing System
|-
| 2170
| 087A
| Superformance
|-
| 2171
| 087B
| Utilities Unlimited
|-
| 2172
| 087C
| phase 5
|-
| 2173
| 087D
| Juergen Kommos
|-
| 2174
| 087E
| Electronic Design
|-
| 2175
| 087F
| James Cook University of North Queensland
|-
| 2176
| 0880
| AmiTrix Development
|-
| 2177
| 0881
| Ferranti
|-
| 2178
| 0882
| Leviathan Development
|-
| 2179
| 0883
| United Video Inc.
|-
| 2180
| 0884
| GPSoft Pty. Ltd.
| Originally registered to Juergen Kommos
|-
| 2181
| 0885
| ArMAX
| Oliver Bausch
|-
| 2182
| 0886
| CP Computer
|-
| 2183
| 0887
| Amiga Modula & Oberon Klub
|-
| 2184
| 0888
| ITEK Neser & Sieber GbR
|-
| 2185
| 0889
| Phillip C. Lello
|-
| 2186
| 088A
| Cyborg Design Services
|-
| 2187
| 088B
| G2 Systems
|-
| 2188
| 088C
| Pro System Computersysteme
|-
| 2189
| 088D
| ZEUS Electronic
| Originally registered to MSPI (Markt & Technik)
|-
| 2190
| 088E
| Altatech
|-
| 2191
| 088F
| NewTek
|-
| 2192
| 0890
| M-TEC Hardware Design
| Originally registered to Hardware Design Udo Neuroth
|-
| 2193
| 0891
| Great Valley Products
| Originally registered to Viona Development
|-
| 2194
| 0892
| Amitek
| Originally assigned to Marpet Developments
|-
| 2195
| 0893
| Ingenieurbuero Helfrich
|-
| 2196
| 0894
| The Neo Group
|-
| 2197
| 0895
| Cyon
|-
| 2198
| 0896
| Bob Research Group
|-
| 2199
| 0897
| Richmond Sound Design Ltd.
|-
| 2200
| 0898
| US Cybernetics
|-
| 2201
| 0899
| Fulvio Ieva
|-
| 2202
| 089A
| Silicon Studio
|-
| 2203
| 089B
| MacroSystems (USA)
| Was named Micro System Devices
|-
| 2204
| 089C
| Conspector Entertainment
|-
| 2205
| 089D
| Laserforum
|-
| 2206
| 089E
| Elbox Computer
| Mistakenly used by Index Information Ltd.
|-
| 2207
| 089F
| Applied Magic Inc.
|-
| 2208
| 08A0
| SDL Ltd.
|-
| 2560
| 0A00
| Harms
|-
| 2588
| 0A1C
| A1K.org Community
|-
| 2640
| 0A50
| Micronik
|-
| 2782
| 2782
| OA Design
|-
| 3084
| 0C0C
| Team 4
|-
| 3643
| 0E3B
| E3B
| Michael Boehmer
|-
| 3855
| 0F0F
| Micronik
|-
| 4096
| 1000
| MegaMicro
|-
| 4110
| 100E
| DigiFeX
|-
| 4136
| 1028
| Imtronics/Memphis
|-
| 4149
| 1035
| PROTAR
|-
| 4369
| 1111
| Frank Strauß Elektronik
| Also used by Kupke
|-
| 4626
| 1212
| Individual Computers
|-
| 4648
| 1228
| Flesch Hornemann Computer Elec.
|-
| 4680
| 1248
| Kupke Computertechnik GmbH
|-
| 4711
| 1267
| RBM digitaltechnik
|-
| 4754
| 1292
| MacroSystems
|-
| 5000
| 1388
| ITH
|-
| 5001
| 1389
| VMC
|-
| 5010
| 1392
| Ambience Creation Technology
|-
| 5011
| 1393
| Creative Development
|-
| 5012
| 1394
| Georg Braun
|-
| 5013
| 1395
| Swedish User Group of Amiga
|-
| 5014
| 1396
| Jakub Bednarski
|-
| 5015
| 1397
| KryoFlux, Ltd.
|-
| 5016
| 1398
| Igor Majstorovic
|-
| 5017
| 1399
| Alastair M. Robinson
|-
| 5018
| 139A
| Austex Software
|-
| 5019
| 139B
| Sören Gust
|-
| 5020
| 139C
| Rok Krajnc
|-
| 5030
| 13A6
| Tim Tashpulatov
|-
| 5040
| 13B0
| 7-bit
|-
| 5050
| 13BA
| Sakura IT
|-
| 5060
| 13C4
| FPGAArcade
|-
| 5070
| 13CE
| CancerSoft Inc.
|-
| 5080
| 13D8
| Stephen Leary
|-
| 5090
| 13E2
| DMA Softlab LLC
|-
| 5100
| 13EC
| Brookhouse Engineering
|-
| 5110
| 13F6
| Eduardo Arana
|-
| 5120
| 1400
| CS-LAB
|-
| 5130
| 140A
| Robert Miranda
|-
| 5132
| 140C
| UAS Interface Ltd.
|-
| 5140
| 1414
| RastPort
|-
| 5150
| 141E
| Amiga Kit
|-
| 5160
| 1428
| Central Texas Commodore User Group
|-
| 5170
| 1432
| Confusion Research Center
|-
| 5180
| 143C
| Solar Soyuz Zaibatsu
|-
| 5190
| 1446
| BooBip
|-
| 5191
| 1447
| Matthias Hampel
|-
| 5192
| 1448
| dec0de Consulting Ltd.
|-
| 5193
| 1449
| Puppy Concepts
|-
| 5194
| 144A
| Open Amiga Hardware Repository
|-
| 5195
| 144B
| Double H Tech
|-
| 5196
| 144C
| Retromatik
|-
| 5500
| 157C
| Inhouse Information
|-
| 5768
| 1688
| Bio Con
|-
| 6148
| 1804
| HK-Computer
|-
| 6502
| 1966
| Cloanto
|-
| 6520
| 1978
| Oliver Gantert
|-
| 7777
| 1E61
| Rafal Gabriel Chyla
|-
| 8215
| 2017
| Vortex
|-
| 8244
| 2034
| Spirit Technology
|-
| 8290
| 2062
| Expansion Systems
|-
| 8448
| 2100
| ReadySoft
|-
| 8512
| 2140
| Phase 5 Digital Products
|-
| 8553
| 2169
| Digital Processing Systems Inc.
|-
| 8704
| 2200
| ACT Elektronik
|-
| 8738
| 2222
| ACT Elektronik
|-
| 9512
| 2528
| Tower Technologies
|-
| 10676
| 29B4
| Electronic Design
|-
| 14195
| 3773
| Media-net-Point
|-
| 14501
| 38A5
| Petsoff, Finland
|-
| 16375
| 3FF7
| Uwe Gerlach
|-
| 16707
| 4143
| Ateo Concepts
|-
| 16708
| 4144
| ALiENDESiGN
|-
| 16945
| 4231
| A.C.T.
|-
| 17740
| 454C
| HK-Computer (ELSAT)
|-
| 18260
| 4754
| MacroSystems (Germany)
|-
| 19796
| 4D54
| Markt & Technik
|-
| 20480
| 5000
| François Lacombe
|-
| 22359
| 5757
| Markt & Technik
|-
| 26464
| 6760
| Combitec
|-
| 26470
| 6766
| Combitec
|-
| 28014
| 6D6E
| MNT Media and Technology UG
|-
| 28019
| 6D73
| Michal Schulz
|-
| 28020
| 6D74
| PiStorm
|-
| 32768
| 8000
| M.A.S.T.
|-
| 42240
| A500
| Aethreum Digital
|-
| 43437
| A9AD
| Reis-Ware
|-
| 43521
| AA01
| Cameron
|-
| 43537
| AA11
| Reis-Ware
|-
| 44359
| AD47
| Matay
|-
| 46504
| B5A8
| Phoenix
|-
| 48879
| BEEF
| Swiss Mountain Dog Products
|-
| 49160
| C008
| Combitec
|-
| 49374
| C0DE
| Stefan Reinauer
|-
| 61453
| F00D
| Forefront Technologies Inc.
|}

For any changes/additions to this registry see [[#How_to_Obtain_a_Manufacturer_Number|How to Obtain a Manufacturer Number]]

Amiga Hardware Manufacturer ID Registry

2026-09-08T11:14:58Z

Costel Mincea: Added Stefan Reinauer (49374)

__TOC__

= How to Obtain a Manufacturer Number =

Manufacturer's numbers are assigned by the AmigaOS development team. To obtain your unique manufacturer number send a support request to [mailto:support@hyperion-entertainment.com support@hyperion-entertainment.com] including these information:

1. The name of the company or person which the number is assigned to

2. Postal address/contact address

3. Name of the contact person, with a corresponding e-mail address

4. A brief description of the kind of products you want to produce

= Your Manufacturer Number =

Attention hardware manufacturers. If you are developing a hardware expansion product for the Classic Amiga (e.g. 500, 2000, 3000) then you will need to obtain a special manufacturer ID number from the AmigaOS development team to identify your product. This manufacturer number is used by the Amiga to link your hardware with its driver software at boot time.

Your manufacturer number is part of the special protocol that the Amiga uses to automatically configure all expansion devices on the bus without the user having to cut jumpers or adjust dip switches. This is called auto-config.

At start-up time, the system first polls each board in the system and assigns the board its own address space. If it is a memory board, its RAM is linked into the memory free pool. Later in the boot sequence, after DOS is initialized, the binddrivers program is run. Binddrivers will search the directory SYS:Expansion for the drivers that go with the boards.

To do this binddrivers looks in the Tool Type field of all icon files in SYS:Expansion. If the first seven bytes of the Tool Type field are "PRODUCT", then this is an icon file for a driver.

Binddrivers will then attempt to match the drivers it has found with the boards that were found earlier. This is where your manufacturer number comes in.

Your manufacturer number goes in two places. First, it is burned in hex form into the PAL which is part of ALL auto-config expansion products. Second, it appears in ASCII in the Tool Type field of the icon file for your product's driver. By matching these two numbers, the Amiga can automatically configure your board and bind it's software driver into the system as well.

The manufacturer's number is a 16-bit ID which appears in PAL offsets $10-$17. There is also an 8-bit product number which you assign. The product number is for uniquely identifying different products from the same vendor. The product number will appear in PAL offsets $04-$07. This gives you a total of 24 bits to identify each of your products.

These 24 bits of information in the PAL which identify your product are matched against the information in the Tool Type field of all icon files in the SYS:Expansion drawer. For example, suppose you are manufacturer #1019. You have two products, #1 and #2 which both use the same driver. The icon for your driver for these two products would have a Tool Type set to "PRODUCT=1019/1|1019/2". This means: I am an icon for a driver that works with product number 1 or 2 from manufacturer 1019, now bind me. Spaces are not legal. Here are two other examples:

; PRODUCT=1208/11
: is the Tool Type for a driver for product 11 from manufacturer number 1208.

; PRODUCT=1017
: is the Tool Type for a driver for any product from manufacturer number 1017.

For an informal explanation of the auto-configuration process, see the chapter on Software Expansion Architecture from the 2nd Annual Amiga Developer's Conference Notes (available on ADCD 2.1). For the details of timing, power, the PAL equations and PAL address specifications and the expansion library documentation, see sections 3.1 to 3.3 of the A500/A2000 Technical Reference Manual. The original auto-config spec appears in the A1000 Schematics and Expansion Specification.

The auto-config process makes the addition of expansion products to the system very easy. All the user has to do is put the board in any slot and copy the driver from the release disk to his own SYS:Expansion drawer. Everything else is automatic. There are no jumpers or dip switches to set. Best of all, you will get a lot less support calls asking how to make your product work with the XYZ-Corp-battery-backed-clock.

= Notes =

Some notes on hardware manufacturer ID assignment.

* Manufacturer ID numbers are assigned free of charge.
* Please provide the following information when requesting an ID:
*# Name of the company or person
*# Postal address/contact address
*# Name of the contact person, with a corresponding e-mail address
*# A brief description of the kind of products you want to produce
* All ID numbers smaller than 5000 must be considered unsafe because no information exists on which numbers exactly were taken during the time Commodore, Inc. disintegrated.
* ID numbers in the range 8192 to 18841 must be considered unsafe because some hardware developers mistook the numbers assigned to them to be given in hexadecimal format. Hence 0x2000 = 8192 and 0x4999 = 18841.

= Example code =

<syntaxhighlight lang="C" line>
/*-----------------------------------------------*/
/* Here is a short program which will tell you */
/* about the expansion boards configured in your */
/* system without you opening up the machine. */
/* Code by Bill Koester of CATS */
/*-----------------------------------------------*/
#include <libraries/configvars.h>
#include <libraries/expansion.h>

struct ExpansionBase *ExpansionBase;

void cleanup();
void printdev();

int main()
{
struct ConfigDev *MyConfigDev;

/*----------------------------------*/
/* Open the expansion library, */
/* if there is a problem then exit */
/*----------------------------------*/

ExpansionBase =(struct ExpansionBase *) OpenLibrary(EXPANSIONNAME,0);
if(ExpansionBase==NULL)
{
printf("Error opening expansion library!!\n");
cleanup();
exit(0);
}

/*--------------------------------------------*/
/* Use FindConfigDev to get info on the first */
/* expansion board on the list maintained by */
/* Exec. If there are no expansion boards in */
/* the system then exit. */
/*--------------------------------------------*/

MyConfigDev = NULL;

/*--------------------------------------------------*/
/* FindConfigDev(oldConfigDev,manufacturer,product) */
/* oldConfigDev = NULL for the top of the list */
/* manufacturer = -1 for any manufacturer */
/* product = -1 for any product */
/*--------------------------------------------------*/

MyConfigDev = FindConfigDev(NULL,-1,-1);

if(MyConfigDev==NULL)
{
printf("No Configured Devices found!!\n");
cleanup();
exit(0);
}

printdev(MyConfigDev);

/*-----------------------------------*/
/* OK, there is at least one board, */
/* so loop and get the entire list */
/* printing as we go with printdev() */
/*-----------------------------------*/

while(MyConfigDev = FindConfigDev(MyConfigDev,-1,-1))
{
printdev(MyConfigDev);
}
cleanup();
return 0;
}

/*-------------------*/
/* Close up shop... */
/*-------------------*/
void cleanup()
{
if(ExpansionBase)
CloseLibrary(ExpansionBase);
}

/*----------------------------------*/
/* Print out the contents of the */
/* dev structure for this expansion */
/* product. */
/*----------------------------------*/

void printdev(dev)
struct ConfigDev *dev;
{
char buff[200];

printf("Flags = ");
if(dev->cd_Flags==NULL)
printf("NULL ");
if(dev->cd_Flags&CDF_SHUTUP)
printf("CDF_SHUTUP ");
if(dev->cd_Flags&CDF_CONFIGME)
printf("CDF_CONFIGME ");
printf("\n");
printf("Board Address = %x\n",dev->cd_BoardAddr);
printf("Board Size = %d bytes\n",dev->cd_BoardSize);
printf("Slot Address = %d\n",dev->cd_SlotAddr);
printf("Slot Size = %d\n",dev->cd_SlotSize);
printf("Driver code at %x\n",dev->cd_Driver);

printf("er_Type = %x\n",dev->cd_Rom.er_Type);
printf("er_Product = %x\n",dev->cd_Rom.er_Product);
printf("er_Flags = %x\n",dev->cd_Rom.er_Flags);
printf("er_Reserved03 = %x\n",dev->cd_Rom.er_Reserved03);
printf("er_Manufacturer = %x\n",dev->cd_Rom.er_Manufacturer);
printf("er_SerialNumber = %x\n",dev->cd_Rom.er_SerialNumber);
printf("er_InitDiagVec = %x\n",dev->cd_Rom.er_InitDiagVec);
printf("er_Reserved0c = %x\n",dev->cd_Rom.er_Reserved0c);
printf("er_Reserved0d = %x\n",dev->cd_Rom.er_Reserved0d);
printf("er_Reserved0e = %x\n",dev->cd_Rom.er_Reserved0e);
printf("er_Reserved0f = %x\n",dev->cd_Rom.er_Reserved0f);

printf("Hit Return to continue:\n");
gets(buff);
}
</syntaxhighlight>

= Registry =

{| class="wikitable"
! ID (decimal)
! ID (hexadecimal)
! Manufacturer
! Notes
|-
| 1
| 0001
| Micronik
|-
| 211
| 00D3
| Pacific Peripherals/Profex
|-
| 221
| 00DD
| Kupke Computertechnik GmbH
|-
| 256
| 0100
| Memphis
| Originally registered to MacroSystems US
|-
| 512
| 0200
| 3-State Computertechnik
|-
| 513
| 0201
| Commodore (Braunschweig)
|-
| 514
| 0202
| Commodore (West Chester)
|-
| 515
| 0203
| Commodore (West Chester)
| Originally registered to Combitech/Macrosystem
|-
| 756
| 02F4
| Progressive Peripherals & Software
|-
| 767
| 02FF
| Kolff Computer Supplies
|-
| 1001
| 03E9
| Tecmar
|-
| 1002
| 03EA
| Telesys
|-
| 1003
| 03EB
| The Micro-Forge
|-
| 1004
| 03EC
| Kronos/C Ltd.
| Originally registered to Card Co. (Supra)
|-
| 1005
| 03ED
| A-Squared
|-
| 1006
| 03EE
| Comspec Communications
|-
| 1007
| 03EF
| HT Electronics
|-
| 1008
| 03F0
| RDS Software
|-
| 1009
| 03F1
| Anakin Research
|-
| 1010
| 03F2
| MicroBotics
|-
| 1011
| 03F3
| Bob Krauth
|-
| 1012
| 03F4
| Access Associates (Alegra)
|-
| 1013
| 03F5
| Mini Comp Systems Ltd.
|-
| 1014
| 03F6
| Cypress Technology
|-
| 1015
| 03F7
| Fuller Computers
|-
| 1016
| 03F8
| Galaxy Computers
|-
| 1017
| 03F9
| ADA Research
|-
| 1018
| 03FA
| Computer Service Italia
|-
| 1019
| 03FB
| Amigo
|-
| 1020
| 03FC
| Micro-Solutions Inc.
|-
| 1021
| 03FD
| Stacar International
|-
| 1022
| 03FE
| Video Precisions
|-
| 1023
| 03FF
| ASDG, Inc.
|-
| 1025
| 0401
| Ing. Buero Kalawsky
|-
| 1026
| 0402
| Computer Tuning
|-
| 1027
| 0403
| Interplan Unternehmensberatung
|-
| 1028
| 0404
| Imtronics/Memphis
| Originally registered to Peter Ohlich
|-
| 1030
| 0406
| Commodore (Lowell University)
| Originally registered to Productivity Center
|-
| 1041
| 0411
| Design Labs
|-
| 1042
| 0412
| MCS
|-
| 1043
| 0413
| B. J. Freeman
|-
| 1044
| 0414
| Side Effects Inc.
|-
| 1045
| 0415
| Oklahoma Personal Comp.
|-
| 1046
| 0416
| Advanced Micro Innovations
|-
| 1047
| 0417
| Industrial Support Services
|-
| 1048
| 0418
| Technisoft
|-
| 1049
| 0419
| Prolific, Inc.
|-
| 1050
| 041A
| Softeam, Inc.
|-
| 1051
| 041B
| GRC Electronics
|-
| 1052
| 041C
| David Lai
|-
| 1053
| 041D
| Ameristar Technologies
|-
| 1054
| 041E
| Cline Refrigeration
|-
| 1055
| 041F
| Cardiac Pacemakers, Inc.
|-
| 1056
| 0420
| Supra Corp. (Creative Microsystems)
|-
| 1057
| 0421
| Wayne Diener
|-
| 1058
| 0422
| Computer Systems Associates (CSA)
|-
| 1059
| 0423
| Trionix, Inc.
|-
| 1060
| 0424
| David Lucas
|-
| 1061
| 0425
| Analog Precision
| Also assigned to D & L Distributing
|-
| 1267
| 04F3
| RBM Digitaltechnik
|-
| 1282
| 0502
| M-TEC Hardware Design
|-
| 1337
| 0539
| Thomas Stenzel (DaFR34K)
|-
| 1576
| 0628
| Boris Križma
|-
| 1729
| 06C1
| Thomas Richter / OpenPCI-A1200 Mediator bridge
|-
| 1730
| 06C2
| Thomas Richter / OpenPCI-A4000 Mediator bridge
|-
| 1731
| 06C3
| Thomas Richter / OpenPCI-Prometheus bridge (Firestorm or original)
|-
| 1732
| 06C4
| Thomas Richter / OpenPCI-Reserved1
|-
| 1733
| 06C5
| Thomas Richter / OpenPCI-Grex bridge (both A1200 and A4000)
|-
| 1734
| 06C6
| Thomas Richter / OpenPCI-Reserved2
|-
| 1735
| 06C7
| Thomas Richter / OpenPCI-Reserved3
|-
| 1736
| 06C8
| Thomas Richter / OpenPCI-Reserved4
|-
| 1737
| 06C9
| Thomas Richter / OpenPCI-Reserved5
|-
| 1738
| 06CA
| Thomas Richter / OpenPCI-Reserved6
|-
| 1739
| 06CB
| Thomas Richter / OpenPCI-Reserved7
|-
| 1740
| 06CC
| Thomas Richter / OpenPCI-Reserved8
|-
| 1741
| 06CD
| Thomas Richter / OpenPCI-Reserved9
|-
| 1742
| 06CE
| Thomas Richter / OpenPCI-Reserved10
|-
| 1743
| 06CF
| Thomas Richter / OpenPCI-Reserved11
|-
| 1744
| 06D0
| Thomas Richter / OpenPCI-Reserved12
|-
| 1761
| 06E1
| Great Valley Products
|-
| 1803
| 070B
| UAE Amiga Emulator
|-
| 2002
| 07D2
| Mimetics Corp.
|-
| 2003
| 07D3
| ACDA
|-
| 2004
| 07D4
| Finn R. Jacobsen
|-
| 2005
| 07D5
| Elthen Electronics
|-
| 2006
| 07D6
| Nine Tiles Computer Systems Ltd.
|-
| 2007
| 07D7
| Analog Electronics
|-
| 2008
| 07D8
| Bell & Howell
|-
| 2009
| 07D9
| Roland Kochler
|-
| 2010
| 07DA
| Byte Corp.
|-
| 2011
| 07DB
| Reserved
|-
| 2012
| 07DC
| DKB, Inc.
| Previously named Michigan Software
|-
| 2013
| 07DD
| Pacific Peripherals
|-
| 2014
| 07DE
| Sysaphus Software
|-
| 2015
| 07DF
| Digitronics
|-
| 2016
| 07E0
| Akron Systems
|-
| 2017
| 07E1
| Great Valley Products
|-
| 2018
| 07E2
| Calmos
|-
| 2019
| 07E3
| Dover Research
|-
| 2020
| 07E4
| David Krehbiel
|-
| 2021
| 07E5
| Synergy Peripheral Systems
| Also known as California Access
|-
| 2022
| 07E6
| Xetec
|-
| 2023
| 07E7
| Micron Technology
|-
| 2024
| 07E8
| CH Electronics
|-
| 2025
| 07E9
| American Liquid Light
|-
| 2026
| 07EA
| Progressive Peripherals & Software
| Also used by Ateo
|-
| 2027
| 07EB
| Wicat Systems
|-
| 2028
| 07EC
| Applied Systems & Peripherals
|-
| 2029
| 07ED
| Delaware Valley Software
|-
| 2030
| 07EE
| Palomax
|-
| 2031
| 07EF
| Incognito Software
|-
| 2032
| 07F0
| Jadesign
|-
| 2033
| 07F1
| BVR
|-
| 2034
| 07F2
| Spirit Technology
|-
| 2035
| 07F3
| Spirit Technology
|-
| 2036
| 07F4
| Atronic
|-
| 2037
| 07F5
| Scott Karlin
|-
| 2038
| 07F6
| Howitch
|-
| 2039
| 07F7
| Sullivan Brothers Visual Engineers
|-
| 2040
| 07F8
| G I T
|-
| 2041
| 07F9
| Amigo Business Computers
|-
| 2042
| 07FA
| Micro E Ab
|-
| 2043
| 07FB
| Ralph Kruse
|-
| 2044
| 07FC
| Clearpoint Research
|-
| 2045
| 07FD
| Kodiak
|-
| 2046
| 07FE
| BSC
| Originally registered to Phoenix Electronics
|-
| 2047
| 07FF
| No Name Shown
|-
| 2048
| 0800
| Commodore Braunschweig
|-
| 2049
| 0801
| BSC
| Originally registered to Elaborate Bytes
|-
| 2050
| 0802
| Kronos/C Ltd.
|-
| 2051
| 0803
| Spartanics
|-
| 2052
| 0804
| Jochheim Computer Tuning
|-
| 2053
| 0805
| Trans Data Systems
|-
| 2054
| 0806
| Applied Systems & Peripherals Ltd.
|-
| 2055
| 0807
| Checkpoint Technologies
| Originally registered to Amiga Solutions
|-
| 2056
| 0808
| Adept Development
|-
| 2057
| 0809
| Advanced Computer Design
|-
| 2058
| 080A
| Sir Netics
|-
| 2059
| 080B
| Expert Services
|-
| 2060
| 080C
| Digital Art Systems
|-
| 2061
| 080D
| Adept Development
|-
| 2062
| 080E
| Expansion Technologies (Expansion Systems)
|-
| 2063
| 080F
| Alphatech
|-
| 2064
| 0810
| Edotronik GmbH
|-
| 2065
| 0811
| California Access/Synergy
| Originally registered to Logical Design Works
|-
| 2066
| 0812
| Bowden, Williams, Full & Assoc.
|-
| 2067
| 0813
| NES, Inc.
|-
| 2068
| 0814
| Amdev
|-
| 2069
| 0815
| Big Brother Security Systems
|-
| 2070
| 0816
| Active Circuits Inc.
|-
| 2071
| 0817
| ICD, Inc.
|-
| 2072
| 0818
| Multi-Meg Electronique
|-
| 2073
| 0819
| Kupke Computertechnik GmbH
|-
| 2074
| 081A
| The Checkered Ball
|-
| 2075
| 081B
| Hi Tension Computer Services Ltd. (UK)
|-
| 2076
| 081C
| Alfa Data
| Originally assigned to Elmtech Research, Ltd. (UK)
|-
| 2077
| 081D
| Great Valley Products
| Originally registered to Clartscreen, Ltd. (UK)
|-
| 2078
| 081E
| Interworks
|-
| 2079
| 081F
| Galysh Enterprises
|-
| 2080
| 0820
| Hardital Synthesis
| Originally registered to Realtime Games Software Ltd.
|-
| 2081
| 0821
| GBS
|-
| 2082
| 0822
| Circum Design Inc.
|-
| 2083
| 0823
| Alberta Micro Electronic Center
|-
| 2084
| 0824
| Bestech
|-
| 2085
| 0825
| Lasar Fantasy
|-
| 2086
| 0826
| Pulsar
|-
| 2087
| 0827
| Ivis
|-
| 2088
| 0828
| Applied Engineering
|-
| 2089
| 0829
| Solid-State Design & Development
|-
| 2090
| 082A
| Vison Quest
|-
| 2091
| 082B
| Seaview Software
|-
| 2092
| 082C
| BSC
| Mistakenly used by ADS (Advanced Development Software)
|-
| 2093
| 082D
| Bernd Culenfeld
|-
| 2094
| 082E
| American Liquid Light
|-
| 2095
| 082F
| CEGITES
|-
| 2096
| 0830
| Quadlite Computers Ltd.
| Originally registered to EV Industries
|-
| 2097
| 0831
| Silicon Peace
|-
| 2098
| 0832
| Black Belt Systems
|-
| 2099
| 0833
| Village Tronic
| Originally registerd to Steve Yaeger
|-
| 2100
| 0834
| ReadySoft
|-
| 2101
| 0835
| Phoenix Micro Technologies
|-
| 2102
| 0836
| Advanced Systems & Software
| Orignally assigned to Preferred Technology
|-
| 2103
| 0837
| Rombo Productions
|-
| 2104
| 0838
| Impulse Inc.
|-
| 2105
| 0839
| Beta Unlimited
|-
| 2106
| 083A
| Memory Expansion System, Ltd.
|-
| 2107
| 083B
| Vortex Computer Systems GmbH
|-
| 2108
| 083C
| Platypus Systems
|-
| 2109
| 083D
| Gigatron OHG
|-
| 2110
| 083E
| PG Electronics
|-
| 2111
| 083F
| New Technologies Group
|-
| 2112
| 0840
| Interactive Video Systems (IVS)
| Pacific Peripherals
|-
| 2113
| 0841
| Vector
| Originally registered to H. K. Computer
|-
| 2114
| 0842
| Pacific Digital
| Originally registered to C. H. Helfrich Elektronik
|-
| 2115
| 0843
| Xanadu
|-
| 2116
| 0844
| Pacific Digital
| Originally registered to AMS
|-
| 2117
| 0845
| X-Pert
|-
| 2118
| 0846
| The Amiga Centre
|-
| 2119
| 0847
| Digital Pacific
|-
| 2120
| 0848
| Solid State Leisure
|-
| 2121
| 0849
| Hydra Systems
| Originally registered to Analog Electronics
|-
| 2122
| 084A
| Cumana
|-
| 2123
| 084B
| KAPS 2C Conception
|-
| 2124
| 084C
| Mike Mason
|-
| 2125
| 084D
| For Your Eyes
|-
| 2126
| 084E
| Volkmar Breitfeld Computersysteme
|-
| 2127
| 084F
| Sunrize Industries
|-
| 2128
| 0850
| Scott Advanced Micro Designs
|-
| 2129
| 0851
| Digital Micronics
|-
| 2130
| 0852
| Alfa-Laval
|-
| 2131
| 0853
| Multigros A/S
|-
| 2132
| 0854
| Archos
|-
| 2133
| 0855
| Icom Simulations
|-
| 2134
| 0856
| Commodore Test Engineering Group
|-
| 2135
| 0857
| Microcreations
|-
| 2136
| 0858
| Shoestring Productions
|-
| 2137
| 0859
| Faberushi
|-
| 2138
| 085A
| Evesham Micro Ltd.
|-
| 2139
| 085B
| Panagolin Laser Software
|-
| 2140
| 085C
| Thomas Rudloff
|-
| 2141
| 085D
| Daniel Hohabir
|-
| 2142
| 085E
| GfxBase, Inc.
|-
| 2143
| 085F
| Axellabs
|-
| 2144
| 0860
| Roctec Electronics Inc.
|-
| 2145
| 0861
| Omega Datentechnik
|-
| 2146
| 0862
| Atlantis
|-
| 2147
| 0863
| Skytec Computers
|-
| 2148
| 0864
| Protar Electronics
|-
| 2149
| 0865
| ACS
|-
| 2150
| 0866
| Software Results Enterprises
| Originally registered to University of Illinois
|-
| 2151
| 0867
| Infinity Systems Design Group
|-
| 2152
| 0868
| Trade It
|-
| 2153
| 0869
| Suntec, Inc.
|-
| 2154
| 086A
| DJW Micro Systems
| Originally registered to Tritec Marketing
|-
| 2155
| 086B
| Power Computing Ltd.
|-
| 2156
| 086C
| MacroSystems
|-
| 2157
| 086D
| Masoboshi GmbH (DCE)
|-
| 2158
| 086E
| HAL Software Hardware Handel
|-
| 2159
| 086F
| Mainhattan Data
| Originally registered to Michael Lamm Computersysteme
|-
| 2160
| 0870
| Digital Processing System
| Originally registered to bbdp Electronics
|-
| 2161
| 0871
| Blue Ribbon Soundworks
| Originally registered to Design Computer Systems
|-
| 2162
| 0872
| XPert
| Originally registered to The Station
|-
| 2163
| 0873
| DelaComp
| Originally registered to Bryan Williams
|-
| 2164
| 0874
| Superformance Computer Engineering GmbH
|-
| 2165
| 0875
| Overland Engineering
|-
| 2166
| 0876
| Thomas Hamren
|-
| 2167
| 0877
| Village Tronic
|-
| 2168
| 0878
| Toolbox Design
|-
| 2169
| 0879
| Digital Processing System
|-
| 2170
| 087A
| Superformance
|-
| 2171
| 087B
| Utilities Unlimited
|-
| 2172
| 087C
| phase 5
|-
| 2173
| 087D
| Juergen Kommos
|-
| 2174
| 087E
| Electronic Design
|-
| 2175
| 087F
| James Cook University of North Queensland
|-
| 2176
| 0880
| AmiTrix Development
|-
| 2177
| 0881
| Ferranti
|-
| 2178
| 0882
| Leviathan Development
|-
| 2179
| 0883
| United Video Inc.
|-
| 2180
| 0884
| GPSoft Pty. Ltd.
| Originally registered to Juergen Kommos
|-
| 2181
| 0885
| ArMAX
| Oliver Bausch
|-
| 2182
| 0886
| CP Computer
|-
| 2183
| 0887
| AMOK - Amiga Module & Oberon Klub
|-
| 2184
| 0888
| ITEK Neser & Sieber GbR
|-
| 2185
| 0889
| Phillip C. Lello
|-
| 2186
| 088A
| Cyborg Design Services
|-
| 2187
| 088B
| G2 Systems
|-
| 2188
| 088C
| Pro System Computersysteme
|-
| 2189
| 088D
| ZEUS Electronic
| Originally registered to MSPI (Markt & Technik)
|-
| 2190
| 088E
| Altatech
|-
| 2191
| 088F
| NewTek
|-
| 2192
| 0890
| M-TEC Hardware Design
| Originally registered to Hardware Design Udo Neuroth
|-
| 2193
| 0891
| Great Valley Products
| Originally registered to Viona Development
|-
| 2194
| 0892
| Amitek
| Originally assigned to Marpet Developments
|-
| 2195
| 0893
| Ingenieurbuero Helfrich
|-
| 2196
| 0894
| The Neo Group
|-
| 2197
| 0895
| Cyon
|-
| 2198
| 0896
| Bob Research Group
|-
| 2199
| 0897
| Richmond Sound Design Ltd.
|-
| 2200
| 0898
| US Cybernetics
|-
| 2201
| 0899
| Fulvio Ieva
|-
| 2202
| 089A
| Silicon Studio
|-
| 2203
| 089B
| MacroSystems (USA)
| Was named Micro System Devices
|-
| 2204
| 089C
| Conspector Entertainment
|-
| 2205
| 089D
| Laserforum
|-
| 2206
| 089E
| Elbox Computer
| Mistakenly used by Index Information Ltd.
|-
| 2207
| 089F
| Applied Magic Inc.
|-
| 2208
| 08A0
| SDL Ltd.
|-
| 2560
| 0A00
| Harms
|-
| 2588
| 0A1C
| A1K.org Community
|-
| 2640
| 0A50
| Micronik
|-
| 2782
| 2782
| OA Design
|-
| 3084
| 0C0C
| Team 4
|-
| 3643
| 0E3B
| E3B
| Michael Boehmer
|-
| 3855
| 0F0F
| Micronik
|-
| 4096
| 1000
| MegaMicro
|-
| 4110
| 100E
| DigiFeX
|-
| 4136
| 1028
| Imtronics/Memphis
|-
| 4149
| 1035
| PROTAR
|-
| 4369
| 1111
| Frank Strauß Elektronik
| Also used by Kupke
|-
| 4626
| 1212
| Individual Computers
|-
| 4648
| 1228
| Flesch Hornemann Computer Elec.
|-
| 4680
| 1248
| Kupke Computertechnik GmbH
|-
| 4711
| 1267
| RBM digitaltechnik
|-
| 4754
| 1292
| MacroSystems
|-
| 5000
| 1388
| ITH
|-
| 5001
| 1389
| VMC
|-
| 5010
| 1392
| Ambience Creation Technology
|-
| 5011
| 1393
| Creative Development
|-
| 5012
| 1394
| Georg Braun
|-
| 5013
| 1395
| Swedish User Group of Amiga
|-
| 5014
| 1396
| Jakub Bednarski
|-
| 5015
| 1397
| KryoFlux, Ltd.
|-
| 5016
| 1398
| Igor Majstorovic
|-
| 5017
| 1399
| Alastair M. Robinson
|-
| 5018
| 139A
| Austex Software
|-
| 5019
| 139B
| Sören Gust
|-
| 5020
| 139C
| Rok Krajnc
|-
| 5030
| 13A6
| Tim Tashpulatov
|-
| 5040
| 13B0
| 7-bit
|-
| 5050
| 13BA
| Sakura IT
|-
| 5060
| 13C4
| FPGAArcade
|-
| 5070
| 13CE
| CancerSoft Inc.
|-
| 5080
| 13D8
| Stephen Leary
|-
| 5090
| 13E2
| DMA Softlab LLC
|-
| 5100
| 13EC
| Brookhouse Engineering
|-
| 5110
| 13F6
| Eduardo Arana
|-
| 5120
| 1400
| CS-LAB
|-
| 5130
| 140A
| Robert Miranda
|-
| 5140
| 1414
| RastPort
|-
| 5132
| 140C
| UAS Interface Ltd6
|-
| 5150
| 141E
| Amiga Kit
|-
| 5160
| 1428
| Central Texas Commodore User Group
|-
| 5170
| 1432
| Confusion Research Center
|-
| 5180
| 143C
| Solar Soyuz Zaibatsu
|-
| 5190
| 1446
| BooBip
|-
| 5191
| 1447
| Matthias Hampel
|-
| 5192
| 1448
| dec0de Consulting Ltd.
|-
| 5193
| 1449
| Puppy Concepts
|-
| 5194
| 144A
| Open Amiga Hardware Repository
|-
| 5195
| 144B
| Double H Tech
|-
| 5196
| 144C
| Retromatik
|-
| 5500
| 157C
| Inhouse Information
|-
| 5768
| 1688
| Bio Con
|-
| 6148
| 1804
| HK-Computer
|-
| 6502
| 1966
| Cloanto
|-
| 6520
| 1978
| Oliver Gantert
|-
| 7777
| 1E61
| Rafal Gabriel Chyla
|-
| 8215
| 2017
| Vortex
|-
| 8244
| 2034
| Spirit Technology
|-
| 8290
| 2062
| Expansion Systems
|-
| 8448
| 2100
| ReadySoft
|-
| 8512
| 2140
| Phase 5 Digital Products
|-
| 8553
| 2169
| Digital Processing Systems Inc.
|-
| 8704
| 2200
| ACT Elektronik
|-
| 8738
| 2222
| ACT Elektronik
|-
| 9512
| 2528
| Tower Technologies
|-
| 10676
| 29B4
| Electronic Design
|-
| 14195
| 3773
| Media-net-Point
|-
| 14501
| 38A5
| Petsoff, Finland
|-
| 16375
| 3FF7
| Uwe Gerlach
|-
| 16707
| 4143
| Ateo Concepts
|-
| 16708
| 4144
| ALiENDESiGN
|-
| 16945
| 4231
| A.C.T.
|-
| 17740
| 454C
| HK-Computer (ELSAT)
|-
| 18260
| 4754
| MacroSystems (Germany)
|-
| 19796
| 4D54
| Markt & Technik
|-
| 20480
| 5000
| François Lacombe
|-
| 22359
| 5757
| Markt & Technik
|-
| 26464
| 6760
| Combitec
|-
| 26470
| 6766
| Combitec
|-
| 28014
| 6D6E
| MNT Media and Technology UG
|-
| 28019
| 6D73
| Michal Schulz
|-
| 28020
| 6D74
| PiStorm
|-
| 32768
| 8000
| M.A.S.T.
|-
| 42240
| A500
| Aethreum Digital
|-
| 43437
| A9AD
| Reis-Ware
|-
| 43521
| AA01
| Cameron
|-
| 43537
| AA11
| Reis-Ware
|-
| 44359
| AD47
| Matay
|-
| 46504
| B5A8
| Phoenix
|-
| 48879
| BEEF
| Swiss Mountain Dog Products
|-
| 49160
| C008
| Combitec
|-
| 49374
| C0DE
| Stefan Reinauer
|-
| 61453
| F00D
| Forefront Technologies Inc.
|}

For any changes/additions to this registry see [[#How_to_Obtain_a_Manufacturer_Number|How to Obtain a Manufacturer Number]]

Amiga Hardware Manufacturer ID Registry

2026-09-08T11:13:41Z

Costel Mincea: Added PiStorm (28020)

__TOC__

= How to Obtain a Manufacturer Number =

Manufacturer's numbers are assigned by the AmigaOS development team. To obtain your unique manufacturer number send a support request to [mailto:support@hyperion-entertainment.com support@hyperion-entertainment.com] including these information:

1. The name of the company or person which the number is assigned to

2. Postal address/contact address

3. Name of the contact person, with a corresponding e-mail address

4. A brief description of the kind of products you want to produce

= Your Manufacturer Number =

Attention hardware manufacturers. If you are developing a hardware expansion product for the Classic Amiga (e.g. 500, 2000, 3000) then you will need to obtain a special manufacturer ID number from the AmigaOS development team to identify your product. This manufacturer number is used by the Amiga to link your hardware with its driver software at boot time.

Your manufacturer number is part of the special protocol that the Amiga uses to automatically configure all expansion devices on the bus without the user having to cut jumpers or adjust dip switches. This is called auto-config.

At start-up time, the system first polls each board in the system and assigns the board its own address space. If it is a memory board, its RAM is linked into the memory free pool. Later in the boot sequence, after DOS is initialized, the binddrivers program is run. Binddrivers will search the directory SYS:Expansion for the drivers that go with the boards.

To do this binddrivers looks in the Tool Type field of all icon files in SYS:Expansion. If the first seven bytes of the Tool Type field are "PRODUCT", then this is an icon file for a driver.

Binddrivers will then attempt to match the drivers it has found with the boards that were found earlier. This is where your manufacturer number comes in.

Your manufacturer number goes in two places. First, it is burned in hex form into the PAL which is part of ALL auto-config expansion products. Second, it appears in ASCII in the Tool Type field of the icon file for your product's driver. By matching these two numbers, the Amiga can automatically configure your board and bind it's software driver into the system as well.

The manufacturer's number is a 16-bit ID which appears in PAL offsets $10-$17. There is also an 8-bit product number which you assign. The product number is for uniquely identifying different products from the same vendor. The product number will appear in PAL offsets $04-$07. This gives you a total of 24 bits to identify each of your products.

These 24 bits of information in the PAL which identify your product are matched against the information in the Tool Type field of all icon files in the SYS:Expansion drawer. For example, suppose you are manufacturer #1019. You have two products, #1 and #2 which both use the same driver. The icon for your driver for these two products would have a Tool Type set to "PRODUCT=1019/1|1019/2". This means: I am an icon for a driver that works with product number 1 or 2 from manufacturer 1019, now bind me. Spaces are not legal. Here are two other examples:

; PRODUCT=1208/11
: is the Tool Type for a driver for product 11 from manufacturer number 1208.

; PRODUCT=1017
: is the Tool Type for a driver for any product from manufacturer number 1017.

For an informal explanation of the auto-configuration process, see the chapter on Software Expansion Architecture from the 2nd Annual Amiga Developer's Conference Notes (available on ADCD 2.1). For the details of timing, power, the PAL equations and PAL address specifications and the expansion library documentation, see sections 3.1 to 3.3 of the A500/A2000 Technical Reference Manual. The original auto-config spec appears in the A1000 Schematics and Expansion Specification.

The auto-config process makes the addition of expansion products to the system very easy. All the user has to do is put the board in any slot and copy the driver from the release disk to his own SYS:Expansion drawer. Everything else is automatic. There are no jumpers or dip switches to set. Best of all, you will get a lot less support calls asking how to make your product work with the XYZ-Corp-battery-backed-clock.

= Notes =

Some notes on hardware manufacturer ID assignment.

* Manufacturer ID numbers are assigned free of charge.
* Please provide the following information when requesting an ID:
*# Name of the company or person
*# Postal address/contact address
*# Name of the contact person, with a corresponding e-mail address
*# A brief description of the kind of products you want to produce
* All ID numbers smaller than 5000 must be considered unsafe because no information exists on which numbers exactly were taken during the time Commodore, Inc. disintegrated.
* ID numbers in the range 8192 to 18841 must be considered unsafe because some hardware developers mistook the numbers assigned to them to be given in hexadecimal format. Hence 0x2000 = 8192 and 0x4999 = 18841.

= Example code =

<syntaxhighlight lang="C" line>
/*-----------------------------------------------*/
/* Here is a short program which will tell you */
/* about the expansion boards configured in your */
/* system without you opening up the machine. */
/* Code by Bill Koester of CATS */
/*-----------------------------------------------*/
#include <libraries/configvars.h>
#include <libraries/expansion.h>

struct ExpansionBase *ExpansionBase;

void cleanup();
void printdev();

int main()
{
struct ConfigDev *MyConfigDev;

/*----------------------------------*/
/* Open the expansion library, */
/* if there is a problem then exit */
/*----------------------------------*/

ExpansionBase =(struct ExpansionBase *) OpenLibrary(EXPANSIONNAME,0);
if(ExpansionBase==NULL)
{
printf("Error opening expansion library!!\n");
cleanup();
exit(0);
}

/*--------------------------------------------*/
/* Use FindConfigDev to get info on the first */
/* expansion board on the list maintained by */
/* Exec. If there are no expansion boards in */
/* the system then exit. */
/*--------------------------------------------*/

MyConfigDev = NULL;

/*--------------------------------------------------*/
/* FindConfigDev(oldConfigDev,manufacturer,product) */
/* oldConfigDev = NULL for the top of the list */
/* manufacturer = -1 for any manufacturer */
/* product = -1 for any product */
/*--------------------------------------------------*/

MyConfigDev = FindConfigDev(NULL,-1,-1);

if(MyConfigDev==NULL)
{
printf("No Configured Devices found!!\n");
cleanup();
exit(0);
}

printdev(MyConfigDev);

/*-----------------------------------*/
/* OK, there is at least one board, */
/* so loop and get the entire list */
/* printing as we go with printdev() */
/*-----------------------------------*/

while(MyConfigDev = FindConfigDev(MyConfigDev,-1,-1))
{
printdev(MyConfigDev);
}
cleanup();
return 0;
}

/*-------------------*/
/* Close up shop... */
/*-------------------*/
void cleanup()
{
if(ExpansionBase)
CloseLibrary(ExpansionBase);
}

/*----------------------------------*/
/* Print out the contents of the */
/* dev structure for this expansion */
/* product. */
/*----------------------------------*/

void printdev(dev)
struct ConfigDev *dev;
{
char buff[200];

printf("Flags = ");
if(dev->cd_Flags==NULL)
printf("NULL ");
if(dev->cd_Flags&CDF_SHUTUP)
printf("CDF_SHUTUP ");
if(dev->cd_Flags&CDF_CONFIGME)
printf("CDF_CONFIGME ");
printf("\n");
printf("Board Address = %x\n",dev->cd_BoardAddr);
printf("Board Size = %d bytes\n",dev->cd_BoardSize);
printf("Slot Address = %d\n",dev->cd_SlotAddr);
printf("Slot Size = %d\n",dev->cd_SlotSize);
printf("Driver code at %x\n",dev->cd_Driver);

printf("er_Type = %x\n",dev->cd_Rom.er_Type);
printf("er_Product = %x\n",dev->cd_Rom.er_Product);
printf("er_Flags = %x\n",dev->cd_Rom.er_Flags);
printf("er_Reserved03 = %x\n",dev->cd_Rom.er_Reserved03);
printf("er_Manufacturer = %x\n",dev->cd_Rom.er_Manufacturer);
printf("er_SerialNumber = %x\n",dev->cd_Rom.er_SerialNumber);
printf("er_InitDiagVec = %x\n",dev->cd_Rom.er_InitDiagVec);
printf("er_Reserved0c = %x\n",dev->cd_Rom.er_Reserved0c);
printf("er_Reserved0d = %x\n",dev->cd_Rom.er_Reserved0d);
printf("er_Reserved0e = %x\n",dev->cd_Rom.er_Reserved0e);
printf("er_Reserved0f = %x\n",dev->cd_Rom.er_Reserved0f);

printf("Hit Return to continue:\n");
gets(buff);
}
</syntaxhighlight>

= Registry =

{| class="wikitable"
! ID (decimal)
! ID (hexadecimal)
! Manufacturer
! Notes
|-
| 1
| 0001
| Micronik
|-
| 211
| 00D3
| Pacific Peripherals/Profex
|-
| 221
| 00DD
| Kupke Computertechnik GmbH
|-
| 256
| 0100
| Memphis
| Originally registered to MacroSystems US
|-
| 512
| 0200
| 3-State Computertechnik
|-
| 513
| 0201
| Commodore (Braunschweig)
|-
| 514
| 0202
| Commodore (West Chester)
|-
| 515
| 0203
| Commodore (West Chester)
| Originally registered to Combitech/Macrosystem
|-
| 756
| 02F4
| Progressive Peripherals & Software
|-
| 767
| 02FF
| Kolff Computer Supplies
|-
| 1001
| 03E9
| Tecmar
|-
| 1002
| 03EA
| Telesys
|-
| 1003
| 03EB
| The Micro-Forge
|-
| 1004
| 03EC
| Kronos/C Ltd.
| Originally registered to Card Co. (Supra)
|-
| 1005
| 03ED
| A-Squared
|-
| 1006
| 03EE
| Comspec Communications
|-
| 1007
| 03EF
| HT Electronics
|-
| 1008
| 03F0
| RDS Software
|-
| 1009
| 03F1
| Anakin Research
|-
| 1010
| 03F2
| MicroBotics
|-
| 1011
| 03F3
| Bob Krauth
|-
| 1012
| 03F4
| Access Associates (Alegra)
|-
| 1013
| 03F5
| Mini Comp Systems Ltd.
|-
| 1014
| 03F6
| Cypress Technology
|-
| 1015
| 03F7
| Fuller Computers
|-
| 1016
| 03F8
| Galaxy Computers
|-
| 1017
| 03F9
| ADA Research
|-
| 1018
| 03FA
| Computer Service Italia
|-
| 1019
| 03FB
| Amigo
|-
| 1020
| 03FC
| Micro-Solutions Inc.
|-
| 1021
| 03FD
| Stacar International
|-
| 1022
| 03FE
| Video Precisions
|-
| 1023
| 03FF
| ASDG, Inc.
|-
| 1025
| 0401
| Ing. Buero Kalawsky
|-
| 1026
| 0402
| Computer Tuning
|-
| 1027
| 0403
| Interplan Unternehmensberatung
|-
| 1028
| 0404
| Imtronics/Memphis
| Originally registered to Peter Ohlich
|-
| 1030
| 0406
| Commodore (Lowell University)
| Originally registered to Productivity Center
|-
| 1041
| 0411
| Design Labs
|-
| 1042
| 0412
| MCS
|-
| 1043
| 0413
| B. J. Freeman
|-
| 1044
| 0414
| Side Effects Inc.
|-
| 1045
| 0415
| Oklahoma Personal Comp.
|-
| 1046
| 0416
| Advanced Micro Innovations
|-
| 1047
| 0417
| Industrial Support Services
|-
| 1048
| 0418
| Technisoft
|-
| 1049
| 0419
| Prolific, Inc.
|-
| 1050
| 041A
| Softeam, Inc.
|-
| 1051
| 041B
| GRC Electronics
|-
| 1052
| 041C
| David Lai
|-
| 1053
| 041D
| Ameristar Technologies
|-
| 1054
| 041E
| Cline Refrigeration
|-
| 1055
| 041F
| Cardiac Pacemakers, Inc.
|-
| 1056
| 0420
| Supra Corp. (Creative Microsystems)
|-
| 1057
| 0421
| Wayne Diener
|-
| 1058
| 0422
| Computer Systems Associates (CSA)
|-
| 1059
| 0423
| Trionix, Inc.
|-
| 1060
| 0424
| David Lucas
|-
| 1061
| 0425
| Analog Precision
| Also assigned to D & L Distributing
|-
| 1267
| 04F3
| RBM Digitaltechnik
|-
| 1282
| 0502
| M-TEC Hardware Design
|-
| 1337
| 0539
| Thomas Stenzel (DaFR34K)
|-
| 1576
| 0628
| Boris Križma
|-
| 1729
| 06C1
| Thomas Richter / OpenPCI-A1200 Mediator bridge
|-
| 1730
| 06C2
| Thomas Richter / OpenPCI-A4000 Mediator bridge
|-
| 1731
| 06C3
| Thomas Richter / OpenPCI-Prometheus bridge (Firestorm or original)
|-
| 1732
| 06C4
| Thomas Richter / OpenPCI-Reserved1
|-
| 1733
| 06C5
| Thomas Richter / OpenPCI-Grex bridge (both A1200 and A4000)
|-
| 1734
| 06C6
| Thomas Richter / OpenPCI-Reserved2
|-
| 1735
| 06C7
| Thomas Richter / OpenPCI-Reserved3
|-
| 1736
| 06C8
| Thomas Richter / OpenPCI-Reserved4
|-
| 1737
| 06C9
| Thomas Richter / OpenPCI-Reserved5
|-
| 1738
| 06CA
| Thomas Richter / OpenPCI-Reserved6
|-
| 1739
| 06CB
| Thomas Richter / OpenPCI-Reserved7
|-
| 1740
| 06CC
| Thomas Richter / OpenPCI-Reserved8
|-
| 1741
| 06CD
| Thomas Richter / OpenPCI-Reserved9
|-
| 1742
| 06CE
| Thomas Richter / OpenPCI-Reserved10
|-
| 1743
| 06CF
| Thomas Richter / OpenPCI-Reserved11
|-
| 1744
| 06D0
| Thomas Richter / OpenPCI-Reserved12
|-
| 1761
| 06E1
| Great Valley Products
|-
| 1803
| 070B
| UAE Amiga Emulator
|-
| 2002
| 07D2
| Mimetics Corp.
|-
| 2003
| 07D3
| ACDA
|-
| 2004
| 07D4
| Finn R. Jacobsen
|-
| 2005
| 07D5
| Elthen Electronics
|-
| 2006
| 07D6
| Nine Tiles Computer Systems Ltd.
|-
| 2007
| 07D7
| Analog Electronics
|-
| 2008
| 07D8
| Bell & Howell
|-
| 2009
| 07D9
| Roland Kochler
|-
| 2010
| 07DA
| Byte Corp.
|-
| 2011
| 07DB
| Reserved
|-
| 2012
| 07DC
| DKB, Inc.
| Previously named Michigan Software
|-
| 2013
| 07DD
| Pacific Peripherals
|-
| 2014
| 07DE
| Sysaphus Software
|-
| 2015
| 07DF
| Digitronics
|-
| 2016
| 07E0
| Akron Systems
|-
| 2017
| 07E1
| Great Valley Products
|-
| 2018
| 07E2
| Calmos
|-
| 2019
| 07E3
| Dover Research
|-
| 2020
| 07E4
| David Krehbiel
|-
| 2021
| 07E5
| Synergy Peripheral Systems
| Also known as California Access
|-
| 2022
| 07E6
| Xetec
|-
| 2023
| 07E7
| Micron Technology
|-
| 2024
| 07E8
| CH Electronics
|-
| 2025
| 07E9
| American Liquid Light
|-
| 2026
| 07EA
| Progressive Peripherals & Software
| Also used by Ateo
|-
| 2027
| 07EB
| Wicat Systems
|-
| 2028
| 07EC
| Applied Systems & Peripherals
|-
| 2029
| 07ED
| Delaware Valley Software
|-
| 2030
| 07EE
| Palomax
|-
| 2031
| 07EF
| Incognito Software
|-
| 2032
| 07F0
| Jadesign
|-
| 2033
| 07F1
| BVR
|-
| 2034
| 07F2
| Spirit Technology
|-
| 2035
| 07F3
| Spirit Technology
|-
| 2036
| 07F4
| Atronic
|-
| 2037
| 07F5
| Scott Karlin
|-
| 2038
| 07F6
| Howitch
|-
| 2039
| 07F7
| Sullivan Brothers Visual Engineers
|-
| 2040
| 07F8
| G I T
|-
| 2041
| 07F9
| Amigo Business Computers
|-
| 2042
| 07FA
| Micro E Ab
|-
| 2043
| 07FB
| Ralph Kruse
|-
| 2044
| 07FC
| Clearpoint Research
|-
| 2045
| 07FD
| Kodiak
|-
| 2046
| 07FE
| BSC
| Originally registered to Phoenix Electronics
|-
| 2047
| 07FF
| No Name Shown
|-
| 2048
| 0800
| Commodore Braunschweig
|-
| 2049
| 0801
| BSC
| Originally registered to Elaborate Bytes
|-
| 2050
| 0802
| Kronos/C Ltd.
|-
| 2051
| 0803
| Spartanics
|-
| 2052
| 0804
| Jochheim Computer Tuning
|-
| 2053
| 0805
| Trans Data Systems
|-
| 2054
| 0806
| Applied Systems & Peripherals Ltd.
|-
| 2055
| 0807
| Checkpoint Technologies
| Originally registered to Amiga Solutions
|-
| 2056
| 0808
| Adept Development
|-
| 2057
| 0809
| Advanced Computer Design
|-
| 2058
| 080A
| Sir Netics
|-
| 2059
| 080B
| Expert Services
|-
| 2060
| 080C
| Digital Art Systems
|-
| 2061
| 080D
| Adept Development
|-
| 2062
| 080E
| Expansion Technologies (Expansion Systems)
|-
| 2063
| 080F
| Alphatech
|-
| 2064
| 0810
| Edotronik GmbH
|-
| 2065
| 0811
| California Access/Synergy
| Originally registered to Logical Design Works
|-
| 2066
| 0812
| Bowden, Williams, Full & Assoc.
|-
| 2067
| 0813
| NES, Inc.
|-
| 2068
| 0814
| Amdev
|-
| 2069
| 0815
| Big Brother Security Systems
|-
| 2070
| 0816
| Active Circuits Inc.
|-
| 2071
| 0817
| ICD, Inc.
|-
| 2072
| 0818
| Multi-Meg Electronique
|-
| 2073
| 0819
| Kupke Computertechnik GmbH
|-
| 2074
| 081A
| The Checkered Ball
|-
| 2075
| 081B
| Hi Tension Computer Services Ltd. (UK)
|-
| 2076
| 081C
| Alfa Data
| Originally assigned to Elmtech Research, Ltd. (UK)
|-
| 2077
| 081D
| Great Valley Products
| Originally registered to Clartscreen, Ltd. (UK)
|-
| 2078
| 081E
| Interworks
|-
| 2079
| 081F
| Galysh Enterprises
|-
| 2080
| 0820
| Hardital Synthesis
| Originally registered to Realtime Games Software Ltd.
|-
| 2081
| 0821
| GBS
|-
| 2082
| 0822
| Circum Design Inc.
|-
| 2083
| 0823
| Alberta Micro Electronic Center
|-
| 2084
| 0824
| Bestech
|-
| 2085
| 0825
| Lasar Fantasy
|-
| 2086
| 0826
| Pulsar
|-
| 2087
| 0827
| Ivis
|-
| 2088
| 0828
| Applied Engineering
|-
| 2089
| 0829
| Solid-State Design & Development
|-
| 2090
| 082A
| Vison Quest
|-
| 2091
| 082B
| Seaview Software
|-
| 2092
| 082C
| BSC
| Mistakenly used by ADS (Advanced Development Software)
|-
| 2093
| 082D
| Bernd Culenfeld
|-
| 2094
| 082E
| American Liquid Light
|-
| 2095
| 082F
| CEGITES
|-
| 2096
| 0830
| Quadlite Computers Ltd.
| Originally registered to EV Industries
|-
| 2097
| 0831
| Silicon Peace
|-
| 2098
| 0832
| Black Belt Systems
|-
| 2099
| 0833
| Village Tronic
| Originally registerd to Steve Yaeger
|-
| 2100
| 0834
| ReadySoft
|-
| 2101
| 0835
| Phoenix Micro Technologies
|-
| 2102
| 0836
| Advanced Systems & Software
| Orignally assigned to Preferred Technology
|-
| 2103
| 0837
| Rombo Productions
|-
| 2104
| 0838
| Impulse Inc.
|-
| 2105
| 0839
| Beta Unlimited
|-
| 2106
| 083A
| Memory Expansion System, Ltd.
|-
| 2107
| 083B
| Vortex Computer Systems GmbH
|-
| 2108
| 083C
| Platypus Systems
|-
| 2109
| 083D
| Gigatron OHG
|-
| 2110
| 083E
| PG Electronics
|-
| 2111
| 083F
| New Technologies Group
|-
| 2112
| 0840
| Interactive Video Systems (IVS)
| Pacific Peripherals
|-
| 2113
| 0841
| Vector
| Originally registered to H. K. Computer
|-
| 2114
| 0842
| Pacific Digital
| Originally registered to C. H. Helfrich Elektronik
|-
| 2115
| 0843
| Xanadu
|-
| 2116
| 0844
| Pacific Digital
| Originally registered to AMS
|-
| 2117
| 0845
| X-Pert
|-
| 2118
| 0846
| The Amiga Centre
|-
| 2119
| 0847
| Digital Pacific
|-
| 2120
| 0848
| Solid State Leisure
|-
| 2121
| 0849
| Hydra Systems
| Originally registered to Analog Electronics
|-
| 2122
| 084A
| Cumana
|-
| 2123
| 084B
| KAPS 2C Conception
|-
| 2124
| 084C
| Mike Mason
|-
| 2125
| 084D
| For Your Eyes
|-
| 2126
| 084E
| Volkmar Breitfeld Computersysteme
|-
| 2127
| 084F
| Sunrize Industries
|-
| 2128
| 0850
| Scott Advanced Micro Designs
|-
| 2129
| 0851
| Digital Micronics
|-
| 2130
| 0852
| Alfa-Laval
|-
| 2131
| 0853
| Multigros A/S
|-
| 2132
| 0854
| Archos
|-
| 2133
| 0855
| Icom Simulations
|-
| 2134
| 0856
| Commodore Test Engineering Group
|-
| 2135
| 0857
| Microcreations
|-
| 2136
| 0858
| Shoestring Productions
|-
| 2137
| 0859
| Faberushi
|-
| 2138
| 085A
| Evesham Micro Ltd.
|-
| 2139
| 085B
| Panagolin Laser Software
|-
| 2140
| 085C
| Thomas Rudloff
|-
| 2141
| 085D
| Daniel Hohabir
|-
| 2142
| 085E
| GfxBase, Inc.
|-
| 2143
| 085F
| Axellabs
|-
| 2144
| 0860
| Roctec Electronics Inc.
|-
| 2145
| 0861
| Omega Datentechnik
|-
| 2146
| 0862
| Atlantis
|-
| 2147
| 0863
| Skytec Computers
|-
| 2148
| 0864
| Protar Electronics
|-
| 2149
| 0865
| ACS
|-
| 2150
| 0866
| Software Results Enterprises
| Originally registered to University of Illinois
|-
| 2151
| 0867
| Infinity Systems Design Group
|-
| 2152
| 0868
| Trade It
|-
| 2153
| 0869
| Suntec, Inc.
|-
| 2154
| 086A
| DJW Micro Systems
| Originally registered to Tritec Marketing
|-
| 2155
| 086B
| Power Computing Ltd.
|-
| 2156
| 086C
| MacroSystems
|-
| 2157
| 086D
| Masoboshi GmbH (DCE)
|-
| 2158
| 086E
| HAL Software Hardware Handel
|-
| 2159
| 086F
| Mainhattan Data
| Originally registered to Michael Lamm Computersysteme
|-
| 2160
| 0870
| Digital Processing System
| Originally registered to bbdp Electronics
|-
| 2161
| 0871
| Blue Ribbon Soundworks
| Originally registered to Design Computer Systems
|-
| 2162
| 0872
| XPert
| Originally registered to The Station
|-
| 2163
| 0873
| DelaComp
| Originally registered to Bryan Williams
|-
| 2164
| 0874
| Superformance Computer Engineering GmbH
|-
| 2165
| 0875
| Overland Engineering
|-
| 2166
| 0876
| Thomas Hamren
|-
| 2167
| 0877
| Village Tronic
|-
| 2168
| 0878
| Toolbox Design
|-
| 2169
| 0879
| Digital Processing System
|-
| 2170
| 087A
| Superformance
|-
| 2171
| 087B
| Utilities Unlimited
|-
| 2172
| 087C
| phase 5
|-
| 2173
| 087D
| Juergen Kommos
|-
| 2174
| 087E
| Electronic Design
|-
| 2175
| 087F
| James Cook University of North Queensland
|-
| 2176
| 0880
| AmiTrix Development
|-
| 2177
| 0881
| Ferranti
|-
| 2178
| 0882
| Leviathan Development
|-
| 2179
| 0883
| United Video Inc.
|-
| 2180
| 0884
| GPSoft Pty. Ltd.
| Originally registered to Juergen Kommos
|-
| 2181
| 0885
| ArMAX
| Oliver Bausch
|-
| 2182
| 0886
| CP Computer
|-
| 2183
| 0887
| AMOK - Amiga Module & Oberon Klub
|-
| 2184
| 0888
| ITEK Neser & Sieber GbR
|-
| 2185
| 0889
| Phillip C. Lello
|-
| 2186
| 088A
| Cyborg Design Services
|-
| 2187
| 088B
| G2 Systems
|-
| 2188
| 088C
| Pro System Computersysteme
|-
| 2189
| 088D
| ZEUS Electronic
| Originally registered to MSPI (Markt & Technik)
|-
| 2190
| 088E
| Altatech
|-
| 2191
| 088F
| NewTek
|-
| 2192
| 0890
| M-TEC Hardware Design
| Originally registered to Hardware Design Udo Neuroth
|-
| 2193
| 0891
| Great Valley Products
| Originally registered to Viona Development
|-
| 2194
| 0892
| Amitek
| Originally assigned to Marpet Developments
|-
| 2195
| 0893
| Ingenieurbuero Helfrich
|-
| 2196
| 0894
| The Neo Group
|-
| 2197
| 0895
| Cyon
|-
| 2198
| 0896
| Bob Research Group
|-
| 2199
| 0897
| Richmond Sound Design Ltd.
|-
| 2200
| 0898
| US Cybernetics
|-
| 2201
| 0899
| Fulvio Ieva
|-
| 2202
| 089A
| Silicon Studio
|-
| 2203
| 089B
| MacroSystems (USA)
| Was named Micro System Devices
|-
| 2204
| 089C
| Conspector Entertainment
|-
| 2205
| 089D
| Laserforum
|-
| 2206
| 089E
| Elbox Computer
| Mistakenly used by Index Information Ltd.
|-
| 2207
| 089F
| Applied Magic Inc.
|-
| 2208
| 08A0
| SDL Ltd.
|-
| 2560
| 0A00
| Harms
|-
| 2588
| 0A1C
| A1K.org Community
|-
| 2640
| 0A50
| Micronik
|-
| 2782
| 2782
| OA Design
|-
| 3084
| 0C0C
| Team 4
|-
| 3643
| 0E3B
| E3B
| Michael Boehmer
|-
| 3855
| 0F0F
| Micronik
|-
| 4096
| 1000
| MegaMicro
|-
| 4110
| 100E
| DigiFeX
|-
| 4136
| 1028
| Imtronics/Memphis
|-
| 4149
| 1035
| PROTAR
|-
| 4369
| 1111
| Frank Strauß Elektronik
| Also used by Kupke
|-
| 4626
| 1212
| Individual Computers
|-
| 4648
| 1228
| Flesch Hornemann Computer Elec.
|-
| 4680
| 1248
| Kupke Computertechnik GmbH
|-
| 4711
| 1267
| RBM digitaltechnik
|-
| 4754
| 1292
| MacroSystems
|-
| 5000
| 1388
| ITH
|-
| 5001
| 1389
| VMC
|-
| 5010
| 1392
| Ambience Creation Technology
|-
| 5011
| 1393
| Creative Development
|-
| 5012
| 1394
| Georg Braun
|-
| 5013
| 1395
| Swedish User Group of Amiga
|-
| 5014
| 1396
| Jakub Bednarski
|-
| 5015
| 1397
| KryoFlux, Ltd.
|-
| 5016
| 1398
| Igor Majstorovic
|-
| 5017
| 1399
| Alastair M. Robinson
|-
| 5018
| 139A
| Austex Software
|-
| 5019
| 139B
| Sören Gust
|-
| 5020
| 139C
| Rok Krajnc
|-
| 5030
| 13A6
| Tim Tashpulatov
|-
| 5040
| 13B0
| 7-bit
|-
| 5050
| 13BA
| Sakura IT
|-
| 5060
| 13C4
| FPGAArcade
|-
| 5070
| 13CE
| CancerSoft Inc.
|-
| 5080
| 13D8
| Stephen Leary
|-
| 5090
| 13E2
| DMA Softlab LLC
|-
| 5100
| 13EC
| Brookhouse Engineering
|-
| 5110
| 13F6
| Eduardo Arana
|-
| 5120
| 1400
| CS-LAB
|-
| 5130
| 140A
| Robert Miranda
|-
| 5140
| 1414
| RastPort
|-
| 5132
| 140C
| UAS Interface Ltd6
|-
| 5150
| 141E
| Amiga Kit
|-
| 5160
| 1428
| Central Texas Commodore User Group
|-
| 5170
| 1432
| Confusion Research Center
|-
| 5180
| 143C
| Solar Soyuz Zaibatsu
|-
| 5190
| 1446
| BooBip
|-
| 5191
| 1447
| Matthias Hampel
|-
| 5192
| 1448
| dec0de Consulting Ltd.
|-
| 5193
| 1449
| Puppy Concepts
|-
| 5194
| 144A
| Open Amiga Hardware Repository
|-
| 5195
| 144B
| Double H Tech
|-
| 5196
| 144C
| Retromatik
|-
| 5500
| 157C
| Inhouse Information
|-
| 5768
| 1688
| Bio Con
|-
| 6148
| 1804
| HK-Computer
|-
| 6502
| 1966
| Cloanto
|-
| 6520
| 1978
| Oliver Gantert
|-
| 7777
| 1E61
| Rafal Gabriel Chyla
|-
| 8215
| 2017
| Vortex
|-
| 8244
| 2034
| Spirit Technology
|-
| 8290
| 2062
| Expansion Systems
|-
| 8448
| 2100
| ReadySoft
|-
| 8512
| 2140
| Phase 5 Digital Products
|-
| 8553
| 2169
| Digital Processing Systems Inc.
|-
| 8704
| 2200
| ACT Elektronik
|-
| 8738
| 2222
| ACT Elektronik
|-
| 9512
| 2528
| Tower Technologies
|-
| 10676
| 29B4
| Electronic Design
|-
| 14195
| 3773
| Media-net-Point
|-
| 14501
| 38A5
| Petsoff, Finland
|-
| 16375
| 3FF7
| Uwe Gerlach
|-
| 16707
| 4143
| Ateo Concepts
|-
| 16708
| 4144
| ALiENDESiGN
|-
| 16945
| 4231
| A.C.T.
|-
| 17740
| 454C
| HK-Computer (ELSAT)
|-
| 18260
| 4754
| MacroSystems (Germany)
|-
| 19796
| 4D54
| Markt & Technik
|-
| 20480
| 5000
| François Lacombe
|-
| 22359
| 5757
| Markt & Technik
|-
| 26464
| 6760
| Combitec
|-
| 26470
| 6766
| Combitec
|-
| 28014
| 6D6E
| MNT Media and Technology UG
|-
| 28019
| 6D73
| Michal Schulz
|-
| 28020
| 6D74
| PiStorm
|-
| 32768
| 8000
| M.A.S.T.
|-
| 42240
| A500
| Aethreum Digital
|-
| 43437
| A9AD
| Reis-Ware
|-
| 43521
| AA01
| Cameron
|-
| 43537
| AA11
| Reis-Ware
|-
| 44359
| AD47
| Matay
|-
| 46504
| B5A8
| Phoenix
|-
| 48879
| BEEF
| Swiss Mountain Dog Products
|-
| 49160
| C008
| Combitec
|-
| 61453
| F00D
| Forefront Technologies Inc.
|}

For any changes/additions to this registry see [[#How_to_Obtain_a_Manufacturer_Number|How to Obtain a Manufacturer Number]]

Amiga Hardware Manufacturer ID Registry

2026-09-08T11:12:47Z

Costel Mincea: Added Michal Schulz (28019)

__TOC__

= How to Obtain a Manufacturer Number =

Manufacturer's numbers are assigned by the AmigaOS development team. To obtain your unique manufacturer number send a support request to [mailto:support@hyperion-entertainment.com support@hyperion-entertainment.com] including these information:

1. The name of the company or person which the number is assigned to

2. Postal address/contact address

3. Name of the contact person, with a corresponding e-mail address

4. A brief description of the kind of products you want to produce

= Your Manufacturer Number =

Attention hardware manufacturers. If you are developing a hardware expansion product for the Classic Amiga (e.g. 500, 2000, 3000) then you will need to obtain a special manufacturer ID number from the AmigaOS development team to identify your product. This manufacturer number is used by the Amiga to link your hardware with its driver software at boot time.

Your manufacturer number is part of the special protocol that the Amiga uses to automatically configure all expansion devices on the bus without the user having to cut jumpers or adjust dip switches. This is called auto-config.

At start-up time, the system first polls each board in the system and assigns the board its own address space. If it is a memory board, its RAM is linked into the memory free pool. Later in the boot sequence, after DOS is initialized, the binddrivers program is run. Binddrivers will search the directory SYS:Expansion for the drivers that go with the boards.

To do this binddrivers looks in the Tool Type field of all icon files in SYS:Expansion. If the first seven bytes of the Tool Type field are "PRODUCT", then this is an icon file for a driver.

Binddrivers will then attempt to match the drivers it has found with the boards that were found earlier. This is where your manufacturer number comes in.

Your manufacturer number goes in two places. First, it is burned in hex form into the PAL which is part of ALL auto-config expansion products. Second, it appears in ASCII in the Tool Type field of the icon file for your product's driver. By matching these two numbers, the Amiga can automatically configure your board and bind it's software driver into the system as well.

The manufacturer's number is a 16-bit ID which appears in PAL offsets $10-$17. There is also an 8-bit product number which you assign. The product number is for uniquely identifying different products from the same vendor. The product number will appear in PAL offsets $04-$07. This gives you a total of 24 bits to identify each of your products.

These 24 bits of information in the PAL which identify your product are matched against the information in the Tool Type field of all icon files in the SYS:Expansion drawer. For example, suppose you are manufacturer #1019. You have two products, #1 and #2 which both use the same driver. The icon for your driver for these two products would have a Tool Type set to "PRODUCT=1019/1|1019/2". This means: I am an icon for a driver that works with product number 1 or 2 from manufacturer 1019, now bind me. Spaces are not legal. Here are two other examples:

; PRODUCT=1208/11
: is the Tool Type for a driver for product 11 from manufacturer number 1208.

; PRODUCT=1017
: is the Tool Type for a driver for any product from manufacturer number 1017.

For an informal explanation of the auto-configuration process, see the chapter on Software Expansion Architecture from the 2nd Annual Amiga Developer's Conference Notes (available on ADCD 2.1). For the details of timing, power, the PAL equations and PAL address specifications and the expansion library documentation, see sections 3.1 to 3.3 of the A500/A2000 Technical Reference Manual. The original auto-config spec appears in the A1000 Schematics and Expansion Specification.

The auto-config process makes the addition of expansion products to the system very easy. All the user has to do is put the board in any slot and copy the driver from the release disk to his own SYS:Expansion drawer. Everything else is automatic. There are no jumpers or dip switches to set. Best of all, you will get a lot less support calls asking how to make your product work with the XYZ-Corp-battery-backed-clock.

= Notes =

Some notes on hardware manufacturer ID assignment.

* Manufacturer ID numbers are assigned free of charge.
* Please provide the following information when requesting an ID:
*# Name of the company or person
*# Postal address/contact address
*# Name of the contact person, with a corresponding e-mail address
*# A brief description of the kind of products you want to produce
* All ID numbers smaller than 5000 must be considered unsafe because no information exists on which numbers exactly were taken during the time Commodore, Inc. disintegrated.
* ID numbers in the range 8192 to 18841 must be considered unsafe because some hardware developers mistook the numbers assigned to them to be given in hexadecimal format. Hence 0x2000 = 8192 and 0x4999 = 18841.

= Example code =

<syntaxhighlight lang="C" line>
/*-----------------------------------------------*/
/* Here is a short program which will tell you */
/* about the expansion boards configured in your */
/* system without you opening up the machine. */
/* Code by Bill Koester of CATS */
/*-----------------------------------------------*/
#include <libraries/configvars.h>
#include <libraries/expansion.h>

struct ExpansionBase *ExpansionBase;

void cleanup();
void printdev();

int main()
{
struct ConfigDev *MyConfigDev;

/*----------------------------------*/
/* Open the expansion library, */
/* if there is a problem then exit */
/*----------------------------------*/

ExpansionBase =(struct ExpansionBase *) OpenLibrary(EXPANSIONNAME,0);
if(ExpansionBase==NULL)
{
printf("Error opening expansion library!!\n");
cleanup();
exit(0);
}

/*--------------------------------------------*/
/* Use FindConfigDev to get info on the first */
/* expansion board on the list maintained by */
/* Exec. If there are no expansion boards in */
/* the system then exit. */
/*--------------------------------------------*/

MyConfigDev = NULL;

/*--------------------------------------------------*/
/* FindConfigDev(oldConfigDev,manufacturer,product) */
/* oldConfigDev = NULL for the top of the list */
/* manufacturer = -1 for any manufacturer */
/* product = -1 for any product */
/*--------------------------------------------------*/

MyConfigDev = FindConfigDev(NULL,-1,-1);

if(MyConfigDev==NULL)
{
printf("No Configured Devices found!!\n");
cleanup();
exit(0);
}

printdev(MyConfigDev);

/*-----------------------------------*/
/* OK, there is at least one board, */
/* so loop and get the entire list */
/* printing as we go with printdev() */
/*-----------------------------------*/

while(MyConfigDev = FindConfigDev(MyConfigDev,-1,-1))
{
printdev(MyConfigDev);
}
cleanup();
return 0;
}

/*-------------------*/
/* Close up shop... */
/*-------------------*/
void cleanup()
{
if(ExpansionBase)
CloseLibrary(ExpansionBase);
}

/*----------------------------------*/
/* Print out the contents of the */
/* dev structure for this expansion */
/* product. */
/*----------------------------------*/

void printdev(dev)
struct ConfigDev *dev;
{
char buff[200];

printf("Flags = ");
if(dev->cd_Flags==NULL)
printf("NULL ");
if(dev->cd_Flags&CDF_SHUTUP)
printf("CDF_SHUTUP ");
if(dev->cd_Flags&CDF_CONFIGME)
printf("CDF_CONFIGME ");
printf("\n");
printf("Board Address = %x\n",dev->cd_BoardAddr);
printf("Board Size = %d bytes\n",dev->cd_BoardSize);
printf("Slot Address = %d\n",dev->cd_SlotAddr);
printf("Slot Size = %d\n",dev->cd_SlotSize);
printf("Driver code at %x\n",dev->cd_Driver);

printf("er_Type = %x\n",dev->cd_Rom.er_Type);
printf("er_Product = %x\n",dev->cd_Rom.er_Product);
printf("er_Flags = %x\n",dev->cd_Rom.er_Flags);
printf("er_Reserved03 = %x\n",dev->cd_Rom.er_Reserved03);
printf("er_Manufacturer = %x\n",dev->cd_Rom.er_Manufacturer);
printf("er_SerialNumber = %x\n",dev->cd_Rom.er_SerialNumber);
printf("er_InitDiagVec = %x\n",dev->cd_Rom.er_InitDiagVec);
printf("er_Reserved0c = %x\n",dev->cd_Rom.er_Reserved0c);
printf("er_Reserved0d = %x\n",dev->cd_Rom.er_Reserved0d);
printf("er_Reserved0e = %x\n",dev->cd_Rom.er_Reserved0e);
printf("er_Reserved0f = %x\n",dev->cd_Rom.er_Reserved0f);

printf("Hit Return to continue:\n");
gets(buff);
}
</syntaxhighlight>

= Registry =

{| class="wikitable"
! ID (decimal)
! ID (hexadecimal)
! Manufacturer
! Notes
|-
| 1
| 0001
| Micronik
|-
| 211
| 00D3
| Pacific Peripherals/Profex
|-
| 221
| 00DD
| Kupke Computertechnik GmbH
|-
| 256
| 0100
| Memphis
| Originally registered to MacroSystems US
|-
| 512
| 0200
| 3-State Computertechnik
|-
| 513
| 0201
| Commodore (Braunschweig)
|-
| 514
| 0202
| Commodore (West Chester)
|-
| 515
| 0203
| Commodore (West Chester)
| Originally registered to Combitech/Macrosystem
|-
| 756
| 02F4
| Progressive Peripherals & Software
|-
| 767
| 02FF
| Kolff Computer Supplies
|-
| 1001
| 03E9
| Tecmar
|-
| 1002
| 03EA
| Telesys
|-
| 1003
| 03EB
| The Micro-Forge
|-
| 1004
| 03EC
| Kronos/C Ltd.
| Originally registered to Card Co. (Supra)
|-
| 1005
| 03ED
| A-Squared
|-
| 1006
| 03EE
| Comspec Communications
|-
| 1007
| 03EF
| HT Electronics
|-
| 1008
| 03F0
| RDS Software
|-
| 1009
| 03F1
| Anakin Research
|-
| 1010
| 03F2
| MicroBotics
|-
| 1011
| 03F3
| Bob Krauth
|-
| 1012
| 03F4
| Access Associates (Alegra)
|-
| 1013
| 03F5
| Mini Comp Systems Ltd.
|-
| 1014
| 03F6
| Cypress Technology
|-
| 1015
| 03F7
| Fuller Computers
|-
| 1016
| 03F8
| Galaxy Computers
|-
| 1017
| 03F9
| ADA Research
|-
| 1018
| 03FA
| Computer Service Italia
|-
| 1019
| 03FB
| Amigo
|-
| 1020
| 03FC
| Micro-Solutions Inc.
|-
| 1021
| 03FD
| Stacar International
|-
| 1022
| 03FE
| Video Precisions
|-
| 1023
| 03FF
| ASDG, Inc.
|-
| 1025
| 0401
| Ing. Buero Kalawsky
|-
| 1026
| 0402
| Computer Tuning
|-
| 1027
| 0403
| Interplan Unternehmensberatung
|-
| 1028
| 0404
| Imtronics/Memphis
| Originally registered to Peter Ohlich
|-
| 1030
| 0406
| Commodore (Lowell University)
| Originally registered to Productivity Center
|-
| 1041
| 0411
| Design Labs
|-
| 1042
| 0412
| MCS
|-
| 1043
| 0413
| B. J. Freeman
|-
| 1044
| 0414
| Side Effects Inc.
|-
| 1045
| 0415
| Oklahoma Personal Comp.
|-
| 1046
| 0416
| Advanced Micro Innovations
|-
| 1047
| 0417
| Industrial Support Services
|-
| 1048
| 0418
| Technisoft
|-
| 1049
| 0419
| Prolific, Inc.
|-
| 1050
| 041A
| Softeam, Inc.
|-
| 1051
| 041B
| GRC Electronics
|-
| 1052
| 041C
| David Lai
|-
| 1053
| 041D
| Ameristar Technologies
|-
| 1054
| 041E
| Cline Refrigeration
|-
| 1055
| 041F
| Cardiac Pacemakers, Inc.
|-
| 1056
| 0420
| Supra Corp. (Creative Microsystems)
|-
| 1057
| 0421
| Wayne Diener
|-
| 1058
| 0422
| Computer Systems Associates (CSA)
|-
| 1059
| 0423
| Trionix, Inc.
|-
| 1060
| 0424
| David Lucas
|-
| 1061
| 0425
| Analog Precision
| Also assigned to D & L Distributing
|-
| 1267
| 04F3
| RBM Digitaltechnik
|-
| 1282
| 0502
| M-TEC Hardware Design
|-
| 1337
| 0539
| Thomas Stenzel (DaFR34K)
|-
| 1576
| 0628
| Boris Križma
|-
| 1729
| 06C1
| Thomas Richter / OpenPCI-A1200 Mediator bridge
|-
| 1730
| 06C2
| Thomas Richter / OpenPCI-A4000 Mediator bridge
|-
| 1731
| 06C3
| Thomas Richter / OpenPCI-Prometheus bridge (Firestorm or original)
|-
| 1732
| 06C4
| Thomas Richter / OpenPCI-Reserved1
|-
| 1733
| 06C5
| Thomas Richter / OpenPCI-Grex bridge (both A1200 and A4000)
|-
| 1734
| 06C6
| Thomas Richter / OpenPCI-Reserved2
|-
| 1735
| 06C7
| Thomas Richter / OpenPCI-Reserved3
|-
| 1736
| 06C8
| Thomas Richter / OpenPCI-Reserved4
|-
| 1737
| 06C9
| Thomas Richter / OpenPCI-Reserved5
|-
| 1738
| 06CA
| Thomas Richter / OpenPCI-Reserved6
|-
| 1739
| 06CB
| Thomas Richter / OpenPCI-Reserved7
|-
| 1740
| 06CC
| Thomas Richter / OpenPCI-Reserved8
|-
| 1741
| 06CD
| Thomas Richter / OpenPCI-Reserved9
|-
| 1742
| 06CE
| Thomas Richter / OpenPCI-Reserved10
|-
| 1743
| 06CF
| Thomas Richter / OpenPCI-Reserved11
|-
| 1744
| 06D0
| Thomas Richter / OpenPCI-Reserved12
|-
| 1761
| 06E1
| Great Valley Products
|-
| 1803
| 070B
| UAE Amiga Emulator
|-
| 2002
| 07D2
| Mimetics Corp.
|-
| 2003
| 07D3
| ACDA
|-
| 2004
| 07D4
| Finn R. Jacobsen
|-
| 2005
| 07D5
| Elthen Electronics
|-
| 2006
| 07D6
| Nine Tiles Computer Systems Ltd.
|-
| 2007
| 07D7
| Analog Electronics
|-
| 2008
| 07D8
| Bell & Howell
|-
| 2009
| 07D9
| Roland Kochler
|-
| 2010
| 07DA
| Byte Corp.
|-
| 2011
| 07DB
| Reserved
|-
| 2012
| 07DC
| DKB, Inc.
| Previously named Michigan Software
|-
| 2013
| 07DD
| Pacific Peripherals
|-
| 2014
| 07DE
| Sysaphus Software
|-
| 2015
| 07DF
| Digitronics
|-
| 2016
| 07E0
| Akron Systems
|-
| 2017
| 07E1
| Great Valley Products
|-
| 2018
| 07E2
| Calmos
|-
| 2019
| 07E3
| Dover Research
|-
| 2020
| 07E4
| David Krehbiel
|-
| 2021
| 07E5
| Synergy Peripheral Systems
| Also known as California Access
|-
| 2022
| 07E6
| Xetec
|-
| 2023
| 07E7
| Micron Technology
|-
| 2024
| 07E8
| CH Electronics
|-
| 2025
| 07E9
| American Liquid Light
|-
| 2026
| 07EA
| Progressive Peripherals & Software
| Also used by Ateo
|-
| 2027
| 07EB
| Wicat Systems
|-
| 2028
| 07EC
| Applied Systems & Peripherals
|-
| 2029
| 07ED
| Delaware Valley Software
|-
| 2030
| 07EE
| Palomax
|-
| 2031
| 07EF
| Incognito Software
|-
| 2032
| 07F0
| Jadesign
|-
| 2033
| 07F1
| BVR
|-
| 2034
| 07F2
| Spirit Technology
|-
| 2035
| 07F3
| Spirit Technology
|-
| 2036
| 07F4
| Atronic
|-
| 2037
| 07F5
| Scott Karlin
|-
| 2038
| 07F6
| Howitch
|-
| 2039
| 07F7
| Sullivan Brothers Visual Engineers
|-
| 2040
| 07F8
| G I T
|-
| 2041
| 07F9
| Amigo Business Computers
|-
| 2042
| 07FA
| Micro E Ab
|-
| 2043
| 07FB
| Ralph Kruse
|-
| 2044
| 07FC
| Clearpoint Research
|-
| 2045
| 07FD
| Kodiak
|-
| 2046
| 07FE
| BSC
| Originally registered to Phoenix Electronics
|-
| 2047
| 07FF
| No Name Shown
|-
| 2048
| 0800
| Commodore Braunschweig
|-
| 2049
| 0801
| BSC
| Originally registered to Elaborate Bytes
|-
| 2050
| 0802
| Kronos/C Ltd.
|-
| 2051
| 0803
| Spartanics
|-
| 2052
| 0804
| Jochheim Computer Tuning
|-
| 2053
| 0805
| Trans Data Systems
|-
| 2054
| 0806
| Applied Systems & Peripherals Ltd.
|-
| 2055
| 0807
| Checkpoint Technologies
| Originally registered to Amiga Solutions
|-
| 2056
| 0808
| Adept Development
|-
| 2057
| 0809
| Advanced Computer Design
|-
| 2058
| 080A
| Sir Netics
|-
| 2059
| 080B
| Expert Services
|-
| 2060
| 080C
| Digital Art Systems
|-
| 2061
| 080D
| Adept Development
|-
| 2062
| 080E
| Expansion Technologies (Expansion Systems)
|-
| 2063
| 080F
| Alphatech
|-
| 2064
| 0810
| Edotronik GmbH
|-
| 2065
| 0811
| California Access/Synergy
| Originally registered to Logical Design Works
|-
| 2066
| 0812
| Bowden, Williams, Full & Assoc.
|-
| 2067
| 0813
| NES, Inc.
|-
| 2068
| 0814
| Amdev
|-
| 2069
| 0815
| Big Brother Security Systems
|-
| 2070
| 0816
| Active Circuits Inc.
|-
| 2071
| 0817
| ICD, Inc.
|-
| 2072
| 0818
| Multi-Meg Electronique
|-
| 2073
| 0819
| Kupke Computertechnik GmbH
|-
| 2074
| 081A
| The Checkered Ball
|-
| 2075
| 081B
| Hi Tension Computer Services Ltd. (UK)
|-
| 2076
| 081C
| Alfa Data
| Originally assigned to Elmtech Research, Ltd. (UK)
|-
| 2077
| 081D
| Great Valley Products
| Originally registered to Clartscreen, Ltd. (UK)
|-
| 2078
| 081E
| Interworks
|-
| 2079
| 081F
| Galysh Enterprises
|-
| 2080
| 0820
| Hardital Synthesis
| Originally registered to Realtime Games Software Ltd.
|-
| 2081
| 0821
| GBS
|-
| 2082
| 0822
| Circum Design Inc.
|-
| 2083
| 0823
| Alberta Micro Electronic Center
|-
| 2084
| 0824
| Bestech
|-
| 2085
| 0825
| Lasar Fantasy
|-
| 2086
| 0826
| Pulsar
|-
| 2087
| 0827
| Ivis
|-
| 2088
| 0828
| Applied Engineering
|-
| 2089
| 0829
| Solid-State Design & Development
|-
| 2090
| 082A
| Vison Quest
|-
| 2091
| 082B
| Seaview Software
|-
| 2092
| 082C
| BSC
| Mistakenly used by ADS (Advanced Development Software)
|-
| 2093
| 082D
| Bernd Culenfeld
|-
| 2094
| 082E
| American Liquid Light
|-
| 2095
| 082F
| CEGITES
|-
| 2096
| 0830
| Quadlite Computers Ltd.
| Originally registered to EV Industries
|-
| 2097
| 0831
| Silicon Peace
|-
| 2098
| 0832
| Black Belt Systems
|-
| 2099
| 0833
| Village Tronic
| Originally registerd to Steve Yaeger
|-
| 2100
| 0834
| ReadySoft
|-
| 2101
| 0835
| Phoenix Micro Technologies
|-
| 2102
| 0836
| Advanced Systems & Software
| Orignally assigned to Preferred Technology
|-
| 2103
| 0837
| Rombo Productions
|-
| 2104
| 0838
| Impulse Inc.
|-
| 2105
| 0839
| Beta Unlimited
|-
| 2106
| 083A
| Memory Expansion System, Ltd.
|-
| 2107
| 083B
| Vortex Computer Systems GmbH
|-
| 2108
| 083C
| Platypus Systems
|-
| 2109
| 083D
| Gigatron OHG
|-
| 2110
| 083E
| PG Electronics
|-
| 2111
| 083F
| New Technologies Group
|-
| 2112
| 0840
| Interactive Video Systems (IVS)
| Pacific Peripherals
|-
| 2113
| 0841
| Vector
| Originally registered to H. K. Computer
|-
| 2114
| 0842
| Pacific Digital
| Originally registered to C. H. Helfrich Elektronik
|-
| 2115
| 0843
| Xanadu
|-
| 2116
| 0844
| Pacific Digital
| Originally registered to AMS
|-
| 2117
| 0845
| X-Pert
|-
| 2118
| 0846
| The Amiga Centre
|-
| 2119
| 0847
| Digital Pacific
|-
| 2120
| 0848
| Solid State Leisure
|-
| 2121
| 0849
| Hydra Systems
| Originally registered to Analog Electronics
|-
| 2122
| 084A
| Cumana
|-
| 2123
| 084B
| KAPS 2C Conception
|-
| 2124
| 084C
| Mike Mason
|-
| 2125
| 084D
| For Your Eyes
|-
| 2126
| 084E
| Volkmar Breitfeld Computersysteme
|-
| 2127
| 084F
| Sunrize Industries
|-
| 2128
| 0850
| Scott Advanced Micro Designs
|-
| 2129
| 0851
| Digital Micronics
|-
| 2130
| 0852
| Alfa-Laval
|-
| 2131
| 0853
| Multigros A/S
|-
| 2132
| 0854
| Archos
|-
| 2133
| 0855
| Icom Simulations
|-
| 2134
| 0856
| Commodore Test Engineering Group
|-
| 2135
| 0857
| Microcreations
|-
| 2136
| 0858
| Shoestring Productions
|-
| 2137
| 0859
| Faberushi
|-
| 2138
| 085A
| Evesham Micro Ltd.
|-
| 2139
| 085B
| Panagolin Laser Software
|-
| 2140
| 085C
| Thomas Rudloff
|-
| 2141
| 085D
| Daniel Hohabir
|-
| 2142
| 085E
| GfxBase, Inc.
|-
| 2143
| 085F
| Axellabs
|-
| 2144
| 0860
| Roctec Electronics Inc.
|-
| 2145
| 0861
| Omega Datentechnik
|-
| 2146
| 0862
| Atlantis
|-
| 2147
| 0863
| Skytec Computers
|-
| 2148
| 0864
| Protar Electronics
|-
| 2149
| 0865
| ACS
|-
| 2150
| 0866
| Software Results Enterprises
| Originally registered to University of Illinois
|-
| 2151
| 0867
| Infinity Systems Design Group
|-
| 2152
| 0868
| Trade It
|-
| 2153
| 0869
| Suntec, Inc.
|-
| 2154
| 086A
| DJW Micro Systems
| Originally registered to Tritec Marketing
|-
| 2155
| 086B
| Power Computing Ltd.
|-
| 2156
| 086C
| MacroSystems
|-
| 2157
| 086D
| Masoboshi GmbH (DCE)
|-
| 2158
| 086E
| HAL Software Hardware Handel
|-
| 2159
| 086F
| Mainhattan Data
| Originally registered to Michael Lamm Computersysteme
|-
| 2160
| 0870
| Digital Processing System
| Originally registered to bbdp Electronics
|-
| 2161
| 0871
| Blue Ribbon Soundworks
| Originally registered to Design Computer Systems
|-
| 2162
| 0872
| XPert
| Originally registered to The Station
|-
| 2163
| 0873
| DelaComp
| Originally registered to Bryan Williams
|-
| 2164
| 0874
| Superformance Computer Engineering GmbH
|-
| 2165
| 0875
| Overland Engineering
|-
| 2166
| 0876
| Thomas Hamren
|-
| 2167
| 0877
| Village Tronic
|-
| 2168
| 0878
| Toolbox Design
|-
| 2169
| 0879
| Digital Processing System
|-
| 2170
| 087A
| Superformance
|-
| 2171
| 087B
| Utilities Unlimited
|-
| 2172
| 087C
| phase 5
|-
| 2173
| 087D
| Juergen Kommos
|-
| 2174
| 087E
| Electronic Design
|-
| 2175
| 087F
| James Cook University of North Queensland
|-
| 2176
| 0880
| AmiTrix Development
|-
| 2177
| 0881
| Ferranti
|-
| 2178
| 0882
| Leviathan Development
|-
| 2179
| 0883
| United Video Inc.
|-
| 2180
| 0884
| GPSoft Pty. Ltd.
| Originally registered to Juergen Kommos
|-
| 2181
| 0885
| ArMAX
| Oliver Bausch
|-
| 2182
| 0886
| CP Computer
|-
| 2183
| 0887
| AMOK - Amiga Module & Oberon Klub
|-
| 2184
| 0888
| ITEK Neser & Sieber GbR
|-
| 2185
| 0889
| Phillip C. Lello
|-
| 2186
| 088A
| Cyborg Design Services
|-
| 2187
| 088B
| G2 Systems
|-
| 2188
| 088C
| Pro System Computersysteme
|-
| 2189
| 088D
| ZEUS Electronic
| Originally registered to MSPI (Markt & Technik)
|-
| 2190
| 088E
| Altatech
|-
| 2191
| 088F
| NewTek
|-
| 2192
| 0890
| M-TEC Hardware Design
| Originally registered to Hardware Design Udo Neuroth
|-
| 2193
| 0891
| Great Valley Products
| Originally registered to Viona Development
|-
| 2194
| 0892
| Amitek
| Originally assigned to Marpet Developments
|-
| 2195
| 0893
| Ingenieurbuero Helfrich
|-
| 2196
| 0894
| The Neo Group
|-
| 2197
| 0895
| Cyon
|-
| 2198
| 0896
| Bob Research Group
|-
| 2199
| 0897
| Richmond Sound Design Ltd.
|-
| 2200
| 0898
| US Cybernetics
|-
| 2201
| 0899
| Fulvio Ieva
|-
| 2202
| 089A
| Silicon Studio
|-
| 2203
| 089B
| MacroSystems (USA)
| Was named Micro System Devices
|-
| 2204
| 089C
| Conspector Entertainment
|-
| 2205
| 089D
| Laserforum
|-
| 2206
| 089E
| Elbox Computer
| Mistakenly used by Index Information Ltd.
|-
| 2207
| 089F
| Applied Magic Inc.
|-
| 2208
| 08A0
| SDL Ltd.
|-
| 2560
| 0A00
| Harms
|-
| 2588
| 0A1C
| A1K.org Community
|-
| 2640
| 0A50
| Micronik
|-
| 2782
| 2782
| OA Design
|-
| 3084
| 0C0C
| Team 4
|-
| 3643
| 0E3B
| E3B
| Michael Boehmer
|-
| 3855
| 0F0F
| Micronik
|-
| 4096
| 1000
| MegaMicro
|-
| 4110
| 100E
| DigiFeX
|-
| 4136
| 1028
| Imtronics/Memphis
|-
| 4149
| 1035
| PROTAR
|-
| 4369
| 1111
| Frank Strauß Elektronik
| Also used by Kupke
|-
| 4626
| 1212
| Individual Computers
|-
| 4648
| 1228
| Flesch Hornemann Computer Elec.
|-
| 4680
| 1248
| Kupke Computertechnik GmbH
|-
| 4711
| 1267
| RBM digitaltechnik
|-
| 4754
| 1292
| MacroSystems
|-
| 5000
| 1388
| ITH
|-
| 5001
| 1389
| VMC
|-
| 5010
| 1392
| Ambience Creation Technology
|-
| 5011
| 1393
| Creative Development
|-
| 5012
| 1394
| Georg Braun
|-
| 5013
| 1395
| Swedish User Group of Amiga
|-
| 5014
| 1396
| Jakub Bednarski
|-
| 5015
| 1397
| KryoFlux, Ltd.
|-
| 5016
| 1398
| Igor Majstorovic
|-
| 5017
| 1399
| Alastair M. Robinson
|-
| 5018
| 139A
| Austex Software
|-
| 5019
| 139B
| Sören Gust
|-
| 5020
| 139C
| Rok Krajnc
|-
| 5030
| 13A6
| Tim Tashpulatov
|-
| 5040
| 13B0
| 7-bit
|-
| 5050
| 13BA
| Sakura IT
|-
| 5060
| 13C4
| FPGAArcade
|-
| 5070
| 13CE
| CancerSoft Inc.
|-
| 5080
| 13D8
| Stephen Leary
|-
| 5090
| 13E2
| DMA Softlab LLC
|-
| 5100
| 13EC
| Brookhouse Engineering
|-
| 5110
| 13F6
| Eduardo Arana
|-
| 5120
| 1400
| CS-LAB
|-
| 5130
| 140A
| Robert Miranda
|-
| 5140
| 1414
| RastPort
|-
| 5132
| 140C
| UAS Interface Ltd6
|-
| 5150
| 141E
| Amiga Kit
|-
| 5160
| 1428
| Central Texas Commodore User Group
|-
| 5170
| 1432
| Confusion Research Center
|-
| 5180
| 143C
| Solar Soyuz Zaibatsu
|-
| 5190
| 1446
| BooBip
|-
| 5191
| 1447
| Matthias Hampel
|-
| 5192
| 1448
| dec0de Consulting Ltd.
|-
| 5193
| 1449
| Puppy Concepts
|-
| 5194
| 144A
| Open Amiga Hardware Repository
|-
| 5195
| 144B
| Double H Tech
|-
| 5196
| 144C
| Retromatik
|-
| 5500
| 157C
| Inhouse Information
|-
| 5768
| 1688
| Bio Con
|-
| 6148
| 1804
| HK-Computer
|-
| 6502
| 1966
| Cloanto
|-
| 6520
| 1978
| Oliver Gantert
|-
| 7777
| 1E61
| Rafal Gabriel Chyla
|-
| 8215
| 2017
| Vortex
|-
| 8244
| 2034
| Spirit Technology
|-
| 8290
| 2062
| Expansion Systems
|-
| 8448
| 2100
| ReadySoft
|-
| 8512
| 2140
| Phase 5 Digital Products
|-
| 8553
| 2169
| Digital Processing Systems Inc.
|-
| 8704
| 2200
| ACT Elektronik
|-
| 8738
| 2222
| ACT Elektronik
|-
| 9512
| 2528
| Tower Technologies
|-
| 10676
| 29B4
| Electronic Design
|-
| 14195
| 3773
| Media-net-Point
|-
| 14501
| 38A5
| Petsoff, Finland
|-
| 16375
| 3FF7
| Uwe Gerlach
|-
| 16707
| 4143
| Ateo Concepts
|-
| 16708
| 4144
| ALiENDESiGN
|-
| 16945
| 4231
| A.C.T.
|-
| 17740
| 454C
| HK-Computer (ELSAT)
|-
| 18260
| 4754
| MacroSystems (Germany)
|-
| 19796
| 4D54
| Markt & Technik
|-
| 20480
| 5000
| François Lacombe
|-
| 22359
| 5757
| Markt & Technik
|-
| 26464
| 6760
| Combitec
|-
| 26470
| 6766
| Combitec
|-
| 28014
| 6D6E
| MNT Media and Technology UG
|-
| 28019
| 6D73
| Michal Schulz
|-
| 32768
| 8000
| M.A.S.T.
|-
| 42240
| A500
| Aethreum Digital
|-
| 43437
| A9AD
| Reis-Ware
|-
| 43521
| AA01
| Cameron
|-
| 43537
| AA11
| Reis-Ware
|-
| 44359
| AD47
| Matay
|-
| 46504
| B5A8
| Phoenix
|-
| 48879
| BEEF
| Swiss Mountain Dog Products
|-
| 49160
| C008
| Combitec
|-
| 61453
| F00D
| Forefront Technologies Inc.
|}

For any changes/additions to this registry see [[#How_to_Obtain_a_Manufacturer_Number|How to Obtain a Manufacturer Number]]

Amiga Hardware Manufacturer ID Registry

2026-09-08T11:11:20Z

Costel Mincea: Added François Lacombe (20480)

__TOC__

= How to Obtain a Manufacturer Number =

Manufacturer's numbers are assigned by the AmigaOS development team. To obtain your unique manufacturer number send a support request to [mailto:support@hyperion-entertainment.com support@hyperion-entertainment.com] including these information:

1. The name of the company or person which the number is assigned to

2. Postal address/contact address

3. Name of the contact person, with a corresponding e-mail address

4. A brief description of the kind of products you want to produce

= Your Manufacturer Number =

Attention hardware manufacturers. If you are developing a hardware expansion product for the Classic Amiga (e.g. 500, 2000, 3000) then you will need to obtain a special manufacturer ID number from the AmigaOS development team to identify your product. This manufacturer number is used by the Amiga to link your hardware with its driver software at boot time.

Your manufacturer number is part of the special protocol that the Amiga uses to automatically configure all expansion devices on the bus without the user having to cut jumpers or adjust dip switches. This is called auto-config.

At start-up time, the system first polls each board in the system and assigns the board its own address space. If it is a memory board, its RAM is linked into the memory free pool. Later in the boot sequence, after DOS is initialized, the binddrivers program is run. Binddrivers will search the directory SYS:Expansion for the drivers that go with the boards.

To do this binddrivers looks in the Tool Type field of all icon files in SYS:Expansion. If the first seven bytes of the Tool Type field are "PRODUCT", then this is an icon file for a driver.

Binddrivers will then attempt to match the drivers it has found with the boards that were found earlier. This is where your manufacturer number comes in.

Your manufacturer number goes in two places. First, it is burned in hex form into the PAL which is part of ALL auto-config expansion products. Second, it appears in ASCII in the Tool Type field of the icon file for your product's driver. By matching these two numbers, the Amiga can automatically configure your board and bind it's software driver into the system as well.

The manufacturer's number is a 16-bit ID which appears in PAL offsets $10-$17. There is also an 8-bit product number which you assign. The product number is for uniquely identifying different products from the same vendor. The product number will appear in PAL offsets $04-$07. This gives you a total of 24 bits to identify each of your products.

These 24 bits of information in the PAL which identify your product are matched against the information in the Tool Type field of all icon files in the SYS:Expansion drawer. For example, suppose you are manufacturer #1019. You have two products, #1 and #2 which both use the same driver. The icon for your driver for these two products would have a Tool Type set to "PRODUCT=1019/1|1019/2". This means: I am an icon for a driver that works with product number 1 or 2 from manufacturer 1019, now bind me. Spaces are not legal. Here are two other examples:

; PRODUCT=1208/11
: is the Tool Type for a driver for product 11 from manufacturer number 1208.

; PRODUCT=1017
: is the Tool Type for a driver for any product from manufacturer number 1017.

For an informal explanation of the auto-configuration process, see the chapter on Software Expansion Architecture from the 2nd Annual Amiga Developer's Conference Notes (available on ADCD 2.1). For the details of timing, power, the PAL equations and PAL address specifications and the expansion library documentation, see sections 3.1 to 3.3 of the A500/A2000 Technical Reference Manual. The original auto-config spec appears in the A1000 Schematics and Expansion Specification.

The auto-config process makes the addition of expansion products to the system very easy. All the user has to do is put the board in any slot and copy the driver from the release disk to his own SYS:Expansion drawer. Everything else is automatic. There are no jumpers or dip switches to set. Best of all, you will get a lot less support calls asking how to make your product work with the XYZ-Corp-battery-backed-clock.

= Notes =

Some notes on hardware manufacturer ID assignment.

* Manufacturer ID numbers are assigned free of charge.
* Please provide the following information when requesting an ID:
*# Name of the company or person
*# Postal address/contact address
*# Name of the contact person, with a corresponding e-mail address
*# A brief description of the kind of products you want to produce
* All ID numbers smaller than 5000 must be considered unsafe because no information exists on which numbers exactly were taken during the time Commodore, Inc. disintegrated.
* ID numbers in the range 8192 to 18841 must be considered unsafe because some hardware developers mistook the numbers assigned to them to be given in hexadecimal format. Hence 0x2000 = 8192 and 0x4999 = 18841.

= Example code =

<syntaxhighlight lang="C" line>
/*-----------------------------------------------*/
/* Here is a short program which will tell you */
/* about the expansion boards configured in your */
/* system without you opening up the machine. */
/* Code by Bill Koester of CATS */
/*-----------------------------------------------*/
#include <libraries/configvars.h>
#include <libraries/expansion.h>

struct ExpansionBase *ExpansionBase;

void cleanup();
void printdev();

int main()
{
struct ConfigDev *MyConfigDev;

/*----------------------------------*/
/* Open the expansion library, */
/* if there is a problem then exit */
/*----------------------------------*/

ExpansionBase =(struct ExpansionBase *) OpenLibrary(EXPANSIONNAME,0);
if(ExpansionBase==NULL)
{
printf("Error opening expansion library!!\n");
cleanup();
exit(0);
}

/*--------------------------------------------*/
/* Use FindConfigDev to get info on the first */
/* expansion board on the list maintained by */
/* Exec. If there are no expansion boards in */
/* the system then exit. */
/*--------------------------------------------*/

MyConfigDev = NULL;

/*--------------------------------------------------*/
/* FindConfigDev(oldConfigDev,manufacturer,product) */
/* oldConfigDev = NULL for the top of the list */
/* manufacturer = -1 for any manufacturer */
/* product = -1 for any product */
/*--------------------------------------------------*/

MyConfigDev = FindConfigDev(NULL,-1,-1);

if(MyConfigDev==NULL)
{
printf("No Configured Devices found!!\n");
cleanup();
exit(0);
}

printdev(MyConfigDev);

/*-----------------------------------*/
/* OK, there is at least one board, */
/* so loop and get the entire list */
/* printing as we go with printdev() */
/*-----------------------------------*/

while(MyConfigDev = FindConfigDev(MyConfigDev,-1,-1))
{
printdev(MyConfigDev);
}
cleanup();
return 0;
}

/*-------------------*/
/* Close up shop... */
/*-------------------*/
void cleanup()
{
if(ExpansionBase)
CloseLibrary(ExpansionBase);
}

/*----------------------------------*/
/* Print out the contents of the */
/* dev structure for this expansion */
/* product. */
/*----------------------------------*/

void printdev(dev)
struct ConfigDev *dev;
{
char buff[200];

printf("Flags = ");
if(dev->cd_Flags==NULL)
printf("NULL ");
if(dev->cd_Flags&CDF_SHUTUP)
printf("CDF_SHUTUP ");
if(dev->cd_Flags&CDF_CONFIGME)
printf("CDF_CONFIGME ");
printf("\n");
printf("Board Address = %x\n",dev->cd_BoardAddr);
printf("Board Size = %d bytes\n",dev->cd_BoardSize);
printf("Slot Address = %d\n",dev->cd_SlotAddr);
printf("Slot Size = %d\n",dev->cd_SlotSize);
printf("Driver code at %x\n",dev->cd_Driver);

printf("er_Type = %x\n",dev->cd_Rom.er_Type);
printf("er_Product = %x\n",dev->cd_Rom.er_Product);
printf("er_Flags = %x\n",dev->cd_Rom.er_Flags);
printf("er_Reserved03 = %x\n",dev->cd_Rom.er_Reserved03);
printf("er_Manufacturer = %x\n",dev->cd_Rom.er_Manufacturer);
printf("er_SerialNumber = %x\n",dev->cd_Rom.er_SerialNumber);
printf("er_InitDiagVec = %x\n",dev->cd_Rom.er_InitDiagVec);
printf("er_Reserved0c = %x\n",dev->cd_Rom.er_Reserved0c);
printf("er_Reserved0d = %x\n",dev->cd_Rom.er_Reserved0d);
printf("er_Reserved0e = %x\n",dev->cd_Rom.er_Reserved0e);
printf("er_Reserved0f = %x\n",dev->cd_Rom.er_Reserved0f);

printf("Hit Return to continue:\n");
gets(buff);
}
</syntaxhighlight>

= Registry =

{| class="wikitable"
! ID (decimal)
! ID (hexadecimal)
! Manufacturer
! Notes
|-
| 1
| 0001
| Micronik
|-
| 211
| 00D3
| Pacific Peripherals/Profex
|-
| 221
| 00DD
| Kupke Computertechnik GmbH
|-
| 256
| 0100
| Memphis
| Originally registered to MacroSystems US
|-
| 512
| 0200
| 3-State Computertechnik
|-
| 513
| 0201
| Commodore (Braunschweig)
|-
| 514
| 0202
| Commodore (West Chester)
|-
| 515
| 0203
| Commodore (West Chester)
| Originally registered to Combitech/Macrosystem
|-
| 756
| 02F4
| Progressive Peripherals & Software
|-
| 767
| 02FF
| Kolff Computer Supplies
|-
| 1001
| 03E9
| Tecmar
|-
| 1002
| 03EA
| Telesys
|-
| 1003
| 03EB
| The Micro-Forge
|-
| 1004
| 03EC
| Kronos/C Ltd.
| Originally registered to Card Co. (Supra)
|-
| 1005
| 03ED
| A-Squared
|-
| 1006
| 03EE
| Comspec Communications
|-
| 1007
| 03EF
| HT Electronics
|-
| 1008
| 03F0
| RDS Software
|-
| 1009
| 03F1
| Anakin Research
|-
| 1010
| 03F2
| MicroBotics
|-
| 1011
| 03F3
| Bob Krauth
|-
| 1012
| 03F4
| Access Associates (Alegra)
|-
| 1013
| 03F5
| Mini Comp Systems Ltd.
|-
| 1014
| 03F6
| Cypress Technology
|-
| 1015
| 03F7
| Fuller Computers
|-
| 1016
| 03F8
| Galaxy Computers
|-
| 1017
| 03F9
| ADA Research
|-
| 1018
| 03FA
| Computer Service Italia
|-
| 1019
| 03FB
| Amigo
|-
| 1020
| 03FC
| Micro-Solutions Inc.
|-
| 1021
| 03FD
| Stacar International
|-
| 1022
| 03FE
| Video Precisions
|-
| 1023
| 03FF
| ASDG, Inc.
|-
| 1025
| 0401
| Ing. Buero Kalawsky
|-
| 1026
| 0402
| Computer Tuning
|-
| 1027
| 0403
| Interplan Unternehmensberatung
|-
| 1028
| 0404
| Imtronics/Memphis
| Originally registered to Peter Ohlich
|-
| 1030
| 0406
| Commodore (Lowell University)
| Originally registered to Productivity Center
|-
| 1041
| 0411
| Design Labs
|-
| 1042
| 0412
| MCS
|-
| 1043
| 0413
| B. J. Freeman
|-
| 1044
| 0414
| Side Effects Inc.
|-
| 1045
| 0415
| Oklahoma Personal Comp.
|-
| 1046
| 0416
| Advanced Micro Innovations
|-
| 1047
| 0417
| Industrial Support Services
|-
| 1048
| 0418
| Technisoft
|-
| 1049
| 0419
| Prolific, Inc.
|-
| 1050
| 041A
| Softeam, Inc.
|-
| 1051
| 041B
| GRC Electronics
|-
| 1052
| 041C
| David Lai
|-
| 1053
| 041D
| Ameristar Technologies
|-
| 1054
| 041E
| Cline Refrigeration
|-
| 1055
| 041F
| Cardiac Pacemakers, Inc.
|-
| 1056
| 0420
| Supra Corp. (Creative Microsystems)
|-
| 1057
| 0421
| Wayne Diener
|-
| 1058
| 0422
| Computer Systems Associates (CSA)
|-
| 1059
| 0423
| Trionix, Inc.
|-
| 1060
| 0424
| David Lucas
|-
| 1061
| 0425
| Analog Precision
| Also assigned to D & L Distributing
|-
| 1267
| 04F3
| RBM Digitaltechnik
|-
| 1282
| 0502
| M-TEC Hardware Design
|-
| 1337
| 0539
| Thomas Stenzel (DaFR34K)
|-
| 1576
| 0628
| Boris Križma
|-
| 1729
| 06C1
| Thomas Richter / OpenPCI-A1200 Mediator bridge
|-
| 1730
| 06C2
| Thomas Richter / OpenPCI-A4000 Mediator bridge
|-
| 1731
| 06C3
| Thomas Richter / OpenPCI-Prometheus bridge (Firestorm or original)
|-
| 1732
| 06C4
| Thomas Richter / OpenPCI-Reserved1
|-
| 1733
| 06C5
| Thomas Richter / OpenPCI-Grex bridge (both A1200 and A4000)
|-
| 1734
| 06C6
| Thomas Richter / OpenPCI-Reserved2
|-
| 1735
| 06C7
| Thomas Richter / OpenPCI-Reserved3
|-
| 1736
| 06C8
| Thomas Richter / OpenPCI-Reserved4
|-
| 1737
| 06C9
| Thomas Richter / OpenPCI-Reserved5
|-
| 1738
| 06CA
| Thomas Richter / OpenPCI-Reserved6
|-
| 1739
| 06CB
| Thomas Richter / OpenPCI-Reserved7
|-
| 1740
| 06CC
| Thomas Richter / OpenPCI-Reserved8
|-
| 1741
| 06CD
| Thomas Richter / OpenPCI-Reserved9
|-
| 1742
| 06CE
| Thomas Richter / OpenPCI-Reserved10
|-
| 1743
| 06CF
| Thomas Richter / OpenPCI-Reserved11
|-
| 1744
| 06D0
| Thomas Richter / OpenPCI-Reserved12
|-
| 1761
| 06E1
| Great Valley Products
|-
| 1803
| 070B
| UAE Amiga Emulator
|-
| 2002
| 07D2
| Mimetics Corp.
|-
| 2003
| 07D3
| ACDA
|-
| 2004
| 07D4
| Finn R. Jacobsen
|-
| 2005
| 07D5
| Elthen Electronics
|-
| 2006
| 07D6
| Nine Tiles Computer Systems Ltd.
|-
| 2007
| 07D7
| Analog Electronics
|-
| 2008
| 07D8
| Bell & Howell
|-
| 2009
| 07D9
| Roland Kochler
|-
| 2010
| 07DA
| Byte Corp.
|-
| 2011
| 07DB
| Reserved
|-
| 2012
| 07DC
| DKB, Inc.
| Previously named Michigan Software
|-
| 2013
| 07DD
| Pacific Peripherals
|-
| 2014
| 07DE
| Sysaphus Software
|-
| 2015
| 07DF
| Digitronics
|-
| 2016
| 07E0
| Akron Systems
|-
| 2017
| 07E1
| Great Valley Products
|-
| 2018
| 07E2
| Calmos
|-
| 2019
| 07E3
| Dover Research
|-
| 2020
| 07E4
| David Krehbiel
|-
| 2021
| 07E5
| Synergy Peripheral Systems
| Also known as California Access
|-
| 2022
| 07E6
| Xetec
|-
| 2023
| 07E7
| Micron Technology
|-
| 2024
| 07E8
| CH Electronics
|-
| 2025
| 07E9
| American Liquid Light
|-
| 2026
| 07EA
| Progressive Peripherals & Software
| Also used by Ateo
|-
| 2027
| 07EB
| Wicat Systems
|-
| 2028
| 07EC
| Applied Systems & Peripherals
|-
| 2029
| 07ED
| Delaware Valley Software
|-
| 2030
| 07EE
| Palomax
|-
| 2031
| 07EF
| Incognito Software
|-
| 2032
| 07F0
| Jadesign
|-
| 2033
| 07F1
| BVR
|-
| 2034
| 07F2
| Spirit Technology
|-
| 2035
| 07F3
| Spirit Technology
|-
| 2036
| 07F4
| Atronic
|-
| 2037
| 07F5
| Scott Karlin
|-
| 2038
| 07F6
| Howitch
|-
| 2039
| 07F7
| Sullivan Brothers Visual Engineers
|-
| 2040
| 07F8
| G I T
|-
| 2041
| 07F9
| Amigo Business Computers
|-
| 2042
| 07FA
| Micro E Ab
|-
| 2043
| 07FB
| Ralph Kruse
|-
| 2044
| 07FC
| Clearpoint Research
|-
| 2045
| 07FD
| Kodiak
|-
| 2046
| 07FE
| BSC
| Originally registered to Phoenix Electronics
|-
| 2047
| 07FF
| No Name Shown
|-
| 2048
| 0800
| Commodore Braunschweig
|-
| 2049
| 0801
| BSC
| Originally registered to Elaborate Bytes
|-
| 2050
| 0802
| Kronos/C Ltd.
|-
| 2051
| 0803
| Spartanics
|-
| 2052
| 0804
| Jochheim Computer Tuning
|-
| 2053
| 0805
| Trans Data Systems
|-
| 2054
| 0806
| Applied Systems & Peripherals Ltd.
|-
| 2055
| 0807
| Checkpoint Technologies
| Originally registered to Amiga Solutions
|-
| 2056
| 0808
| Adept Development
|-
| 2057
| 0809
| Advanced Computer Design
|-
| 2058
| 080A
| Sir Netics
|-
| 2059
| 080B
| Expert Services
|-
| 2060
| 080C
| Digital Art Systems
|-
| 2061
| 080D
| Adept Development
|-
| 2062
| 080E
| Expansion Technologies (Expansion Systems)
|-
| 2063
| 080F
| Alphatech
|-
| 2064
| 0810
| Edotronik GmbH
|-
| 2065
| 0811
| California Access/Synergy
| Originally registered to Logical Design Works
|-
| 2066
| 0812
| Bowden, Williams, Full & Assoc.
|-
| 2067
| 0813
| NES, Inc.
|-
| 2068
| 0814
| Amdev
|-
| 2069
| 0815
| Big Brother Security Systems
|-
| 2070
| 0816
| Active Circuits Inc.
|-
| 2071
| 0817
| ICD, Inc.
|-
| 2072
| 0818
| Multi-Meg Electronique
|-
| 2073
| 0819
| Kupke Computertechnik GmbH
|-
| 2074
| 081A
| The Checkered Ball
|-
| 2075
| 081B
| Hi Tension Computer Services Ltd. (UK)
|-
| 2076
| 081C
| Alfa Data
| Originally assigned to Elmtech Research, Ltd. (UK)
|-
| 2077
| 081D
| Great Valley Products
| Originally registered to Clartscreen, Ltd. (UK)
|-
| 2078
| 081E
| Interworks
|-
| 2079
| 081F
| Galysh Enterprises
|-
| 2080
| 0820
| Hardital Synthesis
| Originally registered to Realtime Games Software Ltd.
|-
| 2081
| 0821
| GBS
|-
| 2082
| 0822
| Circum Design Inc.
|-
| 2083
| 0823
| Alberta Micro Electronic Center
|-
| 2084
| 0824
| Bestech
|-
| 2085
| 0825
| Lasar Fantasy
|-
| 2086
| 0826
| Pulsar
|-
| 2087
| 0827
| Ivis
|-
| 2088
| 0828
| Applied Engineering
|-
| 2089
| 0829
| Solid-State Design & Development
|-
| 2090
| 082A
| Vison Quest
|-
| 2091
| 082B
| Seaview Software
|-
| 2092
| 082C
| BSC
| Mistakenly used by ADS (Advanced Development Software)
|-
| 2093
| 082D
| Bernd Culenfeld
|-
| 2094
| 082E
| American Liquid Light
|-
| 2095
| 082F
| CEGITES
|-
| 2096
| 0830
| Quadlite Computers Ltd.
| Originally registered to EV Industries
|-
| 2097
| 0831
| Silicon Peace
|-
| 2098
| 0832
| Black Belt Systems
|-
| 2099
| 0833
| Village Tronic
| Originally registerd to Steve Yaeger
|-
| 2100
| 0834
| ReadySoft
|-
| 2101
| 0835
| Phoenix Micro Technologies
|-
| 2102
| 0836
| Advanced Systems & Software
| Orignally assigned to Preferred Technology
|-
| 2103
| 0837
| Rombo Productions
|-
| 2104
| 0838
| Impulse Inc.
|-
| 2105
| 0839
| Beta Unlimited
|-
| 2106
| 083A
| Memory Expansion System, Ltd.
|-
| 2107
| 083B
| Vortex Computer Systems GmbH
|-
| 2108
| 083C
| Platypus Systems
|-
| 2109
| 083D
| Gigatron OHG
|-
| 2110
| 083E
| PG Electronics
|-
| 2111
| 083F
| New Technologies Group
|-
| 2112
| 0840
| Interactive Video Systems (IVS)
| Pacific Peripherals
|-
| 2113
| 0841
| Vector
| Originally registered to H. K. Computer
|-
| 2114
| 0842
| Pacific Digital
| Originally registered to C. H. Helfrich Elektronik
|-
| 2115
| 0843
| Xanadu
|-
| 2116
| 0844
| Pacific Digital
| Originally registered to AMS
|-
| 2117
| 0845
| X-Pert
|-
| 2118
| 0846
| The Amiga Centre
|-
| 2119
| 0847
| Digital Pacific
|-
| 2120
| 0848
| Solid State Leisure
|-
| 2121
| 0849
| Hydra Systems
| Originally registered to Analog Electronics
|-
| 2122
| 084A
| Cumana
|-
| 2123
| 084B
| KAPS 2C Conception
|-
| 2124
| 084C
| Mike Mason
|-
| 2125
| 084D
| For Your Eyes
|-
| 2126
| 084E
| Volkmar Breitfeld Computersysteme
|-
| 2127
| 084F
| Sunrize Industries
|-
| 2128
| 0850
| Scott Advanced Micro Designs
|-
| 2129
| 0851
| Digital Micronics
|-
| 2130
| 0852
| Alfa-Laval
|-
| 2131
| 0853
| Multigros A/S
|-
| 2132
| 0854
| Archos
|-
| 2133
| 0855
| Icom Simulations
|-
| 2134
| 0856
| Commodore Test Engineering Group
|-
| 2135
| 0857
| Microcreations
|-
| 2136
| 0858
| Shoestring Productions
|-
| 2137
| 0859
| Faberushi
|-
| 2138
| 085A
| Evesham Micro Ltd.
|-
| 2139
| 085B
| Panagolin Laser Software
|-
| 2140
| 085C
| Thomas Rudloff
|-
| 2141
| 085D
| Daniel Hohabir
|-
| 2142
| 085E
| GfxBase, Inc.
|-
| 2143
| 085F
| Axellabs
|-
| 2144
| 0860
| Roctec Electronics Inc.
|-
| 2145
| 0861
| Omega Datentechnik
|-
| 2146
| 0862
| Atlantis
|-
| 2147
| 0863
| Skytec Computers
|-
| 2148
| 0864
| Protar Electronics
|-
| 2149
| 0865
| ACS
|-
| 2150
| 0866
| Software Results Enterprises
| Originally registered to University of Illinois
|-
| 2151
| 0867
| Infinity Systems Design Group
|-
| 2152
| 0868
| Trade It
|-
| 2153
| 0869
| Suntec, Inc.
|-
| 2154
| 086A
| DJW Micro Systems
| Originally registered to Tritec Marketing
|-
| 2155
| 086B
| Power Computing Ltd.
|-
| 2156
| 086C
| MacroSystems
|-
| 2157
| 086D
| Masoboshi GmbH (DCE)
|-
| 2158
| 086E
| HAL Software Hardware Handel
|-
| 2159
| 086F
| Mainhattan Data
| Originally registered to Michael Lamm Computersysteme
|-
| 2160
| 0870
| Digital Processing System
| Originally registered to bbdp Electronics
|-
| 2161
| 0871
| Blue Ribbon Soundworks
| Originally registered to Design Computer Systems
|-
| 2162
| 0872
| XPert
| Originally registered to The Station
|-
| 2163
| 0873
| DelaComp
| Originally registered to Bryan Williams
|-
| 2164
| 0874
| Superformance Computer Engineering GmbH
|-
| 2165
| 0875
| Overland Engineering
|-
| 2166
| 0876
| Thomas Hamren
|-
| 2167
| 0877
| Village Tronic
|-
| 2168
| 0878
| Toolbox Design
|-
| 2169
| 0879
| Digital Processing System
|-
| 2170
| 087A
| Superformance
|-
| 2171
| 087B
| Utilities Unlimited
|-
| 2172
| 087C
| phase 5
|-
| 2173
| 087D
| Juergen Kommos
|-
| 2174
| 087E
| Electronic Design
|-
| 2175
| 087F
| James Cook University of North Queensland
|-
| 2176
| 0880
| AmiTrix Development
|-
| 2177
| 0881
| Ferranti
|-
| 2178
| 0882
| Leviathan Development
|-
| 2179
| 0883
| United Video Inc.
|-
| 2180
| 0884
| GPSoft Pty. Ltd.
| Originally registered to Juergen Kommos
|-
| 2181
| 0885
| ArMAX
| Oliver Bausch
|-
| 2182
| 0886
| CP Computer
|-
| 2183
| 0887
| AMOK - Amiga Module & Oberon Klub
|-
| 2184
| 0888
| ITEK Neser & Sieber GbR
|-
| 2185
| 0889
| Phillip C. Lello
|-
| 2186
| 088A
| Cyborg Design Services
|-
| 2187
| 088B
| G2 Systems
|-
| 2188
| 088C
| Pro System Computersysteme
|-
| 2189
| 088D
| ZEUS Electronic
| Originally registered to MSPI (Markt & Technik)
|-
| 2190
| 088E
| Altatech
|-
| 2191
| 088F
| NewTek
|-
| 2192
| 0890
| M-TEC Hardware Design
| Originally registered to Hardware Design Udo Neuroth
|-
| 2193
| 0891
| Great Valley Products
| Originally registered to Viona Development
|-
| 2194
| 0892
| Amitek
| Originally assigned to Marpet Developments
|-
| 2195
| 0893
| Ingenieurbuero Helfrich
|-
| 2196
| 0894
| The Neo Group
|-
| 2197
| 0895
| Cyon
|-
| 2198
| 0896
| Bob Research Group
|-
| 2199
| 0897
| Richmond Sound Design Ltd.
|-
| 2200
| 0898
| US Cybernetics
|-
| 2201
| 0899
| Fulvio Ieva
|-
| 2202
| 089A
| Silicon Studio
|-
| 2203
| 089B
| MacroSystems (USA)
| Was named Micro System Devices
|-
| 2204
| 089C
| Conspector Entertainment
|-
| 2205
| 089D
| Laserforum
|-
| 2206
| 089E
| Elbox Computer
| Mistakenly used by Index Information Ltd.
|-
| 2207
| 089F
| Applied Magic Inc.
|-
| 2208
| 08A0
| SDL Ltd.
|-
| 2560
| 0A00
| Harms
|-
| 2588
| 0A1C
| A1K.org Community
|-
| 2640
| 0A50
| Micronik
|-
| 2782
| 2782
| OA Design
|-
| 3084
| 0C0C
| Team 4
|-
| 3643
| 0E3B
| E3B
| Michael Boehmer
|-
| 3855
| 0F0F
| Micronik
|-
| 4096
| 1000
| MegaMicro
|-
| 4110
| 100E
| DigiFeX
|-
| 4136
| 1028
| Imtronics/Memphis
|-
| 4149
| 1035
| PROTAR
|-
| 4369
| 1111
| Frank Strauß Elektronik
| Also used by Kupke
|-
| 4626
| 1212
| Individual Computers
|-
| 4648
| 1228
| Flesch Hornemann Computer Elec.
|-
| 4680
| 1248
| Kupke Computertechnik GmbH
|-
| 4711
| 1267
| RBM digitaltechnik
|-
| 4754
| 1292
| MacroSystems
|-
| 5000
| 1388
| ITH
|-
| 5001
| 1389
| VMC
|-
| 5010
| 1392
| Ambience Creation Technology
|-
| 5011
| 1393
| Creative Development
|-
| 5012
| 1394
| Georg Braun
|-
| 5013
| 1395
| Swedish User Group of Amiga
|-
| 5014
| 1396
| Jakub Bednarski
|-
| 5015
| 1397
| KryoFlux, Ltd.
|-
| 5016
| 1398
| Igor Majstorovic
|-
| 5017
| 1399
| Alastair M. Robinson
|-
| 5018
| 139A
| Austex Software
|-
| 5019
| 139B
| Sören Gust
|-
| 5020
| 139C
| Rok Krajnc
|-
| 5030
| 13A6
| Tim Tashpulatov
|-
| 5040
| 13B0
| 7-bit
|-
| 5050
| 13BA
| Sakura IT
|-
| 5060
| 13C4
| FPGAArcade
|-
| 5070
| 13CE
| CancerSoft Inc.
|-
| 5080
| 13D8
| Stephen Leary
|-
| 5090
| 13E2
| DMA Softlab LLC
|-
| 5100
| 13EC
| Brookhouse Engineering
|-
| 5110
| 13F6
| Eduardo Arana
|-
| 5120
| 1400
| CS-LAB
|-
| 5130
| 140A
| Robert Miranda
|-
| 5140
| 1414
| RastPort
|-
| 5132
| 140C
| UAS Interface Ltd6
|-
| 5150
| 141E
| Amiga Kit
|-
| 5160
| 1428
| Central Texas Commodore User Group
|-
| 5170
| 1432
| Confusion Research Center
|-
| 5180
| 143C
| Solar Soyuz Zaibatsu
|-
| 5190
| 1446
| BooBip
|-
| 5191
| 1447
| Matthias Hampel
|-
| 5192
| 1448
| dec0de Consulting Ltd.
|-
| 5193
| 1449
| Puppy Concepts
|-
| 5194
| 144A
| Open Amiga Hardware Repository
|-
| 5195
| 144B
| Double H Tech
|-
| 5196
| 144C
| Retromatik
|-
| 5500
| 157C
| Inhouse Information
|-
| 5768
| 1688
| Bio Con
|-
| 6148
| 1804
| HK-Computer
|-
| 6502
| 1966
| Cloanto
|-
| 6520
| 1978
| Oliver Gantert
|-
| 7777
| 1E61
| Rafal Gabriel Chyla
|-
| 8215
| 2017
| Vortex
|-
| 8244
| 2034
| Spirit Technology
|-
| 8290
| 2062
| Expansion Systems
|-
| 8448
| 2100
| ReadySoft
|-
| 8512
| 2140
| Phase 5 Digital Products
|-
| 8553
| 2169
| Digital Processing Systems Inc.
|-
| 8704
| 2200
| ACT Elektronik
|-
| 8738
| 2222
| ACT Elektronik
|-
| 9512
| 2528
| Tower Technologies
|-
| 10676
| 29B4
| Electronic Design
|-
| 14195
| 3773
| Media-net-Point
|-
| 14501
| 38A5
| Petsoff, Finland
|-
| 16375
| 3FF7
| Uwe Gerlach
|-
| 16707
| 4143
| Ateo Concepts
|-
| 16708
| 4144
| ALiENDESiGN
|-
| 16945
| 4231
| A.C.T.
|-
| 17740
| 454C
| HK-Computer (ELSAT)
|-
| 18260
| 4754
| MacroSystems (Germany)
|-
| 19796
| 4D54
| Markt & Technik
|-
| 20480
| 5000
| François Lacombe
|-
| 22359
| 5757
| Markt & Technik
|-
| 26464
| 6760
| Combitec
|-
| 26470
| 6766
| Combitec
|-
| 28014
| 6D6E
| MNT Media and Technology UG
|-
| 32768
| 8000
| M.A.S.T.
|-
| 42240
| A500
| Aethreum Digital
|-
| 43437
| A9AD
| Reis-Ware
|-
| 43521
| AA01
| Cameron
|-
| 43537
| AA11
| Reis-Ware
|-
| 44359
| AD47
| Matay
|-
| 46504
| B5A8
| Phoenix
|-
| 48879
| BEEF
| Swiss Mountain Dog Products
|-
| 49160
| C008
| Combitec
|-
| 61453
| F00D
| Forefront Technologies Inc.
|}

For any changes/additions to this registry see [[#How_to_Obtain_a_Manufacturer_Number|How to Obtain a Manufacturer Number]]

Amiga Hardware Manufacturer ID Registry

2026-09-08T11:09:43Z

Costel Mincea: /* Registry */

__TOC__

= How to Obtain a Manufacturer Number =

Manufacturer's numbers are assigned by the AmigaOS development team. To obtain your unique manufacturer number send a support request to [mailto:support@hyperion-entertainment.com support@hyperion-entertainment.com] including these information:

1. The name of the company or person which the number is assigned to

2. Postal address/contact address

3. Name of the contact person, with a corresponding e-mail address

4. A brief description of the kind of products you want to produce

= Your Manufacturer Number =

Attention hardware manufacturers. If you are developing a hardware expansion product for the Classic Amiga (e.g. 500, 2000, 3000) then you will need to obtain a special manufacturer ID number from the AmigaOS development team to identify your product. This manufacturer number is used by the Amiga to link your hardware with its driver software at boot time.

Your manufacturer number is part of the special protocol that the Amiga uses to automatically configure all expansion devices on the bus without the user having to cut jumpers or adjust dip switches. This is called auto-config.

At start-up time, the system first polls each board in the system and assigns the board its own address space. If it is a memory board, its RAM is linked into the memory free pool. Later in the boot sequence, after DOS is initialized, the binddrivers program is run. Binddrivers will search the directory SYS:Expansion for the drivers that go with the boards.

To do this binddrivers looks in the Tool Type field of all icon files in SYS:Expansion. If the first seven bytes of the Tool Type field are "PRODUCT", then this is an icon file for a driver.

Binddrivers will then attempt to match the drivers it has found with the boards that were found earlier. This is where your manufacturer number comes in.

Your manufacturer number goes in two places. First, it is burned in hex form into the PAL which is part of ALL auto-config expansion products. Second, it appears in ASCII in the Tool Type field of the icon file for your product's driver. By matching these two numbers, the Amiga can automatically configure your board and bind it's software driver into the system as well.

The manufacturer's number is a 16-bit ID which appears in PAL offsets $10-$17. There is also an 8-bit product number which you assign. The product number is for uniquely identifying different products from the same vendor. The product number will appear in PAL offsets $04-$07. This gives you a total of 24 bits to identify each of your products.

These 24 bits of information in the PAL which identify your product are matched against the information in the Tool Type field of all icon files in the SYS:Expansion drawer. For example, suppose you are manufacturer #1019. You have two products, #1 and #2 which both use the same driver. The icon for your driver for these two products would have a Tool Type set to "PRODUCT=1019/1|1019/2". This means: I am an icon for a driver that works with product number 1 or 2 from manufacturer 1019, now bind me. Spaces are not legal. Here are two other examples:

; PRODUCT=1208/11
: is the Tool Type for a driver for product 11 from manufacturer number 1208.

; PRODUCT=1017
: is the Tool Type for a driver for any product from manufacturer number 1017.

For an informal explanation of the auto-configuration process, see the chapter on Software Expansion Architecture from the 2nd Annual Amiga Developer's Conference Notes (available on ADCD 2.1). For the details of timing, power, the PAL equations and PAL address specifications and the expansion library documentation, see sections 3.1 to 3.3 of the A500/A2000 Technical Reference Manual. The original auto-config spec appears in the A1000 Schematics and Expansion Specification.

The auto-config process makes the addition of expansion products to the system very easy. All the user has to do is put the board in any slot and copy the driver from the release disk to his own SYS:Expansion drawer. Everything else is automatic. There are no jumpers or dip switches to set. Best of all, you will get a lot less support calls asking how to make your product work with the XYZ-Corp-battery-backed-clock.

= Notes =

Some notes on hardware manufacturer ID assignment.

* Manufacturer ID numbers are assigned free of charge.
* Please provide the following information when requesting an ID:
*# Name of the company or person
*# Postal address/contact address
*# Name of the contact person, with a corresponding e-mail address
*# A brief description of the kind of products you want to produce
* All ID numbers smaller than 5000 must be considered unsafe because no information exists on which numbers exactly were taken during the time Commodore, Inc. disintegrated.
* ID numbers in the range 8192 to 18841 must be considered unsafe because some hardware developers mistook the numbers assigned to them to be given in hexadecimal format. Hence 0x2000 = 8192 and 0x4999 = 18841.

= Example code =

<syntaxhighlight lang="C" line>
/*-----------------------------------------------*/
/* Here is a short program which will tell you */
/* about the expansion boards configured in your */
/* system without you opening up the machine. */
/* Code by Bill Koester of CATS */
/*-----------------------------------------------*/
#include <libraries/configvars.h>
#include <libraries/expansion.h>

struct ExpansionBase *ExpansionBase;

void cleanup();
void printdev();

int main()
{
struct ConfigDev *MyConfigDev;

/*----------------------------------*/
/* Open the expansion library, */
/* if there is a problem then exit */
/*----------------------------------*/

ExpansionBase =(struct ExpansionBase *) OpenLibrary(EXPANSIONNAME,0);
if(ExpansionBase==NULL)
{
printf("Error opening expansion library!!\n");
cleanup();
exit(0);
}

/*--------------------------------------------*/
/* Use FindConfigDev to get info on the first */
/* expansion board on the list maintained by */
/* Exec. If there are no expansion boards in */
/* the system then exit. */
/*--------------------------------------------*/

MyConfigDev = NULL;

/*--------------------------------------------------*/
/* FindConfigDev(oldConfigDev,manufacturer,product) */
/* oldConfigDev = NULL for the top of the list */
/* manufacturer = -1 for any manufacturer */
/* product = -1 for any product */
/*--------------------------------------------------*/

MyConfigDev = FindConfigDev(NULL,-1,-1);

if(MyConfigDev==NULL)
{
printf("No Configured Devices found!!\n");
cleanup();
exit(0);
}

printdev(MyConfigDev);

/*-----------------------------------*/
/* OK, there is at least one board, */
/* so loop and get the entire list */
/* printing as we go with printdev() */
/*-----------------------------------*/

while(MyConfigDev = FindConfigDev(MyConfigDev,-1,-1))
{
printdev(MyConfigDev);
}
cleanup();
return 0;
}

/*-------------------*/
/* Close up shop... */
/*-------------------*/
void cleanup()
{
if(ExpansionBase)
CloseLibrary(ExpansionBase);
}

/*----------------------------------*/
/* Print out the contents of the */
/* dev structure for this expansion */
/* product. */
/*----------------------------------*/

void printdev(dev)
struct ConfigDev *dev;
{
char buff[200];

printf("Flags = ");
if(dev->cd_Flags==NULL)
printf("NULL ");
if(dev->cd_Flags&CDF_SHUTUP)
printf("CDF_SHUTUP ");
if(dev->cd_Flags&CDF_CONFIGME)
printf("CDF_CONFIGME ");
printf("\n");
printf("Board Address = %x\n",dev->cd_BoardAddr);
printf("Board Size = %d bytes\n",dev->cd_BoardSize);
printf("Slot Address = %d\n",dev->cd_SlotAddr);
printf("Slot Size = %d\n",dev->cd_SlotSize);
printf("Driver code at %x\n",dev->cd_Driver);

printf("er_Type = %x\n",dev->cd_Rom.er_Type);
printf("er_Product = %x\n",dev->cd_Rom.er_Product);
printf("er_Flags = %x\n",dev->cd_Rom.er_Flags);
printf("er_Reserved03 = %x\n",dev->cd_Rom.er_Reserved03);
printf("er_Manufacturer = %x\n",dev->cd_Rom.er_Manufacturer);
printf("er_SerialNumber = %x\n",dev->cd_Rom.er_SerialNumber);
printf("er_InitDiagVec = %x\n",dev->cd_Rom.er_InitDiagVec);
printf("er_Reserved0c = %x\n",dev->cd_Rom.er_Reserved0c);
printf("er_Reserved0d = %x\n",dev->cd_Rom.er_Reserved0d);
printf("er_Reserved0e = %x\n",dev->cd_Rom.er_Reserved0e);
printf("er_Reserved0f = %x\n",dev->cd_Rom.er_Reserved0f);

printf("Hit Return to continue:\n");
gets(buff);
}
</syntaxhighlight>

= Registry =

{| class="wikitable"
! ID (decimal)
! ID (hexadecimal)
! Manufacturer
! Notes
|-
| 1
| 0001
| Micronik
|-
| 211
| 00D3
| Pacific Peripherals/Profex
|-
| 221
| 00DD
| Kupke Computertechnik GmbH
|-
| 256
| 0100
| Memphis
| Originally registered to MacroSystems US
|-
| 512
| 0200
| 3-State Computertechnik
|-
| 513
| 0201
| Commodore (Braunschweig)
|-
| 514
| 0202
| Commodore (West Chester)
|-
| 515
| 0203
| Commodore (West Chester)
| Originally registered to Combitech/Macrosystem
|-
| 756
| 02F4
| Progressive Peripherals & Software
|-
| 767
| 02FF
| Kolff Computer Supplies
|-
| 1001
| 03E9
| Tecmar
|-
| 1002
| 03EA
| Telesys
|-
| 1003
| 03EB
| The Micro-Forge
|-
| 1004
| 03EC
| Kronos/C Ltd.
| Originally registered to Card Co. (Supra)
|-
| 1005
| 03ED
| A-Squared
|-
| 1006
| 03EE
| Comspec Communications
|-
| 1007
| 03EF
| HT Electronics
|-
| 1008
| 03F0
| RDS Software
|-
| 1009
| 03F1
| Anakin Research
|-
| 1010
| 03F2
| MicroBotics
|-
| 1011
| 03F3
| Bob Krauth
|-
| 1012
| 03F4
| Access Associates (Alegra)
|-
| 1013
| 03F5
| Mini Comp Systems Ltd.
|-
| 1014
| 03F6
| Cypress Technology
|-
| 1015
| 03F7
| Fuller Computers
|-
| 1016
| 03F8
| Galaxy Computers
|-
| 1017
| 03F9
| ADA Research
|-
| 1018
| 03FA
| Computer Service Italia
|-
| 1019
| 03FB
| Amigo
|-
| 1020
| 03FC
| Micro-Solutions Inc.
|-
| 1021
| 03FD
| Stacar International
|-
| 1022
| 03FE
| Video Precisions
|-
| 1023
| 03FF
| ASDG, Inc.
|-
| 1025
| 0401
| Ing. Buero Kalawsky
|-
| 1026
| 0402
| Computer Tuning
|-
| 1027
| 0403
| Interplan Unternehmensberatung
|-
| 1028
| 0404
| Imtronics/Memphis
| Originally registered to Peter Ohlich
|-
| 1030
| 0406
| Commodore (Lowell University)
| Originally registered to Productivity Center
|-
| 1041
| 0411
| Design Labs
|-
| 1042
| 0412
| MCS
|-
| 1043
| 0413
| B. J. Freeman
|-
| 1044
| 0414
| Side Effects Inc.
|-
| 1045
| 0415
| Oklahoma Personal Comp.
|-
| 1046
| 0416
| Advanced Micro Innovations
|-
| 1047
| 0417
| Industrial Support Services
|-
| 1048
| 0418
| Technisoft
|-
| 1049
| 0419
| Prolific, Inc.
|-
| 1050
| 041A
| Softeam, Inc.
|-
| 1051
| 041B
| GRC Electronics
|-
| 1052
| 041C
| David Lai
|-
| 1053
| 041D
| Ameristar Technologies
|-
| 1054
| 041E
| Cline Refrigeration
|-
| 1055
| 041F
| Cardiac Pacemakers, Inc.
|-
| 1056
| 0420
| Supra Corp. (Creative Microsystems)
|-
| 1057
| 0421
| Wayne Diener
|-
| 1058
| 0422
| Computer Systems Associates (CSA)
|-
| 1059
| 0423
| Trionix, Inc.
|-
| 1060
| 0424
| David Lucas
|-
| 1061
| 0425
| Analog Precision
| Also assigned to D & L Distributing
|-
| 1267
| 04F3
| RBM Digitaltechnik
|-
| 1282
| 0502
| M-TEC Hardware Design
|-
| 1337
| 0539
| Thomas Stenzel (DaFR34K)
|-
| 1576
| 0628
| Boris Križma
|-
| 1729
| 06C1
| Thomas Richter / OpenPCI-A1200 Mediator bridge
|-
| 1730
| 06C2
| Thomas Richter / OpenPCI-A4000 Mediator bridge
|-
| 1731
| 06C3
| Thomas Richter / OpenPCI-Prometheus bridge (Firestorm or original)
|-
| 1732
| 06C4
| Thomas Richter / OpenPCI-Reserved1
|-
| 1733
| 06C5
| Thomas Richter / OpenPCI-Grex bridge (both A1200 and A4000)
|-
| 1734
| 06C6
| Thomas Richter / OpenPCI-Reserved2
|-
| 1735
| 06C7
| Thomas Richter / OpenPCI-Reserved3
|-
| 1736
| 06C8
| Thomas Richter / OpenPCI-Reserved4
|-
| 1737
| 06C9
| Thomas Richter / OpenPCI-Reserved5
|-
| 1738
| 06CA
| Thomas Richter / OpenPCI-Reserved6
|-
| 1739
| 06CB
| Thomas Richter / OpenPCI-Reserved7
|-
| 1740
| 06CC
| Thomas Richter / OpenPCI-Reserved8
|-
| 1741
| 06CD
| Thomas Richter / OpenPCI-Reserved9
|-
| 1742
| 06CE
| Thomas Richter / OpenPCI-Reserved10
|-
| 1743
| 06CF
| Thomas Richter / OpenPCI-Reserved11
|-
| 1744
| 06D0
| Thomas Richter / OpenPCI-Reserved12
|-
| 1761
| 06E1
| Great Valley Products
|-
| 1803
| 070B
| UAE Amiga Emulator
|-
| 2002
| 07D2
| Mimetics Corp.
|-
| 2003
| 07D3
| ACDA
|-
| 2004
| 07D4
| Finn R. Jacobsen
|-
| 2005
| 07D5
| Elthen Electronics
|-
| 2006
| 07D6
| Nine Tiles Computer Systems Ltd.
|-
| 2007
| 07D7
| Analog Electronics
|-
| 2008
| 07D8
| Bell & Howell
|-
| 2009
| 07D9
| Roland Kochler
|-
| 2010
| 07DA
| Byte Corp.
|-
| 2011
| 07DB
| Reserved
|-
| 2012
| 07DC
| DKB, Inc.
| Previously named Michigan Software
|-
| 2013
| 07DD
| Pacific Peripherals
|-
| 2014
| 07DE
| Sysaphus Software
|-
| 2015
| 07DF
| Digitronics
|-
| 2016
| 07E0
| Akron Systems
|-
| 2017
| 07E1
| Great Valley Products
|-
| 2018
| 07E2
| Calmos
|-
| 2019
| 07E3
| Dover Research
|-
| 2020
| 07E4
| David Krehbiel
|-
| 2021
| 07E5
| Synergy Peripheral Systems
| Also known as California Access
|-
| 2022
| 07E6
| Xetec
|-
| 2023
| 07E7
| Micron Technology
|-
| 2024
| 07E8
| CH Electronics
|-
| 2025
| 07E9
| American Liquid Light
|-
| 2026
| 07EA
| Progressive Peripherals & Software
| Also used by Ateo
|-
| 2027
| 07EB
| Wicat Systems
|-
| 2028
| 07EC
| Applied Systems & Peripherals
|-
| 2029
| 07ED
| Delaware Valley Software
|-
| 2030
| 07EE
| Palomax
|-
| 2031
| 07EF
| Incognito Software
|-
| 2032
| 07F0
| Jadesign
|-
| 2033
| 07F1
| BVR
|-
| 2034
| 07F2
| Spirit Technology
|-
| 2035
| 07F3
| Spirit Technology
|-
| 2036
| 07F4
| Atronic
|-
| 2037
| 07F5
| Scott Karlin
|-
| 2038
| 07F6
| Howitch
|-
| 2039
| 07F7
| Sullivan Brothers Visual Engineers
|-
| 2040
| 07F8
| G I T
|-
| 2041
| 07F9
| Amigo Business Computers
|-
| 2042
| 07FA
| Micro E Ab
|-
| 2043
| 07FB
| Ralph Kruse
|-
| 2044
| 07FC
| Clearpoint Research
|-
| 2045
| 07FD
| Kodiak
|-
| 2046
| 07FE
| BSC
| Originally registered to Phoenix Electronics
|-
| 2047
| 07FF
| No Name Shown
|-
| 2048
| 0800
| Commodore Braunschweig
|-
| 2049
| 0801
| BSC
| Originally registered to Elaborate Bytes
|-
| 2050
| 0802
| Kronos/C Ltd.
|-
| 2051
| 0803
| Spartanics
|-
| 2052
| 0804
| Jochheim Computer Tuning
|-
| 2053
| 0805
| Trans Data Systems
|-
| 2054
| 0806
| Applied Systems & Peripherals Ltd.
|-
| 2055
| 0807
| Checkpoint Technologies
| Originally registered to Amiga Solutions
|-
| 2056
| 0808
| Adept Development
|-
| 2057
| 0809
| Advanced Computer Design
|-
| 2058
| 080A
| Sir Netics
|-
| 2059
| 080B
| Expert Services
|-
| 2060
| 080C
| Digital Art Systems
|-
| 2061
| 080D
| Adept Development
|-
| 2062
| 080E
| Expansion Technologies (Expansion Systems)
|-
| 2063
| 080F
| Alphatech
|-
| 2064
| 0810
| Edotronik GmbH
|-
| 2065
| 0811
| California Access/Synergy
| Originally registered to Logical Design Works
|-
| 2066
| 0812
| Bowden, Williams, Full & Assoc.
|-
| 2067
| 0813
| NES, Inc.
|-
| 2068
| 0814
| Amdev
|-
| 2069
| 0815
| Big Brother Security Systems
|-
| 2070
| 0816
| Active Circuits Inc.
|-
| 2071
| 0817
| ICD, Inc.
|-
| 2072
| 0818
| Multi-Meg Electronique
|-
| 2073
| 0819
| Kupke Computertechnik GmbH
|-
| 2074
| 081A
| The Checkered Ball
|-
| 2075
| 081B
| Hi Tension Computer Services Ltd. (UK)
|-
| 2076
| 081C
| Alfa Data
| Originally assigned to Elmtech Research, Ltd. (UK)
|-
| 2077
| 081D
| Great Valley Products
| Originally registered to Clartscreen, Ltd. (UK)
|-
| 2078
| 081E
| Interworks
|-
| 2079
| 081F
| Galysh Enterprises
|-
| 2080
| 0820
| Hardital Synthesis
| Originally registered to Realtime Games Software Ltd.
|-
| 2081
| 0821
| GBS
|-
| 2082
| 0822
| Circum Design Inc.
|-
| 2083
| 0823
| Alberta Micro Electronic Center
|-
| 2084
| 0824
| Bestech
|-
| 2085
| 0825
| Lasar Fantasy
|-
| 2086
| 0826
| Pulsar
|-
| 2087
| 0827
| Ivis
|-
| 2088
| 0828
| Applied Engineering
|-
| 2089
| 0829
| Solid-State Design & Development
|-
| 2090
| 082A
| Vison Quest
|-
| 2091
| 082B
| Seaview Software
|-
| 2092
| 082C
| BSC
| Mistakenly used by ADS (Advanced Development Software)
|-
| 2093
| 082D
| Bernd Culenfeld
|-
| 2094
| 082E
| American Liquid Light
|-
| 2095
| 082F
| CEGITES
|-
| 2096
| 0830
| Quadlite Computers Ltd.
| Originally registered to EV Industries
|-
| 2097
| 0831
| Silicon Peace
|-
| 2098
| 0832
| Black Belt Systems
|-
| 2099
| 0833
| Village Tronic
| Originally registerd to Steve Yaeger
|-
| 2100
| 0834
| ReadySoft
|-
| 2101
| 0835
| Phoenix Micro Technologies
|-
| 2102
| 0836
| Advanced Systems & Software
| Orignally assigned to Preferred Technology
|-
| 2103
| 0837
| Rombo Productions
|-
| 2104
| 0838
| Impulse Inc.
|-
| 2105
| 0839
| Beta Unlimited
|-
| 2106
| 083A
| Memory Expansion System, Ltd.
|-
| 2107
| 083B
| Vortex Computer Systems GmbH
|-
| 2108
| 083C
| Platypus Systems
|-
| 2109
| 083D
| Gigatron OHG
|-
| 2110
| 083E
| PG Electronics
|-
| 2111
| 083F
| New Technologies Group
|-
| 2112
| 0840
| Interactive Video Systems (IVS)
| Pacific Peripherals
|-
| 2113
| 0841
| Vector
| Originally registered to H. K. Computer
|-
| 2114
| 0842
| Pacific Digital
| Originally registered to C. H. Helfrich Elektronik
|-
| 2115
| 0843
| Xanadu
|-
| 2116
| 0844
| Pacific Digital
| Originally registered to AMS
|-
| 2117
| 0845
| X-Pert
|-
| 2118
| 0846
| The Amiga Centre
|-
| 2119
| 0847
| Digital Pacific
|-
| 2120
| 0848
| Solid State Leisure
|-
| 2121
| 0849
| Hydra Systems
| Originally registered to Analog Electronics
|-
| 2122
| 084A
| Cumana
|-
| 2123
| 084B
| KAPS 2C Conception
|-
| 2124
| 084C
| Mike Mason
|-
| 2125
| 084D
| For Your Eyes
|-
| 2126
| 084E
| Volkmar Breitfeld Computersysteme
|-
| 2127
| 084F
| Sunrize Industries
|-
| 2128
| 0850
| Scott Advanced Micro Designs
|-
| 2129
| 0851
| Digital Micronics
|-
| 2130
| 0852
| Alfa-Laval
|-
| 2131
| 0853
| Multigros A/S
|-
| 2132
| 0854
| Archos
|-
| 2133
| 0855
| Icom Simulations
|-
| 2134
| 0856
| Commodore Test Engineering Group
|-
| 2135
| 0857
| Microcreations
|-
| 2136
| 0858
| Shoestring Productions
|-
| 2137
| 0859
| Faberushi
|-
| 2138
| 085A
| Evesham Micro Ltd.
|-
| 2139
| 085B
| Panagolin Laser Software
|-
| 2140
| 085C
| Thomas Rudloff
|-
| 2141
| 085D
| Daniel Hohabir
|-
| 2142
| 085E
| GfxBase, Inc.
|-
| 2143
| 085F
| Axellabs
|-
| 2144
| 0860
| Roctec Electronics Inc.
|-
| 2145
| 0861
| Omega Datentechnik
|-
| 2146
| 0862
| Atlantis
|-
| 2147
| 0863
| Skytec Computers
|-
| 2148
| 0864
| Protar Electronics
|-
| 2149
| 0865
| ACS
|-
| 2150
| 0866
| Software Results Enterprises
| Originally registered to University of Illinois
|-
| 2151
| 0867
| Infinity Systems Design Group
|-
| 2152
| 0868
| Trade It
|-
| 2153
| 0869
| Suntec, Inc.
|-
| 2154
| 086A
| DJW Micro Systems
| Originally registered to Tritec Marketing
|-
| 2155
| 086B
| Power Computing Ltd.
|-
| 2156
| 086C
| MacroSystems
|-
| 2157
| 086D
| Masoboshi GmbH (DCE)
|-
| 2158
| 086E
| HAL Software Hardware Handel
|-
| 2159
| 086F
| Mainhattan Data
| Originally registered to Michael Lamm Computersysteme
|-
| 2160
| 0870
| Digital Processing System
| Originally registered to bbdp Electronics
|-
| 2161
| 0871
| Blue Ribbon Soundworks
| Originally registered to Design Computer Systems
|-
| 2162
| 0872
| XPert
| Originally registered to The Station
|-
| 2163
| 0873
| DelaComp
| Originally registered to Bryan Williams
|-
| 2164
| 0874
| Superformance Computer Engineering GmbH
|-
| 2165
| 0875
| Overland Engineering
|-
| 2166
| 0876
| Thomas Hamren
|-
| 2167
| 0877
| Village Tronic
|-
| 2168
| 0878
| Toolbox Design
|-
| 2169
| 0879
| Digital Processing System
|-
| 2170
| 087A
| Superformance
|-
| 2171
| 087B
| Utilities Unlimited
|-
| 2172
| 087C
| phase 5
|-
| 2173
| 087D
| Juergen Kommos
|-
| 2174
| 087E
| Electronic Design
|-
| 2175
| 087F
| James Cook University of North Queensland
|-
| 2176
| 0880
| AmiTrix Development
|-
| 2177
| 0881
| Ferranti
|-
| 2178
| 0882
| Leviathan Development
|-
| 2179
| 0883
| United Video Inc.
|-
| 2180
| 0884
| GPSoft Pty. Ltd.
| Originally registered to Juergen Kommos
|-
| 2181
| 0885
| ArMAX
| Oliver Bausch
|-
| 2182
| 0886
| CP Computer
|-
| 2183
| 0887
| AMOK - Amiga Module & Oberon Klub
|-
| 2184
| 0888
| ITEK Neser & Sieber GbR
|-
| 2185
| 0889
| Phillip C. Lello
|-
| 2186
| 088A
| Cyborg Design Services
|-
| 2187
| 088B
| G2 Systems
|-
| 2188
| 088C
| Pro System Computersysteme
|-
| 2189
| 088D
| ZEUS Electronic
| Originally registered to MSPI (Markt & Technik)
|-
| 2190
| 088E
| Altatech
|-
| 2191
| 088F
| NewTek
|-
| 2192
| 0890
| M-TEC Hardware Design
| Originally registered to Hardware Design Udo Neuroth
|-
| 2193
| 0891
| Great Valley Products
| Originally registered to Viona Development
|-
| 2194
| 0892
| Amitek
| Originally assigned to Marpet Developments
|-
| 2195
| 0893
| Ingenieurbuero Helfrich
|-
| 2196
| 0894
| The Neo Group
|-
| 2197
| 0895
| Cyon
|-
| 2198
| 0896
| Bob Research Group
|-
| 2199
| 0897
| Richmond Sound Design Ltd.
|-
| 2200
| 0898
| US Cybernetics
|-
| 2201
| 0899
| Fulvio Ieva
|-
| 2202
| 089A
| Silicon Studio
|-
| 2203
| 089B
| MacroSystems (USA)
| Was named Micro System Devices
|-
| 2204
| 089C
| Conspector Entertainment
|-
| 2205
| 089D
| Laserforum
|-
| 2206
| 089E
| Elbox Computer
| Mistakenly used by Index Information Ltd.
|-
| 2207
| 089F
| Applied Magic Inc.
|-
| 2208
| 08A0
| SDL Ltd.
|-
| 2560
| 0A00
| Harms
|-
| 2588
| 0A1C
| A1K.org Community
|-
| 2640
| 0A50
| Micronik
|-
| 2782
| 2782
| OA Design
|-
| 3084
| 0C0C
| Team 4
|-
| 3643
| 0E3B
| E3B
| Michael Boehmer
|-
| 3855
| 0F0F
| Micronik
|-
| 4096
| 1000
| MegaMicro
|-
| 4110
| 100E
| DigiFeX
|-
| 4136
| 1028
| Imtronics/Memphis
|-
| 4149
| 1035
| PROTAR
|-
| 4369
| 1111
| Frank Strauß Elektronik
| Also used by Kupke
|-
| 4626
| 1212
| Individual Computers
|-
| 4648
| 1228
| Flesch Hornemann Computer Elec.
|-
| 4680
| 1248
| Kupke Computertechnik GmbH
|-
| 4711
| 1267
| RBM digitaltechnik
|-
| 4754
| 1292
| MacroSystems
|-
| 5000
| 1388
| ITH
|-
| 5001
| 1389
| VMC
|-
| 5010
| 1392
| Ambience Creation Technology
|-
| 5011
| 1393
| Creative Development
|-
| 5012
| 1394
| Georg Braun
|-
| 5013
| 1395
| Swedish User Group of Amiga
|-
| 5014
| 1396
| Jakub Bednarski
|-
| 5015
| 1397
| KryoFlux, Ltd.
|-
| 5016
| 1398
| Igor Majstorovic
|-
| 5017
| 1399
| Alastair M. Robinson
|-
| 5018
| 139A
| Austex Software
|-
| 5019
| 139B
| Sören Gust
|-
| 5020
| 139C
| Rok Krajnc
|-
| 5030
| 13A6
| Tim Tashpulatov
|-
| 5040
| 13B0
| 7-bit
|-
| 5050
| 13BA
| Sakura IT
|-
| 5060
| 13C4
| FPGAArcade
|-
| 5070
| 13CE
| CancerSoft Inc.
|-
| 5080
| 13D8
| Stephen Leary
|-
| 5090
| 13E2
| DMA Softlab LLC
|-
| 5100
| 13EC
| Brookhouse Engineering
|-
| 5110
| 13F6
| Eduardo Arana
|-
| 5120
| 1400
| CS-LAB
|-
| 5130
| 140A
| Robert Miranda
|-
| 5140
| 1414
| RastPort
|-
| 5132
| 140C
| UAS Interface Ltd6
|-
| 5150
| 141E
| Amiga Kit
|-
| 5160
| 1428
| Central Texas Commodore User Group
|-
| 5170
| 1432
| Confusion Research Center
|-
| 5180
| 143C
| Solar Soyuz Zaibatsu
|-
| 5190
| 1446
| BooBip
|-
| 5191
| 1447
| Matthias Hampel
|-
| 5192
| 1448
| dec0de Consulting Ltd.
|-
| 5193
| 1449
| Puppy Concepts
|-
| 5194
| 144A
| Open Amiga Hardware Repository
|-
| 5195
| 144B
| Double H Tech
|-
| 5196
| 144C
| Retromatik
|-
| 5500
| 157C
| Inhouse Information
|-
| 5768
| 1688
| Bio Con
|-
| 6148
| 1804
| HK-Computer
|-
| 6502
| 1966
| Cloanto
|-
| 6520
| 1978
| Oliver Gantert
|-
| 7777
| 1E61
| Rafal Gabriel Chyla
|-
| 8215
| 2017
| Vortex
|-
| 8244
| 2034
| Spirit Technology
|-
| 8290
| 2062
| Expansion Systems
|-
| 8448
| 2100
| ReadySoft
|-
| 8512
| 2140
| Phase 5 Digital Products
|-
| 8553
| 2169
| Digital Processing Systems Inc.
|-
| 8704
| 2200
| ACT Elektronik
|-
| 8738
| 2222
| ACT Elektronik
|-
| 9512
| 2528
| Tower Technologies
|-
| 10676
| 29B4
| Electronic Design
|-
| 14195
| 3773
| Media-net-Point
|-
| 14501
| 38A5
| Petsoff, Finland
|-
| 16375
| 3FF7
| Uwe Gerlach
|-
| 16707
| 4143
| Ateo Concepts
|-
| 16708
| 4144
| ALiENDESiGN
|-
| 16945
| 4231
| A.C.T.
|-
| 17740
| 454C
| HK-Computer (ELSAT)
|-
| 18260
| 4754
| MacroSystems (Germany)
|-
| 19796
| 4D54
| Markt & Technik
|-
| 22359
| 5757
| Markt & Technik
|-
| 26464
| 6760
| Combitec
|-
| 26470
| 6766
| Combitec
|-
| 28014
| 6D6E
| MNT Media and Technology UG
|-
| 32768
| 8000
| M.A.S.T.
|-
| 42240
| A500
| Aethreum Digital
|-
| 43437
| A9AD
| Reis-Ware
|-
| 43521
| AA01
| Cameron
|-
| 43537
| AA11
| Reis-Ware
|-
| 44359
| AD47
| Matay
|-
| 46504
| B5A8
| Phoenix
|-
| 48879
| BEEF
| Swiss Mountain Dog Products
|-
| 49160
| C008
| Combitec
|-
| 61453
| F00D
| Forefront Technologies Inc.
|}

For any changes/additions to this registry see [[#How_to_Obtain_a_Manufacturer_Number|How to Obtain a Manufacturer Number]]

Amiga Hardware Manufacturer ID Registry

2026-09-08T11:08:52Z

Costel Mincea: Added 2782 Oliver Achten

__TOC__

= How to Obtain a Manufacturer Number =

Manufacturer's numbers are assigned by the AmigaOS development team. To obtain your unique manufacturer number send a support request to [mailto:support@hyperion-entertainment.com support@hyperion-entertainment.com] including these information:

1. The name of the company or person which the number is assigned to

2. Postal address/contact address

3. Name of the contact person, with a corresponding e-mail address

4. A brief description of the kind of products you want to produce

= Your Manufacturer Number =

Attention hardware manufacturers. If you are developing a hardware expansion product for the Classic Amiga (e.g. 500, 2000, 3000) then you will need to obtain a special manufacturer ID number from the AmigaOS development team to identify your product. This manufacturer number is used by the Amiga to link your hardware with its driver software at boot time.

Your manufacturer number is part of the special protocol that the Amiga uses to automatically configure all expansion devices on the bus without the user having to cut jumpers or adjust dip switches. This is called auto-config.

At start-up time, the system first polls each board in the system and assigns the board its own address space. If it is a memory board, its RAM is linked into the memory free pool. Later in the boot sequence, after DOS is initialized, the binddrivers program is run. Binddrivers will search the directory SYS:Expansion for the drivers that go with the boards.

To do this binddrivers looks in the Tool Type field of all icon files in SYS:Expansion. If the first seven bytes of the Tool Type field are "PRODUCT", then this is an icon file for a driver.

Binddrivers will then attempt to match the drivers it has found with the boards that were found earlier. This is where your manufacturer number comes in.

Your manufacturer number goes in two places. First, it is burned in hex form into the PAL which is part of ALL auto-config expansion products. Second, it appears in ASCII in the Tool Type field of the icon file for your product's driver. By matching these two numbers, the Amiga can automatically configure your board and bind it's software driver into the system as well.

The manufacturer's number is a 16-bit ID which appears in PAL offsets $10-$17. There is also an 8-bit product number which you assign. The product number is for uniquely identifying different products from the same vendor. The product number will appear in PAL offsets $04-$07. This gives you a total of 24 bits to identify each of your products.

These 24 bits of information in the PAL which identify your product are matched against the information in the Tool Type field of all icon files in the SYS:Expansion drawer. For example, suppose you are manufacturer #1019. You have two products, #1 and #2 which both use the same driver. The icon for your driver for these two products would have a Tool Type set to "PRODUCT=1019/1|1019/2". This means: I am an icon for a driver that works with product number 1 or 2 from manufacturer 1019, now bind me. Spaces are not legal. Here are two other examples:

; PRODUCT=1208/11
: is the Tool Type for a driver for product 11 from manufacturer number 1208.

; PRODUCT=1017
: is the Tool Type for a driver for any product from manufacturer number 1017.

For an informal explanation of the auto-configuration process, see the chapter on Software Expansion Architecture from the 2nd Annual Amiga Developer's Conference Notes (available on ADCD 2.1). For the details of timing, power, the PAL equations and PAL address specifications and the expansion library documentation, see sections 3.1 to 3.3 of the A500/A2000 Technical Reference Manual. The original auto-config spec appears in the A1000 Schematics and Expansion Specification.

The auto-config process makes the addition of expansion products to the system very easy. All the user has to do is put the board in any slot and copy the driver from the release disk to his own SYS:Expansion drawer. Everything else is automatic. There are no jumpers or dip switches to set. Best of all, you will get a lot less support calls asking how to make your product work with the XYZ-Corp-battery-backed-clock.

= Notes =

Some notes on hardware manufacturer ID assignment.

* Manufacturer ID numbers are assigned free of charge.
* Please provide the following information when requesting an ID:
*# Name of the company or person
*# Postal address/contact address
*# Name of the contact person, with a corresponding e-mail address
*# A brief description of the kind of products you want to produce
* All ID numbers smaller than 5000 must be considered unsafe because no information exists on which numbers exactly were taken during the time Commodore, Inc. disintegrated.
* ID numbers in the range 8192 to 18841 must be considered unsafe because some hardware developers mistook the numbers assigned to them to be given in hexadecimal format. Hence 0x2000 = 8192 and 0x4999 = 18841.

= Example code =

<syntaxhighlight lang="C" line>
/*-----------------------------------------------*/
/* Here is a short program which will tell you */
/* about the expansion boards configured in your */
/* system without you opening up the machine. */
/* Code by Bill Koester of CATS */
/*-----------------------------------------------*/
#include <libraries/configvars.h>
#include <libraries/expansion.h>

struct ExpansionBase *ExpansionBase;

void cleanup();
void printdev();

int main()
{
struct ConfigDev *MyConfigDev;

/*----------------------------------*/
/* Open the expansion library, */
/* if there is a problem then exit */
/*----------------------------------*/

ExpansionBase =(struct ExpansionBase *) OpenLibrary(EXPANSIONNAME,0);
if(ExpansionBase==NULL)
{
printf("Error opening expansion library!!\n");
cleanup();
exit(0);
}

/*--------------------------------------------*/
/* Use FindConfigDev to get info on the first */
/* expansion board on the list maintained by */
/* Exec. If there are no expansion boards in */
/* the system then exit. */
/*--------------------------------------------*/

MyConfigDev = NULL;

/*--------------------------------------------------*/
/* FindConfigDev(oldConfigDev,manufacturer,product) */
/* oldConfigDev = NULL for the top of the list */
/* manufacturer = -1 for any manufacturer */
/* product = -1 for any product */
/*--------------------------------------------------*/

MyConfigDev = FindConfigDev(NULL,-1,-1);

if(MyConfigDev==NULL)
{
printf("No Configured Devices found!!\n");
cleanup();
exit(0);
}

printdev(MyConfigDev);

/*-----------------------------------*/
/* OK, there is at least one board, */
/* so loop and get the entire list */
/* printing as we go with printdev() */
/*-----------------------------------*/

while(MyConfigDev = FindConfigDev(MyConfigDev,-1,-1))
{
printdev(MyConfigDev);
}
cleanup();
return 0;
}

/*-------------------*/
/* Close up shop... */
/*-------------------*/
void cleanup()
{
if(ExpansionBase)
CloseLibrary(ExpansionBase);
}

/*----------------------------------*/
/* Print out the contents of the */
/* dev structure for this expansion */
/* product. */
/*----------------------------------*/

void printdev(dev)
struct ConfigDev *dev;
{
char buff[200];

printf("Flags = ");
if(dev->cd_Flags==NULL)
printf("NULL ");
if(dev->cd_Flags&CDF_SHUTUP)
printf("CDF_SHUTUP ");
if(dev->cd_Flags&CDF_CONFIGME)
printf("CDF_CONFIGME ");
printf("\n");
printf("Board Address = %x\n",dev->cd_BoardAddr);
printf("Board Size = %d bytes\n",dev->cd_BoardSize);
printf("Slot Address = %d\n",dev->cd_SlotAddr);
printf("Slot Size = %d\n",dev->cd_SlotSize);
printf("Driver code at %x\n",dev->cd_Driver);

printf("er_Type = %x\n",dev->cd_Rom.er_Type);
printf("er_Product = %x\n",dev->cd_Rom.er_Product);
printf("er_Flags = %x\n",dev->cd_Rom.er_Flags);
printf("er_Reserved03 = %x\n",dev->cd_Rom.er_Reserved03);
printf("er_Manufacturer = %x\n",dev->cd_Rom.er_Manufacturer);
printf("er_SerialNumber = %x\n",dev->cd_Rom.er_SerialNumber);
printf("er_InitDiagVec = %x\n",dev->cd_Rom.er_InitDiagVec);
printf("er_Reserved0c = %x\n",dev->cd_Rom.er_Reserved0c);
printf("er_Reserved0d = %x\n",dev->cd_Rom.er_Reserved0d);
printf("er_Reserved0e = %x\n",dev->cd_Rom.er_Reserved0e);
printf("er_Reserved0f = %x\n",dev->cd_Rom.er_Reserved0f);

printf("Hit Return to continue:\n");
gets(buff);
}
</syntaxhighlight>

= Registry =

{| class="wikitable"
! ID (decimal)
! ID (hexadecimal)
! Manufacturer
! Notes
|-
| 1
| 0001
| Micronik
|-
| 211
| 00D3
| Pacific Peripherals/Profex
|-
| 221
| 00DD
| Kupke Computertechnik GmbH
|-
| 256
| 0100
| Memphis
| Originally registered to MacroSystems US
|-
| 512
| 0200
| 3-State Computertechnik
|-
| 513
| 0201
| Commodore (Braunschweig)
|-
| 514
| 0202
| Commodore (West Chester)
|-
| 515
| 0203
| Commodore (West Chester)
| Originally registered to Combitech/Macrosystem
|-
| 756
| 02F4
| Progressive Peripherals & Software
|-
| 767
| 02FF
| Kolff Computer Supplies
|-
| 1001
| 03E9
| Tecmar
|-
| 1002
| 03EA
| Telesys
|-
| 1003
| 03EB
| The Micro-Forge
|-
| 1004
| 03EC
| Kronos/C Ltd.
| Originally registered to Card Co. (Supra)
|-
| 1005
| 03ED
| A-Squared
|-
| 1006
| 03EE
| Comspec Communications
|-
| 1007
| 03EF
| HT Electronics
|-
| 1008
| 03F0
| RDS Software
|-
| 1009
| 03F1
| Anakin Research
|-
| 1010
| 03F2
| MicroBotics
|-
| 1011
| 03F3
| Bob Krauth
|-
| 1012
| 03F4
| Access Associates (Alegra)
|-
| 1013
| 03F5
| Mini Comp Systems Ltd.
|-
| 1014
| 03F6
| Cypress Technology
|-
| 1015
| 03F7
| Fuller Computers
|-
| 1016
| 03F8
| Galaxy Computers
|-
| 1017
| 03F9
| ADA Research
|-
| 1018
| 03FA
| Computer Service Italia
|-
| 1019
| 03FB
| Amigo
|-
| 1020
| 03FC
| Micro-Solutions Inc.
|-
| 1021
| 03FD
| Stacar International
|-
| 1022
| 03FE
| Video Precisions
|-
| 1023
| 03FF
| ASDG, Inc.
|-
| 1025
| 0401
| Ing. Buero Kalawsky
|-
| 1026
| 0402
| Computer Tuning
|-
| 1027
| 0403
| Interplan Unternehmensberatung
|-
| 1028
| 0404
| Imtronics/Memphis
| Originally registered to Peter Ohlich
|-
| 1030
| 0406
| Commodore (Lowell University)
| Originally registered to Productivity Center
|-
| 1041
| 0411
| Design Labs
|-
| 1042
| 0412
| MCS
|-
| 1043
| 0413
| B. J. Freeman
|-
| 1044
| 0414
| Side Effects Inc.
|-
| 1045
| 0415
| Oklahoma Personal Comp.
|-
| 1046
| 0416
| Advanced Micro Innovations
|-
| 1047
| 0417
| Industrial Support Services
|-
| 1048
| 0418
| Technisoft
|-
| 1049
| 0419
| Prolific, Inc.
|-
| 1050
| 041A
| Softeam, Inc.
|-
| 1051
| 041B
| GRC Electronics
|-
| 1052
| 041C
| David Lai
|-
| 1053
| 041D
| Ameristar Technologies
|-
| 1054
| 041E
| Cline Refrigeration
|-
| 1055
| 041F
| Cardiac Pacemakers, Inc.
|-
| 1056
| 0420
| Supra Corp. (Creative Microsystems)
|-
| 1057
| 0421
| Wayne Diener
|-
| 1058
| 0422
| Computer Systems Associates (CSA)
|-
| 1059
| 0423
| Trionix, Inc.
|-
| 1060
| 0424
| David Lucas
|-
| 1061
| 0425
| Analog Precision
| Also assigned to D & L Distributing
|-
| 1267
| 04F3
| RBM Digitaltechnik
|-
| 1282
| 0502
| M-TEC Hardware Design
|-
| 1337
| 0539
| Thomas Stenzel (DaFR34K)
|-
| 1576
| 0628
| Boris Križma
|-
| 1729
| 06C1
| Thomas Richter / OpenPCI-A1200 Mediator bridge
|-
| 1730
| 06C2
| Thomas Richter / OpenPCI-A4000 Mediator bridge
|-
| 1731
| 06C3
| Thomas Richter / OpenPCI-Prometheus bridge (Firestorm or original)
|-
| 1732
| 06C4
| Thomas Richter / OpenPCI-Reserved1
|-
| 1733
| 06C5
| Thomas Richter / OpenPCI-Grex bridge (both A1200 and A4000)
|-
| 1734
| 06C6
| Thomas Richter / OpenPCI-Reserved2
|-
| 1735
| 06C7
| Thomas Richter / OpenPCI-Reserved3
|-
| 1736
| 06C8
| Thomas Richter / OpenPCI-Reserved4
|-
| 1737
| 06C9
| Thomas Richter / OpenPCI-Reserved5
|-
| 1738
| 06CA
| Thomas Richter / OpenPCI-Reserved6
|-
| 1739
| 06CB
| Thomas Richter / OpenPCI-Reserved7
|-
| 1740
| 06CC
| Thomas Richter / OpenPCI-Reserved8
|-
| 1741
| 06CD
| Thomas Richter / OpenPCI-Reserved9
|-
| 1742
| 06CE
| Thomas Richter / OpenPCI-Reserved10
|-
| 1743
| 06CF
| Thomas Richter / OpenPCI-Reserved11
|-
| 1744
| 06D0
| Thomas Richter / OpenPCI-Reserved12
|-
| 1761
| 06E1
| Great Valley Products
|-
| 1803
| 070B
| UAE Amiga Emulator
|-
| 2002
| 07D2
| Mimetics Corp.
|-
| 2003
| 07D3
| ACDA
|-
| 2004
| 07D4
| Finn R. Jacobsen
|-
| 2005
| 07D5
| Elthen Electronics
|-
| 2006
| 07D6
| Nine Tiles Computer Systems Ltd.
|-
| 2007
| 07D7
| Analog Electronics
|-
| 2008
| 07D8
| Bell & Howell
|-
| 2009
| 07D9
| Roland Kochler
|-
| 2010
| 07DA
| Byte Corp.
|-
| 2011
| 07DB
| Reserved
|-
| 2012
| 07DC
| DKB, Inc.
| Previously named Michigan Software
|-
| 2013
| 07DD
| Pacific Peripherals
|-
| 2014
| 07DE
| Sysaphus Software
|-
| 2015
| 07DF
| Digitronics
|-
| 2016
| 07E0
| Akron Systems
|-
| 2017
| 07E1
| Great Valley Products
|-
| 2018
| 07E2
| Calmos
|-
| 2019
| 07E3
| Dover Research
|-
| 2020
| 07E4
| David Krehbiel
|-
| 2021
| 07E5
| Synergy Peripheral Systems
| Also known as California Access
|-
| 2022
| 07E6
| Xetec
|-
| 2023
| 07E7
| Micron Technology
|-
| 2024
| 07E8
| CH Electronics
|-
| 2025
| 07E9
| American Liquid Light
|-
| 2026
| 07EA
| Progressive Peripherals & Software
| Also used by Ateo
|-
| 2027
| 07EB
| Wicat Systems
|-
| 2028
| 07EC
| Applied Systems & Peripherals
|-
| 2029
| 07ED
| Delaware Valley Software
|-
| 2030
| 07EE
| Palomax
|-
| 2031
| 07EF
| Incognito Software
|-
| 2032
| 07F0
| Jadesign
|-
| 2033
| 07F1
| BVR
|-
| 2034
| 07F2
| Spirit Technology
|-
| 2035
| 07F3
| Spirit Technology
|-
| 2036
| 07F4
| Atronic
|-
| 2037
| 07F5
| Scott Karlin
|-
| 2038
| 07F6
| Howitch
|-
| 2039
| 07F7
| Sullivan Brothers Visual Engineers
|-
| 2040
| 07F8
| G I T
|-
| 2041
| 07F9
| Amigo Business Computers
|-
| 2042
| 07FA
| Micro E Ab
|-
| 2043
| 07FB
| Ralph Kruse
|-
| 2044
| 07FC
| Clearpoint Research
|-
| 2045
| 07FD
| Kodiak
|-
| 2046
| 07FE
| BSC
| Originally registered to Phoenix Electronics
|-
| 2047
| 07FF
| No Name Shown
|-
| 2048
| 0800
| Commodore Braunschweig
|-
| 2049
| 0801
| BSC
| Originally registered to Elaborate Bytes
|-
| 2050
| 0802
| Kronos/C Ltd.
|-
| 2051
| 0803
| Spartanics
|-
| 2052
| 0804
| Jochheim Computer Tuning
|-
| 2053
| 0805
| Trans Data Systems
|-
| 2054
| 0806
| Applied Systems & Peripherals Ltd.
|-
| 2055
| 0807
| Checkpoint Technologies
| Originally registered to Amiga Solutions
|-
| 2056
| 0808
| Adept Development
|-
| 2057
| 0809
| Advanced Computer Design
|-
| 2058
| 080A
| Sir Netics
|-
| 2059
| 080B
| Expert Services
|-
| 2060
| 080C
| Digital Art Systems
|-
| 2061
| 080D
| Adept Development
|-
| 2062
| 080E
| Expansion Technologies (Expansion Systems)
|-
| 2063
| 080F
| Alphatech
|-
| 2064
| 0810
| Edotronik GmbH
|-
| 2065
| 0811
| California Access/Synergy
| Originally registered to Logical Design Works
|-
| 2066
| 0812
| Bowden, Williams, Full & Assoc.
|-
| 2067
| 0813
| NES, Inc.
|-
| 2068
| 0814
| Amdev
|-
| 2069
| 0815
| Big Brother Security Systems
|-
| 2070
| 0816
| Active Circuits Inc.
|-
| 2071
| 0817
| ICD, Inc.
|-
| 2072
| 0818
| Multi-Meg Electronique
|-
| 2073
| 0819
| Kupke Computertechnik GmbH
|-
| 2074
| 081A
| The Checkered Ball
|-
| 2075
| 081B
| Hi Tension Computer Services Ltd. (UK)
|-
| 2076
| 081C
| Alfa Data
| Originally assigned to Elmtech Research, Ltd. (UK)
|-
| 2077
| 081D
| Great Valley Products
| Originally registered to Clartscreen, Ltd. (UK)
|-
| 2078
| 081E
| Interworks
|-
| 2079
| 081F
| Galysh Enterprises
|-
| 2080
| 0820
| Hardital Synthesis
| Originally registered to Realtime Games Software Ltd.
|-
| 2081
| 0821
| GBS
|-
| 2082
| 0822
| Circum Design Inc.
|-
| 2083
| 0823
| Alberta Micro Electronic Center
|-
| 2084
| 0824
| Bestech
|-
| 2085
| 0825
| Lasar Fantasy
|-
| 2086
| 0826
| Pulsar
|-
| 2087
| 0827
| Ivis
|-
| 2088
| 0828
| Applied Engineering
|-
| 2089
| 0829
| Solid-State Design & Development
|-
| 2090
| 082A
| Vison Quest
|-
| 2091
| 082B
| Seaview Software
|-
| 2092
| 082C
| BSC
| Mistakenly used by ADS (Advanced Development Software)
|-
| 2093
| 082D
| Bernd Culenfeld
|-
| 2094
| 082E
| American Liquid Light
|-
| 2095
| 082F
| CEGITES
|-
| 2096
| 0830
| Quadlite Computers Ltd.
| Originally registered to EV Industries
|-
| 2097
| 0831
| Silicon Peace
|-
| 2098
| 0832
| Black Belt Systems
|-
| 2099
| 0833
| Village Tronic
| Originally registerd to Steve Yaeger
|-
| 2100
| 0834
| ReadySoft
|-
| 2101
| 0835
| Phoenix Micro Technologies
|-
| 2102
| 0836
| Advanced Systems & Software
| Orignally assigned to Preferred Technology
|-
| 2103
| 0837
| Rombo Productions
|-
| 2104
| 0838
| Impulse Inc.
|-
| 2105
| 0839
| Beta Unlimited
|-
| 2106
| 083A
| Memory Expansion System, Ltd.
|-
| 2107
| 083B
| Vortex Computer Systems GmbH
|-
| 2108
| 083C
| Platypus Systems
|-
| 2109
| 083D
| Gigatron OHG
|-
| 2110
| 083E
| PG Electronics
|-
| 2111
| 083F
| New Technologies Group
|-
| 2112
| 0840
| Interactive Video Systems (IVS)
| Pacific Peripherals
|-
| 2113
| 0841
| Vector
| Originally registered to H. K. Computer
|-
| 2114
| 0842
| Pacific Digital
| Originally registered to C. H. Helfrich Elektronik
|-
| 2115
| 0843
| Xanadu
|-
| 2116
| 0844
| Pacific Digital
| Originally registered to AMS
|-
| 2117
| 0845
| X-Pert
|-
| 2118
| 0846
| The Amiga Centre
|-
| 2119
| 0847
| Digital Pacific
|-
| 2120
| 0848
| Solid State Leisure
|-
| 2121
| 0849
| Hydra Systems
| Originally registered to Analog Electronics
|-
| 2122
| 084A
| Cumana
|-
| 2123
| 084B
| KAPS 2C Conception
|-
| 2124
| 084C
| Mike Mason
|-
| 2125
| 084D
| For Your Eyes
|-
| 2126
| 084E
| Volkmar Breitfeld Computersysteme
|-
| 2127
| 084F
| Sunrize Industries
|-
| 2128
| 0850
| Scott Advanced Micro Designs
|-
| 2129
| 0851
| Digital Micronics
|-
| 2130
| 0852
| Alfa-Laval
|-
| 2131
| 0853
| Multigros A/S
|-
| 2132
| 0854
| Archos
|-
| 2133
| 0855
| Icom Simulations
|-
| 2134
| 0856
| Commodore Test Engineering Group
|-
| 2135
| 0857
| Microcreations
|-
| 2136
| 0858
| Shoestring Productions
|-
| 2137
| 0859
| Faberushi
|-
| 2138
| 085A
| Evesham Micro Ltd.
|-
| 2139
| 085B
| Panagolin Laser Software
|-
| 2140
| 085C
| Thomas Rudloff
|-
| 2141
| 085D
| Daniel Hohabir
|-
| 2142
| 085E
| GfxBase, Inc.
|-
| 2143
| 085F
| Axellabs
|-
| 2144
| 0860
| Roctec Electronics Inc.
|-
| 2145
| 0861
| Omega Datentechnik
|-
| 2146
| 0862
| Atlantis
|-
| 2147
| 0863
| Skytec Computers
|-
| 2148
| 0864
| Protar Electronics
|-
| 2149
| 0865
| ACS
|-
| 2150
| 0866
| Software Results Enterprises
| Originally registered to University of Illinois
|-
| 2151
| 0867
| Infinity Systems Design Group
|-
| 2152
| 0868
| Trade It
|-
| 2153
| 0869
| Suntec, Inc.
|-
| 2154
| 086A
| DJW Micro Systems
| Originally registered to Tritec Marketing
|-
| 2155
| 086B
| Power Computing Ltd.
|-
| 2156
| 086C
| MacroSystems
|-
| 2157
| 086D
| Masoboshi GmbH (DCE)
|-
| 2158
| 086E
| HAL Software Hardware Handel
|-
| 2159
| 086F
| Mainhattan Data
| Originally registered to Michael Lamm Computersysteme
|-
| 2160
| 0870
| Digital Processing System
| Originally registered to bbdp Electronics
|-
| 2161
| 0871
| Blue Ribbon Soundworks
| Originally registered to Design Computer Systems
|-
| 2162
| 0872
| XPert
| Originally registered to The Station
|-
| 2163
| 0873
| DelaComp
| Originally registered to Bryan Williams
|-
| 2164
| 0874
| Superformance Computer Engineering GmbH
|-
| 2165
| 0875
| Overland Engineering
|-
| 2166
| 0876
| Thomas Hamren
|-
| 2167
| 0877
| Village Tronic
|-
| 2168
| 0878
| Toolbox Design
|-
| 2169
| 0879
| Digital Processing System
|-
| 2170
| 087A
| Superformance
|-
| 2171
| 087B
| Utilities Unlimited
|-
| 2172
| 087C
| phase 5
|-
| 2173
| 087D
| Juergen Kommos
|-
| 2174
| 087E
| Electronic Design
|-
| 2175
| 087F
| James Cook University of North Queensland
|-
| 2176
| 0880
| AmiTrix Development
|-
| 2177
| 0881
| Ferranti
|-
| 2178
| 0882
| Leviathan Development
|-
| 2179
| 0883
| United Video Inc.
|-
| 2180
| 0884
| GPSoft Pty. Ltd.
| Originally registered to Juergen Kommos
|-
| 2181
| 0885
| ArMAX
| Oliver Bausch
|-
| 2182
| 0886
| CP Computer
|-
| 2183
| 0887
| AMOK - Amiga Module & Oberon Klub
|-
| 2184
| 0888
| ITEK Neser & Sieber GbR
|-
| 2185
| 0889
| Phillip C. Lello
|-
| 2186
| 088A
| Cyborg Design Services
|-
| 2187
| 088B
| G2 Systems
|-
| 2188
| 088C
| Pro System Computersysteme
|-
| 2189
| 088D
| ZEUS Electronic
| Originally registered to MSPI (Markt & Technik)
|-
| 2190
| 088E
| Altatech
|-
| 2191
| 088F
| NewTek
|-
| 2192
| 0890
| M-TEC Hardware Design
| Originally registered to Hardware Design Udo Neuroth
|-
| 2193
| 0891
| Great Valley Products
| Originally registered to Viona Development
|-
| 2194
| 0892
| Amitek
| Originally assigned to Marpet Developments
|-
| 2195
| 0893
| Ingenieurbuero Helfrich
|-
| 2196
| 0894
| The Neo Group
|-
| 2197
| 0895
| Cyon
|-
| 2198
| 0896
| Bob Research Group
|-
| 2199
| 0897
| Richmond Sound Design Ltd.
|-
| 2200
| 0898
| US Cybernetics
|-
| 2201
| 0899
| Fulvio Ieva
|-
| 2202
| 089A
| Silicon Studio
|-
| 2203
| 089B
| MacroSystems (USA)
| Was named Micro System Devices
|-
| 2204
| 089C
| Conspector Entertainment
|-
| 2205
| 089D
| Laserforum
|-
| 2206
| 089E
| Elbox Computer
| Mistakenly used by Index Information Ltd.
|-
| 2207
| 089F
| Applied Magic Inc.
|-
| 2208
| 08A0
| SDL Ltd.
|-
| 2560
| 0A00
| Harms
|-
| 2588
| 0A1C
| A1K.org Community
|-
| 2640
| 0A50
| Micronik
|-
| 2782
| 2782
| Oliver Achten
|-
| 3084
| 0C0C
| Team 4
|-
| 3643
| 0E3B
| E3B
| Michael Boehmer
|-
| 3855
| 0F0F
| Micronik
|-
| 4096
| 1000
| MegaMicro
|-
| 4110
| 100E
| DigiFeX
|-
| 4136
| 1028
| Imtronics/Memphis
|-
| 4149
| 1035
| PROTAR
|-
| 4369
| 1111
| Frank Strauß Elektronik
| Also used by Kupke
|-
| 4626
| 1212
| Individual Computers
|-
| 4648
| 1228
| Flesch Hornemann Computer Elec.
|-
| 4680
| 1248
| Kupke Computertechnik GmbH
|-
| 4711
| 1267
| RBM digitaltechnik
|-
| 4754
| 1292
| MacroSystems
|-
| 5000
| 1388
| ITH
|-
| 5001
| 1389
| VMC
|-
| 5010
| 1392
| Ambience Creation Technology
|-
| 5011
| 1393
| Creative Development
|-
| 5012
| 1394
| Georg Braun
|-
| 5013
| 1395
| Swedish User Group of Amiga
|-
| 5014
| 1396
| Jakub Bednarski
|-
| 5015
| 1397
| KryoFlux, Ltd.
|-
| 5016
| 1398
| Igor Majstorovic
|-
| 5017
| 1399
| Alastair M. Robinson
|-
| 5018
| 139A
| Austex Software
|-
| 5019
| 139B
| Sören Gust
|-
| 5020
| 139C
| Rok Krajnc
|-
| 5030
| 13A6
| Tim Tashpulatov
|-
| 5040
| 13B0
| 7-bit
|-
| 5050
| 13BA
| Sakura IT
|-
| 5060
| 13C4
| FPGAArcade
|-
| 5070
| 13CE
| CancerSoft Inc.
|-
| 5080
| 13D8
| Stephen Leary
|-
| 5090
| 13E2
| DMA Softlab LLC
|-
| 5100
| 13EC
| Brookhouse Engineering
|-
| 5110
| 13F6
| Eduardo Arana
|-
| 5120
| 1400
| CS-LAB
|-
| 5130
| 140A
| Robert Miranda
|-
| 5140
| 1414
| RastPort
|-
| 5132
| 140C
| UAS Interface Ltd6
|-
| 5150
| 141E
| Amiga Kit
|-
| 5160
| 1428
| Central Texas Commodore User Group
|-
| 5170
| 1432
| Confusion Research Center
|-
| 5180
| 143C
| Solar Soyuz Zaibatsu
|-
| 5190
| 1446
| BooBip
|-
| 5191
| 1447
| Matthias Hampel
|-
| 5192
| 1448
| dec0de Consulting Ltd.
|-
| 5193
| 1449
| Puppy Concepts
|-
| 5194
| 144A
| Open Amiga Hardware Repository
|-
| 5195
| 144B
| Double H Tech
|-
| 5196
| 144C
| Retromatik
|-
| 5500
| 157C
| Inhouse Information
|-
| 5768
| 1688
| Bio Con
|-
| 6148
| 1804
| HK-Computer
|-
| 6502
| 1966
| Cloanto
|-
| 6520
| 1978
| Oliver Gantert
|-
| 7777
| 1E61
| Rafal Gabriel Chyla
|-
| 8215
| 2017
| Vortex
|-
| 8244
| 2034
| Spirit Technology
|-
| 8290
| 2062
| Expansion Systems
|-
| 8448
| 2100
| ReadySoft
|-
| 8512
| 2140
| Phase 5 Digital Products
|-
| 8553
| 2169
| Digital Processing Systems Inc.
|-
| 8704
| 2200
| ACT Elektronik
|-
| 8738
| 2222
| ACT Elektronik
|-
| 9512
| 2528
| Tower Technologies
|-
| 10676
| 29B4
| Electronic Design
|-
| 14195
| 3773
| Media-net-Point
|-
| 14501
| 38A5
| Petsoff, Finland
|-
| 16375
| 3FF7
| Uwe Gerlach
|-
| 16707
| 4143
| Ateo Concepts
|-
| 16708
| 4144
| ALiENDESiGN
|-
| 16945
| 4231
| A.C.T.
|-
| 17740
| 454C
| HK-Computer (ELSAT)
|-
| 18260
| 4754
| MacroSystems (Germany)
|-
| 19796
| 4D54
| Markt & Technik
|-
| 22359
| 5757
| Markt & Technik
|-
| 26464
| 6760
| Combitec
|-
| 26470
| 6766
| Combitec
|-
| 28014
| 6D6E
| MNT Media and Technology UG
|-
| 32768
| 8000
| M.A.S.T.
|-
| 42240
| A500
| Aethreum Digital
|-
| 43437
| A9AD
| Reis-Ware
|-
| 43521
| AA01
| Cameron
|-
| 43537
| AA11
| Reis-Ware
|-
| 44359
| AD47
| Matay
|-
| 46504
| B5A8
| Phoenix
|-
| 48879
| BEEF
| Swiss Mountain Dog Products
|-
| 49160
| C008
| Combitec
|-
| 61453
| F00D
| Forefront Technologies Inc.
|}

For any changes/additions to this registry see [[#How_to_Obtain_a_Manufacturer_Number|How to Obtain a Manufacturer Number]]

Amiga Hardware Manufacturer ID Registry

2026-09-08T11:06:16Z

Costel Mincea: Added IDs 1729-1744 for OpenPCI/Thomas Richter

__TOC__

= How to Obtain a Manufacturer Number =

Manufacturer's numbers are assigned by the AmigaOS development team. To obtain your unique manufacturer number send a support request to [mailto:support@hyperion-entertainment.com support@hyperion-entertainment.com] including these information:

1. The name of the company or person which the number is assigned to

2. Postal address/contact address

3. Name of the contact person, with a corresponding e-mail address

4. A brief description of the kind of products you want to produce

= Your Manufacturer Number =

Attention hardware manufacturers. If you are developing a hardware expansion product for the Classic Amiga (e.g. 500, 2000, 3000) then you will need to obtain a special manufacturer ID number from the AmigaOS development team to identify your product. This manufacturer number is used by the Amiga to link your hardware with its driver software at boot time.

Your manufacturer number is part of the special protocol that the Amiga uses to automatically configure all expansion devices on the bus without the user having to cut jumpers or adjust dip switches. This is called auto-config.

At start-up time, the system first polls each board in the system and assigns the board its own address space. If it is a memory board, its RAM is linked into the memory free pool. Later in the boot sequence, after DOS is initialized, the binddrivers program is run. Binddrivers will search the directory SYS:Expansion for the drivers that go with the boards.

To do this binddrivers looks in the Tool Type field of all icon files in SYS:Expansion. If the first seven bytes of the Tool Type field are "PRODUCT", then this is an icon file for a driver.

Binddrivers will then attempt to match the drivers it has found with the boards that were found earlier. This is where your manufacturer number comes in.

Your manufacturer number goes in two places. First, it is burned in hex form into the PAL which is part of ALL auto-config expansion products. Second, it appears in ASCII in the Tool Type field of the icon file for your product's driver. By matching these two numbers, the Amiga can automatically configure your board and bind it's software driver into the system as well.

The manufacturer's number is a 16-bit ID which appears in PAL offsets $10-$17. There is also an 8-bit product number which you assign. The product number is for uniquely identifying different products from the same vendor. The product number will appear in PAL offsets $04-$07. This gives you a total of 24 bits to identify each of your products.

These 24 bits of information in the PAL which identify your product are matched against the information in the Tool Type field of all icon files in the SYS:Expansion drawer. For example, suppose you are manufacturer #1019. You have two products, #1 and #2 which both use the same driver. The icon for your driver for these two products would have a Tool Type set to "PRODUCT=1019/1|1019/2". This means: I am an icon for a driver that works with product number 1 or 2 from manufacturer 1019, now bind me. Spaces are not legal. Here are two other examples:

; PRODUCT=1208/11
: is the Tool Type for a driver for product 11 from manufacturer number 1208.

; PRODUCT=1017
: is the Tool Type for a driver for any product from manufacturer number 1017.

For an informal explanation of the auto-configuration process, see the chapter on Software Expansion Architecture from the 2nd Annual Amiga Developer's Conference Notes (available on ADCD 2.1). For the details of timing, power, the PAL equations and PAL address specifications and the expansion library documentation, see sections 3.1 to 3.3 of the A500/A2000 Technical Reference Manual. The original auto-config spec appears in the A1000 Schematics and Expansion Specification.

The auto-config process makes the addition of expansion products to the system very easy. All the user has to do is put the board in any slot and copy the driver from the release disk to his own SYS:Expansion drawer. Everything else is automatic. There are no jumpers or dip switches to set. Best of all, you will get a lot less support calls asking how to make your product work with the XYZ-Corp-battery-backed-clock.

= Notes =

Some notes on hardware manufacturer ID assignment.

* Manufacturer ID numbers are assigned free of charge.
* Please provide the following information when requesting an ID:
*# Name of the company or person
*# Postal address/contact address
*# Name of the contact person, with a corresponding e-mail address
*# A brief description of the kind of products you want to produce
* All ID numbers smaller than 5000 must be considered unsafe because no information exists on which numbers exactly were taken during the time Commodore, Inc. disintegrated.
* ID numbers in the range 8192 to 18841 must be considered unsafe because some hardware developers mistook the numbers assigned to them to be given in hexadecimal format. Hence 0x2000 = 8192 and 0x4999 = 18841.

= Example code =

<syntaxhighlight lang="C" line>
/*-----------------------------------------------*/
/* Here is a short program which will tell you */
/* about the expansion boards configured in your */
/* system without you opening up the machine. */
/* Code by Bill Koester of CATS */
/*-----------------------------------------------*/
#include <libraries/configvars.h>
#include <libraries/expansion.h>

struct ExpansionBase *ExpansionBase;

void cleanup();
void printdev();

int main()
{
struct ConfigDev *MyConfigDev;

/*----------------------------------*/
/* Open the expansion library, */
/* if there is a problem then exit */
/*----------------------------------*/

ExpansionBase =(struct ExpansionBase *) OpenLibrary(EXPANSIONNAME,0);
if(ExpansionBase==NULL)
{
printf("Error opening expansion library!!\n");
cleanup();
exit(0);
}

/*--------------------------------------------*/
/* Use FindConfigDev to get info on the first */
/* expansion board on the list maintained by */
/* Exec. If there are no expansion boards in */
/* the system then exit. */
/*--------------------------------------------*/

MyConfigDev = NULL;

/*--------------------------------------------------*/
/* FindConfigDev(oldConfigDev,manufacturer,product) */
/* oldConfigDev = NULL for the top of the list */
/* manufacturer = -1 for any manufacturer */
/* product = -1 for any product */
/*--------------------------------------------------*/

MyConfigDev = FindConfigDev(NULL,-1,-1);

if(MyConfigDev==NULL)
{
printf("No Configured Devices found!!\n");
cleanup();
exit(0);
}

printdev(MyConfigDev);

/*-----------------------------------*/
/* OK, there is at least one board, */
/* so loop and get the entire list */
/* printing as we go with printdev() */
/*-----------------------------------*/

while(MyConfigDev = FindConfigDev(MyConfigDev,-1,-1))
{
printdev(MyConfigDev);
}
cleanup();
return 0;
}

/*-------------------*/
/* Close up shop... */
/*-------------------*/
void cleanup()
{
if(ExpansionBase)
CloseLibrary(ExpansionBase);
}

/*----------------------------------*/
/* Print out the contents of the */
/* dev structure for this expansion */
/* product. */
/*----------------------------------*/

void printdev(dev)
struct ConfigDev *dev;
{
char buff[200];

printf("Flags = ");
if(dev->cd_Flags==NULL)
printf("NULL ");
if(dev->cd_Flags&CDF_SHUTUP)
printf("CDF_SHUTUP ");
if(dev->cd_Flags&CDF_CONFIGME)
printf("CDF_CONFIGME ");
printf("\n");
printf("Board Address = %x\n",dev->cd_BoardAddr);
printf("Board Size = %d bytes\n",dev->cd_BoardSize);
printf("Slot Address = %d\n",dev->cd_SlotAddr);
printf("Slot Size = %d\n",dev->cd_SlotSize);
printf("Driver code at %x\n",dev->cd_Driver);

printf("er_Type = %x\n",dev->cd_Rom.er_Type);
printf("er_Product = %x\n",dev->cd_Rom.er_Product);
printf("er_Flags = %x\n",dev->cd_Rom.er_Flags);
printf("er_Reserved03 = %x\n",dev->cd_Rom.er_Reserved03);
printf("er_Manufacturer = %x\n",dev->cd_Rom.er_Manufacturer);
printf("er_SerialNumber = %x\n",dev->cd_Rom.er_SerialNumber);
printf("er_InitDiagVec = %x\n",dev->cd_Rom.er_InitDiagVec);
printf("er_Reserved0c = %x\n",dev->cd_Rom.er_Reserved0c);
printf("er_Reserved0d = %x\n",dev->cd_Rom.er_Reserved0d);
printf("er_Reserved0e = %x\n",dev->cd_Rom.er_Reserved0e);
printf("er_Reserved0f = %x\n",dev->cd_Rom.er_Reserved0f);

printf("Hit Return to continue:\n");
gets(buff);
}
</syntaxhighlight>

= Registry =

{| class="wikitable"
! ID (decimal)
! ID (hexadecimal)
! Manufacturer
! Notes
|-
| 1
| 0001
| Micronik
|-
| 211
| 00D3
| Pacific Peripherals/Profex
|-
| 221
| 00DD
| Kupke Computertechnik GmbH
|-
| 256
| 0100
| Memphis
| Originally registered to MacroSystems US
|-
| 512
| 0200
| 3-State Computertechnik
|-
| 513
| 0201
| Commodore (Braunschweig)
|-
| 514
| 0202
| Commodore (West Chester)
|-
| 515
| 0203
| Commodore (West Chester)
| Originally registered to Combitech/Macrosystem
|-
| 756
| 02F4
| Progressive Peripherals & Software
|-
| 767
| 02FF
| Kolff Computer Supplies
|-
| 1001
| 03E9
| Tecmar
|-
| 1002
| 03EA
| Telesys
|-
| 1003
| 03EB
| The Micro-Forge
|-
| 1004
| 03EC
| Kronos/C Ltd.
| Originally registered to Card Co. (Supra)
|-
| 1005
| 03ED
| A-Squared
|-
| 1006
| 03EE
| Comspec Communications
|-
| 1007
| 03EF
| HT Electronics
|-
| 1008
| 03F0
| RDS Software
|-
| 1009
| 03F1
| Anakin Research
|-
| 1010
| 03F2
| MicroBotics
|-
| 1011
| 03F3
| Bob Krauth
|-
| 1012
| 03F4
| Access Associates (Alegra)
|-
| 1013
| 03F5
| Mini Comp Systems Ltd.
|-
| 1014
| 03F6
| Cypress Technology
|-
| 1015
| 03F7
| Fuller Computers
|-
| 1016
| 03F8
| Galaxy Computers
|-
| 1017
| 03F9
| ADA Research
|-
| 1018
| 03FA
| Computer Service Italia
|-
| 1019
| 03FB
| Amigo
|-
| 1020
| 03FC
| Micro-Solutions Inc.
|-
| 1021
| 03FD
| Stacar International
|-
| 1022
| 03FE
| Video Precisions
|-
| 1023
| 03FF
| ASDG, Inc.
|-
| 1025
| 0401
| Ing. Buero Kalawsky
|-
| 1026
| 0402
| Computer Tuning
|-
| 1027
| 0403
| Interplan Unternehmensberatung
|-
| 1028
| 0404
| Imtronics/Memphis
| Originally registered to Peter Ohlich
|-
| 1030
| 0406
| Commodore (Lowell University)
| Originally registered to Productivity Center
|-
| 1041
| 0411
| Design Labs
|-
| 1042
| 0412
| MCS
|-
| 1043
| 0413
| B. J. Freeman
|-
| 1044
| 0414
| Side Effects Inc.
|-
| 1045
| 0415
| Oklahoma Personal Comp.
|-
| 1046
| 0416
| Advanced Micro Innovations
|-
| 1047
| 0417
| Industrial Support Services
|-
| 1048
| 0418
| Technisoft
|-
| 1049
| 0419
| Prolific, Inc.
|-
| 1050
| 041A
| Softeam, Inc.
|-
| 1051
| 041B
| GRC Electronics
|-
| 1052
| 041C
| David Lai
|-
| 1053
| 041D
| Ameristar Technologies
|-
| 1054
| 041E
| Cline Refrigeration
|-
| 1055
| 041F
| Cardiac Pacemakers, Inc.
|-
| 1056
| 0420
| Supra Corp. (Creative Microsystems)
|-
| 1057
| 0421
| Wayne Diener
|-
| 1058
| 0422
| Computer Systems Associates (CSA)
|-
| 1059
| 0423
| Trionix, Inc.
|-
| 1060
| 0424
| David Lucas
|-
| 1061
| 0425
| Analog Precision
| Also assigned to D & L Distributing
|-
| 1267
| 04F3
| RBM Digitaltechnik
|-
| 1282
| 0502
| M-TEC Hardware Design
|-
| 1337
| 0539
| Thomas Stenzel (DaFR34K)
|-
| 1576
| 0628
| Boris Križma
|-
| 1729
| 06C1
| Thomas Richter / OpenPCI-A1200 Mediator bridge
|-
| 1730
| 06C2
| Thomas Richter / OpenPCI-A4000 Mediator bridge
|-
| 1731
| 06C3
| Thomas Richter / OpenPCI-Prometheus bridge (Firestorm or original)
|-
| 1732
| 06C4
| Thomas Richter / OpenPCI-Reserved1
|-
| 1733
| 06C5
| Thomas Richter / OpenPCI-Grex bridge (both A1200 and A4000)
|-
| 1734
| 06C6
| Thomas Richter / OpenPCI-Reserved2
|-
| 1735
| 06C7
| Thomas Richter / OpenPCI-Reserved3
|-
| 1736
| 06C8
| Thomas Richter / OpenPCI-Reserved4
|-
| 1737
| 06C9
| Thomas Richter / OpenPCI-Reserved5
|-
| 1738
| 06CA
| Thomas Richter / OpenPCI-Reserved6
|-
| 1739
| 06CB
| Thomas Richter / OpenPCI-Reserved7
|-
| 1740
| 06CC
| Thomas Richter / OpenPCI-Reserved8
|-
| 1741
| 06CD
| Thomas Richter / OpenPCI-Reserved9
|-
| 1742
| 06CE
| Thomas Richter / OpenPCI-Reserved10
|-
| 1743
| 06CF
| Thomas Richter / OpenPCI-Reserved11
|-
| 1744
| 06D0
| Thomas Richter / OpenPCI-Reserved12
|-
| 1761
| 06E1
| Great Valley Products
|-
| 1803
| 070B
| UAE Amiga Emulator
|-
| 2002
| 07D2
| Mimetics Corp.
|-
| 2003
| 07D3
| ACDA
|-
| 2004
| 07D4
| Finn R. Jacobsen
|-
| 2005
| 07D5
| Elthen Electronics
|-
| 2006
| 07D6
| Nine Tiles Computer Systems Ltd.
|-
| 2007
| 07D7
| Analog Electronics
|-
| 2008
| 07D8
| Bell & Howell
|-
| 2009
| 07D9
| Roland Kochler
|-
| 2010
| 07DA
| Byte Corp.
|-
| 2011
| 07DB
| Reserved
|-
| 2012
| 07DC
| DKB, Inc.
| Previously named Michigan Software
|-
| 2013
| 07DD
| Pacific Peripherals
|-
| 2014
| 07DE
| Sysaphus Software
|-
| 2015
| 07DF
| Digitronics
|-
| 2016
| 07E0
| Akron Systems
|-
| 2017
| 07E1
| Great Valley Products
|-
| 2018
| 07E2
| Calmos
|-
| 2019
| 07E3
| Dover Research
|-
| 2020
| 07E4
| David Krehbiel
|-
| 2021
| 07E5
| Synergy Peripheral Systems
| Also known as California Access
|-
| 2022
| 07E6
| Xetec
|-
| 2023
| 07E7
| Micron Technology
|-
| 2024
| 07E8
| CH Electronics
|-
| 2025
| 07E9
| American Liquid Light
|-
| 2026
| 07EA
| Progressive Peripherals & Software
| Also used by Ateo
|-
| 2027
| 07EB
| Wicat Systems
|-
| 2028
| 07EC
| Applied Systems & Peripherals
|-
| 2029
| 07ED
| Delaware Valley Software
|-
| 2030
| 07EE
| Palomax
|-
| 2031
| 07EF
| Incognito Software
|-
| 2032
| 07F0
| Jadesign
|-
| 2033
| 07F1
| BVR
|-
| 2034
| 07F2
| Spirit Technology
|-
| 2035
| 07F3
| Spirit Technology
|-
| 2036
| 07F4
| Atronic
|-
| 2037
| 07F5
| Scott Karlin
|-
| 2038
| 07F6
| Howitch
|-
| 2039
| 07F7
| Sullivan Brothers Visual Engineers
|-
| 2040
| 07F8
| G I T
|-
| 2041
| 07F9
| Amigo Business Computers
|-
| 2042
| 07FA
| Micro E Ab
|-
| 2043
| 07FB
| Ralph Kruse
|-
| 2044
| 07FC
| Clearpoint Research
|-
| 2045
| 07FD
| Kodiak
|-
| 2046
| 07FE
| BSC
| Originally registered to Phoenix Electronics
|-
| 2047
| 07FF
| No Name Shown
|-
| 2048
| 0800
| Commodore Braunschweig
|-
| 2049
| 0801
| BSC
| Originally registered to Elaborate Bytes
|-
| 2050
| 0802
| Kronos/C Ltd.
|-
| 2051
| 0803
| Spartanics
|-
| 2052
| 0804
| Jochheim Computer Tuning
|-
| 2053
| 0805
| Trans Data Systems
|-
| 2054
| 0806
| Applied Systems & Peripherals Ltd.
|-
| 2055
| 0807
| Checkpoint Technologies
| Originally registered to Amiga Solutions
|-
| 2056
| 0808
| Adept Development
|-
| 2057
| 0809
| Advanced Computer Design
|-
| 2058
| 080A
| Sir Netics
|-
| 2059
| 080B
| Expert Services
|-
| 2060
| 080C
| Digital Art Systems
|-
| 2061
| 080D
| Adept Development
|-
| 2062
| 080E
| Expansion Technologies (Expansion Systems)
|-
| 2063
| 080F
| Alphatech
|-
| 2064
| 0810
| Edotronik GmbH
|-
| 2065
| 0811
| California Access/Synergy
| Originally registered to Logical Design Works
|-
| 2066
| 0812
| Bowden, Williams, Full & Assoc.
|-
| 2067
| 0813
| NES, Inc.
|-
| 2068
| 0814
| Amdev
|-
| 2069
| 0815
| Big Brother Security Systems
|-
| 2070
| 0816
| Active Circuits Inc.
|-
| 2071
| 0817
| ICD, Inc.
|-
| 2072
| 0818
| Multi-Meg Electronique
|-
| 2073
| 0819
| Kupke Computertechnik GmbH
|-
| 2074
| 081A
| The Checkered Ball
|-
| 2075
| 081B
| Hi Tension Computer Services Ltd. (UK)
|-
| 2076
| 081C
| Alfa Data
| Originally assigned to Elmtech Research, Ltd. (UK)
|-
| 2077
| 081D
| Great Valley Products
| Originally registered to Clartscreen, Ltd. (UK)
|-
| 2078
| 081E
| Interworks
|-
| 2079
| 081F
| Galysh Enterprises
|-
| 2080
| 0820
| Hardital Synthesis
| Originally registered to Realtime Games Software Ltd.
|-
| 2081
| 0821
| GBS
|-
| 2082
| 0822
| Circum Design Inc.
|-
| 2083
| 0823
| Alberta Micro Electronic Center
|-
| 2084
| 0824
| Bestech
|-
| 2085
| 0825
| Lasar Fantasy
|-
| 2086
| 0826
| Pulsar
|-
| 2087
| 0827
| Ivis
|-
| 2088
| 0828
| Applied Engineering
|-
| 2089
| 0829
| Solid-State Design & Development
|-
| 2090
| 082A
| Vison Quest
|-
| 2091
| 082B
| Seaview Software
|-
| 2092
| 082C
| BSC
| Mistakenly used by ADS (Advanced Development Software)
|-
| 2093
| 082D
| Bernd Culenfeld
|-
| 2094
| 082E
| American Liquid Light
|-
| 2095
| 082F
| CEGITES
|-
| 2096
| 0830
| Quadlite Computers Ltd.
| Originally registered to EV Industries
|-
| 2097
| 0831
| Silicon Peace
|-
| 2098
| 0832
| Black Belt Systems
|-
| 2099
| 0833
| Village Tronic
| Originally registerd to Steve Yaeger
|-
| 2100
| 0834
| ReadySoft
|-
| 2101
| 0835
| Phoenix Micro Technologies
|-
| 2102
| 0836
| Advanced Systems & Software
| Orignally assigned to Preferred Technology
|-
| 2103
| 0837
| Rombo Productions
|-
| 2104
| 0838
| Impulse Inc.
|-
| 2105
| 0839
| Beta Unlimited
|-
| 2106
| 083A
| Memory Expansion System, Ltd.
|-
| 2107
| 083B
| Vortex Computer Systems GmbH
|-
| 2108
| 083C
| Platypus Systems
|-
| 2109
| 083D
| Gigatron OHG
|-
| 2110
| 083E
| PG Electronics
|-
| 2111
| 083F
| New Technologies Group
|-
| 2112
| 0840
| Interactive Video Systems (IVS)
| Pacific Peripherals
|-
| 2113
| 0841
| Vector
| Originally registered to H. K. Computer
|-
| 2114
| 0842
| Pacific Digital
| Originally registered to C. H. Helfrich Elektronik
|-
| 2115
| 0843
| Xanadu
|-
| 2116
| 0844
| Pacific Digital
| Originally registered to AMS
|-
| 2117
| 0845
| X-Pert
|-
| 2118
| 0846
| The Amiga Centre
|-
| 2119
| 0847
| Digital Pacific
|-
| 2120
| 0848
| Solid State Leisure
|-
| 2121
| 0849
| Hydra Systems
| Originally registered to Analog Electronics
|-
| 2122
| 084A
| Cumana
|-
| 2123
| 084B
| KAPS 2C Conception
|-
| 2124
| 084C
| Mike Mason
|-
| 2125
| 084D
| For Your Eyes
|-
| 2126
| 084E
| Volkmar Breitfeld Computersysteme
|-
| 2127
| 084F
| Sunrize Industries
|-
| 2128
| 0850
| Scott Advanced Micro Designs
|-
| 2129
| 0851
| Digital Micronics
|-
| 2130
| 0852
| Alfa-Laval
|-
| 2131
| 0853
| Multigros A/S
|-
| 2132
| 0854
| Archos
|-
| 2133
| 0855
| Icom Simulations
|-
| 2134
| 0856
| Commodore Test Engineering Group
|-
| 2135
| 0857
| Microcreations
|-
| 2136
| 0858
| Shoestring Productions
|-
| 2137
| 0859
| Faberushi
|-
| 2138
| 085A
| Evesham Micro Ltd.
|-
| 2139
| 085B
| Panagolin Laser Software
|-
| 2140
| 085C
| Thomas Rudloff
|-
| 2141
| 085D
| Daniel Hohabir
|-
| 2142
| 085E
| GfxBase, Inc.
|-
| 2143
| 085F
| Axellabs
|-
| 2144
| 0860
| Roctec Electronics Inc.
|-
| 2145
| 0861
| Omega Datentechnik
|-
| 2146
| 0862
| Atlantis
|-
| 2147
| 0863
| Skytec Computers
|-
| 2148
| 0864
| Protar Electronics
|-
| 2149
| 0865
| ACS
|-
| 2150
| 0866
| Software Results Enterprises
| Originally registered to University of Illinois
|-
| 2151
| 0867
| Infinity Systems Design Group
|-
| 2152
| 0868
| Trade It
|-
| 2153
| 0869
| Suntec, Inc.
|-
| 2154
| 086A
| DJW Micro Systems
| Originally registered to Tritec Marketing
|-
| 2155
| 086B
| Power Computing Ltd.
|-
| 2156
| 086C
| MacroSystems
|-
| 2157
| 086D
| Masoboshi GmbH (DCE)
|-
| 2158
| 086E
| HAL Software Hardware Handel
|-
| 2159
| 086F
| Mainhattan Data
| Originally registered to Michael Lamm Computersysteme
|-
| 2160
| 0870
| Digital Processing System
| Originally registered to bbdp Electronics
|-
| 2161
| 0871
| Blue Ribbon Soundworks
| Originally registered to Design Computer Systems
|-
| 2162
| 0872
| XPert
| Originally registered to The Station
|-
| 2163
| 0873
| DelaComp
| Originally registered to Bryan Williams
|-
| 2164
| 0874
| Superformance Computer Engineering GmbH
|-
| 2165
| 0875
| Overland Engineering
|-
| 2166
| 0876
| Thomas Hamren
|-
| 2167
| 0877
| Village Tronic
|-
| 2168
| 0878
| Toolbox Design
|-
| 2169
| 0879
| Digital Processing System
|-
| 2170
| 087A
| Superformance
|-
| 2171
| 087B
| Utilities Unlimited
|-
| 2172
| 087C
| phase 5
|-
| 2173
| 087D
| Juergen Kommos
|-
| 2174
| 087E
| Electronic Design
|-
| 2175
| 087F
| James Cook University of North Queensland
|-
| 2176
| 0880
| AmiTrix Development
|-
| 2177
| 0881
| Ferranti
|-
| 2178
| 0882
| Leviathan Development
|-
| 2179
| 0883
| United Video Inc.
|-
| 2180
| 0884
| GPSoft Pty. Ltd.
| Originally registered to Juergen Kommos
|-
| 2181
| 0885
| ArMAX
| Oliver Bausch
|-
| 2182
| 0886
| CP Computer
|-
| 2183
| 0887
| AMOK - Amiga Module & Oberon Klub
|-
| 2184
| 0888
| ITEK Neser & Sieber GbR
|-
| 2185
| 0889
| Phillip C. Lello
|-
| 2186
| 088A
| Cyborg Design Services
|-
| 2187
| 088B
| G2 Systems
|-
| 2188
| 088C
| Pro System Computersysteme
|-
| 2189
| 088D
| ZEUS Electronic
| Originally registered to MSPI (Markt & Technik)
|-
| 2190
| 088E
| Altatech
|-
| 2191
| 088F
| NewTek
|-
| 2192
| 0890
| M-TEC Hardware Design
| Originally registered to Hardware Design Udo Neuroth
|-
| 2193
| 0891
| Great Valley Products
| Originally registered to Viona Development
|-
| 2194
| 0892
| Amitek
| Originally assigned to Marpet Developments
|-
| 2195
| 0893
| Ingenieurbuero Helfrich
|-
| 2196
| 0894
| The Neo Group
|-
| 2197
| 0895
| Cyon
|-
| 2198
| 0896
| Bob Research Group
|-
| 2199
| 0897
| Richmond Sound Design Ltd.
|-
| 2200
| 0898
| US Cybernetics
|-
| 2201
| 0899
| Fulvio Ieva
|-
| 2202
| 089A
| Silicon Studio
|-
| 2203
| 089B
| MacroSystems (USA)
| Was named Micro System Devices
|-
| 2204
| 089C
| Conspector Entertainment
|-
| 2205
| 089D
| Laserforum
|-
| 2206
| 089E
| Elbox Computer
| Mistakenly used by Index Information Ltd.
|-
| 2207
| 089F
| Applied Magic Inc.
|-
| 2208
| 08A0
| SDL Ltd.
|-
| 2560
| 0A00
| Harms
|-
| 2588
| 0A1C
| A1K.org Community
|-
| 2640
| 0A50
| Micronik
|-
| 3084
| 0C0C
| Team 4
|-
| 3643
| 0E3B
| E3B
| Michael Boehmer
|-
| 3855
| 0F0F
| Micronik
|-
| 4096
| 1000
| MegaMicro
|-
| 4110
| 100E
| DigiFeX
|-
| 4136
| 1028
| Imtronics/Memphis
|-
| 4149
| 1035
| PROTAR
|-
| 4369
| 1111
| Frank Strauß Elektronik
| Also used by Kupke
|-
| 4626
| 1212
| Individual Computers
|-
| 4648
| 1228
| Flesch Hornemann Computer Elec.
|-
| 4680
| 1248
| Kupke Computertechnik GmbH
|-
| 4711
| 1267
| RBM digitaltechnik
|-
| 4754
| 1292
| MacroSystems
|-
| 5000
| 1388
| ITH
|-
| 5001
| 1389
| VMC
|-
| 5010
| 1392
| Ambience Creation Technology
|-
| 5011
| 1393
| Creative Development
|-
| 5012
| 1394
| Georg Braun
|-
| 5013
| 1395
| Swedish User Group of Amiga
|-
| 5014
| 1396
| Jakub Bednarski
|-
| 5015
| 1397
| KryoFlux, Ltd.
|-
| 5016
| 1398
| Igor Majstorovic
|-
| 5017
| 1399
| Alastair M. Robinson
|-
| 5018
| 139A
| Austex Software
|-
| 5019
| 139B
| Sören Gust
|-
| 5020
| 139C
| Rok Krajnc
|-
| 5030
| 13A6
| Tim Tashpulatov
|-
| 5040
| 13B0
| 7-bit
|-
| 5050
| 13BA
| Sakura IT
|-
| 5060
| 13C4
| FPGAArcade
|-
| 5070
| 13CE
| CancerSoft Inc.
|-
| 5080
| 13D8
| Stephen Leary
|-
| 5090
| 13E2
| DMA Softlab LLC
|-
| 5100
| 13EC
| Brookhouse Engineering
|-
| 5110
| 13F6
| Eduardo Arana
|-
| 5120
| 1400
| CS-LAB
|-
| 5130
| 140A
| Robert Miranda
|-
| 5140
| 1414
| RastPort
|-
| 5132
| 140C
| UAS Interface Ltd6
|-
| 5150
| 141E
| Amiga Kit
|-
| 5160
| 1428
| Central Texas Commodore User Group
|-
| 5170
| 1432
| Confusion Research Center
|-
| 5180
| 143C
| Solar Soyuz Zaibatsu
|-
| 5190
| 1446
| BooBip
|-
| 5191
| 1447
| Matthias Hampel
|-
| 5192
| 1448
| dec0de Consulting Ltd.
|-
| 5193
| 1449
| Puppy Concepts
|-
| 5194
| 144A
| Open Amiga Hardware Repository
|-
| 5195
| 144B
| Double H Tech
|-
| 5196
| 144C
| Retromatik
|-
| 5500
| 157C
| Inhouse Information
|-
| 5768
| 1688
| Bio Con
|-
| 6148
| 1804
| HK-Computer
|-
| 6502
| 1966
| Cloanto
|-
| 6520
| 1978
| Oliver Gantert
|-
| 7777
| 1E61
| Rafal Gabriel Chyla
|-
| 8215
| 2017
| Vortex
|-
| 8244
| 2034
| Spirit Technology
|-
| 8290
| 2062
| Expansion Systems
|-
| 8448
| 2100
| ReadySoft
|-
| 8512
| 2140
| Phase 5 Digital Products
|-
| 8553
| 2169
| Digital Processing Systems Inc.
|-
| 8704
| 2200
| ACT Elektronik
|-
| 8738
| 2222
| ACT Elektronik
|-
| 9512
| 2528
| Tower Technologies
|-
| 10676
| 29B4
| Electronic Design
|-
| 14195
| 3773
| Media-net-Point
|-
| 14501
| 38A5
| Petsoff, Finland
|-
| 16375
| 3FF7
| Uwe Gerlach
|-
| 16707
| 4143
| Ateo Concepts
|-
| 16708
| 4144
| ALiENDESiGN
|-
| 16945
| 4231
| A.C.T.
|-
| 17740
| 454C
| HK-Computer (ELSAT)
|-
| 18260
| 4754
| MacroSystems (Germany)
|-
| 19796
| 4D54
| Markt & Technik
|-
| 22359
| 5757
| Markt & Technik
|-
| 26464
| 6760
| Combitec
|-
| 26470
| 6766
| Combitec
|-
| 28014
| 6D6E
| MNT Media and Technology UG
|-
| 32768
| 8000
| M.A.S.T.
|-
| 42240
| A500
| Aethreum Digital
|-
| 43437
| A9AD
| Reis-Ware
|-
| 43521
| AA01
| Cameron
|-
| 43537
| AA11
| Reis-Ware
|-
| 44359
| AD47
| Matay
|-
| 46504
| B5A8
| Phoenix
|-
| 48879
| BEEF
| Swiss Mountain Dog Products
|-
| 49160
| C008
| Combitec
|-
| 61453
| F00D
| Forefront Technologies Inc.
|}

For any changes/additions to this registry see [[#How_to_Obtain_a_Manufacturer_Number|How to Obtain a Manufacturer Number]]

Amiga Hardware Manufacturer ID Registry

2026-09-08T10:31:25Z

Costel Mincea:

__TOC__

= How to Obtain a Manufacturer Number =

Manufacturer's numbers are assigned by the AmigaOS development team. To obtain your unique manufacturer number send a support request to [mailto:support@hyperion-entertainment.com support@hyperion-entertainment.com] including these information:

1. The name of the company or person which the number is assigned to

2. Postal address/contact address

3. Name of the contact person, with a corresponding e-mail address

4. A brief description of the kind of products you want to produce

= Your Manufacturer Number =

Attention hardware manufacturers. If you are developing a hardware expansion product for the Classic Amiga (e.g. 500, 2000, 3000) then you will need to obtain a special manufacturer ID number from the AmigaOS development team to identify your product. This manufacturer number is used by the Amiga to link your hardware with its driver software at boot time.

Your manufacturer number is part of the special protocol that the Amiga uses to automatically configure all expansion devices on the bus without the user having to cut jumpers or adjust dip switches. This is called auto-config.

At start-up time, the system first polls each board in the system and assigns the board its own address space. If it is a memory board, its RAM is linked into the memory free pool. Later in the boot sequence, after DOS is initialized, the binddrivers program is run. Binddrivers will search the directory SYS:Expansion for the drivers that go with the boards.

To do this binddrivers looks in the Tool Type field of all icon files in SYS:Expansion. If the first seven bytes of the Tool Type field are "PRODUCT", then this is an icon file for a driver.

Binddrivers will then attempt to match the drivers it has found with the boards that were found earlier. This is where your manufacturer number comes in.

Your manufacturer number goes in two places. First, it is burned in hex form into the PAL which is part of ALL auto-config expansion products. Second, it appears in ASCII in the Tool Type field of the icon file for your product's driver. By matching these two numbers, the Amiga can automatically configure your board and bind it's software driver into the system as well.

The manufacturer's number is a 16-bit ID which appears in PAL offsets $10-$17. There is also an 8-bit product number which you assign. The product number is for uniquely identifying different products from the same vendor. The product number will appear in PAL offsets $04-$07. This gives you a total of 24 bits to identify each of your products.

These 24 bits of information in the PAL which identify your product are matched against the information in the Tool Type field of all icon files in the SYS:Expansion drawer. For example, suppose you are manufacturer #1019. You have two products, #1 and #2 which both use the same driver. The icon for your driver for these two products would have a Tool Type set to "PRODUCT=1019/1|1019/2". This means: I am an icon for a driver that works with product number 1 or 2 from manufacturer 1019, now bind me. Spaces are not legal. Here are two other examples:

; PRODUCT=1208/11
: is the Tool Type for a driver for product 11 from manufacturer number 1208.

; PRODUCT=1017
: is the Tool Type for a driver for any product from manufacturer number 1017.

For an informal explanation of the auto-configuration process, see the chapter on Software Expansion Architecture from the 2nd Annual Amiga Developer's Conference Notes (available on ADCD 2.1). For the details of timing, power, the PAL equations and PAL address specifications and the expansion library documentation, see sections 3.1 to 3.3 of the A500/A2000 Technical Reference Manual. The original auto-config spec appears in the A1000 Schematics and Expansion Specification.

The auto-config process makes the addition of expansion products to the system very easy. All the user has to do is put the board in any slot and copy the driver from the release disk to his own SYS:Expansion drawer. Everything else is automatic. There are no jumpers or dip switches to set. Best of all, you will get a lot less support calls asking how to make your product work with the XYZ-Corp-battery-backed-clock.

= Notes =

Some notes on hardware manufacturer ID assignment.

* Manufacturer ID numbers are assigned free of charge.
* Please provide the following information when requesting an ID:
*# Name of the company or person
*# Postal address/contact address
*# Name of the contact person, with a corresponding e-mail address
*# A brief description of the kind of products you want to produce
* All ID numbers smaller than 5000 must be considered unsafe because no information exists on which numbers exactly were taken during the time Commodore, Inc. disintegrated.
* ID numbers in the range 8192 to 18841 must be considered unsafe because some hardware developers mistook the numbers assigned to them to be given in hexadecimal format. Hence 0x2000 = 8192 and 0x4999 = 18841.

= Example code =

<syntaxhighlight lang="C" line>
/*-----------------------------------------------*/
/* Here is a short program which will tell you */
/* about the expansion boards configured in your */
/* system without you opening up the machine. */
/* Code by Bill Koester of CATS */
/*-----------------------------------------------*/
#include <libraries/configvars.h>
#include <libraries/expansion.h>

struct ExpansionBase *ExpansionBase;

void cleanup();
void printdev();

int main()
{
struct ConfigDev *MyConfigDev;

/*----------------------------------*/
/* Open the expansion library, */
/* if there is a problem then exit */
/*----------------------------------*/

ExpansionBase =(struct ExpansionBase *) OpenLibrary(EXPANSIONNAME,0);
if(ExpansionBase==NULL)
{
printf("Error opening expansion library!!\n");
cleanup();
exit(0);
}

/*--------------------------------------------*/
/* Use FindConfigDev to get info on the first */
/* expansion board on the list maintained by */
/* Exec. If there are no expansion boards in */
/* the system then exit. */
/*--------------------------------------------*/

MyConfigDev = NULL;

/*--------------------------------------------------*/
/* FindConfigDev(oldConfigDev,manufacturer,product) */
/* oldConfigDev = NULL for the top of the list */
/* manufacturer = -1 for any manufacturer */
/* product = -1 for any product */
/*--------------------------------------------------*/

MyConfigDev = FindConfigDev(NULL,-1,-1);

if(MyConfigDev==NULL)
{
printf("No Configured Devices found!!\n");
cleanup();
exit(0);
}

printdev(MyConfigDev);

/*-----------------------------------*/
/* OK, there is at least one board, */
/* so loop and get the entire list */
/* printing as we go with printdev() */
/*-----------------------------------*/

while(MyConfigDev = FindConfigDev(MyConfigDev,-1,-1))
{
printdev(MyConfigDev);
}
cleanup();
return 0;
}

/*-------------------*/
/* Close up shop... */
/*-------------------*/
void cleanup()
{
if(ExpansionBase)
CloseLibrary(ExpansionBase);
}

/*----------------------------------*/
/* Print out the contents of the */
/* dev structure for this expansion */
/* product. */
/*----------------------------------*/

void printdev(dev)
struct ConfigDev *dev;
{
char buff[200];

printf("Flags = ");
if(dev->cd_Flags==NULL)
printf("NULL ");
if(dev->cd_Flags&CDF_SHUTUP)
printf("CDF_SHUTUP ");
if(dev->cd_Flags&CDF_CONFIGME)
printf("CDF_CONFIGME ");
printf("\n");
printf("Board Address = %x\n",dev->cd_BoardAddr);
printf("Board Size = %d bytes\n",dev->cd_BoardSize);
printf("Slot Address = %d\n",dev->cd_SlotAddr);
printf("Slot Size = %d\n",dev->cd_SlotSize);
printf("Driver code at %x\n",dev->cd_Driver);

printf("er_Type = %x\n",dev->cd_Rom.er_Type);
printf("er_Product = %x\n",dev->cd_Rom.er_Product);
printf("er_Flags = %x\n",dev->cd_Rom.er_Flags);
printf("er_Reserved03 = %x\n",dev->cd_Rom.er_Reserved03);
printf("er_Manufacturer = %x\n",dev->cd_Rom.er_Manufacturer);
printf("er_SerialNumber = %x\n",dev->cd_Rom.er_SerialNumber);
printf("er_InitDiagVec = %x\n",dev->cd_Rom.er_InitDiagVec);
printf("er_Reserved0c = %x\n",dev->cd_Rom.er_Reserved0c);
printf("er_Reserved0d = %x\n",dev->cd_Rom.er_Reserved0d);
printf("er_Reserved0e = %x\n",dev->cd_Rom.er_Reserved0e);
printf("er_Reserved0f = %x\n",dev->cd_Rom.er_Reserved0f);

printf("Hit Return to continue:\n");
gets(buff);
}
</syntaxhighlight>

= Registry =

{| class="wikitable"
! ID (decimal)
! ID (hexadecimal)
! Manufacturer
! Notes
|-
| 1
| 0001
| Micronik
|-
| 211
| 00D3
| Pacific Peripherals/Profex
|-
| 221
| 00DD
| Kupke Computertechnik GmbH
|-
| 256
| 0100
| Memphis
| Originally registered to MacroSystems US
|-
| 512
| 0200
| 3-State Computertechnik
|-
| 513
| 0201
| Commodore (Braunschweig)
|-
| 514
| 0202
| Commodore (West Chester)
|-
| 515
| 0203
| Commodore (West Chester)
| Originally registered to Combitech/Macrosystem
|-
| 756
| 02F4
| Progressive Peripherals & Software
|-
| 767
| 02FF
| Kolff Computer Supplies
|-
| 1001
| 03E9
| Tecmar
|-
| 1002
| 03EA
| Telesys
|-
| 1003
| 03EB
| The Micro-Forge
|-
| 1004
| 03EC
| Kronos/C Ltd.
| Originally registered to Card Co. (Supra)
|-
| 1005
| 03ED
| A-Squared
|-
| 1006
| 03EE
| Comspec Communications
|-
| 1007
| 03EF
| HT Electronics
|-
| 1008
| 03F0
| RDS Software
|-
| 1009
| 03F1
| Anakin Research
|-
| 1010
| 03F2
| MicroBotics
|-
| 1011
| 03F3
| Bob Krauth
|-
| 1012
| 03F4
| Access Associates (Alegra)
|-
| 1013
| 03F5
| Mini Comp Systems Ltd.
|-
| 1014
| 03F6
| Cypress Technology
|-
| 1015
| 03F7
| Fuller Computers
|-
| 1016
| 03F8
| Galaxy Computers
|-
| 1017
| 03F9
| ADA Research
|-
| 1018
| 03FA
| Computer Service Italia
|-
| 1019
| 03FB
| Amigo
|-
| 1020
| 03FC
| Micro-Solutions Inc.
|-
| 1021
| 03FD
| Stacar International
|-
| 1022
| 03FE
| Video Precisions
|-
| 1023
| 03FF
| ASDG, Inc.
|-
| 1025
| 0401
| Ing. Buero Kalawsky
|-
| 1026
| 0402
| Computer Tuning
|-
| 1027
| 0403
| Interplan Unternehmensberatung
|-
| 1028
| 0404
| Imtronics/Memphis
| Originally registered to Peter Ohlich
|-
| 1030
| 0406
| Commodore (Lowell University)
| Originally registered to Productivity Center
|-
| 1041
| 0411
| Design Labs
|-
| 1042
| 0412
| MCS
|-
| 1043
| 0413
| B. J. Freeman
|-
| 1044
| 0414
| Side Effects Inc.
|-
| 1045
| 0415
| Oklahoma Personal Comp.
|-
| 1046
| 0416
| Advanced Micro Innovations
|-
| 1047
| 0417
| Industrial Support Services
|-
| 1048
| 0418
| Technisoft
|-
| 1049
| 0419
| Prolific, Inc.
|-
| 1050
| 041A
| Softeam, Inc.
|-
| 1051
| 041B
| GRC Electronics
|-
| 1052
| 041C
| David Lai
|-
| 1053
| 041D
| Ameristar Technologies
|-
| 1054
| 041E
| Cline Refrigeration
|-
| 1055
| 041F
| Cardiac Pacemakers, Inc.
|-
| 1056
| 0420
| Supra Corp. (Creative Microsystems)
|-
| 1057
| 0421
| Wayne Diener
|-
| 1058
| 0422
| Computer Systems Associates (CSA)
|-
| 1059
| 0423
| Trionix, Inc.
|-
| 1060
| 0424
| David Lucas
|-
| 1061
| 0425
| Analog Precision
| Also assigned to D & L Distributing
|-
| 1267
| 04F3
| RBM Digitaltechnik
|-
| 1282
| 0502
| M-TEC Hardware Design
|-
| 1337
| 0539
| Thomas Stenzel (DaFR34K)
|-
| 1576
| 0628
| Boris Križma
|-
| 1761
| 06E1
| Great Valley Products
|-
| 1803
| 070B
| UAE Amiga Emulator
|-
| 2002
| 07D2
| Mimetics Corp.
|-
| 2003
| 07D3
| ACDA
|-
| 2004
| 07D4
| Finn R. Jacobsen
|-
| 2005
| 07D5
| Elthen Electronics
|-
| 2006
| 07D6
| Nine Tiles Computer Systems Ltd.
|-
| 2007
| 07D7
| Analog Electronics
|-
| 2008
| 07D8
| Bell & Howell
|-
| 2009
| 07D9
| Roland Kochler
|-
| 2010
| 07DA
| Byte Corp.
|-
| 2011
| 07DB
| Reserved
|-
| 2012
| 07DC
| DKB, Inc.
| Previously named Michigan Software
|-
| 2013
| 07DD
| Pacific Peripherals
|-
| 2014
| 07DE
| Sysaphus Software
|-
| 2015
| 07DF
| Digitronics
|-
| 2016
| 07E0
| Akron Systems
|-
| 2017
| 07E1
| Great Valley Products
|-
| 2018
| 07E2
| Calmos
|-
| 2019
| 07E3
| Dover Research
|-
| 2020
| 07E4
| David Krehbiel
|-
| 2021
| 07E5
| Synergy Peripheral Systems
| Also known as California Access
|-
| 2022
| 07E6
| Xetec
|-
| 2023
| 07E7
| Micron Technology
|-
| 2024
| 07E8
| CH Electronics
|-
| 2025
| 07E9
| American Liquid Light
|-
| 2026
| 07EA
| Progressive Peripherals & Software
| Also used by Ateo
|-
| 2027
| 07EB
| Wicat Systems
|-
| 2028
| 07EC
| Applied Systems & Peripherals
|-
| 2029
| 07ED
| Delaware Valley Software
|-
| 2030
| 07EE
| Palomax
|-
| 2031
| 07EF
| Incognito Software
|-
| 2032
| 07F0
| Jadesign
|-
| 2033
| 07F1
| BVR
|-
| 2034
| 07F2
| Spirit Technology
|-
| 2035
| 07F3
| Spirit Technology
|-
| 2036
| 07F4
| Atronic
|-
| 2037
| 07F5
| Scott Karlin
|-
| 2038
| 07F6
| Howitch
|-
| 2039
| 07F7
| Sullivan Brothers Visual Engineers
|-
| 2040
| 07F8
| G I T
|-
| 2041
| 07F9
| Amigo Business Computers
|-
| 2042
| 07FA
| Micro E Ab
|-
| 2043
| 07FB
| Ralph Kruse
|-
| 2044
| 07FC
| Clearpoint Research
|-
| 2045
| 07FD
| Kodiak
|-
| 2046
| 07FE
| BSC
| Originally registered to Phoenix Electronics
|-
| 2047
| 07FF
| No Name Shown
|-
| 2048
| 0800
| Commodore Braunschweig
|-
| 2049
| 0801
| BSC
| Originally registered to Elaborate Bytes
|-
| 2050
| 0802
| Kronos/C Ltd.
|-
| 2051
| 0803
| Spartanics
|-
| 2052
| 0804
| Jochheim Computer Tuning
|-
| 2053
| 0805
| Trans Data Systems
|-
| 2054
| 0806
| Applied Systems & Peripherals Ltd.
|-
| 2055
| 0807
| Checkpoint Technologies
| Originally registered to Amiga Solutions
|-
| 2056
| 0808
| Adept Development
|-
| 2057
| 0809
| Advanced Computer Design
|-
| 2058
| 080A
| Sir Netics
|-
| 2059
| 080B
| Expert Services
|-
| 2060
| 080C
| Digital Art Systems
|-
| 2061
| 080D
| Adept Development
|-
| 2062
| 080E
| Expansion Technologies (Expansion Systems)
|-
| 2063
| 080F
| Alphatech
|-
| 2064
| 0810
| Edotronik GmbH
|-
| 2065
| 0811
| California Access/Synergy
| Originally registered to Logical Design Works
|-
| 2066
| 0812
| Bowden, Williams, Full & Assoc.
|-
| 2067
| 0813
| NES, Inc.
|-
| 2068
| 0814
| Amdev
|-
| 2069
| 0815
| Big Brother Security Systems
|-
| 2070
| 0816
| Active Circuits Inc.
|-
| 2071
| 0817
| ICD, Inc.
|-
| 2072
| 0818
| Multi-Meg Electronique
|-
| 2073
| 0819
| Kupke Computertechnik GmbH
|-
| 2074
| 081A
| The Checkered Ball
|-
| 2075
| 081B
| Hi Tension Computer Services Ltd. (UK)
|-
| 2076
| 081C
| Alfa Data
| Originally assigned to Elmtech Research, Ltd. (UK)
|-
| 2077
| 081D
| Great Valley Products
| Originally registered to Clartscreen, Ltd. (UK)
|-
| 2078
| 081E
| Interworks
|-
| 2079
| 081F
| Galysh Enterprises
|-
| 2080
| 0820
| Hardital Synthesis
| Originally registered to Realtime Games Software Ltd.
|-
| 2081
| 0821
| GBS
|-
| 2082
| 0822
| Circum Design Inc.
|-
| 2083
| 0823
| Alberta Micro Electronic Center
|-
| 2084
| 0824
| Bestech
|-
| 2085
| 0825
| Lasar Fantasy
|-
| 2086
| 0826
| Pulsar
|-
| 2087
| 0827
| Ivis
|-
| 2088
| 0828
| Applied Engineering
|-
| 2089
| 0829
| Solid-State Design & Development
|-
| 2090
| 082A
| Vison Quest
|-
| 2091
| 082B
| Seaview Software
|-
| 2092
| 082C
| BSC
| Mistakenly used by ADS (Advanced Development Software)
|-
| 2093
| 082D
| Bernd Culenfeld
|-
| 2094
| 082E
| American Liquid Light
|-
| 2095
| 082F
| CEGITES
|-
| 2096
| 0830
| Quadlite Computers Ltd.
| Originally registered to EV Industries
|-
| 2097
| 0831
| Silicon Peace
|-
| 2098
| 0832
| Black Belt Systems
|-
| 2099
| 0833
| Village Tronic
| Originally registerd to Steve Yaeger
|-
| 2100
| 0834
| ReadySoft
|-
| 2101
| 0835
| Phoenix Micro Technologies
|-
| 2102
| 0836
| Advanced Systems & Software
| Orignally assigned to Preferred Technology
|-
| 2103
| 0837
| Rombo Productions
|-
| 2104
| 0838
| Impulse Inc.
|-
| 2105
| 0839
| Beta Unlimited
|-
| 2106
| 083A
| Memory Expansion System, Ltd.
|-
| 2107
| 083B
| Vortex Computer Systems GmbH
|-
| 2108
| 083C
| Platypus Systems
|-
| 2109
| 083D
| Gigatron OHG
|-
| 2110
| 083E
| PG Electronics
|-
| 2111
| 083F
| New Technologies Group
|-
| 2112
| 0840
| Interactive Video Systems (IVS)
| Pacific Peripherals
|-
| 2113
| 0841
| Vector
| Originally registered to H. K. Computer
|-
| 2114
| 0842
| Pacific Digital
| Originally registered to C. H. Helfrich Elektronik
|-
| 2115
| 0843
| Xanadu
|-
| 2116
| 0844
| Pacific Digital
| Originally registered to AMS
|-
| 2117
| 0845
| X-Pert
|-
| 2118
| 0846
| The Amiga Centre
|-
| 2119
| 0847
| Digital Pacific
|-
| 2120
| 0848
| Solid State Leisure
|-
| 2121
| 0849
| Hydra Systems
| Originally registered to Analog Electronics
|-
| 2122
| 084A
| Cumana
|-
| 2123
| 084B
| KAPS 2C Conception
|-
| 2124
| 084C
| Mike Mason
|-
| 2125
| 084D
| For Your Eyes
|-
| 2126
| 084E
| Volkmar Breitfeld Computersysteme
|-
| 2127
| 084F
| Sunrize Industries
|-
| 2128
| 0850
| Scott Advanced Micro Designs
|-
| 2129
| 0851
| Digital Micronics
|-
| 2130
| 0852
| Alfa-Laval
|-
| 2131
| 0853
| Multigros A/S
|-
| 2132
| 0854
| Archos
|-
| 2133
| 0855
| Icom Simulations
|-
| 2134
| 0856
| Commodore Test Engineering Group
|-
| 2135
| 0857
| Microcreations
|-
| 2136
| 0858
| Shoestring Productions
|-
| 2137
| 0859
| Faberushi
|-
| 2138
| 085A
| Evesham Micro Ltd.
|-
| 2139
| 085B
| Panagolin Laser Software
|-
| 2140
| 085C
| Thomas Rudloff
|-
| 2141
| 085D
| Daniel Hohabir
|-
| 2142
| 085E
| GfxBase, Inc.
|-
| 2143
| 085F
| Axellabs
|-
| 2144
| 0860
| Roctec Electronics Inc.
|-
| 2145
| 0861
| Omega Datentechnik
|-
| 2146
| 0862
| Atlantis
|-
| 2147
| 0863
| Skytec Computers
|-
| 2148
| 0864
| Protar Electronics
|-
| 2149
| 0865
| ACS
|-
| 2150
| 0866
| Software Results Enterprises
| Originally registered to University of Illinois
|-
| 2151
| 0867
| Infinity Systems Design Group
|-
| 2152
| 0868
| Trade It
|-
| 2153
| 0869
| Suntec, Inc.
|-
| 2154
| 086A
| DJW Micro Systems
| Originally registered to Tritec Marketing
|-
| 2155
| 086B
| Power Computing Ltd.
|-
| 2156
| 086C
| MacroSystems
|-
| 2157
| 086D
| Masoboshi GmbH (DCE)
|-
| 2158
| 086E
| HAL Software Hardware Handel
|-
| 2159
| 086F
| Mainhattan Data
| Originally registered to Michael Lamm Computersysteme
|-
| 2160
| 0870
| Digital Processing System
| Originally registered to bbdp Electronics
|-
| 2161
| 0871
| Blue Ribbon Soundworks
| Originally registered to Design Computer Systems
|-
| 2162
| 0872
| XPert
| Originally registered to The Station
|-
| 2163
| 0873
| DelaComp
| Originally registered to Bryan Williams
|-
| 2164
| 0874
| Superformance Computer Engineering GmbH
|-
| 2165
| 0875
| Overland Engineering
|-
| 2166
| 0876
| Thomas Hamren
|-
| 2167
| 0877
| Village Tronic
|-
| 2168
| 0878
| Toolbox Design
|-
| 2169
| 0879
| Digital Processing System
|-
| 2170
| 087A
| Superformance
|-
| 2171
| 087B
| Utilities Unlimited
|-
| 2172
| 087C
| phase 5
|-
| 2173
| 087D
| Juergen Kommos
|-
| 2174
| 087E
| Electronic Design
|-
| 2175
| 087F
| James Cook University of North Queensland
|-
| 2176
| 0880
| AmiTrix Development
|-
| 2177
| 0881
| Ferranti
|-
| 2178
| 0882
| Leviathan Development
|-
| 2179
| 0883
| United Video Inc.
|-
| 2180
| 0884
| GPSoft Pty. Ltd.
| Originally registered to Juergen Kommos
|-
| 2181
| 0885
| ArMAX
| Oliver Bausch
|-
| 2182
| 0886
| CP Computer
|-
| 2183
| 0887
| AMOK - Amiga Module & Oberon Klub
|-
| 2184
| 0888
| ITEK Neser & Sieber GbR
|-
| 2185
| 0889
| Phillip C. Lello
|-
| 2186
| 088A
| Cyborg Design Services
|-
| 2187
| 088B
| G2 Systems
|-
| 2188
| 088C
| Pro System Computersysteme
|-
| 2189
| 088D
| ZEUS Electronic
| Originally registered to MSPI (Markt & Technik)
|-
| 2190
| 088E
| Altatech
|-
| 2191
| 088F
| NewTek
|-
| 2192
| 0890
| M-TEC Hardware Design
| Originally registered to Hardware Design Udo Neuroth
|-
| 2193
| 0891
| Great Valley Products
| Originally registered to Viona Development
|-
| 2194
| 0892
| Amitek
| Originally assigned to Marpet Developments
|-
| 2195
| 0893
| Ingenieurbuero Helfrich
|-
| 2196
| 0894
| The Neo Group
|-
| 2197
| 0895
| Cyon
|-
| 2198
| 0896
| Bob Research Group
|-
| 2199
| 0897
| Richmond Sound Design Ltd.
|-
| 2200
| 0898
| US Cybernetics
|-
| 2201
| 0899
| Fulvio Ieva
|-
| 2202
| 089A
| Silicon Studio
|-
| 2203
| 089B
| MacroSystems (USA)
| Was named Micro System Devices
|-
| 2204
| 089C
| Conspector Entertainment
|-
| 2205
| 089D
| Laserforum
|-
| 2206
| 089E
| Elbox Computer
| Mistakenly used by Index Information Ltd.
|-
| 2207
| 089F
| Applied Magic Inc.
|-
| 2208
| 08A0
| SDL Ltd.
|-
| 2560
| 0A00
| Harms
|-
| 2588
| 0A1C
| A1K.org Community
|-
| 2640
| 0A50
| Micronik
|-
| 3084
| 0C0C
| Team 4
|-
| 3643
| 0E3B
| E3B
| Michael Boehmer
|-
| 3855
| 0F0F
| Micronik
|-
| 4096
| 1000
| MegaMicro
|-
| 4110
| 100E
| DigiFeX
|-
| 4136
| 1028
| Imtronics/Memphis
|-
| 4149
| 1035
| PROTAR
|-
| 4369
| 1111
| Frank Strauß Elektronik
| Also used by Kupke
|-
| 4626
| 1212
| Individual Computers
|-
| 4648
| 1228
| Flesch Hornemann Computer Elec.
|-
| 4680
| 1248
| Kupke Computertechnik GmbH
|-
| 4711
| 1267
| RBM digitaltechnik
|-
| 4754
| 1292
| MacroSystems
|-
| 5000
| 1388
| ITH
|-
| 5001
| 1389
| VMC
|-
| 5010
| 1392
| Ambience Creation Technology
|-
| 5011
| 1393
| Creative Development
|-
| 5012
| 1394
| Georg Braun
|-
| 5013
| 1395
| Swedish User Group of Amiga
|-
| 5014
| 1396
| Jakub Bednarski
|-
| 5015
| 1397
| KryoFlux, Ltd.
|-
| 5016
| 1398
| Igor Majstorovic
|-
| 5017
| 1399
| Alastair M. Robinson
|-
| 5018
| 139A
| Austex Software
|-
| 5019
| 139B
| Sören Gust
|-
| 5020
| 139C
| Rok Krajnc
|-
| 5030
| 13A6
| Tim Tashpulatov
|-
| 5040
| 13B0
| 7-bit
|-
| 5050
| 13BA
| Sakura IT
|-
| 5060
| 13C4
| FPGAArcade
|-
| 5070
| 13CE
| CancerSoft Inc.
|-
| 5080
| 13D8
| Stephen Leary
|-
| 5090
| 13E2
| DMA Softlab LLC
|-
| 5100
| 13EC
| Brookhouse Engineering
|-
| 5110
| 13F6
| Eduardo Arana
|-
| 5120
| 1400
| CS-LAB
|-
| 5130
| 140A
| Robert Miranda
|-
| 5140
| 1414
| RastPort
|-
| 5132
| 140C
| UAS Interface Ltd6
|-
| 5150
| 141E
| Amiga Kit
|-
| 5160
| 1428
| Central Texas Commodore User Group
|-
| 5170
| 1432
| Confusion Research Center
|-
| 5180
| 143C
| Solar Soyuz Zaibatsu
|-
| 5190
| 1446
| BooBip
|-
| 5191
| 1447
| Matthias Hampel
|-
| 5192
| 1448
| dec0de Consulting Ltd.
|-
| 5193
| 1449
| Puppy Concepts
|-
| 5194
| 144A
| Open Amiga Hardware Repository
|-
| 5195
| 144B
| Double H Tech
|-
| 5196
| 144C
| Retromatik
|-
| 5500
| 157C
| Inhouse Information
|-
| 5768
| 1688
| Bio Con
|-
| 6148
| 1804
| HK-Computer
|-
| 6502
| 1966
| Cloanto
|-
| 6520
| 1978
| Oliver Gantert
|-
| 7777
| 1E61
| Rafal Gabriel Chyla
|-
| 8215
| 2017
| Vortex
|-
| 8244
| 2034
| Spirit Technology
|-
| 8290
| 2062
| Expansion Systems
|-
| 8448
| 2100
| ReadySoft
|-
| 8512
| 2140
| Phase 5 Digital Products
|-
| 8553
| 2169
| Digital Processing Systems Inc.
|-
| 8704
| 2200
| ACT Elektronik
|-
| 8738
| 2222
| ACT Elektronik
|-
| 9512
| 2528
| Tower Technologies
|-
| 10676
| 29B4
| Electronic Design
|-
| 14195
| 3773
| Media-net-Point
|-
| 14501
| 38A5
| Petsoff, Finland
|-
| 16375
| 3FF7
| Uwe Gerlach
|-
| 16707
| 4143
| Ateo Concepts
|-
| 16708
| 4144
| ALiENDESiGN
|-
| 16945
| 4231
| A.C.T.
|-
| 17740
| 454C
| HK-Computer (ELSAT)
|-
| 18260
| 4754
| MacroSystems (Germany)
|-
| 19796
| 4D54
| Markt & Technik
|-
| 22359
| 5757
| Markt & Technik
|-
| 26464
| 6760
| Combitec
|-
| 26470
| 6766
| Combitec
|-
| 28014
| 6D6E
| MNT Media and Technology UG
|-
| 32768
| 8000
| M.A.S.T.
|-
| 42240
| A500
| Aethreum Digital
|-
| 43437
| A9AD
| Reis-Ware
|-
| 43521
| AA01
| Cameron
|-
| 43537
| AA11
| Reis-Ware
|-
| 44359
| AD47
| Matay
|-
| 46504
| B5A8
| Phoenix
|-
| 48879
| BEEF
| Swiss Mountain Dog Products
|-
| 49160
| C008
| Combitec
|-
| 61453
| F00D
| Forefront Technologies Inc.
|}

For any changes/additions to this registry see [[#How_to_Obtain_a_Manufacturer_Number|How to Obtain a Manufacturer Number]]

Amiga Hardware Manufacturer ID Registry

2026-09-08T10:28:02Z

Costel Mincea: /* How to Obtain a Manufacturer Number */

__TOC__

= How to Obtain a Manufacturer Number =

Manufacturer's numbers are assigned by the AmigaOS development team. To obtain your unique manufacturer number send a support request to [mailto:support@hyperion-entertainment.com support@hyperion-entertainment.com] including these information:

1. The name of the company or person which the number is assigned to

2. Postal address/contact address

3. Name of the contact person, with a corresponding e-mail address

4. A brief description of the kind of products you want to produce

= Your Manufacturer Number =

Attention hardware manufacturers. If you are developing a hardware expansion product for the Classic Amiga (e.g. 500, 2000, 3000) then you will need to obtain a special manufacturer ID number from the AmigaOS development team to identify your product. This manufacturer number is used by the Amiga to link your hardware with its driver software at boot time.

Your manufacturer number is part of the special protocol that the Amiga uses to automatically configure all expansion devices on the bus without the user having to cut jumpers or adjust dip switches. This is called auto-config.

At start-up time, the system first polls each board in the system and assigns the board its own address space. If it is a memory board, its RAM is linked into the memory free pool. Later in the boot sequence, after DOS is initialized, the binddrivers program is run. Binddrivers will search the directory SYS:Expansion for the drivers that go with the boards.

To do this binddrivers looks in the Tool Type field of all icon files in SYS:Expansion. If the first seven bytes of the Tool Type field are "PRODUCT", then this is an icon file for a driver.

Binddrivers will then attempt to match the drivers it has found with the boards that were found earlier. This is where your manufacturer number comes in.

Your manufacturer number goes in two places. First, it is burned in hex form into the PAL which is part of ALL auto-config expansion products. Second, it appears in ASCII in the Tool Type field of the icon file for your product's driver. By matching these two numbers, the Amiga can automatically configure your board and bind it's software driver into the system as well.

The manufacturer's number is a 16-bit ID which appears in PAL offsets $10-$17. There is also an 8-bit product number which you assign. The product number is for uniquely identifying different products from the same vendor. The product number will appear in PAL offsets $04-$07. This gives you a total of 24 bits to identify each of your products.

These 24 bits of information in the PAL which identify your product are matched against the information in the Tool Type field of all icon files in the SYS:Expansion drawer. For example, suppose you are manufacturer #1019. You have two products, #1 and #2 which both use the same driver. The icon for your driver for these two products would have a Tool Type set to "PRODUCT=1019/1|1019/2". This means: I am an icon for a driver that works with product number 1 or 2 from manufacturer 1019, now bind me. Spaces are not legal. Here are two other examples:

; PRODUCT=1208/11
: is the Tool Type for a driver for product 11 from manufacturer number 1208.

; PRODUCT=1017
: is the Tool Type for a driver for any product from manufacturer number 1017.

For an informal explanation of the auto-configuration process, see the chapter on Software Expansion Architecture from the 2nd Annual Amiga Developer's Conference Notes (available on ADCD 2.1). For the details of timing, power, the PAL equations and PAL address specifications and the expansion library documentation, see sections 3.1 to 3.3 of the A500/A2000 Technical Reference Manual. The original auto-config spec appears in the A1000 Schematics and Expansion Specification.

The auto-config process makes the addition of expansion products to the system very easy. All the user has to do is put the board in any slot and copy the driver from the release disk to his own SYS:Expansion drawer. Everything else is automatic. There are no jumpers or dip switches to set. Best of all, you will get a lot less support calls asking how to make your product work with the XYZ-Corp-battery-backed-clock.

= Notes =

Some notes on hardware manufacturer ID assignment.

* Manufacturer ID numbers are assigned free of charge.
* Please provide the following information when requesting an ID:
*# Name of the company or person
*# Postal address/contact address
*# Name of the contact person, with a corresponding e-mail address
*# A brief description of the kind of products you want to produce
* All ID numbers smaller than 5000 must be considered unsafe because no information exists on which numbers exactly were taken during the time Commodore, Inc. disintegrated.
* ID numbers in the range 8192 to 18841 must be considered unsafe because some hardware developers mistook the numbers assigned to them to be given in hexadecimal format. Hence 0x2000 = 8192 and 0x4999 = 18841.

= Example code =

<syntaxhighlight lang="C" line>
/*-----------------------------------------------*/
/* Here is a short program which will tell you */
/* about the expansion boards configured in your */
/* system without you opening up the machine. */
/* Code by Bill Koester of CATS */
/*-----------------------------------------------*/
#include <libraries/configvars.h>
#include <libraries/expansion.h>

struct ExpansionBase *ExpansionBase;

void cleanup();
void printdev();

int main()
{
struct ConfigDev *MyConfigDev;

/*----------------------------------*/
/* Open the expansion library, */
/* if there is a problem then exit */
/*----------------------------------*/

ExpansionBase =(struct ExpansionBase *) OpenLibrary(EXPANSIONNAME,0);
if(ExpansionBase==NULL)
{
printf("Error opening expansion library!!\n");
cleanup();
exit(0);
}

/*--------------------------------------------*/
/* Use FindConfigDev to get info on the first */
/* expansion board on the list maintained by */
/* Exec. If there are no expansion boards in */
/* the system then exit. */
/*--------------------------------------------*/

MyConfigDev = NULL;

/*--------------------------------------------------*/
/* FindConfigDev(oldConfigDev,manufacturer,product) */
/* oldConfigDev = NULL for the top of the list */
/* manufacturer = -1 for any manufacturer */
/* product = -1 for any product */
/*--------------------------------------------------*/

MyConfigDev = FindConfigDev(NULL,-1,-1);

if(MyConfigDev==NULL)
{
printf("No Configured Devices found!!\n");
cleanup();
exit(0);
}

printdev(MyConfigDev);

/*-----------------------------------*/
/* OK, there is at least one board, */
/* so loop and get the entire list */
/* printing as we go with printdev() */
/*-----------------------------------*/

while(MyConfigDev = FindConfigDev(MyConfigDev,-1,-1))
{
printdev(MyConfigDev);
}
cleanup();
return 0;
}

/*-------------------*/
/* Close up shop... */
/*-------------------*/
void cleanup()
{
if(ExpansionBase)
CloseLibrary(ExpansionBase);
}

/*----------------------------------*/
/* Print out the contents of the */
/* dev structure for this expansion */
/* product. */
/*----------------------------------*/

void printdev(dev)
struct ConfigDev *dev;
{
char buff[200];

printf("Flags = ");
if(dev->cd_Flags==NULL)
printf("NULL ");
if(dev->cd_Flags&CDF_SHUTUP)
printf("CDF_SHUTUP ");
if(dev->cd_Flags&CDF_CONFIGME)
printf("CDF_CONFIGME ");
printf("\n");
printf("Board Address = %x\n",dev->cd_BoardAddr);
printf("Board Size = %d bytes\n",dev->cd_BoardSize);
printf("Slot Address = %d\n",dev->cd_SlotAddr);
printf("Slot Size = %d\n",dev->cd_SlotSize);
printf("Driver code at %x\n",dev->cd_Driver);

printf("er_Type = %x\n",dev->cd_Rom.er_Type);
printf("er_Product = %x\n",dev->cd_Rom.er_Product);
printf("er_Flags = %x\n",dev->cd_Rom.er_Flags);
printf("er_Reserved03 = %x\n",dev->cd_Rom.er_Reserved03);
printf("er_Manufacturer = %x\n",dev->cd_Rom.er_Manufacturer);
printf("er_SerialNumber = %x\n",dev->cd_Rom.er_SerialNumber);
printf("er_InitDiagVec = %x\n",dev->cd_Rom.er_InitDiagVec);
printf("er_Reserved0c = %x\n",dev->cd_Rom.er_Reserved0c);
printf("er_Reserved0d = %x\n",dev->cd_Rom.er_Reserved0d);
printf("er_Reserved0e = %x\n",dev->cd_Rom.er_Reserved0e);
printf("er_Reserved0f = %x\n",dev->cd_Rom.er_Reserved0f);

printf("Hit Return to continue:\n");
gets(buff);
}
</syntaxhighlight>

= Registry =

{| class="wikitable"
! ID (decimal)
! ID (hexadecimal)
! Manufacturer
! Notes
|-
| 1
| 0001
| Micronik
|-
| 211
| 00D3
| Pacific Peripherals/Profex
|-
| 221
| 00DD
| Kupke Computertechnik GmbH
|-
| 256
| 0100
| Memphis
| Originally registered to MacroSystems US
|-
| 512
| 0200
| 3-State Computertechnik
|-
| 513
| 0201
| Commodore (Braunschweig)
|-
| 514
| 0202
| Commodore (West Chester)
|-
| 515
| 0203
| Commodore (West Chester)
| Originally registered to Combitech/Macrosystem
|-
| 756
| 02F4
| Progressive Peripherals & Software
|-
| 767
| 02FF
| Kolff Computer Supplies
|-
| 1001
| 03E9
| Tecmar
|-
| 1002
| 03EA
| Telesys
|-
| 1003
| 03EB
| The Micro-Forge
|-
| 1004
| 03EC
| Kronos/C Ltd.
| Originally registered to Card Co. (Supra)
|-
| 1005
| 03ED
| A-Squared
|-
| 1006
| 03EE
| Comspec Communications
|-
| 1007
| 03EF
| HT Electronics
|-
| 1008
| 03F0
| RDS Software
|-
| 1009
| 03F1
| Anakin Research
|-
| 1010
| 03F2
| MicroBotics
|-
| 1011
| 03F3
| Bob Krauth
|-
| 1012
| 03F4
| Access Associates (Alegra)
|-
| 1013
| 03F5
| Mini Comp Systems Ltd.
|-
| 1014
| 03F6
| Cypress Technology
|-
| 1015
| 03F7
| Fuller Computers
|-
| 1016
| 03F8
| Galaxy Computers
|-
| 1017
| 03F9
| ADA Research
|-
| 1018
| 03FA
| Computer Service Italia
|-
| 1019
| 03FB
| Amigo
|-
| 1020
| 03FC
| Micro-Solutions Inc.
|-
| 1021
| 03FD
| Stacar International
|-
| 1022
| 03FE
| Video Precisions
|-
| 1023
| 03FF
| ASDG, Inc.
|-
| 1025
| 0401
| Ing. Buero Kalawsky
|-
| 1026
| 0402
| Computer Tuning
|-
| 1027
| 0403
| Interplan Unternehmensberatung
|-
| 1028
| 0404
| Imtronics/Memphis
| Originally registered to Peter Ohlich
|-
| 1030
| 0406
| Commodore (Lowell University)
| Originally registered to Productivity Center
|-
| 1041
| 0411
| Design Labs
|-
| 1042
| 0412
| MCS
|-
| 1043
| 0413
| B. J. Freeman
|-
| 1044
| 0414
| Side Effects Inc.
|-
| 1045
| 0415
| Oklahoma Personal Comp.
|-
| 1046
| 0416
| Advanced Micro Innovations
|-
| 1047
| 0417
| Industrial Support Services
|-
| 1048
| 0418
| Technisoft
|-
| 1049
| 0419
| Prolific, Inc.
|-
| 1050
| 041A
| Softeam, Inc.
|-
| 1051
| 041B
| GRC Electronics
|-
| 1052
| 041C
| David Lai
|-
| 1053
| 041D
| Ameristar Technologies
|-
| 1054
| 041E
| Cline Refrigeration
|-
| 1055
| 041F
| Cardiac Pacemakers, Inc.
|-
| 1056
| 0420
| Supra Corp. (Creative Microsystems)
|-
| 1057
| 0421
| Wayne Diener
|-
| 1058
| 0422
| Computer Systems Associates (CSA)
|-
| 1059
| 0423
| Trionix, Inc.
|-
| 1060
| 0424
| David Lucas
|-
| 1061
| 0425
| Analog Precision
| Also assigned to D & L Distributing
|-
| 1267
| 04F3
| RBM Digitaltechnik
|-
| 1282
| 0502
| M-TEC Hardware Design
|-
| 1337
| 0539
| Thomas Stenzel (DaFR34K)
|-
| 1576
| 0628
| Boris Križma
|-
| 1761
| 06E1
| Great Valley Products
|-
| 1803
| 070B
| UAE Amiga Emulator
|-
| 2002
| 07D2
| Mimetics Corp.
|-
| 2003
| 07D3
| ACDA
|-
| 2004
| 07D4
| Finn R. Jacobsen
|-
| 2005
| 07D5
| Elthen Electronics
|-
| 2006
| 07D6
| Nine Tiles Computer Systems Ltd.
|-
| 2007
| 07D7
| Analog Electronics
|-
| 2008
| 07D8
| Bell & Howell
|-
| 2009
| 07D9
| Roland Kochler
|-
| 2010
| 07DA
| Byte Corp.
|-
| 2011
| 07DB
| Reserved
|-
| 2012
| 07DC
| DKB, Inc.
| Previously named Michigan Software
|-
| 2013
| 07DD
| Pacific Peripherals
|-
| 2014
| 07DE
| Sysaphus Software
|-
| 2015
| 07DF
| Digitronics
|-
| 2016
| 07E0
| Akron Systems
|-
| 2017
| 07E1
| Great Valley Products
|-
| 2018
| 07E2
| Calmos
|-
| 2019
| 07E3
| Dover Research
|-
| 2020
| 07E4
| David Krehbiel
|-
| 2021
| 07E5
| Synergy Peripheral Systems
| Also known as California Access
|-
| 2022
| 07E6
| Xetec
|-
| 2023
| 07E7
| Micron Technology
|-
| 2024
| 07E8
| CH Electronics
|-
| 2025
| 07E9
| American Liquid Light
|-
| 2026
| 07EA
| Progressive Peripherals & Software
| Also used by Ateo
|-
| 2027
| 07EB
| Wicat Systems
|-
| 2028
| 07EC
| Applied Systems & Peripherals
|-
| 2029
| 07ED
| Delaware Valley Software
|-
| 2030
| 07EE
| Palomax
|-
| 2031
| 07EF
| Incognito Software
|-
| 2032
| 07F0
| Jadesign
|-
| 2033
| 07F1
| BVR
|-
| 2034
| 07F2
| Spirit Technology
|-
| 2035
| 07F3
| Spirit Technology
|-
| 2036
| 07F4
| Atronic
|-
| 2037
| 07F5
| Scott Karlin
|-
| 2038
| 07F6
| Howitch
|-
| 2039
| 07F7
| Sullivan Brothers Visual Engineers
|-
| 2040
| 07F8
| G I T
|-
| 2041
| 07F9
| Amigo Business Computers
|-
| 2042
| 07FA
| Micro E Ab
|-
| 2043
| 07FB
| Ralph Kruse
|-
| 2044
| 07FC
| Clearpoint Research
|-
| 2045
| 07FD
| Kodiak
|-
| 2046
| 07FE
| BSC
| Originally registered to Phoenix Electronics
|-
| 2047
| 07FF
| No Name Shown
|-
| 2048
| 0800
| Commodore Braunschweig
|-
| 2049
| 0801
| BSC
| Originally registered to Elaborate Bytes
|-
| 2050
| 0802
| Kronos/C Ltd.
|-
| 2051
| 0803
| Spartanics
|-
| 2052
| 0804
| Jochheim Computer Tuning
|-
| 2053
| 0805
| Trans Data Systems
|-
| 2054
| 0806
| Applied Systems & Peripherals Ltd.
|-
| 2055
| 0807
| Checkpoint Technologies
| Originally registered to Amiga Solutions
|-
| 2056
| 0808
| Adept Development
|-
| 2057
| 0809
| Advanced Computer Design
|-
| 2058
| 080A
| Sir Netics
|-
| 2059
| 080B
| Expert Services
|-
| 2060
| 080C
| Digital Art Systems
|-
| 2061
| 080D
| Adept Development
|-
| 2062
| 080E
| Expansion Technologies (Expansion Systems)
|-
| 2063
| 080F
| Alphatech
|-
| 2064
| 0810
| Edotronik GmbH
|-
| 2065
| 0811
| California Access/Synergy
| Originally registered to Logical Design Works
|-
| 2066
| 0812
| Bowden, Williams, Full & Assoc.
|-
| 2067
| 0813
| NES, Inc.
|-
| 2068
| 0814
| Amdev
|-
| 2069
| 0815
| Big Brother Security Systems
|-
| 2070
| 0816
| Active Circuits Inc.
|-
| 2071
| 0817
| ICD, Inc.
|-
| 2072
| 0818
| Multi-Meg Electronique
|-
| 2073
| 0819
| Kupke Computertechnik GmbH
|-
| 2074
| 081A
| The Checkered Ball
|-
| 2075
| 081B
| Hi Tension Computer Services Ltd. (UK)
|-
| 2076
| 081C
| Alfa Data
| Originally assigned to Elmtech Research, Ltd. (UK)
|-
| 2077
| 081D
| Great Valley Products
| Originally registered to Clartscreen, Ltd. (UK)
|-
| 2078
| 081E
| Interworks
|-
| 2079
| 081F
| Galysh Enterprises
|-
| 2080
| 0820
| Hardital Synthesis
| Originally registered to Realtime Games Software Ltd.
|-
| 2081
| 0821
| GBS
|-
| 2082
| 0822
| Circum Design Inc.
|-
| 2083
| 0823
| Alberta Micro Electronic Center
|-
| 2084
| 0824
| Bestech
|-
| 2085
| 0825
| Lasar Fantasy
|-
| 2086
| 0826
| Pulsar
|-
| 2087
| 0827
| Ivis
|-
| 2088
| 0828
| Applied Engineering
|-
| 2089
| 0829
| Solid-State Design & Development
|-
| 2090
| 082A
| Vison Quest
|-
| 2091
| 082B
| Seaview Software
|-
| 2092
| 082C
| BSC
| Mistakenly used by ADS (Advanced Development Software)
|-
| 2093
| 082D
| Bernd Culenfeld
|-
| 2094
| 082E
| American Liquid Light
|-
| 2095
| 082F
| CEGITES
|-
| 2096
| 0830
| Quadlite Computers Ltd.
| Originally registered to EV Industries
|-
| 2097
| 0831
| Silicon Peace
|-
| 2098
| 0832
| Black Belt Systems
|-
| 2099
| 0833
| Village Tronic
| Originally registerd to Steve Yaeger
|-
| 2100
| 0834
| ReadySoft
|-
| 2101
| 0835
| Phoenix Micro Technologies
|-
| 2102
| 0836
| Advanced Systems & Software
| Orignally assigned to Preferred Technology
|-
| 2103
| 0837
| Rombo Productions
|-
| 2104
| 0838
| Impulse Inc.
|-
| 2105
| 0839
| Beta Unlimited
|-
| 2106
| 083A
| Memory Expansion System, Ltd.
|-
| 2107
| 083B
| Vortex Computer Systems GmbH
|-
| 2108
| 083C
| Platypus Systems
|-
| 2109
| 083D
| Gigatron OHG
|-
| 2110
| 083E
| PG Electronics
|-
| 2111
| 083F
| New Technologies Group
|-
| 2112
| 0840
| Interactive Video Systems (IVS)
| Pacific Peripherals
|-
| 2113
| 0841
| Vector
| Originally registered to H. K. Computer
|-
| 2114
| 0842
| Pacific Digital
| Originally registered to C. H. Helfrich Elektronik
|-
| 2115
| 0843
| Xanadu
|-
| 2116
| 0844
| Pacific Digital
| Originally registered to AMS
|-
| 2117
| 0845
| X-Pert
|-
| 2118
| 0846
| The Amiga Centre
|-
| 2119
| 0847
| Digital Pacific
|-
| 2120
| 0848
| Solid State Leisure
|-
| 2121
| 0849
| Hydra Systems
| Originally registered to Analog Electronics
|-
| 2122
| 084A
| Cumana
|-
| 2123
| 084B
| KAPS 2C Conception
|-
| 2124
| 084C
| Mike Mason
|-
| 2125
| 084D
| For Your Eyes
|-
| 2126
| 084E
| Volkmar Breitfeld Computersysteme
|-
| 2127
| 084F
| Sunrize Industries
|-
| 2128
| 0850
| Scott Advanced Micro Designs
|-
| 2129
| 0851
| Digital Micronics
|-
| 2130
| 0852
| Alfa-Laval
|-
| 2131
| 0853
| Multigros A/S
|-
| 2132
| 0854
| Archos
|-
| 2133
| 0855
| Icom Simulations
|-
| 2134
| 0856
| Commodore Test Engineering Group
|-
| 2135
| 0857
| Microcreations
|-
| 2136
| 0858
| Shoestring Productions
|-
| 2137
| 0859
| Faberushi
|-
| 2138
| 085A
| Evesham Micro Ltd.
|-
| 2139
| 085B
| Panagolin Laser Software
|-
| 2140
| 085C
| Thomas Rudloff
|-
| 2141
| 085D
| Daniel Hohabir
|-
| 2142
| 085E
| GfxBase, Inc.
|-
| 2143
| 085F
| Axellabs
|-
| 2144
| 0860
| Roctec Electronics Inc.
|-
| 2145
| 0861
| Omega Datentechnik
|-
| 2146
| 0862
| Atlantis
|-
| 2147
| 0863
| Skytec Computers
|-
| 2148
| 0864
| Protar Electronics
|-
| 2149
| 0865
| ACS
|-
| 2150
| 0866
| Software Results Enterprises
| Originally registered to University of Illinois
|-
| 2151
| 0867
| Infinity Systems Design Group
|-
| 2152
| 0868
| Trade It
|-
| 2153
| 0869
| Suntec, Inc.
|-
| 2154
| 086A
| DJW Micro Systems
| Originally registered to Tritec Marketing
|-
| 2155
| 086B
| Power Computing Ltd.
|-
| 2156
| 086C
| MacroSystems
|-
| 2157
| 086D
| Masoboshi GmbH (DCE)
|-
| 2158
| 086E
| HAL Software Hardware Handel
|-
| 2159
| 086F
| Mainhattan Data
| Originally registered to Michael Lamm Computersysteme
|-
| 2160
| 0870
| Digital Processing System
| Originally registered to bbdp Electronics
|-
| 2161
| 0871
| Blue Ribbon Soundworks
| Originally registered to Design Computer Systems
|-
| 2162
| 0872
| XPert
| Originally registered to The Station
|-
| 2163
| 0873
| DelaComp
| Originally registered to Bryan Williams
|-
| 2164
| 0874
| Superformance Computer Engineering GmbH
|-
| 2165
| 0875
| Overland Engineering
|-
| 2166
| 0876
| Thomas Hamren
|-
| 2167
| 0877
| Village Tronic
|-
| 2168
| 0878
| Toolbox Design
|-
| 2169
| 0879
| Digital Processing System
|-
| 2170
| 087A
| Superformance
|-
| 2171
| 087B
| Utilities Unlimited
|-
| 2172
| 087C
| phase 5
|-
| 2173
| 087D
| Juergen Kommos
|-
| 2174
| 087E
| Electronic Design
|-
| 2175
| 087F
| James Cook University of North Queensland
|-
| 2176
| 0880
| AmiTrix Development
|-
| 2177
| 0881
| Ferranti
|-
| 2178
| 0882
| Leviathan Development
|-
| 2179
| 0883
| United Video Inc.
|-
| 2180
| 0884
| GPSoft Pty. Ltd.
| Originally registered to Juergen Kommos
|-
| 2181
| 0885
| ArMAX
| Oliver Bausch
|-
| 2182
| 0886
| CP Computer
|-
| 2183
| 0887
| AMOK - Amiga Module & Oberon Klub
|-
| 2184
| 0888
| ITEK Neser & Sieber GbR
|-
| 2185
| 0889
| Phillip C. Lello
|-
| 2186
| 088A
| Cyborg Design Services
|-
| 2187
| 088B
| G2 Systems
|-
| 2188
| 088C
| Pro System Computersysteme
|-
| 2189
| 088D
| ZEUS Electronic
| Originally registered to MSPI (Markt & Technik)
|-
| 2190
| 088E
| Altatech
|-
| 2191
| 088F
| NewTek
|-
| 2192
| 0890
| M-TEC Hardware Design
| Originally registered to Hardware Design Udo Neuroth
|-
| 2193
| 0891
| Great Valley Products
| Originally registered to Viona Development
|-
| 2194
| 0892
| Amitek
| Originally assigned to Marpet Developments
|-
| 2195
| 0893
| Ingenieurbuero Helfrich
|-
| 2196
| 0894
| The Neo Group
|-
| 2197
| 0895
| Cyon
|-
| 2198
| 0896
| Bob Research Group
|-
| 2199
| 0897
| Richmond Sound Design Ltd.
|-
| 2200
| 0898
| US Cybernetics
|-
| 2201
| 0899
| Fulvio Ieva
|-
| 2202
| 089A
| Silicon Studio
|-
| 2203
| 089B
| MacroSystems (USA)
| Was named Micro System Devices
|-
| 2204
| 089C
| Conspector Entertainment
|-
| 2205
| 089D
| Laserforum
|-
| 2206
| 089E
| Elbox Computer
| Mistakenly used by Index Information Ltd.
|-
| 2207
| 089F
| Applied Magic Inc.
|-
| 2208
| 08A0
| SDL Ltd.
|-
| 2560
| 0A00
| Harms
|-
| 2588
| 0A1C
| A1K.org Community
|-
| 2640
| 0A50
| Micronik
|-
| 3084
| 0C0C
| Team 4
|-
| 3643
| 0E3B
| E3B
| Michael Boehmer
|-
| 3855
| 0F0F
| Micronik
|-
| 4096
| 1000
| MegaMicro
|-
| 4110
| 100E
| DigiFeX
|-
| 4136
| 1028
| Imtronics/Memphis
|-
| 4149
| 1035
| PROTAR
|-
| 4369
| 1111
| Frank Strauß Elektronik
| Also used by Kupke
|-
| 4626
| 1212
| Individual Computers
|-
| 4648
| 1228
| Flesch Hornemann Computer Elec.
|-
| 4680
| 1248
| Kupke Computertechnik GmbH
|-
| 4711
| 1267
| RBM digitaltechnik
|-
| 4754
| 1292
| MacroSystems
|-
| 5000
| 1388
| ITH
|-
| 5001
| 1389
| VMC
|-
| 5010
| 1392
| Ambience Creation Technology
|-
| 5011
| 1393
| Creative Development
|-
| 5012
| 1394
| Georg Braun
|-
| 5013
| 1395
| Swedish User Group of Amiga
|-
| 5014
| 1396
| Jakub Bednarski
|-
| 5015
| 1397
| KryoFlux, Ltd.
|-
| 5016
| 1398
| Igor Majstorovic
|-
| 5017
| 1399
| Alastair M. Robinson
|-
| 5018
| 139A
| Austex Software
|-
| 5019
| 139B
| Sören Gust
|-
| 5020
| 139C
| Rok Krajnc
|-
| 5030
| 13A6
| Tim Tashpulatov
|-
| 5040
| 13B0
| 7-bit
|-
| 5050
| 13BA
| Sakura IT
|-
| 5060
| 13C4
| FPGAArcade
|-
| 5070
| 13CE
| CancerSoft Inc.
|-
| 5080
| 13D8
| Stephen Leary
|-
| 5090
| 13E2
| DMA Softlab LLC
|-
| 5100
| 13EC
| Brookhouse Engineering
|-
| 5110
| 13F6
| Eduardo Arana
|-
| 5120
| 1400
| CS-LAB
|-
| 5130
| 140A
| Robert Miranda
|-
| 5140
| 1414
| RastPort
|-
| 5132
| 140C
| UAS Interface Ltd6
|-
| 5150
| 141E
| Amiga Kit
|-
| 5160
| 1428
| Central Texas Commodore User Group
|-
| 5170
| 1432
| Confusion Research Center
|-
| 5180
| 143C
| Solar Soyuz Zaibatsu
|-
| 5190
| 1446
| BooBip
|-
| 5191
| 1447
| Matthias Hampel
|-
| 5192
| 1448
| dec0de Consulting Ltd.
|-
| 5193
| 1449
| Puppy Concepts
|-
| 5194
| 144A
| Open Amiga Hardware Repository
|-
| 5195
| 144B
| Double H Tech
|-
| 5196
| 144C
| Retromatik
|-
| 5500
| 157C
| Inhouse Information
|-
| 5768
| 1688
| Bio Con
|-
| 6148
| 1804
| HK-Computer
|-
| 6502
| 1966
| Cloanto
|-
| 6520
| 1978
| Oliver Gantert
|-
| 7777
| 1E61
| Rafal Gabriel Chyla
|-
| 8215
| 2017
| Vortex
|-
| 8244
| 2034
| Spirit Technology
|-
| 8290
| 2062
| Expansion Systems
|-
| 8448
| 2100
| ReadySoft
|-
| 8512
| 2140
| Phase 5 Digital Products
|-
| 8553
| 2169
| Digital Processing Systems Inc.
|-
| 8704
| 2200
| ACT Elektronik
|-
| 8738
| 2222
| ACT Elektronik
|-
| 9512
| 2528
| Tower Technologies
|-
| 10676
| 29B4
| Electronic Design
|-
| 14195
| 3773
| Media-net-Point
|-
| 14501
| 38A5
| Petsoff, Finland
|-
| 16375
| 3FF7
| Uwe Gerlach
|-
| 16707
| 4143
| Ateo Concepts
|-
| 16708
| 4144
| ALiENDESiGN
|-
| 16945
| 4231
| A.C.T.
|-
| 17740
| 454C
| HK-Computer (ELSAT)
|-
| 18260
| 4754
| MacroSystems (Germany)
|-
| 19796
| 4D54
| Markt & Technik
|-
| 22359
| 5757
| Markt & Technik
|-
| 26464
| 6760
| Combitec
|-
| 26470
| 6766
| Combitec
|-
| 28014
| 6D6E
| MNT Media and Technology UG
|-
| 32768
| 8000
| M.A.S.T.
|-
| 42240
| A500
| Aethreum Digital
|-
| 43437
| A9AD
| Reis-Ware
|-
| 43521
| AA01
| Cameron
|-
| 43537
| AA11
| Reis-Ware
|-
| 44359
| AD47
| Matay
|-
| 46504
| B5A8
| Phoenix
|-
| 48879
| BEEF
| Swiss Mountain Dog Products
|-
| 49160
| C008
| Combitec
|-
| 61453
| F00D
| Forefront Technologies Inc.
|}

For any changes/additions to this registry please send a support request to [mailto:support@hyperion-entertainment.com support@hyperion-entertainment.com].

Amiga Hardware Manufacturer ID Registry

2026-09-08T10:27:48Z

Costel Mincea: /* How to Obtain a Manufacturer Number */

__TOC__

= How to Obtain a Manufacturer Number =

Manufacturer's numbers are assigned by the AmigaOS development team. To obtain your unique manufacturer number send a support request to [mailto:support@hyperion-entertainment.com support@hyperion-entertainment.com] including these information:

1. The name of the company or person which the number is assigned to

2. Postal address/contact address

3. Name of the contact person, with a corresponding e-mail address

4. A brief description of the kind of products you want to produce

Be sure and include your name and the type of expansion product you are developing.

= Your Manufacturer Number =

Attention hardware manufacturers. If you are developing a hardware expansion product for the Classic Amiga (e.g. 500, 2000, 3000) then you will need to obtain a special manufacturer ID number from the AmigaOS development team to identify your product. This manufacturer number is used by the Amiga to link your hardware with its driver software at boot time.

Your manufacturer number is part of the special protocol that the Amiga uses to automatically configure all expansion devices on the bus without the user having to cut jumpers or adjust dip switches. This is called auto-config.

At start-up time, the system first polls each board in the system and assigns the board its own address space. If it is a memory board, its RAM is linked into the memory free pool. Later in the boot sequence, after DOS is initialized, the binddrivers program is run. Binddrivers will search the directory SYS:Expansion for the drivers that go with the boards.

To do this binddrivers looks in the Tool Type field of all icon files in SYS:Expansion. If the first seven bytes of the Tool Type field are "PRODUCT", then this is an icon file for a driver.

Binddrivers will then attempt to match the drivers it has found with the boards that were found earlier. This is where your manufacturer number comes in.

Your manufacturer number goes in two places. First, it is burned in hex form into the PAL which is part of ALL auto-config expansion products. Second, it appears in ASCII in the Tool Type field of the icon file for your product's driver. By matching these two numbers, the Amiga can automatically configure your board and bind it's software driver into the system as well.

The manufacturer's number is a 16-bit ID which appears in PAL offsets $10-$17. There is also an 8-bit product number which you assign. The product number is for uniquely identifying different products from the same vendor. The product number will appear in PAL offsets $04-$07. This gives you a total of 24 bits to identify each of your products.

These 24 bits of information in the PAL which identify your product are matched against the information in the Tool Type field of all icon files in the SYS:Expansion drawer. For example, suppose you are manufacturer #1019. You have two products, #1 and #2 which both use the same driver. The icon for your driver for these two products would have a Tool Type set to "PRODUCT=1019/1|1019/2". This means: I am an icon for a driver that works with product number 1 or 2 from manufacturer 1019, now bind me. Spaces are not legal. Here are two other examples:

; PRODUCT=1208/11
: is the Tool Type for a driver for product 11 from manufacturer number 1208.

; PRODUCT=1017
: is the Tool Type for a driver for any product from manufacturer number 1017.

For an informal explanation of the auto-configuration process, see the chapter on Software Expansion Architecture from the 2nd Annual Amiga Developer's Conference Notes (available on ADCD 2.1). For the details of timing, power, the PAL equations and PAL address specifications and the expansion library documentation, see sections 3.1 to 3.3 of the A500/A2000 Technical Reference Manual. The original auto-config spec appears in the A1000 Schematics and Expansion Specification.

The auto-config process makes the addition of expansion products to the system very easy. All the user has to do is put the board in any slot and copy the driver from the release disk to his own SYS:Expansion drawer. Everything else is automatic. There are no jumpers or dip switches to set. Best of all, you will get a lot less support calls asking how to make your product work with the XYZ-Corp-battery-backed-clock.

= Notes =

Some notes on hardware manufacturer ID assignment.

* Manufacturer ID numbers are assigned free of charge.
* Please provide the following information when requesting an ID:
*# Name of the company or person
*# Postal address/contact address
*# Name of the contact person, with a corresponding e-mail address
*# A brief description of the kind of products you want to produce
* All ID numbers smaller than 5000 must be considered unsafe because no information exists on which numbers exactly were taken during the time Commodore, Inc. disintegrated.
* ID numbers in the range 8192 to 18841 must be considered unsafe because some hardware developers mistook the numbers assigned to them to be given in hexadecimal format. Hence 0x2000 = 8192 and 0x4999 = 18841.

= Example code =

<syntaxhighlight lang="C" line>
/*-----------------------------------------------*/
/* Here is a short program which will tell you */
/* about the expansion boards configured in your */
/* system without you opening up the machine. */
/* Code by Bill Koester of CATS */
/*-----------------------------------------------*/
#include <libraries/configvars.h>
#include <libraries/expansion.h>

struct ExpansionBase *ExpansionBase;

void cleanup();
void printdev();

int main()
{
struct ConfigDev *MyConfigDev;

/*----------------------------------*/
/* Open the expansion library, */
/* if there is a problem then exit */
/*----------------------------------*/

ExpansionBase =(struct ExpansionBase *) OpenLibrary(EXPANSIONNAME,0);
if(ExpansionBase==NULL)
{
printf("Error opening expansion library!!\n");
cleanup();
exit(0);
}

/*--------------------------------------------*/
/* Use FindConfigDev to get info on the first */
/* expansion board on the list maintained by */
/* Exec. If there are no expansion boards in */
/* the system then exit. */
/*--------------------------------------------*/

MyConfigDev = NULL;

/*--------------------------------------------------*/
/* FindConfigDev(oldConfigDev,manufacturer,product) */
/* oldConfigDev = NULL for the top of the list */
/* manufacturer = -1 for any manufacturer */
/* product = -1 for any product */
/*--------------------------------------------------*/

MyConfigDev = FindConfigDev(NULL,-1,-1);

if(MyConfigDev==NULL)
{
printf("No Configured Devices found!!\n");
cleanup();
exit(0);
}

printdev(MyConfigDev);

/*-----------------------------------*/
/* OK, there is at least one board, */
/* so loop and get the entire list */
/* printing as we go with printdev() */
/*-----------------------------------*/

while(MyConfigDev = FindConfigDev(MyConfigDev,-1,-1))
{
printdev(MyConfigDev);
}
cleanup();
return 0;
}

/*-------------------*/
/* Close up shop... */
/*-------------------*/
void cleanup()
{
if(ExpansionBase)
CloseLibrary(ExpansionBase);
}

/*----------------------------------*/
/* Print out the contents of the */
/* dev structure for this expansion */
/* product. */
/*----------------------------------*/

void printdev(dev)
struct ConfigDev *dev;
{
char buff[200];

printf("Flags = ");
if(dev->cd_Flags==NULL)
printf("NULL ");
if(dev->cd_Flags&CDF_SHUTUP)
printf("CDF_SHUTUP ");
if(dev->cd_Flags&CDF_CONFIGME)
printf("CDF_CONFIGME ");
printf("\n");
printf("Board Address = %x\n",dev->cd_BoardAddr);
printf("Board Size = %d bytes\n",dev->cd_BoardSize);
printf("Slot Address = %d\n",dev->cd_SlotAddr);
printf("Slot Size = %d\n",dev->cd_SlotSize);
printf("Driver code at %x\n",dev->cd_Driver);

printf("er_Type = %x\n",dev->cd_Rom.er_Type);
printf("er_Product = %x\n",dev->cd_Rom.er_Product);
printf("er_Flags = %x\n",dev->cd_Rom.er_Flags);
printf("er_Reserved03 = %x\n",dev->cd_Rom.er_Reserved03);
printf("er_Manufacturer = %x\n",dev->cd_Rom.er_Manufacturer);
printf("er_SerialNumber = %x\n",dev->cd_Rom.er_SerialNumber);
printf("er_InitDiagVec = %x\n",dev->cd_Rom.er_InitDiagVec);
printf("er_Reserved0c = %x\n",dev->cd_Rom.er_Reserved0c);
printf("er_Reserved0d = %x\n",dev->cd_Rom.er_Reserved0d);
printf("er_Reserved0e = %x\n",dev->cd_Rom.er_Reserved0e);
printf("er_Reserved0f = %x\n",dev->cd_Rom.er_Reserved0f);

printf("Hit Return to continue:\n");
gets(buff);
}
</syntaxhighlight>

= Registry =

{| class="wikitable"
! ID (decimal)
! ID (hexadecimal)
! Manufacturer
! Notes
|-
| 1
| 0001
| Micronik
|-
| 211
| 00D3
| Pacific Peripherals/Profex
|-
| 221
| 00DD
| Kupke Computertechnik GmbH
|-
| 256
| 0100
| Memphis
| Originally registered to MacroSystems US
|-
| 512
| 0200
| 3-State Computertechnik
|-
| 513
| 0201
| Commodore (Braunschweig)
|-
| 514
| 0202
| Commodore (West Chester)
|-
| 515
| 0203
| Commodore (West Chester)
| Originally registered to Combitech/Macrosystem
|-
| 756
| 02F4
| Progressive Peripherals & Software
|-
| 767
| 02FF
| Kolff Computer Supplies
|-
| 1001
| 03E9
| Tecmar
|-
| 1002
| 03EA
| Telesys
|-
| 1003
| 03EB
| The Micro-Forge
|-
| 1004
| 03EC
| Kronos/C Ltd.
| Originally registered to Card Co. (Supra)
|-
| 1005
| 03ED
| A-Squared
|-
| 1006
| 03EE
| Comspec Communications
|-
| 1007
| 03EF
| HT Electronics
|-
| 1008
| 03F0
| RDS Software
|-
| 1009
| 03F1
| Anakin Research
|-
| 1010
| 03F2
| MicroBotics
|-
| 1011
| 03F3
| Bob Krauth
|-
| 1012
| 03F4
| Access Associates (Alegra)
|-
| 1013
| 03F5
| Mini Comp Systems Ltd.
|-
| 1014
| 03F6
| Cypress Technology
|-
| 1015
| 03F7
| Fuller Computers
|-
| 1016
| 03F8
| Galaxy Computers
|-
| 1017
| 03F9
| ADA Research
|-
| 1018
| 03FA
| Computer Service Italia
|-
| 1019
| 03FB
| Amigo
|-
| 1020
| 03FC
| Micro-Solutions Inc.
|-
| 1021
| 03FD
| Stacar International
|-
| 1022
| 03FE
| Video Precisions
|-
| 1023
| 03FF
| ASDG, Inc.
|-
| 1025
| 0401
| Ing. Buero Kalawsky
|-
| 1026
| 0402
| Computer Tuning
|-
| 1027
| 0403
| Interplan Unternehmensberatung
|-
| 1028
| 0404
| Imtronics/Memphis
| Originally registered to Peter Ohlich
|-
| 1030
| 0406
| Commodore (Lowell University)
| Originally registered to Productivity Center
|-
| 1041
| 0411
| Design Labs
|-
| 1042
| 0412
| MCS
|-
| 1043
| 0413
| B. J. Freeman
|-
| 1044
| 0414
| Side Effects Inc.
|-
| 1045
| 0415
| Oklahoma Personal Comp.
|-
| 1046
| 0416
| Advanced Micro Innovations
|-
| 1047
| 0417
| Industrial Support Services
|-
| 1048
| 0418
| Technisoft
|-
| 1049
| 0419
| Prolific, Inc.
|-
| 1050
| 041A
| Softeam, Inc.
|-
| 1051
| 041B
| GRC Electronics
|-
| 1052
| 041C
| David Lai
|-
| 1053
| 041D
| Ameristar Technologies
|-
| 1054
| 041E
| Cline Refrigeration
|-
| 1055
| 041F
| Cardiac Pacemakers, Inc.
|-
| 1056
| 0420
| Supra Corp. (Creative Microsystems)
|-
| 1057
| 0421
| Wayne Diener
|-
| 1058
| 0422
| Computer Systems Associates (CSA)
|-
| 1059
| 0423
| Trionix, Inc.
|-
| 1060
| 0424
| David Lucas
|-
| 1061
| 0425
| Analog Precision
| Also assigned to D & L Distributing
|-
| 1267
| 04F3
| RBM Digitaltechnik
|-
| 1282
| 0502
| M-TEC Hardware Design
|-
| 1337
| 0539
| Thomas Stenzel (DaFR34K)
|-
| 1576
| 0628
| Boris Križma
|-
| 1761
| 06E1
| Great Valley Products
|-
| 1803
| 070B
| UAE Amiga Emulator
|-
| 2002
| 07D2
| Mimetics Corp.
|-
| 2003
| 07D3
| ACDA
|-
| 2004
| 07D4
| Finn R. Jacobsen
|-
| 2005
| 07D5
| Elthen Electronics
|-
| 2006
| 07D6
| Nine Tiles Computer Systems Ltd.
|-
| 2007
| 07D7
| Analog Electronics
|-
| 2008
| 07D8
| Bell & Howell
|-
| 2009
| 07D9
| Roland Kochler
|-
| 2010
| 07DA
| Byte Corp.
|-
| 2011
| 07DB
| Reserved
|-
| 2012
| 07DC
| DKB, Inc.
| Previously named Michigan Software
|-
| 2013
| 07DD
| Pacific Peripherals
|-
| 2014
| 07DE
| Sysaphus Software
|-
| 2015
| 07DF
| Digitronics
|-
| 2016
| 07E0
| Akron Systems
|-
| 2017
| 07E1
| Great Valley Products
|-
| 2018
| 07E2
| Calmos
|-
| 2019
| 07E3
| Dover Research
|-
| 2020
| 07E4
| David Krehbiel
|-
| 2021
| 07E5
| Synergy Peripheral Systems
| Also known as California Access
|-
| 2022
| 07E6
| Xetec
|-
| 2023
| 07E7
| Micron Technology
|-
| 2024
| 07E8
| CH Electronics
|-
| 2025
| 07E9
| American Liquid Light
|-
| 2026
| 07EA
| Progressive Peripherals & Software
| Also used by Ateo
|-
| 2027
| 07EB
| Wicat Systems
|-
| 2028
| 07EC
| Applied Systems & Peripherals
|-
| 2029
| 07ED
| Delaware Valley Software
|-
| 2030
| 07EE
| Palomax
|-
| 2031
| 07EF
| Incognito Software
|-
| 2032
| 07F0
| Jadesign
|-
| 2033
| 07F1
| BVR
|-
| 2034
| 07F2
| Spirit Technology
|-
| 2035
| 07F3
| Spirit Technology
|-
| 2036
| 07F4
| Atronic
|-
| 2037
| 07F5
| Scott Karlin
|-
| 2038
| 07F6
| Howitch
|-
| 2039
| 07F7
| Sullivan Brothers Visual Engineers
|-
| 2040
| 07F8
| G I T
|-
| 2041
| 07F9
| Amigo Business Computers
|-
| 2042
| 07FA
| Micro E Ab
|-
| 2043
| 07FB
| Ralph Kruse
|-
| 2044
| 07FC
| Clearpoint Research
|-
| 2045
| 07FD
| Kodiak
|-
| 2046
| 07FE
| BSC
| Originally registered to Phoenix Electronics
|-
| 2047
| 07FF
| No Name Shown
|-
| 2048
| 0800
| Commodore Braunschweig
|-
| 2049
| 0801
| BSC
| Originally registered to Elaborate Bytes
|-
| 2050
| 0802
| Kronos/C Ltd.
|-
| 2051
| 0803
| Spartanics
|-
| 2052
| 0804
| Jochheim Computer Tuning
|-
| 2053
| 0805
| Trans Data Systems
|-
| 2054
| 0806
| Applied Systems & Peripherals Ltd.
|-
| 2055
| 0807
| Checkpoint Technologies
| Originally registered to Amiga Solutions
|-
| 2056
| 0808
| Adept Development
|-
| 2057
| 0809
| Advanced Computer Design
|-
| 2058
| 080A
| Sir Netics
|-
| 2059
| 080B
| Expert Services
|-
| 2060
| 080C
| Digital Art Systems
|-
| 2061
| 080D
| Adept Development
|-
| 2062
| 080E
| Expansion Technologies (Expansion Systems)
|-
| 2063
| 080F
| Alphatech
|-
| 2064
| 0810
| Edotronik GmbH
|-
| 2065
| 0811
| California Access/Synergy
| Originally registered to Logical Design Works
|-
| 2066
| 0812
| Bowden, Williams, Full & Assoc.
|-
| 2067
| 0813
| NES, Inc.
|-
| 2068
| 0814
| Amdev
|-
| 2069
| 0815
| Big Brother Security Systems
|-
| 2070
| 0816
| Active Circuits Inc.
|-
| 2071
| 0817
| ICD, Inc.
|-
| 2072
| 0818
| Multi-Meg Electronique
|-
| 2073
| 0819
| Kupke Computertechnik GmbH
|-
| 2074
| 081A
| The Checkered Ball
|-
| 2075
| 081B
| Hi Tension Computer Services Ltd. (UK)
|-
| 2076
| 081C
| Alfa Data
| Originally assigned to Elmtech Research, Ltd. (UK)
|-
| 2077
| 081D
| Great Valley Products
| Originally registered to Clartscreen, Ltd. (UK)
|-
| 2078
| 081E
| Interworks
|-
| 2079
| 081F
| Galysh Enterprises
|-
| 2080
| 0820
| Hardital Synthesis
| Originally registered to Realtime Games Software Ltd.
|-
| 2081
| 0821
| GBS
|-
| 2082
| 0822
| Circum Design Inc.
|-
| 2083
| 0823
| Alberta Micro Electronic Center
|-
| 2084
| 0824
| Bestech
|-
| 2085
| 0825
| Lasar Fantasy
|-
| 2086
| 0826
| Pulsar
|-
| 2087
| 0827
| Ivis
|-
| 2088
| 0828
| Applied Engineering
|-
| 2089
| 0829
| Solid-State Design & Development
|-
| 2090
| 082A
| Vison Quest
|-
| 2091
| 082B
| Seaview Software
|-
| 2092
| 082C
| BSC
| Mistakenly used by ADS (Advanced Development Software)
|-
| 2093
| 082D
| Bernd Culenfeld
|-
| 2094
| 082E
| American Liquid Light
|-
| 2095
| 082F
| CEGITES
|-
| 2096
| 0830
| Quadlite Computers Ltd.
| Originally registered to EV Industries
|-
| 2097
| 0831
| Silicon Peace
|-
| 2098
| 0832
| Black Belt Systems
|-
| 2099
| 0833
| Village Tronic
| Originally registerd to Steve Yaeger
|-
| 2100
| 0834
| ReadySoft
|-
| 2101
| 0835
| Phoenix Micro Technologies
|-
| 2102
| 0836
| Advanced Systems & Software
| Orignally assigned to Preferred Technology
|-
| 2103
| 0837
| Rombo Productions
|-
| 2104
| 0838
| Impulse Inc.
|-
| 2105
| 0839
| Beta Unlimited
|-
| 2106
| 083A
| Memory Expansion System, Ltd.
|-
| 2107
| 083B
| Vortex Computer Systems GmbH
|-
| 2108
| 083C
| Platypus Systems
|-
| 2109
| 083D
| Gigatron OHG
|-
| 2110
| 083E
| PG Electronics
|-
| 2111
| 083F
| New Technologies Group
|-
| 2112
| 0840
| Interactive Video Systems (IVS)
| Pacific Peripherals
|-
| 2113
| 0841
| Vector
| Originally registered to H. K. Computer
|-
| 2114
| 0842
| Pacific Digital
| Originally registered to C. H. Helfrich Elektronik
|-
| 2115
| 0843
| Xanadu
|-
| 2116
| 0844
| Pacific Digital
| Originally registered to AMS
|-
| 2117
| 0845
| X-Pert
|-
| 2118
| 0846
| The Amiga Centre
|-
| 2119
| 0847
| Digital Pacific
|-
| 2120
| 0848
| Solid State Leisure
|-
| 2121
| 0849
| Hydra Systems
| Originally registered to Analog Electronics
|-
| 2122
| 084A
| Cumana
|-
| 2123
| 084B
| KAPS 2C Conception
|-
| 2124
| 084C
| Mike Mason
|-
| 2125
| 084D
| For Your Eyes
|-
| 2126
| 084E
| Volkmar Breitfeld Computersysteme
|-
| 2127
| 084F
| Sunrize Industries
|-
| 2128
| 0850
| Scott Advanced Micro Designs
|-
| 2129
| 0851
| Digital Micronics
|-
| 2130
| 0852
| Alfa-Laval
|-
| 2131
| 0853
| Multigros A/S
|-
| 2132
| 0854
| Archos
|-
| 2133
| 0855
| Icom Simulations
|-
| 2134
| 0856
| Commodore Test Engineering Group
|-
| 2135
| 0857
| Microcreations
|-
| 2136
| 0858
| Shoestring Productions
|-
| 2137
| 0859
| Faberushi
|-
| 2138
| 085A
| Evesham Micro Ltd.
|-
| 2139
| 085B
| Panagolin Laser Software
|-
| 2140
| 085C
| Thomas Rudloff
|-
| 2141
| 085D
| Daniel Hohabir
|-
| 2142
| 085E
| GfxBase, Inc.
|-
| 2143
| 085F
| Axellabs
|-
| 2144
| 0860
| Roctec Electronics Inc.
|-
| 2145
| 0861
| Omega Datentechnik
|-
| 2146
| 0862
| Atlantis
|-
| 2147
| 0863
| Skytec Computers
|-
| 2148
| 0864
| Protar Electronics
|-
| 2149
| 0865
| ACS
|-
| 2150
| 0866
| Software Results Enterprises
| Originally registered to University of Illinois
|-
| 2151
| 0867
| Infinity Systems Design Group
|-
| 2152
| 0868
| Trade It
|-
| 2153
| 0869
| Suntec, Inc.
|-
| 2154
| 086A
| DJW Micro Systems
| Originally registered to Tritec Marketing
|-
| 2155
| 086B
| Power Computing Ltd.
|-
| 2156
| 086C
| MacroSystems
|-
| 2157
| 086D
| Masoboshi GmbH (DCE)
|-
| 2158
| 086E
| HAL Software Hardware Handel
|-
| 2159
| 086F
| Mainhattan Data
| Originally registered to Michael Lamm Computersysteme
|-
| 2160
| 0870
| Digital Processing System
| Originally registered to bbdp Electronics
|-
| 2161
| 0871
| Blue Ribbon Soundworks
| Originally registered to Design Computer Systems
|-
| 2162
| 0872
| XPert
| Originally registered to The Station
|-
| 2163
| 0873
| DelaComp
| Originally registered to Bryan Williams
|-
| 2164
| 0874
| Superformance Computer Engineering GmbH
|-
| 2165
| 0875
| Overland Engineering
|-
| 2166
| 0876
| Thomas Hamren
|-
| 2167
| 0877
| Village Tronic
|-
| 2168
| 0878
| Toolbox Design
|-
| 2169
| 0879
| Digital Processing System
|-
| 2170
| 087A
| Superformance
|-
| 2171
| 087B
| Utilities Unlimited
|-
| 2172
| 087C
| phase 5
|-
| 2173
| 087D
| Juergen Kommos
|-
| 2174
| 087E
| Electronic Design
|-
| 2175
| 087F
| James Cook University of North Queensland
|-
| 2176
| 0880
| AmiTrix Development
|-
| 2177
| 0881
| Ferranti
|-
| 2178
| 0882
| Leviathan Development
|-
| 2179
| 0883
| United Video Inc.
|-
| 2180
| 0884
| GPSoft Pty. Ltd.
| Originally registered to Juergen Kommos
|-
| 2181
| 0885
| ArMAX
| Oliver Bausch
|-
| 2182
| 0886
| CP Computer
|-
| 2183
| 0887
| AMOK - Amiga Module & Oberon Klub
|-
| 2184
| 0888
| ITEK Neser & Sieber GbR
|-
| 2185
| 0889
| Phillip C. Lello
|-
| 2186
| 088A
| Cyborg Design Services
|-
| 2187
| 088B
| G2 Systems
|-
| 2188
| 088C
| Pro System Computersysteme
|-
| 2189
| 088D
| ZEUS Electronic
| Originally registered to MSPI (Markt & Technik)
|-
| 2190
| 088E
| Altatech
|-
| 2191
| 088F
| NewTek
|-
| 2192
| 0890
| M-TEC Hardware Design
| Originally registered to Hardware Design Udo Neuroth
|-
| 2193
| 0891
| Great Valley Products
| Originally registered to Viona Development
|-
| 2194
| 0892
| Amitek
| Originally assigned to Marpet Developments
|-
| 2195
| 0893
| Ingenieurbuero Helfrich
|-
| 2196
| 0894
| The Neo Group
|-
| 2197
| 0895
| Cyon
|-
| 2198
| 0896
| Bob Research Group
|-
| 2199
| 0897
| Richmond Sound Design Ltd.
|-
| 2200
| 0898
| US Cybernetics
|-
| 2201
| 0899
| Fulvio Ieva
|-
| 2202
| 089A
| Silicon Studio
|-
| 2203
| 089B
| MacroSystems (USA)
| Was named Micro System Devices
|-
| 2204
| 089C
| Conspector Entertainment
|-
| 2205
| 089D
| Laserforum
|-
| 2206
| 089E
| Elbox Computer
| Mistakenly used by Index Information Ltd.
|-
| 2207
| 089F
| Applied Magic Inc.
|-
| 2208
| 08A0
| SDL Ltd.
|-
| 2560
| 0A00
| Harms
|-
| 2588
| 0A1C
| A1K.org Community
|-
| 2640
| 0A50
| Micronik
|-
| 3084
| 0C0C
| Team 4
|-
| 3643
| 0E3B
| E3B
| Michael Boehmer
|-
| 3855
| 0F0F
| Micronik
|-
| 4096
| 1000
| MegaMicro
|-
| 4110
| 100E
| DigiFeX
|-
| 4136
| 1028
| Imtronics/Memphis
|-
| 4149
| 1035
| PROTAR
|-
| 4369
| 1111
| Frank Strauß Elektronik
| Also used by Kupke
|-
| 4626
| 1212
| Individual Computers
|-
| 4648
| 1228
| Flesch Hornemann Computer Elec.
|-
| 4680
| 1248
| Kupke Computertechnik GmbH
|-
| 4711
| 1267
| RBM digitaltechnik
|-
| 4754
| 1292
| MacroSystems
|-
| 5000
| 1388
| ITH
|-
| 5001
| 1389
| VMC
|-
| 5010
| 1392
| Ambience Creation Technology
|-
| 5011
| 1393
| Creative Development
|-
| 5012
| 1394
| Georg Braun
|-
| 5013
| 1395
| Swedish User Group of Amiga
|-
| 5014
| 1396
| Jakub Bednarski
|-
| 5015
| 1397
| KryoFlux, Ltd.
|-
| 5016
| 1398
| Igor Majstorovic
|-
| 5017
| 1399
| Alastair M. Robinson
|-
| 5018
| 139A
| Austex Software
|-
| 5019
| 139B
| Sören Gust
|-
| 5020
| 139C
| Rok Krajnc
|-
| 5030
| 13A6
| Tim Tashpulatov
|-
| 5040
| 13B0
| 7-bit
|-
| 5050
| 13BA
| Sakura IT
|-
| 5060
| 13C4
| FPGAArcade
|-
| 5070
| 13CE
| CancerSoft Inc.
|-
| 5080
| 13D8
| Stephen Leary
|-
| 5090
| 13E2
| DMA Softlab LLC
|-
| 5100
| 13EC
| Brookhouse Engineering
|-
| 5110
| 13F6
| Eduardo Arana
|-
| 5120
| 1400
| CS-LAB
|-
| 5130
| 140A
| Robert Miranda
|-
| 5140
| 1414
| RastPort
|-
| 5132
| 140C
| UAS Interface Ltd6
|-
| 5150
| 141E
| Amiga Kit
|-
| 5160
| 1428
| Central Texas Commodore User Group
|-
| 5170
| 1432
| Confusion Research Center
|-
| 5180
| 143C
| Solar Soyuz Zaibatsu
|-
| 5190
| 1446
| BooBip
|-
| 5191
| 1447
| Matthias Hampel
|-
| 5192
| 1448
| dec0de Consulting Ltd.
|-
| 5193
| 1449
| Puppy Concepts
|-
| 5194
| 144A
| Open Amiga Hardware Repository
|-
| 5195
| 144B
| Double H Tech
|-
| 5196
| 144C
| Retromatik
|-
| 5500
| 157C
| Inhouse Information
|-
| 5768
| 1688
| Bio Con
|-
| 6148
| 1804
| HK-Computer
|-
| 6502
| 1966
| Cloanto
|-
| 6520
| 1978
| Oliver Gantert
|-
| 7777
| 1E61
| Rafal Gabriel Chyla
|-
| 8215
| 2017
| Vortex
|-
| 8244
| 2034
| Spirit Technology
|-
| 8290
| 2062
| Expansion Systems
|-
| 8448
| 2100
| ReadySoft
|-
| 8512
| 2140
| Phase 5 Digital Products
|-
| 8553
| 2169
| Digital Processing Systems Inc.
|-
| 8704
| 2200
| ACT Elektronik
|-
| 8738
| 2222
| ACT Elektronik
|-
| 9512
| 2528
| Tower Technologies
|-
| 10676
| 29B4
| Electronic Design
|-
| 14195
| 3773
| Media-net-Point
|-
| 14501
| 38A5
| Petsoff, Finland
|-
| 16375
| 3FF7
| Uwe Gerlach
|-
| 16707
| 4143
| Ateo Concepts
|-
| 16708
| 4144
| ALiENDESiGN
|-
| 16945
| 4231
| A.C.T.
|-
| 17740
| 454C
| HK-Computer (ELSAT)
|-
| 18260
| 4754
| MacroSystems (Germany)
|-
| 19796
| 4D54
| Markt & Technik
|-
| 22359
| 5757
| Markt & Technik
|-
| 26464
| 6760
| Combitec
|-
| 26470
| 6766
| Combitec
|-
| 28014
| 6D6E
| MNT Media and Technology UG
|-
| 32768
| 8000
| M.A.S.T.
|-
| 42240
| A500
| Aethreum Digital
|-
| 43437
| A9AD
| Reis-Ware
|-
| 43521
| AA01
| Cameron
|-
| 43537
| AA11
| Reis-Ware
|-
| 44359
| AD47
| Matay
|-
| 46504
| B5A8
| Phoenix
|-
| 48879
| BEEF
| Swiss Mountain Dog Products
|-
| 49160
| C008
| Combitec
|-
| 61453
| F00D
| Forefront Technologies Inc.
|}

For any changes/additions to this registry please send a support request to [mailto:support@hyperion-entertainment.com support@hyperion-entertainment.com].

Amiga Hardware Manufacturer ID Registry

2026-09-08T10:18:26Z

Costel Mincea: Added IDs 5190-5196

__TOC__

= How to Obtain a Manufacturer Number =

Manufacturer's numbers are assigned by the AmigaOS development team. To obtain your unique manufacturer number send a support request to [mailto:support@hyperion-entertainment.com support@hyperion-entertainment.com].

Be sure and include your name and the type of expansion product you are developing.

= Your Manufacturer Number =

Attention hardware manufacturers. If you are developing a hardware expansion product for the Classic Amiga (e.g. 500, 2000, 3000) then you will need to obtain a special manufacturer ID number from the AmigaOS development team to identify your product. This manufacturer number is used by the Amiga to link your hardware with its driver software at boot time.

Your manufacturer number is part of the special protocol that the Amiga uses to automatically configure all expansion devices on the bus without the user having to cut jumpers or adjust dip switches. This is called auto-config.

At start-up time, the system first polls each board in the system and assigns the board its own address space. If it is a memory board, its RAM is linked into the memory free pool. Later in the boot sequence, after DOS is initialized, the binddrivers program is run. Binddrivers will search the directory SYS:Expansion for the drivers that go with the boards.

To do this binddrivers looks in the Tool Type field of all icon files in SYS:Expansion. If the first seven bytes of the Tool Type field are "PRODUCT", then this is an icon file for a driver.

Binddrivers will then attempt to match the drivers it has found with the boards that were found earlier. This is where your manufacturer number comes in.

Your manufacturer number goes in two places. First, it is burned in hex form into the PAL which is part of ALL auto-config expansion products. Second, it appears in ASCII in the Tool Type field of the icon file for your product's driver. By matching these two numbers, the Amiga can automatically configure your board and bind it's software driver into the system as well.

The manufacturer's number is a 16-bit ID which appears in PAL offsets $10-$17. There is also an 8-bit product number which you assign. The product number is for uniquely identifying different products from the same vendor. The product number will appear in PAL offsets $04-$07. This gives you a total of 24 bits to identify each of your products.

These 24 bits of information in the PAL which identify your product are matched against the information in the Tool Type field of all icon files in the SYS:Expansion drawer. For example, suppose you are manufacturer #1019. You have two products, #1 and #2 which both use the same driver. The icon for your driver for these two products would have a Tool Type set to "PRODUCT=1019/1|1019/2". This means: I am an icon for a driver that works with product number 1 or 2 from manufacturer 1019, now bind me. Spaces are not legal. Here are two other examples:

; PRODUCT=1208/11
: is the Tool Type for a driver for product 11 from manufacturer number 1208.

; PRODUCT=1017
: is the Tool Type for a driver for any product from manufacturer number 1017.

For an informal explanation of the auto-configuration process, see the chapter on Software Expansion Architecture from the 2nd Annual Amiga Developer's Conference Notes (available on ADCD 2.1). For the details of timing, power, the PAL equations and PAL address specifications and the expansion library documentation, see sections 3.1 to 3.3 of the A500/A2000 Technical Reference Manual. The original auto-config spec appears in the A1000 Schematics and Expansion Specification.

The auto-config process makes the addition of expansion products to the system very easy. All the user has to do is put the board in any slot and copy the driver from the release disk to his own SYS:Expansion drawer. Everything else is automatic. There are no jumpers or dip switches to set. Best of all, you will get a lot less support calls asking how to make your product work with the XYZ-Corp-battery-backed-clock.

= Notes =

Some notes on hardware manufacturer ID assignment.

* Manufacturer ID numbers are assigned free of charge.
* Please provide the following information when requesting an ID:
*# Name of the company or person
*# Postal address/contact address
*# Name of the contact person, with a corresponding e-mail address
*# A brief description of the kind of products you want to produce
* All ID numbers smaller than 5000 must be considered unsafe because no information exists on which numbers exactly were taken during the time Commodore, Inc. disintegrated.
* ID numbers in the range 8192 to 18841 must be considered unsafe because some hardware developers mistook the numbers assigned to them to be given in hexadecimal format. Hence 0x2000 = 8192 and 0x4999 = 18841.

= Example code =

<syntaxhighlight lang="C" line>
/*-----------------------------------------------*/
/* Here is a short program which will tell you */
/* about the expansion boards configured in your */
/* system without you opening up the machine. */
/* Code by Bill Koester of CATS */
/*-----------------------------------------------*/
#include <libraries/configvars.h>
#include <libraries/expansion.h>

struct ExpansionBase *ExpansionBase;

void cleanup();
void printdev();

int main()
{
struct ConfigDev *MyConfigDev;

/*----------------------------------*/
/* Open the expansion library, */
/* if there is a problem then exit */
/*----------------------------------*/

ExpansionBase =(struct ExpansionBase *) OpenLibrary(EXPANSIONNAME,0);
if(ExpansionBase==NULL)
{
printf("Error opening expansion library!!\n");
cleanup();
exit(0);
}

/*--------------------------------------------*/
/* Use FindConfigDev to get info on the first */
/* expansion board on the list maintained by */
/* Exec. If there are no expansion boards in */
/* the system then exit. */
/*--------------------------------------------*/

MyConfigDev = NULL;

/*--------------------------------------------------*/
/* FindConfigDev(oldConfigDev,manufacturer,product) */
/* oldConfigDev = NULL for the top of the list */
/* manufacturer = -1 for any manufacturer */
/* product = -1 for any product */
/*--------------------------------------------------*/

MyConfigDev = FindConfigDev(NULL,-1,-1);

if(MyConfigDev==NULL)
{
printf("No Configured Devices found!!\n");
cleanup();
exit(0);
}

printdev(MyConfigDev);

/*-----------------------------------*/
/* OK, there is at least one board, */
/* so loop and get the entire list */
/* printing as we go with printdev() */
/*-----------------------------------*/

while(MyConfigDev = FindConfigDev(MyConfigDev,-1,-1))
{
printdev(MyConfigDev);
}
cleanup();
return 0;
}

/*-------------------*/
/* Close up shop... */
/*-------------------*/
void cleanup()
{
if(ExpansionBase)
CloseLibrary(ExpansionBase);
}

/*----------------------------------*/
/* Print out the contents of the */
/* dev structure for this expansion */
/* product. */
/*----------------------------------*/

void printdev(dev)
struct ConfigDev *dev;
{
char buff[200];

printf("Flags = ");
if(dev->cd_Flags==NULL)
printf("NULL ");
if(dev->cd_Flags&CDF_SHUTUP)
printf("CDF_SHUTUP ");
if(dev->cd_Flags&CDF_CONFIGME)
printf("CDF_CONFIGME ");
printf("\n");
printf("Board Address = %x\n",dev->cd_BoardAddr);
printf("Board Size = %d bytes\n",dev->cd_BoardSize);
printf("Slot Address = %d\n",dev->cd_SlotAddr);
printf("Slot Size = %d\n",dev->cd_SlotSize);
printf("Driver code at %x\n",dev->cd_Driver);

printf("er_Type = %x\n",dev->cd_Rom.er_Type);
printf("er_Product = %x\n",dev->cd_Rom.er_Product);
printf("er_Flags = %x\n",dev->cd_Rom.er_Flags);
printf("er_Reserved03 = %x\n",dev->cd_Rom.er_Reserved03);
printf("er_Manufacturer = %x\n",dev->cd_Rom.er_Manufacturer);
printf("er_SerialNumber = %x\n",dev->cd_Rom.er_SerialNumber);
printf("er_InitDiagVec = %x\n",dev->cd_Rom.er_InitDiagVec);
printf("er_Reserved0c = %x\n",dev->cd_Rom.er_Reserved0c);
printf("er_Reserved0d = %x\n",dev->cd_Rom.er_Reserved0d);
printf("er_Reserved0e = %x\n",dev->cd_Rom.er_Reserved0e);
printf("er_Reserved0f = %x\n",dev->cd_Rom.er_Reserved0f);

printf("Hit Return to continue:\n");
gets(buff);
}
</syntaxhighlight>

= Registry =

{| class="wikitable"
! ID (decimal)
! ID (hexadecimal)
! Manufacturer
! Notes
|-
| 1
| 0001
| Micronik
|-
| 211
| 00D3
| Pacific Peripherals/Profex
|-
| 221
| 00DD
| Kupke Computertechnik GmbH
|-
| 256
| 0100
| Memphis
| Originally registered to MacroSystems US
|-
| 512
| 0200
| 3-State Computertechnik
|-
| 513
| 0201
| Commodore (Braunschweig)
|-
| 514
| 0202
| Commodore (West Chester)
|-
| 515
| 0203
| Commodore (West Chester)
| Originally registered to Combitech/Macrosystem
|-
| 756
| 02F4
| Progressive Peripherals & Software
|-
| 767
| 02FF
| Kolff Computer Supplies
|-
| 1001
| 03E9
| Tecmar
|-
| 1002
| 03EA
| Telesys
|-
| 1003
| 03EB
| The Micro-Forge
|-
| 1004
| 03EC
| Kronos/C Ltd.
| Originally registered to Card Co. (Supra)
|-
| 1005
| 03ED
| A-Squared
|-
| 1006
| 03EE
| Comspec Communications
|-
| 1007
| 03EF
| HT Electronics
|-
| 1008
| 03F0
| RDS Software
|-
| 1009
| 03F1
| Anakin Research
|-
| 1010
| 03F2
| MicroBotics
|-
| 1011
| 03F3
| Bob Krauth
|-
| 1012
| 03F4
| Access Associates (Alegra)
|-
| 1013
| 03F5
| Mini Comp Systems Ltd.
|-
| 1014
| 03F6
| Cypress Technology
|-
| 1015
| 03F7
| Fuller Computers
|-
| 1016
| 03F8
| Galaxy Computers
|-
| 1017
| 03F9
| ADA Research
|-
| 1018
| 03FA
| Computer Service Italia
|-
| 1019
| 03FB
| Amigo
|-
| 1020
| 03FC
| Micro-Solutions Inc.
|-
| 1021
| 03FD
| Stacar International
|-
| 1022
| 03FE
| Video Precisions
|-
| 1023
| 03FF
| ASDG, Inc.
|-
| 1025
| 0401
| Ing. Buero Kalawsky
|-
| 1026
| 0402
| Computer Tuning
|-
| 1027
| 0403
| Interplan Unternehmensberatung
|-
| 1028
| 0404
| Imtronics/Memphis
| Originally registered to Peter Ohlich
|-
| 1030
| 0406
| Commodore (Lowell University)
| Originally registered to Productivity Center
|-
| 1041
| 0411
| Design Labs
|-
| 1042
| 0412
| MCS
|-
| 1043
| 0413
| B. J. Freeman
|-
| 1044
| 0414
| Side Effects Inc.
|-
| 1045
| 0415
| Oklahoma Personal Comp.
|-
| 1046
| 0416
| Advanced Micro Innovations
|-
| 1047
| 0417
| Industrial Support Services
|-
| 1048
| 0418
| Technisoft
|-
| 1049
| 0419
| Prolific, Inc.
|-
| 1050
| 041A
| Softeam, Inc.
|-
| 1051
| 041B
| GRC Electronics
|-
| 1052
| 041C
| David Lai
|-
| 1053
| 041D
| Ameristar Technologies
|-
| 1054
| 041E
| Cline Refrigeration
|-
| 1055
| 041F
| Cardiac Pacemakers, Inc.
|-
| 1056
| 0420
| Supra Corp. (Creative Microsystems)
|-
| 1057
| 0421
| Wayne Diener
|-
| 1058
| 0422
| Computer Systems Associates (CSA)
|-
| 1059
| 0423
| Trionix, Inc.
|-
| 1060
| 0424
| David Lucas
|-
| 1061
| 0425
| Analog Precision
| Also assigned to D & L Distributing
|-
| 1267
| 04F3
| RBM Digitaltechnik
|-
| 1282
| 0502
| M-TEC Hardware Design
|-
| 1337
| 0539
| Thomas Stenzel (DaFR34K)
|-
| 1576
| 0628
| Boris Križma
|-
| 1761
| 06E1
| Great Valley Products
|-
| 1803
| 070B
| UAE Amiga Emulator
|-
| 2002
| 07D2
| Mimetics Corp.
|-
| 2003
| 07D3
| ACDA
|-
| 2004
| 07D4
| Finn R. Jacobsen
|-
| 2005
| 07D5
| Elthen Electronics
|-
| 2006
| 07D6
| Nine Tiles Computer Systems Ltd.
|-
| 2007
| 07D7
| Analog Electronics
|-
| 2008
| 07D8
| Bell & Howell
|-
| 2009
| 07D9
| Roland Kochler
|-
| 2010
| 07DA
| Byte Corp.
|-
| 2011
| 07DB
| Reserved
|-
| 2012
| 07DC
| DKB, Inc.
| Previously named Michigan Software
|-
| 2013
| 07DD
| Pacific Peripherals
|-
| 2014
| 07DE
| Sysaphus Software
|-
| 2015
| 07DF
| Digitronics
|-
| 2016
| 07E0
| Akron Systems
|-
| 2017
| 07E1
| Great Valley Products
|-
| 2018
| 07E2
| Calmos
|-
| 2019
| 07E3
| Dover Research
|-
| 2020
| 07E4
| David Krehbiel
|-
| 2021
| 07E5
| Synergy Peripheral Systems
| Also known as California Access
|-
| 2022
| 07E6
| Xetec
|-
| 2023
| 07E7
| Micron Technology
|-
| 2024
| 07E8
| CH Electronics
|-
| 2025
| 07E9
| American Liquid Light
|-
| 2026
| 07EA
| Progressive Peripherals & Software
| Also used by Ateo
|-
| 2027
| 07EB
| Wicat Systems
|-
| 2028
| 07EC
| Applied Systems & Peripherals
|-
| 2029
| 07ED
| Delaware Valley Software
|-
| 2030
| 07EE
| Palomax
|-
| 2031
| 07EF
| Incognito Software
|-
| 2032
| 07F0
| Jadesign
|-
| 2033
| 07F1
| BVR
|-
| 2034
| 07F2
| Spirit Technology
|-
| 2035
| 07F3
| Spirit Technology
|-
| 2036
| 07F4
| Atronic
|-
| 2037
| 07F5
| Scott Karlin
|-
| 2038
| 07F6
| Howitch
|-
| 2039
| 07F7
| Sullivan Brothers Visual Engineers
|-
| 2040
| 07F8
| G I T
|-
| 2041
| 07F9
| Amigo Business Computers
|-
| 2042
| 07FA
| Micro E Ab
|-
| 2043
| 07FB
| Ralph Kruse
|-
| 2044
| 07FC
| Clearpoint Research
|-
| 2045
| 07FD
| Kodiak
|-
| 2046
| 07FE
| BSC
| Originally registered to Phoenix Electronics
|-
| 2047
| 07FF
| No Name Shown
|-
| 2048
| 0800
| Commodore Braunschweig
|-
| 2049
| 0801
| BSC
| Originally registered to Elaborate Bytes
|-
| 2050
| 0802
| Kronos/C Ltd.
|-
| 2051
| 0803
| Spartanics
|-
| 2052
| 0804
| Jochheim Computer Tuning
|-
| 2053
| 0805
| Trans Data Systems
|-
| 2054
| 0806
| Applied Systems & Peripherals Ltd.
|-
| 2055
| 0807
| Checkpoint Technologies
| Originally registered to Amiga Solutions
|-
| 2056
| 0808
| Adept Development
|-
| 2057
| 0809
| Advanced Computer Design
|-
| 2058
| 080A
| Sir Netics
|-
| 2059
| 080B
| Expert Services
|-
| 2060
| 080C
| Digital Art Systems
|-
| 2061
| 080D
| Adept Development
|-
| 2062
| 080E
| Expansion Technologies (Expansion Systems)
|-
| 2063
| 080F
| Alphatech
|-
| 2064
| 0810
| Edotronik GmbH
|-
| 2065
| 0811
| California Access/Synergy
| Originally registered to Logical Design Works
|-
| 2066
| 0812
| Bowden, Williams, Full & Assoc.
|-
| 2067
| 0813
| NES, Inc.
|-
| 2068
| 0814
| Amdev
|-
| 2069
| 0815
| Big Brother Security Systems
|-
| 2070
| 0816
| Active Circuits Inc.
|-
| 2071
| 0817
| ICD, Inc.
|-
| 2072
| 0818
| Multi-Meg Electronique
|-
| 2073
| 0819
| Kupke Computertechnik GmbH
|-
| 2074
| 081A
| The Checkered Ball
|-
| 2075
| 081B
| Hi Tension Computer Services Ltd. (UK)
|-
| 2076
| 081C
| Alfa Data
| Originally assigned to Elmtech Research, Ltd. (UK)
|-
| 2077
| 081D
| Great Valley Products
| Originally registered to Clartscreen, Ltd. (UK)
|-
| 2078
| 081E
| Interworks
|-
| 2079
| 081F
| Galysh Enterprises
|-
| 2080
| 0820
| Hardital Synthesis
| Originally registered to Realtime Games Software Ltd.
|-
| 2081
| 0821
| GBS
|-
| 2082
| 0822
| Circum Design Inc.
|-
| 2083
| 0823
| Alberta Micro Electronic Center
|-
| 2084
| 0824
| Bestech
|-
| 2085
| 0825
| Lasar Fantasy
|-
| 2086
| 0826
| Pulsar
|-
| 2087
| 0827
| Ivis
|-
| 2088
| 0828
| Applied Engineering
|-
| 2089
| 0829
| Solid-State Design & Development
|-
| 2090
| 082A
| Vison Quest
|-
| 2091
| 082B
| Seaview Software
|-
| 2092
| 082C
| BSC
| Mistakenly used by ADS (Advanced Development Software)
|-
| 2093
| 082D
| Bernd Culenfeld
|-
| 2094
| 082E
| American Liquid Light
|-
| 2095
| 082F
| CEGITES
|-
| 2096
| 0830
| Quadlite Computers Ltd.
| Originally registered to EV Industries
|-
| 2097
| 0831
| Silicon Peace
|-
| 2098
| 0832
| Black Belt Systems
|-
| 2099
| 0833
| Village Tronic
| Originally registerd to Steve Yaeger
|-
| 2100
| 0834
| ReadySoft
|-
| 2101
| 0835
| Phoenix Micro Technologies
|-
| 2102
| 0836
| Advanced Systems & Software
| Orignally assigned to Preferred Technology
|-
| 2103
| 0837
| Rombo Productions
|-
| 2104
| 0838
| Impulse Inc.
|-
| 2105
| 0839
| Beta Unlimited
|-
| 2106
| 083A
| Memory Expansion System, Ltd.
|-
| 2107
| 083B
| Vortex Computer Systems GmbH
|-
| 2108
| 083C
| Platypus Systems
|-
| 2109
| 083D
| Gigatron OHG
|-
| 2110
| 083E
| PG Electronics
|-
| 2111
| 083F
| New Technologies Group
|-
| 2112
| 0840
| Interactive Video Systems (IVS)
| Pacific Peripherals
|-
| 2113
| 0841
| Vector
| Originally registered to H. K. Computer
|-
| 2114
| 0842
| Pacific Digital
| Originally registered to C. H. Helfrich Elektronik
|-
| 2115
| 0843
| Xanadu
|-
| 2116
| 0844
| Pacific Digital
| Originally registered to AMS
|-
| 2117
| 0845
| X-Pert
|-
| 2118
| 0846
| The Amiga Centre
|-
| 2119
| 0847
| Digital Pacific
|-
| 2120
| 0848
| Solid State Leisure
|-
| 2121
| 0849
| Hydra Systems
| Originally registered to Analog Electronics
|-
| 2122
| 084A
| Cumana
|-
| 2123
| 084B
| KAPS 2C Conception
|-
| 2124
| 084C
| Mike Mason
|-
| 2125
| 084D
| For Your Eyes
|-
| 2126
| 084E
| Volkmar Breitfeld Computersysteme
|-
| 2127
| 084F
| Sunrize Industries
|-
| 2128
| 0850
| Scott Advanced Micro Designs
|-
| 2129
| 0851
| Digital Micronics
|-
| 2130
| 0852
| Alfa-Laval
|-
| 2131
| 0853
| Multigros A/S
|-
| 2132
| 0854
| Archos
|-
| 2133
| 0855
| Icom Simulations
|-
| 2134
| 0856
| Commodore Test Engineering Group
|-
| 2135
| 0857
| Microcreations
|-
| 2136
| 0858
| Shoestring Productions
|-
| 2137
| 0859
| Faberushi
|-
| 2138
| 085A
| Evesham Micro Ltd.
|-
| 2139
| 085B
| Panagolin Laser Software
|-
| 2140
| 085C
| Thomas Rudloff
|-
| 2141
| 085D
| Daniel Hohabir
|-
| 2142
| 085E
| GfxBase, Inc.
|-
| 2143
| 085F
| Axellabs
|-
| 2144
| 0860
| Roctec Electronics Inc.
|-
| 2145
| 0861
| Omega Datentechnik
|-
| 2146
| 0862
| Atlantis
|-
| 2147
| 0863
| Skytec Computers
|-
| 2148
| 0864
| Protar Electronics
|-
| 2149
| 0865
| ACS
|-
| 2150
| 0866
| Software Results Enterprises
| Originally registered to University of Illinois
|-
| 2151
| 0867
| Infinity Systems Design Group
|-
| 2152
| 0868
| Trade It
|-
| 2153
| 0869
| Suntec, Inc.
|-
| 2154
| 086A
| DJW Micro Systems
| Originally registered to Tritec Marketing
|-
| 2155
| 086B
| Power Computing Ltd.
|-
| 2156
| 086C
| MacroSystems
|-
| 2157
| 086D
| Masoboshi GmbH (DCE)
|-
| 2158
| 086E
| HAL Software Hardware Handel
|-
| 2159
| 086F
| Mainhattan Data
| Originally registered to Michael Lamm Computersysteme
|-
| 2160
| 0870
| Digital Processing System
| Originally registered to bbdp Electronics
|-
| 2161
| 0871
| Blue Ribbon Soundworks
| Originally registered to Design Computer Systems
|-
| 2162
| 0872
| XPert
| Originally registered to The Station
|-
| 2163
| 0873
| DelaComp
| Originally registered to Bryan Williams
|-
| 2164
| 0874
| Superformance Computer Engineering GmbH
|-
| 2165
| 0875
| Overland Engineering
|-
| 2166
| 0876
| Thomas Hamren
|-
| 2167
| 0877
| Village Tronic
|-
| 2168
| 0878
| Toolbox Design
|-
| 2169
| 0879
| Digital Processing System
|-
| 2170
| 087A
| Superformance
|-
| 2171
| 087B
| Utilities Unlimited
|-
| 2172
| 087C
| phase 5
|-
| 2173
| 087D
| Juergen Kommos
|-
| 2174
| 087E
| Electronic Design
|-
| 2175
| 087F
| James Cook University of North Queensland
|-
| 2176
| 0880
| AmiTrix Development
|-
| 2177
| 0881
| Ferranti
|-
| 2178
| 0882
| Leviathan Development
|-
| 2179
| 0883
| United Video Inc.
|-
| 2180
| 0884
| GPSoft Pty. Ltd.
| Originally registered to Juergen Kommos
|-
| 2181
| 0885
| ArMAX
| Oliver Bausch
|-
| 2182
| 0886
| CP Computer
|-
| 2183
| 0887
| AMOK - Amiga Module & Oberon Klub
|-
| 2184
| 0888
| ITEK Neser & Sieber GbR
|-
| 2185
| 0889
| Phillip C. Lello
|-
| 2186
| 088A
| Cyborg Design Services
|-
| 2187
| 088B
| G2 Systems
|-
| 2188
| 088C
| Pro System Computersysteme
|-
| 2189
| 088D
| ZEUS Electronic
| Originally registered to MSPI (Markt & Technik)
|-
| 2190
| 088E
| Altatech
|-
| 2191
| 088F
| NewTek
|-
| 2192
| 0890
| M-TEC Hardware Design
| Originally registered to Hardware Design Udo Neuroth
|-
| 2193
| 0891
| Great Valley Products
| Originally registered to Viona Development
|-
| 2194
| 0892
| Amitek
| Originally assigned to Marpet Developments
|-
| 2195
| 0893
| Ingenieurbuero Helfrich
|-
| 2196
| 0894
| The Neo Group
|-
| 2197
| 0895
| Cyon
|-
| 2198
| 0896
| Bob Research Group
|-
| 2199
| 0897
| Richmond Sound Design Ltd.
|-
| 2200
| 0898
| US Cybernetics
|-
| 2201
| 0899
| Fulvio Ieva
|-
| 2202
| 089A
| Silicon Studio
|-
| 2203
| 089B
| MacroSystems (USA)
| Was named Micro System Devices
|-
| 2204
| 089C
| Conspector Entertainment
|-
| 2205
| 089D
| Laserforum
|-
| 2206
| 089E
| Elbox Computer
| Mistakenly used by Index Information Ltd.
|-
| 2207
| 089F
| Applied Magic Inc.
|-
| 2208
| 08A0
| SDL Ltd.
|-
| 2560
| 0A00
| Harms
|-
| 2588
| 0A1C
| A1K.org Community
|-
| 2640
| 0A50
| Micronik
|-
| 3084
| 0C0C
| Team 4
|-
| 3643
| 0E3B
| E3B
| Michael Boehmer
|-
| 3855
| 0F0F
| Micronik
|-
| 4096
| 1000
| MegaMicro
|-
| 4110
| 100E
| DigiFeX
|-
| 4136
| 1028
| Imtronics/Memphis
|-
| 4149
| 1035
| PROTAR
|-
| 4369
| 1111
| Frank Strauß Elektronik
| Also used by Kupke
|-
| 4626
| 1212
| Individual Computers
|-
| 4648
| 1228
| Flesch Hornemann Computer Elec.
|-
| 4680
| 1248
| Kupke Computertechnik GmbH
|-
| 4711
| 1267
| RBM digitaltechnik
|-
| 4754
| 1292
| MacroSystems
|-
| 5000
| 1388
| ITH
|-
| 5001
| 1389
| VMC
|-
| 5010
| 1392
| Ambience Creation Technology
|-
| 5011
| 1393
| Creative Development
|-
| 5012
| 1394
| Georg Braun
|-
| 5013
| 1395
| Swedish User Group of Amiga
|-
| 5014
| 1396
| Jakub Bednarski
|-
| 5015
| 1397
| KryoFlux, Ltd.
|-
| 5016
| 1398
| Igor Majstorovic
|-
| 5017
| 1399
| Alastair M. Robinson
|-
| 5018
| 139A
| Austex Software
|-
| 5019
| 139B
| Sören Gust
|-
| 5020
| 139C
| Rok Krajnc
|-
| 5030
| 13A6
| Tim Tashpulatov
|-
| 5040
| 13B0
| 7-bit
|-
| 5050
| 13BA
| Sakura IT
|-
| 5060
| 13C4
| FPGAArcade
|-
| 5070
| 13CE
| CancerSoft Inc.
|-
| 5080
| 13D8
| Stephen Leary
|-
| 5090
| 13E2
| DMA Softlab LLC
|-
| 5100
| 13EC
| Brookhouse Engineering
|-
| 5110
| 13F6
| Eduardo Arana
|-
| 5120
| 1400
| CS-LAB
|-
| 5130
| 140A
| Robert Miranda
|-
| 5140
| 1414
| RastPort
|-
| 5132
| 140C
| UAS Interface Ltd6
|-
| 5150
| 141E
| Amiga Kit
|-
| 5160
| 1428
| Central Texas Commodore User Group
|-
| 5170
| 1432
| Confusion Research Center
|-
| 5180
| 143C
| Solar Soyuz Zaibatsu
|-
| 5190
| 1446
| BooBip
|-
| 5191
| 1447
| Matthias Hampel
|-
| 5192
| 1448
| dec0de Consulting Ltd.
|-
| 5193
| 1449
| Puppy Concepts
|-
| 5194
| 144A
| Open Amiga Hardware Repository
|-
| 5195
| 144B
| Double H Tech
|-
| 5196
| 144C
| Retromatik
|-
| 5500
| 157C
| Inhouse Information
|-
| 5768
| 1688
| Bio Con
|-
| 6148
| 1804
| HK-Computer
|-
| 6502
| 1966
| Cloanto
|-
| 6520
| 1978
| Oliver Gantert
|-
| 7777
| 1E61
| Rafal Gabriel Chyla
|-
| 8215
| 2017
| Vortex
|-
| 8244
| 2034
| Spirit Technology
|-
| 8290
| 2062
| Expansion Systems
|-
| 8448
| 2100
| ReadySoft
|-
| 8512
| 2140
| Phase 5 Digital Products
|-
| 8553
| 2169
| Digital Processing Systems Inc.
|-
| 8704
| 2200
| ACT Elektronik
|-
| 8738
| 2222
| ACT Elektronik
|-
| 9512
| 2528
| Tower Technologies
|-
| 10676
| 29B4
| Electronic Design
|-
| 14195
| 3773
| Media-net-Point
|-
| 14501
| 38A5
| Petsoff, Finland
|-
| 16375
| 3FF7
| Uwe Gerlach
|-
| 16707
| 4143
| Ateo Concepts
|-
| 16708
| 4144
| ALiENDESiGN
|-
| 16945
| 4231
| A.C.T.
|-
| 17740
| 454C
| HK-Computer (ELSAT)
|-
| 18260
| 4754
| MacroSystems (Germany)
|-
| 19796
| 4D54
| Markt & Technik
|-
| 22359
| 5757
| Markt & Technik
|-
| 26464
| 6760
| Combitec
|-
| 26470
| 6766
| Combitec
|-
| 28014
| 6D6E
| MNT Media and Technology UG
|-
| 32768
| 8000
| M.A.S.T.
|-
| 42240
| A500
| Aethreum Digital
|-
| 43437
| A9AD
| Reis-Ware
|-
| 43521
| AA01
| Cameron
|-
| 43537
| AA11
| Reis-Ware
|-
| 44359
| AD47
| Matay
|-
| 46504
| B5A8
| Phoenix
|-
| 48879
| BEEF
| Swiss Mountain Dog Products
|-
| 49160
| C008
| Combitec
|-
| 61453
| F00D
| Forefront Technologies Inc.
|}

For any changes/additions to this registry please send a support request to [mailto:support@hyperion-entertainment.com support@hyperion-entertainment.com].

Amiga Hardware Manufacturer ID Registry

2026-09-08T10:11:48Z

Costel Mincea:

__TOC__

= How to Obtain a Manufacturer Number =

Manufacturer's numbers are assigned by the AmigaOS development team. To obtain your unique manufacturer number send a support request to [mailto:support@hyperion-entertainment.com support@hyperion-entertainment.com].

Be sure and include your name and the type of expansion product you are developing.

= Your Manufacturer Number =

Attention hardware manufacturers. If you are developing a hardware expansion product for the Classic Amiga (e.g. 500, 2000, 3000) then you will need to obtain a special manufacturer ID number from the AmigaOS development team to identify your product. This manufacturer number is used by the Amiga to link your hardware with its driver software at boot time.

Your manufacturer number is part of the special protocol that the Amiga uses to automatically configure all expansion devices on the bus without the user having to cut jumpers or adjust dip switches. This is called auto-config.

At start-up time, the system first polls each board in the system and assigns the board its own address space. If it is a memory board, its RAM is linked into the memory free pool. Later in the boot sequence, after DOS is initialized, the binddrivers program is run. Binddrivers will search the directory SYS:Expansion for the drivers that go with the boards.

To do this binddrivers looks in the Tool Type field of all icon files in SYS:Expansion. If the first seven bytes of the Tool Type field are "PRODUCT", then this is an icon file for a driver.

Binddrivers will then attempt to match the drivers it has found with the boards that were found earlier. This is where your manufacturer number comes in.

Your manufacturer number goes in two places. First, it is burned in hex form into the PAL which is part of ALL auto-config expansion products. Second, it appears in ASCII in the Tool Type field of the icon file for your product's driver. By matching these two numbers, the Amiga can automatically configure your board and bind it's software driver into the system as well.

The manufacturer's number is a 16-bit ID which appears in PAL offsets $10-$17. There is also an 8-bit product number which you assign. The product number is for uniquely identifying different products from the same vendor. The product number will appear in PAL offsets $04-$07. This gives you a total of 24 bits to identify each of your products.

These 24 bits of information in the PAL which identify your product are matched against the information in the Tool Type field of all icon files in the SYS:Expansion drawer. For example, suppose you are manufacturer #1019. You have two products, #1 and #2 which both use the same driver. The icon for your driver for these two products would have a Tool Type set to "PRODUCT=1019/1|1019/2". This means: I am an icon for a driver that works with product number 1 or 2 from manufacturer 1019, now bind me. Spaces are not legal. Here are two other examples:

; PRODUCT=1208/11
: is the Tool Type for a driver for product 11 from manufacturer number 1208.

; PRODUCT=1017
: is the Tool Type for a driver for any product from manufacturer number 1017.

For an informal explanation of the auto-configuration process, see the chapter on Software Expansion Architecture from the 2nd Annual Amiga Developer's Conference Notes (available on ADCD 2.1). For the details of timing, power, the PAL equations and PAL address specifications and the expansion library documentation, see sections 3.1 to 3.3 of the A500/A2000 Technical Reference Manual. The original auto-config spec appears in the A1000 Schematics and Expansion Specification.

The auto-config process makes the addition of expansion products to the system very easy. All the user has to do is put the board in any slot and copy the driver from the release disk to his own SYS:Expansion drawer. Everything else is automatic. There are no jumpers or dip switches to set. Best of all, you will get a lot less support calls asking how to make your product work with the XYZ-Corp-battery-backed-clock.

= Notes =

Some notes on hardware manufacturer ID assignment.

* Manufacturer ID numbers are assigned free of charge.
* Please provide the following information when requesting an ID:
*# Name of the company or person
*# Postal address/contact address
*# Name of the contact person, with a corresponding e-mail address
*# A brief description of the kind of products you want to produce
* All ID numbers smaller than 5000 must be considered unsafe because no information exists on which numbers exactly were taken during the time Commodore, Inc. disintegrated.
* ID numbers in the range 8192 to 18841 must be considered unsafe because some hardware developers mistook the numbers assigned to them to be given in hexadecimal format. Hence 0x2000 = 8192 and 0x4999 = 18841.

= Example code =

<syntaxhighlight lang="C" line>
/*-----------------------------------------------*/
/* Here is a short program which will tell you */
/* about the expansion boards configured in your */
/* system without you opening up the machine. */
/* Code by Bill Koester of CATS */
/*-----------------------------------------------*/
#include <libraries/configvars.h>
#include <libraries/expansion.h>

struct ExpansionBase *ExpansionBase;

void cleanup();
void printdev();

int main()
{
struct ConfigDev *MyConfigDev;

/*----------------------------------*/
/* Open the expansion library, */
/* if there is a problem then exit */
/*----------------------------------*/

ExpansionBase =(struct ExpansionBase *) OpenLibrary(EXPANSIONNAME,0);
if(ExpansionBase==NULL)
{
printf("Error opening expansion library!!\n");
cleanup();
exit(0);
}

/*--------------------------------------------*/
/* Use FindConfigDev to get info on the first */
/* expansion board on the list maintained by */
/* Exec. If there are no expansion boards in */
/* the system then exit. */
/*--------------------------------------------*/

MyConfigDev = NULL;

/*--------------------------------------------------*/
/* FindConfigDev(oldConfigDev,manufacturer,product) */
/* oldConfigDev = NULL for the top of the list */
/* manufacturer = -1 for any manufacturer */
/* product = -1 for any product */
/*--------------------------------------------------*/

MyConfigDev = FindConfigDev(NULL,-1,-1);

if(MyConfigDev==NULL)
{
printf("No Configured Devices found!!\n");
cleanup();
exit(0);
}

printdev(MyConfigDev);

/*-----------------------------------*/
/* OK, there is at least one board, */
/* so loop and get the entire list */
/* printing as we go with printdev() */
/*-----------------------------------*/

while(MyConfigDev = FindConfigDev(MyConfigDev,-1,-1))
{
printdev(MyConfigDev);
}
cleanup();
return 0;
}

/*-------------------*/
/* Close up shop... */
/*-------------------*/
void cleanup()
{
if(ExpansionBase)
CloseLibrary(ExpansionBase);
}

/*----------------------------------*/
/* Print out the contents of the */
/* dev structure for this expansion */
/* product. */
/*----------------------------------*/

void printdev(dev)
struct ConfigDev *dev;
{
char buff[200];

printf("Flags = ");
if(dev->cd_Flags==NULL)
printf("NULL ");
if(dev->cd_Flags&CDF_SHUTUP)
printf("CDF_SHUTUP ");
if(dev->cd_Flags&CDF_CONFIGME)
printf("CDF_CONFIGME ");
printf("\n");
printf("Board Address = %x\n",dev->cd_BoardAddr);
printf("Board Size = %d bytes\n",dev->cd_BoardSize);
printf("Slot Address = %d\n",dev->cd_SlotAddr);
printf("Slot Size = %d\n",dev->cd_SlotSize);
printf("Driver code at %x\n",dev->cd_Driver);

printf("er_Type = %x\n",dev->cd_Rom.er_Type);
printf("er_Product = %x\n",dev->cd_Rom.er_Product);
printf("er_Flags = %x\n",dev->cd_Rom.er_Flags);
printf("er_Reserved03 = %x\n",dev->cd_Rom.er_Reserved03);
printf("er_Manufacturer = %x\n",dev->cd_Rom.er_Manufacturer);
printf("er_SerialNumber = %x\n",dev->cd_Rom.er_SerialNumber);
printf("er_InitDiagVec = %x\n",dev->cd_Rom.er_InitDiagVec);
printf("er_Reserved0c = %x\n",dev->cd_Rom.er_Reserved0c);
printf("er_Reserved0d = %x\n",dev->cd_Rom.er_Reserved0d);
printf("er_Reserved0e = %x\n",dev->cd_Rom.er_Reserved0e);
printf("er_Reserved0f = %x\n",dev->cd_Rom.er_Reserved0f);

printf("Hit Return to continue:\n");
gets(buff);
}
</syntaxhighlight>

= Registry =

{| class="wikitable"
! ID (decimal)
! ID (hexadecimal)
! Manufacturer
! Notes
|-
| 1
| 0001
| Micronik
|-
| 211
| 00D3
| Pacific Peripherals/Profex
|-
| 221
| 00DD
| Kupke Computertechnik GmbH
|-
| 256
| 0100
| Memphis
| Originally registered to MacroSystems US
|-
| 512
| 0200
| 3-State Computertechnik
|-
| 513
| 0201
| Commodore (Braunschweig)
|-
| 514
| 0202
| Commodore (West Chester)
|-
| 515
| 0203
| Commodore (West Chester)
| Originally registered to Combitech/Macrosystem
|-
| 756
| 02F4
| Progressive Peripherals & Software
|-
| 767
| 02FF
| Kolff Computer Supplies
|-
| 1001
| 03E9
| Tecmar
|-
| 1002
| 03EA
| Telesys
|-
| 1003
| 03EB
| The Micro-Forge
|-
| 1004
| 03EC
| Kronos/C Ltd.
| Originally registered to Card Co. (Supra)
|-
| 1005
| 03ED
| A-Squared
|-
| 1006
| 03EE
| Comspec Communications
|-
| 1007
| 03EF
| HT Electronics
|-
| 1008
| 03F0
| RDS Software
|-
| 1009
| 03F1
| Anakin Research
|-
| 1010
| 03F2
| MicroBotics
|-
| 1011
| 03F3
| Bob Krauth
|-
| 1012
| 03F4
| Access Associates (Alegra)
|-
| 1013
| 03F5
| Mini Comp Systems Ltd.
|-
| 1014
| 03F6
| Cypress Technology
|-
| 1015
| 03F7
| Fuller Computers
|-
| 1016
| 03F8
| Galaxy Computers
|-
| 1017
| 03F9
| ADA Research
|-
| 1018
| 03FA
| Computer Service Italia
|-
| 1019
| 03FB
| Amigo
|-
| 1020
| 03FC
| Micro-Solutions Inc.
|-
| 1021
| 03FD
| Stacar International
|-
| 1022
| 03FE
| Video Precisions
|-
| 1023
| 03FF
| ASDG, Inc.
|-
| 1025
| 0401
| Ing. Buero Kalawsky
|-
| 1026
| 0402
| Computer Tuning
|-
| 1027
| 0403
| Interplan Unternehmensberatung
|-
| 1028
| 0404
| Imtronics/Memphis
| Originally registered to Peter Ohlich
|-
| 1030
| 0406
| Commodore (Lowell University)
| Originally registered to Productivity Center
|-
| 1041
| 0411
| Design Labs
|-
| 1042
| 0412
| MCS
|-
| 1043
| 0413
| B. J. Freeman
|-
| 1044
| 0414
| Side Effects Inc.
|-
| 1045
| 0415
| Oklahoma Personal Comp.
|-
| 1046
| 0416
| Advanced Micro Innovations
|-
| 1047
| 0417
| Industrial Support Services
|-
| 1048
| 0418
| Technisoft
|-
| 1049
| 0419
| Prolific, Inc.
|-
| 1050
| 041A
| Softeam, Inc.
|-
| 1051
| 041B
| GRC Electronics
|-
| 1052
| 041C
| David Lai
|-
| 1053
| 041D
| Ameristar Technologies
|-
| 1054
| 041E
| Cline Refrigeration
|-
| 1055
| 041F
| Cardiac Pacemakers, Inc.
|-
| 1056
| 0420
| Supra Corp. (Creative Microsystems)
|-
| 1057
| 0421
| Wayne Diener
|-
| 1058
| 0422
| Computer Systems Associates (CSA)
|-
| 1059
| 0423
| Trionix, Inc.
|-
| 1060
| 0424
| David Lucas
|-
| 1061
| 0425
| Analog Precision
| Also assigned to D & L Distributing
|-
| 1267
| 04F3
| RBM Digitaltechnik
|-
| 1282
| 0502
| M-TEC Hardware Design
|-
| 1337
| 0539
| Thomas Stenzel (DaFR34K)
|-
| 1576
| 0628
| Boris Križma
|-
| 1761
| 06E1
| Great Valley Products
|-
| 1803
| 070B
| UAE Amiga Emulator
|-
| 2002
| 07D2
| Mimetics Corp.
|-
| 2003
| 07D3
| ACDA
|-
| 2004
| 07D4
| Finn R. Jacobsen
|-
| 2005
| 07D5
| Elthen Electronics
|-
| 2006
| 07D6
| Nine Tiles Computer Systems Ltd.
|-
| 2007
| 07D7
| Analog Electronics
|-
| 2008
| 07D8
| Bell & Howell
|-
| 2009
| 07D9
| Roland Kochler
|-
| 2010
| 07DA
| Byte Corp.
|-
| 2011
| 07DB
| Reserved
|-
| 2012
| 07DC
| DKB, Inc.
| Previously named Michigan Software
|-
| 2013
| 07DD
| Pacific Peripherals
|-
| 2014
| 07DE
| Sysaphus Software
|-
| 2015
| 07DF
| Digitronics
|-
| 2016
| 07E0
| Akron Systems
|-
| 2017
| 07E1
| Great Valley Products
|-
| 2018
| 07E2
| Calmos
|-
| 2019
| 07E3
| Dover Research
|-
| 2020
| 07E4
| David Krehbiel
|-
| 2021
| 07E5
| Synergy Peripheral Systems
| Also known as California Access
|-
| 2022
| 07E6
| Xetec
|-
| 2023
| 07E7
| Micron Technology
|-
| 2024
| 07E8
| CH Electronics
|-
| 2025
| 07E9
| American Liquid Light
|-
| 2026
| 07EA
| Progressive Peripherals & Software
| Also used by Ateo
|-
| 2027
| 07EB
| Wicat Systems
|-
| 2028
| 07EC
| Applied Systems & Peripherals
|-
| 2029
| 07ED
| Delaware Valley Software
|-
| 2030
| 07EE
| Palomax
|-
| 2031
| 07EF
| Incognito Software
|-
| 2032
| 07F0
| Jadesign
|-
| 2033
| 07F1
| BVR
|-
| 2034
| 07F2
| Spirit Technology
|-
| 2035
| 07F3
| Spirit Technology
|-
| 2036
| 07F4
| Atronic
|-
| 2037
| 07F5
| Scott Karlin
|-
| 2038
| 07F6
| Howitch
|-
| 2039
| 07F7
| Sullivan Brothers Visual Engineers
|-
| 2040
| 07F8
| G I T
|-
| 2041
| 07F9
| Amigo Business Computers
|-
| 2042
| 07FA
| Micro E Ab
|-
| 2043
| 07FB
| Ralph Kruse
|-
| 2044
| 07FC
| Clearpoint Research
|-
| 2045
| 07FD
| Kodiak
|-
| 2046
| 07FE
| BSC
| Originally registered to Phoenix Electronics
|-
| 2047
| 07FF
| No Name Shown
|-
| 2048
| 0800
| Commodore Braunschweig
|-
| 2049
| 0801
| BSC
| Originally registered to Elaborate Bytes
|-
| 2050
| 0802
| Kronos/C Ltd.
|-
| 2051
| 0803
| Spartanics
|-
| 2052
| 0804
| Jochheim Computer Tuning
|-
| 2053
| 0805
| Trans Data Systems
|-
| 2054
| 0806
| Applied Systems & Peripherals Ltd.
|-
| 2055
| 0807
| Checkpoint Technologies
| Originally registered to Amiga Solutions
|-
| 2056
| 0808
| Adept Development
|-
| 2057
| 0809
| Advanced Computer Design
|-
| 2058
| 080A
| Sir Netics
|-
| 2059
| 080B
| Expert Services
|-
| 2060
| 080C
| Digital Art Systems
|-
| 2061
| 080D
| Adept Development
|-
| 2062
| 080E
| Expansion Technologies (Expansion Systems)
|-
| 2063
| 080F
| Alphatech
|-
| 2064
| 0810
| Edotronik GmbH
|-
| 2065
| 0811
| California Access/Synergy
| Originally registered to Logical Design Works
|-
| 2066
| 0812
| Bowden, Williams, Full & Assoc.
|-
| 2067
| 0813
| NES, Inc.
|-
| 2068
| 0814
| Amdev
|-
| 2069
| 0815
| Big Brother Security Systems
|-
| 2070
| 0816
| Active Circuits Inc.
|-
| 2071
| 0817
| ICD, Inc.
|-
| 2072
| 0818
| Multi-Meg Electronique
|-
| 2073
| 0819
| Kupke Computertechnik GmbH
|-
| 2074
| 081A
| The Checkered Ball
|-
| 2075
| 081B
| Hi Tension Computer Services Ltd. (UK)
|-
| 2076
| 081C
| Alfa Data
| Originally assigned to Elmtech Research, Ltd. (UK)
|-
| 2077
| 081D
| Great Valley Products
| Originally registered to Clartscreen, Ltd. (UK)
|-
| 2078
| 081E
| Interworks
|-
| 2079
| 081F
| Galysh Enterprises
|-
| 2080
| 0820
| Hardital Synthesis
| Originally registered to Realtime Games Software Ltd.
|-
| 2081
| 0821
| GBS
|-
| 2082
| 0822
| Circum Design Inc.
|-
| 2083
| 0823
| Alberta Micro Electronic Center
|-
| 2084
| 0824
| Bestech
|-
| 2085
| 0825
| Lasar Fantasy
|-
| 2086
| 0826
| Pulsar
|-
| 2087
| 0827
| Ivis
|-
| 2088
| 0828
| Applied Engineering
|-
| 2089
| 0829
| Solid-State Design & Development
|-
| 2090
| 082A
| Vison Quest
|-
| 2091
| 082B
| Seaview Software
|-
| 2092
| 082C
| BSC
| Mistakenly used by ADS (Advanced Development Software)
|-
| 2093
| 082D
| Bernd Culenfeld
|-
| 2094
| 082E
| American Liquid Light
|-
| 2095
| 082F
| CEGITES
|-
| 2096
| 0830
| Quadlite Computers Ltd.
| Originally registered to EV Industries
|-
| 2097
| 0831
| Silicon Peace
|-
| 2098
| 0832
| Black Belt Systems
|-
| 2099
| 0833
| Village Tronic
| Originally registerd to Steve Yaeger
|-
| 2100
| 0834
| ReadySoft
|-
| 2101
| 0835
| Phoenix Micro Technologies
|-
| 2102
| 0836
| Advanced Systems & Software
| Orignally assigned to Preferred Technology
|-
| 2103
| 0837
| Rombo Productions
|-
| 2104
| 0838
| Impulse Inc.
|-
| 2105
| 0839
| Beta Unlimited
|-
| 2106
| 083A
| Memory Expansion System, Ltd.
|-
| 2107
| 083B
| Vortex Computer Systems GmbH
|-
| 2108
| 083C
| Platypus Systems
|-
| 2109
| 083D
| Gigatron OHG
|-
| 2110
| 083E
| PG Electronics
|-
| 2111
| 083F
| New Technologies Group
|-
| 2112
| 0840
| Interactive Video Systems (IVS)
| Pacific Peripherals
|-
| 2113
| 0841
| Vector
| Originally registered to H. K. Computer
|-
| 2114
| 0842
| Pacific Digital
| Originally registered to C. H. Helfrich Elektronik
|-
| 2115
| 0843
| Xanadu
|-
| 2116
| 0844
| Pacific Digital
| Originally registered to AMS
|-
| 2117
| 0845
| X-Pert
|-
| 2118
| 0846
| The Amiga Centre
|-
| 2119
| 0847
| Digital Pacific
|-
| 2120
| 0848
| Solid State Leisure
|-
| 2121
| 0849
| Hydra Systems
| Originally registered to Analog Electronics
|-
| 2122
| 084A
| Cumana
|-
| 2123
| 084B
| KAPS 2C Conception
|-
| 2124
| 084C
| Mike Mason
|-
| 2125
| 084D
| For Your Eyes
|-
| 2126
| 084E
| Volkmar Breitfeld Computersysteme
|-
| 2127
| 084F
| Sunrize Industries
|-
| 2128
| 0850
| Scott Advanced Micro Designs
|-
| 2129
| 0851
| Digital Micronics
|-
| 2130
| 0852
| Alfa-Laval
|-
| 2131
| 0853
| Multigros A/S
|-
| 2132
| 0854
| Archos
|-
| 2133
| 0855
| Icom Simulations
|-
| 2134
| 0856
| Commodore Test Engineering Group
|-
| 2135
| 0857
| Microcreations
|-
| 2136
| 0858
| Shoestring Productions
|-
| 2137
| 0859
| Faberushi
|-
| 2138
| 085A
| Evesham Micro Ltd.
|-
| 2139
| 085B
| Panagolin Laser Software
|-
| 2140
| 085C
| Thomas Rudloff
|-
| 2141
| 085D
| Daniel Hohabir
|-
| 2142
| 085E
| GfxBase, Inc.
|-
| 2143
| 085F
| Axellabs
|-
| 2144
| 0860
| Roctec Electronics Inc.
|-
| 2145
| 0861
| Omega Datentechnik
|-
| 2146
| 0862
| Atlantis
|-
| 2147
| 0863
| Skytec Computers
|-
| 2148
| 0864
| Protar Electronics
|-
| 2149
| 0865
| ACS
|-
| 2150
| 0866
| Software Results Enterprises
| Originally registered to University of Illinois
|-
| 2151
| 0867
| Infinity Systems Design Group
|-
| 2152
| 0868
| Trade It
|-
| 2153
| 0869
| Suntec, Inc.
|-
| 2154
| 086A
| DJW Micro Systems
| Originally registered to Tritec Marketing
|-
| 2155
| 086B
| Power Computing Ltd.
|-
| 2156
| 086C
| MacroSystems
|-
| 2157
| 086D
| Masoboshi GmbH (DCE)
|-
| 2158
| 086E
| HAL Software Hardware Handel
|-
| 2159
| 086F
| Mainhattan Data
| Originally registered to Michael Lamm Computersysteme
|-
| 2160
| 0870
| Digital Processing System
| Originally registered to bbdp Electronics
|-
| 2161
| 0871
| Blue Ribbon Soundworks
| Originally registered to Design Computer Systems
|-
| 2162
| 0872
| XPert
| Originally registered to The Station
|-
| 2163
| 0873
| DelaComp
| Originally registered to Bryan Williams
|-
| 2164
| 0874
| Superformance Computer Engineering GmbH
|-
| 2165
| 0875
| Overland Engineering
|-
| 2166
| 0876
| Thomas Hamren
|-
| 2167
| 0877
| Village Tronic
|-
| 2168
| 0878
| Toolbox Design
|-
| 2169
| 0879
| Digital Processing System
|-
| 2170
| 087A
| Superformance
|-
| 2171
| 087B
| Utilities Unlimited
|-
| 2172
| 087C
| phase 5
|-
| 2173
| 087D
| Juergen Kommos
|-
| 2174
| 087E
| Electronic Design
|-
| 2175
| 087F
| James Cook University of North Queensland
|-
| 2176
| 0880
| AmiTrix Development
|-
| 2177
| 0881
| Ferranti
|-
| 2178
| 0882
| Leviathan Development
|-
| 2179
| 0883
| United Video Inc.
|-
| 2180
| 0884
| GPSoft Pty. Ltd.
| Originally registered to Juergen Kommos
|-
| 2181
| 0885
| ArMAX
| Oliver Bausch
|-
| 2182
| 0886
| CP Computer
|-
| 2183
| 0887
| AMOK - Amiga Module & Oberon Klub
|-
| 2184
| 0888
| ITEK Neser & Sieber GbR
|-
| 2185
| 0889
| Phillip C. Lello
|-
| 2186
| 088A
| Cyborg Design Services
|-
| 2187
| 088B
| G2 Systems
|-
| 2188
| 088C
| Pro System Computersysteme
|-
| 2189
| 088D
| ZEUS Electronic
| Originally registered to MSPI (Markt & Technik)
|-
| 2190
| 088E
| Altatech
|-
| 2191
| 088F
| NewTek
|-
| 2192
| 0890
| M-TEC Hardware Design
| Originally registered to Hardware Design Udo Neuroth
|-
| 2193
| 0891
| Great Valley Products
| Originally registered to Viona Development
|-
| 2194
| 0892
| Amitek
| Originally assigned to Marpet Developments
|-
| 2195
| 0893
| Ingenieurbuero Helfrich
|-
| 2196
| 0894
| The Neo Group
|-
| 2197
| 0895
| Cyon
|-
| 2198
| 0896
| Bob Research Group
|-
| 2199
| 0897
| Richmond Sound Design Ltd.
|-
| 2200
| 0898
| US Cybernetics
|-
| 2201
| 0899
| Fulvio Ieva
|-
| 2202
| 089A
| Silicon Studio
|-
| 2203
| 089B
| MacroSystems (USA)
| Was named Micro System Devices
|-
| 2204
| 089C
| Conspector Entertainment
|-
| 2205
| 089D
| Laserforum
|-
| 2206
| 089E
| Elbox Computer
| Mistakenly used by Index Information Ltd.
|-
| 2207
| 089F
| Applied Magic Inc.
|-
| 2208
| 08A0
| SDL Ltd.
|-
| 2560
| 0A00
| Harms
|-
| 2588
| 0A1C
| A1K.org Community
|-
| 2640
| 0A50
| Micronik
|-
| 3084
| 0C0C
| Team 4
|-
| 3643
| 0E3B
| E3B
| Michael Boehmer
|-
| 3855
| 0F0F
| Micronik
|-
| 4096
| 1000
| MegaMicro
|-
| 4110
| 100E
| DigiFeX
|-
| 4136
| 1028
| Imtronics/Memphis
|-
| 4149
| 1035
| PROTAR
|-
| 4369
| 1111
| Frank Strauß Elektronik
| Also used by Kupke
|-
| 4626
| 1212
| Individual Computers
|-
| 4648
| 1228
| Flesch Hornemann Computer Elec.
|-
| 4680
| 1248
| Kupke Computertechnik GmbH
|-
| 4711
| 1267
| RBM digitaltechnik
|-
| 4754
| 1292
| MacroSystems
|-
| 5000
| 1388
| ITH
|-
| 5001
| 1389
| VMC
|-
| 5010
| 1392
| Ambience Creation Technology
|-
| 5011
| 1393
| Creative Development
|-
| 5012
| 1394
| Georg Braun
|-
| 5013
| 1395
| Swedish User Group of Amiga
|-
| 5014
| 1396
| Jakub Bednarski
|-
| 5015
| 1397
| KryoFlux, Ltd.
|-
| 5016
| 1398
| Igor Majstorovic
|-
| 5017
| 1399
| Alastair M. Robinson
|-
| 5018
| 139A
| Austex Software
|-
| 5019
| 139B
| Sören Gust
|-
| 5020
| 139C
| Rok Krajnc
|-
| 5030
| 13A6
| Tim Tashpulatov
|-
| 5040
| 13B0
| 7-bit
|-
| 5050
| 13BA
| Sakura IT
|-
| 5060
| 13C4
| FPGAArcade
|-
| 5070
| 13CE
| CancerSoft Inc.
|-
| 5080
| 13D8
| Stephen Leary
|-
| 5090
| 13E2
| DMA Softlab LLC
|-
| 5100
| 13EC
| Brookhouse Engineering
|-
| 5110
| 13F6
| Eduardo Arana
|-
| 5120
| 1400
| CS-LAB
|-
| 5130
| 140A
| Robert Miranda
|-
| 5140
| 1414
| RastPort
|-
| 5132
| 140C
| UAS Interface Ltd6
|-
| 5150
| 141E
| Amiga Kit
|-
| 5160
| 1428
| Central Texas Commodore User Group
|-
| 5170
| 1432
| Confusion Research Center
|-
| 5180
| 143C
| Solar Soyuz Zaibatsu
|-
| 5500
| 157C
| Inhouse Information
|-
| 5768
| 1688
| Bio Con
|-
| 6148
| 1804
| HK-Computer
|-
| 6502
| 1966
| Cloanto
|-
| 6520
| 1978
| Oliver Gantert
|-
| 7777
| 1E61
| Rafal Gabriel Chyla
|-
| 8215
| 2017
| Vortex
|-
| 8244
| 2034
| Spirit Technology
|-
| 8290
| 2062
| Expansion Systems
|-
| 8448
| 2100
| ReadySoft
|-
| 8512
| 2140
| Phase 5 Digital Products
|-
| 8553
| 2169
| Digital Processing Systems Inc.
|-
| 8704
| 2200
| ACT Elektronik
|-
| 8738
| 2222
| ACT Elektronik
|-
| 9512
| 2528
| Tower Technologies
|-
| 10676
| 29B4
| Electronic Design
|-
| 14195
| 3773
| Media-net-Point
|-
| 14501
| 38A5
| Petsoff, Finland
|-
| 16375
| 3FF7
| Uwe Gerlach
|-
| 16707
| 4143
| Ateo Concepts
|-
| 16708
| 4144
| ALiENDESiGN
|-
| 16945
| 4231
| A.C.T.
|-
| 17740
| 454C
| HK-Computer (ELSAT)
|-
| 18260
| 4754
| MacroSystems (Germany)
|-
| 19796
| 4D54
| Markt & Technik
|-
| 22359
| 5757
| Markt & Technik
|-
| 26464
| 6760
| Combitec
|-
| 26470
| 6766
| Combitec
|-
| 28014
| 6D6E
| MNT Media and Technology UG
|-
| 32768
| 8000
| M.A.S.T.
|-
| 42240
| A500
| Aethreum Digital
|-
| 43437
| A9AD
| Reis-Ware
|-
| 43521
| AA01
| Cameron
|-
| 43537
| AA11
| Reis-Ware
|-
| 44359
| AD47
| Matay
|-
| 46504
| B5A8
| Phoenix
|-
| 48879
| BEEF
| Swiss Mountain Dog Products
|-
| 49160
| C008
| Combitec
|-
| 61453
| F00D
| Forefront Technologies Inc.
|}

For any changes/additions to this registry please send a support request to [mailto:support@hyperion-entertainment.com support@hyperion-entertainment.com].

Amiga Hardware Manufacturer ID Registry

2026-09-08T09:38:33Z

Costel Mincea: Added "Swiss Mountain Dog Products"

__TOC__

= How to Obtain a Manufacturer Number =

Manufacturer's numbers are assigned by the AmigaOS development team. To obtain your unique manufacturer number send a support request to [mailto:support@hyperion-entertainment.com support@hyperion-entertainment.com].

Be sure and include your name and the type of expansion product you are developing.

= Your Manufacturer Number =

Attention hardware manufacturers. If you are developing a hardware expansion product for the Classic Amiga (e.g. 500, 2000, 3000) then you will need to obtain a special manufacturer ID number from the AmigaOS development team to identify your product. This manufacturer number is used by the Amiga to link your hardware with its driver software at boot time.

Your manufacturer number is part of the special protocol that the Amiga uses to automatically configure all expansion devices on the bus without the user having to cut jumpers or adjust dip switches. This is called auto-config.

At start-up time, the system first polls each board in the system and assigns the board its own address space. If it is a memory board, its RAM is linked into the memory free pool. Later in the boot sequence, after DOS is initialized, the binddrivers program is run. Binddrivers will search the directory SYS:Expansion for the drivers that go with the boards.

To do this binddrivers looks in the Tool Type field of all icon files in SYS:Expansion. If the first seven bytes of the Tool Type field are "PRODUCT", then this is an icon file for a driver.

Binddrivers will then attempt to match the drivers it has found with the boards that were found earlier. This is where your manufacturer number comes in.

Your manufacturer number goes in two places. First, it is burned in hex form into the PAL which is part of ALL auto-config expansion products. Second, it appears in ASCII in the Tool Type field of the icon file for your product's driver. By matching these two numbers, the Amiga can automatically configure your board and bind it's software driver into the system as well.

The manufacturer's number is a 16-bit ID which appears in PAL offsets $10-$17. There is also an 8-bit product number which you assign. The product number is for uniquely identifying different products from the same vendor. The product number will appear in PAL offsets $04-$07. This gives you a total of 24 bits to identify each of your products.

These 24 bits of information in the PAL which identify your product are matched against the information in the Tool Type field of all icon files in the SYS:Expansion drawer. For example, suppose you are manufacturer #1019. You have two products, #1 and #2 which both use the same driver. The icon for your driver for these two products would have a Tool Type set to "PRODUCT=1019/1|1019/2". This means: I am an icon for a driver that works with product number 1 or 2 from manufacturer 1019, now bind me. Spaces are not legal. Here are two other examples:

; PRODUCT=1208/11
: is the Tool Type for a driver for product 11 from manufacturer number 1208.

; PRODUCT=1017
: is the Tool Type for a driver for any product from manufacturer number 1017.

For an informal explanation of the auto-configuration process, see the chapter on Software Expansion Architecture from the 2nd Annual Amiga Developer's Conference Notes (available on ADCD 2.1). For the details of timing, power, the PAL equations and PAL address specifications and the expansion library documentation, see sections 3.1 to 3.3 of the A500/A2000 Technical Reference Manual. The original auto-config spec appears in the A1000 Schematics and Expansion Specification.

The auto-config process makes the addition of expansion products to the system very easy. All the user has to do is put the board in any slot and copy the driver from the release disk to his own SYS:Expansion drawer. Everything else is automatic. There are no jumpers or dip switches to set. Best of all, you will get a lot less support calls asking how to make your product work with the XYZ-Corp-battery-backed-clock.

= Notes =

Some notes on hardware manufacturer ID assignment.

* Manufacturer ID numbers are assigned free of charge.
* Please provide the following information when requesting an ID:
*# Name of the company or person
*# Postal address/contact address
*# Name of the contact person, with a corresponding e-mail address
*# A brief description of the kind of products you want to produce
* All ID numbers smaller than 5000 must be considered unsafe because no information exists on which numbers exactly were taken during the time Commodore, Inc. disintegrated.
* ID numbers in the range 8192 to 18841 must be considered unsafe because some hardware developers mistook the numbers assigned to them to be given in hexadecimal format. Hence 0x2000 = 8192 and 0x4999 = 18841.

= Example code =

<syntaxhighlight lang="C" line>
/*-----------------------------------------------*/
/* Here is a short program which will tell you */
/* about the expansion boards configured in your */
/* system without you opening up the machine. */
/* Code by Bill Koester of CATS */
/*-----------------------------------------------*/
#include <libraries/configvars.h>
#include <libraries/expansion.h>

struct ExpansionBase *ExpansionBase;

void cleanup();
void printdev();

int main()
{
struct ConfigDev *MyConfigDev;

/*----------------------------------*/
/* Open the expansion library, */
/* if there is a problem then exit */
/*----------------------------------*/

ExpansionBase =(struct ExpansionBase *) OpenLibrary(EXPANSIONNAME,0);
if(ExpansionBase==NULL)
{
printf("Error opening expansion library!!\n");
cleanup();
exit(0);
}

/*--------------------------------------------*/
/* Use FindConfigDev to get info on the first */
/* expansion board on the list maintained by */
/* Exec. If there are no expansion boards in */
/* the system then exit. */
/*--------------------------------------------*/

MyConfigDev = NULL;

/*--------------------------------------------------*/
/* FindConfigDev(oldConfigDev,manufacturer,product) */
/* oldConfigDev = NULL for the top of the list */
/* manufacturer = -1 for any manufacturer */
/* product = -1 for any product */
/*--------------------------------------------------*/

MyConfigDev = FindConfigDev(NULL,-1,-1);

if(MyConfigDev==NULL)
{
printf("No Configured Devices found!!\n");
cleanup();
exit(0);
}

printdev(MyConfigDev);

/*-----------------------------------*/
/* OK, there is at least one board, */
/* so loop and get the entire list */
/* printing as we go with printdev() */
/*-----------------------------------*/

while(MyConfigDev = FindConfigDev(MyConfigDev,-1,-1))
{
printdev(MyConfigDev);
}
cleanup();
return 0;
}

/*-------------------*/
/* Close up shop... */
/*-------------------*/
void cleanup()
{
if(ExpansionBase)
CloseLibrary(ExpansionBase);
}

/*----------------------------------*/
/* Print out the contents of the */
/* dev structure for this expansion */
/* product. */
/*----------------------------------*/

void printdev(dev)
struct ConfigDev *dev;
{
char buff[200];

printf("Flags = ");
if(dev->cd_Flags==NULL)
printf("NULL ");
if(dev->cd_Flags&CDF_SHUTUP)
printf("CDF_SHUTUP ");
if(dev->cd_Flags&CDF_CONFIGME)
printf("CDF_CONFIGME ");
printf("\n");
printf("Board Address = %x\n",dev->cd_BoardAddr);
printf("Board Size = %d bytes\n",dev->cd_BoardSize);
printf("Slot Address = %d\n",dev->cd_SlotAddr);
printf("Slot Size = %d\n",dev->cd_SlotSize);
printf("Driver code at %x\n",dev->cd_Driver);

printf("er_Type = %x\n",dev->cd_Rom.er_Type);
printf("er_Product = %x\n",dev->cd_Rom.er_Product);
printf("er_Flags = %x\n",dev->cd_Rom.er_Flags);
printf("er_Reserved03 = %x\n",dev->cd_Rom.er_Reserved03);
printf("er_Manufacturer = %x\n",dev->cd_Rom.er_Manufacturer);
printf("er_SerialNumber = %x\n",dev->cd_Rom.er_SerialNumber);
printf("er_InitDiagVec = %x\n",dev->cd_Rom.er_InitDiagVec);
printf("er_Reserved0c = %x\n",dev->cd_Rom.er_Reserved0c);
printf("er_Reserved0d = %x\n",dev->cd_Rom.er_Reserved0d);
printf("er_Reserved0e = %x\n",dev->cd_Rom.er_Reserved0e);
printf("er_Reserved0f = %x\n",dev->cd_Rom.er_Reserved0f);

printf("Hit Return to continue:\n");
gets(buff);
}
</syntaxhighlight>

= Registry =

{| class="wikitable"
! ID (decimal)
! ID (hexadecimal)
! Manufacturer
! Notes
|-
| 1
| 0001
| Micronik
|-
| 211
| 00D3
| Pacific Peripherals/Profex
|-
| 221
| 00DD
| Kupke Computertechnik GmbH
|-
| 256
| 0100
| Memphis
| Originally registered to MacroSystems US
|-
| 512
| 0200
| 3-State Computertechnik
|-
| 513
| 0201
| Commodore (Braunschweig)
|-
| 514
| 0202
| Commodore (West Chester)
|-
| 515
| 0203
| Commodore (West Chester)
| Originally registered to Combitech/Macrosystem
|-
| 756
| 02F4
| Progressive Peripherals & Software
|-
| 767
| 02FF
| Kolff Computer Supplies
|-
| 1001
| 03E9
| Tecmar
|-
| 1002
| 03EA
| Telesys
|-
| 1003
| 03EB
| The Micro-Forge
|-
| 1004
| 03EC
| Kronos/C Ltd.
| Originally registered to Card Co. (Supra)
|-
| 1005
| 03ED
| A-Squared
|-
| 1006
| 03EE
| Comspec Communications
|-
| 1007
| 03EF
| HT Electronics
|-
| 1008
| 03F0
| RDS Software
|-
| 1009
| 03F1
| Anakin Research
|-
| 1010
| 03F2
| MicroBotics
|-
| 1011
| 03F3
| Bob Krauth
|-
| 1012
| 03F4
| Access Associates (Alegra)
|-
| 1013
| 03F5
| Mini Comp Systems Ltd.
|-
| 1014
| 03F6
| Cypress Technology
|-
| 1015
| 03F7
| Fuller Computers
|-
| 1016
| 03F8
| Galaxy Computers
|-
| 1017
| 03F9
| ADA Research
|-
| 1018
| 03FA
| Computer Service Italia
|-
| 1019
| 03FB
| Amigo
|-
| 1020
| 03FC
| Micro-Solutions Inc.
|-
| 1021
| 03FD
| Stacar International
|-
| 1022
| 03FE
| Video Precisions
|-
| 1023
| 03FF
| ASDG, Inc.
|-
| 1025
| 0401
| Ing. Buero Kalawsky
|-
| 1026
| 0402
| Computer Tuning
|-
| 1027
| 0403
| Interplan Unternehmensberatung
|-
| 1028
| 0404
| Imtronics/Memphis
| Originally registered to Peter Ohlich
|-
| 1030
| 0406
| Commodore (Lowell University)
| Originally registered to Productivity Center
|-
| 1041
| 0411
| Design Labs
|-
| 1042
| 0412
| MCS
|-
| 1043
| 0413
| B. J. Freeman
|-
| 1044
| 0414
| Side Effects Inc.
|-
| 1045
| 0415
| Oklahoma Personal Comp.
|-
| 1046
| 0416
| Advanced Micro Innovations
|-
| 1047
| 0417
| Industrial Support Services
|-
| 1048
| 0418
| Technisoft
|-
| 1049
| 0419
| Prolific, Inc.
|-
| 1050
| 041A
| Softeam, Inc.
|-
| 1051
| 041B
| GRC Electronics
|-
| 1052
| 041C
| David Lai
|-
| 1053
| 041D
| Ameristar Technologies
|-
| 1054
| 041E
| Cline Refrigeration
|-
| 1055
| 041F
| Cardiac Pacemakers, Inc.
|-
| 1056
| 0420
| Supra Corp. (Creative Microsystems)
|-
| 1057
| 0421
| Wayne Diener
|-
| 1058
| 0422
| Computer Systems Associates (CSA)
|-
| 1059
| 0423
| Trionix, Inc.
|-
| 1060
| 0424
| David Lucas
|-
| 1061
| 0425
| Analog Precision
| Also assigned to D & L Distributing
|-
| 1267
| 04F3
| RBM Digitaltechnik
|-
| 1282
| 0502
| M-TEC Hardware Design
|-
| 1337
| 0539
| Thomas Stenzel (DaFR34K)
|-
| 1576
| 0628
| Boris Križma
|-
| 1761
| 06E1
| Great Valley Products
|-
| 1803
| 070B
| UAE Amiga Emulator
|-
| 2002
| 07D2
| Mimetics Corp.
|-
| 2003
| 07D3
| ACDA
|-
| 2004
| 07D4
| Finn R. Jacobsen
|-
| 2005
| 07D5
| Elthen Electronics
|-
| 2006
| 07D6
| Nine Tiles Computer Systems Ltd.
|-
| 2007
| 07D7
| Analog Electronics
|-
| 2008
| 07D8
| Bell & Howell
|-
| 2009
| 07D9
| Roland Kochler
|-
| 2010
| 07DA
| Byte Corp.
|-
| 2011
| 07DB
| Reserved
|-
| 2012
| 07DC
| DKB, Inc.
| Previously named Michigan Software
|-
| 2013
| 07DD
| Pacific Peripherals
|-
| 2014
| 07DE
| Sysaphus Software
|-
| 2015
| 07DF
| Digitronics
|-
| 2016
| 07E0
| Akron Systems
|-
| 2017
| 07E1
| Great Valley Products
|-
| 2018
| 07E2
| Calmos
|-
| 2019
| 07E3
| Dover Research
|-
| 2020
| 07E4
| David Krehbiel
|-
| 2021
| 07E5
| Synergy Peripheral Systems
| Also known as California Access
|-
| 2022
| 07E6
| Xetec
|-
| 2023
| 07E7
| Micron Technology
|-
| 2024
| 07E8
| CH Electronics
|-
| 2025
| 07E9
| American Liquid Light
|-
| 2026
| 07EA
| Progressive Peripherals & Software
| Also used by Ateo
|-
| 2027
| 07EB
| Wicat Systems
|-
| 2028
| 07EC
| Applied Systems & Peripherals
|-
| 2029
| 07ED
| Delaware Valley Software
|-
| 2030
| 07EE
| Palomax
|-
| 2031
| 07EF
| Incognito Software
|-
| 2032
| 07F0
| Jadesign
|-
| 2033
| 07F1
| BVR
|-
| 2034
| 07F2
| Spirit Technology
|-
| 2035
| 07F3
| Spirit Technology
|-
| 2036
| 07F4
| Atronic
|-
| 2037
| 07F5
| Scott Karlin
|-
| 2038
| 07F6
| Howitch
|-
| 2039
| 07F7
| Sullivan Brothers Visual Engineers
|-
| 2040
| 07F8
| G I T
|-
| 2041
| 07F9
| Amigo Business Computers
|-
| 2042
| 07FA
| Micro E Ab
|-
| 2043
| 07FB
| Ralph Kruse
|-
| 2044
| 07FC
| Clearpoint Research
|-
| 2045
| 07FD
| Kodiak
|-
| 2046
| 07FE
| BSC
| Originally registered to Phoenix Electronics
|-
| 2047
| 07FF
| No Name Shown
|-
| 2048
| 0800
| Commodore Braunschweig
|-
| 2049
| 0801
| BSC
| Originally registered to Elaborate Bytes
|-
| 2050
| 0802
| Kronos/C Ltd.
|-
| 2051
| 0803
| Spartanics
|-
| 2052
| 0804
| Jochheim Computer Tuning
|-
| 2053
| 0805
| Trans Data Systems
|-
| 2054
| 0806
| Applied Systems & Peripherals Ltd.
|-
| 2055
| 0807
| Checkpoint Technologies
| Originally registered to Amiga Solutions
|-
| 2056
| 0808
| Adept Development
|-
| 2057
| 0809
| Advanced Computer Design
|-
| 2058
| 080A
| Sir Netics
|-
| 2059
| 080B
| Expert Services
|-
| 2060
| 080C
| Digital Art Systems
|-
| 2061
| 080D
| Adept Development
|-
| 2062
| 080E
| Expansion Technologies (Expansion Systems)
|-
| 2063
| 080F
| Alphatech
|-
| 2064
| 0810
| Edotronik GmbH
|-
| 2065
| 0811
| California Access/Synergy
| Originally registered to Logical Design Works
|-
| 2066
| 0812
| Bowden, Williams, Full & Assoc.
|-
| 2067
| 0813
| NES, Inc.
|-
| 2068
| 0814
| Amdev
|-
| 2069
| 0815
| Big Brother Security Systems
|-
| 2070
| 0816
| Active Circuits Inc.
|-
| 2071
| 0817
| ICD, Inc.
|-
| 2072
| 0818
| Multi-Meg Electronique
|-
| 2073
| 0819
| Kupke Computertechnik GmbH
|-
| 2074
| 081A
| The Checkered Ball
|-
| 2075
| 081B
| Hi Tension Computer Services Ltd. (UK)
|-
| 2076
| 081C
| Alfa Data
| Originally assigned to Elmtech Research, Ltd. (UK)
|-
| 2077
| 081D
| Great Valley Products
| Originally registered to Clartscreen, Ltd. (UK)
|-
| 2078
| 081E
| Interworks
|-
| 2079
| 081F
| Galysh Enterprises
|-
| 2080
| 0820
| Hardital Synthesis
| Originally registered to Realtime Games Software Ltd.
|-
| 2081
| 0821
| GBS
|-
| 2082
| 0822
| Circum Design Inc.
|-
| 2083
| 0823
| Alberta Micro Electronic Center
|-
| 2084
| 0824
| Bestech
|-
| 2085
| 0825
| Lasar Fantasy
|-
| 2086
| 0826
| Pulsar
|-
| 2087
| 0827
| Ivis
|-
| 2088
| 0828
| Applied Engineering
|-
| 2089
| 0829
| Solid-State Design & Development
|-
| 2090
| 082A
| Vison Quest
|-
| 2091
| 082B
| Seaview Software
|-
| 2092
| 082C
| BSC
| Mistakenly used by ADS (Advanced Development Software)
|-
| 2093
| 082D
| Bernd Culenfeld
|-
| 2094
| 082E
| American Liquid Light
|-
| 2095
| 082F
| CEGITES
|-
| 2096
| 0830
| Quadlite Computers Ltd.
| Originally registered to EV Industries
|-
| 2097
| 0831
| Silicon Peace
|-
| 2098
| 0832
| Black Belt Systems
|-
| 2099
| 0833
| Village Tronic
| Originally registerd to Steve Yaeger
|-
| 2100
| 0834
| ReadySoft
|-
| 2101
| 0835
| Phoenix Micro Technologies
|-
| 2102
| 0836
| Advanced Systems & Software
| Orignally assigned to Preferred Technology
|-
| 2103
| 0837
| Rombo Productions
|-
| 2104
| 0838
| Impulse Inc.
|-
| 2105
| 0839
| Beta Unlimited
|-
| 2106
| 083A
| Memory Expansion System, Ltd.
|-
| 2107
| 083B
| Vortex Computer Systems GmbH
|-
| 2108
| 083C
| Platypus Systems
|-
| 2109
| 083D
| Gigatron OHG
|-
| 2110
| 083E
| PG Electronics
|-
| 2111
| 083F
| New Technologies Group
|-
| 2112
| 0840
| Interactive Video Systems (IVS)
| Pacific Peripherals
|-
| 2113
| 0841
| Vector
| Originally registered to H. K. Computer
|-
| 2114
| 0842
| Pacific Digital
| Originally registered to C. H. Helfrich Elektronik
|-
| 2115
| 0843
| Xanadu
|-
| 2116
| 0844
| Pacific Digital
| Originally registered to AMS
|-
| 2117
| 0845
| X-Pert
|-
| 2118
| 0846
| The Amiga Centre
|-
| 2119
| 0847
| Digital Pacific
|-
| 2120
| 0848
| Solid State Leisure
|-
| 2121
| 0849
| Hydra Systems
| Originally registered to Analog Electronics
|-
| 2122
| 084A
| Cumana
|-
| 2123
| 084B
| KAPS 2C Conception
|-
| 2124
| 084C
| Mike Mason
|-
| 2125
| 084D
| For Your Eyes
|-
| 2126
| 084E
| Volkmar Breitfeld Computersysteme
|-
| 2127
| 084F
| Sunrize Industries
|-
| 2128
| 0850
| Scott Advanced Micro Designs
|-
| 2129
| 0851
| Digital Micronics
|-
| 2130
| 0852
| Alfa-Laval
|-
| 2131
| 0853
| Multigros A/S
|-
| 2132
| 0854
| Archos
|-
| 2133
| 0855
| Icom Simulations
|-
| 2134
| 0856
| Commodore Test Engineering Group
|-
| 2135
| 0857
| Microcreations
|-
| 2136
| 0858
| Shoestring Productions
|-
| 2137
| 0859
| Faberushi
|-
| 2138
| 085A
| Evesham Micro Ltd.
|-
| 2139
| 085B
| Panagolin Laser Software
|-
| 2140
| 085C
| Thomas Rudloff
|-
| 2141
| 085D
| Daniel Hohabir
|-
| 2142
| 085E
| GfxBase, Inc.
|-
| 2143
| 085F
| Axellabs
|-
| 2144
| 0860
| Roctec Electronics Inc.
|-
| 2145
| 0861
| Omega Datentechnik
|-
| 2146
| 0862
| Atlantis
|-
| 2147
| 0863
| Skytec Computers
|-
| 2148
| 0864
| Protar Electronics
|-
| 2149
| 0865
| ACS
|-
| 2150
| 0866
| Software Results Enterprises
| Originally registered to University of Illinois
|-
| 2151
| 0867
| Infinity Systems Design Group
|-
| 2152
| 0868
| Trade It
|-
| 2153
| 0869
| Suntec, Inc.
|-
| 2154
| 086A
| DJW Micro Systems
| Originally registered to Tritec Marketing
|-
| 2155
| 086B
| Power Computing Ltd.
|-
| 2156
| 086C
| MacroSystems
|-
| 2157
| 086D
| Masoboshi GmbH (DCE)
|-
| 2158
| 086E
| HAL Software Hardware Handel
|-
| 2159
| 086F
| Mainhattan Data
| Originally registered to Michael Lamm Computersysteme
|-
| 2160
| 0870
| Digital Processing System
| Originally registered to bbdp Electronics
|-
| 2161
| 0871
| Blue Ribbon Soundworks
| Originally registered to Design Computer Systems
|-
| 2162
| 0872
| XPert
| Originally registered to The Station
|-
| 2163
| 0873
| DelaComp
| Originally registered to Bryan Williams
|-
| 2164
| 0874
| Superformance Computer Engineering GmbH
|-
| 2165
| 0875
| Overland Engineering
|-
| 2166
| 0876
| Thomas Hamren
|-
| 2167
| 0877
| Village Tronic
|-
| 2168
| 0878
| Toolbox Design
|-
| 2169
| 0879
| Digital Processing System
|-
| 2170
| 087A
| Superformance
|-
| 2171
| 087B
| Utilities Unlimited
|-
| 2172
| 087C
| phase 5
|-
| 2173
| 087D
| Juergen Kommos
|-
| 2174
| 087E
| Electronic Design
|-
| 2175
| 087F
| James Cook University of North Queensland
|-
| 2176
| 0880
| AmiTrix Development
|-
| 2177
| 0881
| Ferranti
|-
| 2178
| 0882
| Leviathan Development
|-
| 2179
| 0883
| United Video Inc.
|-
| 2180
| 0884
| GPSoft Pty. Ltd.
| Originally registered to Juergen Kommos
|-
| 2181
| 0885
| ArMAX
| Oliver Bausch
|-
| 2182
| 0886
| CP Computer
|-
| 2183
| 0887
| AMOK - Amiga Module & Oberon Klub
|-
| 2184
| 0888
| ITEK Neser & Sieber GbR
|-
| 2185
| 0889
| Phillip C. Lello
|-
| 2186
| 088A
| Cyborg Design Services
|-
| 2187
| 088B
| G2 Systems
|-
| 2188
| 088C
| Pro System Computersysteme
|-
| 2189
| 088D
| ZEUS Electronic
| Originally registered to MSPI (Markt & Technik)
|-
| 2190
| 088E
| Altatech
|-
| 2191
| 088F
| NewTek
|-
| 2192
| 0890
| M-TEC Hardware Design
| Originally registered to Hardware Design Udo Neuroth
|-
| 2193
| 0891
| Great Valley Products
| Originally registered to Viona Development
|-
| 2194
| 0892
| Amitek
| Originally assigned to Marpet Developments
|-
| 2195
| 0893
| Ingenieurbuero Helfrich
|-
| 2196
| 0894
| The Neo Group
|-
| 2197
| 0895
| Cyon
|-
| 2198
| 0896
| Bob Research Group
|-
| 2199
| 0897
| Richmond Sound Design Ltd.
|-
| 2200
| 0898
| US Cybernetics
|-
| 2201
| 0899
| Fulvio Ieva
|-
| 2202
| 089A
| Silicon Studio
|-
| 2203
| 089B
| MacroSystems (USA)
| Was named Micro System Devices
|-
| 2204
| 089C
| Conspector Entertainment
|-
| 2205
| 089D
| Laserforum
|-
| 2206
| 089E
| Elbox Computer
| Mistakenly used by Index Information Ltd.
|-
| 2207
| 089F
| Applied Magic Inc.
|-
| 2208
| 08A0
| SDL Ltd.
|-
| 2560
| 0A00
| Harms
|-
| 2588
| 0A1C
| A1K.org Community
|-
| 2640
| 0A50
| Micronik
|-
| 3084
| 0C0C
| Team 4
|-
| 3643
| 0E3B
| E3B
| Michael Boehmer
|-
| 3855
| 0F0F
| Micronik
|-
| 4096
| 1000
| MegaMicro
|-
| 4110
| 100E
| DigiFeX
|-
| 4136
| 1028
| Imtronics/Memphis
|-
| 4149
| 1035
| PROTAR
|-
| 4369
| 1111
| Frank Strauß Elektronik
| Also used by Kupke
|-
| 4626
| 1212
| Individual Computers
|-
| 4648
| 1228
| Flesch Hornemann Computer Elec.
|-
| 4680
| 1248
| Kupke Computertechnik GmbH
|-
| 4711
| 1267
| RBM digitaltechnik
|-
| 4754
| 1292
| MacroSystems
|-
| 5000
| 1388
| ITH
|-
| 5001
| 1389
| VMC
|-
| 5010
| 1392
| Ambience Creation Technology
|-
| 5011
| 1393
| Creative Development
|-
| 5012
| 1394
| Georg Braun
|-
| 5013
| 1395
| Swedish User Group of Amiga
|-
| 5014
| 1396
| Jakub Bednarski
|-
| 5015
| 1397
| KryoFlux, Ltd.
|-
| 5016
| 1398
| Igor Majstorovic
|-
| 5017
| 1399
| Alastair M. Robinson
|-
| 5018
| 139A
| Austex Software
|-
| 5019
| 139B
| Sören Gust
|-
| 5020
| 139C
| Rok Krajnc
|-
| 5030
| 13A6
| Tim Tashpulatov
|-
| 5040
| 13B0
| 7-bit
|-
| 5050
| 13BA
| Sakura IT
|-
| 5060
| 13C4
| FPGAArcade
|-
| 5070
| 13CE
| CancerSoft Inc.
|-
| 5080
| 13D8
| Stephen Leary
|-
| 5090
| 13E2
| DMA Softlab LLC
|-
| 5100
| 13EC
| Brookhouse Engineering
|-
| 5110
| 13F6
| Eduardo Arana
|-
| 5120
| 1400
| CS-LAB
|-
| 5130
| 140A
| Robert Miranda
|-
| 5140
| 1414
| RastPort
|-
| 5132
| 140C
| UAS Interface Ltd6
|-
| 5150
| 141E
| Amiga Kit
|-
| 5160
| 1428
| Central Texas Commodore User Group
|-
| 5170
| 1432
| Confusion Research Center
|-
| 5180
| 143C
| Solar Soyuz Zaibatsu
|-
| 5500
| 157C
| Inhouse Information
|-
| 5768
| 1688
| Bio Con
|-
| 6148
| 1804
| HK-Computer
|-
| 6502
| 1966
| Cloanto
|-
| 6520
| 1978
| Oliver Gantert
|-
| 7777
| 1E61
| Rafal Gabriel Chyla
|-
| 8215
| 2017
| Vortex
|-
| 8244
| 2034
| Spirit Technology
|-
| 8290
| 2062
| Expansion Systems
|-
| 8448
| 2100
| ReadySoft
|-
| 8512
| 2140
| Phase 5 Digital Products
|-
| 8553
| 2169
| Digital Processing Systems Inc.
|-
| 8704
| 2200
| ACT Elektronik
|-
| 8738
| 2222
| ACT Elektronik
|-
| 9512
| 2528
| Tower Technologies
|-
| 10676
| 29B4
| Electronic Design
|-
| 14195
| 3773
| Media-net-Point
|-
| 14501
| 38A5
| Petsoff, Finland
|-
| 16375
| 3FF7
| Uwe Gerlach
|-
| 16707
| 4143
| Ateo Concepts
|-
| 16708
| 4144
| ALiENDESiGN
|-
| 16945
| 4231
| A.C.T.
|-
| 17740
| 454C
| HK-Computer (ELSAT)
|-
| 18260
| 4754
| MacroSystems (Germany)
|-
| 19796
| 4D54
| Markt & Technik
|-
| 22359
| 5757
| Markt & Technik
|-
| 26464
| 6760
| Combitec
|-
| 26470
| 6766
| Combitec
|-
| 28014
| 6D6E
| MNT Media and Technology UG
|-
| 32768
| 8000
| M.A.S.T.
|-
| 42240
| A500
| Aethreum Digital
|-
| 43437
| A9AD
| Reis-Ware
|-
| 43521
| AA01
| Cameron
|-
| 43537
| AA11
| Reis-Ware
|-
| 44359
| AD47
| Matay
|-
| 46504
| B5A8
| Phoenix
|-
| 48879
| BEEF
| Swiss Mountain Dog Products
|-
| 49160
| C008
| Combitec
|-
| 61453
| F00D
| Forefront Technologies Inc.
|}

For any changes/additions to this registry please use the [http://www.amigaos.net/contact AmigaOS web site contact form].

SANA-II Revision 7

2026-09-02T11:09:43Z

Costel Mincea: /* S2_DEVICEQUERY */

{{WIP}}
= SANA-II Network Device Driver Specification =

The "SANA-II Network Device Driver Specification" is a standard for an Amiga software interface between networking hardware and network protocol stacks (or for software tools such as network monitors). A network protocol stack is a layer of software that network applications use to address particular processes on remote machines and to send data reliably in spite of hardware errors. There are several common network protocol stacks including ''TCP/IP'', ''OSI'', ''AppleTalk'', ''DECNet'' and ''Novell''.

SANA-II device drivers are intended to allow multiple network protocol stacks running on the same machine to share one network device. For example, the TCP/IP and AppleTalk protocol stacks could both run on the same machine over one ethernet board. The device drivers are also intended to allow network protocol stacks to be written in a hardware-independent fashion so that a different version of each protocol stack doesn't have to be written for each networking hardware device.

The standard does not address the writing of network applications. Application writers must not use SANA-II Device Drivers directly. Network applications must use the API provided by the network protocol software the application supports. The Amiga standard network API for TCP/IP is provided via the bsdsocket.library which is a part of Roadshow.

To write a SANA-II device driver, you will need to be familiar with the specification documents for the hardware you are writing to and with the "SANA-II Network Device Driver Specification".

To write a network protocol stack which will use SANA-II device drivers, you should have general familiarity with common network hardware and must be very familiar with the "SANA-II Network Device Driver Specification" as well as the specification for the protocol you are developing. If you are creating a new protocol, you must obtain a protocol type number for any hardware on which your protocol will be used.

This version of the specification is final. Any new version of the standard (i.e., to add new features) is planned to be backward compatible. No SANA-II device driver or software utilizing those drivers should be written to any earlier version of the specification.

Distribution of this version of the standard is unlimited. Anyone may write Amiga software which implements a SANA-II network device driver or which calls a SANA-II network device driver without restriction and may freely distribute such software that they have written.

It is important to try to test each SANA-II device driver against all software which uses SANA-II devices. Available example programs are valuable in initial testing. The Amiga Networking Group is interested in receiving evaluation and/or beta test copies of all Amiga networking hardware, SANA-II device drivers and software which uses SANA-II devices. However, we make no assurances regarding any testing which we may or may not perform with such evaluation copies.

The SANA-II standard caters to both Motorola 68000 platforms and PowerPC platforms.

Please feel free to comment. You can contact the AmigaOS development team through the [http://www.amigaos.net/contact AmigaOS contact form].

= Driver Form =

SANA-II device drivers are Amiga Exec device drivers. They use an extended IORequest structure and a number of extended commands for tallying network statistics, sending broadcasts and multicasts, network addressing and the handling of unexpected packets. The SDK includes information on how to construct an Exec device.

= Opening a SANA-II Device =

As when opening any other Exec device, on the call to OpenDevice() a SANA-II device receives an IORequest structure which the device initializes for the opener's use. The opener must copy this structure if it desires to use multiple asynchronous requests. The SANA-II IORequest is defined as follows:

<syntaxhighlight lang="C" line>
struct IOSana2Req
{
struct IORequest ios2_Req;
ULONG ios2_WireError;
ULONG ios2_PacketType;
UBYTE ios2_SrcAddr[SANA2_MAX_ADDR_BYTES];
UBYTE ios2_DstAddr[SANA2_MAX_ADDR_BYTES];
ULONG ios2_DataLength;
APTR ios2_Data;
APTR ios2_StatData;
APTR ios2_BufferManagement;
};
</syntaxhighlight>

; ios2_Req
: A standard Exec device IORequest.
; ios2_WireError
: A more specific device code which may be set when there is an io_Error. See <devices/sana2.h> for the defined WireErrors.
; ios2_PacketType
: The type of packet requested. See the section on "Packet Types".
; ios2_SrcAddr
: The device fills in this field with the interface (network hardware) address of the source of the packet that satisfied a read command. The bytes used to hold the address will be left justified but the bit layout is dependent on the particular type of network.
; ios2_DstAddr
: Before the device user sends a packet, it fills this with the interface destination address of the packet. On receives, the device fills this with the interface destination address. Other commands may use this field differently (see the "SANA-II network device driver Autodocs" in the SDK). The bytes used to hold the address will be left justified but the bit layout is dependent on the particular type of network.
; ios2_DataLength
: The device user initializes this field with the amount of data available in the Data buffer before passing the IOSana2Req to the device. The device fills in this field with the size of the packet data as it was sent on the wire. This does not include the header and trailer information. Depending on the network type and protocol type, the driver may have to calculate this value. This is generally used only for reads and writes (including broadcast and multicast).
; ios2_Data
: A pointer to some abstract data structure containing packet data. ''Drivers may not directly manipulate or examine anything pointed to by Data!'' This is generally used only for reads and writes (including broadcast and multicast).

; ios2_StatData
: Pointer to a structure in which to place a snapshot of device statistics. The data area must be long word aligned. This is only used on calls to the statistics commands.

; ios2_BufferManagement
: The opener places a pointer to a tag list in this field before calling OpenDevice(). Functions pointed to in the tag list are called by the device when processing IORequests from the opener. When returned from OpenDevice(), this field contains a pointer to driver-private information used to access these functions. See "Buffer Management" below for more details.

: Note that the <tt>ios2_BufferManagement</tt> field provided by the driver on <tt>OpenDevice()</tt> time in conjunction with <tt>io_Device</tt> and <tt>io_Unit</tt> is the unique identifier for all requests coming from this protocol stack until <tt>CloseDevice()</tt>. The driver must not ever change the <tt>ios2_BufferManagement</tt> field for a protocol stack at run time, even if <tt>S2_SANAHOOK</tt> is called to request extended features.

The flags used with the device on OpenDevice() are (SANA2OPB_xxx):

{| class="wikitable"
! Name
! Description
|-
| SANA2OPB_MINE
| Exclusive access to the unit requested.
|-
| SANA2OPB_PROM
| Promiscuous mode requested. Hardware which supports promiscuous mode allows all packets sent over the wire to be captured whether or not they are addressed to this node.
'''''Note:''' Promiscuous mode requires exclusive opening of the device.''
|}

The flags used during I/O requests are (SANA2IOB_xxx):

{| class="wikitable"
! Name
! Description
|-
| SANA2IOB_RAW
| Raw packet read/write requested. Raw packets should include the entire data-link layer packet. Devices with the same hardware device number should have the same raw packet format.
|-
| SANA2IOB_BCAST
| Broadcast packet (received).
|-
| SANA2IOB_MCAST
| Multicast packet (received).
|-
| SANA2IOB_QUICK
| Quick IO requested.
|}

= Buffer Management =

Unlike most other Exec Device drivers, SANA-II drivers have no internal buffers. Instead, they read/write to/from an abstract data structure allocated by the driver user. The driver accesses these buffers only via functions that the driver user provides to the driver. The driver user must provide two functions: one copies data to the abstract data structure and one copies data from the abstract data structure. The driver user can therefore choose the data structure used for buffer management by both the driver and driver user in order to have efficient memory and CPU usage overall.

The IOSana2Req contains a pointer to data and the length of said data. A driver is not allowed to make assumptions about how the data is stored. The driver cannot directly manipulate or examine the buffer in any manner. The driver can only access the buffer by calling the functions provided by the driver user.

Before calling OpenDevice(), the driver user points ios2_BufferManagement to a list of tags (defined in <devices/sana2.h>) which include pointers to the buffer management functions required by the driver (defined below). The driver will fail to open if the driver user does not supply all of the required functions. If the device opens successfully, the driver sets ios2_BufferManagement to a value which this opener must use in all future calls to the driver. This "magic cookie" is used from then on to access these functions (a "magic cookie" is a value which one software entity passes to another but which is only meaningful to one of the software entities). The driver user may not use the "magic cookie" in any way--it is for the driver to do with as it wishes. The driver could in theory choose to just copy the tag list to driver-owned memory and then parse the list for every IORequest, but it is much more efficient for the driver to create some sort of table of functions and to point ios2_BufferManagement to that table.

Another recommendation for the ``magic cookie`` is to use it to maintain a separate packet read queue for each device opener. This would allow multiple protocol stacks that all wish to receive the same packet type to work together without having to "know" about each other as ''Envoy'' and ''AS225'' do right now. What does multiple protocol stack support mean? Basically this means that each opener gets all the packets necessary. If a packet comes in that fills a request for more than one opener of the device, all of them will get a copy of the packet. This feature should never be left out of a device design. If it is missing, the usefulness of the device is severely limited.

In order to help system load, a packet filter callback allows protocol stacks to reject packets that are known to not be useful. ''Envoy'''s nipc.library (for example) could be modified to reject TCP packets (as it never uses them).

The specification currently defines the following tags for the OpenDevice() ios2_BufferManagement tag list:

{| class="wikitable"
|+ Copy data from network interface to protocol stack buffer
! Tag
! Description
|-
| S2_CopyToBuff (mandatory)
| This is a pointer to a function which conforms to the CopyToBuff Autodoc.
|-
| S2_CopyToBuff16 (optional)
| Copy to a 16 bit aligned buffer using 16 bit data words.
|-
| S2_CopyToBuff32 (optional)
| Copy to a 32 bit aligned buffer using 32 bit data words.
|-
| S2_DMACopyToBuff32 (optional)
| Perform a DMA copy to a 32 bit aligned contiguous buffer using 32 bit data words.
|-
| S2_DMACopyToBuff64 (optional)
| Perform a DMA copy to a 64 bit aligned contiguous buffer using 64 bit data words.
|}

{| class="wikitable"
|+ Copy data from protocol stack buffer to network interface
! Tag
! Description
|-
| S2_CopyFromBuff (mandatory)
| This is a pointer to a function which conforms to the CopyFromBuff Autodoc.
|-
| S2_CopyFromBuff16 (optional)
| Copy from a 16 bit aligned buffer using 16 bit data words.
|-
| S2_CopyFromBuff32 (optional)
| Copy from a 32 bit aligned buffer using 32 bit data words.
|-
| S2_DMACopyFromBuff32 (optional)
| Perform a DMA copy from a 32 bit aligned contiguous buffer using 32 bit data words.
|-
| S2_DMACopyFromBuff64 (optional)
| Perform a DMA copy from a 64 bit aligned contiguous buffer using 64 bit data words.
|}

{| class="wikitable"
|+ Filter data before protocol stack buffer
! Tag
! Description
|-
| S2_PacketFilter (optional)
| This is a pointer to a standard Hook to be called before S2_CopyToBuff is done. See the PacketFilter Autodoc for more information.
|}

{| class="wikitable"
|+ Logging messages from the driver
! Tag
! Description
|-
| S2_Log (optional)
| This is a pointer to a standard Hook to be called when the driver logs events.
|}

== Better buffer management ==

The mandatory buffer management callbacks may not be very efficient for certain types of hardware. They also do not allow driver DMA access.

All the new features are completely optional and do not collide with existing features. They may be used only when the protocol stack asks for them on opening a driver.

The enhancements consist of several new tags that may be specified by a protocol stack on OpenDevice() to offer certain data transfer options. It is up to the device driver to chose which callbacks to use at what time. These tags are advisory only and may be ignored by the driver for any data buffer at any time:

{| class="wikitable"
| S2_CopyToBuff16
|-
| S2_CopyFromBuff16
|-
| S2_CopyToBuff32
|-
| S2_CopyFromBuff32
|}

These are optional callbacks presented to the device with the same calling interface as for S2_CopyToBuff or S2_CopyFromBuff, respectively. The difference to the original callbacks is the required and guaranteed transfer size and alignment for accessing the device's buffer for a single piece of a data of either 16 or 32 bits, a data word. The copy function called may only use 16/32 bit aligned read/write commands of 16/32 bits at once to transfer the data words, respectively. If the buffer data length is not a multiple of the required data word transfer size, the last data word transfer may contain garbage padding in either transfer direction.

The following tags have been added to support direct writes into hardware buffers that do not allow arbitrarily sized or aligned accesses:

{| class="wikitable"
| S2_DMACopyToBuff32
|-
| S2_DMACopyFromBuff32
|}

If the protocol stack wants to optionally enhance data transfer efficiency with DMA supporting devices, it may pass any of these optional tags to the device on OpenDevice().

If the device driver supports DMA, it may call the respective callback with the abstract magic cookie ios2_Data in register A0. The callback may return NULL in D0. In this case, the driver may not use DMA for this buffer. Alternatively, the callback may return the address of the actual data buffer in D0, if it has these characteristics:

* The buffer is in contiguous memory. Depending on the intended data direction, it shall be readable or writable.
* The buffer is aligned on a 32 bit boundary.
* The buffer size shall be a multiple of 32 bit and it is at least = ios2_DataLength.
* It is up to the driver to decide if it can use DMA for this buffer and it shall fall back to the standard CPU callbacks if necessary. The data transfer method actually used by the driver will not be known in advance by the protocol stack.

The following tags have been added to allow for 64 bit aligned PCI DMA accesses to take place:

{| class="wikitable"
| S2_DMACopyToBuff64
|-
| S2_DMACopyFromBuff64
|}

These two callbacks are identical in operation to the <tt>S2_DMACopyToBuff32</tt> and <tt>S2_DMACopyFromBuff32</tt> callbacks. The difference is in that the memory region DMA is to take place in must be aligned to a 64 bit boundary and must be large enough to hold data that is a multiple of 64 bits in size.

== Best buffer management ==

The SANA-II driver interface is intended to transform data between the hardware layer and the link layer, to be used by networking software such as TCP/IP stacks. This transformation is performed by callback functions which are supplied by the networking software at the time the device driver is opened. The device driver then invokes these functions later in order to transfer data received and data to be sent.

The function parameters used by these callbacks are passed in 68000 registers for the lowest overhead. The problem with 68000 register parameters is that on the PowerPC platform, this form of parameter passing may require the use of emulation code. This is costly and may incur a severe performance penalty. It is an even greater problem if PowerPC native networking software is calling PowerPC native networking driver software and the other way round. In both cases the runtime environment will have to enter emulation mode, return to to PowerPC native execution, dip into emulation mode and return to native PowerPC execution. It would be much better if the chain of execution would stay in PowerPC mode all the time.

Alternatively, if a hook function is used, the operating system may be able to decide whether the function to be invoked needs emulating or called directly. The <tt>Hook</tt> effectively works as an abstraction which makes the function invocation platform independent.

The following standard wraps the copying and logging functions into the standardized <tt>Hook</tt> interface.

==== The hook function ====

The hook function itself is invoked with the following parameters:

<syntaxhighlight lang="C" line>
result = hook_function(hook, sana2req, sana2hookmsg)

ULONG hook_function(struct Hook *hook,
struct IOSana2Req *sana2req,
struct SANA2HookMsg *sana2hookmsg);
</syntaxhighlight>

Note that the result is not necessarily of type <tt>ULONG</tt>. It is a 32 bit value, which can be a boolean result code (for <tt>CopyFromBuff</tt>, <tt>CopyToBuff</tt> and their like) or a pointer to a memory address (for <tt>DMACopyToBuff</tt>, <tt>DMACopyFromBuff</tt> and their like).

=== Data structures ===

The following hook messages are to be used:

<syntaxhighlight lang="C" line>
struct SANA2HookMsg
{
ULONG shm_Method;
ULONG shm_MsgSize;
};
</syntaxhighlight>

In this data structure the <tt>shm_Method</tt> field would indicate the task to be performed. This can be a request to copy data or to store a log message. The <tt>shm_MsgSize</tt> field tells you how large the data structure is for future enhancements which may cause the data structure to grow.

==== Copying operations ====

For copying operations the message is:

<syntaxhighlight lang="C" line>
struct SANA2CopyHookMsg
{
ULONG schm_Method;
ULONG schm_MsgSize;

APTR schm_To;
APTR schm_From;
ULONG schm_Size;
};
</syntaxhighlight>

The structure members are as follows:

; schm_Method
: This must be one <tt>S2_CopyToBuff</tt>, <tt>S2_CopyFromBuff</tt>, <tt>S2_CopyToBuff16</tt>, <tt>S2_CopyFromBuff16</tt>, <tt>S2_CopyToBuff32</tt>, <tt>S2_CopyFromBuff32</tt>, <tt>S2_DMACopyToBuff32</tt>, <tt>S2_DMACopyFromBuff32</tt>, <tt>S2_DMACopyToBuff64</tt> or <tt>S2_DMACopyFromBuff64</tt> to identify the function to be performed.

; schm_MsgSize
: Size of this message data structure in bytes. This must be >= 20 for this message type.
: The driver shall set <tt>schm_MsgSize</tt> always correctly to be compliant. The protocol stack shall use this field to validate the message and to reject/ignore bad messages via a <tt>FALSE</tt> hook function return value. For DMA related hooks, a <tt>FALSE</tt> return value is equivalent to a <tt>NULL</tt> pointer.

; schm_To
: Equivalent to the <tt>to</tt> parameter of the <tt>CopyFromBuff</tt>, <tt>CopyToBuff</tt> and <tt>DMACopyToBuff</tt> functions.

; schm_From
: Equivalent to the <tt>from</tt> parameter of the <tt>CopyFromBuff</tt> and <tt>CopyToBuff</tt> functions.

; schm_Size
: Equivalent to the <tt>n</tt> parameter of the <tt>CopyFromBuff</tt>, <tt>CopyToBuff</tt>, functions.

==== Logging operations ====

For logging operations the message is:

<syntaxhighlight lang="C" line>
struct SANA2LogHookMsg
{
ULONG slhm_Method;
ULONG slhm_MsgSize;

ULONG slhm_Priority;
STRPTR slhm_Name;
STRPTR slhm_Message;
};
</syntaxhighlight>

The structure members would be used as follows:

; slhm_Method
: This must be <tt>S2_Log</tt>, as defined in the SANA-IIR4 specification.

; slhm_MsgSize
: Size of this message data structure in bytes. This must be >= 20 for this message type.
: The driver shall set <tt>slhm_MsgSize</tt> always correctly to be compliant. The protocol stack shall use this field to validate the message and to reject/ignore bad messages via a <tt>FALSE</tt> hook function return value. For DMA related hooks, a <tt>FALSE</tt> return value is equivalent to a <tt>NULL</tt> pointer.

; slhm_Priority
: The smaller this value, the more important the message to be logged or displayed. The following priority levels are defined (similar to the Unix syslog() mechanism):
:{| class="wikitable"
| S2LOG_Emergency || A panic condition.
|-
| S2LOG_Alert || A condition that should be corrected immediately.
|-
| S2LOG_Critical || Critical conditions.
|-
| S2LOG_Error || A plain error.
|-
| S2LOG_Warning || A warning message.
|-
| S2LOG_Notice || Conditions that are not error conditions, but should possibly be handled specially.
|-
| S2LOG_Information || An informational message.
|-
| S2LOG_Debug || Messages that contain information normally of use only when debugging.
|}
: Only these priority values may be used by a driver. It is suggested that a driver is configurable to generate different types of messages or not, e.g., a driver may be configured to only emit <tt>S2LOG_Emergency</tt> and <tt>S2LOG_Debug</tt> messages

; slhm_Name
: Pointer to a <tt>NUL</tt>-terminated string which identifies the source of this message. This can be <tt>NULL</tt> in which case the OS device name of the driver shall be used by the protocol stack.

; slhm_Message
: Pointer to a <tt>NUL</tt>-terminated string which contains the log message. The text should not contain any formatting characters such as line feeds or carriage returns. The <tt>slhm_Message</tt> member must never be <tt>NULL</tt>.
: All message texts shall preferably be formatted in the current user's locale. If that is not possible, the english language shall be used. <tt>slhm_Name</tt> and <tt>slhm_Message</tt> shall only contain printable characters.

=== Application and driver software use of the new functions ===

Since plenty of software exists which uses the 'traditional' <tt>TagItem</tt> list provided at <tt>OpenDevice()</tt> time, drivers must always examine these parameters and not expect a <tt>S2_SANA2HOOK</tt> command to be sent later.

If the new <tt>Hook</tt>-based callback functions are used then the driver must invoke the Hooks via <tt>utility.library/CallHookPkt</tt>. It must never invoke the hook functions through local assembly language stubs or the <tt>amiga.lib/CallHook</tt> and <tt>amiga.lib/CallHookA</tt> functions.

=== Caveats ===

The functionality above suggests that one could do entirely without the <tt>TagItem</tt> list passed in at <tt>OpenDevice()</tt> time. However, at this time it is hard to tell how existing driver software will react to empty <tt>TagItem</tt> lists or even a NULL pointer in the <tt>IOSana2Req->ios2_BufferManagement</tt> field. It is therefore important to always provide for a <tt>TagItem</tt> list which includes proper (i.e. they must point to working functions and may not be <tt>NULL</tt>) function pointers for the <tt>S2_CopyToBuff</tt> and <tt>S2_CopyFromBuff</tt> tags. Once the device has been opened successfully, the next step is to try and install the copy <tt>Hook</tt> through the proposed <tt>S2_SANA2HOOK</tt> command. If the command fails, the application can still expect that the <tt>S2_CopyToBuff</tt> and <tt>S2_CopyFromBuff</tt> tags supplied at <tt>OpenDevice()</tt> time will work.

== Packet filtering ==

With the original "SANA-II Network Device Driver Specification", a protocol stack could open a device and ask for certain packet types. It got all the packets that matched this type. As it turned out, this could be mighty inefficient if there were packets that the protocol stack did not use at all. These would go into read processing of the protocol stack and waste CPU time even though they could have been easily identified on arrival.

== Driver event logging ==

A driver may want to report an important event for the user to see. Adding a log message to a file or opening a window to display a message in may not be the optimum approach as the user may be unaware of the context into which the message belongs. It may be advisable for the driver to use the message reporting and logging facilities used by the client software that uses its services, such as a TCP/IP stack. The <tt>S2_Log</tt> callback hook is intended to provide for such a link.

If present, the driver must use this callback hook rather than whatever logging methods it implements itself. Note that unlike the other SANA-II callbacks, this is a regular hook, as to be invoked using <tt>utility.library</tt>/<tt>CallHookPkt()</tt>. The hook function is invoked using the following parameters:

<syntaxhighlight lang="C" line>
log_hook_function(hook, reserved, message)

void log_hook_function(struct hook * hook,APTR reserved,
struct S2LogMessage * message);
</syntaxhighlight>

The <tt>reserved</tt> parameter '''must''' be set to <tt>NULL</tt>. The <tt>S2LogMessage</tt> structure passed as the third parameter looks like this:

<syntaxhighlight lang="C" line>
struct S2LogMessage
{
LONG s2lm_Size;
ULONG s2lm_Priority;
STRPTR s2lm_Name;
STRPTR s2lm_Message;
};
</syntaxhighlight>

The individual structure members serve the following functions:

; s2lm_Size
: Size of the <tt>S2LogMessage</tt> structure, in bytes. The idea is to extend this data structure in the future, and the size stored in here tells you how long the structure is. The size '''must''' always be >= 16.

;s2lm_Priority
: The smaller this value, the more important the message to be logged or displayed. The following priority levels are defined (similar to the Unix <tt>syslog()</tt> mechanism):
:{| class="wikitable"
| S2LOG_Emergency || A panic condition.
|-
| S2LOG_Alert || A condition that should be corrected immediately.
|-
| S2LOG_Critical || Critical conditions.
|-
| S2LOG_Error || A plain error.
|-
| S2LOG_Warning || A warning message.
|-
| S2LOG_Notice || Conditions that are not error conditions, but should possibly be handled specially.
|-
| S2LOG_Information || An informational message.
|-
| S2LOG_Debug || Messages that contain information normally of use only when debugging.
|}

; s2lm_Name</tt>
: Pointer to a <tt>NUL</tt>-terminated string which identifies the source of this message. This can be <tt>NULL</tt> in which case the name is treated as being unknown.

; s2lm_Message
: Pointer to a <tt>NUL</tt>-terminated string which contains the log message. The text should not contain any formatting characters such as line feeds or carriage returns. The <tt>s2lm_Message</tt> member '''must never''' be <tt>NULL</tt>.

All error messages issued by the device driver should use the current system locale wherever this is possible. The purpose of an error message is, after all, to assist the user in recovering from the error. Which may be difficult if the user does not even know the language in which the message is written.

The log message string is valid until the log hook function returns. If the driver needs to retain the message any longer, it must make a copy of it.

Since the client software into which the log hook calls may have to allocate memory to hold and display the log message, the log hook '''must not''' be called from interrupt code. The log hook shall not <tt>Wait()</tt> and it shall assume only a <tt>Task</tt> calling context of unknown priority. <tt>dos.library</tt> functions may not be called. Also, stack space is provided only to call <tt>exec.library</tt> and <tt>utility.library</tt> functions. The callback shall not place excessive data on the stack. Stack space should be considered limited and the callback should be designed to be fast and short.

This hook is installed at <tt>OpenDevice()</tt> time, which means that the hook is used for the unit that was opened, and not just for the I/O request it was opened with. The hook must remain installed until the I/O request that installed it is eventually used to close the device. When this happens, the device should fall back to use no log hook at all. No nesting is permitted or required.

= Packet Type =

Network frames always have a type field associated with them. These type fields vary in length, position and meaning by frame type (frame types generally correspond one-to-one with hardware types, but see "Ethernet Packet Types" below). The meanings of the type numbers are always carefully defined and every type number is registered with some official body. Do not use a type number which is not registered for any standard hardware you use or in a manner inconsistent with that registration.

The type field allows the SANA-II device driver to fulfill CMD_READs based on the type of packet the driver user wants. Multiple protocols can therefore run over the same wire using the same driver without stepping on each other's toes.

Packet types are specified as a long word. Unfortunately, the type field means different things on different wires. Driver users must allow their software to be configured with a SANA-II device name, unit number and the type number(s) used by the protocol stack with each device. This way, if new hardware becomes available, a hardware manufacturer can supply a listing of type assignments to configure pre-existing software.

== Ethernet Packet Types ==

Ethernet has a special problem with packet types. Two types of ethernet frames can be sent over the same wire: ethernet and 802.3. These frames differ in that the Type field of an ethernet frame is the Length field of an 802.3 frame. This creates a problem in that demultiplexing incoming packets can be cumbersome and inefficient, as well as requiring driver users to be aware of the frame type used.

All 802.3 frames have numbers less than 1500 in the Type field. The only frames with numbers less than 1500 in the type field are 802.3 frames. SANA-II ethernet drivers abnormally return packets contained in ethernet frames when the requested Type falls within the 802.3 range-if the Type requested is within the 802.3 range, the driver returns the next packet contained within an 802.3 frame, regardless of the type specified for the packet within the 802.3 frame. This requires that there be no more than one driver user requesting 802.3 packets and that it do its own interpretation of the frames.

== ARCNET Frames ==

ARCNET also has a special problem with framing. ARCNET frames consist of a hardware header and a software header. The software header is in the data area of the hardware packet, and includes at least the protocol ID.

There are two types of software header. Old-style ARCNET software headers consist entirely of a one or two byte protocol ID. New ARCNET software headers (defined in RFC 1201 and in the paper "ARCNET Packet Header Definition Standard", Novell, Inc., 1989) include more information. They allow more efficient use of ARCNET through data link layer fragmentation and reassembly (ARCNET has a small Maximum Transmission Unit) and allow sending any size packet up to the MTU (rather than requiring that packets of size 253, 254 and 255 be padded to at least 256 bytes).

SANA-II device drivers for ARCNET should implement the old ARCNET packet headers. Driver users which wish to interoperate with platforms using the new software headers must add the new fields to the data to be sent and must process it for incoming data. A SANA-II driver which implemented the data link layer fragmentation internally (and advertised a large MTU) could be more efficient than requiring the driver user to do it. This would make driver writing more difficult and reduce interoperability, but if there is ever a demand for that extra performance, a new hardware type may be assigned by Amiga for SANA-II ARCNET device drivers which implement the new framing.

= Addressing =

In the SANA-II standard, network hardware addresses are stored in an array of ''n'' bytes. No meaning is ascribed by the standard to the contents of the array.

In case there exists a network which does not have an address field consisting of a number of bits not divisible by eight, add pad bits at the end of the bit stream. For example, if an address is ten bits long it will be stored like this:

<pre>
98765432 10PPPPPP
BYTE 0 BYTE 1
</pre>

Where the numerals are bit numbers and "P" is a pad (ignored) bit.

Driver users which do not implement the bit shifting necessary to use a network with such addressing (if one exists) should at least check the number of significant bits in the address field (returned from the device's S2_DEVICEQUERY function) to make sure that it is evenly divisible by eight.

Driver users will map hardware addresses to protocol addresses in a protocol and hardware dependent manner, as described by the relevant standards (i.e., RFC 826 for TCP/IP over Ethernet, RFC 1201 or RFC 1051 for TCP/IP over ARCNET). Some protocols will always use the same mapping on all hardware, but other protocols will have particular address mapping schemes for some particular hardware and a reasonable default for other (unknown) hardware.

Some SANA-II devices will have "hardware addresses" which aren't really hardware addresses. As an example, consider ''PPP'' (Point-to-Point Protocol). PPP is a standard for transmitting IP packets over a serial line. It uses IP addresses negotiated during the establishment of a connection. In a SANA-II driver implementation of PPP, the driver would negotiate the address at S2_CONFIGINTERFACE. Thus, the address in SrcAddr returned by the device on an S2_CONFIGINTERFACE (or in a subsequent S2_GETSTATIONADDRESS) will be a protocol address, not a true hardware address.

'''Note:''' Some hardware always uses a ROM hardware address. Other hardware which has a ROM address or is configurable with DIP switches may be overridden by software. Some hardware always dynamically allocates a new hardware address at initialization. See "Configuration" for details on how this is handled by driver writers and by driver users.

= Hardware Type =

The HardwareType returned by the device's S2_DEVICEQUERY function is necessary for those protocols whose standards require different behavior on different hardware. It is also useful for determining appropriate packet type numbers to use with the device. The HardwareType values already issued for standard network hardware are the same as those in RFC 1060 (assigned numbers). Hardware developers implementing networks without a SANA-II hardware number must contact the AmigaOS development team to have a new hardware type number assigned. Driver users should all have reasonable defaults which can be used for hardware with which they are not familiar.

= Errors =

The SANA-II extended IORequest structure (struct IOSana2Req) includes both the ios2_Error and ios2_WireError fields. Driver users must always check IOSana2Reqs on return for an error in ios2_Error. ios2_Error will be zero if no error occurred, otherwise it will contain a value from <exec/errors.h> or <devices/sana2.h>. If there was an error, there may be more specific information in ios2_WireError. Drivers are required to fill in the WireError if there is an applicable error code.

Error codes are #define'd in the "defined errors" sections of the file <devices/sana2.h>: 

{| class="wikitable"
! IOSana2Req S2io_Error field
! Description
|-
| S2ERR_NO_RESOURCES
| Insufficient resources available.
|-
| S2ERR_BAD_ARGUMENT
| Noticeably bad argument.
|-
| S2ERR_BAD_STATE
| Command inappropriate for current state.
|-
| S2ERR_BAD_ADDRESS
| Noticeably bad address.
|-
| S2ERR_MTU_EXCEEDED
| Write data too large.
|-
| S2ERR_NOT_SUPPORTED
| Command is not supported by this driver. This is similar to IOERR_NOCMD as defined in <exec/errors.h> but S2ERR_NOT_SUPPORTED indicates that the requested command is a valid SANA-II command and that the driver does not support it because the hardware is incapable of supporting it (e.g., S2_MULTICAST). Note that IOERR_NOCMD is still valid for reasons other than a lack of hardware support (i.e., commands which are no-ops in a SANA-II driver).
|-
| S2ERR_SOFTWARE
| Software error of some kind.
|-
| S2ERR_OUTOFSERVICE
| When a hardware device is taken off-line, any pending requests are returned with this error.
|}

See also the standard errors in <exec/errors.h>.

{| class="wikitable"
! IOSana2Req S2io_WireError field
! Description
! Value
|-
| S2WERR_NOT_CONFIGURED
| Command requires unit to be configured.
|-
| S2WERR_UNIT_ONLINE
| Command requires that the unit be off-line.
|-
| S2WERR_UNIT_OFFLINE
| Command requires that the unit be on-line.
|-
| S2WERR_ALREADY_TRACKED
| Protocol is already being tracked.
|-
| S2WERR_NOT_TRACKED
| Protocol is not being tracked.
|-
| S2WERR_BUFF_ERROR
| Buffer management function returned an error.
|-
| S2WERR_SRC_ADDRESS
| Problem with the source address field.
|-
| S2WERR_DST_ADDRESS
| Problem with destination address field.
|-
| S2WERR_BAD_BROADCAST
| Problem with an attempt to broadcast.
|-
| S2WERR_BAD_MULTICAST
| Problem with an attempt to multicast.
|-
| S2WERR_MULTICAST_FULL
| Multicast address list full.
|-
| S2WERR_BAD_EVENT
| Event specified is unknown.
|-
| S2WERR_BAD_STATDATA
| The ios2_StatData pointer or the data it points to failed a sanity check.
|-
| S2WERR_IS_CONFIGURED
| Attempt to reconfigure the unit.
|-
| S2WERR_NULL_POINTER
| A NULL pointer was detected in one of the arguments. S2ERR_BAD_ARGUMENT should always be the S2ERR.
|-
| S2WERR_UNIT_DISCONNECTED
| This error code is a counterpart to <tt>S2WERR_UNIT_OFFLINE</tt>. It indicates that the associated command could not be executed because the link layer is not connected.
| 19
|-
| S2WERR_UNIT_CONNECTED
| This error code is a counterpart to <tt>S2WERR_UNIT_ONLINE</tt>. It indicates that the associated command could not be executed because the link layer is already connected.
| 20
|-
| S2WERR_INVALID_OPTION
| This error code indicates that an option, such as passed by the <tt>S2_CONNECT</tt> command, is not acceptable. The option's value may be out of range or may not match the syntax specifications. To indicate which option that may be, a different mechanism '''must''' be used; a simple indication that something was wrong is '''not sufficient'''.
| 21
|-
| S2WERR_MISSING_OPTION
| This error code indicates that a mandatory option, such as passed by the <tt>S2_CONNECT</tt> command, is not present. To indicate which option that may be, a different mechanism '''must''' be used; a simple indication that something was wrong is '''not sufficient'''.
| 22
|-
| S2WERR_AUTHENTICATION_FAILED
| Some drivers run protocols that require them to authenticate to a server. That process may fail. This wire error code is to indicate this fact.
| 23
|}

= Standard Commands =

See the "SANA-II network device driver Autodocs" for full details on each of the SANA-II device commands. Extended commands are explained in the sections below.

Many of the Exec device standard commands are no-ops in SANA-II devices, but this may not always be the case. For example, CMD_RESET might someday be used for dynamically reconfiguring hardware. This should present no compatibility problems for properly written drivers.

== Broadcast and Multicast ==

Some hardware supports broadcast and/or multicast. A broadcast is a packet sent to all other machines. A multicast is a packet sent to a set of machines. Drivers for hardware which does not allow broadcast or multicast will return ios2_Error S2ERR_NOT_SUPPORTED as appropriate.

To send a broadcast, use S2_BROADCAST instead of CMD_WRITE. Broadcasts are received just like any other packets (using a CMD_READ for the appropriate packet type).

To send a multicast, use S2_MULTICAST instead of CMD_WRITE. The device keeps a list of addresses that want to receive multicasts. You add a receiver's address to this list by using S2_ADDMULTICASTADDRESS. The receiver then posts a CMD_READ for the type of packet to be received. Some SANA-II devices which support multicast may have a limit on the number of addresses that can simultaneously wait for packets. Always check for an S2WERR_MULTICAST_FULL error return when adding a multicast address.

Note that when the device adds a multicast address, it is usually added for all users of the device, not just the driver user which called S2_ADDMULTICASTADDRESS. In other words, received multicast packets will fill a read request of the appropriate type regardless of whether the requesting driver user is the same one which added the multicast address.

In general, driver users should not care how received packets were sent (normally or broadcast/multicast), only that it was received. If a driver user really must know, however, it can check for SANA2IOB_BCAST and/or SANA2IOB_MCAST in the ios2_Flags field.

Drivers should keep a count for the number of opens on a multicast address so that they don't actually remove it until it has been S2_DELMULTICASTADDRESS'd as many times as it has been S2_ADDMULTICASTADDRESS'd.

== Stats ==

There are many statistics which may be very important to someone trying to debug, tune or optimize a protocol stack, as well as to the end user who may need to tune parameters or investigate a problem. Some of these statistics can only be kept by the SANA-II driver, thus there are several required and optional statistics and commands for this purpose.

S2_TRACKTYPE tells the device driver to gather statistics for a particular packet type. S2_UNTRACKTYPE tells it to stop (keeping statistics by type causes the driver to use additional resources). S2_GETTYPESTATS returns any statistics accumulated by the driver for a type being tracked (stats are lost when a type is S2_UNTRACKTYPE'd). Drivers are required to implement the functionality of type tracking. The stats are returned in a struct Sana2PacketTypeStats:

<syntaxhighlight lang="C" line>
struct Sana2PacketTypeStats
{
ULONG PacketsSent;
ULONG PacketsReceived;
ULONG BytesSent;
ULONG BytesReceived;
ULONG PacketsDropped;
};
</syntaxhighlight>

; PacketsSent
: Number of packets of a particular type sent.
; PacketsReceived
: Number of packets of a particular type that satisfied a read command.
; BytesSent
: Number of bytes of data sent in packets of a particular type.
; BytesReceived
: Number of bytes of data of a particular packet type that satisfied a read command.
; PacketsDropped
: Number of packets of a particular type that were received while there were no pending reads of that packet type.

returns global statistics kept by the driver. Drivers are required to keep all applicable statistics. Since all are applicable to most hardware, most drivers will maintain all statistics. The stats are returned in a struct Sana2DeviceStats:

<syntaxhighlight lang="C" line>
struct Sana2DeviceStats
{
ULONG PacketsReceived;
ULONG PacketsSent;
ULONG BadData;
ULONG Overruns;
ULONG UnknownTypesReceived;
ULONG Reconfigurations;
struct timeval LastStart;
};
</syntaxhighlight>

; PacketsReceived
: Number of packets that this unit has received.
; PacketsSent
: Number of packets that this unit has sent.
; BadData
: Number of bad packets received (i.e., hardware CRC failed).
; Overruns
: Number of packets dropped due to insufficient resources available in the network interface.
; UnknownTypeReceived
: Number of packets received that had no pending read command with the appropriate packet type.
; Reconfigurations
: Number of network reconfigurations since this unit was last configured.
; LastStart
: The time when this unit last went on-line.

returns any special statistics kept by a particular driver. Each new wire type will have a set of documented, required statistics for that wire type and a standard set of optional statistics for that wire type (optional because they might not be available from all hardware). The data returned by S2_GETSPECIALSTATS will require wire-specific interpretation. See <devices/sana2specialstats.h> on page devicessana2specialstatspage for currently defined special statistics. The statistics are returned in the following structures:

<syntaxhighlight lang="C" line>
struct Sana2SpecialStatRecord
{
ULONG Type;
ULONG Count;
char * String;
};
</syntaxhighlight>

; Type
: Statistic identifier.
; Count
: Statistic itself.
; String
: An identifying, null-terminated string for the statistic. Should be plain ASCII with no formatting characters.

<syntaxhighlight lang="C" line>
struct Sana2SpecialStatHeader
{
ULONG RecordCountMax;
ULONG RecordCountSupplied;
struct Sana2SpecialStatRecord[RecordCountMax];
};
</syntaxhighlight>

; RecordCountMax
: There is space for this many records into which statistics may be placed.
; RecordCountSupplied
: Number of statistic records supplied.

is not, strictly speaking, a statistical function. It is a request to read any packet of a type for which there is no outstanding CMD_READ. S2_READORPHAN might be used in the same manner as many statistics, though, such as to determine what packet types are causing overruns, etc.

== Configuration ==

The device driver needs to configure the hardware before using it. The driver user must know some network hardware parameters (hardware address and MTU, for example) when using it. These commands address those needs.

When a driver user is initialized, it should try to S2_CONFIGINTERFACE even though an interface can only be configured once and someone else may have done it. Before you call S2_CONFIGINTERFACE, first call S2_GETSTATIONADDRESS to determine the factory address (if any). Also provide for user-override of the factory address (that address may be optional and the user may need to override it). When S2_CONFIGINTERFACE returns, check the ios2_SrcAddr for the actual address the hardware has been configured with. This is because some hardware (or serial line standards such as PPP) always dynamically allocates an address at initialization.

Driver users will want to use S2_DEVICEQUERY to determine the MTU and other characteristics of the network. The structure returned from S2_DEVICEQUERY is defined as:

<syntaxhighlight lang="C" line>
struct Sana2DeviceQuery
{
/*
** Standard information
*/
ULONG SizeAvailable; /* bytes available */
ULONG SizeSupplied; /* bytes supplied */
LONG DevQueryFormat; /* this is type 0 */
LONG DeviceLevel; /* this document is level 0 */

/*
** Common information
*/
UWORD AddrFieldSize; /* address size in bits */
ULONG MTU; /* maximum packet data size */
LONG BPS; /* line rate (bits/sec) */
LONG HardwareType; /* what the wire is */
ULONG RawMTU; /* maximum raw packet data size */

/*
** Format specific information
*/
};
</syntaxhighlight>

; SizeAvailable
: Size, in bytes, of the space available in which to place device information. This includes both size fields.
; SizeSupplied
: Size, in bytes, of the data supplied.
; DevQueryFormat
: The format defined here is format 0.
; DeviceLevel
: This spec defines level 0.
; AddrFieldSize
: The number of bits in an interface address.
; MTU
: Maximum Transmission Unit, the size, in bytes, of the maximum packet size, not including header and trailer information.
; BPS
: Best guess at the raw line rate for this network in bits per second.

; HardwareType
: Specifies the type of network hardware the driver controls.

; RawMTU
: The <tt>RawMTU</tt> member is new as of SANA-II Revision 4. Devices which do not know and support this structure member may fill in the <tt>Sana2DeviceQuery</tt> structure only up to and including the <tt>HardwareType</tt> member.

: In this context 'raw' means the number of bytes that are available for reading and writing when using the <tt>SANA2IOB_RAW</tt> flag with a <tt>CMD_READ</tt>/<tt>CMD_WRITE</tt> request on a device that supports these access methods. Currently, software developers can only make assumptions on how many bytes might comprise the 'raw' MTU by checking the <tt>Sana2DeviceQuery.HardwareType</tt> member and hoping that the driver supports raw <tt>CMD_READ</tt>/<tt>CMD_WRITE</tt> access.

: Devices which know and support the <tt>RawMTU</tt> member must fill it with a well-defined value. For Amiga Ethernet drivers, that value would be 1514, which is the standard MTU value of 1500 bytes plus the size of the Ethernet frame header, as per RFC894 (six bytes for the destination address, six bytes for the source address and two bytes for the frame type; the eight byte preamble and the terminating four byte CRC value are typically not under the control of the driver). Drivers which do not support raw read or write access must set the <tt>RawMTU</tt> member to zero.

: If the <tt>RawMTU</tt> member is not provided, all bets are off and the application software must fall back to making estimates based upon the hardware type and the raw frame types it wishes to read and write. Ultimatively, the driver itself must decide whether it can accept raw read and write commands (or has to reject them with <tt>S2ERR_NOT_SUPPORTED</tt>) and whether the raw packet size is still covered by the underlying hardware MTU (or must be rejected with <tt>S2ERR_MTU_EXCEEDED</tt>).

: A word of warning: a little testing with various Ethernet hardware drivers has revealed that the A2065 driver <tt>a2065.device</tt> does not handle the <tt>S2_DEVICEQUERY</tt> command properly if the <tt>Sana2DeviceQuery</tt> structure provided is larger than 30 bytes. In other words, the command will fail if the proposed <tt>RawMTU</tt> member is present in the query data structure to be filled in.

== On-line ==

In order to run hardware tests on an otherwise live system, the S2_OFFLINE command allows the SANA-II device driver to be "turned off" until the tests are complete and an S2_ONLINE is sent to the driver. S2_ONLINE causes the interface to re-configure and re-initialize. Any packets destined for the hardware while the device is off-line will be lost. All pending and new requests to the driver shall be returned with S2ERR_OUTOFSERVICE when a device is off-line.

All driver users must understand that any IO request may return with S2ERR_OUTOFSERVICE because the driver is off-line (any other program may call S2_OFFLINE to make it so). In such an event, the driver will usually want to wait until the unit comes back on-line (for the program which called S2_OFFLINE to call S2_ONLINE). It may do this by calling S2_ONEVENT to wait for S2EVENT_ONLINE. S2_ONEVENT allows the driver user to wait on various events.

A driver must track events, but may not distinguish between some types of events. Drivers return S2_ONEVENT with S2ERR_NOT_SUPPORTED and S2WERR_BAD_EVENT for unsupported events. One error may cause more than one event (see below). Errors which seem to have been caused by a malformed or unusual request should not generally trigger an event. 

{| class="wikitable"
! Event type
! Description
|-
| S2EVENT_ERROR
| Return when any error occurs.
|-
| S2EVENT_TX
| Return on any transmit error (always an error).
|-
| S2EVENT_RX
| Return on any receive error (always an error).
|-
| S2EVENT_ONLINE
| Return when unit goes on-line or return immediately if unit is already on-line (not an error).
|-
| S2EVENT_OFFLINE
| Return when unit goes off-line or return immediately if unit is already off-line (not an error.)
|-
| S2EVENT_BUFF
| Return on any buffer management function error (always an error).
|-
| S2EVENT_HARDWARE
| Return when any hardware error occurs (always an error, may be a S2EVENT_TX or S2EVENT_RX, too).
|-
| S2EVENT_SOFTWARE
| Return when any software error occurs (always an error, may be a S2EVENT_TX or S2EVENT_RX, too).
|-
| S2EVENT_CONFIGCHANGED
| Return when client-visible configuration information changes (not an error).
|-
| S2EVENT_CONNECT
| Return when the driver has successfully established a link layer connection (not an error).
|-
| S2EVENT_DISCONNECT
| Return when the driver has closed the link layer connection previously established by the S2_CONNECT command (not an error).
|}

=== S2EVENT_CONFIGCHANGED ===

For drivers such as those which implement the <tt>S2_GETPEERADDRESS</tt> and <tt>S2_GETDNSADDRESS</tt> commands it is vital that such changes can take place and be noticed by the client software. For this purpose a new event type is introduced, to be used with the SANA-II <tt>S2_ONEVENT</tt> command, using the following definition:

<tt>#define S2EVENT_CONFIGCHANGED (1L<<8)</tt>

This event should be triggered whenever client-visible configuration information changes, as can be queried via the <tt>S2_DEVICEQUERY</tt>, <tt>S2_GETSTATIONADDRESS</tt>, <tt>S2_GETSPECIALSTATS</tt>, <tt>S2_GETGLOBALSTATS</tt>, <tt>S2_GETPEERADDRESS</tt> and <tt>S2_GETDNSADDRESS</tt> commands. Here is a short list of what could change:

# S2_DEVICEQUERY: <tt>AddrFieldSize</tt>, <tt>MTU</tt>, <tt>BPS</tt>
# S2_GETSTATIONADDRESS: <tt>ios2_SrcAddr</tt>
# S2_GETGLOBALSTATS: <tt>Reconfigurations</tt>, <tt>LastStart</tt>
# S2_GETPEERADDRESS: <tt>ios2_SrcAddr</tt>, <tt>ios2_DstAddr</tt>
# S2_GETDNSADDRESS: <tt>ios2_SrcAddr</tt>, <tt>ios2_DstAddr</tt>

The purpose of this event '''is not''' to post a notification whenever another byte or event counter has changed so that a monitoring program may update its display. The purpose '''is''' to convey to the client software that an important device configuration option has changed and that it is supposed to react and adapt to it. For example, a TCP/IP stack may, upon learning that a device's IP address has changed, rebuild its routing table.

Since the <tt>S2EVENT_CONFIGCHANGED</tt> event may arrive at any time and does not indicate what exactly has changed, application software should query the information it expects to change during its life time, and keep a copy of it around for later reference. When the <tt>S2EVENT_CONFIGCHANGED</tt> event arrives, it can compare the contents of the copy against the current state of affairs and act according to the differences it finds.

=== S2EVENT_CONNECT ===

This event is a counterpart to <tt>S2EVENT_ONLINE</tt>, and is associated with the <tt>S2_CONNECT</tt> command. It has the following semantics:

<tt>#define S2EVENT_CONNECT (1L<<9) /* Driver has opened session */</tt>

The event is to be sent when the driver has successfully established a link layer connection.

=== S2EVENT_DISCONNECT ===

This event is a counterpart to <tt>S2EVENT_OFFLINE</tt>, and is associated with the <tt>S2_DISCONNECT</tt> command. It has the following semantics:

<tt>#define S2EVENT_DISCONNECT (1L<<10) /* Driver has closed session */</tt>

The event is to be sent when the driver has closed the link layer connection previously established by the <tt>S2_CONNECT</tt> command.

== S2_ONLINE and S2_OFFLINE ==

The <tt>S2_CONNECT</tt> and <tt>S2_DISCONNECT</tt> commands are somewhat related to the <tt>S2_ONLINE</tt> and <tt>S2_OFFLINE</tt> commands. How this relation works out shall be explained below. Note that the following text assumes that both the <tt>S2_CONNECT</tt>/<tt>S2_DISCONNECT</tt> and <tt>S2_ONLINE</tt>/<tt>S2_OFFLINE</tt> command pairs are implemented.

<tt>S2_CONNECT</tt> implies <tt>S2_ONLINE</tt> and, if successful, may report <tt>S2EVENT_ONLINE</tt> and <tt>S2EVENT_CONNECT</tt> events. If the unit is currently disconnected, but still online, only the <tt>S2EVENT_CONNECT</tt> event shall be sent. Invoking the <tt>S2_CONNECT</tt> command on a driver which is already connected must be rejected with <tt>ios2_Req.io_Error=S2ERR_BAD_STATE</tt> and <tt>ios2_WireError=S2WERR_UNIT_CONNECTED</tt>.

<tt>S2_DISCONNECT</tt> implies <tt>S2_OFFLINE</tt> and, if successful, may report <tt>S2EVENT_OFFLINE</tt> and <tt>S2EVENT_DISCONNECT</tt> events. If the unit is currently connected and offline, then only the <tt>S2EVENT_DISCONNECT</tt> event shall be sent. Invoking the <tt>S2_DISCONNECT</tt> command on a driver which is already disconnected must be rejected with <tt>ios2_Req.io_Error=S2ERR_BAD_STATE</tt> and <tt>ios2_WireError=S2WERR_UNIT_DISCONNECTED</tt>.

<tt>S2_OFFLINE</tt> may be used after the <tt>S2_CONNECT</tt> has successfully connected the unit. In this case the driver will release control over the link layer and report the <tt>S2EVENT_OFFLINE</tt> event. The connection established using the <tt>S2_CONNECT</tt> will, however, persist.

<tt>S2_ONLINE</tt> may be used after <tt>S2_CONNECT</tt> has successfully connected the unit and the <tt>S2_OFFLINE</tt> was used. In this case the driver will again try to obtain control over the link layer and report the <tt>S2EVENT_ONLINE</tt> event if successful.

If the <tt>S2_CONNECT</tt> command was never successfully executed, then the commands <tt>S2_ONLINE</tt> and <tt>S2_OFFLINE</tt> must be rejected with <tt>ios2_Req.io_Error=S2ERR_BAD_STATE</tt> and <tt>ios2_WireError=S2WERR_UNIT_DISCONNECTED</tt>.

== Wireless (IEEE 802.11) ==

Several new commands have been added to the SANA-II API to facilitate use of IEEE 802.11 wireless network devices in client and ad-hoc modes. The new commands are split into two overlapping sets. One set needs to be implemented by drivers for Soft-MAC wireless devices, while the other is implemented for Hard-MAC devices.

{| class="wikitable"
! Soft-MAC commands
|-
| S2_SETOPTIONS
|-
| S2_SETKEY
|-
| S2_WRITEMGMT
|-
| S2_READMGMT
|}

{| class="wikitable"
! Hard-MAC commands
|-
| S2_SETOPTIONS
|-
| S2_SETKEY
|-
| S2_GETNETWORKS
|-
| S2_GETNETWORKINFO
|-
| S2_GETSIGNALQUALITY
|}

=== sana2wireless.h ===

<syntaxhighlight lang="C" line>
#ifndef DEVICES_SANA2WIRELESS_H
#define DEVICES_SANA2WIRELESS_H

#include <exec/types.h>
#include <utility/tagitem.h>

/* Constants */
/* ========= */

/* Tags to get and set information */

#define S2INFO_SSID (TAG_USER + 0)
#define S2INFO_BSSID (TAG_USER + 1)
#define S2INFO_AuthTypes (TAG_USER + 2)
#define S2INFO_AssocID (TAG_USER + 3)
#define S2INFO_Encryption (TAG_USER + 4)
#define S2INFO_PortType (TAG_USER + 5)
#define S2INFO_BeaconInterval (TAG_USER + 6)
#define S2INFO_Channel (TAG_USER + 7)
#define S2INFO_Signal (TAG_USER + 8)
#define S2INFO_Noise (TAG_USER + 9)
#define S2INFO_Capabilities (TAG_USER + 10)
#define S2INFO_InfoElements (TAG_USER + 11)
#define S2INFO_WPAInfo (TAG_USER + 12)
#define S2INFO_Band (TAG_USER + 13)
#define S2INFO_DefaultKeyNo (TAG_USER + 14)

/* Wireless Commands */

#define S2_GETSIGNALQUALITY 0xc010
#define S2_GETNETWORKS 0xc011
#define S2_SETOPTIONS 0xc012
#define S2_SETKEY 0xc013
#define S2_GETNETWORKINFO 0xc014
#define S2_READMGMT 0xc015
#define S2_WRITEMGMT 0xc016
#define S2_GETRADIOBANDS 0xc017

/* Encryption types */

#define S2ENC_NONE 0
#define S2ENC_WEP 1
#define S2ENC_TKIP 2
#define S2ENC_CCMP 3

/* Radio modes */

#define S2BAND_A 0
#define S2BAND_B 1
#define S2BAND_G 2
#define S2BAND_N 3

/* Network topologies */

#define S2PORT_MANAGED 7
#define S2PORT_ADHOC 8

/* Structures */
/* ========== */

/* Structure for returning signal quality */

struct Sana2SignalQuality
{
LONG SignalLevel; /* signal level in dBm */
LONG NoiseLevel; /* noise level in dBm */
};

#endif
</syntaxhighlight>

= Driver requirements =

This section is an attempt to clarify parts of the specification and to lay down a few rules that every SANA-II driver must follow.

* A driver that does not use a broadcast medium, such as Ethernet, must not implement the <tt>S2_BROADCAST</tt> command. Likewise, if no multicast mechanism is supported, the <tt>S2_MULTICAST</tt> must not be implemented either.

* SANA-II standard commands which the driver does not implement must be rejected with the <tt>IOERR_NOCMD</tt> error code. Commands that are implemented, but which cannot perform the requested services, must be rejected with the <tt>S2ERR_NOT_SUPPORTED</tt> error code. The difference between the two cases is in when the decision is made whether a command can be handled or not. Which commands should return <tt>IOERR_NOCMD</tt> is decided upon at the time the driver is designed and implemented. At this stage the implementer knows for sure which capabilities the driver will have and which it will not have. Commands which the driver will never be able to execute will be made to return the <tt>IOERR_NOCMD</tt> error code. If the decision whether a command can be executed is made only at run time, by evaluating the conditions under which a command can be executed, then the error code <tt>S2ERR_NOT_SUPPORTED</tt> should be returned in case of failure.

* It must be possible to open the driver with an ordinary <tt>struct IOStdReq</tt>. This is necessary for the NewStyleDevices query command to work. In the command dispatcher, the driver must verify that all SANA-II commands are invoked with a proper size <tt>struct IOSana2Req</tt> I/O request. If the I/O request is shorter (as can be verified by looking at the embedded Message's <tt>mn_Length</tt> member), the command must be rejected with <tt>ios2_Req.io_Error=IOERR_BADLENGTH</tt>.

* A driver must implement the NewStyleDevices <tt>NSCMD_DEVICEQUERY</tt> command, in conformance with the NSD specification 1.6 or newer. The motivation for this is to have a mechanism available for probing the capabilities of the driver, and the supported command set can provide for vital clues. In this context, the absence of the <tt>S2_BROADCAST</tt> command would suggest that the driver cannot send or receive broadcast messages.

* A driver that does not allow its station address to be set with the <tt>S2_CONFIGINTERFACE</tt> command may silently ignore the command (returning it without setting an error condition) and even pretend that it can be configured more than once.

* In response to the <tt>S2_DEVICEQUERY</tt>, <tt>S2_GETSPECIALSTATS</tt> and <tt>S2_GETGLOBALSTATS</tt> commands a driver may return information that is not entirely correct if it has to go online before it can provide for the correct data. For example, the maximum transmission unit for PPP is a number in the range of [1..1500] which is negotiated during the protocol configuration process. It is unlikely that numbers greater than 1500 will be used, yet it is still not impossible. Since the actual number will be known only after the driver has configured the protocol, the MTU value returned before the session was opened can differ from the MTU value valid after it has been opened. A driver should therefore attempt to return 'safe' defaults in place of information that is unavailable at the time it is queried. The 'safe' values shall be set up to allow the driver to work even if the protocol stack is not aware of later changes to those values. Beware of zero-length buffer sizes or time intervals that may cause client software to perform zero-length memory allocations or divisions by zero.

* SANA-II assigns packet type numbers according to the underlying transport media. For example, Ethernet uses packet type 2048 for IP frames. No such packet type definition exists for PPP yet, which is why this standard proposes to assign packet type 31 for IP packets transmitted via PPP. To simplify client software configuration, drivers may treat packet type 2048 as equivalent to the packet number associated with IP frames. This association is permitted only if it does not introduce ambiguity. For example, this association would not be permitted if the driver would receive and transmit IP packets in two different frame types or if the driver already associates packet type 2048 with non-IP packets.

= Driver Installation =

The standard system location for SANA-II network device driver is in a directory called "Networks" which exists in the "DEVS:" directory.

Example:

<blockquote>
DEVS:Networks/eth3com.device
</blockquote>

This is the official location for the drivers. It may be necessary for your install program/script to create this directory if it doesn't exist in a user's system.

= Unresolved Issues =

* Unfortunately, it isn't possible to completely isolate network protocols from the hardware they run on. Hardware types and addressing both remain somewhat hardware-dependent in spite of our efforts. See the "Packet Type" section for an explanation of how packet types are handled and why protocols cannot be isolated from them. See the "Addressing" section for an explanation of how addressing is handled any why protocols cannot be isolated from it.

* Additionally, there are at least two cases where a hardware type has multiple framing methods in use (ethernet/802.3 and arcnet/(Novell) "ARCNET Packet Header Definition Standard"). In both cases, software which must interoperate with other platforms on this hardware may need to be aware of the distinctions and may have to do extra processing in order to use the appropriate frame type. See the sections on "Ethernet Packet Types" and on "ARCNET frames" for more details.

* Protocols like PPP can provide both for IPv4 and IPv6 addresses that should be used by the local client, the peer or any of the domain name servers. While the two addressing families are interoperable, there is a problem in how the driver should report them. Can you assume 128 bit addresses and encapsulate 32 bit addresses in them? If so, how do you make sure that the address format is unambiguous?

* Currently, only the device's hardware type provides a clue as to what packet type responds to which protocol transported via the link. For Ethernet, IP packets are encapsulated in type 2048 frames, PPP encapsulates IP packets in type 31 frames, Arcnet can use type 240 or 212. Matching a protocol with a frame type is not an easy process which could be handled more elegantly.

* How to extend the <tt>Sana2DeviceQuery</tt> structure in the future? The current layout separates standard, common and format specific information, but there is no hint as to where which each section starts and where the next begins. Now that there is a proposal to add a new field to the common section, how would you add fields to the format specific section?

= SANA-II network device driver Autodocs =

== AbortIO ==

<pre>
NAME
AbortIO -- Remove an existing device request.

SYNOPSIS
error = AbortIO(Sana2Req)
D0 A1

LONG AbortIO(struct IOSana2Req *);

FUNCTION
This is an exec.library call.

This function aborts an ioRequest. If the request is active, it may or
may not be aborted. If the request is queued it is removed. The
request will be returned in the same way as if it had normally
completed. You must WaitIO() after AbortIO() for the request to
return.

INPUTS
Sana2Req - Sana2Req to be aborted.

RESULTS
error - Zero if the request was aborted, non-zero otherwise.
io_Error in Sana2Req will be set to IOERR_ABORTED
if it was aborted.

SEE ALSO
exec.library/AbortIO(), exec.library/WaitIO()
</pre>

== CloseDevice ==

<pre>
NAME
CloseDevice -- Close the device.

SYNOPSIS
CloseDevice(Sana2Req)
A1

void CloseDevice(struct IOSana2Req *);

FUNCTION
This function is called by exec.library CloseDevice().

This function performs whatever cleanup is required at device closes.

Note that all IORequests MUST be complete before closing. If any are
pending, your program must AbortIO() then WaitIO() each outstanding
IORequest to complete them.

INPUTS
Sana2Req - Pointer to IOSana2Req initialized by OpenDevice().

SEE ALSO
exec.library/CloseDevice(), exec.library/OpenDevice()
</pre>

== CMD_CLEAR ==

<pre>
NAME
CMD_CLEAR -- Clear internal network interface read buffers.

FUNCTION
There are no device internal buffers, so CMD_CLEAR does not apply to
this class of device.

IO REQUEST
ios2_Command - CMD_CLEAR.

RESULTS
ios2_Error - IOERR_NOCMD.
</pre>

== CMD_FLUSH ==

<pre>
NAME
CMD_FLUSH -- Clear all queued I/O requests for the SANA-II device.

FUNCTION
This command aborts all I/O requests in both the read and write
request queues of the device. All pending I/O requests are
returned with an error message (IOERR_ABORTED). CMD_FLUSH does not
affect active requests.

IO REQUEST
ios2_Command - CMD_FLUSH.

RESULTS
ios2_Error - Zero if successful; non-zero otherwise.
</pre>

== CMD_INVALID ==

<pre>
NAME
CMD_INVALID -- Return with error IOERR_NOCMD.

FUNCTION
This command causes device driver to reply with an error IOERR_NOCMD
as defined in <exec/errors.h> indicating the command is not supported.

IO REQUEST
ios2_Command - CMD_INVALID.

RESULTS
ios2_Error - IOERR_NOCMD.

BUGS
Not known to be useful.
</pre>

== CMD_READ ==

<pre>
NAME
CMD_READ -- Get a packet from the network.

FUNCTION
Get the next packet available of the requested packet type. The data
copied (via a call to the requestor-provided CopyToBuffer function)
into ios2_Data is normally the Data Link Layer packet data only. If
bit SANA2IOB_RAW is set in ios2_Flags, then the entire physical frame
will be returned.

Unlike most Exec devices, SANA-II device drivers do not have internal
buffers. If you wish to read data from a SANA-II device you should
have multiple CMD_READ requests pending at any given time. The
functions provided by you the requestor will be used for any incoming
packets of the type you've requested. If no read requests are
outstanding for a type which comes in and no read_orphan requests are
outstanding, the packet will be lost.

IO REQUEST
ios2_Command - CMD_READ
ios2_Flags - Supported flags are:
SANA2IOB_RAW
SANA2IOB_QUICK
ios2_PacketType - Packet type desired.
ios2_Data - Abstract data structure to hold packet data.

RESULTS
ios2_Error - Zero if successful; non-zero otherwise.
ios2_WireError - More specific error number.
ios2_Flags - The following flags may be returned:
SANA2IOB_RAW
SANA2IOB_BCAST
SANA2IOB_MCAST
ios2_SrcAddr - Source interface address of packet.
ios2_DstAddr - Destination interface address of packet.
ios2_DataLength - Length of packet data.
ios2_Data - Abstract data structure which packet data is
contained in.

NOTES
The driver may not directly examine or modify anything pointed to by
ios2_Data. It *must* use the requester-provided functions to access
this data.

SEE ALSO
S2_READORPHAN, CMD_WRITE, any_protocol/CopyToBuffer
</pre>

== CMD_RESET ==

<pre>
NAME
CMD_RESET -- Reset the network interface to initialized state.

FUNCTION
Currently, SANA-II devices can only be configured once (with
CMD_CONFIGINTERFACE) and cannot be re-configured, hence,
CMD_RESET does not apply to this class of device.

IO REQUEST
ios2_Command - CMD_RESET.

RESULTS
ios2_Error - IOERR_NOCMD.
</pre>

== CMD_START ==

<pre>
NAME
CMD_START -- Restart device operation.

FUNCTION
There is no way for the driver to keep queuing requests without
servicing them, so CMD_STOP does not apply to this class of device.
S2_OFFLINE and S2_ONLINE do perform a similar function to CMD_STOP
and CMD_START

IO REQUEST
ios2_Command - CMD_START.

RESULTS
ios2_Error - IOERR_NOCMD.

SEE ALSO
S2_ONLINE, S2_OFFLINE
</pre>

== CMD_STOP ==

<pre>
NAME
CMD_STOP -- Pause device operation.

FUNCTION
There is no way for the driver to keep queuing requests without
servicing them, so CMD_STOP does not apply to this class of device.
S2_OFFLINE and S2_ONLINE do perform a similar function to CMD_STOP
and CMD_START

IO REQUEST
ios2_Command - CMD_STOP.

RESULTS
ios2_Error - IOERR_NOCMD.

NOTES

SEE ALSO
S2_ONLINE, S2_OFFLINE
</pre>

== CMD_UPDATE ==

<pre>
NAME
CMD_UPDATE -- Force packets out to device.

FUNCTION
Since there are no device internal buffers, CMD_UPDATE does not
apply to this class of device.

IO REQUEST
ios2_Command - CMD_UPDATE.

RESULTS
ios2_Error - IOERR_NOCMD.
</pre>

== CMD_WRITE ==

<pre>
NAME
CMD_WRITE -- Send packet to the network.

FUNCTION
This command causes the packet to be sent to the specified network
interface. Normally, appropriate packet header and trailer information
will be added to the packet data when it is sent. If bit SANA2IOB_RAW
is set in io_Flags, then the ios2_Data is assumed to contain an entire
physical frame and will be sent (copied to the wire via
CopyFromBuffer() unmodified.

Note that the device should not check to see if the destination
address is on the local hardware. Network protocols should realize
that the packet has a local destination long before it gets to a
SANA-II driver.

IO REQUEST
ios2_Command - CMD_WRITE.
ios2_Flags - Supported flags are:
SANA2IOB_RAW
SANA2IOB_QUICK
ios2_PacketType - Packet type to send.
ios2_DstAddr - Destination interface address for this packet.
ios2_DataLength - Length of the Data to be sent.
ios2_Data - Abstract data structure which packet data is
contained in.

RESULTS
ios2_Error - Zero if successful; non-zero otherwise.
ios2_WireError - More specific error number.

NOTES
The driver may not directly examine or modify anything pointed to by
ios2_Data. It *must* use the requester-provided functions to access
this data.

SEE ALSO
CMD_READ, S2_BROADCAST, S2_MULTICAST, any_protocol/CopyFromBuffer
</pre>

== OpenDevice ==

<pre>
NAME
Open -- Request an opening of the network device.

SYNOPSIS
error = OpenDevice(unit, IOSana2Req, flags)
D0 D0 A1 D1

BYTE OpenDevice(ULONG, struct IOSana2Req *, ULONG);

FUNCTION
This function is called by exec.library OpenDevice().

This function performs whatever initialization is required per
device open and initializes the Sana2Req for use by the
device.

INPUTS
unit - Device unit to open.
Sana2Req - Pointer to IOSana2Req structure to be initialized by
the sana2.device.
flags - Supported flags are:
SANA2OPB_MINE
SANA2OPB_PROM
ios2_BufferManagement - A pointer to a tag list containing
pointers to buffer management functions.

RESULTS
error - same as io_Error
io_Error - Zero if successful; non-zero otherwise.
io_Device - A pointer to whatever device will handle the calls
for this unit. This pointer may be different
depending on what unit is requested.
ios2_BufferManagement - A pointer to device internal information
used to call buffer management functions.

NOTES
A SANA-II device must reject all open requests with a request
structure that is too short, e.g. an IOStdReq. A simple check of the
mn_Length field in the Message part of the request is needed to make
sure that a device does not dereference invalid data due to a wrong
device configuration.

A SANA-II device may open if no buffer management tags are provided to
make the configuration process and obtaining statistics easier. Buffer
management tags with a NULL value must be treated as not specified.
The device shall fail requests gracefully depending on the missing
tags in this case. Any malfunction is not acceptable.

SEE ALSO
exec.library/OpenDevice(), exec.library/CloseDevice()
</pre>

== S2_ADDMULTICASTADDRESS ==

<pre>
NAME
S2_ADDMULTICASTADDRESS -- Enable an interface multicast address.

FUNCTION
This command causes the device driver to enable multicast packet
reception for the requested address.

IO REQUEST
ios2_Command - S2_ADDMULTICASTADDRESS.
ios2_SrcAddr - Multicast address to enable.

RESULTS
ios2_Error - Zero if successful; non-zero otherwise.
ios2_WireError - More specific error number.

NOTES
Multicast addresses are added globally -- anyone using the device
may receive packets as a result of any multicast address which has
been added for the device.

Since multicast addresses are not "bound" to a particular packet type,
each enabled multicast address has an "enabled" count associated with
it so that if two protocols add the same multicast address and later
one removes it, it is still enabled until the second removes it.

SEE ALSO
S2_MULTICAST, S2_DELMULTICASTADDRESS
</pre>

== S2_BROADCAST ==

<pre>
NAME
S2_BROADCAST -- Broadcast a packet on network.

FUNCTION
This command works the same as CMD_WRITE except that it also performs
whatever special processing of the packet is required to do a
broadcast send. The actual broadcast mechanism is neccessarily
network/interface/device specific.

IO REQUEST
ios2_Command - S2_BROADCAST.
ios2_Flags - Supported flags are:
SANA2IOB_RAW
SANA2IOB_QUICK
ios2_PacketType - Packet type to send.
ios2_DataLength - Length of the Data to be sent.
ios2_Data - Abstract data structure which packet data is
contained in.

RESULTS
ios2_DstAddr - The contents of this field are to be
considered trash upon return of the IOReq.
ios2_Error - Zero if successful; non-zero otherwise.
This command can fail for many reasons and
is not supported by all networks and/or
network interfaces.
ios2_WireError - More specific error number.

NOTES
The DstAddr field may be trashed by the driver because this function
may be implemented by filling DstAddr with a broadcast address and
internally calling CMD_WRITE.

SEE ALSO
CMD_WRITE, S2_MULTICAST
</pre>

== S2_CONFIGINTERFACE ==

<pre>
NAME
S2_CONFIGINTERFACE -- Configure the network interface.

FUNCTION
This command causes the device driver to initialize the interface
hardware and to set the network interface address to the address in
ios2_SrcAddr. This command can only be executed once and, if
successful, will leave the driver and network interface fully
operational and the network interface in ios2_SrcAddr.

To set the interface address to the factory address, the network
management software must use GetStationAddress first and then call
ConfigInterface with the result. If there is no factory address then
the network software must pick an address to use.

Until this command is executed the device will not listen for any
packets on the hardware.

IO REQUEST
ios2_Command - S2_CONFIGINTERFACE.
ios2_Flags - Supported flags are:
SANA2IOB_QUICK
ios2_SrcAddr - Address for this interface.

RESULTS
ios2_Error - Zero if successful; non-zero otherwise.
ios2_WireError - More specific error number.
ios2_SrcAddr - Address of this interface as configured.

NOTES
Some networks have the interfaces choose a currently unused interface
address each time the interface is initialized. The caller must check
ios2_SrcAddr for the actual interface address after configuring the
interface.

SEE ALSO
S2_GETSTATIONADDRESS
</pre>

== S2_CONNECT ==

The driver model specified by the SANA-II standard really only covers networking hardware well. Software-only drivers, such as for dial-up networking, are, well, somehow mentioned in the standard, but they don't receive much attention. In particular, this means that a networking driver is assumed to be practically always attached to its link layer and no provisions exist to specify what kind of link layer that might be and how it might be accessed. This small oversight can probably be explained by the fact that at the time the SANA-II standard was adopted, dial-up networking had not yet gained the prominence it has today.

To bridge this gap, I propose a new command which will make a driver connect to its link layer and go online, which uses the following data structure:

<syntaxhighlight lang="C" line>
struct Sana2Connection
{
ULONG s2c_Size;
struct MinList s2c_Options;
struct Hook s2c_ErrorHook;
struct Hook s2c_ConnectHook;
struct Hook s2c_DisconnectHook;
STRPTR s2c_Login;
STRPTR s2c_Password;
};
</syntaxhighlight>

The individual structure members have the following purposes:

<tt>s2c_Size</tt>

The size of the entire data structure is stored here. This value '''must''' be >= 84. Smaller values '''must''' be rejected with <tt>ios2_Req.io_Error</tt>=<tt>IOERR_BADLENGTH</tt>. The purpose of <tt>s2c_Size</tt> is to allow for future expansion during which the structure may grow in size.

<tt>s2c_Options</tt>

This list contains options, to be used during the connection process. Each node has the following format:

<syntaxhighlight lang="C" line>
struct Sana2ConnectionOption
{
struct MinNode s2co_MinNode;
STRPTR s2co_Name;
STRPTR s2co_Value;
};
</syntaxhighlight>

The <tt>s2co_Name</tt> and <tt>s2co_Value</tt> entries point to <tt>NUL</tt>-terminated strings, which contain the name and the value of a parameter. ''Note that for numeric values, the respective number will be encoded in a text string.'' A number of parameters are reserved, which are [[#s2c_options|listed later]] in this text.

<tt>s2c_ErrorHook</tt>

This hook is called whenever an error message is to be reported during the connection/disconnection process. The hook function is invoked using the following parameters:

<pre>error_hook_func(hook,reserved,message);

VOID error_hook_func(struct Hook *hook,APTR reserved,
STRPTR message);</pre>
The <tt>reserved</tt> parameter '''must''' be <tt>NULL</tt>. The <tt>message</tt> parameter points to a <tt>NUL</tt>-terminated string. It '''must not''' be <tt>NULL</tt>.

Because the hook function may have to allocate memory, it '''must not''' be called from interrupt code.

<tt>s2c_ConnectHook</tt>

This hook is called when the link level device has been set up, but further initializations are necessary, such as telling a modem to dial out. The hook function is invoked with the following parameters:

<pre>
success = connect_hook_func(hook,reserved,s2cm);

BOOL connect_hook_func(struct Hook *hook,APTR reserved,
struct Sana2ConnectionMessage *s2cm);
</pre>

The <tt>reserved</tt> parameter '''must''' be <tt>NULL</tt>. The <tt>s2cm</tt> parameter points to a data structure, as follows:

<syntaxhighlight lang="C" line>
struct Sana2ConnectionMessage
{
ULONG s2cm_Size;
struct Sana2Connection * s2cm_Connection;
struct IORequest * s2cm_Request[2];
LONG s2cm_RequestType;
};
</syntaxhighlight>

In this structure, the members have the following purposes:

<tt>s2cm_Size</tt>

The size of this data structure; it '''must''' be at least 20 bytes in size. The purpose of <tt>s2cm_Size</tt> is to allow for future expansion, which may cause the size of this structure to grow.

<tt>s2cm_Connection</tt>

This points back to the <tt>Sana2Connection</tt> structure which the hook that was invoked with the <tt>Sana2ConnectionMessage</tt> is embedded in.

<tt>s2cm_Request</tt>

Here you will find two I/O requests which can be used for reading and writing data to the link layer. These pointers '''must not''' be <tt>NULL</tt> and they '''must''' refer to different I/O requests, it is not permitted to pass the same request twice.

The dialer can use these requests for communicating with the modem, but it is also permitted to clone these requests by creating new I/O requests of the same size, copying the original contents and filling in different reply ports.

There is a danger in that the hook code may not receive the right kind of I/O request, which is why the <tt>s2cm_RequestType</tt> field identifies the kind of device the requests were created for.

When the hook function returns, it '''must''' make sure that none of the I/O requests are still pending, i.e. asynchronous I/O '''must''' have been stopped.

<tt>s2cm_RequestType</tt>

This identifies the type of device the I/O requests passed in <tt>s2cm_Request</tt> were created for. Possible values for this entry come from the New Style Device specification, e.g. <tt>NSDEVTYPE_SERIAL</tt> for a <tt>serial.device</tt>-like device or <tt>NSDEVTYPE_SANA2</tt> for a networking driver.

The hook function '''must''' return <tt>TRUE</tt> if the connection could be established, and <tt>FALSE</tt> otherwise. Note that it is ''not'' sufficient to just return <tt>FALSE</tt> in case of failure. Your code '''must''' have called the <tt>s2c_ErrorHook</tt> with an explanation why things went wrong first.

<tt>s2c_DisconnectHook</tt>

This hook is called by <tt>S2_CONNECT</tt> when the connection could not be established (the <tt>s2c_ConnectHook</tt> returned <tt>FALSE</tt>), or by <tt>S2_DISCONNECT</tt>, shortly before the link level device is to be closed. The hook function is invoked with the following parameters:

<pre>
disconnect_hook_func(hook,reserved,s2cm);

VOID disconnect_hook_func(struct Hook *hook,APTR reserved,
struct Sana2ConnectionMessage *s2cm);
</pre>

The <tt>reserved</tt> parameter '''must''' be <tt>NULL</tt>. The <tt>s2cm</tt> parameter points to a data structure, as was described for the <tt>s2c_ConnectHook</tt>.

<tt>s2c_Login</tt>

<tt>s2c_Password</tt>

The purpose of these entries is to transport the authentication information the protocol may require. These entries are either <tt>NULL</tt> or contain pointers to <tt>NUL</tt>-terminated strings. If <tt>s2c_Login</tt> is <tt>NULL</tt>, then both login and password '''must''' be assumed to be empty. If <tt>s2c_Login</tt> is not <tt>NULL</tt> and <tt>s2c_Password</tt> is <tt>NULL</tt>, then the password '''must''' be assumed to be empty.

The list of options in <tt>s2c_Options</tt> supplies the necessary information on how the driver is to connect to the link layer. Each node contains an option, which bears a name and contains a value. This pair is what I call a ''parameter''. A number of parameter names are reserved, as will be listed below:

<tt>ppp</tt>.async.device

Name of device driver to use for asynchronous PPP.

Example: <tt>serial.device</tt>

<tt>ppp</tt>.async.unit

Device unit number to use for asynchronous PPP.

Example: <tt>0</tt>

<tt>ppp</tt>.async.speed

Transmission speed to use for asynchronous PPP in bits per second.

Example: <tt>115200</tt>

<tt>ppp.async.buffersize</tt>

Receive buffer size for asynchronous PPP.

Example: <tt>50000</tt>

<tt>ppp.async.checkcarrier</tt>

Whether the carrier signal of the link layer should be tested or not. This can be either 0 (do not test) or 1 (test the carrier signal).

Example: <tt>1</tt>

<tt>ppp.async.rtscts</tt>

Whether or not hardware handshaking should be used by the link layer. This can be either <tt>0</tt> (off) or <tt>1</tt> (on).

Example: <tt>1</tt>

<tt>ppp.async.shared</tt>

Whether or not the link layer device should be opened in shared mode. This can be either <tt>0</tt> (off) or <tt>1</tt> (on).

Example: <tt>0</tt>

<tt>ppp.async.nullmodem</tt>

Whether or not the link layer is a direct connection, such as a nullmodem. This can be either <tt>0</tt> (off) or <tt>1</tt> (on).

Example: <tt>0</tt>

<tt>ppp.async.eof</tt>

Whether or not the underlying serial device driver's 'EOF mode' should be enabled. This can be either <tt>0</tt> (off) or <tt>1</tt> (on).

Example: <tt>0</tt>

<tt>ppp.async.readrequests</tt>

Number of read requests to be used for asynchronous PPP.

Example: <tt>16</tt>

<tt>ppp.async.writerequests</tt>

Number of write requests to be used for asynchronous PPP.

Example: <tt>16</tt>

<tt>ppp.async.accm</tt>

Asynchronous control character map, expressed as a hexadecimal value.

Example: <tt>$000A0000</tt>

<tt>ppp.async.pfc</tt>

Whether or not protocol field compression should be used. This can be either <tt>0</tt> (off) or <tt>1</tt> (on).

Example: <tt>1</tt>

<tt>ppp.async.aacfc</tt>

Whether or not address and control field compression should be used. This can be either <tt>0</tt> (off) or <tt>1</tt> (on).

Example: <tt>1</tt>

<tt>ppp.async.vjhc</tt>

Whether or not Van Jacobson header compression should be used. This can be either <tt>0</tt> (off) or <tt>1</tt> (on).

Example: <tt>1</tt>

<tt>ppp.async.ignorefcs</tt>

Whether or not frame check sequences should be ignored upon reception. This can be either <tt>0</tt> (off) or <tt>1</tt> (on).

Example: <tt>0</tt>

<tt>ppp.async.initialize</tt>

The modem initialization command, with embedded control sequences, if possible.

Example: <tt>AT\r</tt>

<tt>ppp.async.dial</tt>

The modem dial command, with embedded control sequences, if possible.

Example: <tt>ATD12345\r</tt>

<tt>ppp.async.dialtimeout</tt>

The dial timeout, i.e. the number of seconds to wait after the dial command has been sent for the modem to establish a connection.

Example: <tt>60</tt>

<tt>ppp.async.hangup</tt>

The modem hangup command, with embedded control sequences, if possible.

Example: <tt>ATH0\r</tt>

<tt>ppp.idletimeout</tt>

Number of seconds the local host may remain idle, i.e. send no data to the peer, before a watchdog timeout elapses and proceeds to verify that the line is still operational.

Example: <tt>30</tt>

<tt>ppp.localaddress</tt>

The IP address to assign to the local host, as part of the PPP negotiation process. This must be given in dotted decimal notation (RFC1700).

Example: <tt>1.2.3.4</tt>

<tt>ppp.remoteaddress</tt>

The IP address to assume for the peer, as part of the PPP negotiation process. This must be given in dotted decimal notation (RFC1700).

Example: <tt>1.2.3.4</tt>

<tt>ppp.dns1address</tt>

The IP address to be used by the primary domain name server, as part of the PPP negotiation process. This must be given in dotted decimal notation (RFC1700).

Example: <tt>1.2.3.4</tt>

<tt>ppp.dns2address</tt>

The IP address to be used by the secondary domain name server, as part of the PPP negotiation process. This must be given in dotted decimal notation (RFC1700).

Example: <tt>1.2.3.4</tt>

<tt>ppp.maxfail</tt>

The maximum number of negative configuration acknowledgements to be sent before the PPP negotiation process switches to reject those options.

Example: <tt>5</tt>

<tt>ppp.maxterm</tt>

The maximum number of termination requests to be sent before the respective PPP network or link protocol gives up.

Example: <tt>2</tt>

<tt>ppp.maxconfig</tt>

The maximum number of configuration requests to be sent before the respective PPP network or link protocol gives up.

Example: <tt>10</tt>

<tt>ppp.timeout</tt>

The number of seconds that have to pass before the respective PPP network or link protocol will retry to do whatever didn't work during the last attempt.

Example: <tt>3</tt>

<tt>ppp.mtu</tt>

The maximum transmission unit to use.

Example: <tt>1500</tt>

<tt>ppp.peeridletimeout</tt>

Number of seconds the peer may remain idle, i.e. send no data to the local host, before a watchdog timeout elapses and proceeds to verify that the line is still operational.

Example: <tt>30</tt>

<tt>ppp.rejectpap</tt>

Whether or not the Password Authentication Protocol should be accepted, if offered by the peer. This can be either <tt>0</tt> (accept) or <tt>1</tt> (reject).

Example: <tt>0</tt>

<tt>ppp.sendid</tt>

A flag which controls whether the local host should send LCP identification packets or not. This can be either <tt>0</tt> (off) or <tt>1</tt> (on).

Example: <tt>0</tt>

<tt>ppp.pap.timeout</tt>

The Password Authentication Protocol requires that the server answers to the client's request to log in. The server may be unable to respond immediately, which means that the client will have to repeat its request. A short delay should separate each request sent, such as three seconds.

Example: <tt>3</tt>

<tt>ppp.pap.retry</tt>

If the client does not manage to authenticate with the server immediately, it may resend the authentication request several times. But the attempts have to stop eventually, such as after having resent the message ten times.

Example: <tt>10</tt>

<tt>ppp.dummyremoteaddress</tt>

Whether or not the PPP driver should make up an IP address if the peer refuses to state its own IP address.

Example: <tt>1</tt>

<tt>logfile</tt>

The name of a log file to create. If the file already exists, then new data should be appended to it.

Example: <tt>t:logfile</tt>

<tt>logoptions</tt>

A list of options which control what exactly should be logged.

<tt>ppp.ethernet.device</tt>

Name of device driver to use for PPPoE (PPP over Ethernet).

Example: <tt>a2065.device</tt>

<tt>ppp.ethernet.unit</tt>

Device unit number to use for PPPoE.

Example: <tt>0</tt>

<tt>ppp.ethernet.raw</tt>

Whether or not raw link layer frames should be constructed for transmission or not. This can be either <tt>0</tt> (off) or <tt>1</tt> (on).

Example: <tt>1</tt>

<tt>ppp.ethernet.bypass</tt>

Whether or not the IP packet transmission and reception should bypass several copying steps. This can be either <tt>0</tt> (off) or <tt>1</tt> (on).

Example: <tt>1</tt>

<tt>ppp.ethernet.readpackets</tt>

The number of read requests to queue for the link layer.

Example: <tt>16</tt>

<tt>ppp.ethernet.writepackets</tt>

The number of write requests to queue for the link layer.

Example: <tt>16</tt>

<tt>ppp.ethernet.service</tt>

The name of the PPPoE service to request.

Example: <tt>?</tt>

<tt>ppp.ethernet.ac</tt>

The name of the PPPoE access concentrator to request.

Example: <tt>?</tt>

<tt>ppp.ethernet.connecttimeout</tt>

The number of seconds to wait for the PPPoE server to allow a session to be opened.

Example: <tt>3</tt>

While this list of parameters may suggest that the command described above can be used solely with the PPP protocol, do not let that put you off. This list is merely the starting point, but it is not set in stone that it cannot be extended.

The names of the parameters are not case sensitive. As the names suggest, the name space itself is hierarchic in construction, i.e. everything related to the PPP protocol bears a name starting with the letters 'ppp' with the dot '.' separating the individual items. By this rule, ppp.async refers to options that concern asynchronous PPP and ppp.ethernet to options that concern PPP over Ethernet wire.

To add your own parameter, register it with the maintainer of the SANA-II standard or prefix its name with the letters 'x-'. For example, to use your own kind of 'ppp.ethernet.connecttimeout' parameter, change the name of the last component like this: ppp.ethernet.x-connecttimeout. No officially-registered parameter will ever begin with the prefix 'x-'.

The command should work as follows:

# The client must set up the <tt>Sana2Connection</tt> data structure, initialize the <tt>s2c_Size</tt>, <tt>s2c_Options</tt>, <tt>s2c_ErrorHook</tt>, <tt>s2c_ConnectHook</tt>, <tt>s2c_DisconnectHook</tt>, <tt>s2c_Login</tt> and <tt>s2c_Password</tt> fields.
# The connection options must be filled in, which means that nodes containing the respective information must be stored in the <tt>s2c_Options</tt> list. The client must make sure that the syntax of the parameters conforms to the specifications described above.
# A pointer to the <tt>Sana2Connection</tt> data structure is placed in the <tt>ios2_Data</tt> member of an <tt>IOSana2Req</tt>, the command is set to <tt>S2_CONNECT</tt> and the request is sent via <tt>DoIO()</tt> or <tt>SendIO()</tt>.
# The driver receives the request and begins to examine the contents of the <tt>s2c_Options</tt> list, as provided in the data structure pointed to by the <tt>ios2_Data</tt> member of the request. Unknown options are ignored, options whose values do not conform to the syntax specification are rejected; this is done by calling the <tt>s2c_ErrorHook</tt> with an error message referring to the option in question and by returning the <tt>IOSana2Req</tt> with an error code of <tt>S2ERR_BAD_ARGUMENT</tt> and wire error code of <tt>S2WERR_INVALID_OPTION</tt>.
# If the options are all in good order, the driver proceeds to verify that all mandatory options are provided. If this is not the case, the <tt>s2c_ErrorHook</tt> is called with an error message referring to the option in question and the <tt>IOSana2Req</tt> is returned with an error code of <tt>S2ERR_BAD_ARGUMENT</tt> and wire error code of <tt>S2WERR_MISSING_OPTION</tt>.
# The driver proceeds to do its local initialization, which involves opening the link layer device, etc. If this initialization fails, the <tt>s2c_ErrorHook</tt> is called with an error message referring to the problem and the <tt>IOSana2Req</tt> is returned with an appropriate error code.
# When the initialization has finished, the driver may invoke the <tt>s2c_ConnectHook</tt> callback. Some drivers may require this, such as asynchronous PPP, some may not, such as PPPoE. The purpose of the hook function is to give the client a chance to perform modem initializations and connect to the peer. If the <tt>s2c_ConnectHook</tt> cannot perform its duties, it has to invoke the <tt>s2c_ErrorHook</tt> with an error message and eventually return <tt>FALSE</tt>. If <tt>FALSE</tt> is returned, the driver must invoke the <tt>s2c_DisconnectHook</tt>, reverse any initializations it had made and eventually returned the <tt>IOSana2Req</tt> with an appropriate error code. If the <tt>s2c_ConnectHook</tt> returned <tt>TRUE</tt>, then the driver must proceed with the actions that require that the link layer is operational. A protocol negotiation may follow, which, if successful, will make the driver return the <tt>IOSana2Req</tt> with an error code of zero, indicating success. If successful, the SANA-II events <tt>S2EVENT_CONNECT</tt> and <tt>S2EVENT_ONLINE</tt> must be sent.
# The command will eventually return, but the client '''must not''' release the memory allocated for the <tt>Sana2Connection</tt> structure and the option nodes in the <tt>s2c_Options</tt> list. This is because the driver may have to invoke the <tt>s2c_DisconnectHook</tt> hook due to the connection shutting down on its own accord.

The connect and disconnect hook functions '''must not''' be called from interrupt code. For each hook only a <tt>Task</tt> calling context of unknown priority must be assumed. Also, stack space is provided only to call <tt>exec.library</tt> and <tt>utility.library</tt> functions. The callback shall not place excessive data on the stack. Stack space should be considered limited.

I propose a command with the following semantics:

<pre>
NAME
S2_CONNECT -- Establish a link layer connection and go
online.

FUNCTION
This command is for use by networking devices which require
a special link layer device to transmit their data, such as
an asynchronous serial line and need to know about the
configuration parameters necessary to open the connection.

IO REQUEST
ios2_Command - S2_CONNECT
ios2_Data - Pointer to Sana2Connection structure
ios2_BufferManagement - Magic cookie as returned when opening the
driver with a struct IOSana2Req

RESULTS
ios2_Req.io_Error - Zero if successful; non-zero otherwise
ios2_WireError - More specific error number

NOTES
If successful, this command implies S2_ONLINE, i.e. the
link layer is allocated and used by the driver.

The contents of the Sana2Connection structure must be valid
until the connection is eventually shut down. The driver will
need to cache it, so it must not be deallocated or otherwise
modified.

Note that S2_ONLINE does not necessarily imply S2_CONNECT, if
the S2_CONNECT command is listed as supported by the driver via
NSCMD_DEVICEQUERY. If S2_CONNECT is not listed as supported,
S2_ONLINE obviously implies connect functionality.

S2_CONNECT/S2_DISCONNECT do not nest.

SEE ALSO
S2_DISCONNECT</pre>
I propose that the following command number should be assigned:

<tt>#define S2_CONNECT 0xC005</tt>

== S2_DELMULTICASTADDRESS ==

<pre>
NAME
S2_DELMULTICASTADDRESS -- Disable an interface multicast address.

FUNCTION
This command causes device driver to disable multicast packet
reception for the requested address.

It is an error to disable a multicast address that is not enabled.

IO REQUEST
ios2_Command - S2_DELMULTICASTADDRESS
ios2_SrcAddr - Multicast address to disable.

RESULTS
ios2_Error - Zero if successful; non-zero otherwise.
ios2_WireError - More specific error number.

NOTES
Multicast addresses are added globally -- anyone using the device
may receive packets as a result of any multicast address which has
been added for the device.

Since multicast addresses are not "bound" to a particular packet type,
each enabled multicast address has an "enabled" count associated with
it so that if two protocols add the same multicast address and later
one removes it, it is still enabled until the second removes it.

SEE ALSO
S2_ADDMULTICASTADDRESS
</pre>

== S2_DEVICEQUERY ==

<pre>
NAME
S2_DEVICEQUERY -- Return parameters for this network interface.

FUNCTION
This command causes the device driver to report information about the
device. Up to SizeAvailable bytes of the information is copied
into a buffer pointed to by ios2_StatData. The format of the data is
as follows:

struct Sana2DeviceQuery
{
/*
** Standard information
*/
ULONG SizeAvailble; /* bytes available */
ULONG SizeSupplied; /* bytes supplied */
ULONG DevQueryFormat; /* this is type 0 */
ULONG DeviceLevel; /* this document is level 0 */

/*
** Common information
*/
UWORD AddrFieldSize; /* address size in bits */
ULONG MTU; /* maximum packet data size */
ULONG bps; /* line rate (bits/sec) */
ULONG HardwareType; /* what the wire is */
ULONG RawMTU; /* maximum raw packet data size */

/*
** Format specific information
*/
};

The SizeAvailable specifies the number of bytes that the caller
is prepared to accomodate, including the standard information fields.

SizeSupplied is the number of bytes actually supplied,
including the standard information fields, which will not exceed
SizeAvailable.

IO REQUEST
ios2_Command - S2_DEVICEQUERY.
ios2_StatData - Pointer to Sana2DeviceQuery structure to fill in.

RESULTS
ios2_Error - Zero if successful; non-zero otherwise.
ios2_WireError - More specific error number.
</pre>

== S2_DISCONNECT ==

This command complements <tt>S2_CONNECT</tt> in that it tears down a connection. It uses the same <tt>Sana2Connection</tt> structure and hooks, but most of these members are ignored.

The command should work as follows:

# The client must set up the <tt>Sana2Connection</tt> data structure, initialize the <tt>s2c_Size</tt>, <tt>s2c_Options</tt>, <tt>s2c_ErrorHook</tt>, <tt>s2c_ConnectHook</tt>, <tt>s2c_DisconnectHook</tt>, <tt>s2c_Login</tt> and <tt>s2c_Password</tt> fields. The <tt>s2c_Options</tt>, <tt>s2c_ConnectHook</tt>, <tt>s2c_Login</tt> and <tt>s2c_Password</tt> fields will be ignored, but the client should play things safe.
# A pointer to the <tt>Sana2Connection</tt> data structure is placed in the <tt>ios2_Data</tt> member of an <tt>IOSana2Req</tt>, the command is set to <tt>S2_DISCONNECT</tt> and the request is sent via <tt>DoIO()</tt> or <tt>SendIO()</tt>.
# The driver receives the request and proceeds to reverse the steps that previously allowed it to establish a connection. This includes telling the peer to shut down the link, but it does not include cleaning up the link layer device access, i.e. no I/O requests used for accessing a modem may be shut down yet.
# The <tt>s2c_DisconnectHook</tt> may be invoked with the proper parameters. Some drivers, such as for asynchronous PPP, will need the hook to tell the modem to hang up the line. Some drivers, such as for PPPoE, may not need this hook and thus ignore it.
# The initialization is reversed completely, all resources allocated when the connection was previously opened are released. The <tt>IOSana2Req</tt> is returned with an error code of zero, indicating success. The SANA-II event <tt>S2EVENT_DISCONNECT</tt> must be sent, and, if necessary, <tt>S2EVENT_OFFLINE</tt>.

The connect and disconnect hook functions must not be called from interrupt code. For each hook only a <tt>Task</tt> calling context of unknown priority must be assumed. Also, stack space is provided only to call <tt>exec.library</tt> and <tt>utility.library</tt> functions. The callback shall not place excessive data on the stack. Stack space should be considered limited.

I propose a command with the following semantics:

<pre>
NAME
S2_DISCONNECT -- Go offline and close a link layer connection
previously established with S2_CONNECT.

FUNCTION
This command complements the S2_CONNECT command in that it
reverses the steps taken to establish a link layer connection.

IO REQUEST
ios2_Command - S2_DISCONNECT
ios2_Data - Pointer to Sana2Connection structure
ios2_BufferManagement - Magic cookie as returned when opening the
driver with a struct IOSana2Req

RESULTS
ios2_Req.io_Error - Zero if successful; non-zero otherwise
ios2_WireError - More specific error number

NOTES
If successful, this command implies S2_OFFLINE, i.e. the
link layer is deallocated.

The driver must ignore the S2_DISCONNECT command and
recover gracefully if the S2_CONNECT was never sent or
returned with an error.

The contents of the Sana2Connection structure are valid only
until the device driver has processed the command and returned
the IOSana2Req. Any data the driver may need to retain beyond
that point of time must be copied.

Once the S2_DISCONNECT command has returned, it is safe to dispose
of the Sana2Connection structure provided at S2_CONNECT time.

Note that S2_OFFLINE does not necessarily imply S2_DISCONNECT, if
the S2_DISCONNECT command is listed as supported by the driver via
NSCMD_DEVICEQUERY. If S2_DISCONNECT is not listed as supported,
S2_OFFLINE obviously implies disconnect functionality.

S2_CONNECT/S2_DISCONNECT do not nest.

SEE ALSO
S2_CONNECT
</pre>

I propose that the following command number should be assigned:

<tt>#define S2_DISCONNECT 0xC006</tt>

== S2_GETDNSADDRESS ==

The PPP negotiation process may produce information on which domain name and NetBIOS name servers are available to the client. I think that it is doubtful that the availability of NetBIOS name servers will be useful for Amiga software (let alone whether NetBIOS name resolution has a future), which is why I suggest that a SANA-II command for returning only the domain name servers is introduced.

I propose a command with the following semantics:

<pre>
NAME
S2_GETDNSADDRESS -- Obtain the addresses of the primary
and secondary domain name servers.

FUNCTION
Obtain the addresses of the domain name servers available to the
client using this driver's address.

IO REQUEST
ios2_Command - S2_GETDNSADDRESS
ios2_Flags - Supported flags are:
SANA2IOB_QUICK
ios2_BufferManagement - Magic cookie as returned when opening the
driver with a struct IOSana2Req

RESULTS
ios2_Req.io_Error - Zero if successful; non-zero otherwise
ios2_WireError - More specific error number
ios2_SrcAddr - Address of primary domain name server
ios2_DstAddr - Address of secondary domain name server

NOTES
The size of the address returned by S2_GETPEERADDRESS must not be
different from the size as returned by the S2_DEVICEQUERY command. For
example, if a 32 bit IPv4 address was advertized, the driver must not
return a 128 bit IPv6 address instead.

If the driver is unable to return the primary domain name server
address (ios2_SrcAddr) or the secondary domain name server address
(ios2_DstAddr) it must fill the respective address fields with zeroes.
It is legal for a driver to respond to the S2_GETDNSADDRESS command
with two zero addresses (both ios2_SrcAddr and ios2_DstAddr filled
with zeroes).
</pre>

I propose that the following command number should be assigned:
<tt>#define S2_GETDNSADDRESS 0xC003</tt>

This command may be useful beyond the typical application (PPP) described above.

== S2_GETEXTENDEDGLOBALSTATS ==

There already exists a SANA-II command for querying global device statistics (<tt>S2_GETGLOBALSTATS</tt>) which should be common to all kinds of networking devices. Statistics that are particular to a certain device type are intended to be returned through the <tt>S2_GETSPECIALSTATS</tt> command. I feel that these mechanisms both fail to cater well enough for dial-up or session-oriented networking applications such as PPP or PPPoE. Since the data structure used by <tt>S2_GETGLOBALSTATS</tt> is of a fixed size and not intended to accomodate for new fields, I propose to introduce a new command which uses a different data structure, as follows:

<syntaxhighlight lang="C" line>
struct Sana2ExtDeviceStats
{
ULONG s2xds_Length;
ULONG s2xds_Actual;

S2QUAD s2xds_PacketsReceived;
S2QUAD s2xds_PacketsSent;
S2QUAD s2xds_BadData;
S2QUAD s2xds_Overruns;
S2QUAD s2xds_UnknownTypesReceived;
S2QUAD s2xds_Reconfigurations;
struct timeval s2xds_LastStart;

struct timeval s2xds_LastConnected;
struct timeval s2xds_LastDisconnected;
struct timeval s2xds_TimeConnected;
};
</syntaxhighlight>

Before I proceed to explain what purposes the individual members serve, a few words on the <tt>S2QUAD</tt> type, which is defined as follows:
<tt>typedef struct { ULONG s2q_High; ULONG s2q_Low; } S2QUAD;</tt>

In other words, the <tt>S2QUAD</tt> type stands for an unsigned 64 bit big endian integer, as expressed in ISO 'C' terms.

The structure members have the following purposes:

<tt>s2xds_Length</tt>

This is the size of the data structure to be filled in and should be initialized by the caller to <tt>sizeof(struct Sana2ExtDeviceStats)</tt>. Smaller values are permitted, but these '''must not''' be smaller than 8 (which covers the <tt>s2xds_Length</tt> and <tt>s2xds_Actual</tt> members). A driver which finds an <tt>s2xds_Length</tt> < 8 '''must''' treat this as an error and reject the command with <tt>ios2_Req.io_Error</tt>=<tt>IOERR_BADLENGTH</tt>.

<tt>s2xds_Actual</tt>

The size of the data structure filled with information. This member is initialized by the driver and '''must''' be <= <tt>s2xds_Length</tt>.

<tt>s2xds_PacketsReceived</tt>

Number of packets that this unit has received. This is a 64 bit integer.

<tt>s2xds_PacketsSent</tt>

Number of packets that this unit has sent. This is a 64 bit integer.

<tt>s2xds_BadData</tt>

Number of bad packets received (i.e., hardware CRC failed). This is a 64 bit integer.

<tt>s2xds_Overruns</tt>

Number of packets dropped due to insufficient resources available in the network interface. This is a 64 bit integer.

<tt>s2xds_UnknownTypesReceived</tt>

Number of packets received that had no pending read command with the appropriate packet type. This is a 64 bit integer.

<tt>s2xds_Reconfigurations</tt>

Number of network reconfigurations since this unit was last configured. This is a 64 bit integer.

<tt>s2xds_LastStart</tt>

The time when this unit last went on-line.

<tt>s2xds_LastConnected</tt>

The time when this unit last established a connection. For dial-up connections, this should be the time when the underlying serial line started to accumulate costs. <tt>s2xds_LastConnected</tt> '''must''' be set to zero if the unit never managed to make a connection.

<tt>s2xds_LastDisconnected</tt>

The time when this unit last shut down a connection. For dial-up connections, this should be the time when the underlying serial line stopped accumulating costs, e.g. when the modem's carrier signal was lost. <tt>s2xds_LastDisconnected</tt> '''must''' be set to zero if the unit never disconnected.

<tt>s2xds_TimeConnected</tt>

The time this unit has been connected. For dial-up connections this should be the time between now and when the underlying serial line started accumulating costs.

If this unit is not currently connected, then <tt>s2xds_TimeConnected</tt> '''must''' be set to zero. This means in particular that when the connection is lost, <tt>s2xds_TimeConnected</tt> '''must''' be immediately set to zero and <tt>s2xds_LastDisconnected</tt> '''must''' be filled in so that client software can query how long the unit was connected by subtracting <tt>s2xds_LastConnected</tt> from <tt>s2xds_LastDisconnected</tt>.

If this unit is currently connected, <tt>s2xds_TimeConnected</tt> '''must never''' be zero; if necessary, set <tt>s2xds_TimeConnected.tv_secs=0</tt> and <tt>s2xds_TimeConnected.tv_micros=1</tt>.

If <tt>s2xds_TimeConnected</tt> is zero, check <tt>s2xds_LastConnected</tt> and <tt>s2xds_LastDisconnected</tt>; if the latter two are not zero, you can calculate the previous connection time by subtracting <tt>s2xds_LastConnected</tt> from <tt>s2xds_LastDisconnected</tt>.

The layout and semantics used by the <tt>Sana2ExtDeviceStats</tt> data structure suggest that there is a difference between the underlying networking media (the link layer) and the state of the protocol that is running on top of it. With drivers for networking hardware such as Ethernet there was no difference between these two, but for protocols like SLIP, PPP or PPPoE there is a difference. The difference is in that a session or connection may exist for a certain time whereas the protocol running inside that session may be switched 'online' later. The primary purpose of the <tt>s2xds_LastConnected</tt>, <tt>s2xds_LastDisconnected</tt> and <tt>s2xds_TimeConnected</tt> fields is to allow for cost accounting and traffic monitoring (so that, for example, a driver may be disconnected after it has been idle for a while) to be written.

I propose a command with the following semantics:

<pre>
NAME
S2_GETEXTENDEDGLOBALSTATS -- Get interface accumulated statistics;
updated version.

FUNCTION
This command causes the device driver to retrieve various global
runtime statistics for this network interface. The format of the data
returned is as follows:

struct Sana2ExtDeviceStats
{
ULONG s2xds_Length;
ULONG s2xds_Actual;

S2QUAD s2xds_PacketsReceived;
S2QUAD s2xds_PacketsSent;
S2QUAD s2xds_BadData;
S2QUAD s2xds_Overruns;
S2QUAD s2xds_UnknownTypesReceived;
S2QUAD s2xds_Reconfigurations;
struct timeval s2xds_LastStart;

struct timeval s2xds_LastConnected;
struct timeval s2xds_LastDisconnected;
struct timeval s2xds_TimeConnected;
};

IO REQUEST
ios2_Command - S2_GETEXTENDEDGLOBALSTATS
ios2_StatData - Pointer to Sana2ExtDeviceStats structure
to fill in
ios2_BufferManagement - Magic cookie as returned when opening the
driver with a struct IOSana2Req

RESULTS
ios2_Req.io_Error - Zero if successful; non-zero otherwise
ios2_WireError - More specific error number
</pre>

I propose that the following command number should be assigned:
<tt>#define S2_GETEXTENDEDGLOBALSTATS 0xC004</tt>

== S2_GETGLOBALSTATS ==

<pre>
NAME
GetGlobalStats -- Get interface accumulated statistics.

FUNCTION
This command causes the device driver to retrieve various global
runtime statistics for this network interface. The format of the
data returned is as follows:

struct Sana2DeviceStats
{
ULONG PacketsReceived;
ULONG PacketsSent;
ULONG BadData;
ULONG Overruns;
ULONG UnknownTypesReceived;
ULONG Reconfigurations;
timeval LastStart;
};

IO REQUEST
ios2_Command - S2_GETGLOBALSTATS.
ios2_StatData - Pointer to Sana2DeviceStats structure to fill.

RESULTS
ios2_Error - Zero if successful; non-zero otherwise.
ios2_WireError - More specific error number.

SEE ALSO
S2_GETSPECIALSTATS
</pre>

== S2_GETNETWORKINFO ==

<pre>
NAME
S2_GETNETWORKINFO -- Get information on current network.

FUNCTION
This command provides information on the status of the currently
used network. If this command completes successfully, ios2_StatData
will contain a pointer to a tag list that contains information on
the network. The S2INFO_#? tags used are defined in the
devices/sana2wireless.h include file.

The returned taglist is allocated from the supplied memory pool.
To discard the results of this command, the entire memory pool
should be destroyed.

INPUTS
ios2_Data - Pointer to an Exec memory pool.

RESULTS
ios2_Data - Remains unchanged.
ios2_StatData - Pointer to a tag list.
io_Error - Zero if successful; non-zero otherwise.
ios2_WireError - More specific error code.
</pre>

== S2_GETNETWORKS ==

<pre>
NAME
S2_GETNETWORKS -- Scan for available networks.

FUNCTION
This command supplies details of available networks. If the scan
should be limited to one specific network, the S2INFO_SSID tag
should specify its name.

If this command completes successfully, ios2_StatData will contain
an array of pointers to tag lists, each of which contains
information on a single network. The device will set ios2_DataLength
to the number of elements in this array.

The returned taglists are allocated from the supplied memory pool.
To discard the results of this command, the entire memory pool
should be destroyed.

The S2INFO_#? tags used with this command are defined in the
devices/sana2wireless.h include file.

INPUTS
ios2_Data - Pointer to an Exec memory pool.
ios2_StatData - Pointer to taglist that specifies parameters to use.

RESULTS
ios2_DataLength - Number of tag lists returned.
ios2_Data - Remains unchanged.
ios2_StatData - Pointer to an array of tag lists.
io_Error - Zero if successful; non-zero otherwise.
ios2_WireError - More specific error code.
</pre>

== S2_GETPEERADDRESS ==

As part of the negotiation process, the PPP protocol can return the addresses used by the peer (the other side of the point-to-point connection PPP establishes; typically a dial-in server) and assigned to the client establishing the connection. The SANA-II standard does not provide for a mechanism to return such information. Existing drivers therefore had to resort to other means, such as by setting global environment variables containing this information.

I propose a command with the following semantics:

<pre>
NAME
S2_GETPEERADDRESS -- Obtain the addresses used by the peer
(server) and the client of a point-to-point connection.

FUNCTION
Obtain the address used by the peer of a point-to-point connection and
the address assigned to the local driver.

IO REQUEST
ios2_Command - S2_GETPEERADDRESS
ios2_Flags - Supported flags are:
SANA2IOB_QUICK
ios2_BufferManagement - Magic cookie as returned when opening the
driver with a struct IOSana2Req

RESULTS
ios2_Req.io_Error - Zero if successful; non-zero otherwise
ios2_WireError - More specific error number
ios2_SrcAddr - Address assigned to the local driver
ios2_DstAddr - Address used by the peer

NOTES
The size of the address returned by S2_GETPEERADDRESS must not be
different from the size returned by the S2_DEVICEQUERY command. For
example, if a 32 bit IPv4 address was advertized, the driver must not
return a 128 bit IPv6 address instead.

If the driver is unable to return the local driver address
(ios2_SrcAddr) or the peer's address (ios2_DstAddr) it must fill the
respective address fields with zeroes. It is legal for a driver to
respond to the S2_GETPEERADDRESS command with two zero addresses (both
ios2_SrcAddr and ios2_DstAddr filled with zeroes).
</pre>

I propose that the following command number should be assigned:
<tt>#define S2_GETPEERADDRESS 0xC002</tt>

This command may be useful beyond the typical application (PPP) described above.

== S2_GETSIGNALQUALITY ==

<pre>
NAME
S2_GETSIGNALQUALITY -- Get signal quality statistics.

FUNCTION
This command fills in the supplied Sana2SignalQuality structure with
current signal and noise levels. The unit for these figures is dBm.
Typically, they are negative values.

INPUTS
ios2_StatData - Pointer to Sana2SignalQuality structure.

RESULTS
io_Error - Zero if successful; non-zero otherwise.
ios2_WireError - More specific error code.
ios2_StatData - Pointer to filled Sana2SignalQuality structure.
</pre>

== S2_GETSPECIALSTATS ==

<pre>
NAME
S2_GETSPECIALSTATS -- Get network type specific statistics.

FUNCTION
This function returns statistics which are specific to the type of
network medium this driver controls. For example, this command could
return statistics common to all Ethernets which are not common to all
network mediums in general.

The supplied Sana2SpecialStatData structure is given below:

struct Sana2SpecialStatData
{
ULONG RecordCountMax;
ULONG RecordCountSupplied;
struct Sana2StatRecord[RecordCountMax];
};

The format of the data returned is:

struct Sana2StatRecord
{
ULONG Type; /* Amiga registered */
LONG Count; /* the stat itself */
char *String; /* null terminated */
};

The RecordCountMax field specifies the number of records that the
caller is prepared to accomodate.

RecordCountSupplied is the number of record actually supplied which
will not exceed RecordCountMax.

IO REQUEST
ios2_Command - S2_GETSPECIALSTATS.
ios2_StatData - Pointer to a Sana2SpecialStatData structure to fill.
RecordCountMax must be initialized.

RESULTS
ios2_Error - Zero if successful; non-zero otherwise.
ios2_WireError - More specific error number.

NOTES
Amiga will maintain registered statistic Types.

SEE ALSO
S2_GETGLOBALSTATS, <devices/sana2specialstats.h>
</pre>

== S2_GETSTATIONADDRESS ==

<pre>
NAME
S2_GETSTATIONADDRESS -- Get default and interface address.

FUNCTION
This command causes the device driver to copy the current interface
address into ios2_SrcAddr, and to copy the factory default station
address (if any) into ios2_DstAddr.

IO REQUEST
ios2_Command - S2_GETSTATIONADDRESS.

RESULTS
ios2_Error - Zero if successful; non-zero otherwise.
ios2_WireError - More specific error number.
ios2_SrcAddr - Current interface address.
ios2_DstAddr - Default interface address (if any).

SEE ALSO
S2_CONFIGINTERFACE
</pre>

== S2_GETTYPESTATS ==

<pre>
NAME
S2_GETTYPESTATS -- Get accumulated type specific statistics.

FUNCTION
This command causes the device driver to retrieve various packet type
specific runtime statistics for this network interface. The format of
the data returned is as follows:

struct Sana2TypeStatData
{
LONG PacketsSent;
LONG PacketsReceived;
LONG BytesSent;
LONG BytesReceived;
LONG PacketsDropped;
};

IO REQUEST
ios2_Command - S2_GETTYPESTATS.
ios2_PacketType - Packet type of interest.
ios2_StatData - Pointer to TypeStatData structure to fill in.

RESULTS
ios2_Error - Zero if successful; non-zero otherwise.
ios2_WireError - More specific error number.

NOTES
Statistics for a particular packet type are only available while that
packet type is being ``tracked''.

SEE ALSO
S2_TRACKTYPE, S2_UNTRACKTYPE
</pre>

== S2_MULTICAST ==

<pre>
NAME
S2_MULTICAST -- Multicast a packet on network.

FUNCTION
This command works the same as CMD_WRITE except that it also performs
whatever special processing of the packet is required to do a
multicast send. The actual multicast mechanism is neccessarily
network/interface/device specific.

IO REQUEST
ios2_Command - S2_MULTICAST.
ios2_Flags - Supported flags are:
SANA2IOB_RAW
SANA2IOB_QUICK
ios2_PacketType - Packet type to send.
ios2_DstAddr - Destination interface address for this packet.
ios2_DataLength - Length of the Data to be sent.
ios2_Data - Abstract data structure which packet data is
contained in.

RESULTS
ios2_Error - Zero if successful; non-zero otherwise.
This command can fail for many reasons and
is not supported by all networks and/or
network interfaces.
ios2_WireError - More specific error number.

NOTES
The address supplied in ios2_DstAddr will be sanity checked (if
possible) by the driver. If the supplied address fails this sanity
check, the multicast request will fail immediately with ios2_Error
set to S2WERR_BAD_MULTICAST.

Another Amiga will not receive a multicast packet unless it has had
the particular multicast address being used S2_ADDMULTICASTADRESS'd.

SEE ALSO
CMD_WRITE, S2_BROADCAST, S2_ADDMULTICASTADDRESS
</pre>

== S2_OFFLINE ==

<pre>
NAME
S2_OFFLINE -- Remove interface from service.

FUNCTION
This command removes a network interface from service.

IO REQUEST
ios2_Command - S2_OFFLINE.

RESULTS
ios2_Error - Zero if successful; non-zero otherwise.
ios2_WireError - More specific error number.

NOTES
Aborts all pending reads and writes with ios2_Error set to
S2ERR_OUTOFSERVICE.

While the interface is offline, all read, writes and any other
command that touches interface hardware will be rejected with
ios2_Error set to S2ERR_OUTOFSERVICE.

This command is intended to permit a network interface to be
tested on an otherwise live system.

SEE ALSO
S2_ONLINE
</pre>

== S2_ONEVENT ==

<pre>
NAME
S2_ONEVENT -- Return when specified event occures.

FUNCTION
This command returns when a particular event condition has occured
on the network or this network interface.

IO REQUEST
ios2_Command - S2_ONEVENT.
ios2_Flags - Supported flags are:
SANA2IOB_QUICK
ios2_WireError - Mask of event(s) to wait for
(from <devices/sana2.h>).

RESULTS
ios2_Error - Zero if successful; non-zero otherwise.
ios2_WireError - Mask of events that occured.

NOTES
If this device driver does not understand the specified event
condition(s) then the command returns immediately with
ios2_Req.io_Error set to S2_ERR_NOT_SUPPORTED and ios2_WireError
S2WERR_BAD_EVENT. A successful return will have ios2_Error set to
zero ios2_WireError set to the event number.

All pending requests for a particular event will be returned when
that event occurs.

All event types that cover a particular condition are returned when
that condition occures. For instance, if an error is returned by
a buffer management function during receive processing, events of
types S2EVENT_ERROR, S2EVENT_RX and S2EVENT_BUFF would be returned if
pending.

Types ONLINE and OFFLINE return immediately if the device is
already in the state to be waited for.
</pre>

== S2_ONLINE ==

<pre>
NAME
S2_ONLINE -- Put a network interface back in service.

FUNCTION
This command places an offline network interface back into service.

IO REQUEST
ios2_Command - S2_ONLINE.

RESULTS
ios2_Error - Zero if successful; non-zero otherwise.
ios2_WireError - More specific error number.

NOTES
This command is responsible for putting the network interface
hardware back into a known state (as close as possible to the
state before S2_OFFLINE) and resets the unit global and special
statistics.

SEE ALSO
S2_OFFLINE
</pre>

== S2_READMGMT ==

<pre>
NAME
S2_READMGMT -- Read a management frame.

FUNCTION
Reads a raw IEEE 802.11 management frame from the device. The buffer
management mechanism used is simpler than that used for data
packets (e.g. with CMD_READ): a buffer pointer and a length value
are passed to the device.

As with CMDREAD/S2_READORPHAN, multiple S2_READMGMT requests can
(and should) be queued concurrently to ensure no incoming frames are
missed.

INPUTS
ios2_DataLength - size of frame buffer.
ios2_Data - pointer to a frame buffer.

RESULTS
io_Error - Zero if successful; non-zero otherwise.
ios2_WireError - More specific error code.
ios2_DataLength - actual size of received frame.
ios2_Data - pointer to the filled frame buffer.
</pre>

== S2_READORPHAN ==

<pre>
NAME
S2_READORPHAN -- Get a packet for which there is no reader.

FUNCTION
Get the next packet available that does not satisfy any then-pending
CMD_READ requests. The data returned in the ios2_Data structure is
normally the Data Link Layer packet type field and the packet data. If
bit SANA2IOB_RAW is set in ios2_Flags, then the entire Data Link Layer
packet, including both header and trailer information, will be
returned.

IO REQUEST
ios2_Command - CMD_READORPHAN.
ios2_Flags - Supported flags are:
SANA2IOB_RAW
SANA2IOB_QUICK
ios2_DataLength - Length of the Data to be sent.
ios2_Data - Abstract data structure which packet data is
contained in.

RESULTS
ios2_Error - Zero if successful; non-zero otherwise.
ios2_WireError - More specific error number.
ios2_Flags - The following flags may be returned:
SANA2IOB_RAW
SANA2IOB_BCAST
SANA2IOB_MCAST
ios2_SrcAddr - Source interface address of packet.
ios2_DstAddr - Destination interface address of packet.
ios2_DataLength - Length of the Data to be sent.
ios2_Data - Abstract data structure which packet data is
contained in.

NOTES
This is intended for debugging and management tools. Protocols should
not use this.

As with 802.3 packets on an ethernet, to determine which protocol
family the returned packet belongs to you may have to specify
SANA2IOB_RAW to get the entire data link layer wrapper (which is where
the protocol type may be kept). Notice this necessarily means that
this cannot be done in a network interface independent fashion. The
driver will, however, fill in the PacketType field to the best of its
ability.

SEE ALSO
CMD_READ, CMD_WRITE
</pre>

== S2_SAMPLE_THROUGHPUT ==

The SANA-II standard already allows for statistics to be returned on the amount of data that has passed through a driver. Unfortunately, that information is not very accurate in that no information is provided on the time span in which the data was accumulated. Such information would be helpful in trying to determine as accurately as possible how large the data throughput actually is. I therefore propose a new command which can be used to obtain that information, which uses the following data structure:

<syntaxhighlight lang="C" line>
struct Sana2ThroughputStats
{
ULONG s2ts_Length;
ULONG s2ts_Actual;

struct Task * s2ts_NotifyTask;
ULONG s2ts_NotifyMask;

struct timeval s2ts_StartTime;
struct timeval s2ts_EndTime;
S2QUAD s2ts_BytesSent;
S2QUAD s2ts_BytesReceived;
S2QUAD s2ts_Updates;
};
</syntaxhighlight>

Before I proceed to explain what purposes the individual members serve, a few words on the <tt>S2QUAD</tt> type, which is defined as follows:

<tt>typedef struct { ULONG s2q_High; ULONG s2q_Low; } S2QUAD;</tt>

In other words, the <tt>S2QUAD</tt> type stands for an unsigned 64 bit big endian integer, as expressed in ISO 'C' terms.

The structure members have the following purposes:

<tt>s2ts_Length</tt>

This is the size of the data structure to be filled in and should be initialized by the caller to <tt>sizeof(struct Sana2ThroughputStats)</tt>. Smaller values are permitted, but these must not be smaller than 8 (which covers the <tt>s2ts_Length</tt> and <tt>s2ts_Actual</tt> members). A driver which finds an <tt>s2ts_Length</tt> < 8 must treat this as an error and reject the command with <tt>ios2_Req.io_Error</tt>=<tt>IOERR_BADLENGTH</tt>.

<tt>s2ts_Actual</tt>

The size of the data structure filled with information. This member is initialized by the driver and must be <= <tt>s2ts_Length</tt>.

<tt>s2ts_NotifyTask</tt>

The <tt>Task</tt> to notify whenever the contents of this data structure change. This must be <tt>NULL</tt> if no notification is desired.

'''Note:''' This feature should be used carefully, as so much data may arrive that the driver will almost be constantly signalling this <tt>Task</tt> that a change has taken place.

It is recommend that periodic polling be used, such as to update displays of a link monitoring program.

<tt>s2ts_NotifyMask</tt>

The signal mask to use for notifying the <tt>Task</tt> whose address is found in <tt>s2ts_NotifyTask</tt> (via <tt>Signal(s2ts->s2ts_NotifyTask,s2ts->s2ts_NotifyMask);</tt>). This must be zero if no notification is desired.

<tt>s2ts_StartTime</tt>

The time when the driver started to fill in this data structure.

<tt>s2ts_EndTime</tt>

The time when the driver last updated the contents of this data structure.

<tt>s2ts_BytesSent</tt>

Total number of bytes sent since the driver started to fill in this data structure. This is a 64 bit integer.

<tt>s2ts_BytesReceived</tt>

Total number of bytes received since the driver started to fill in this data structure. This is a 64 bit integer.

<tt>s2ts_Updates</tt>

Number of times the driver has updated this data structure. This value will increase with every change. This is a 64 bit integer.

A driver implementing this command should take care to update the members <tt>s2ts_EndTime</tt>, <tt>s2ts_BytesSent</tt>, <tt>s2ts_BytesReceived</tt> and <tt>s2ts_Updates</tt> atomically each time changes are made.

I propose a command with the following semantics:

<pre>
NAME
S2_SAMPLE_THROUGHPUT -- Obtain accurate information on
driver data throughput.

FUNCTION
This command installs a data structure which is updated every time
data is sent or received by the driver.

This command must be sent via SendIO() or BeginIO(); until
the associated I/O request is recalled using AbortIO(), the
device unit will continue to update the Sana2ThroughputStats
structure in real time.

IO REQUEST
ios2_Command - S2_SAMPLE_THROUGHPUT
ios2_StatData - Pointer to Sana2ThroughputStats structure
to fill in
ios2_BufferManagement - Magic cookie as returned when opening the
driver with a struct IOSana2Req

RESULTS
ios2_Req.io_Error - Zero if successful; non-zero otherwise

NOTES
If this device driver does not understand this command,
it will immediately return the IOSana2Req with
ios2_Req.io_Error set to IOERR_NOCMD. Otherwise, the request will
remain queued until it is removed with AbortIO() later.
</pre>

I propose that the following command number should be assigned:

<tt>#define S2_SAMPLE_THROUGHPUT 0xC007</tt>

== S2_SANA2HOOK ==

The 'traditional' copy call-back functions are installed at <tt>OpenDevice()</tt> time, and they are found in a <tt>TagItem</tt> list which is passed along with the <tt>IOSana2Req</tt>. For the new <tt>Hook</tt>-based call-back functionality, I propose to introduce a new command. This command would take care of installing one single <tt>Hook</tt> which will be invoked with the parameters described in section 3.1. The hook function can key off the <tt>SANA2HookMsg->schm_Method</tt> field to figure out which function should be performed. Once the <tt>Hook</tt> is installed via the command as follows, the driver shall ignore any and all tags passed to it during <tt>OpenDevice()</tt> time.

<pre>
NAME
S2_SANA2HOOK -- Install a Hook to perform operations such as copying,
overriding the call-back functions installed at
OpenDevice() time.

FUNCTION
The S2_SANA2HOOK command is to replace the 'traditional' call-back
functions installed through the TagItem list found in the
IOSana2Req->ios2_BufferManagement field. Instead of assigning a
function pointer for each copying function, all operations are
to be performed through a Hook. This is intended to make the
interface more portable and less dependant on a certain hardware
architecture.

The hook message and the hook data structures allow for more than
copying to be done.

IO REQUEST
ios2_Command - S2_SANA2HOOK
ios2_Data - Points to a struct Sana2Hook, which looks
like this:

struct Sana2Hook
{
struct Hook s2h_Hook;
Tag * s2h_Methods;
};

The structure fields have the following purposes:

s2h_Hook
A standard Hook structure, ready to be
called. Once installed, the complete Hook
structure including its Node structure is
off limits! The s2h_Hook remains installed
until CloseDevice().

s2h_Methods
Points to a table of Tag values, each
identifying a copy method supported
(S2_CopyToBuff, S2_CopyFromBuff,
S2_CopyToBuff16, S2_CopyFromBuff16,
S2_CopyToBuff32, S2_CopyFromBuff32,
S2_DMACopyToBuff32, S2_DMACopyFromBuff32,
S2_DMACopyToBuff64 or S2_DMACopyFromBuff64)
or the logging facility (S2_Log).
The table must be terminated by TAG_END.

The driver will check the table and
verify that the mandatory S2_CopyToBuff
and S2_CopyFromBuff commands are present.
Additional functionality is used as
available if the driver supports it.

ios2_DataLength - Must be >= 20, which is the default length of
the Sana2Hook structure. This may grow in
the future, and larger values for ios2_DataLength
may indicate additional functionality associated
with the Sana2Hook.

RESULTS
ios2_Error - IOERR_NOCMD if this command is not supported
by the driver.

IOERR_BADLENGTH if IOSana2Req->ios2_DataLength
is < 20.

IOERR_UNITBUSY if the Hook was already
installed or if any of the CMD_READ, CMD_WRITE,
S2_MULTICAST or S2_BROADCAST have already been
invoked.

S2WERR_FUNCTIONS_MISSING if the table pointed
to by Sana2Hook->s2h_Methods does not
include the S2_CopyToBuff and S2_CopyFromBuff
tags.

NOTES
The S2_SANA2HOOK command shall be invoked right after OpenDevice()
as very first command.

When the command has been executed, the driver must use the
newly installed Hook for all its copying or logging and cease to
use the call-back functions provided at OpenDevice() time.

The contents of the Sana2Hook structure, as passed to the
driver, must not be modified. This includes the MinNode
at the beginning of the Hook structure which the driver may
need to use for its own purposes.

The table pointed to by Sana2Hook->s2h_Methods must
include at least the S2_CopyToBuff and S2_CopyFromBuff tags.
It must be valid until CloseDevice() is called.

This field is to be treated as private by a protocol stack.
IOSana2Req structures may be duplicated by copying
ios2_BufferManagement, io_Device, and io_Unit.
</pre>

The new command value is defined as follows:

<pre>
#define S2_SANA2HOOK 0xC008
</pre>

The new error code is defined as follows:

<pre>
#define S2WERR_FUNCTIONS_MISSING 24 /* mandatory copy functions are missing */
</pre>

== S2_SETKEY ==

<pre>
NAME
S2_SETKEY -- Set an encryption key.

FUNCTION
Sets one of the encryption keys for the device. Note that
ios2_StatData, if used, points to a byte array representing the RX
RX counter value.

INPUTS
ios2_WireError - Key index.
ios2_PacketType - Encryption type (e.g. S2ENC_WEP).
ios2_DataLength - Key length.
ios2_Data - Key.
ios2_StatData - RX counter number (NULL if unused).

RESULTS
io_Error - Zero if successful; non-zero otherwise.
ios2_WireError - More specific error code.
</pre>

== S2_SETOPTIONS ==

<pre>
NAME
S2_SETOPTIONS -- Set network options.

FUNCTION
Set various parameters for the network interface. This command
should be called before going online to set any essential parameters
not covered elsewhere. The S2INFO_#? tags used are defined in the
devices/sana2wireless.h include file.

INPUTS
ios2_Data - Pointer to a taglist that specifies parameters to use.

RESULTS
io_Error - Zero if successful; non-zero otherwise.
ios2_WireError - More specific error code.
</pre>

== S2_TRACKTYPE ==

<pre>
NAME
S2_TRACKTYPE -- Accumulate statistics about a packet type.

FUNCTION
This command causes the device driver to accumulate statistics about
a particular packet type. Packet type statistics, for the particular
packet type, are zeroed by this command.

IO REQUEST
ios2_Command - S2_TRACKTYPE.
ios2_PacketType - Packet type of interest.

RESULTS
ios2_Error - Zero if successful; non-zero otherwise.
ios2_WireError - More specific error number.

SEE ALSO
S2_UNTRACKTYPE, S2_GETTYPESTATS
</pre>

== S2_UNTRACKTYPE ==

<pre>
NAME
S2_UNTRACKTYPE -- End statistics about a packet type.

FUNCTION
This command causes the device driver to stop accumulating
statistics about a particular packet type.

IO REQUEST
ios2_Command - S2_UNTRACKTYPE.
ios2_PacketType - Packet type of interest.

RESULTS
ios2_Error - Zero if successful; non-zero otherwise.
ios2_WireError - More specific error number.

SEE ALSO
S2_TRACKTYPE, S2_GETTYPESTATS
</pre>

== S2_WRITEMGMT ==

<pre>
NAME
S2_WRITEMGMT -- Write a management frame.

FUNCTION
Writes a raw IEEE 802.11 management frame to the device. The buffer
management mechanism used is simpler than that used for data
packets (e.g. with CMD_WRITE): a buffer pointer and a length value
are passed to the device.

INPUTS
ios2_DataLength - full frame length.
ios2_Data - pointer to a complete IEEE 802.11 management frame.

RESULTS
io_Error - Zero if successful; non-zero otherwise.
ios2_WireError - More specific error code.
</pre>

= Callback mechanisms =

== CopyFromBuff ==

<pre>
NAME
CopyFromBuff -- Copy n bytes from an abstract data structure.

SYNOPSIS
success = CopyFromBuff(to, from, n)
d0 a0 a1 d0

BOOL CopyToBuff(VOID *, VOID *, ULONG);

FUNCTION
This function copies 'n' bytes of data in the abstract data structure
pointed to by 'from' into the contigous memory pointed to by 'to'.
'to' must contain at least 'n' bytes of usable memory or innocent
memory will be overwritten.

INPUTS
to - pointer to contiguous memory to copy to.
from - pointer to abstract structure to copy from.
n - number of bytes to copy.

RESULT
success - TRUE if operation was successful, else FALSE.

NOTES
This function must be callable from interrupts. In particular, this
means that this function may not directly or indirectly call any
system memory functions (since those functions rely on Forbid() to
protect themselves) and that you must not compile this function
with stack checking enabled. See the Exec Interrupts
chapter for more details on what is legal in a routine called from
an interrupt handler.

'C' programmers should not compile with stack checking (option '-v'
in SAS) and should geta4() or __saveds.</pre>

== CopyToBuff ==

<pre>
NAME
CopyToBuff -- Copy n bytes to an abstract data structure.

SYNOPSIS
success = CopyToBuff(to, from, n)
d0 a0 a1 d0

BOOL CopyToBuff(VOID *, VOID *, ULONG);

FUNCTION
This function first does any initialization and/or allocation
required to prepare the abstract data structure pointed at by 'to'
to be filled with 'n' bytes of data from 'from'. It then executes
the copy operation.

If, for example, there is not enough memory available to prepare
the abstract data structure, the call is failed and FALSE is returned.

The buffer management scheme should be such that any memory needed
to fulfill CopyToBuff() calls is already allocated from the system
before the call to CopyToBuff() is made.

INPUTS
to - pointer to abstract structure to copy to.
from - pointer to contiguous memory to copy from.
n - number of bytes to copy.

RESULT
success - TRUE if operation was successful, else FALSE.

NOTES
This function must be callable from interrupts. In particular, this
means that this function may not directly or indirectly call any
system memory functions (since those functions rely on Forbid() to
protect themselves) and that you must not compile this function
with stack checking enabled. See the Exec Interrupts
chapter for more details on what is legal in a routine called from
an interrupt handler.

'C' programmers should not compile with stack checking (option '-v'
in SAS) and should geta4() or __saveds.</pre>

== PacketFilter ==

<pre>
NAME
PacketFilter -- Perform filtering operation on CMD_READ's.

SYNOPSIS
keep = PacketFilter(hook, ios2, data)
d0 a0 a2 a1

BOOL PacketFilter(struct Hook *, struct IOSana2Req *, APTR);

FUNCTION
This function (if supplied by a protocol stack) may be used to
reject packets before they are copied into a protocol stack's
internal buffers.

The IOSana2Req structure should be set up to look (almost) exactly
as it would if it was successfully returned for the current packet.
Specifically, the fields that should be set up correctly are:

ios2->ios2_DataLength
ios2->ios2_SrcAddr
ios2->ios2_DstAddr

The "data" pointer must point to the beginning of the packet data
that is stored in contiguous memory. The data should NOT include
any hardware specific headers (unless of course the CMD_READ
request wanted RAW packets).

INPUTS
hook - pointer to the Hook originally supplied during
OpenDevice().
ios2 - The IOSana2Req CMD_READ request that will be used
(the "object" of the Hook call).
data - The packet data (the "message" of the Hook call).

RESULT
success - TRUE if the driver should provide the packet to
the protocol stack, FALSE if the packet should be
ignored.

NOTES
This function must be callable from interrupts. In particular, this
means that this function may not directly or indirectly call any
system memory functions (since those functions rely on Forbid() to
protect themselves) and that you must not compile this function
with stack checking enabled. See the Exec Interrupts
chapter for more details on what is legal in a routine called from
an interrupt handler.

'C' programmers should not compile with stack checking (option '-v'
in SAS) and should geta4() or __saveds.

What does packet filtering do? With the original ``SANA-II Network
Device Driver Specification'', a protocol stack could open a device
and ask for certain packet types. It got all the packets that matched
this type. As it turned out, this could be mighty inefficient if there
were packets that the protocol stack did not use at all. These would
go into read processing of the protocol stack and waste CPU time even
though they could have been easily identified on arrival.</pre>

= Ethernet description =

<pre>#define S2WireType_Ethernet 1

ios2_DataLength:
valid ethernet packets have 64 to 1500 bytes of data.

Address format:
Ethernet addresses consist of 47 bits of address information and
a 1 bit multicast flag. The standard for expressing ethernet
addresses is as 6 bytes (octets) in the order in which the bytes
are transmitted with the low-order bits in a byte transmitted
first. The multicast flag bit is the least-significant bit of the
first byte.

Ethernet addresses in a Sana2IOReq occupy the first 6 bytes of
an address field in transmission order with the low-order bits in
a byte transmitted first.

Station Address:
Each ethernet board must have a unique ethernet hardware address.
Drivers will override any attempt to set the address to anything
other than the ROM address.

Raw reads and writes:
6 bytes of destination address,
6 bytes of source address,
2 bytes of type,
64 to 1500 bytes of data
(followed by 4 byte CRC value covering all of the above
which is hardware generated and checked, hence not included
in even raw packets)

Multicast: Supported

Broadcast: Supported

Promiscuous: Supported

Packet Type Numbers for Ethernet are assigned by:

Xerox Corporation
Xerox Systems Institute
475 Oakmead Parkway, Sunnyvale, CA 94086
Attn: Ms. Fonda Pallone
(408) 737-4652

Some Common Packet Type Numbers:

decimal Hex Description
------- --- -----------
000 0000-05DC IEEE 802.3 Length Field
2048 0800 TCP/IP -- IP
2054 0806 TCP/IP -- ARP
32821 8035 TCP/IP -- RARP
32923 809B Appletalk
33011 80F3 AppleTalk AARP (Kinetics)
33100 814C SNMP
33079 8137-8138 Novell, Inc.</pre>
= ARCNET description =

<pre>S2WireType_Arcnet 7

ios2_DataLength:
506 byte MTU (because of the possibility of two byte Types).
Packets of size 254, 255, or 256 bytes are padded to 257 bytes before
transmition.

Station Address:
ARCNET hardware may have addresses set with jumpers, DIP switches
or software. Different drivers may therefore behave differently
with S2_CONFIGINTERFACE.

Hardware addresses should be assigned by users from highest to lowest
because there is some efficiency gained in the token passing scheme
this way. For example, on a three node network, hardware numbers 254,
253 and 252 should be used rather than 1, 2 and 3.

Raw reads and writes:
Short Packets (1-253 bytes)
Destination Address (1 byte)
Source Address (1 byte)
Count (256-N-Type length) (1 byte)
Padding (to byte number Count)
Type (1 or 2 bytes)
Data (N bytes)

Long Packets (257-506 bytes)
Destination Address (1 byte)
Source Address (1 byte)
zero (1 byte)
Count (512-N-Type length) (1 byte)
Padding (to byte number Count)
Type (1 or 2 bytes)
Data (N bytes)

Multicast: Not Supported

Broadcast: Supported

Promiscuous: Generally Not Supported

Packet Type Numbers for ARCNET are assigned by:
Datapoint Corporation

Some Common Packet Type Numbers

decimal hex description
------- --- -----------
221 DD AppleTalk
240 F0 TCP/IP -- IP (RFC 1051)
241 F1 TCP/IP -- ARP (RFC 1051)
212 F0 TCP/IP IP (RFC 1201, proposed)
213 F1 TCP/IP -- ARP (RFC 1201, proposed)
214 D6 TCP/IP -- RARP (RFC 1201, proposed)
247 F7 Banyan Vines
250 FA Novell IPX
</pre>

= Authors =

== Revision 2 & 3 ==

Copyright © 1992-2000 Amiga, Inc. All Rights Reserved 

Amiga is a registered trademark of Amiga, Inc. Ethernet is a trademark of Xerox Corporation. ARCNET is a trademark of Datapoint Corporation. DECNet is a trademark of Digital Equipment Corporation. AppleTalk is a trademark of Apple Computer, Inc.

== Revision 4 ==

Extending the SANA-II network driver specification 
by Olaf Barthel

(Last updated 02-Mar-2003)

== Revision 5 ==

Hook-based callback function extensions for SANA-II (SANA-IIR5) 
by Olaf Barthel and Heinz Wrobel

== Revision 6 ==

SANA-II IEEE 802.11 wireless API 
by Neil Cafferkey

= Acknowledgments =

== Revision 2 & 3 ==

Many people and companies have contributed to the "SANA-II Network Device Driver Specification". The original SANA-II Autodocs and includes were put together by Ray Brand, Perry Kivolowitz (ASDG) and Martin Hunt. Those original documents evolved to their current state and grew to include this document at the hands of Dale Larson and Greg Miller. Brian Jackson and John Orr provided valuable editing. Randell Jesup has provided sage advice on several occasions. The buffer management callback mechanism was his idea. Dale Luck (GfxBase) and Rick Spanbauer (Ameristar Technologies) have provided valuable comments throughout the process. Nicolas Benezan (ADONIS) provided many detailed and useful comments on weaknesses in late drafts of the specification. The enhancements for better buffer management, clarifications and notes for device implementers were added to the specification by Heinz Wrobel whilst consulting for Amiga Technologies GmbH, yielding revision 3.0 of the specification.

Thanks to all the above and the numerous others who have contributed with their comments, questions and discussions.

= Changes =

== Revision 4 ==

Changes since 24-Dec-2002:

* The <tt>Sana2Connection</tt> data structure used by the <tt>S2_CONNECT</tt> command now must remain valid until the <tt>S2_DISCONNECT</tt> command is sent (see [[#2.4|section 2.4]]).

Changes since 01-May-2002:

* Added the <tt>ppp.async.readrequests</tt> and <tt>ppp.async.eof</tt> configuration keywords.

Changes since 04-Jan-2002:

* Added the <tt>ppp.dummyremoteaddress</tt> and <tt>ppp.ethernet.ac</tt> configuration keywords.

Changes since 10-Dec-2001:

* Converted to HTML format.
* Added the <tt><devices/sana2.h></tt> header file to the appendix.
* The memory alignment for the <tt>S2_DMACopyToBuff64</tt> and <tt>S2_DMACopyFromBuff64</tt> hooks refers to bits and not to bytes.

Changes since 19-Nov-2001:

* Added to the list of reserved configuration keywords (<tt>ppp.idletimeout</tt>, <tt>ppp.peeridletimeout</tt>, <tt>ppp.sendid</tt>).
* Renamed the fields of the <tt>Sana2ExtDeviceStats</tt> structure.
* Clarified that the <tt>S2QUAD</tt> type is a big endian integer.
* More clarifications for the <tt>S2_CONNECT</tt>/<tt>S2_DISCONNECT</tt> and <tt>S2_ONLINE</tt>/<tt>S2_OFFLINE</tt> commands.
* Updated the discussion of the <tt>Sana2DeviceQuery.RawMTU</tt> field, clarifying what is included in the the Ethernet <tt>RawMTU</tt>.
* Updated the <tt><devices/sana2.h></tt> header file. Note that there is no equivalent <tt>"devices/sana2.i"</tt> header file yet.

Changes since 12-Nov-2001:

* Changed the command numbers of <tt>S2_GETPEERADDRESS</tt>, <tt>S2_GETDNSADDRESS</tt>, <tt>S2_GETEXTENDEDGLOBALSTATS</tt>, <tt>S2_CONNECT</tt>, <tt>S2_DISCONNECT</tt> and <tt>S2_SAMPLE_THROUGHPUT</tt> to be NSD-compliant. Also assigned a new number to the <tt>S2_SAMPLE_THROUGHPUT </tt> command.
* Added section 4 ("Extensions for existing commands").
* Added the last paragraph to section 9, relating to the future extension of the <tt>Sana2DeviceQuery</tt> structure.

Changes since 03-Nov-2001:

* Renamed <tt>S2_GETNEWGLOBALSTATS</tt> to <tt>S2_GETEXTENDEDGLOBALSTATS</tt> (see [[#2.3|section 2.3]]).
* The <tt>S2_GETEXTENDEDGLOBALSTATS</tt> now uses 64 bit quantities for the <tt>s2xds_PacketsReceived</tt>, <tt>s2xds_PacketsSent</tt>, <tt>s2xds_BadData</tt>, <tt>s2xds_Overruns</tt>, <tt>s2xds_UnknownTypesReceived</tt> and <tt>s2xds_Reconfigurations</tt> counters.
* In section 2.6 the <tt>S2_SAMPLE_THROUGHPUT</tt> command was modified to use 64 bit integers for all members of the <tt>Sana2ThroughputStats</tt> structure.
* All proposed commands are now listed with their numeric IDs.
* The command autodocs specifically mention the <tt>ios2_BufferManagement</tt> field.
* All references to <tt>ios2_Error</tt> have been replaced with <tt>ios2_Req.io_Error</tt>.
* In section 7 the use of the <tt>IOERR_NOCMD</tt>/<tt>S2ERR_NOT_SUPPORTED</tt> error codes is clarified.
* Section 7 takes a more detailed look at safe default values returned by the query commands.
* Inserted section 3 ("Annotations for existing commands").
* The <tt>S2_CONNECT</tt> and <tt>S2_DISCONNECT</tt> commands now specifically mention the life time of the data they have to deal with.

Changes since 14-Oct-2001:

* Added <tt>S2_CONNECT</tt> and <tt>S2_DISCONNECT</tt> commands.
* Added <tt>S2EVENT_CONNECT</tt> and <tt>S2EVENT_DISCONNECT</tt> events.
* Added section 4 ("New wire error codes").
* In section 5.2 the originally proposed log callback function has been wrapped into a standard Hook structure.
* Removed item on <tt>S2_CONNECT</tt>/<tt>S2_DISCONNECT</tt> from section 7 ("Unsolved problems").
* Added section 8 ("Changes").

== Revision 5 ==

22-Mar-2004:

* Conversion to HTML

21-Jan-2004:

* Added clarifications for <tt>schm_MsgSize</tt>, <tt>slhm_MsgSize</tt>, <tt>slhm_Priority</tt>, <tt>slhm_Name</tt>, <tt>slhm_Message</tt> and <tt>s2h_Hook</tt>.
* Updated the <tt>S2_SANA2HOOK</tt> documentation.
* Shortened section 4.
* Updated section 5.

30-Nov-2003:

* Extended the applicability of the <tt>Hook</tt> to logging.
* Renamed <tt>S2_COPYHOOK</tt> to <tt>S2_SANA2HOOK</tt>, which matches the extended scope it should cover.
* The message passed to the <tt>Hook</tt> now includes a size field which holds the size of the message, expressed in bytes.

06-Oct-2003:

* Replaced the list of new tag items with a single <tt>Hook</tt>, which is installed through a new command.
* Added "Caveats" and "Changes" sections
* Removed the documentation for the originally proposed <tt>TagItem</tt> (sections 3.2.1 through 3.2.10)

= History =

== Revision 2 and 3 ==

This standard has undergone several drafts with long periods for comment from developers and the Amiga community at large. These drafts include a UseNet release which was also distributed on the Fish Disks in June, 1991 (as well as published in the '91 DevCon notes), and the November 7 Draft for Final Comment and Approval distributed via Bix, ADSP and UseNet. There were also several intermediate drafts with more limited distribution.

== Revision 4 ==

(Olaf Barthel)

I've been working on a TCP/IP stack and PPP drivers to go with them for a while and found that there were some things that SANA-II did specifically not address, and which ought to be covered by it. In other areas clarification was needed. Also, discussions I had with Harald Frank suggested that the extensions made by Heinz Wrobel and Stefan Sticht in the SANA-IIR3 specification could need extending.

SANA-II Revision 7

2026-09-02T11:08:47Z

Costel Mincea: /* S2_DEVICEQUERY */

{{WIP}}
= SANA-II Network Device Driver Specification =

The "SANA-II Network Device Driver Specification" is a standard for an Amiga software interface between networking hardware and network protocol stacks (or for software tools such as network monitors). A network protocol stack is a layer of software that network applications use to address particular processes on remote machines and to send data reliably in spite of hardware errors. There are several common network protocol stacks including ''TCP/IP'', ''OSI'', ''AppleTalk'', ''DECNet'' and ''Novell''.

SANA-II device drivers are intended to allow multiple network protocol stacks running on the same machine to share one network device. For example, the TCP/IP and AppleTalk protocol stacks could both run on the same machine over one ethernet board. The device drivers are also intended to allow network protocol stacks to be written in a hardware-independent fashion so that a different version of each protocol stack doesn't have to be written for each networking hardware device.

The standard does not address the writing of network applications. Application writers must not use SANA-II Device Drivers directly. Network applications must use the API provided by the network protocol software the application supports. The Amiga standard network API for TCP/IP is provided via the bsdsocket.library which is a part of Roadshow.

To write a SANA-II device driver, you will need to be familiar with the specification documents for the hardware you are writing to and with the "SANA-II Network Device Driver Specification".

To write a network protocol stack which will use SANA-II device drivers, you should have general familiarity with common network hardware and must be very familiar with the "SANA-II Network Device Driver Specification" as well as the specification for the protocol you are developing. If you are creating a new protocol, you must obtain a protocol type number for any hardware on which your protocol will be used.

This version of the specification is final. Any new version of the standard (i.e., to add new features) is planned to be backward compatible. No SANA-II device driver or software utilizing those drivers should be written to any earlier version of the specification.

Distribution of this version of the standard is unlimited. Anyone may write Amiga software which implements a SANA-II network device driver or which calls a SANA-II network device driver without restriction and may freely distribute such software that they have written.

It is important to try to test each SANA-II device driver against all software which uses SANA-II devices. Available example programs are valuable in initial testing. The Amiga Networking Group is interested in receiving evaluation and/or beta test copies of all Amiga networking hardware, SANA-II device drivers and software which uses SANA-II devices. However, we make no assurances regarding any testing which we may or may not perform with such evaluation copies.

The SANA-II standard caters to both Motorola 68000 platforms and PowerPC platforms.

Please feel free to comment. You can contact the AmigaOS development team through the [http://www.amigaos.net/contact AmigaOS contact form].

= Driver Form =

SANA-II device drivers are Amiga Exec device drivers. They use an extended IORequest structure and a number of extended commands for tallying network statistics, sending broadcasts and multicasts, network addressing and the handling of unexpected packets. The SDK includes information on how to construct an Exec device.

= Opening a SANA-II Device =

As when opening any other Exec device, on the call to OpenDevice() a SANA-II device receives an IORequest structure which the device initializes for the opener's use. The opener must copy this structure if it desires to use multiple asynchronous requests. The SANA-II IORequest is defined as follows:

<syntaxhighlight lang="C" line>
struct IOSana2Req
{
struct IORequest ios2_Req;
ULONG ios2_WireError;
ULONG ios2_PacketType;
UBYTE ios2_SrcAddr[SANA2_MAX_ADDR_BYTES];
UBYTE ios2_DstAddr[SANA2_MAX_ADDR_BYTES];
ULONG ios2_DataLength;
APTR ios2_Data;
APTR ios2_StatData;
APTR ios2_BufferManagement;
};
</syntaxhighlight>

; ios2_Req
: A standard Exec device IORequest.
; ios2_WireError
: A more specific device code which may be set when there is an io_Error. See <devices/sana2.h> for the defined WireErrors.
; ios2_PacketType
: The type of packet requested. See the section on "Packet Types".
; ios2_SrcAddr
: The device fills in this field with the interface (network hardware) address of the source of the packet that satisfied a read command. The bytes used to hold the address will be left justified but the bit layout is dependent on the particular type of network.
; ios2_DstAddr
: Before the device user sends a packet, it fills this with the interface destination address of the packet. On receives, the device fills this with the interface destination address. Other commands may use this field differently (see the "SANA-II network device driver Autodocs" in the SDK). The bytes used to hold the address will be left justified but the bit layout is dependent on the particular type of network.
; ios2_DataLength
: The device user initializes this field with the amount of data available in the Data buffer before passing the IOSana2Req to the device. The device fills in this field with the size of the packet data as it was sent on the wire. This does not include the header and trailer information. Depending on the network type and protocol type, the driver may have to calculate this value. This is generally used only for reads and writes (including broadcast and multicast).
; ios2_Data
: A pointer to some abstract data structure containing packet data. ''Drivers may not directly manipulate or examine anything pointed to by Data!'' This is generally used only for reads and writes (including broadcast and multicast).

; ios2_StatData
: Pointer to a structure in which to place a snapshot of device statistics. The data area must be long word aligned. This is only used on calls to the statistics commands.

; ios2_BufferManagement
: The opener places a pointer to a tag list in this field before calling OpenDevice(). Functions pointed to in the tag list are called by the device when processing IORequests from the opener. When returned from OpenDevice(), this field contains a pointer to driver-private information used to access these functions. See "Buffer Management" below for more details.

: Note that the <tt>ios2_BufferManagement</tt> field provided by the driver on <tt>OpenDevice()</tt> time in conjunction with <tt>io_Device</tt> and <tt>io_Unit</tt> is the unique identifier for all requests coming from this protocol stack until <tt>CloseDevice()</tt>. The driver must not ever change the <tt>ios2_BufferManagement</tt> field for a protocol stack at run time, even if <tt>S2_SANAHOOK</tt> is called to request extended features.

The flags used with the device on OpenDevice() are (SANA2OPB_xxx):

{| class="wikitable"
! Name
! Description
|-
| SANA2OPB_MINE
| Exclusive access to the unit requested.
|-
| SANA2OPB_PROM
| Promiscuous mode requested. Hardware which supports promiscuous mode allows all packets sent over the wire to be captured whether or not they are addressed to this node.
'''''Note:''' Promiscuous mode requires exclusive opening of the device.''
|}

The flags used during I/O requests are (SANA2IOB_xxx):

{| class="wikitable"
! Name
! Description
|-
| SANA2IOB_RAW
| Raw packet read/write requested. Raw packets should include the entire data-link layer packet. Devices with the same hardware device number should have the same raw packet format.
|-
| SANA2IOB_BCAST
| Broadcast packet (received).
|-
| SANA2IOB_MCAST
| Multicast packet (received).
|-
| SANA2IOB_QUICK
| Quick IO requested.
|}

= Buffer Management =

Unlike most other Exec Device drivers, SANA-II drivers have no internal buffers. Instead, they read/write to/from an abstract data structure allocated by the driver user. The driver accesses these buffers only via functions that the driver user provides to the driver. The driver user must provide two functions: one copies data to the abstract data structure and one copies data from the abstract data structure. The driver user can therefore choose the data structure used for buffer management by both the driver and driver user in order to have efficient memory and CPU usage overall.

The IOSana2Req contains a pointer to data and the length of said data. A driver is not allowed to make assumptions about how the data is stored. The driver cannot directly manipulate or examine the buffer in any manner. The driver can only access the buffer by calling the functions provided by the driver user.

Before calling OpenDevice(), the driver user points ios2_BufferManagement to a list of tags (defined in <devices/sana2.h>) which include pointers to the buffer management functions required by the driver (defined below). The driver will fail to open if the driver user does not supply all of the required functions. If the device opens successfully, the driver sets ios2_BufferManagement to a value which this opener must use in all future calls to the driver. This "magic cookie" is used from then on to access these functions (a "magic cookie" is a value which one software entity passes to another but which is only meaningful to one of the software entities). The driver user may not use the "magic cookie" in any way--it is for the driver to do with as it wishes. The driver could in theory choose to just copy the tag list to driver-owned memory and then parse the list for every IORequest, but it is much more efficient for the driver to create some sort of table of functions and to point ios2_BufferManagement to that table.

Another recommendation for the ``magic cookie`` is to use it to maintain a separate packet read queue for each device opener. This would allow multiple protocol stacks that all wish to receive the same packet type to work together without having to "know" about each other as ''Envoy'' and ''AS225'' do right now. What does multiple protocol stack support mean? Basically this means that each opener gets all the packets necessary. If a packet comes in that fills a request for more than one opener of the device, all of them will get a copy of the packet. This feature should never be left out of a device design. If it is missing, the usefulness of the device is severely limited.

In order to help system load, a packet filter callback allows protocol stacks to reject packets that are known to not be useful. ''Envoy'''s nipc.library (for example) could be modified to reject TCP packets (as it never uses them).

The specification currently defines the following tags for the OpenDevice() ios2_BufferManagement tag list:

{| class="wikitable"
|+ Copy data from network interface to protocol stack buffer
! Tag
! Description
|-
| S2_CopyToBuff (mandatory)
| This is a pointer to a function which conforms to the CopyToBuff Autodoc.
|-
| S2_CopyToBuff16 (optional)
| Copy to a 16 bit aligned buffer using 16 bit data words.
|-
| S2_CopyToBuff32 (optional)
| Copy to a 32 bit aligned buffer using 32 bit data words.
|-
| S2_DMACopyToBuff32 (optional)
| Perform a DMA copy to a 32 bit aligned contiguous buffer using 32 bit data words.
|-
| S2_DMACopyToBuff64 (optional)
| Perform a DMA copy to a 64 bit aligned contiguous buffer using 64 bit data words.
|}

{| class="wikitable"
|+ Copy data from protocol stack buffer to network interface
! Tag
! Description
|-
| S2_CopyFromBuff (mandatory)
| This is a pointer to a function which conforms to the CopyFromBuff Autodoc.
|-
| S2_CopyFromBuff16 (optional)
| Copy from a 16 bit aligned buffer using 16 bit data words.
|-
| S2_CopyFromBuff32 (optional)
| Copy from a 32 bit aligned buffer using 32 bit data words.
|-
| S2_DMACopyFromBuff32 (optional)
| Perform a DMA copy from a 32 bit aligned contiguous buffer using 32 bit data words.
|-
| S2_DMACopyFromBuff64 (optional)
| Perform a DMA copy from a 64 bit aligned contiguous buffer using 64 bit data words.
|}

{| class="wikitable"
|+ Filter data before protocol stack buffer
! Tag
! Description
|-
| S2_PacketFilter (optional)
| This is a pointer to a standard Hook to be called before S2_CopyToBuff is done. See the PacketFilter Autodoc for more information.
|}

{| class="wikitable"
|+ Logging messages from the driver
! Tag
! Description
|-
| S2_Log (optional)
| This is a pointer to a standard Hook to be called when the driver logs events.
|}

== Better buffer management ==

The mandatory buffer management callbacks may not be very efficient for certain types of hardware. They also do not allow driver DMA access.

All the new features are completely optional and do not collide with existing features. They may be used only when the protocol stack asks for them on opening a driver.

The enhancements consist of several new tags that may be specified by a protocol stack on OpenDevice() to offer certain data transfer options. It is up to the device driver to chose which callbacks to use at what time. These tags are advisory only and may be ignored by the driver for any data buffer at any time:

{| class="wikitable"
| S2_CopyToBuff16
|-
| S2_CopyFromBuff16
|-
| S2_CopyToBuff32
|-
| S2_CopyFromBuff32
|}

These are optional callbacks presented to the device with the same calling interface as for S2_CopyToBuff or S2_CopyFromBuff, respectively. The difference to the original callbacks is the required and guaranteed transfer size and alignment for accessing the device's buffer for a single piece of a data of either 16 or 32 bits, a data word. The copy function called may only use 16/32 bit aligned read/write commands of 16/32 bits at once to transfer the data words, respectively. If the buffer data length is not a multiple of the required data word transfer size, the last data word transfer may contain garbage padding in either transfer direction.

The following tags have been added to support direct writes into hardware buffers that do not allow arbitrarily sized or aligned accesses:

{| class="wikitable"
| S2_DMACopyToBuff32
|-
| S2_DMACopyFromBuff32
|}

If the protocol stack wants to optionally enhance data transfer efficiency with DMA supporting devices, it may pass any of these optional tags to the device on OpenDevice().

If the device driver supports DMA, it may call the respective callback with the abstract magic cookie ios2_Data in register A0. The callback may return NULL in D0. In this case, the driver may not use DMA for this buffer. Alternatively, the callback may return the address of the actual data buffer in D0, if it has these characteristics:

* The buffer is in contiguous memory. Depending on the intended data direction, it shall be readable or writable.
* The buffer is aligned on a 32 bit boundary.
* The buffer size shall be a multiple of 32 bit and it is at least = ios2_DataLength.
* It is up to the driver to decide if it can use DMA for this buffer and it shall fall back to the standard CPU callbacks if necessary. The data transfer method actually used by the driver will not be known in advance by the protocol stack.

The following tags have been added to allow for 64 bit aligned PCI DMA accesses to take place:

{| class="wikitable"
| S2_DMACopyToBuff64
|-
| S2_DMACopyFromBuff64
|}

These two callbacks are identical in operation to the <tt>S2_DMACopyToBuff32</tt> and <tt>S2_DMACopyFromBuff32</tt> callbacks. The difference is in that the memory region DMA is to take place in must be aligned to a 64 bit boundary and must be large enough to hold data that is a multiple of 64 bits in size.

== Best buffer management ==

The SANA-II driver interface is intended to transform data between the hardware layer and the link layer, to be used by networking software such as TCP/IP stacks. This transformation is performed by callback functions which are supplied by the networking software at the time the device driver is opened. The device driver then invokes these functions later in order to transfer data received and data to be sent.

The function parameters used by these callbacks are passed in 68000 registers for the lowest overhead. The problem with 68000 register parameters is that on the PowerPC platform, this form of parameter passing may require the use of emulation code. This is costly and may incur a severe performance penalty. It is an even greater problem if PowerPC native networking software is calling PowerPC native networking driver software and the other way round. In both cases the runtime environment will have to enter emulation mode, return to to PowerPC native execution, dip into emulation mode and return to native PowerPC execution. It would be much better if the chain of execution would stay in PowerPC mode all the time.

Alternatively, if a hook function is used, the operating system may be able to decide whether the function to be invoked needs emulating or called directly. The <tt>Hook</tt> effectively works as an abstraction which makes the function invocation platform independent.

The following standard wraps the copying and logging functions into the standardized <tt>Hook</tt> interface.

==== The hook function ====

The hook function itself is invoked with the following parameters:

<syntaxhighlight lang="C" line>
result = hook_function(hook, sana2req, sana2hookmsg)

ULONG hook_function(struct Hook *hook,
struct IOSana2Req *sana2req,
struct SANA2HookMsg *sana2hookmsg);
</syntaxhighlight>

Note that the result is not necessarily of type <tt>ULONG</tt>. It is a 32 bit value, which can be a boolean result code (for <tt>CopyFromBuff</tt>, <tt>CopyToBuff</tt> and their like) or a pointer to a memory address (for <tt>DMACopyToBuff</tt>, <tt>DMACopyFromBuff</tt> and their like).

=== Data structures ===

The following hook messages are to be used:

<syntaxhighlight lang="C" line>
struct SANA2HookMsg
{
ULONG shm_Method;
ULONG shm_MsgSize;
};
</syntaxhighlight>

In this data structure the <tt>shm_Method</tt> field would indicate the task to be performed. This can be a request to copy data or to store a log message. The <tt>shm_MsgSize</tt> field tells you how large the data structure is for future enhancements which may cause the data structure to grow.

==== Copying operations ====

For copying operations the message is:

<syntaxhighlight lang="C" line>
struct SANA2CopyHookMsg
{
ULONG schm_Method;
ULONG schm_MsgSize;

APTR schm_To;
APTR schm_From;
ULONG schm_Size;
};
</syntaxhighlight>

The structure members are as follows:

; schm_Method
: This must be one <tt>S2_CopyToBuff</tt>, <tt>S2_CopyFromBuff</tt>, <tt>S2_CopyToBuff16</tt>, <tt>S2_CopyFromBuff16</tt>, <tt>S2_CopyToBuff32</tt>, <tt>S2_CopyFromBuff32</tt>, <tt>S2_DMACopyToBuff32</tt>, <tt>S2_DMACopyFromBuff32</tt>, <tt>S2_DMACopyToBuff64</tt> or <tt>S2_DMACopyFromBuff64</tt> to identify the function to be performed.

; schm_MsgSize
: Size of this message data structure in bytes. This must be >= 20 for this message type.
: The driver shall set <tt>schm_MsgSize</tt> always correctly to be compliant. The protocol stack shall use this field to validate the message and to reject/ignore bad messages via a <tt>FALSE</tt> hook function return value. For DMA related hooks, a <tt>FALSE</tt> return value is equivalent to a <tt>NULL</tt> pointer.

; schm_To
: Equivalent to the <tt>to</tt> parameter of the <tt>CopyFromBuff</tt>, <tt>CopyToBuff</tt> and <tt>DMACopyToBuff</tt> functions.

; schm_From
: Equivalent to the <tt>from</tt> parameter of the <tt>CopyFromBuff</tt> and <tt>CopyToBuff</tt> functions.

; schm_Size
: Equivalent to the <tt>n</tt> parameter of the <tt>CopyFromBuff</tt>, <tt>CopyToBuff</tt>, functions.

==== Logging operations ====

For logging operations the message is:

<syntaxhighlight lang="C" line>
struct SANA2LogHookMsg
{
ULONG slhm_Method;
ULONG slhm_MsgSize;

ULONG slhm_Priority;
STRPTR slhm_Name;
STRPTR slhm_Message;
};
</syntaxhighlight>

The structure members would be used as follows:

; slhm_Method
: This must be <tt>S2_Log</tt>, as defined in the SANA-IIR4 specification.

; slhm_MsgSize
: Size of this message data structure in bytes. This must be >= 20 for this message type.
: The driver shall set <tt>slhm_MsgSize</tt> always correctly to be compliant. The protocol stack shall use this field to validate the message and to reject/ignore bad messages via a <tt>FALSE</tt> hook function return value. For DMA related hooks, a <tt>FALSE</tt> return value is equivalent to a <tt>NULL</tt> pointer.

; slhm_Priority
: The smaller this value, the more important the message to be logged or displayed. The following priority levels are defined (similar to the Unix syslog() mechanism):
:{| class="wikitable"
| S2LOG_Emergency || A panic condition.
|-
| S2LOG_Alert || A condition that should be corrected immediately.
|-
| S2LOG_Critical || Critical conditions.
|-
| S2LOG_Error || A plain error.
|-
| S2LOG_Warning || A warning message.
|-
| S2LOG_Notice || Conditions that are not error conditions, but should possibly be handled specially.
|-
| S2LOG_Information || An informational message.
|-
| S2LOG_Debug || Messages that contain information normally of use only when debugging.
|}
: Only these priority values may be used by a driver. It is suggested that a driver is configurable to generate different types of messages or not, e.g., a driver may be configured to only emit <tt>S2LOG_Emergency</tt> and <tt>S2LOG_Debug</tt> messages

; slhm_Name
: Pointer to a <tt>NUL</tt>-terminated string which identifies the source of this message. This can be <tt>NULL</tt> in which case the OS device name of the driver shall be used by the protocol stack.

; slhm_Message
: Pointer to a <tt>NUL</tt>-terminated string which contains the log message. The text should not contain any formatting characters such as line feeds or carriage returns. The <tt>slhm_Message</tt> member must never be <tt>NULL</tt>.
: All message texts shall preferably be formatted in the current user's locale. If that is not possible, the english language shall be used. <tt>slhm_Name</tt> and <tt>slhm_Message</tt> shall only contain printable characters.

=== Application and driver software use of the new functions ===

Since plenty of software exists which uses the 'traditional' <tt>TagItem</tt> list provided at <tt>OpenDevice()</tt> time, drivers must always examine these parameters and not expect a <tt>S2_SANA2HOOK</tt> command to be sent later.

If the new <tt>Hook</tt>-based callback functions are used then the driver must invoke the Hooks via <tt>utility.library/CallHookPkt</tt>. It must never invoke the hook functions through local assembly language stubs or the <tt>amiga.lib/CallHook</tt> and <tt>amiga.lib/CallHookA</tt> functions.

=== Caveats ===

The functionality above suggests that one could do entirely without the <tt>TagItem</tt> list passed in at <tt>OpenDevice()</tt> time. However, at this time it is hard to tell how existing driver software will react to empty <tt>TagItem</tt> lists or even a NULL pointer in the <tt>IOSana2Req->ios2_BufferManagement</tt> field. It is therefore important to always provide for a <tt>TagItem</tt> list which includes proper (i.e. they must point to working functions and may not be <tt>NULL</tt>) function pointers for the <tt>S2_CopyToBuff</tt> and <tt>S2_CopyFromBuff</tt> tags. Once the device has been opened successfully, the next step is to try and install the copy <tt>Hook</tt> through the proposed <tt>S2_SANA2HOOK</tt> command. If the command fails, the application can still expect that the <tt>S2_CopyToBuff</tt> and <tt>S2_CopyFromBuff</tt> tags supplied at <tt>OpenDevice()</tt> time will work.

== Packet filtering ==

With the original "SANA-II Network Device Driver Specification", a protocol stack could open a device and ask for certain packet types. It got all the packets that matched this type. As it turned out, this could be mighty inefficient if there were packets that the protocol stack did not use at all. These would go into read processing of the protocol stack and waste CPU time even though they could have been easily identified on arrival.

== Driver event logging ==

A driver may want to report an important event for the user to see. Adding a log message to a file or opening a window to display a message in may not be the optimum approach as the user may be unaware of the context into which the message belongs. It may be advisable for the driver to use the message reporting and logging facilities used by the client software that uses its services, such as a TCP/IP stack. The <tt>S2_Log</tt> callback hook is intended to provide for such a link.

If present, the driver must use this callback hook rather than whatever logging methods it implements itself. Note that unlike the other SANA-II callbacks, this is a regular hook, as to be invoked using <tt>utility.library</tt>/<tt>CallHookPkt()</tt>. The hook function is invoked using the following parameters:

<syntaxhighlight lang="C" line>
log_hook_function(hook, reserved, message)

void log_hook_function(struct hook * hook,APTR reserved,
struct S2LogMessage * message);
</syntaxhighlight>

The <tt>reserved</tt> parameter '''must''' be set to <tt>NULL</tt>. The <tt>S2LogMessage</tt> structure passed as the third parameter looks like this:

<syntaxhighlight lang="C" line>
struct S2LogMessage
{
LONG s2lm_Size;
ULONG s2lm_Priority;
STRPTR s2lm_Name;
STRPTR s2lm_Message;
};
</syntaxhighlight>

The individual structure members serve the following functions:

; s2lm_Size
: Size of the <tt>S2LogMessage</tt> structure, in bytes. The idea is to extend this data structure in the future, and the size stored in here tells you how long the structure is. The size '''must''' always be >= 16.

;s2lm_Priority
: The smaller this value, the more important the message to be logged or displayed. The following priority levels are defined (similar to the Unix <tt>syslog()</tt> mechanism):
:{| class="wikitable"
| S2LOG_Emergency || A panic condition.
|-
| S2LOG_Alert || A condition that should be corrected immediately.
|-
| S2LOG_Critical || Critical conditions.
|-
| S2LOG_Error || A plain error.
|-
| S2LOG_Warning || A warning message.
|-
| S2LOG_Notice || Conditions that are not error conditions, but should possibly be handled specially.
|-
| S2LOG_Information || An informational message.
|-
| S2LOG_Debug || Messages that contain information normally of use only when debugging.
|}

; s2lm_Name</tt>
: Pointer to a <tt>NUL</tt>-terminated string which identifies the source of this message. This can be <tt>NULL</tt> in which case the name is treated as being unknown.

; s2lm_Message
: Pointer to a <tt>NUL</tt>-terminated string which contains the log message. The text should not contain any formatting characters such as line feeds or carriage returns. The <tt>s2lm_Message</tt> member '''must never''' be <tt>NULL</tt>.

All error messages issued by the device driver should use the current system locale wherever this is possible. The purpose of an error message is, after all, to assist the user in recovering from the error. Which may be difficult if the user does not even know the language in which the message is written.

The log message string is valid until the log hook function returns. If the driver needs to retain the message any longer, it must make a copy of it.

Since the client software into which the log hook calls may have to allocate memory to hold and display the log message, the log hook '''must not''' be called from interrupt code. The log hook shall not <tt>Wait()</tt> and it shall assume only a <tt>Task</tt> calling context of unknown priority. <tt>dos.library</tt> functions may not be called. Also, stack space is provided only to call <tt>exec.library</tt> and <tt>utility.library</tt> functions. The callback shall not place excessive data on the stack. Stack space should be considered limited and the callback should be designed to be fast and short.

This hook is installed at <tt>OpenDevice()</tt> time, which means that the hook is used for the unit that was opened, and not just for the I/O request it was opened with. The hook must remain installed until the I/O request that installed it is eventually used to close the device. When this happens, the device should fall back to use no log hook at all. No nesting is permitted or required.

= Packet Type =

Network frames always have a type field associated with them. These type fields vary in length, position and meaning by frame type (frame types generally correspond one-to-one with hardware types, but see "Ethernet Packet Types" below). The meanings of the type numbers are always carefully defined and every type number is registered with some official body. Do not use a type number which is not registered for any standard hardware you use or in a manner inconsistent with that registration.

The type field allows the SANA-II device driver to fulfill CMD_READs based on the type of packet the driver user wants. Multiple protocols can therefore run over the same wire using the same driver without stepping on each other's toes.

Packet types are specified as a long word. Unfortunately, the type field means different things on different wires. Driver users must allow their software to be configured with a SANA-II device name, unit number and the type number(s) used by the protocol stack with each device. This way, if new hardware becomes available, a hardware manufacturer can supply a listing of type assignments to configure pre-existing software.

== Ethernet Packet Types ==

Ethernet has a special problem with packet types. Two types of ethernet frames can be sent over the same wire: ethernet and 802.3. These frames differ in that the Type field of an ethernet frame is the Length field of an 802.3 frame. This creates a problem in that demultiplexing incoming packets can be cumbersome and inefficient, as well as requiring driver users to be aware of the frame type used.

All 802.3 frames have numbers less than 1500 in the Type field. The only frames with numbers less than 1500 in the type field are 802.3 frames. SANA-II ethernet drivers abnormally return packets contained in ethernet frames when the requested Type falls within the 802.3 range-if the Type requested is within the 802.3 range, the driver returns the next packet contained within an 802.3 frame, regardless of the type specified for the packet within the 802.3 frame. This requires that there be no more than one driver user requesting 802.3 packets and that it do its own interpretation of the frames.

== ARCNET Frames ==

ARCNET also has a special problem with framing. ARCNET frames consist of a hardware header and a software header. The software header is in the data area of the hardware packet, and includes at least the protocol ID.

There are two types of software header. Old-style ARCNET software headers consist entirely of a one or two byte protocol ID. New ARCNET software headers (defined in RFC 1201 and in the paper "ARCNET Packet Header Definition Standard", Novell, Inc., 1989) include more information. They allow more efficient use of ARCNET through data link layer fragmentation and reassembly (ARCNET has a small Maximum Transmission Unit) and allow sending any size packet up to the MTU (rather than requiring that packets of size 253, 254 and 255 be padded to at least 256 bytes).

SANA-II device drivers for ARCNET should implement the old ARCNET packet headers. Driver users which wish to interoperate with platforms using the new software headers must add the new fields to the data to be sent and must process it for incoming data. A SANA-II driver which implemented the data link layer fragmentation internally (and advertised a large MTU) could be more efficient than requiring the driver user to do it. This would make driver writing more difficult and reduce interoperability, but if there is ever a demand for that extra performance, a new hardware type may be assigned by Amiga for SANA-II ARCNET device drivers which implement the new framing.

= Addressing =

In the SANA-II standard, network hardware addresses are stored in an array of ''n'' bytes. No meaning is ascribed by the standard to the contents of the array.

In case there exists a network which does not have an address field consisting of a number of bits not divisible by eight, add pad bits at the end of the bit stream. For example, if an address is ten bits long it will be stored like this:

<pre>
98765432 10PPPPPP
BYTE 0 BYTE 1
</pre>

Where the numerals are bit numbers and "P" is a pad (ignored) bit.

Driver users which do not implement the bit shifting necessary to use a network with such addressing (if one exists) should at least check the number of significant bits in the address field (returned from the device's S2_DEVICEQUERY function) to make sure that it is evenly divisible by eight.

Driver users will map hardware addresses to protocol addresses in a protocol and hardware dependent manner, as described by the relevant standards (i.e., RFC 826 for TCP/IP over Ethernet, RFC 1201 or RFC 1051 for TCP/IP over ARCNET). Some protocols will always use the same mapping on all hardware, but other protocols will have particular address mapping schemes for some particular hardware and a reasonable default for other (unknown) hardware.

Some SANA-II devices will have "hardware addresses" which aren't really hardware addresses. As an example, consider ''PPP'' (Point-to-Point Protocol). PPP is a standard for transmitting IP packets over a serial line. It uses IP addresses negotiated during the establishment of a connection. In a SANA-II driver implementation of PPP, the driver would negotiate the address at S2_CONFIGINTERFACE. Thus, the address in SrcAddr returned by the device on an S2_CONFIGINTERFACE (or in a subsequent S2_GETSTATIONADDRESS) will be a protocol address, not a true hardware address.

'''Note:''' Some hardware always uses a ROM hardware address. Other hardware which has a ROM address or is configurable with DIP switches may be overridden by software. Some hardware always dynamically allocates a new hardware address at initialization. See "Configuration" for details on how this is handled by driver writers and by driver users.

= Hardware Type =

The HardwareType returned by the device's S2_DEVICEQUERY function is necessary for those protocols whose standards require different behavior on different hardware. It is also useful for determining appropriate packet type numbers to use with the device. The HardwareType values already issued for standard network hardware are the same as those in RFC 1060 (assigned numbers). Hardware developers implementing networks without a SANA-II hardware number must contact the AmigaOS development team to have a new hardware type number assigned. Driver users should all have reasonable defaults which can be used for hardware with which they are not familiar.

= Errors =

The SANA-II extended IORequest structure (struct IOSana2Req) includes both the ios2_Error and ios2_WireError fields. Driver users must always check IOSana2Reqs on return for an error in ios2_Error. ios2_Error will be zero if no error occurred, otherwise it will contain a value from <exec/errors.h> or <devices/sana2.h>. If there was an error, there may be more specific information in ios2_WireError. Drivers are required to fill in the WireError if there is an applicable error code.

Error codes are #define'd in the "defined errors" sections of the file <devices/sana2.h>: 

{| class="wikitable"
! IOSana2Req S2io_Error field
! Description
|-
| S2ERR_NO_RESOURCES
| Insufficient resources available.
|-
| S2ERR_BAD_ARGUMENT
| Noticeably bad argument.
|-
| S2ERR_BAD_STATE
| Command inappropriate for current state.
|-
| S2ERR_BAD_ADDRESS
| Noticeably bad address.
|-
| S2ERR_MTU_EXCEEDED
| Write data too large.
|-
| S2ERR_NOT_SUPPORTED
| Command is not supported by this driver. This is similar to IOERR_NOCMD as defined in <exec/errors.h> but S2ERR_NOT_SUPPORTED indicates that the requested command is a valid SANA-II command and that the driver does not support it because the hardware is incapable of supporting it (e.g., S2_MULTICAST). Note that IOERR_NOCMD is still valid for reasons other than a lack of hardware support (i.e., commands which are no-ops in a SANA-II driver).
|-
| S2ERR_SOFTWARE
| Software error of some kind.
|-
| S2ERR_OUTOFSERVICE
| When a hardware device is taken off-line, any pending requests are returned with this error.
|}

See also the standard errors in <exec/errors.h>.

{| class="wikitable"
! IOSana2Req S2io_WireError field
! Description
! Value
|-
| S2WERR_NOT_CONFIGURED
| Command requires unit to be configured.
|-
| S2WERR_UNIT_ONLINE
| Command requires that the unit be off-line.
|-
| S2WERR_UNIT_OFFLINE
| Command requires that the unit be on-line.
|-
| S2WERR_ALREADY_TRACKED
| Protocol is already being tracked.
|-
| S2WERR_NOT_TRACKED
| Protocol is not being tracked.
|-
| S2WERR_BUFF_ERROR
| Buffer management function returned an error.
|-
| S2WERR_SRC_ADDRESS
| Problem with the source address field.
|-
| S2WERR_DST_ADDRESS
| Problem with destination address field.
|-
| S2WERR_BAD_BROADCAST
| Problem with an attempt to broadcast.
|-
| S2WERR_BAD_MULTICAST
| Problem with an attempt to multicast.
|-
| S2WERR_MULTICAST_FULL
| Multicast address list full.
|-
| S2WERR_BAD_EVENT
| Event specified is unknown.
|-
| S2WERR_BAD_STATDATA
| The ios2_StatData pointer or the data it points to failed a sanity check.
|-
| S2WERR_IS_CONFIGURED
| Attempt to reconfigure the unit.
|-
| S2WERR_NULL_POINTER
| A NULL pointer was detected in one of the arguments. S2ERR_BAD_ARGUMENT should always be the S2ERR.
|-
| S2WERR_UNIT_DISCONNECTED
| This error code is a counterpart to <tt>S2WERR_UNIT_OFFLINE</tt>. It indicates that the associated command could not be executed because the link layer is not connected.
| 19
|-
| S2WERR_UNIT_CONNECTED
| This error code is a counterpart to <tt>S2WERR_UNIT_ONLINE</tt>. It indicates that the associated command could not be executed because the link layer is already connected.
| 20
|-
| S2WERR_INVALID_OPTION
| This error code indicates that an option, such as passed by the <tt>S2_CONNECT</tt> command, is not acceptable. The option's value may be out of range or may not match the syntax specifications. To indicate which option that may be, a different mechanism '''must''' be used; a simple indication that something was wrong is '''not sufficient'''.
| 21
|-
| S2WERR_MISSING_OPTION
| This error code indicates that a mandatory option, such as passed by the <tt>S2_CONNECT</tt> command, is not present. To indicate which option that may be, a different mechanism '''must''' be used; a simple indication that something was wrong is '''not sufficient'''.
| 22
|-
| S2WERR_AUTHENTICATION_FAILED
| Some drivers run protocols that require them to authenticate to a server. That process may fail. This wire error code is to indicate this fact.
| 23
|}

= Standard Commands =

See the "SANA-II network device driver Autodocs" for full details on each of the SANA-II device commands. Extended commands are explained in the sections below.

Many of the Exec device standard commands are no-ops in SANA-II devices, but this may not always be the case. For example, CMD_RESET might someday be used for dynamically reconfiguring hardware. This should present no compatibility problems for properly written drivers.

== Broadcast and Multicast ==

Some hardware supports broadcast and/or multicast. A broadcast is a packet sent to all other machines. A multicast is a packet sent to a set of machines. Drivers for hardware which does not allow broadcast or multicast will return ios2_Error S2ERR_NOT_SUPPORTED as appropriate.

To send a broadcast, use S2_BROADCAST instead of CMD_WRITE. Broadcasts are received just like any other packets (using a CMD_READ for the appropriate packet type).

To send a multicast, use S2_MULTICAST instead of CMD_WRITE. The device keeps a list of addresses that want to receive multicasts. You add a receiver's address to this list by using S2_ADDMULTICASTADDRESS. The receiver then posts a CMD_READ for the type of packet to be received. Some SANA-II devices which support multicast may have a limit on the number of addresses that can simultaneously wait for packets. Always check for an S2WERR_MULTICAST_FULL error return when adding a multicast address.

Note that when the device adds a multicast address, it is usually added for all users of the device, not just the driver user which called S2_ADDMULTICASTADDRESS. In other words, received multicast packets will fill a read request of the appropriate type regardless of whether the requesting driver user is the same one which added the multicast address.

In general, driver users should not care how received packets were sent (normally or broadcast/multicast), only that it was received. If a driver user really must know, however, it can check for SANA2IOB_BCAST and/or SANA2IOB_MCAST in the ios2_Flags field.

Drivers should keep a count for the number of opens on a multicast address so that they don't actually remove it until it has been S2_DELMULTICASTADDRESS'd as many times as it has been S2_ADDMULTICASTADDRESS'd.

== Stats ==

There are many statistics which may be very important to someone trying to debug, tune or optimize a protocol stack, as well as to the end user who may need to tune parameters or investigate a problem. Some of these statistics can only be kept by the SANA-II driver, thus there are several required and optional statistics and commands for this purpose.

S2_TRACKTYPE tells the device driver to gather statistics for a particular packet type. S2_UNTRACKTYPE tells it to stop (keeping statistics by type causes the driver to use additional resources). S2_GETTYPESTATS returns any statistics accumulated by the driver for a type being tracked (stats are lost when a type is S2_UNTRACKTYPE'd). Drivers are required to implement the functionality of type tracking. The stats are returned in a struct Sana2PacketTypeStats:

<syntaxhighlight lang="C" line>
struct Sana2PacketTypeStats
{
ULONG PacketsSent;
ULONG PacketsReceived;
ULONG BytesSent;
ULONG BytesReceived;
ULONG PacketsDropped;
};
</syntaxhighlight>

; PacketsSent
: Number of packets of a particular type sent.
; PacketsReceived
: Number of packets of a particular type that satisfied a read command.
; BytesSent
: Number of bytes of data sent in packets of a particular type.
; BytesReceived
: Number of bytes of data of a particular packet type that satisfied a read command.
; PacketsDropped
: Number of packets of a particular type that were received while there were no pending reads of that packet type.

returns global statistics kept by the driver. Drivers are required to keep all applicable statistics. Since all are applicable to most hardware, most drivers will maintain all statistics. The stats are returned in a struct Sana2DeviceStats:

<syntaxhighlight lang="C" line>
struct Sana2DeviceStats
{
ULONG PacketsReceived;
ULONG PacketsSent;
ULONG BadData;
ULONG Overruns;
ULONG UnknownTypesReceived;
ULONG Reconfigurations;
struct timeval LastStart;
};
</syntaxhighlight>

; PacketsReceived
: Number of packets that this unit has received.
; PacketsSent
: Number of packets that this unit has sent.
; BadData
: Number of bad packets received (i.e., hardware CRC failed).
; Overruns
: Number of packets dropped due to insufficient resources available in the network interface.
; UnknownTypeReceived
: Number of packets received that had no pending read command with the appropriate packet type.
; Reconfigurations
: Number of network reconfigurations since this unit was last configured.
; LastStart
: The time when this unit last went on-line.

returns any special statistics kept by a particular driver. Each new wire type will have a set of documented, required statistics for that wire type and a standard set of optional statistics for that wire type (optional because they might not be available from all hardware). The data returned by S2_GETSPECIALSTATS will require wire-specific interpretation. See <devices/sana2specialstats.h> on page devicessana2specialstatspage for currently defined special statistics. The statistics are returned in the following structures:

<syntaxhighlight lang="C" line>
struct Sana2SpecialStatRecord
{
ULONG Type;
ULONG Count;
char * String;
};
</syntaxhighlight>

; Type
: Statistic identifier.
; Count
: Statistic itself.
; String
: An identifying, null-terminated string for the statistic. Should be plain ASCII with no formatting characters.

<syntaxhighlight lang="C" line>
struct Sana2SpecialStatHeader
{
ULONG RecordCountMax;
ULONG RecordCountSupplied;
struct Sana2SpecialStatRecord[RecordCountMax];
};
</syntaxhighlight>

; RecordCountMax
: There is space for this many records into which statistics may be placed.
; RecordCountSupplied
: Number of statistic records supplied.

is not, strictly speaking, a statistical function. It is a request to read any packet of a type for which there is no outstanding CMD_READ. S2_READORPHAN might be used in the same manner as many statistics, though, such as to determine what packet types are causing overruns, etc.

== Configuration ==

The device driver needs to configure the hardware before using it. The driver user must know some network hardware parameters (hardware address and MTU, for example) when using it. These commands address those needs.

When a driver user is initialized, it should try to S2_CONFIGINTERFACE even though an interface can only be configured once and someone else may have done it. Before you call S2_CONFIGINTERFACE, first call S2_GETSTATIONADDRESS to determine the factory address (if any). Also provide for user-override of the factory address (that address may be optional and the user may need to override it). When S2_CONFIGINTERFACE returns, check the ios2_SrcAddr for the actual address the hardware has been configured with. This is because some hardware (or serial line standards such as PPP) always dynamically allocates an address at initialization.

Driver users will want to use S2_DEVICEQUERY to determine the MTU and other characteristics of the network. The structure returned from S2_DEVICEQUERY is defined as:

<syntaxhighlight lang="C" line>
struct Sana2DeviceQuery
{
/*
** Standard information
*/
ULONG SizeAvailable; /* bytes available */
ULONG SizeSupplied; /* bytes supplied */
LONG DevQueryFormat; /* this is type 0 */
LONG DeviceLevel; /* this document is level 0 */

/*
** Common information
*/
UWORD AddrFieldSize; /* address size in bits */
ULONG MTU; /* maximum packet data size */
LONG BPS; /* line rate (bits/sec) */
LONG HardwareType; /* what the wire is */
ULONG RawMTU; /* maximum raw packet data size */

/*
** Format specific information
*/
};
</syntaxhighlight>

; SizeAvailable
: Size, in bytes, of the space available in which to place device information. This includes both size fields.
; SizeSupplied
: Size, in bytes, of the data supplied.
; DevQueryFormat
: The format defined here is format 0.
; DeviceLevel
: This spec defines level 0.
; AddrFieldSize
: The number of bits in an interface address.
; MTU
: Maximum Transmission Unit, the size, in bytes, of the maximum packet size, not including header and trailer information.
; BPS
: Best guess at the raw line rate for this network in bits per second.

; HardwareType
: Specifies the type of network hardware the driver controls.

; RawMTU
: The <tt>RawMTU</tt> member is new as of SANA-II Revision 4. Devices which do not know and support this structure member may fill in the <tt>Sana2DeviceQuery</tt> structure only up to and including the <tt>HardwareType</tt> member.

: In this context 'raw' means the number of bytes that are available for reading and writing when using the <tt>SANA2IOB_RAW</tt> flag with a <tt>CMD_READ</tt>/<tt>CMD_WRITE</tt> request on a device that supports these access methods. Currently, software developers can only make assumptions on how many bytes might comprise the 'raw' MTU by checking the <tt>Sana2DeviceQuery.HardwareType</tt> member and hoping that the driver supports raw <tt>CMD_READ</tt>/<tt>CMD_WRITE</tt> access.

: Devices which know and support the <tt>RawMTU</tt> member must fill it with a well-defined value. For Amiga Ethernet drivers, that value would be 1514, which is the standard MTU value of 1500 bytes plus the size of the Ethernet frame header, as per RFC894 (six bytes for the destination address, six bytes for the source address and two bytes for the frame type; the eight byte preamble and the terminating four byte CRC value are typically not under the control of the driver). Drivers which do not support raw read or write access must set the <tt>RawMTU</tt> member to zero.

: If the <tt>RawMTU</tt> member is not provided, all bets are off and the application software must fall back to making estimates based upon the hardware type and the raw frame types it wishes to read and write. Ultimatively, the driver itself must decide whether it can accept raw read and write commands (or has to reject them with <tt>S2ERR_NOT_SUPPORTED</tt>) and whether the raw packet size is still covered by the underlying hardware MTU (or must be rejected with <tt>S2ERR_MTU_EXCEEDED</tt>).

: A word of warning: a little testing with various Ethernet hardware drivers has revealed that the A2065 driver <tt>a2065.device</tt> does not handle the <tt>S2_DEVICEQUERY</tt> command properly if the <tt>Sana2DeviceQuery</tt> structure provided is larger than 30 bytes. In other words, the command will fail if the proposed <tt>RawMTU</tt> member is present in the query data structure to be filled in.

== On-line ==

In order to run hardware tests on an otherwise live system, the S2_OFFLINE command allows the SANA-II device driver to be "turned off" until the tests are complete and an S2_ONLINE is sent to the driver. S2_ONLINE causes the interface to re-configure and re-initialize. Any packets destined for the hardware while the device is off-line will be lost. All pending and new requests to the driver shall be returned with S2ERR_OUTOFSERVICE when a device is off-line.

All driver users must understand that any IO request may return with S2ERR_OUTOFSERVICE because the driver is off-line (any other program may call S2_OFFLINE to make it so). In such an event, the driver will usually want to wait until the unit comes back on-line (for the program which called S2_OFFLINE to call S2_ONLINE). It may do this by calling S2_ONEVENT to wait for S2EVENT_ONLINE. S2_ONEVENT allows the driver user to wait on various events.

A driver must track events, but may not distinguish between some types of events. Drivers return S2_ONEVENT with S2ERR_NOT_SUPPORTED and S2WERR_BAD_EVENT for unsupported events. One error may cause more than one event (see below). Errors which seem to have been caused by a malformed or unusual request should not generally trigger an event. 

{| class="wikitable"
! Event type
! Description
|-
| S2EVENT_ERROR
| Return when any error occurs.
|-
| S2EVENT_TX
| Return on any transmit error (always an error).
|-
| S2EVENT_RX
| Return on any receive error (always an error).
|-
| S2EVENT_ONLINE
| Return when unit goes on-line or return immediately if unit is already on-line (not an error).
|-
| S2EVENT_OFFLINE
| Return when unit goes off-line or return immediately if unit is already off-line (not an error.)
|-
| S2EVENT_BUFF
| Return on any buffer management function error (always an error).
|-
| S2EVENT_HARDWARE
| Return when any hardware error occurs (always an error, may be a S2EVENT_TX or S2EVENT_RX, too).
|-
| S2EVENT_SOFTWARE
| Return when any software error occurs (always an error, may be a S2EVENT_TX or S2EVENT_RX, too).
|-
| S2EVENT_CONFIGCHANGED
| Return when client-visible configuration information changes (not an error).
|-
| S2EVENT_CONNECT
| Return when the driver has successfully established a link layer connection (not an error).
|-
| S2EVENT_DISCONNECT
| Return when the driver has closed the link layer connection previously established by the S2_CONNECT command (not an error).
|}

=== S2EVENT_CONFIGCHANGED ===

For drivers such as those which implement the <tt>S2_GETPEERADDRESS</tt> and <tt>S2_GETDNSADDRESS</tt> commands it is vital that such changes can take place and be noticed by the client software. For this purpose a new event type is introduced, to be used with the SANA-II <tt>S2_ONEVENT</tt> command, using the following definition:

<tt>#define S2EVENT_CONFIGCHANGED (1L<<8)</tt>

This event should be triggered whenever client-visible configuration information changes, as can be queried via the <tt>S2_DEVICEQUERY</tt>, <tt>S2_GETSTATIONADDRESS</tt>, <tt>S2_GETSPECIALSTATS</tt>, <tt>S2_GETGLOBALSTATS</tt>, <tt>S2_GETPEERADDRESS</tt> and <tt>S2_GETDNSADDRESS</tt> commands. Here is a short list of what could change:

# S2_DEVICEQUERY: <tt>AddrFieldSize</tt>, <tt>MTU</tt>, <tt>BPS</tt>
# S2_GETSTATIONADDRESS: <tt>ios2_SrcAddr</tt>
# S2_GETGLOBALSTATS: <tt>Reconfigurations</tt>, <tt>LastStart</tt>
# S2_GETPEERADDRESS: <tt>ios2_SrcAddr</tt>, <tt>ios2_DstAddr</tt>
# S2_GETDNSADDRESS: <tt>ios2_SrcAddr</tt>, <tt>ios2_DstAddr</tt>

The purpose of this event '''is not''' to post a notification whenever another byte or event counter has changed so that a monitoring program may update its display. The purpose '''is''' to convey to the client software that an important device configuration option has changed and that it is supposed to react and adapt to it. For example, a TCP/IP stack may, upon learning that a device's IP address has changed, rebuild its routing table.

Since the <tt>S2EVENT_CONFIGCHANGED</tt> event may arrive at any time and does not indicate what exactly has changed, application software should query the information it expects to change during its life time, and keep a copy of it around for later reference. When the <tt>S2EVENT_CONFIGCHANGED</tt> event arrives, it can compare the contents of the copy against the current state of affairs and act according to the differences it finds.

=== S2EVENT_CONNECT ===

This event is a counterpart to <tt>S2EVENT_ONLINE</tt>, and is associated with the <tt>S2_CONNECT</tt> command. It has the following semantics:

<tt>#define S2EVENT_CONNECT (1L<<9) /* Driver has opened session */</tt>

The event is to be sent when the driver has successfully established a link layer connection.

=== S2EVENT_DISCONNECT ===

This event is a counterpart to <tt>S2EVENT_OFFLINE</tt>, and is associated with the <tt>S2_DISCONNECT</tt> command. It has the following semantics:

<tt>#define S2EVENT_DISCONNECT (1L<<10) /* Driver has closed session */</tt>

The event is to be sent when the driver has closed the link layer connection previously established by the <tt>S2_CONNECT</tt> command.

== S2_ONLINE and S2_OFFLINE ==

The <tt>S2_CONNECT</tt> and <tt>S2_DISCONNECT</tt> commands are somewhat related to the <tt>S2_ONLINE</tt> and <tt>S2_OFFLINE</tt> commands. How this relation works out shall be explained below. Note that the following text assumes that both the <tt>S2_CONNECT</tt>/<tt>S2_DISCONNECT</tt> and <tt>S2_ONLINE</tt>/<tt>S2_OFFLINE</tt> command pairs are implemented.

<tt>S2_CONNECT</tt> implies <tt>S2_ONLINE</tt> and, if successful, may report <tt>S2EVENT_ONLINE</tt> and <tt>S2EVENT_CONNECT</tt> events. If the unit is currently disconnected, but still online, only the <tt>S2EVENT_CONNECT</tt> event shall be sent. Invoking the <tt>S2_CONNECT</tt> command on a driver which is already connected must be rejected with <tt>ios2_Req.io_Error=S2ERR_BAD_STATE</tt> and <tt>ios2_WireError=S2WERR_UNIT_CONNECTED</tt>.

<tt>S2_DISCONNECT</tt> implies <tt>S2_OFFLINE</tt> and, if successful, may report <tt>S2EVENT_OFFLINE</tt> and <tt>S2EVENT_DISCONNECT</tt> events. If the unit is currently connected and offline, then only the <tt>S2EVENT_DISCONNECT</tt> event shall be sent. Invoking the <tt>S2_DISCONNECT</tt> command on a driver which is already disconnected must be rejected with <tt>ios2_Req.io_Error=S2ERR_BAD_STATE</tt> and <tt>ios2_WireError=S2WERR_UNIT_DISCONNECTED</tt>.

<tt>S2_OFFLINE</tt> may be used after the <tt>S2_CONNECT</tt> has successfully connected the unit. In this case the driver will release control over the link layer and report the <tt>S2EVENT_OFFLINE</tt> event. The connection established using the <tt>S2_CONNECT</tt> will, however, persist.

<tt>S2_ONLINE</tt> may be used after <tt>S2_CONNECT</tt> has successfully connected the unit and the <tt>S2_OFFLINE</tt> was used. In this case the driver will again try to obtain control over the link layer and report the <tt>S2EVENT_ONLINE</tt> event if successful.

If the <tt>S2_CONNECT</tt> command was never successfully executed, then the commands <tt>S2_ONLINE</tt> and <tt>S2_OFFLINE</tt> must be rejected with <tt>ios2_Req.io_Error=S2ERR_BAD_STATE</tt> and <tt>ios2_WireError=S2WERR_UNIT_DISCONNECTED</tt>.

== Wireless (IEEE 802.11) ==

Several new commands have been added to the SANA-II API to facilitate use of IEEE 802.11 wireless network devices in client and ad-hoc modes. The new commands are split into two overlapping sets. One set needs to be implemented by drivers for Soft-MAC wireless devices, while the other is implemented for Hard-MAC devices.

{| class="wikitable"
! Soft-MAC commands
|-
| S2_SETOPTIONS
|-
| S2_SETKEY
|-
| S2_WRITEMGMT
|-
| S2_READMGMT
|}

{| class="wikitable"
! Hard-MAC commands
|-
| S2_SETOPTIONS
|-
| S2_SETKEY
|-
| S2_GETNETWORKS
|-
| S2_GETNETWORKINFO
|-
| S2_GETSIGNALQUALITY
|}

=== sana2wireless.h ===

<syntaxhighlight lang="C" line>
#ifndef DEVICES_SANA2WIRELESS_H
#define DEVICES_SANA2WIRELESS_H

#include <exec/types.h>
#include <utility/tagitem.h>

/* Constants */
/* ========= */

/* Tags to get and set information */

#define S2INFO_SSID (TAG_USER + 0)
#define S2INFO_BSSID (TAG_USER + 1)
#define S2INFO_AuthTypes (TAG_USER + 2)
#define S2INFO_AssocID (TAG_USER + 3)
#define S2INFO_Encryption (TAG_USER + 4)
#define S2INFO_PortType (TAG_USER + 5)
#define S2INFO_BeaconInterval (TAG_USER + 6)
#define S2INFO_Channel (TAG_USER + 7)
#define S2INFO_Signal (TAG_USER + 8)
#define S2INFO_Noise (TAG_USER + 9)
#define S2INFO_Capabilities (TAG_USER + 10)
#define S2INFO_InfoElements (TAG_USER + 11)
#define S2INFO_WPAInfo (TAG_USER + 12)
#define S2INFO_Band (TAG_USER + 13)
#define S2INFO_DefaultKeyNo (TAG_USER + 14)

/* Wireless Commands */

#define S2_GETSIGNALQUALITY 0xc010
#define S2_GETNETWORKS 0xc011
#define S2_SETOPTIONS 0xc012
#define S2_SETKEY 0xc013
#define S2_GETNETWORKINFO 0xc014
#define S2_READMGMT 0xc015
#define S2_WRITEMGMT 0xc016
#define S2_GETRADIOBANDS 0xc017

/* Encryption types */

#define S2ENC_NONE 0
#define S2ENC_WEP 1
#define S2ENC_TKIP 2
#define S2ENC_CCMP 3

/* Radio modes */

#define S2BAND_A 0
#define S2BAND_B 1
#define S2BAND_G 2
#define S2BAND_N 3

/* Network topologies */

#define S2PORT_MANAGED 7
#define S2PORT_ADHOC 8

/* Structures */
/* ========== */

/* Structure for returning signal quality */

struct Sana2SignalQuality
{
LONG SignalLevel; /* signal level in dBm */
LONG NoiseLevel; /* noise level in dBm */
};

#endif
</syntaxhighlight>

= Driver requirements =

This section is an attempt to clarify parts of the specification and to lay down a few rules that every SANA-II driver must follow.

* A driver that does not use a broadcast medium, such as Ethernet, must not implement the <tt>S2_BROADCAST</tt> command. Likewise, if no multicast mechanism is supported, the <tt>S2_MULTICAST</tt> must not be implemented either.

* SANA-II standard commands which the driver does not implement must be rejected with the <tt>IOERR_NOCMD</tt> error code. Commands that are implemented, but which cannot perform the requested services, must be rejected with the <tt>S2ERR_NOT_SUPPORTED</tt> error code. The difference between the two cases is in when the decision is made whether a command can be handled or not. Which commands should return <tt>IOERR_NOCMD</tt> is decided upon at the time the driver is designed and implemented. At this stage the implementer knows for sure which capabilities the driver will have and which it will not have. Commands which the driver will never be able to execute will be made to return the <tt>IOERR_NOCMD</tt> error code. If the decision whether a command can be executed is made only at run time, by evaluating the conditions under which a command can be executed, then the error code <tt>S2ERR_NOT_SUPPORTED</tt> should be returned in case of failure.

* It must be possible to open the driver with an ordinary <tt>struct IOStdReq</tt>. This is necessary for the NewStyleDevices query command to work. In the command dispatcher, the driver must verify that all SANA-II commands are invoked with a proper size <tt>struct IOSana2Req</tt> I/O request. If the I/O request is shorter (as can be verified by looking at the embedded Message's <tt>mn_Length</tt> member), the command must be rejected with <tt>ios2_Req.io_Error=IOERR_BADLENGTH</tt>.

* A driver must implement the NewStyleDevices <tt>NSCMD_DEVICEQUERY</tt> command, in conformance with the NSD specification 1.6 or newer. The motivation for this is to have a mechanism available for probing the capabilities of the driver, and the supported command set can provide for vital clues. In this context, the absence of the <tt>S2_BROADCAST</tt> command would suggest that the driver cannot send or receive broadcast messages.

* A driver that does not allow its station address to be set with the <tt>S2_CONFIGINTERFACE</tt> command may silently ignore the command (returning it without setting an error condition) and even pretend that it can be configured more than once.

* In response to the <tt>S2_DEVICEQUERY</tt>, <tt>S2_GETSPECIALSTATS</tt> and <tt>S2_GETGLOBALSTATS</tt> commands a driver may return information that is not entirely correct if it has to go online before it can provide for the correct data. For example, the maximum transmission unit for PPP is a number in the range of [1..1500] which is negotiated during the protocol configuration process. It is unlikely that numbers greater than 1500 will be used, yet it is still not impossible. Since the actual number will be known only after the driver has configured the protocol, the MTU value returned before the session was opened can differ from the MTU value valid after it has been opened. A driver should therefore attempt to return 'safe' defaults in place of information that is unavailable at the time it is queried. The 'safe' values shall be set up to allow the driver to work even if the protocol stack is not aware of later changes to those values. Beware of zero-length buffer sizes or time intervals that may cause client software to perform zero-length memory allocations or divisions by zero.

* SANA-II assigns packet type numbers according to the underlying transport media. For example, Ethernet uses packet type 2048 for IP frames. No such packet type definition exists for PPP yet, which is why this standard proposes to assign packet type 31 for IP packets transmitted via PPP. To simplify client software configuration, drivers may treat packet type 2048 as equivalent to the packet number associated with IP frames. This association is permitted only if it does not introduce ambiguity. For example, this association would not be permitted if the driver would receive and transmit IP packets in two different frame types or if the driver already associates packet type 2048 with non-IP packets.

= Driver Installation =

The standard system location for SANA-II network device driver is in a directory called "Networks" which exists in the "DEVS:" directory.

Example:

<blockquote>
DEVS:Networks/eth3com.device
</blockquote>

This is the official location for the drivers. It may be necessary for your install program/script to create this directory if it doesn't exist in a user's system.

= Unresolved Issues =

* Unfortunately, it isn't possible to completely isolate network protocols from the hardware they run on. Hardware types and addressing both remain somewhat hardware-dependent in spite of our efforts. See the "Packet Type" section for an explanation of how packet types are handled and why protocols cannot be isolated from them. See the "Addressing" section for an explanation of how addressing is handled any why protocols cannot be isolated from it.

* Additionally, there are at least two cases where a hardware type has multiple framing methods in use (ethernet/802.3 and arcnet/(Novell) "ARCNET Packet Header Definition Standard"). In both cases, software which must interoperate with other platforms on this hardware may need to be aware of the distinctions and may have to do extra processing in order to use the appropriate frame type. See the sections on "Ethernet Packet Types" and on "ARCNET frames" for more details.

* Protocols like PPP can provide both for IPv4 and IPv6 addresses that should be used by the local client, the peer or any of the domain name servers. While the two addressing families are interoperable, there is a problem in how the driver should report them. Can you assume 128 bit addresses and encapsulate 32 bit addresses in them? If so, how do you make sure that the address format is unambiguous?

* Currently, only the device's hardware type provides a clue as to what packet type responds to which protocol transported via the link. For Ethernet, IP packets are encapsulated in type 2048 frames, PPP encapsulates IP packets in type 31 frames, Arcnet can use type 240 or 212. Matching a protocol with a frame type is not an easy process which could be handled more elegantly.

* How to extend the <tt>Sana2DeviceQuery</tt> structure in the future? The current layout separates standard, common and format specific information, but there is no hint as to where which each section starts and where the next begins. Now that there is a proposal to add a new field to the common section, how would you add fields to the format specific section?

= SANA-II network device driver Autodocs =

== AbortIO ==

<pre>
NAME
AbortIO -- Remove an existing device request.

SYNOPSIS
error = AbortIO(Sana2Req)
D0 A1

LONG AbortIO(struct IOSana2Req *);

FUNCTION
This is an exec.library call.

This function aborts an ioRequest. If the request is active, it may or
may not be aborted. If the request is queued it is removed. The
request will be returned in the same way as if it had normally
completed. You must WaitIO() after AbortIO() for the request to
return.

INPUTS
Sana2Req - Sana2Req to be aborted.

RESULTS
error - Zero if the request was aborted, non-zero otherwise.
io_Error in Sana2Req will be set to IOERR_ABORTED
if it was aborted.

SEE ALSO
exec.library/AbortIO(), exec.library/WaitIO()
</pre>

== CloseDevice ==

<pre>
NAME
CloseDevice -- Close the device.

SYNOPSIS
CloseDevice(Sana2Req)
A1

void CloseDevice(struct IOSana2Req *);

FUNCTION
This function is called by exec.library CloseDevice().

This function performs whatever cleanup is required at device closes.

Note that all IORequests MUST be complete before closing. If any are
pending, your program must AbortIO() then WaitIO() each outstanding
IORequest to complete them.

INPUTS
Sana2Req - Pointer to IOSana2Req initialized by OpenDevice().

SEE ALSO
exec.library/CloseDevice(), exec.library/OpenDevice()
</pre>

== CMD_CLEAR ==

<pre>
NAME
CMD_CLEAR -- Clear internal network interface read buffers.

FUNCTION
There are no device internal buffers, so CMD_CLEAR does not apply to
this class of device.

IO REQUEST
ios2_Command - CMD_CLEAR.

RESULTS
ios2_Error - IOERR_NOCMD.
</pre>

== CMD_FLUSH ==

<pre>
NAME
CMD_FLUSH -- Clear all queued I/O requests for the SANA-II device.

FUNCTION
This command aborts all I/O requests in both the read and write
request queues of the device. All pending I/O requests are
returned with an error message (IOERR_ABORTED). CMD_FLUSH does not
affect active requests.

IO REQUEST
ios2_Command - CMD_FLUSH.

RESULTS
ios2_Error - Zero if successful; non-zero otherwise.
</pre>

== CMD_INVALID ==

<pre>
NAME
CMD_INVALID -- Return with error IOERR_NOCMD.

FUNCTION
This command causes device driver to reply with an error IOERR_NOCMD
as defined in <exec/errors.h> indicating the command is not supported.

IO REQUEST
ios2_Command - CMD_INVALID.

RESULTS
ios2_Error - IOERR_NOCMD.

BUGS
Not known to be useful.
</pre>

== CMD_READ ==

<pre>
NAME
CMD_READ -- Get a packet from the network.

FUNCTION
Get the next packet available of the requested packet type. The data
copied (via a call to the requestor-provided CopyToBuffer function)
into ios2_Data is normally the Data Link Layer packet data only. If
bit SANA2IOB_RAW is set in ios2_Flags, then the entire physical frame
will be returned.

Unlike most Exec devices, SANA-II device drivers do not have internal
buffers. If you wish to read data from a SANA-II device you should
have multiple CMD_READ requests pending at any given time. The
functions provided by you the requestor will be used for any incoming
packets of the type you've requested. If no read requests are
outstanding for a type which comes in and no read_orphan requests are
outstanding, the packet will be lost.

IO REQUEST
ios2_Command - CMD_READ
ios2_Flags - Supported flags are:
SANA2IOB_RAW
SANA2IOB_QUICK
ios2_PacketType - Packet type desired.
ios2_Data - Abstract data structure to hold packet data.

RESULTS
ios2_Error - Zero if successful; non-zero otherwise.
ios2_WireError - More specific error number.
ios2_Flags - The following flags may be returned:
SANA2IOB_RAW
SANA2IOB_BCAST
SANA2IOB_MCAST
ios2_SrcAddr - Source interface address of packet.
ios2_DstAddr - Destination interface address of packet.
ios2_DataLength - Length of packet data.
ios2_Data - Abstract data structure which packet data is
contained in.

NOTES
The driver may not directly examine or modify anything pointed to by
ios2_Data. It *must* use the requester-provided functions to access
this data.

SEE ALSO
S2_READORPHAN, CMD_WRITE, any_protocol/CopyToBuffer
</pre>

== CMD_RESET ==

<pre>
NAME
CMD_RESET -- Reset the network interface to initialized state.

FUNCTION
Currently, SANA-II devices can only be configured once (with
CMD_CONFIGINTERFACE) and cannot be re-configured, hence,
CMD_RESET does not apply to this class of device.

IO REQUEST
ios2_Command - CMD_RESET.

RESULTS
ios2_Error - IOERR_NOCMD.
</pre>

== CMD_START ==

<pre>
NAME
CMD_START -- Restart device operation.

FUNCTION
There is no way for the driver to keep queuing requests without
servicing them, so CMD_STOP does not apply to this class of device.
S2_OFFLINE and S2_ONLINE do perform a similar function to CMD_STOP
and CMD_START

IO REQUEST
ios2_Command - CMD_START.

RESULTS
ios2_Error - IOERR_NOCMD.

SEE ALSO
S2_ONLINE, S2_OFFLINE
</pre>

== CMD_STOP ==

<pre>
NAME
CMD_STOP -- Pause device operation.

FUNCTION
There is no way for the driver to keep queuing requests without
servicing them, so CMD_STOP does not apply to this class of device.
S2_OFFLINE and S2_ONLINE do perform a similar function to CMD_STOP
and CMD_START

IO REQUEST
ios2_Command - CMD_STOP.

RESULTS
ios2_Error - IOERR_NOCMD.

NOTES

SEE ALSO
S2_ONLINE, S2_OFFLINE
</pre>

== CMD_UPDATE ==

<pre>
NAME
CMD_UPDATE -- Force packets out to device.

FUNCTION
Since there are no device internal buffers, CMD_UPDATE does not
apply to this class of device.

IO REQUEST
ios2_Command - CMD_UPDATE.

RESULTS
ios2_Error - IOERR_NOCMD.
</pre>

== CMD_WRITE ==

<pre>
NAME
CMD_WRITE -- Send packet to the network.

FUNCTION
This command causes the packet to be sent to the specified network
interface. Normally, appropriate packet header and trailer information
will be added to the packet data when it is sent. If bit SANA2IOB_RAW
is set in io_Flags, then the ios2_Data is assumed to contain an entire
physical frame and will be sent (copied to the wire via
CopyFromBuffer() unmodified.

Note that the device should not check to see if the destination
address is on the local hardware. Network protocols should realize
that the packet has a local destination long before it gets to a
SANA-II driver.

IO REQUEST
ios2_Command - CMD_WRITE.
ios2_Flags - Supported flags are:
SANA2IOB_RAW
SANA2IOB_QUICK
ios2_PacketType - Packet type to send.
ios2_DstAddr - Destination interface address for this packet.
ios2_DataLength - Length of the Data to be sent.
ios2_Data - Abstract data structure which packet data is
contained in.

RESULTS
ios2_Error - Zero if successful; non-zero otherwise.
ios2_WireError - More specific error number.

NOTES
The driver may not directly examine or modify anything pointed to by
ios2_Data. It *must* use the requester-provided functions to access
this data.

SEE ALSO
CMD_READ, S2_BROADCAST, S2_MULTICAST, any_protocol/CopyFromBuffer
</pre>

== OpenDevice ==

<pre>
NAME
Open -- Request an opening of the network device.

SYNOPSIS
error = OpenDevice(unit, IOSana2Req, flags)
D0 D0 A1 D1

BYTE OpenDevice(ULONG, struct IOSana2Req *, ULONG);

FUNCTION
This function is called by exec.library OpenDevice().

This function performs whatever initialization is required per
device open and initializes the Sana2Req for use by the
device.

INPUTS
unit - Device unit to open.
Sana2Req - Pointer to IOSana2Req structure to be initialized by
the sana2.device.
flags - Supported flags are:
SANA2OPB_MINE
SANA2OPB_PROM
ios2_BufferManagement - A pointer to a tag list containing
pointers to buffer management functions.

RESULTS
error - same as io_Error
io_Error - Zero if successful; non-zero otherwise.
io_Device - A pointer to whatever device will handle the calls
for this unit. This pointer may be different
depending on what unit is requested.
ios2_BufferManagement - A pointer to device internal information
used to call buffer management functions.

NOTES
A SANA-II device must reject all open requests with a request
structure that is too short, e.g. an IOStdReq. A simple check of the
mn_Length field in the Message part of the request is needed to make
sure that a device does not dereference invalid data due to a wrong
device configuration.

A SANA-II device may open if no buffer management tags are provided to
make the configuration process and obtaining statistics easier. Buffer
management tags with a NULL value must be treated as not specified.
The device shall fail requests gracefully depending on the missing
tags in this case. Any malfunction is not acceptable.

SEE ALSO
exec.library/OpenDevice(), exec.library/CloseDevice()
</pre>

== S2_ADDMULTICASTADDRESS ==

<pre>
NAME
S2_ADDMULTICASTADDRESS -- Enable an interface multicast address.

FUNCTION
This command causes the device driver to enable multicast packet
reception for the requested address.

IO REQUEST
ios2_Command - S2_ADDMULTICASTADDRESS.
ios2_SrcAddr - Multicast address to enable.

RESULTS
ios2_Error - Zero if successful; non-zero otherwise.
ios2_WireError - More specific error number.

NOTES
Multicast addresses are added globally -- anyone using the device
may receive packets as a result of any multicast address which has
been added for the device.

Since multicast addresses are not "bound" to a particular packet type,
each enabled multicast address has an "enabled" count associated with
it so that if two protocols add the same multicast address and later
one removes it, it is still enabled until the second removes it.

SEE ALSO
S2_MULTICAST, S2_DELMULTICASTADDRESS
</pre>

== S2_BROADCAST ==

<pre>
NAME
S2_BROADCAST -- Broadcast a packet on network.

FUNCTION
This command works the same as CMD_WRITE except that it also performs
whatever special processing of the packet is required to do a
broadcast send. The actual broadcast mechanism is neccessarily
network/interface/device specific.

IO REQUEST
ios2_Command - S2_BROADCAST.
ios2_Flags - Supported flags are:
SANA2IOB_RAW
SANA2IOB_QUICK
ios2_PacketType - Packet type to send.
ios2_DataLength - Length of the Data to be sent.
ios2_Data - Abstract data structure which packet data is
contained in.

RESULTS
ios2_DstAddr - The contents of this field are to be
considered trash upon return of the IOReq.
ios2_Error - Zero if successful; non-zero otherwise.
This command can fail for many reasons and
is not supported by all networks and/or
network interfaces.
ios2_WireError - More specific error number.

NOTES
The DstAddr field may be trashed by the driver because this function
may be implemented by filling DstAddr with a broadcast address and
internally calling CMD_WRITE.

SEE ALSO
CMD_WRITE, S2_MULTICAST
</pre>

== S2_CONFIGINTERFACE ==

<pre>
NAME
S2_CONFIGINTERFACE -- Configure the network interface.

FUNCTION
This command causes the device driver to initialize the interface
hardware and to set the network interface address to the address in
ios2_SrcAddr. This command can only be executed once and, if
successful, will leave the driver and network interface fully
operational and the network interface in ios2_SrcAddr.

To set the interface address to the factory address, the network
management software must use GetStationAddress first and then call
ConfigInterface with the result. If there is no factory address then
the network software must pick an address to use.

Until this command is executed the device will not listen for any
packets on the hardware.

IO REQUEST
ios2_Command - S2_CONFIGINTERFACE.
ios2_Flags - Supported flags are:
SANA2IOB_QUICK
ios2_SrcAddr - Address for this interface.

RESULTS
ios2_Error - Zero if successful; non-zero otherwise.
ios2_WireError - More specific error number.
ios2_SrcAddr - Address of this interface as configured.

NOTES
Some networks have the interfaces choose a currently unused interface
address each time the interface is initialized. The caller must check
ios2_SrcAddr for the actual interface address after configuring the
interface.

SEE ALSO
S2_GETSTATIONADDRESS
</pre>

== S2_CONNECT ==

The driver model specified by the SANA-II standard really only covers networking hardware well. Software-only drivers, such as for dial-up networking, are, well, somehow mentioned in the standard, but they don't receive much attention. In particular, this means that a networking driver is assumed to be practically always attached to its link layer and no provisions exist to specify what kind of link layer that might be and how it might be accessed. This small oversight can probably be explained by the fact that at the time the SANA-II standard was adopted, dial-up networking had not yet gained the prominence it has today.

To bridge this gap, I propose a new command which will make a driver connect to its link layer and go online, which uses the following data structure:

<syntaxhighlight lang="C" line>
struct Sana2Connection
{
ULONG s2c_Size;
struct MinList s2c_Options;
struct Hook s2c_ErrorHook;
struct Hook s2c_ConnectHook;
struct Hook s2c_DisconnectHook;
STRPTR s2c_Login;
STRPTR s2c_Password;
};
</syntaxhighlight>

The individual structure members have the following purposes:

<tt>s2c_Size</tt>

The size of the entire data structure is stored here. This value '''must''' be >= 84. Smaller values '''must''' be rejected with <tt>ios2_Req.io_Error</tt>=<tt>IOERR_BADLENGTH</tt>. The purpose of <tt>s2c_Size</tt> is to allow for future expansion during which the structure may grow in size.

<tt>s2c_Options</tt>

This list contains options, to be used during the connection process. Each node has the following format:

<syntaxhighlight lang="C" line>
struct Sana2ConnectionOption
{
struct MinNode s2co_MinNode;
STRPTR s2co_Name;
STRPTR s2co_Value;
};
</syntaxhighlight>

The <tt>s2co_Name</tt> and <tt>s2co_Value</tt> entries point to <tt>NUL</tt>-terminated strings, which contain the name and the value of a parameter. ''Note that for numeric values, the respective number will be encoded in a text string.'' A number of parameters are reserved, which are [[#s2c_options|listed later]] in this text.

<tt>s2c_ErrorHook</tt>

This hook is called whenever an error message is to be reported during the connection/disconnection process. The hook function is invoked using the following parameters:

<pre>error_hook_func(hook,reserved,message);

VOID error_hook_func(struct Hook *hook,APTR reserved,
STRPTR message);</pre>
The <tt>reserved</tt> parameter '''must''' be <tt>NULL</tt>. The <tt>message</tt> parameter points to a <tt>NUL</tt>-terminated string. It '''must not''' be <tt>NULL</tt>.

Because the hook function may have to allocate memory, it '''must not''' be called from interrupt code.

<tt>s2c_ConnectHook</tt>

This hook is called when the link level device has been set up, but further initializations are necessary, such as telling a modem to dial out. The hook function is invoked with the following parameters:

<pre>
success = connect_hook_func(hook,reserved,s2cm);

BOOL connect_hook_func(struct Hook *hook,APTR reserved,
struct Sana2ConnectionMessage *s2cm);
</pre>

The <tt>reserved</tt> parameter '''must''' be <tt>NULL</tt>. The <tt>s2cm</tt> parameter points to a data structure, as follows:

<syntaxhighlight lang="C" line>
struct Sana2ConnectionMessage
{
ULONG s2cm_Size;
struct Sana2Connection * s2cm_Connection;
struct IORequest * s2cm_Request[2];
LONG s2cm_RequestType;
};
</syntaxhighlight>

In this structure, the members have the following purposes:

<tt>s2cm_Size</tt>

The size of this data structure; it '''must''' be at least 20 bytes in size. The purpose of <tt>s2cm_Size</tt> is to allow for future expansion, which may cause the size of this structure to grow.

<tt>s2cm_Connection</tt>

This points back to the <tt>Sana2Connection</tt> structure which the hook that was invoked with the <tt>Sana2ConnectionMessage</tt> is embedded in.

<tt>s2cm_Request</tt>

Here you will find two I/O requests which can be used for reading and writing data to the link layer. These pointers '''must not''' be <tt>NULL</tt> and they '''must''' refer to different I/O requests, it is not permitted to pass the same request twice.

The dialer can use these requests for communicating with the modem, but it is also permitted to clone these requests by creating new I/O requests of the same size, copying the original contents and filling in different reply ports.

There is a danger in that the hook code may not receive the right kind of I/O request, which is why the <tt>s2cm_RequestType</tt> field identifies the kind of device the requests were created for.

When the hook function returns, it '''must''' make sure that none of the I/O requests are still pending, i.e. asynchronous I/O '''must''' have been stopped.

<tt>s2cm_RequestType</tt>

This identifies the type of device the I/O requests passed in <tt>s2cm_Request</tt> were created for. Possible values for this entry come from the New Style Device specification, e.g. <tt>NSDEVTYPE_SERIAL</tt> for a <tt>serial.device</tt>-like device or <tt>NSDEVTYPE_SANA2</tt> for a networking driver.

The hook function '''must''' return <tt>TRUE</tt> if the connection could be established, and <tt>FALSE</tt> otherwise. Note that it is ''not'' sufficient to just return <tt>FALSE</tt> in case of failure. Your code '''must''' have called the <tt>s2c_ErrorHook</tt> with an explanation why things went wrong first.

<tt>s2c_DisconnectHook</tt>

This hook is called by <tt>S2_CONNECT</tt> when the connection could not be established (the <tt>s2c_ConnectHook</tt> returned <tt>FALSE</tt>), or by <tt>S2_DISCONNECT</tt>, shortly before the link level device is to be closed. The hook function is invoked with the following parameters:

<pre>
disconnect_hook_func(hook,reserved,s2cm);

VOID disconnect_hook_func(struct Hook *hook,APTR reserved,
struct Sana2ConnectionMessage *s2cm);
</pre>

The <tt>reserved</tt> parameter '''must''' be <tt>NULL</tt>. The <tt>s2cm</tt> parameter points to a data structure, as was described for the <tt>s2c_ConnectHook</tt>.

<tt>s2c_Login</tt>

<tt>s2c_Password</tt>

The purpose of these entries is to transport the authentication information the protocol may require. These entries are either <tt>NULL</tt> or contain pointers to <tt>NUL</tt>-terminated strings. If <tt>s2c_Login</tt> is <tt>NULL</tt>, then both login and password '''must''' be assumed to be empty. If <tt>s2c_Login</tt> is not <tt>NULL</tt> and <tt>s2c_Password</tt> is <tt>NULL</tt>, then the password '''must''' be assumed to be empty.

The list of options in <tt>s2c_Options</tt> supplies the necessary information on how the driver is to connect to the link layer. Each node contains an option, which bears a name and contains a value. This pair is what I call a ''parameter''. A number of parameter names are reserved, as will be listed below:

<tt>ppp</tt>.async.device

Name of device driver to use for asynchronous PPP.

Example: <tt>serial.device</tt>

<tt>ppp</tt>.async.unit

Device unit number to use for asynchronous PPP.

Example: <tt>0</tt>

<tt>ppp</tt>.async.speed

Transmission speed to use for asynchronous PPP in bits per second.

Example: <tt>115200</tt>

<tt>ppp.async.buffersize</tt>

Receive buffer size for asynchronous PPP.

Example: <tt>50000</tt>

<tt>ppp.async.checkcarrier</tt>

Whether the carrier signal of the link layer should be tested or not. This can be either 0 (do not test) or 1 (test the carrier signal).

Example: <tt>1</tt>

<tt>ppp.async.rtscts</tt>

Whether or not hardware handshaking should be used by the link layer. This can be either <tt>0</tt> (off) or <tt>1</tt> (on).

Example: <tt>1</tt>

<tt>ppp.async.shared</tt>

Whether or not the link layer device should be opened in shared mode. This can be either <tt>0</tt> (off) or <tt>1</tt> (on).

Example: <tt>0</tt>

<tt>ppp.async.nullmodem</tt>

Whether or not the link layer is a direct connection, such as a nullmodem. This can be either <tt>0</tt> (off) or <tt>1</tt> (on).

Example: <tt>0</tt>

<tt>ppp.async.eof</tt>

Whether or not the underlying serial device driver's 'EOF mode' should be enabled. This can be either <tt>0</tt> (off) or <tt>1</tt> (on).

Example: <tt>0</tt>

<tt>ppp.async.readrequests</tt>

Number of read requests to be used for asynchronous PPP.

Example: <tt>16</tt>

<tt>ppp.async.writerequests</tt>

Number of write requests to be used for asynchronous PPP.

Example: <tt>16</tt>

<tt>ppp.async.accm</tt>

Asynchronous control character map, expressed as a hexadecimal value.

Example: <tt>$000A0000</tt>

<tt>ppp.async.pfc</tt>

Whether or not protocol field compression should be used. This can be either <tt>0</tt> (off) or <tt>1</tt> (on).

Example: <tt>1</tt>

<tt>ppp.async.aacfc</tt>

Whether or not address and control field compression should be used. This can be either <tt>0</tt> (off) or <tt>1</tt> (on).

Example: <tt>1</tt>

<tt>ppp.async.vjhc</tt>

Whether or not Van Jacobson header compression should be used. This can be either <tt>0</tt> (off) or <tt>1</tt> (on).

Example: <tt>1</tt>

<tt>ppp.async.ignorefcs</tt>

Whether or not frame check sequences should be ignored upon reception. This can be either <tt>0</tt> (off) or <tt>1</tt> (on).

Example: <tt>0</tt>

<tt>ppp.async.initialize</tt>

The modem initialization command, with embedded control sequences, if possible.

Example: <tt>AT\r</tt>

<tt>ppp.async.dial</tt>

The modem dial command, with embedded control sequences, if possible.

Example: <tt>ATD12345\r</tt>

<tt>ppp.async.dialtimeout</tt>

The dial timeout, i.e. the number of seconds to wait after the dial command has been sent for the modem to establish a connection.

Example: <tt>60</tt>

<tt>ppp.async.hangup</tt>

The modem hangup command, with embedded control sequences, if possible.

Example: <tt>ATH0\r</tt>

<tt>ppp.idletimeout</tt>

Number of seconds the local host may remain idle, i.e. send no data to the peer, before a watchdog timeout elapses and proceeds to verify that the line is still operational.

Example: <tt>30</tt>

<tt>ppp.localaddress</tt>

The IP address to assign to the local host, as part of the PPP negotiation process. This must be given in dotted decimal notation (RFC1700).

Example: <tt>1.2.3.4</tt>

<tt>ppp.remoteaddress</tt>

The IP address to assume for the peer, as part of the PPP negotiation process. This must be given in dotted decimal notation (RFC1700).

Example: <tt>1.2.3.4</tt>

<tt>ppp.dns1address</tt>

The IP address to be used by the primary domain name server, as part of the PPP negotiation process. This must be given in dotted decimal notation (RFC1700).

Example: <tt>1.2.3.4</tt>

<tt>ppp.dns2address</tt>

The IP address to be used by the secondary domain name server, as part of the PPP negotiation process. This must be given in dotted decimal notation (RFC1700).

Example: <tt>1.2.3.4</tt>

<tt>ppp.maxfail</tt>

The maximum number of negative configuration acknowledgements to be sent before the PPP negotiation process switches to reject those options.

Example: <tt>5</tt>

<tt>ppp.maxterm</tt>

The maximum number of termination requests to be sent before the respective PPP network or link protocol gives up.

Example: <tt>2</tt>

<tt>ppp.maxconfig</tt>

The maximum number of configuration requests to be sent before the respective PPP network or link protocol gives up.

Example: <tt>10</tt>

<tt>ppp.timeout</tt>

The number of seconds that have to pass before the respective PPP network or link protocol will retry to do whatever didn't work during the last attempt.

Example: <tt>3</tt>

<tt>ppp.mtu</tt>

The maximum transmission unit to use.

Example: <tt>1500</tt>

<tt>ppp.peeridletimeout</tt>

Number of seconds the peer may remain idle, i.e. send no data to the local host, before a watchdog timeout elapses and proceeds to verify that the line is still operational.

Example: <tt>30</tt>

<tt>ppp.rejectpap</tt>

Whether or not the Password Authentication Protocol should be accepted, if offered by the peer. This can be either <tt>0</tt> (accept) or <tt>1</tt> (reject).

Example: <tt>0</tt>

<tt>ppp.sendid</tt>

A flag which controls whether the local host should send LCP identification packets or not. This can be either <tt>0</tt> (off) or <tt>1</tt> (on).

Example: <tt>0</tt>

<tt>ppp.pap.timeout</tt>

The Password Authentication Protocol requires that the server answers to the client's request to log in. The server may be unable to respond immediately, which means that the client will have to repeat its request. A short delay should separate each request sent, such as three seconds.

Example: <tt>3</tt>

<tt>ppp.pap.retry</tt>

If the client does not manage to authenticate with the server immediately, it may resend the authentication request several times. But the attempts have to stop eventually, such as after having resent the message ten times.

Example: <tt>10</tt>

<tt>ppp.dummyremoteaddress</tt>

Whether or not the PPP driver should make up an IP address if the peer refuses to state its own IP address.

Example: <tt>1</tt>

<tt>logfile</tt>

The name of a log file to create. If the file already exists, then new data should be appended to it.

Example: <tt>t:logfile</tt>

<tt>logoptions</tt>

A list of options which control what exactly should be logged.

<tt>ppp.ethernet.device</tt>

Name of device driver to use for PPPoE (PPP over Ethernet).

Example: <tt>a2065.device</tt>

<tt>ppp.ethernet.unit</tt>

Device unit number to use for PPPoE.

Example: <tt>0</tt>

<tt>ppp.ethernet.raw</tt>

Whether or not raw link layer frames should be constructed for transmission or not. This can be either <tt>0</tt> (off) or <tt>1</tt> (on).

Example: <tt>1</tt>

<tt>ppp.ethernet.bypass</tt>

Whether or not the IP packet transmission and reception should bypass several copying steps. This can be either <tt>0</tt> (off) or <tt>1</tt> (on).

Example: <tt>1</tt>

<tt>ppp.ethernet.readpackets</tt>

The number of read requests to queue for the link layer.

Example: <tt>16</tt>

<tt>ppp.ethernet.writepackets</tt>

The number of write requests to queue for the link layer.

Example: <tt>16</tt>

<tt>ppp.ethernet.service</tt>

The name of the PPPoE service to request.

Example: <tt>?</tt>

<tt>ppp.ethernet.ac</tt>

The name of the PPPoE access concentrator to request.

Example: <tt>?</tt>

<tt>ppp.ethernet.connecttimeout</tt>

The number of seconds to wait for the PPPoE server to allow a session to be opened.

Example: <tt>3</tt>

While this list of parameters may suggest that the command described above can be used solely with the PPP protocol, do not let that put you off. This list is merely the starting point, but it is not set in stone that it cannot be extended.

The names of the parameters are not case sensitive. As the names suggest, the name space itself is hierarchic in construction, i.e. everything related to the PPP protocol bears a name starting with the letters 'ppp' with the dot '.' separating the individual items. By this rule, ppp.async refers to options that concern asynchronous PPP and ppp.ethernet to options that concern PPP over Ethernet wire.

To add your own parameter, register it with the maintainer of the SANA-II standard or prefix its name with the letters 'x-'. For example, to use your own kind of 'ppp.ethernet.connecttimeout' parameter, change the name of the last component like this: ppp.ethernet.x-connecttimeout. No officially-registered parameter will ever begin with the prefix 'x-'.

The command should work as follows:

# The client must set up the <tt>Sana2Connection</tt> data structure, initialize the <tt>s2c_Size</tt>, <tt>s2c_Options</tt>, <tt>s2c_ErrorHook</tt>, <tt>s2c_ConnectHook</tt>, <tt>s2c_DisconnectHook</tt>, <tt>s2c_Login</tt> and <tt>s2c_Password</tt> fields.
# The connection options must be filled in, which means that nodes containing the respective information must be stored in the <tt>s2c_Options</tt> list. The client must make sure that the syntax of the parameters conforms to the specifications described above.
# A pointer to the <tt>Sana2Connection</tt> data structure is placed in the <tt>ios2_Data</tt> member of an <tt>IOSana2Req</tt>, the command is set to <tt>S2_CONNECT</tt> and the request is sent via <tt>DoIO()</tt> or <tt>SendIO()</tt>.
# The driver receives the request and begins to examine the contents of the <tt>s2c_Options</tt> list, as provided in the data structure pointed to by the <tt>ios2_Data</tt> member of the request. Unknown options are ignored, options whose values do not conform to the syntax specification are rejected; this is done by calling the <tt>s2c_ErrorHook</tt> with an error message referring to the option in question and by returning the <tt>IOSana2Req</tt> with an error code of <tt>S2ERR_BAD_ARGUMENT</tt> and wire error code of <tt>S2WERR_INVALID_OPTION</tt>.
# If the options are all in good order, the driver proceeds to verify that all mandatory options are provided. If this is not the case, the <tt>s2c_ErrorHook</tt> is called with an error message referring to the option in question and the <tt>IOSana2Req</tt> is returned with an error code of <tt>S2ERR_BAD_ARGUMENT</tt> and wire error code of <tt>S2WERR_MISSING_OPTION</tt>.
# The driver proceeds to do its local initialization, which involves opening the link layer device, etc. If this initialization fails, the <tt>s2c_ErrorHook</tt> is called with an error message referring to the problem and the <tt>IOSana2Req</tt> is returned with an appropriate error code.
# When the initialization has finished, the driver may invoke the <tt>s2c_ConnectHook</tt> callback. Some drivers may require this, such as asynchronous PPP, some may not, such as PPPoE. The purpose of the hook function is to give the client a chance to perform modem initializations and connect to the peer. If the <tt>s2c_ConnectHook</tt> cannot perform its duties, it has to invoke the <tt>s2c_ErrorHook</tt> with an error message and eventually return <tt>FALSE</tt>. If <tt>FALSE</tt> is returned, the driver must invoke the <tt>s2c_DisconnectHook</tt>, reverse any initializations it had made and eventually returned the <tt>IOSana2Req</tt> with an appropriate error code. If the <tt>s2c_ConnectHook</tt> returned <tt>TRUE</tt>, then the driver must proceed with the actions that require that the link layer is operational. A protocol negotiation may follow, which, if successful, will make the driver return the <tt>IOSana2Req</tt> with an error code of zero, indicating success. If successful, the SANA-II events <tt>S2EVENT_CONNECT</tt> and <tt>S2EVENT_ONLINE</tt> must be sent.
# The command will eventually return, but the client '''must not''' release the memory allocated for the <tt>Sana2Connection</tt> structure and the option nodes in the <tt>s2c_Options</tt> list. This is because the driver may have to invoke the <tt>s2c_DisconnectHook</tt> hook due to the connection shutting down on its own accord.

The connect and disconnect hook functions '''must not''' be called from interrupt code. For each hook only a <tt>Task</tt> calling context of unknown priority must be assumed. Also, stack space is provided only to call <tt>exec.library</tt> and <tt>utility.library</tt> functions. The callback shall not place excessive data on the stack. Stack space should be considered limited.

I propose a command with the following semantics:

<pre>
NAME
S2_CONNECT -- Establish a link layer connection and go
online.

FUNCTION
This command is for use by networking devices which require
a special link layer device to transmit their data, such as
an asynchronous serial line and need to know about the
configuration parameters necessary to open the connection.

IO REQUEST
ios2_Command - S2_CONNECT
ios2_Data - Pointer to Sana2Connection structure
ios2_BufferManagement - Magic cookie as returned when opening the
driver with a struct IOSana2Req

RESULTS
ios2_Req.io_Error - Zero if successful; non-zero otherwise
ios2_WireError - More specific error number

NOTES
If successful, this command implies S2_ONLINE, i.e. the
link layer is allocated and used by the driver.

The contents of the Sana2Connection structure must be valid
until the connection is eventually shut down. The driver will
need to cache it, so it must not be deallocated or otherwise
modified.

Note that S2_ONLINE does not necessarily imply S2_CONNECT, if
the S2_CONNECT command is listed as supported by the driver via
NSCMD_DEVICEQUERY. If S2_CONNECT is not listed as supported,
S2_ONLINE obviously implies connect functionality.

S2_CONNECT/S2_DISCONNECT do not nest.

SEE ALSO
S2_DISCONNECT</pre>
I propose that the following command number should be assigned:

<tt>#define S2_CONNECT 0xC005</tt>

== S2_DELMULTICASTADDRESS ==

<pre>
NAME
S2_DELMULTICASTADDRESS -- Disable an interface multicast address.

FUNCTION
This command causes device driver to disable multicast packet
reception for the requested address.

It is an error to disable a multicast address that is not enabled.

IO REQUEST
ios2_Command - S2_DELMULTICASTADDRESS
ios2_SrcAddr - Multicast address to disable.

RESULTS
ios2_Error - Zero if successful; non-zero otherwise.
ios2_WireError - More specific error number.

NOTES
Multicast addresses are added globally -- anyone using the device
may receive packets as a result of any multicast address which has
been added for the device.

Since multicast addresses are not "bound" to a particular packet type,
each enabled multicast address has an "enabled" count associated with
it so that if two protocols add the same multicast address and later
one removes it, it is still enabled until the second removes it.

SEE ALSO
S2_ADDMULTICASTADDRESS
</pre>

== S2_DEVICEQUERY ==

<pre>
NAME
S2_DEVICEQUERY -- Return parameters for this network interface.

FUNCTION
This command causes the device driver to report information about the
device. Up to SizeAvailable bytes of the information is copied
into a buffer pointed to by ios2_StatData. The format of the data is
as follows:

struct Sana2DeviceQuery
{
/*
** Standard information
*/
ULONG SizeAvailble; /* bytes available */
ULONG SizeSupplied; /* bytes supplied */
ULONG DevQueryFormat; /* this is type 0 */
ULONG DeviceLevel; /* this document is level 0 */

/*
** Common information
*/
UWORD AddrFieldSize; /* address size in bits */
ULONG MTU; /* maximum packet data size */
ULONG bps; /* line rate (bits/sec) */
ULONG HardwareType; /* what the wire is */
ULONG RawMTU; /* maximum raw packet data size */

/*
** Format specific information
*/
};

The SizeAvailable specifies the number of bytes that the caller
is prepared to accomodate, including the standard information fields.

SizeSupplied is the number of bytes actually supplied,
including the standard information fields, which will not exceed
SizeAvailable.

<devices/sana2.h> includes constants for these values. If your
hardware does not have a number assigned to it, you must contact
the AmigaOS development team to get a hardware number.

IO REQUEST
ios2_Command - S2_DEVICEQUERY.
ios2_StatData - Pointer to Sana2DeviceQuery structure to fill in.

RESULTS
ios2_Error - Zero if successful; non-zero otherwise.
ios2_WireError - More specific error number.
</pre>

== S2_DISCONNECT ==

This command complements <tt>S2_CONNECT</tt> in that it tears down a connection. It uses the same <tt>Sana2Connection</tt> structure and hooks, but most of these members are ignored.

The command should work as follows:

# The client must set up the <tt>Sana2Connection</tt> data structure, initialize the <tt>s2c_Size</tt>, <tt>s2c_Options</tt>, <tt>s2c_ErrorHook</tt>, <tt>s2c_ConnectHook</tt>, <tt>s2c_DisconnectHook</tt>, <tt>s2c_Login</tt> and <tt>s2c_Password</tt> fields. The <tt>s2c_Options</tt>, <tt>s2c_ConnectHook</tt>, <tt>s2c_Login</tt> and <tt>s2c_Password</tt> fields will be ignored, but the client should play things safe.
# A pointer to the <tt>Sana2Connection</tt> data structure is placed in the <tt>ios2_Data</tt> member of an <tt>IOSana2Req</tt>, the command is set to <tt>S2_DISCONNECT</tt> and the request is sent via <tt>DoIO()</tt> or <tt>SendIO()</tt>.
# The driver receives the request and proceeds to reverse the steps that previously allowed it to establish a connection. This includes telling the peer to shut down the link, but it does not include cleaning up the link layer device access, i.e. no I/O requests used for accessing a modem may be shut down yet.
# The <tt>s2c_DisconnectHook</tt> may be invoked with the proper parameters. Some drivers, such as for asynchronous PPP, will need the hook to tell the modem to hang up the line. Some drivers, such as for PPPoE, may not need this hook and thus ignore it.
# The initialization is reversed completely, all resources allocated when the connection was previously opened are released. The <tt>IOSana2Req</tt> is returned with an error code of zero, indicating success. The SANA-II event <tt>S2EVENT_DISCONNECT</tt> must be sent, and, if necessary, <tt>S2EVENT_OFFLINE</tt>.

The connect and disconnect hook functions must not be called from interrupt code. For each hook only a <tt>Task</tt> calling context of unknown priority must be assumed. Also, stack space is provided only to call <tt>exec.library</tt> and <tt>utility.library</tt> functions. The callback shall not place excessive data on the stack. Stack space should be considered limited.

I propose a command with the following semantics:

<pre>
NAME
S2_DISCONNECT -- Go offline and close a link layer connection
previously established with S2_CONNECT.

FUNCTION
This command complements the S2_CONNECT command in that it
reverses the steps taken to establish a link layer connection.

IO REQUEST
ios2_Command - S2_DISCONNECT
ios2_Data - Pointer to Sana2Connection structure
ios2_BufferManagement - Magic cookie as returned when opening the
driver with a struct IOSana2Req

RESULTS
ios2_Req.io_Error - Zero if successful; non-zero otherwise
ios2_WireError - More specific error number

NOTES
If successful, this command implies S2_OFFLINE, i.e. the
link layer is deallocated.

The driver must ignore the S2_DISCONNECT command and
recover gracefully if the S2_CONNECT was never sent or
returned with an error.

The contents of the Sana2Connection structure are valid only
until the device driver has processed the command and returned
the IOSana2Req. Any data the driver may need to retain beyond
that point of time must be copied.

Once the S2_DISCONNECT command has returned, it is safe to dispose
of the Sana2Connection structure provided at S2_CONNECT time.

Note that S2_OFFLINE does not necessarily imply S2_DISCONNECT, if
the S2_DISCONNECT command is listed as supported by the driver via
NSCMD_DEVICEQUERY. If S2_DISCONNECT is not listed as supported,
S2_OFFLINE obviously implies disconnect functionality.

S2_CONNECT/S2_DISCONNECT do not nest.

SEE ALSO
S2_CONNECT
</pre>

I propose that the following command number should be assigned:

<tt>#define S2_DISCONNECT 0xC006</tt>

== S2_GETDNSADDRESS ==

The PPP negotiation process may produce information on which domain name and NetBIOS name servers are available to the client. I think that it is doubtful that the availability of NetBIOS name servers will be useful for Amiga software (let alone whether NetBIOS name resolution has a future), which is why I suggest that a SANA-II command for returning only the domain name servers is introduced.

I propose a command with the following semantics:

<pre>
NAME
S2_GETDNSADDRESS -- Obtain the addresses of the primary
and secondary domain name servers.

FUNCTION
Obtain the addresses of the domain name servers available to the
client using this driver's address.

IO REQUEST
ios2_Command - S2_GETDNSADDRESS
ios2_Flags - Supported flags are:
SANA2IOB_QUICK
ios2_BufferManagement - Magic cookie as returned when opening the
driver with a struct IOSana2Req

RESULTS
ios2_Req.io_Error - Zero if successful; non-zero otherwise
ios2_WireError - More specific error number
ios2_SrcAddr - Address of primary domain name server
ios2_DstAddr - Address of secondary domain name server

NOTES
The size of the address returned by S2_GETPEERADDRESS must not be
different from the size as returned by the S2_DEVICEQUERY command. For
example, if a 32 bit IPv4 address was advertized, the driver must not
return a 128 bit IPv6 address instead.

If the driver is unable to return the primary domain name server
address (ios2_SrcAddr) or the secondary domain name server address
(ios2_DstAddr) it must fill the respective address fields with zeroes.
It is legal for a driver to respond to the S2_GETDNSADDRESS command
with two zero addresses (both ios2_SrcAddr and ios2_DstAddr filled
with zeroes).
</pre>

I propose that the following command number should be assigned:
<tt>#define S2_GETDNSADDRESS 0xC003</tt>

This command may be useful beyond the typical application (PPP) described above.

== S2_GETEXTENDEDGLOBALSTATS ==

There already exists a SANA-II command for querying global device statistics (<tt>S2_GETGLOBALSTATS</tt>) which should be common to all kinds of networking devices. Statistics that are particular to a certain device type are intended to be returned through the <tt>S2_GETSPECIALSTATS</tt> command. I feel that these mechanisms both fail to cater well enough for dial-up or session-oriented networking applications such as PPP or PPPoE. Since the data structure used by <tt>S2_GETGLOBALSTATS</tt> is of a fixed size and not intended to accomodate for new fields, I propose to introduce a new command which uses a different data structure, as follows:

<syntaxhighlight lang="C" line>
struct Sana2ExtDeviceStats
{
ULONG s2xds_Length;
ULONG s2xds_Actual;

S2QUAD s2xds_PacketsReceived;
S2QUAD s2xds_PacketsSent;
S2QUAD s2xds_BadData;
S2QUAD s2xds_Overruns;
S2QUAD s2xds_UnknownTypesReceived;
S2QUAD s2xds_Reconfigurations;
struct timeval s2xds_LastStart;

struct timeval s2xds_LastConnected;
struct timeval s2xds_LastDisconnected;
struct timeval s2xds_TimeConnected;
};
</syntaxhighlight>

Before I proceed to explain what purposes the individual members serve, a few words on the <tt>S2QUAD</tt> type, which is defined as follows:
<tt>typedef struct { ULONG s2q_High; ULONG s2q_Low; } S2QUAD;</tt>

In other words, the <tt>S2QUAD</tt> type stands for an unsigned 64 bit big endian integer, as expressed in ISO 'C' terms.

The structure members have the following purposes:

<tt>s2xds_Length</tt>

This is the size of the data structure to be filled in and should be initialized by the caller to <tt>sizeof(struct Sana2ExtDeviceStats)</tt>. Smaller values are permitted, but these '''must not''' be smaller than 8 (which covers the <tt>s2xds_Length</tt> and <tt>s2xds_Actual</tt> members). A driver which finds an <tt>s2xds_Length</tt> < 8 '''must''' treat this as an error and reject the command with <tt>ios2_Req.io_Error</tt>=<tt>IOERR_BADLENGTH</tt>.

<tt>s2xds_Actual</tt>

The size of the data structure filled with information. This member is initialized by the driver and '''must''' be <= <tt>s2xds_Length</tt>.

<tt>s2xds_PacketsReceived</tt>

Number of packets that this unit has received. This is a 64 bit integer.

<tt>s2xds_PacketsSent</tt>

Number of packets that this unit has sent. This is a 64 bit integer.

<tt>s2xds_BadData</tt>

Number of bad packets received (i.e., hardware CRC failed). This is a 64 bit integer.

<tt>s2xds_Overruns</tt>

Number of packets dropped due to insufficient resources available in the network interface. This is a 64 bit integer.

<tt>s2xds_UnknownTypesReceived</tt>

Number of packets received that had no pending read command with the appropriate packet type. This is a 64 bit integer.

<tt>s2xds_Reconfigurations</tt>

Number of network reconfigurations since this unit was last configured. This is a 64 bit integer.

<tt>s2xds_LastStart</tt>

The time when this unit last went on-line.

<tt>s2xds_LastConnected</tt>

The time when this unit last established a connection. For dial-up connections, this should be the time when the underlying serial line started to accumulate costs. <tt>s2xds_LastConnected</tt> '''must''' be set to zero if the unit never managed to make a connection.

<tt>s2xds_LastDisconnected</tt>

The time when this unit last shut down a connection. For dial-up connections, this should be the time when the underlying serial line stopped accumulating costs, e.g. when the modem's carrier signal was lost. <tt>s2xds_LastDisconnected</tt> '''must''' be set to zero if the unit never disconnected.

<tt>s2xds_TimeConnected</tt>

The time this unit has been connected. For dial-up connections this should be the time between now and when the underlying serial line started accumulating costs.

If this unit is not currently connected, then <tt>s2xds_TimeConnected</tt> '''must''' be set to zero. This means in particular that when the connection is lost, <tt>s2xds_TimeConnected</tt> '''must''' be immediately set to zero and <tt>s2xds_LastDisconnected</tt> '''must''' be filled in so that client software can query how long the unit was connected by subtracting <tt>s2xds_LastConnected</tt> from <tt>s2xds_LastDisconnected</tt>.

If this unit is currently connected, <tt>s2xds_TimeConnected</tt> '''must never''' be zero; if necessary, set <tt>s2xds_TimeConnected.tv_secs=0</tt> and <tt>s2xds_TimeConnected.tv_micros=1</tt>.

If <tt>s2xds_TimeConnected</tt> is zero, check <tt>s2xds_LastConnected</tt> and <tt>s2xds_LastDisconnected</tt>; if the latter two are not zero, you can calculate the previous connection time by subtracting <tt>s2xds_LastConnected</tt> from <tt>s2xds_LastDisconnected</tt>.

The layout and semantics used by the <tt>Sana2ExtDeviceStats</tt> data structure suggest that there is a difference between the underlying networking media (the link layer) and the state of the protocol that is running on top of it. With drivers for networking hardware such as Ethernet there was no difference between these two, but for protocols like SLIP, PPP or PPPoE there is a difference. The difference is in that a session or connection may exist for a certain time whereas the protocol running inside that session may be switched 'online' later. The primary purpose of the <tt>s2xds_LastConnected</tt>, <tt>s2xds_LastDisconnected</tt> and <tt>s2xds_TimeConnected</tt> fields is to allow for cost accounting and traffic monitoring (so that, for example, a driver may be disconnected after it has been idle for a while) to be written.

I propose a command with the following semantics:

<pre>
NAME
S2_GETEXTENDEDGLOBALSTATS -- Get interface accumulated statistics;
updated version.

FUNCTION
This command causes the device driver to retrieve various global
runtime statistics for this network interface. The format of the data
returned is as follows:

struct Sana2ExtDeviceStats
{
ULONG s2xds_Length;
ULONG s2xds_Actual;

S2QUAD s2xds_PacketsReceived;
S2QUAD s2xds_PacketsSent;
S2QUAD s2xds_BadData;
S2QUAD s2xds_Overruns;
S2QUAD s2xds_UnknownTypesReceived;
S2QUAD s2xds_Reconfigurations;
struct timeval s2xds_LastStart;

struct timeval s2xds_LastConnected;
struct timeval s2xds_LastDisconnected;
struct timeval s2xds_TimeConnected;
};

IO REQUEST
ios2_Command - S2_GETEXTENDEDGLOBALSTATS
ios2_StatData - Pointer to Sana2ExtDeviceStats structure
to fill in
ios2_BufferManagement - Magic cookie as returned when opening the
driver with a struct IOSana2Req

RESULTS
ios2_Req.io_Error - Zero if successful; non-zero otherwise
ios2_WireError - More specific error number
</pre>

I propose that the following command number should be assigned:
<tt>#define S2_GETEXTENDEDGLOBALSTATS 0xC004</tt>

== S2_GETGLOBALSTATS ==

<pre>
NAME
GetGlobalStats -- Get interface accumulated statistics.

FUNCTION
This command causes the device driver to retrieve various global
runtime statistics for this network interface. The format of the
data returned is as follows:

struct Sana2DeviceStats
{
ULONG PacketsReceived;
ULONG PacketsSent;
ULONG BadData;
ULONG Overruns;
ULONG UnknownTypesReceived;
ULONG Reconfigurations;
timeval LastStart;
};

IO REQUEST
ios2_Command - S2_GETGLOBALSTATS.
ios2_StatData - Pointer to Sana2DeviceStats structure to fill.

RESULTS
ios2_Error - Zero if successful; non-zero otherwise.
ios2_WireError - More specific error number.

SEE ALSO
S2_GETSPECIALSTATS
</pre>

== S2_GETNETWORKINFO ==

<pre>
NAME
S2_GETNETWORKINFO -- Get information on current network.

FUNCTION
This command provides information on the status of the currently
used network. If this command completes successfully, ios2_StatData
will contain a pointer to a tag list that contains information on
the network. The S2INFO_#? tags used are defined in the
devices/sana2wireless.h include file.

The returned taglist is allocated from the supplied memory pool.
To discard the results of this command, the entire memory pool
should be destroyed.

INPUTS
ios2_Data - Pointer to an Exec memory pool.

RESULTS
ios2_Data - Remains unchanged.
ios2_StatData - Pointer to a tag list.
io_Error - Zero if successful; non-zero otherwise.
ios2_WireError - More specific error code.
</pre>

== S2_GETNETWORKS ==

<pre>
NAME
S2_GETNETWORKS -- Scan for available networks.

FUNCTION
This command supplies details of available networks. If the scan
should be limited to one specific network, the S2INFO_SSID tag
should specify its name.

If this command completes successfully, ios2_StatData will contain
an array of pointers to tag lists, each of which contains
information on a single network. The device will set ios2_DataLength
to the number of elements in this array.

The returned taglists are allocated from the supplied memory pool.
To discard the results of this command, the entire memory pool
should be destroyed.

The S2INFO_#? tags used with this command are defined in the
devices/sana2wireless.h include file.

INPUTS
ios2_Data - Pointer to an Exec memory pool.
ios2_StatData - Pointer to taglist that specifies parameters to use.

RESULTS
ios2_DataLength - Number of tag lists returned.
ios2_Data - Remains unchanged.
ios2_StatData - Pointer to an array of tag lists.
io_Error - Zero if successful; non-zero otherwise.
ios2_WireError - More specific error code.
</pre>

== S2_GETPEERADDRESS ==

As part of the negotiation process, the PPP protocol can return the addresses used by the peer (the other side of the point-to-point connection PPP establishes; typically a dial-in server) and assigned to the client establishing the connection. The SANA-II standard does not provide for a mechanism to return such information. Existing drivers therefore had to resort to other means, such as by setting global environment variables containing this information.

I propose a command with the following semantics:

<pre>
NAME
S2_GETPEERADDRESS -- Obtain the addresses used by the peer
(server) and the client of a point-to-point connection.

FUNCTION
Obtain the address used by the peer of a point-to-point connection and
the address assigned to the local driver.

IO REQUEST
ios2_Command - S2_GETPEERADDRESS
ios2_Flags - Supported flags are:
SANA2IOB_QUICK
ios2_BufferManagement - Magic cookie as returned when opening the
driver with a struct IOSana2Req

RESULTS
ios2_Req.io_Error - Zero if successful; non-zero otherwise
ios2_WireError - More specific error number
ios2_SrcAddr - Address assigned to the local driver
ios2_DstAddr - Address used by the peer

NOTES
The size of the address returned by S2_GETPEERADDRESS must not be
different from the size returned by the S2_DEVICEQUERY command. For
example, if a 32 bit IPv4 address was advertized, the driver must not
return a 128 bit IPv6 address instead.

If the driver is unable to return the local driver address
(ios2_SrcAddr) or the peer's address (ios2_DstAddr) it must fill the
respective address fields with zeroes. It is legal for a driver to
respond to the S2_GETPEERADDRESS command with two zero addresses (both
ios2_SrcAddr and ios2_DstAddr filled with zeroes).
</pre>

I propose that the following command number should be assigned:
<tt>#define S2_GETPEERADDRESS 0xC002</tt>

This command may be useful beyond the typical application (PPP) described above.

== S2_GETSIGNALQUALITY ==

<pre>
NAME
S2_GETSIGNALQUALITY -- Get signal quality statistics.

FUNCTION
This command fills in the supplied Sana2SignalQuality structure with
current signal and noise levels. The unit for these figures is dBm.
Typically, they are negative values.

INPUTS
ios2_StatData - Pointer to Sana2SignalQuality structure.

RESULTS
io_Error - Zero if successful; non-zero otherwise.
ios2_WireError - More specific error code.
ios2_StatData - Pointer to filled Sana2SignalQuality structure.
</pre>

== S2_GETSPECIALSTATS ==

<pre>
NAME
S2_GETSPECIALSTATS -- Get network type specific statistics.

FUNCTION
This function returns statistics which are specific to the type of
network medium this driver controls. For example, this command could
return statistics common to all Ethernets which are not common to all
network mediums in general.

The supplied Sana2SpecialStatData structure is given below:

struct Sana2SpecialStatData
{
ULONG RecordCountMax;
ULONG RecordCountSupplied;
struct Sana2StatRecord[RecordCountMax];
};

The format of the data returned is:

struct Sana2StatRecord
{
ULONG Type; /* Amiga registered */
LONG Count; /* the stat itself */
char *String; /* null terminated */
};

The RecordCountMax field specifies the number of records that the
caller is prepared to accomodate.

RecordCountSupplied is the number of record actually supplied which
will not exceed RecordCountMax.

IO REQUEST
ios2_Command - S2_GETSPECIALSTATS.
ios2_StatData - Pointer to a Sana2SpecialStatData structure to fill.
RecordCountMax must be initialized.

RESULTS
ios2_Error - Zero if successful; non-zero otherwise.
ios2_WireError - More specific error number.

NOTES
Amiga will maintain registered statistic Types.

SEE ALSO
S2_GETGLOBALSTATS, <devices/sana2specialstats.h>
</pre>

== S2_GETSTATIONADDRESS ==

<pre>
NAME
S2_GETSTATIONADDRESS -- Get default and interface address.

FUNCTION
This command causes the device driver to copy the current interface
address into ios2_SrcAddr, and to copy the factory default station
address (if any) into ios2_DstAddr.

IO REQUEST
ios2_Command - S2_GETSTATIONADDRESS.

RESULTS
ios2_Error - Zero if successful; non-zero otherwise.
ios2_WireError - More specific error number.
ios2_SrcAddr - Current interface address.
ios2_DstAddr - Default interface address (if any).

SEE ALSO
S2_CONFIGINTERFACE
</pre>

== S2_GETTYPESTATS ==

<pre>
NAME
S2_GETTYPESTATS -- Get accumulated type specific statistics.

FUNCTION
This command causes the device driver to retrieve various packet type
specific runtime statistics for this network interface. The format of
the data returned is as follows:

struct Sana2TypeStatData
{
LONG PacketsSent;
LONG PacketsReceived;
LONG BytesSent;
LONG BytesReceived;
LONG PacketsDropped;
};

IO REQUEST
ios2_Command - S2_GETTYPESTATS.
ios2_PacketType - Packet type of interest.
ios2_StatData - Pointer to TypeStatData structure to fill in.

RESULTS
ios2_Error - Zero if successful; non-zero otherwise.
ios2_WireError - More specific error number.

NOTES
Statistics for a particular packet type are only available while that
packet type is being ``tracked''.

SEE ALSO
S2_TRACKTYPE, S2_UNTRACKTYPE
</pre>

== S2_MULTICAST ==

<pre>
NAME
S2_MULTICAST -- Multicast a packet on network.

FUNCTION
This command works the same as CMD_WRITE except that it also performs
whatever special processing of the packet is required to do a
multicast send. The actual multicast mechanism is neccessarily
network/interface/device specific.

IO REQUEST
ios2_Command - S2_MULTICAST.
ios2_Flags - Supported flags are:
SANA2IOB_RAW
SANA2IOB_QUICK
ios2_PacketType - Packet type to send.
ios2_DstAddr - Destination interface address for this packet.
ios2_DataLength - Length of the Data to be sent.
ios2_Data - Abstract data structure which packet data is
contained in.

RESULTS
ios2_Error - Zero if successful; non-zero otherwise.
This command can fail for many reasons and
is not supported by all networks and/or
network interfaces.
ios2_WireError - More specific error number.

NOTES
The address supplied in ios2_DstAddr will be sanity checked (if
possible) by the driver. If the supplied address fails this sanity
check, the multicast request will fail immediately with ios2_Error
set to S2WERR_BAD_MULTICAST.

Another Amiga will not receive a multicast packet unless it has had
the particular multicast address being used S2_ADDMULTICASTADRESS'd.

SEE ALSO
CMD_WRITE, S2_BROADCAST, S2_ADDMULTICASTADDRESS
</pre>

== S2_OFFLINE ==

<pre>
NAME
S2_OFFLINE -- Remove interface from service.

FUNCTION
This command removes a network interface from service.

IO REQUEST
ios2_Command - S2_OFFLINE.

RESULTS
ios2_Error - Zero if successful; non-zero otherwise.
ios2_WireError - More specific error number.

NOTES
Aborts all pending reads and writes with ios2_Error set to
S2ERR_OUTOFSERVICE.

While the interface is offline, all read, writes and any other
command that touches interface hardware will be rejected with
ios2_Error set to S2ERR_OUTOFSERVICE.

This command is intended to permit a network interface to be
tested on an otherwise live system.

SEE ALSO
S2_ONLINE
</pre>

== S2_ONEVENT ==

<pre>
NAME
S2_ONEVENT -- Return when specified event occures.

FUNCTION
This command returns when a particular event condition has occured
on the network or this network interface.

IO REQUEST
ios2_Command - S2_ONEVENT.
ios2_Flags - Supported flags are:
SANA2IOB_QUICK
ios2_WireError - Mask of event(s) to wait for
(from <devices/sana2.h>).

RESULTS
ios2_Error - Zero if successful; non-zero otherwise.
ios2_WireError - Mask of events that occured.

NOTES
If this device driver does not understand the specified event
condition(s) then the command returns immediately with
ios2_Req.io_Error set to S2_ERR_NOT_SUPPORTED and ios2_WireError
S2WERR_BAD_EVENT. A successful return will have ios2_Error set to
zero ios2_WireError set to the event number.

All pending requests for a particular event will be returned when
that event occurs.

All event types that cover a particular condition are returned when
that condition occures. For instance, if an error is returned by
a buffer management function during receive processing, events of
types S2EVENT_ERROR, S2EVENT_RX and S2EVENT_BUFF would be returned if
pending.

Types ONLINE and OFFLINE return immediately if the device is
already in the state to be waited for.
</pre>

== S2_ONLINE ==

<pre>
NAME
S2_ONLINE -- Put a network interface back in service.

FUNCTION
This command places an offline network interface back into service.

IO REQUEST
ios2_Command - S2_ONLINE.

RESULTS
ios2_Error - Zero if successful; non-zero otherwise.
ios2_WireError - More specific error number.

NOTES
This command is responsible for putting the network interface
hardware back into a known state (as close as possible to the
state before S2_OFFLINE) and resets the unit global and special
statistics.

SEE ALSO
S2_OFFLINE
</pre>

== S2_READMGMT ==

<pre>
NAME
S2_READMGMT -- Read a management frame.

FUNCTION
Reads a raw IEEE 802.11 management frame from the device. The buffer
management mechanism used is simpler than that used for data
packets (e.g. with CMD_READ): a buffer pointer and a length value
are passed to the device.

As with CMDREAD/S2_READORPHAN, multiple S2_READMGMT requests can
(and should) be queued concurrently to ensure no incoming frames are
missed.

INPUTS
ios2_DataLength - size of frame buffer.
ios2_Data - pointer to a frame buffer.

RESULTS
io_Error - Zero if successful; non-zero otherwise.
ios2_WireError - More specific error code.
ios2_DataLength - actual size of received frame.
ios2_Data - pointer to the filled frame buffer.
</pre>

== S2_READORPHAN ==

<pre>
NAME
S2_READORPHAN -- Get a packet for which there is no reader.

FUNCTION
Get the next packet available that does not satisfy any then-pending
CMD_READ requests. The data returned in the ios2_Data structure is
normally the Data Link Layer packet type field and the packet data. If
bit SANA2IOB_RAW is set in ios2_Flags, then the entire Data Link Layer
packet, including both header and trailer information, will be
returned.

IO REQUEST
ios2_Command - CMD_READORPHAN.
ios2_Flags - Supported flags are:
SANA2IOB_RAW
SANA2IOB_QUICK
ios2_DataLength - Length of the Data to be sent.
ios2_Data - Abstract data structure which packet data is
contained in.

RESULTS
ios2_Error - Zero if successful; non-zero otherwise.
ios2_WireError - More specific error number.
ios2_Flags - The following flags may be returned:
SANA2IOB_RAW
SANA2IOB_BCAST
SANA2IOB_MCAST
ios2_SrcAddr - Source interface address of packet.
ios2_DstAddr - Destination interface address of packet.
ios2_DataLength - Length of the Data to be sent.
ios2_Data - Abstract data structure which packet data is
contained in.

NOTES
This is intended for debugging and management tools. Protocols should
not use this.

As with 802.3 packets on an ethernet, to determine which protocol
family the returned packet belongs to you may have to specify
SANA2IOB_RAW to get the entire data link layer wrapper (which is where
the protocol type may be kept). Notice this necessarily means that
this cannot be done in a network interface independent fashion. The
driver will, however, fill in the PacketType field to the best of its
ability.

SEE ALSO
CMD_READ, CMD_WRITE
</pre>

== S2_SAMPLE_THROUGHPUT ==

The SANA-II standard already allows for statistics to be returned on the amount of data that has passed through a driver. Unfortunately, that information is not very accurate in that no information is provided on the time span in which the data was accumulated. Such information would be helpful in trying to determine as accurately as possible how large the data throughput actually is. I therefore propose a new command which can be used to obtain that information, which uses the following data structure:

<syntaxhighlight lang="C" line>
struct Sana2ThroughputStats
{
ULONG s2ts_Length;
ULONG s2ts_Actual;

struct Task * s2ts_NotifyTask;
ULONG s2ts_NotifyMask;

struct timeval s2ts_StartTime;
struct timeval s2ts_EndTime;
S2QUAD s2ts_BytesSent;
S2QUAD s2ts_BytesReceived;
S2QUAD s2ts_Updates;
};
</syntaxhighlight>

Before I proceed to explain what purposes the individual members serve, a few words on the <tt>S2QUAD</tt> type, which is defined as follows:

<tt>typedef struct { ULONG s2q_High; ULONG s2q_Low; } S2QUAD;</tt>

In other words, the <tt>S2QUAD</tt> type stands for an unsigned 64 bit big endian integer, as expressed in ISO 'C' terms.

The structure members have the following purposes:

<tt>s2ts_Length</tt>

This is the size of the data structure to be filled in and should be initialized by the caller to <tt>sizeof(struct Sana2ThroughputStats)</tt>. Smaller values are permitted, but these must not be smaller than 8 (which covers the <tt>s2ts_Length</tt> and <tt>s2ts_Actual</tt> members). A driver which finds an <tt>s2ts_Length</tt> < 8 must treat this as an error and reject the command with <tt>ios2_Req.io_Error</tt>=<tt>IOERR_BADLENGTH</tt>.

<tt>s2ts_Actual</tt>

The size of the data structure filled with information. This member is initialized by the driver and must be <= <tt>s2ts_Length</tt>.

<tt>s2ts_NotifyTask</tt>

The <tt>Task</tt> to notify whenever the contents of this data structure change. This must be <tt>NULL</tt> if no notification is desired.

'''Note:''' This feature should be used carefully, as so much data may arrive that the driver will almost be constantly signalling this <tt>Task</tt> that a change has taken place.

It is recommend that periodic polling be used, such as to update displays of a link monitoring program.

<tt>s2ts_NotifyMask</tt>

The signal mask to use for notifying the <tt>Task</tt> whose address is found in <tt>s2ts_NotifyTask</tt> (via <tt>Signal(s2ts->s2ts_NotifyTask,s2ts->s2ts_NotifyMask);</tt>). This must be zero if no notification is desired.

<tt>s2ts_StartTime</tt>

The time when the driver started to fill in this data structure.

<tt>s2ts_EndTime</tt>

The time when the driver last updated the contents of this data structure.

<tt>s2ts_BytesSent</tt>

Total number of bytes sent since the driver started to fill in this data structure. This is a 64 bit integer.

<tt>s2ts_BytesReceived</tt>

Total number of bytes received since the driver started to fill in this data structure. This is a 64 bit integer.

<tt>s2ts_Updates</tt>

Number of times the driver has updated this data structure. This value will increase with every change. This is a 64 bit integer.

A driver implementing this command should take care to update the members <tt>s2ts_EndTime</tt>, <tt>s2ts_BytesSent</tt>, <tt>s2ts_BytesReceived</tt> and <tt>s2ts_Updates</tt> atomically each time changes are made.

I propose a command with the following semantics:

<pre>
NAME
S2_SAMPLE_THROUGHPUT -- Obtain accurate information on
driver data throughput.

FUNCTION
This command installs a data structure which is updated every time
data is sent or received by the driver.

This command must be sent via SendIO() or BeginIO(); until
the associated I/O request is recalled using AbortIO(), the
device unit will continue to update the Sana2ThroughputStats
structure in real time.

IO REQUEST
ios2_Command - S2_SAMPLE_THROUGHPUT
ios2_StatData - Pointer to Sana2ThroughputStats structure
to fill in
ios2_BufferManagement - Magic cookie as returned when opening the
driver with a struct IOSana2Req

RESULTS
ios2_Req.io_Error - Zero if successful; non-zero otherwise

NOTES
If this device driver does not understand this command,
it will immediately return the IOSana2Req with
ios2_Req.io_Error set to IOERR_NOCMD. Otherwise, the request will
remain queued until it is removed with AbortIO() later.
</pre>

I propose that the following command number should be assigned:

<tt>#define S2_SAMPLE_THROUGHPUT 0xC007</tt>

== S2_SANA2HOOK ==

The 'traditional' copy call-back functions are installed at <tt>OpenDevice()</tt> time, and they are found in a <tt>TagItem</tt> list which is passed along with the <tt>IOSana2Req</tt>. For the new <tt>Hook</tt>-based call-back functionality, I propose to introduce a new command. This command would take care of installing one single <tt>Hook</tt> which will be invoked with the parameters described in section 3.1. The hook function can key off the <tt>SANA2HookMsg->schm_Method</tt> field to figure out which function should be performed. Once the <tt>Hook</tt> is installed via the command as follows, the driver shall ignore any and all tags passed to it during <tt>OpenDevice()</tt> time.

<pre>
NAME
S2_SANA2HOOK -- Install a Hook to perform operations such as copying,
overriding the call-back functions installed at
OpenDevice() time.

FUNCTION
The S2_SANA2HOOK command is to replace the 'traditional' call-back
functions installed through the TagItem list found in the
IOSana2Req->ios2_BufferManagement field. Instead of assigning a
function pointer for each copying function, all operations are
to be performed through a Hook. This is intended to make the
interface more portable and less dependant on a certain hardware
architecture.

The hook message and the hook data structures allow for more than
copying to be done.

IO REQUEST
ios2_Command - S2_SANA2HOOK
ios2_Data - Points to a struct Sana2Hook, which looks
like this:

struct Sana2Hook
{
struct Hook s2h_Hook;
Tag * s2h_Methods;
};

The structure fields have the following purposes:

s2h_Hook
A standard Hook structure, ready to be
called. Once installed, the complete Hook
structure including its Node structure is
off limits! The s2h_Hook remains installed
until CloseDevice().

s2h_Methods
Points to a table of Tag values, each
identifying a copy method supported
(S2_CopyToBuff, S2_CopyFromBuff,
S2_CopyToBuff16, S2_CopyFromBuff16,
S2_CopyToBuff32, S2_CopyFromBuff32,
S2_DMACopyToBuff32, S2_DMACopyFromBuff32,
S2_DMACopyToBuff64 or S2_DMACopyFromBuff64)
or the logging facility (S2_Log).
The table must be terminated by TAG_END.

The driver will check the table and
verify that the mandatory S2_CopyToBuff
and S2_CopyFromBuff commands are present.
Additional functionality is used as
available if the driver supports it.

ios2_DataLength - Must be >= 20, which is the default length of
the Sana2Hook structure. This may grow in
the future, and larger values for ios2_DataLength
may indicate additional functionality associated
with the Sana2Hook.

RESULTS
ios2_Error - IOERR_NOCMD if this command is not supported
by the driver.

IOERR_BADLENGTH if IOSana2Req->ios2_DataLength
is < 20.

IOERR_UNITBUSY if the Hook was already
installed or if any of the CMD_READ, CMD_WRITE,
S2_MULTICAST or S2_BROADCAST have already been
invoked.

S2WERR_FUNCTIONS_MISSING if the table pointed
to by Sana2Hook->s2h_Methods does not
include the S2_CopyToBuff and S2_CopyFromBuff
tags.

NOTES
The S2_SANA2HOOK command shall be invoked right after OpenDevice()
as very first command.

When the command has been executed, the driver must use the
newly installed Hook for all its copying or logging and cease to
use the call-back functions provided at OpenDevice() time.

The contents of the Sana2Hook structure, as passed to the
driver, must not be modified. This includes the MinNode
at the beginning of the Hook structure which the driver may
need to use for its own purposes.

The table pointed to by Sana2Hook->s2h_Methods must
include at least the S2_CopyToBuff and S2_CopyFromBuff tags.
It must be valid until CloseDevice() is called.

This field is to be treated as private by a protocol stack.
IOSana2Req structures may be duplicated by copying
ios2_BufferManagement, io_Device, and io_Unit.
</pre>

The new command value is defined as follows:

<pre>
#define S2_SANA2HOOK 0xC008
</pre>

The new error code is defined as follows:

<pre>
#define S2WERR_FUNCTIONS_MISSING 24 /* mandatory copy functions are missing */
</pre>

== S2_SETKEY ==

<pre>
NAME
S2_SETKEY -- Set an encryption key.

FUNCTION
Sets one of the encryption keys for the device. Note that
ios2_StatData, if used, points to a byte array representing the RX
RX counter value.

INPUTS
ios2_WireError - Key index.
ios2_PacketType - Encryption type (e.g. S2ENC_WEP).
ios2_DataLength - Key length.
ios2_Data - Key.
ios2_StatData - RX counter number (NULL if unused).

RESULTS
io_Error - Zero if successful; non-zero otherwise.
ios2_WireError - More specific error code.
</pre>

== S2_SETOPTIONS ==

<pre>
NAME
S2_SETOPTIONS -- Set network options.

FUNCTION
Set various parameters for the network interface. This command
should be called before going online to set any essential parameters
not covered elsewhere. The S2INFO_#? tags used are defined in the
devices/sana2wireless.h include file.

INPUTS
ios2_Data - Pointer to a taglist that specifies parameters to use.

RESULTS
io_Error - Zero if successful; non-zero otherwise.
ios2_WireError - More specific error code.
</pre>

== S2_TRACKTYPE ==

<pre>
NAME
S2_TRACKTYPE -- Accumulate statistics about a packet type.

FUNCTION
This command causes the device driver to accumulate statistics about
a particular packet type. Packet type statistics, for the particular
packet type, are zeroed by this command.

IO REQUEST
ios2_Command - S2_TRACKTYPE.
ios2_PacketType - Packet type of interest.

RESULTS
ios2_Error - Zero if successful; non-zero otherwise.
ios2_WireError - More specific error number.

SEE ALSO
S2_UNTRACKTYPE, S2_GETTYPESTATS
</pre>

== S2_UNTRACKTYPE ==

<pre>
NAME
S2_UNTRACKTYPE -- End statistics about a packet type.

FUNCTION
This command causes the device driver to stop accumulating
statistics about a particular packet type.

IO REQUEST
ios2_Command - S2_UNTRACKTYPE.
ios2_PacketType - Packet type of interest.

RESULTS
ios2_Error - Zero if successful; non-zero otherwise.
ios2_WireError - More specific error number.

SEE ALSO
S2_TRACKTYPE, S2_GETTYPESTATS
</pre>

== S2_WRITEMGMT ==

<pre>
NAME
S2_WRITEMGMT -- Write a management frame.

FUNCTION
Writes a raw IEEE 802.11 management frame to the device. The buffer
management mechanism used is simpler than that used for data
packets (e.g. with CMD_WRITE): a buffer pointer and a length value
are passed to the device.

INPUTS
ios2_DataLength - full frame length.
ios2_Data - pointer to a complete IEEE 802.11 management frame.

RESULTS
io_Error - Zero if successful; non-zero otherwise.
ios2_WireError - More specific error code.
</pre>

= Callback mechanisms =

== CopyFromBuff ==

<pre>
NAME
CopyFromBuff -- Copy n bytes from an abstract data structure.

SYNOPSIS
success = CopyFromBuff(to, from, n)
d0 a0 a1 d0

BOOL CopyToBuff(VOID *, VOID *, ULONG);

FUNCTION
This function copies 'n' bytes of data in the abstract data structure
pointed to by 'from' into the contigous memory pointed to by 'to'.
'to' must contain at least 'n' bytes of usable memory or innocent
memory will be overwritten.

INPUTS
to - pointer to contiguous memory to copy to.
from - pointer to abstract structure to copy from.
n - number of bytes to copy.

RESULT
success - TRUE if operation was successful, else FALSE.

NOTES
This function must be callable from interrupts. In particular, this
means that this function may not directly or indirectly call any
system memory functions (since those functions rely on Forbid() to
protect themselves) and that you must not compile this function
with stack checking enabled. See the Exec Interrupts
chapter for more details on what is legal in a routine called from
an interrupt handler.

'C' programmers should not compile with stack checking (option '-v'
in SAS) and should geta4() or __saveds.</pre>

== CopyToBuff ==

<pre>
NAME
CopyToBuff -- Copy n bytes to an abstract data structure.

SYNOPSIS
success = CopyToBuff(to, from, n)
d0 a0 a1 d0

BOOL CopyToBuff(VOID *, VOID *, ULONG);

FUNCTION
This function first does any initialization and/or allocation
required to prepare the abstract data structure pointed at by 'to'
to be filled with 'n' bytes of data from 'from'. It then executes
the copy operation.

If, for example, there is not enough memory available to prepare
the abstract data structure, the call is failed and FALSE is returned.

The buffer management scheme should be such that any memory needed
to fulfill CopyToBuff() calls is already allocated from the system
before the call to CopyToBuff() is made.

INPUTS
to - pointer to abstract structure to copy to.
from - pointer to contiguous memory to copy from.
n - number of bytes to copy.

RESULT
success - TRUE if operation was successful, else FALSE.

NOTES
This function must be callable from interrupts. In particular, this
means that this function may not directly or indirectly call any
system memory functions (since those functions rely on Forbid() to
protect themselves) and that you must not compile this function
with stack checking enabled. See the Exec Interrupts
chapter for more details on what is legal in a routine called from
an interrupt handler.

'C' programmers should not compile with stack checking (option '-v'
in SAS) and should geta4() or __saveds.</pre>

== PacketFilter ==

<pre>
NAME
PacketFilter -- Perform filtering operation on CMD_READ's.

SYNOPSIS
keep = PacketFilter(hook, ios2, data)
d0 a0 a2 a1

BOOL PacketFilter(struct Hook *, struct IOSana2Req *, APTR);

FUNCTION
This function (if supplied by a protocol stack) may be used to
reject packets before they are copied into a protocol stack's
internal buffers.

The IOSana2Req structure should be set up to look (almost) exactly
as it would if it was successfully returned for the current packet.
Specifically, the fields that should be set up correctly are:

ios2->ios2_DataLength
ios2->ios2_SrcAddr
ios2->ios2_DstAddr

The "data" pointer must point to the beginning of the packet data
that is stored in contiguous memory. The data should NOT include
any hardware specific headers (unless of course the CMD_READ
request wanted RAW packets).

INPUTS
hook - pointer to the Hook originally supplied during
OpenDevice().
ios2 - The IOSana2Req CMD_READ request that will be used
(the "object" of the Hook call).
data - The packet data (the "message" of the Hook call).

RESULT
success - TRUE if the driver should provide the packet to
the protocol stack, FALSE if the packet should be
ignored.

NOTES
This function must be callable from interrupts. In particular, this
means that this function may not directly or indirectly call any
system memory functions (since those functions rely on Forbid() to
protect themselves) and that you must not compile this function
with stack checking enabled. See the Exec Interrupts
chapter for more details on what is legal in a routine called from
an interrupt handler.

'C' programmers should not compile with stack checking (option '-v'
in SAS) and should geta4() or __saveds.

What does packet filtering do? With the original ``SANA-II Network
Device Driver Specification'', a protocol stack could open a device
and ask for certain packet types. It got all the packets that matched
this type. As it turned out, this could be mighty inefficient if there
were packets that the protocol stack did not use at all. These would
go into read processing of the protocol stack and waste CPU time even
though they could have been easily identified on arrival.</pre>

= Ethernet description =

<pre>#define S2WireType_Ethernet 1

ios2_DataLength:
valid ethernet packets have 64 to 1500 bytes of data.

Address format:
Ethernet addresses consist of 47 bits of address information and
a 1 bit multicast flag. The standard for expressing ethernet
addresses is as 6 bytes (octets) in the order in which the bytes
are transmitted with the low-order bits in a byte transmitted
first. The multicast flag bit is the least-significant bit of the
first byte.

Ethernet addresses in a Sana2IOReq occupy the first 6 bytes of
an address field in transmission order with the low-order bits in
a byte transmitted first.

Station Address:
Each ethernet board must have a unique ethernet hardware address.
Drivers will override any attempt to set the address to anything
other than the ROM address.

Raw reads and writes:
6 bytes of destination address,
6 bytes of source address,
2 bytes of type,
64 to 1500 bytes of data
(followed by 4 byte CRC value covering all of the above
which is hardware generated and checked, hence not included
in even raw packets)

Multicast: Supported

Broadcast: Supported

Promiscuous: Supported

Packet Type Numbers for Ethernet are assigned by:

Xerox Corporation
Xerox Systems Institute
475 Oakmead Parkway, Sunnyvale, CA 94086
Attn: Ms. Fonda Pallone
(408) 737-4652

Some Common Packet Type Numbers:

decimal Hex Description
------- --- -----------
000 0000-05DC IEEE 802.3 Length Field
2048 0800 TCP/IP -- IP
2054 0806 TCP/IP -- ARP
32821 8035 TCP/IP -- RARP
32923 809B Appletalk
33011 80F3 AppleTalk AARP (Kinetics)
33100 814C SNMP
33079 8137-8138 Novell, Inc.</pre>
= ARCNET description =

<pre>S2WireType_Arcnet 7

ios2_DataLength:
506 byte MTU (because of the possibility of two byte Types).
Packets of size 254, 255, or 256 bytes are padded to 257 bytes before
transmition.

Station Address:
ARCNET hardware may have addresses set with jumpers, DIP switches
or software. Different drivers may therefore behave differently
with S2_CONFIGINTERFACE.

Hardware addresses should be assigned by users from highest to lowest
because there is some efficiency gained in the token passing scheme
this way. For example, on a three node network, hardware numbers 254,
253 and 252 should be used rather than 1, 2 and 3.

Raw reads and writes:
Short Packets (1-253 bytes)
Destination Address (1 byte)
Source Address (1 byte)
Count (256-N-Type length) (1 byte)
Padding (to byte number Count)
Type (1 or 2 bytes)
Data (N bytes)

Long Packets (257-506 bytes)
Destination Address (1 byte)
Source Address (1 byte)
zero (1 byte)
Count (512-N-Type length) (1 byte)
Padding (to byte number Count)
Type (1 or 2 bytes)
Data (N bytes)

Multicast: Not Supported

Broadcast: Supported

Promiscuous: Generally Not Supported

Packet Type Numbers for ARCNET are assigned by:
Datapoint Corporation

Some Common Packet Type Numbers

decimal hex description
------- --- -----------
221 DD AppleTalk
240 F0 TCP/IP -- IP (RFC 1051)
241 F1 TCP/IP -- ARP (RFC 1051)
212 F0 TCP/IP IP (RFC 1201, proposed)
213 F1 TCP/IP -- ARP (RFC 1201, proposed)
214 D6 TCP/IP -- RARP (RFC 1201, proposed)
247 F7 Banyan Vines
250 FA Novell IPX
</pre>

= Authors =

== Revision 2 & 3 ==

Copyright © 1992-2000 Amiga, Inc. All Rights Reserved 

Amiga is a registered trademark of Amiga, Inc. Ethernet is a trademark of Xerox Corporation. ARCNET is a trademark of Datapoint Corporation. DECNet is a trademark of Digital Equipment Corporation. AppleTalk is a trademark of Apple Computer, Inc.

== Revision 4 ==

Extending the SANA-II network driver specification 
by Olaf Barthel

(Last updated 02-Mar-2003)

== Revision 5 ==

Hook-based callback function extensions for SANA-II (SANA-IIR5) 
by Olaf Barthel and Heinz Wrobel

== Revision 6 ==

SANA-II IEEE 802.11 wireless API 
by Neil Cafferkey

= Acknowledgments =

== Revision 2 & 3 ==

Many people and companies have contributed to the "SANA-II Network Device Driver Specification". The original SANA-II Autodocs and includes were put together by Ray Brand, Perry Kivolowitz (ASDG) and Martin Hunt. Those original documents evolved to their current state and grew to include this document at the hands of Dale Larson and Greg Miller. Brian Jackson and John Orr provided valuable editing. Randell Jesup has provided sage advice on several occasions. The buffer management callback mechanism was his idea. Dale Luck (GfxBase) and Rick Spanbauer (Ameristar Technologies) have provided valuable comments throughout the process. Nicolas Benezan (ADONIS) provided many detailed and useful comments on weaknesses in late drafts of the specification. The enhancements for better buffer management, clarifications and notes for device implementers were added to the specification by Heinz Wrobel whilst consulting for Amiga Technologies GmbH, yielding revision 3.0 of the specification.

Thanks to all the above and the numerous others who have contributed with their comments, questions and discussions.

= Changes =

== Revision 4 ==

Changes since 24-Dec-2002:

* The <tt>Sana2Connection</tt> data structure used by the <tt>S2_CONNECT</tt> command now must remain valid until the <tt>S2_DISCONNECT</tt> command is sent (see [[#2.4|section 2.4]]).

Changes since 01-May-2002:

* Added the <tt>ppp.async.readrequests</tt> and <tt>ppp.async.eof</tt> configuration keywords.

Changes since 04-Jan-2002:

* Added the <tt>ppp.dummyremoteaddress</tt> and <tt>ppp.ethernet.ac</tt> configuration keywords.

Changes since 10-Dec-2001:

* Converted to HTML format.
* Added the <tt><devices/sana2.h></tt> header file to the appendix.
* The memory alignment for the <tt>S2_DMACopyToBuff64</tt> and <tt>S2_DMACopyFromBuff64</tt> hooks refers to bits and not to bytes.

Changes since 19-Nov-2001:

* Added to the list of reserved configuration keywords (<tt>ppp.idletimeout</tt>, <tt>ppp.peeridletimeout</tt>, <tt>ppp.sendid</tt>).
* Renamed the fields of the <tt>Sana2ExtDeviceStats</tt> structure.
* Clarified that the <tt>S2QUAD</tt> type is a big endian integer.
* More clarifications for the <tt>S2_CONNECT</tt>/<tt>S2_DISCONNECT</tt> and <tt>S2_ONLINE</tt>/<tt>S2_OFFLINE</tt> commands.
* Updated the discussion of the <tt>Sana2DeviceQuery.RawMTU</tt> field, clarifying what is included in the the Ethernet <tt>RawMTU</tt>.
* Updated the <tt><devices/sana2.h></tt> header file. Note that there is no equivalent <tt>"devices/sana2.i"</tt> header file yet.

Changes since 12-Nov-2001:

* Changed the command numbers of <tt>S2_GETPEERADDRESS</tt>, <tt>S2_GETDNSADDRESS</tt>, <tt>S2_GETEXTENDEDGLOBALSTATS</tt>, <tt>S2_CONNECT</tt>, <tt>S2_DISCONNECT</tt> and <tt>S2_SAMPLE_THROUGHPUT</tt> to be NSD-compliant. Also assigned a new number to the <tt>S2_SAMPLE_THROUGHPUT </tt> command.
* Added section 4 ("Extensions for existing commands").
* Added the last paragraph to section 9, relating to the future extension of the <tt>Sana2DeviceQuery</tt> structure.

Changes since 03-Nov-2001:

* Renamed <tt>S2_GETNEWGLOBALSTATS</tt> to <tt>S2_GETEXTENDEDGLOBALSTATS</tt> (see [[#2.3|section 2.3]]).
* The <tt>S2_GETEXTENDEDGLOBALSTATS</tt> now uses 64 bit quantities for the <tt>s2xds_PacketsReceived</tt>, <tt>s2xds_PacketsSent</tt>, <tt>s2xds_BadData</tt>, <tt>s2xds_Overruns</tt>, <tt>s2xds_UnknownTypesReceived</tt> and <tt>s2xds_Reconfigurations</tt> counters.
* In section 2.6 the <tt>S2_SAMPLE_THROUGHPUT</tt> command was modified to use 64 bit integers for all members of the <tt>Sana2ThroughputStats</tt> structure.
* All proposed commands are now listed with their numeric IDs.
* The command autodocs specifically mention the <tt>ios2_BufferManagement</tt> field.
* All references to <tt>ios2_Error</tt> have been replaced with <tt>ios2_Req.io_Error</tt>.
* In section 7 the use of the <tt>IOERR_NOCMD</tt>/<tt>S2ERR_NOT_SUPPORTED</tt> error codes is clarified.
* Section 7 takes a more detailed look at safe default values returned by the query commands.
* Inserted section 3 ("Annotations for existing commands").
* The <tt>S2_CONNECT</tt> and <tt>S2_DISCONNECT</tt> commands now specifically mention the life time of the data they have to deal with.

Changes since 14-Oct-2001:

* Added <tt>S2_CONNECT</tt> and <tt>S2_DISCONNECT</tt> commands.
* Added <tt>S2EVENT_CONNECT</tt> and <tt>S2EVENT_DISCONNECT</tt> events.
* Added section 4 ("New wire error codes").
* In section 5.2 the originally proposed log callback function has been wrapped into a standard Hook structure.
* Removed item on <tt>S2_CONNECT</tt>/<tt>S2_DISCONNECT</tt> from section 7 ("Unsolved problems").
* Added section 8 ("Changes").

== Revision 5 ==

22-Mar-2004:

* Conversion to HTML

21-Jan-2004:

* Added clarifications for <tt>schm_MsgSize</tt>, <tt>slhm_MsgSize</tt>, <tt>slhm_Priority</tt>, <tt>slhm_Name</tt>, <tt>slhm_Message</tt> and <tt>s2h_Hook</tt>.
* Updated the <tt>S2_SANA2HOOK</tt> documentation.
* Shortened section 4.
* Updated section 5.

30-Nov-2003:

* Extended the applicability of the <tt>Hook</tt> to logging.
* Renamed <tt>S2_COPYHOOK</tt> to <tt>S2_SANA2HOOK</tt>, which matches the extended scope it should cover.
* The message passed to the <tt>Hook</tt> now includes a size field which holds the size of the message, expressed in bytes.

06-Oct-2003:

* Replaced the list of new tag items with a single <tt>Hook</tt>, which is installed through a new command.
* Added "Caveats" and "Changes" sections
* Removed the documentation for the originally proposed <tt>TagItem</tt> (sections 3.2.1 through 3.2.10)

= History =

== Revision 2 and 3 ==

This standard has undergone several drafts with long periods for comment from developers and the Amiga community at large. These drafts include a UseNet release which was also distributed on the Fish Disks in June, 1991 (as well as published in the '91 DevCon notes), and the November 7 Draft for Final Comment and Approval distributed via Bix, ADSP and UseNet. There were also several intermediate drafts with more limited distribution.

== Revision 4 ==

(Olaf Barthel)

I've been working on a TCP/IP stack and PPP drivers to go with them for a while and found that there were some things that SANA-II did specifically not address, and which ought to be covered by it. In other areas clarification was needed. Also, discussions I had with Harald Frank suggested that the extensions made by Heinz Wrobel and Stefan Sticht in the SANA-IIR3 specification could need extending.

Autodocs:Main

2026-06-09T17:01:45Z

Costel Mincea: Updated to SDK 54.24 AutoDocs

The autodocs are included in the latest [[SDK_FAQ|AmigaOS SDK]] (download from [https://www.hyperion-entertainment.com/index.php/downloads?view=files&parent=30 Hyperion Entertainment]) and are also available as text files below:

* [http://wiki.amigaos.net/amiga/autodocs/a1floppy.doc.txt a1floppy.doc]
* [http://wiki.amigaos.net/amiga/autodocs/a1serial_dev.doc.txt a1serial_dev.doc]
* [http://wiki.amigaos.net/amiga/autodocs/acpires.doc.txt acpires.doc]
* [http://wiki.amigaos.net/amiga/autodocs/AI_Driver.doc.txt AI_Driver.doc]
* [http://wiki.amigaos.net/amiga/autodocs/amigaguide.doc.txt amigaguide.doc]
* [http://wiki.amigaos.net/amiga/autodocs/amigaguide_dtc.doc.txt amigaguide_dtc.doc]
* [http://wiki.amigaos.net/amiga/autodocs/AmigaInput.doc.txt AmigaInput.doc]
* [http://wiki.amigaos.net/amiga/autodocs/amiga_lib.doc.txt amiga_lib.doc]
* [http://wiki.amigaos.net/amiga/autodocs/animation_dtc.doc.txt animation_dtc.doc]
* [http://wiki.amigaos.net/amiga/autodocs/appdir-handler.doc.txt appdir-handler.doc]
* [http://wiki.amigaos.net/amiga/autodocs/application.doc.txt application.doc]
* [http://wiki.amigaos.net/amiga/autodocs/arexx_cl.doc.txt arexx_cl.doc]
* [http://wiki.amigaos.net/amiga/autodocs/asl.doc.txt asl.doc]
* [http://wiki.amigaos.net/amiga/autodocs/audio.doc.txt audio.doc]
* [http://wiki.amigaos.net/amiga/autodocs/aux-handler.doc.txt aux-handler.doc]
* [http://wiki.amigaos.net/amiga/autodocs/battclock.doc.txt battclock.doc]
* [http://wiki.amigaos.net/amiga/autodocs/battmem.doc.txt battmem.doc]
* [http://wiki.amigaos.net/amiga/autodocs/bevel_ic.doc.txt bevel_ic.doc]
* [http://wiki.amigaos.net/amiga/autodocs/biosversion.doc.txt biosversion.doc]
* [http://wiki.amigaos.net/amiga/autodocs/bitmap_ic.doc.txt bitmap_ic.doc]
* [http://wiki.amigaos.net/amiga/autodocs/bootsd.doc.txt bootsd.doc]
* [http://wiki.amigaos.net/amiga/autodocs/bsdsocket.doc.txt bsdsocket.doc]
* [http://wiki.amigaos.net/amiga/autodocs/btree.doc.txt btree.doc]
* [http://wiki.amigaos.net/amiga/autodocs/bullet.doc.txt bullet.doc]
* [http://wiki.amigaos.net/amiga/autodocs/button_gc.doc.txt button_gc.doc]
* [http://wiki.amigaos.net/amiga/autodocs/camd.doc.txt camd.doc]
* [http://wiki.amigaos.net/amiga/autodocs/cardres.doc.txt cardres.doc]
* [http://wiki.amigaos.net/amiga/autodocs/cd.doc.txt cd.doc]
* [http://wiki.amigaos.net/amiga/autodocs/checkbox_gc.doc.txt checkbox_gc.doc]
* [http://wiki.amigaos.net/amiga/autodocs/chooser_gc.doc.txt chooser_gc.doc]
* [http://wiki.amigaos.net/amiga/autodocs/cia.doc.txt cia.doc]
* [http://wiki.amigaos.net/amiga/autodocs/clicktab_gc.doc.txt clicktab_gc.doc]
* [http://wiki.amigaos.net/amiga/autodocs/clipboard.doc.txt clipboard.doc]
* [http://wiki.amigaos.net/amiga/autodocs/colorwheel_gc.doc.txt colorwheel_gc.doc]
* [http://wiki.amigaos.net/amiga/autodocs/commodities.doc.txt commodities.doc]
* [http://wiki.amigaos.net/amiga/autodocs/con-handler.doc.txt con-handler.doc]
* [http://wiki.amigaos.net/amiga/autodocs/console.doc.txt console.doc]
* [http://wiki.amigaos.net/amiga/autodocs/datatypes.doc.txt datatypes.doc]
* [http://wiki.amigaos.net/amiga/autodocs/datebrowser_gc.doc.txt datebrowser_gc.doc]
* [http://wiki.amigaos.net/amiga/autodocs/ddebug_lib.doc.txt ddebug_lib.doc]
* [http://wiki.amigaos.net/amiga/autodocs/debug_lib.doc.txt debug_lib.doc]
* [http://wiki.amigaos.net/amiga/autodocs/diffview_gc.doc.txt diffview_gc.doc]
* [http://wiki.amigaos.net/amiga/autodocs/disk.doc.txt disk.doc]
* [http://wiki.amigaos.net/amiga/autodocs/diskfont.doc.txt diskfont.doc]
* [http://wiki.amigaos.net/amiga/autodocs/diskio.doc.txt diskio.doc]
* [http://wiki.amigaos.net/amiga/autodocs/docky.doc.txt docky.doc]
* [http://wiki.amigaos.net/amiga/autodocs/dos.doc.txt dos.doc]
* [http://wiki.amigaos.net/amiga/autodocs/dos.dospackets.doc.txt dos.dospackets.doc]
* [http://wiki.amigaos.net/amiga/autodocs/dos.obsolete.doc.txt dos.obsolete.doc]
* [http://wiki.amigaos.net/amiga/autodocs/drawlist_ic.doc.txt drawlist_ic.doc]
* [http://wiki.amigaos.net/amiga/autodocs/elf.doc.txt elf.doc]
* [http://wiki.amigaos.net/amiga/autodocs/exec.doc.txt exec.doc]
* [http://wiki.amigaos.net/amiga/autodocs/expansion.doc.txt expansion.doc]
* [http://wiki.amigaos.net/amiga/autodocs/filesysbox.doc.txt filesysbox.doc]
* [http://wiki.amigaos.net/amiga/autodocs/filesysres.doc.txt filesysres.doc]
* [http://wiki.amigaos.net/amiga/autodocs/filler_ic.doc.txt filler_ic.doc]
* [http://wiki.amigaos.net/amiga/autodocs/fillrect_ic.doc.txt fillrect_ic.doc]
* [http://wiki.amigaos.net/amiga/autodocs/frame_ic.doc.txt frame_ic.doc]
* [http://wiki.amigaos.net/amiga/autodocs/frbutton_gc.doc.txt frbutton_gc.doc]
* [http://wiki.amigaos.net/amiga/autodocs/fsldmares.doc.txt fsldmares.doc]
* [http://wiki.amigaos.net/amiga/autodocs/fuelgauge_gc.doc.txt fuelgauge_gc.doc]
* [http://wiki.amigaos.net/amiga/autodocs/gadget_gc.doc.txt gadget_gc.doc]
* [http://wiki.amigaos.net/amiga/autodocs/gadtools.doc.txt gadtools.doc]
* [http://wiki.amigaos.net/amiga/autodocs/gameport.doc.txt gameport.doc]
* [http://wiki.amigaos.net/amiga/autodocs/Gameport_pci.doc.txt Gameport_pci.doc]
* [http://wiki.amigaos.net/amiga/autodocs/gauge_ic.doc.txt gauge_ic.doc]
* [http://wiki.amigaos.net/amiga/autodocs/getcolor_gc.doc.txt getcolor_gc.doc]
* [http://wiki.amigaos.net/amiga/autodocs/getfile_gc.doc.txt getfile_gc.doc]
* [http://wiki.amigaos.net/amiga/autodocs/getfont_gc.doc.txt getfont_gc.doc]
* [http://wiki.amigaos.net/amiga/autodocs/getscreenmode_gc.doc.txt getscreenmode_gc.doc]
* [http://wiki.amigaos.net/amiga/autodocs/glyph_ic.doc.txt glyph_ic.doc]
* [http://wiki.amigaos.net/amiga/autodocs/gradientslider_gc.doc.txt gradientslider_gc.doc]
* [http://wiki.amigaos.net/amiga/autodocs/graphics.doc.txt graphics.doc]
* [http://wiki.amigaos.net/amiga/autodocs/group_gc.doc.txt group_gc.doc]
* [http://wiki.amigaos.net/amiga/autodocs/hunk.doc.txt hunk.doc]
* [http://wiki.amigaos.net/amiga/autodocs/i2cres.doc.txt i2cres.doc]
* [http://wiki.amigaos.net/amiga/autodocs/ibutton_gc.doc.txt ibutton_gc.doc]
* [http://wiki.amigaos.net/amiga/autodocs/ic_cl.doc.txt ic_cl.doc]
* [http://wiki.amigaos.net/amiga/autodocs/icon.doc.txt icon.doc]
* [http://wiki.amigaos.net/amiga/autodocs/iconmodule.doc.txt iconmodule.doc]
* [http://wiki.amigaos.net/amiga/autodocs/iffparse.doc.txt iffparse.doc]
* [http://wiki.amigaos.net/amiga/autodocs/image_ic.doc.txt image_ic.doc]
* [http://wiki.amigaos.net/amiga/autodocs/input.doc.txt input.doc]
* [http://wiki.amigaos.net/amiga/autodocs/integer_gc.doc.txt integer_gc.doc]
* [http://wiki.amigaos.net/amiga/autodocs/intuition.doc.txt intuition.doc]
* [http://wiki.amigaos.net/amiga/autodocs/iscroller_gc.doc.txt iscroller_gc.doc]
* [http://wiki.amigaos.net/amiga/autodocs/istring_gc.doc.txt istring_gc.doc]
* [http://wiki.amigaos.net/amiga/autodocs/itext_ic.doc.txt itext_ic.doc]
* [http://wiki.amigaos.net/amiga/autodocs/keyboard.doc.txt keyboard.doc]
* [http://wiki.amigaos.net/amiga/autodocs/keymap.doc.txt keymap.doc]
* [http://wiki.amigaos.net/amiga/autodocs/label_ic.doc.txt label_ic.doc]
* [http://wiki.amigaos.net/amiga/autodocs/launch-handler.doc.txt launch-handler.doc]
* [http://wiki.amigaos.net/amiga/autodocs/layers.doc.txt layers.doc]
* [http://wiki.amigaos.net/amiga/autodocs/layout_gc.doc.txt layout_gc.doc]
* [http://wiki.amigaos.net/amiga/autodocs/libamiga_a.doc.txt libamiga_a.doc]
* [http://wiki.amigaos.net/amiga/autodocs/listbrowser_gc.doc.txt listbrowser_gc.doc]
* [http://wiki.amigaos.net/amiga/autodocs/locale.doc.txt locale.doc]
* [http://wiki.amigaos.net/amiga/autodocs/lowlevel.doc.txt lowlevel.doc]
* [http://wiki.amigaos.net/amiga/autodocs/mathffp.doc.txt mathffp.doc]
* [http://wiki.amigaos.net/amiga/autodocs/mathieeedoubbas.doc.txt mathieeedoubbas.doc]
* [http://wiki.amigaos.net/amiga/autodocs/mathieeedoubtrans.doc.txt mathieeedoubtrans.doc]
* [http://wiki.amigaos.net/amiga/autodocs/mathieeesingbas.doc.txt mathieeesingbas.doc]
* [http://wiki.amigaos.net/amiga/autodocs/mathieeesingtrans.doc.txt mathieeesingtrans.doc]
* [http://wiki.amigaos.net/amiga/autodocs/mathtrans.doc.txt mathtrans.doc]
* [http://wiki.amigaos.net/amiga/autodocs/menu_cl.doc.txt menu_cl.doc]
* [http://wiki.amigaos.net/amiga/autodocs/misc.doc.txt misc.doc]
* [http://wiki.amigaos.net/amiga/autodocs/model_cl.doc.txt model_cl.doc]
* [http://wiki.amigaos.net/amiga/autodocs/mounter.doc.txt mounter.doc]
* [http://wiki.amigaos.net/amiga/autodocs/narrator.doc.txt narrator.doc]
* [http://wiki.amigaos.net/amiga/autodocs/nonvolatile.doc.txt nonvolatile.doc]
* [http://wiki.amigaos.net/amiga/autodocs/nvramres.doc.txt nvramres.doc]
* [http://wiki.amigaos.net/amiga/autodocs/openfirmware.doc.txt openfirmware.doc]
* [http://wiki.amigaos.net/amiga/autodocs/page_gc.doc.txt page_gc.doc]
* [http://wiki.amigaos.net/amiga/autodocs/palette_gc.doc.txt palette_gc.doc]
* [http://wiki.amigaos.net/amiga/autodocs/parallel.doc.txt parallel.doc]
* [http://wiki.amigaos.net/amiga/autodocs/partition_gc.doc.txt partition_gc.doc]
* [http://wiki.amigaos.net/amiga/autodocs/pasemi_dma.doc.txt pasemi_dma.doc]
* [http://wiki.amigaos.net/amiga/autodocs/penmap_ic.doc.txt penmap_ic.doc]
* [http://wiki.amigaos.net/amiga/autodocs/performancemonitor.doc.txt performancemonitor.doc]
* [http://wiki.amigaos.net/amiga/autodocs/Picasso96API.doc.txt Picasso96API.doc]
* [http://wiki.amigaos.net/amiga/autodocs/picture_dtc.doc.txt picture_dtc.doc]
* [http://wiki.amigaos.net/amiga/autodocs/pointer_cl.doc.txt pointer_cl.doc]
* [http://wiki.amigaos.net/amiga/autodocs/popupmenu_cl.doc.txt popupmenu_cl.doc]
* [http://wiki.amigaos.net/amiga/autodocs/port-handler.doc.txt port-handler.doc]
* [http://wiki.amigaos.net/amiga/autodocs/potgo.doc.txt potgo.doc]
* [http://wiki.amigaos.net/amiga/autodocs/printer.doc.txt printer.doc]
* [http://wiki.amigaos.net/amiga/autodocs/prop_gc.doc.txt prop_gc.doc]
* [http://wiki.amigaos.net/amiga/autodocs/radiobutton_gc.doc.txt radiobutton_gc.doc]
* [http://wiki.amigaos.net/amiga/autodocs/ram.doc.txt ram.doc]
* [http://wiki.amigaos.net/amiga/autodocs/ramlib.doc.txt ramlib.doc]
* [http://wiki.amigaos.net/amiga/autodocs/realtime.doc.txt realtime.doc]
* [http://wiki.amigaos.net/amiga/autodocs/requester_cl.doc.txt requester_cl.doc]
* [http://wiki.amigaos.net/amiga/autodocs/resource.doc.txt resource.doc]
* [http://wiki.amigaos.net/amiga/autodocs/rexxsyslib.doc.txt rexxsyslib.doc]
* [http://wiki.amigaos.net/amiga/autodocs/root_cl.doc.txt root_cl.doc]
* [http://wiki.amigaos.net/amiga/autodocs/screenblanker.doc.txt screenblanker.doc]
* [http://wiki.amigaos.net/amiga/autodocs/scroller_gc.doc.txt scroller_gc.doc]
* [http://wiki.amigaos.net/amiga/autodocs/serial_dev.doc.txt serial_dev.doc]
* [http://wiki.amigaos.net/amiga/autodocs/serial.doc.txt serial.doc]
* [http://wiki.amigaos.net/amiga/autodocs/shell.doc.txt shell.doc]
* [http://wiki.amigaos.net/amiga/autodocs/sketchboard_gc.doc.txt sketchboard_gc.doc]
* [http://wiki.amigaos.net/amiga/autodocs/slider_gc.doc.txt slider_gc.doc]
* [http://wiki.amigaos.net/amiga/autodocs/sound_dtc.doc.txt sound_dtc.doc]
* [http://wiki.amigaos.net/amiga/autodocs/space_gc.doc.txt space_gc.doc]
* [http://wiki.amigaos.net/amiga/autodocs/speedbar_gc.doc.txt speedbar_gc.doc]
* [http://wiki.amigaos.net/amiga/autodocs/string_gc.doc.txt string_gc.doc]
* [http://wiki.amigaos.net/amiga/autodocs/sys_ic.doc.txt sys_ic.doc]
* [http://wiki.amigaos.net/amiga/autodocs/tapedeck_gc.doc.txt tapedeck_gc.doc]
* [http://wiki.amigaos.net/amiga/autodocs/textclip.doc.txt textclip.doc]
* [http://wiki.amigaos.net/amiga/autodocs/textclip-handler.doc.txt textclip-handler.doc]
* [http://wiki.amigaos.net/amiga/autodocs/text_dtc.doc.txt text_dtc.doc]
* [http://wiki.amigaos.net/amiga/autodocs/texteditor_gc.doc.txt texteditor_gc.doc]
* [http://wiki.amigaos.net/amiga/autodocs/timer.doc.txt timer.doc]
* [http://wiki.amigaos.net/amiga/autodocs/timesync.doc.txt timesync.doc]
* [http://wiki.amigaos.net/amiga/autodocs/timezone.doc.txt timezone.doc]
* [http://wiki.amigaos.net/amiga/autodocs/trackdisk.doc.txt trackdisk.doc]
* [http://wiki.amigaos.net/amiga/autodocs/translator.doc.txt translator.doc]
* [http://wiki.amigaos.net/amiga/autodocs/usbfd.doc.txt usbfd.doc]
* [http://wiki.amigaos.net/amiga/autodocs/usbhcd.doc.txt usbhcd.doc]
* [http://wiki.amigaos.net/amiga/autodocs/usbresource.doc.txt usbresource.doc]
* [http://wiki.amigaos.net/amiga/autodocs/usbsys.doc.txt usbsys.doc]
* [http://wiki.amigaos.net/amiga/autodocs/utility.doc.txt utility.doc]
* [http://wiki.amigaos.net/amiga/autodocs/version.doc.txt version.doc]
* [http://wiki.amigaos.net/amiga/autodocs/virtual_gc.doc.txt virtual_gc.doc]
* [http://wiki.amigaos.net/amiga/autodocs/warp3d.doc.txt warp3d.doc]
* [http://wiki.amigaos.net/amiga/autodocs/window_cl.doc.txt window_cl.doc]
* [http://wiki.amigaos.net/amiga/autodocs/workbench.doc.txt workbench.doc]
* [http://wiki.amigaos.net/amiga/autodocs/xenares.doc.txt xenares.doc]
* [http://wiki.amigaos.net/amiga/autodocs/z.doc.txt z.doc]

Autodocs:Main

2026-06-09T16:28:51Z

Costel Mincea: Added link to Hyperion download pages

The autodocs are included in the latest [[SDK_FAQ|AmigaOS SDK]] (download from [https://www.hyperion-entertainment.com/index.php/downloads?view=files&parent=30 Hyperion Entertainment]) and are also available as text files below:

* [http://wiki.amigaos.net/amiga/autodocs/a1floppy.doc.txt a1floppy.doc]
* [http://wiki.amigaos.net/amiga/autodocs/a1serial_dev.doc.txt a1serial_dev.doc]
* [http://wiki.amigaos.net/amiga/autodocs/AI_Driver.doc.txt AI_Driver.doc]
* [http://wiki.amigaos.net/amiga/autodocs/amigaguide.doc.txt amigaguide.doc]
* [http://wiki.amigaos.net/amiga/autodocs/amigaguide_dtc.doc.txt amigaguide_dtc.doc]
* [http://wiki.amigaos.net/amiga/autodocs/AmigaInput.doc.txt AmigaInput.doc]
* [http://wiki.amigaos.net/amiga/autodocs/amiga_lib.doc.txt amiga_lib.doc]
* [http://wiki.amigaos.net/amiga/autodocs/animation_dtc.doc.txt animation_dtc.doc]
* [http://wiki.amigaos.net/amiga/autodocs/application.doc.txt application.doc]
* [http://wiki.amigaos.net/amiga/autodocs/arexx_cl.doc.txt arexx_cl.doc]
* [http://wiki.amigaos.net/amiga/autodocs/asl.doc.txt asl.doc]
* [http://wiki.amigaos.net/amiga/autodocs/audio.doc.txt audio.doc]
* [http://wiki.amigaos.net/amiga/autodocs/battclock.doc.txt battclock.doc]
* [http://wiki.amigaos.net/amiga/autodocs/battmem.doc.txt battmem.doc]
* [http://wiki.amigaos.net/amiga/autodocs/bevel_ic.doc.txt bevel_ic.doc]
* [http://wiki.amigaos.net/amiga/autodocs/biosversion.doc.txt biosversion.doc]
* [http://wiki.amigaos.net/amiga/autodocs/bitmap_ic.doc.txt bitmap_ic.doc]
* [http://wiki.amigaos.net/amiga/autodocs/bsdsocket.doc.txt bsdsocket.doc]
* [http://wiki.amigaos.net/amiga/autodocs/btree.doc.txt btree.doc]
* [http://wiki.amigaos.net/amiga/autodocs/bullet.doc.txt bullet.doc]
* [http://wiki.amigaos.net/amiga/autodocs/button_gc.doc.txt button_gc.doc]
* [http://wiki.amigaos.net/amiga/autodocs/camd.doc.txt camd.doc]
* [http://wiki.amigaos.net/amiga/autodocs/cardres.doc.txt cardres.doc]
* [http://wiki.amigaos.net/amiga/autodocs/cd.doc.txt cd.doc]
* [http://wiki.amigaos.net/amiga/autodocs/checkbox_gc.doc.txt checkbox_gc.doc]
* [http://wiki.amigaos.net/amiga/autodocs/chooser_gc.doc.txt chooser_gc.doc]
* [http://wiki.amigaos.net/amiga/autodocs/cia.doc.txt cia.doc]
* [http://wiki.amigaos.net/amiga/autodocs/clicktab_gc.doc.txt clicktab_gc.doc]
* [http://wiki.amigaos.net/amiga/autodocs/clipboard.doc.txt clipboard.doc]
* [http://wiki.amigaos.net/amiga/autodocs/colorwheel_gc.doc.txt colorwheel_gc.doc]
* [http://wiki.amigaos.net/amiga/autodocs/commodities.doc.txt commodities.doc]
* [http://wiki.amigaos.net/amiga/autodocs/console.doc.txt console.doc]
* [http://wiki.amigaos.net/amiga/autodocs/datatypes.doc.txt datatypes.doc]
* [http://wiki.amigaos.net/amiga/autodocs/datebrowser_gc.doc.txt datebrowser_gc.doc]
* [http://wiki.amigaos.net/amiga/autodocs/ddebug_lib.doc.txt ddebug_lib.doc]
* [http://wiki.amigaos.net/amiga/autodocs/debug_lib.doc.txt debug_lib.doc]
* [http://wiki.amigaos.net/amiga/autodocs/diffview_gc.doc.txt diffview_gc.doc]
* [http://wiki.amigaos.net/amiga/autodocs/disk.doc.txt disk.doc]
* [http://wiki.amigaos.net/amiga/autodocs/diskfont.doc.txt diskfont.doc]
* [http://wiki.amigaos.net/amiga/autodocs/diskio.doc.txt diskio.doc]
* [http://wiki.amigaos.net/amiga/autodocs/docky.doc.txt docky.doc]
* [http://wiki.amigaos.net/amiga/autodocs/dos.doc.txt dos.doc]
* [http://wiki.amigaos.net/amiga/autodocs/dos.dospackets.doc.txt dos.dospackets.doc]
* [http://wiki.amigaos.net/amiga/autodocs/dos.obsolete.doc.txt dos.obsolete.doc]
* [http://wiki.amigaos.net/amiga/autodocs/drawlist_ic.doc.txt drawlist_ic.doc]
* [http://wiki.amigaos.net/amiga/autodocs/elf.doc.txt elf.doc]
* [http://wiki.amigaos.net/amiga/autodocs/exec.doc.txt exec.doc]
* [http://wiki.amigaos.net/amiga/autodocs/expansion.doc.txt expansion.doc]
* [http://wiki.amigaos.net/amiga/autodocs/filesysbox.doc.txt filesysbox.doc]
* [http://wiki.amigaos.net/amiga/autodocs/filesysres.doc.txt filesysres.doc]
* [http://wiki.amigaos.net/amiga/autodocs/filler_ic.doc.txt filler_ic.doc]
* [http://wiki.amigaos.net/amiga/autodocs/fillrect_ic.doc.txt fillrect_ic.doc]
* [http://wiki.amigaos.net/amiga/autodocs/frame_ic.doc.txt frame_ic.doc]
* [http://wiki.amigaos.net/amiga/autodocs/frbutton_gc.doc.txt frbutton_gc.doc]
* [http://wiki.amigaos.net/amiga/autodocs/fuelgauge_gc.doc.txt fuelgauge_gc.doc]
* [http://wiki.amigaos.net/amiga/autodocs/gadget_gc.doc.txt gadget_gc.doc]
* [http://wiki.amigaos.net/amiga/autodocs/gadtools.doc.txt gadtools.doc]
* [http://wiki.amigaos.net/amiga/autodocs/gameport.doc.txt gameport.doc]
* [http://wiki.amigaos.net/amiga/autodocs/Gameport_pci.doc.txt Gameport_pci.doc]
* [http://wiki.amigaos.net/amiga/autodocs/gauge_ic.doc.txt gauge_ic.doc]
* [http://wiki.amigaos.net/amiga/autodocs/getcolor_gc.doc.txt getcolor_gc.doc]
* [http://wiki.amigaos.net/amiga/autodocs/getfile_gc.doc.txt getfile_gc.doc]
* [http://wiki.amigaos.net/amiga/autodocs/getfont_gc.doc.txt getfont_gc.doc]
* [http://wiki.amigaos.net/amiga/autodocs/getscreenmode_gc.doc.txt getscreenmode_gc.doc]
* [http://wiki.amigaos.net/amiga/autodocs/glyph_ic.doc.txt glyph_ic.doc]
* [http://wiki.amigaos.net/amiga/autodocs/gradientslider_gc.doc.txt gradientslider_gc.doc]
* [http://wiki.amigaos.net/amiga/autodocs/graphics.doc.txt graphics.doc]
* [http://wiki.amigaos.net/amiga/autodocs/group_gc.doc.txt group_gc.doc]
* [http://wiki.amigaos.net/amiga/autodocs/hunk.doc.txt hunk.doc]
* [http://wiki.amigaos.net/amiga/autodocs/ibutton_gc.doc.txt ibutton_gc.doc]
* [http://wiki.amigaos.net/amiga/autodocs/icon.doc.txt icon.doc]
* [http://wiki.amigaos.net/amiga/autodocs/iconmodule.doc.txt iconmodule.doc]
* [http://wiki.amigaos.net/amiga/autodocs/ic_cl.doc.txt ic_cl.doc]
* [http://wiki.amigaos.net/amiga/autodocs/iffparse.doc.txt iffparse.doc]
* [http://wiki.amigaos.net/amiga/autodocs/image_ic.doc.txt image_ic.doc]
* [http://wiki.amigaos.net/amiga/autodocs/input.doc.txt input.doc]
* [http://wiki.amigaos.net/amiga/autodocs/integer_gc.doc.txt integer_gc.doc]
* [http://wiki.amigaos.net/amiga/autodocs/intuition.doc.txt intuition.doc]
* [http://wiki.amigaos.net/amiga/autodocs/iscroller_gc.doc.txt iscroller_gc.doc]
* [http://wiki.amigaos.net/amiga/autodocs/istring_gc.doc.txt istring_gc.doc]
* [http://wiki.amigaos.net/amiga/autodocs/itext_ic.doc.txt itext_ic.doc]
* [http://wiki.amigaos.net/amiga/autodocs/keyboard.doc.txt keyboard.doc]
* [http://wiki.amigaos.net/amiga/autodocs/keymap.doc.txt keymap.doc]
* [http://wiki.amigaos.net/amiga/autodocs/label_ic.doc.txt label_ic.doc]
* [http://wiki.amigaos.net/amiga/autodocs/layers.doc.txt layers.doc]
* [http://wiki.amigaos.net/amiga/autodocs/layout_gc.doc.txt layout_gc.doc]
* [http://wiki.amigaos.net/amiga/autodocs/libamiga_a.doc.txt libamiga_a.doc]
* [http://wiki.amigaos.net/amiga/autodocs/listbrowser_gc.doc.txt listbrowser_gc.doc]
* [http://wiki.amigaos.net/amiga/autodocs/locale.doc.txt locale.doc]
* [http://wiki.amigaos.net/amiga/autodocs/lowlevel.doc.txt lowlevel.doc]
* [http://wiki.amigaos.net/amiga/autodocs/mathffp.doc.txt mathffp.doc]
* [http://wiki.amigaos.net/amiga/autodocs/mathieeedoubbas.doc.txt mathieeedoubbas.doc]
* [http://wiki.amigaos.net/amiga/autodocs/mathieeedoubtrans.doc.txt mathieeedoubtrans.doc]
* [http://wiki.amigaos.net/amiga/autodocs/mathieeesingbas.doc.txt mathieeesingbas.doc]
* [http://wiki.amigaos.net/amiga/autodocs/mathieeesingtrans.doc.txt mathieeesingtrans.doc]
* [http://wiki.amigaos.net/amiga/autodocs/mathtrans.doc.txt mathtrans.doc]
* [http://wiki.amigaos.net/amiga/autodocs/menu_cl.doc.txt menu_cl.doc]
* [http://wiki.amigaos.net/amiga/autodocs/misc.doc.txt misc.doc]
* [http://wiki.amigaos.net/amiga/autodocs/model_cl.doc.txt model_cl.doc]
* [http://wiki.amigaos.net/amiga/autodocs/narrator.doc.txt narrator.doc]
* [http://wiki.amigaos.net/amiga/autodocs/nonvolatile.doc.txt nonvolatile.doc]
* [http://wiki.amigaos.net/amiga/autodocs/openfirmware.doc.txt openfirmware.doc]
* [http://wiki.amigaos.net/amiga/autodocs/page_gc.doc.txt page_gc.doc]
* [http://wiki.amigaos.net/amiga/autodocs/palette_gc.doc.txt palette_gc.doc]
* [http://wiki.amigaos.net/amiga/autodocs/parallel.doc.txt parallel.doc]
* [http://wiki.amigaos.net/amiga/autodocs/partition_gc.doc.txt partition_gc.doc]
* [http://wiki.amigaos.net/amiga/autodocs/penmap_ic.doc.txt penmap_ic.doc]
* [http://wiki.amigaos.net/amiga/autodocs/performancemonitor.doc.txt performancemonitor.doc]
* [http://wiki.amigaos.net/amiga/autodocs/Picasso96API.doc.txt Picasso96API.doc]
* [http://wiki.amigaos.net/amiga/autodocs/picture_dtc.doc.txt picture_dtc.doc]
* [http://wiki.amigaos.net/amiga/autodocs/pointer_cl.doc.txt pointer_cl.doc]
* [http://wiki.amigaos.net/amiga/autodocs/popupmenu_cl.doc.txt popupmenu_cl.doc]
* [http://wiki.amigaos.net/amiga/autodocs/potgo.doc.txt potgo.doc]
* [http://wiki.amigaos.net/amiga/autodocs/printer.doc.txt printer.doc]
* [http://wiki.amigaos.net/amiga/autodocs/prop_gc.doc.txt prop_gc.doc]
* [http://wiki.amigaos.net/amiga/autodocs/radiobutton_gc.doc.txt radiobutton_gc.doc]
* [http://wiki.amigaos.net/amiga/autodocs/realtime.doc.txt realtime.doc]
* [http://wiki.amigaos.net/amiga/autodocs/requester_cl.doc.txt requester_cl.doc]
* [http://wiki.amigaos.net/amiga/autodocs/resource.doc.txt resource.doc]
* [http://wiki.amigaos.net/amiga/autodocs/rexxsyslib.doc.txt rexxsyslib.doc]
* [http://wiki.amigaos.net/amiga/autodocs/root_cl.doc.txt root_cl.doc]
* [http://wiki.amigaos.net/amiga/autodocs/scroller_gc.doc.txt scroller_gc.doc]
* [http://wiki.amigaos.net/amiga/autodocs/serial_dev.doc.txt serial_dev.doc]
* [http://wiki.amigaos.net/amiga/autodocs/sketchboard_gc.doc.txt sketchboard_gc.doc]
* [http://wiki.amigaos.net/amiga/autodocs/slider_gc.doc.txt slider_gc.doc]
* [http://wiki.amigaos.net/amiga/autodocs/sound_dtc.doc.txt sound_dtc.doc]
* [http://wiki.amigaos.net/amiga/autodocs/space_gc.doc.txt space_gc.doc]
* [http://wiki.amigaos.net/amiga/autodocs/speedbar_gc.doc.txt speedbar_gc.doc]
* [http://wiki.amigaos.net/amiga/autodocs/string_gc.doc.txt string_gc.doc]
* [http://wiki.amigaos.net/amiga/autodocs/sys_ic.doc.txt sys_ic.doc]
* [http://wiki.amigaos.net/amiga/autodocs/tapedeck_gc.doc.txt tapedeck_gc.doc]
* [http://wiki.amigaos.net/amiga/autodocs/textclip.doc.txt textclip.doc]
* [http://wiki.amigaos.net/amiga/autodocs/texteditor_gc.doc.txt texteditor_gc.doc]
* [http://wiki.amigaos.net/amiga/autodocs/text_dtc.doc.txt text_dtc.doc]
* [http://wiki.amigaos.net/amiga/autodocs/timer.doc.txt timer.doc]
* [http://wiki.amigaos.net/amiga/autodocs/timesync.doc.txt timesync.doc]
* [http://wiki.amigaos.net/amiga/autodocs/timezone.doc.txt timezone.doc]
* [http://wiki.amigaos.net/amiga/autodocs/trackdisk.doc.txt trackdisk.doc]
* [http://wiki.amigaos.net/amiga/autodocs/translator.doc.txt translator.doc]
* [http://wiki.amigaos.net/amiga/autodocs/usbfd.doc.txt usbfd.doc]
* [http://wiki.amigaos.net/amiga/autodocs/usbhcd.doc.txt usbhcd.doc]
* [http://wiki.amigaos.net/amiga/autodocs/usbresource.doc.txt usbresource.doc]
* [http://wiki.amigaos.net/amiga/autodocs/usbsys.doc.txt usbsys.doc]
* [http://wiki.amigaos.net/amiga/autodocs/utility.doc.txt utility.doc]
* [http://wiki.amigaos.net/amiga/autodocs/virtual_gc.doc.txt virtual_gc.doc]
* [http://wiki.amigaos.net/amiga/autodocs/warp3d.doc.txt warp3d.doc]
* [http://wiki.amigaos.net/amiga/autodocs/window_cl.doc.txt window_cl.doc]
* [http://wiki.amigaos.net/amiga/autodocs/workbench.doc.txt workbench.doc]
* [http://wiki.amigaos.net/amiga/autodocs/xenares.doc.txt xenares.doc]
* [http://wiki.amigaos.net/amiga/autodocs/z.doc.txt z.doc]

Amiga Hardware Manufacturer ID Registry

2026-03-06T07:29:18Z

Costel Mincea: /* How to Obtain a Manufacturer Number */

__TOC__

= How to Obtain a Manufacturer Number =

Manufacturer's numbers are assigned by the AmigaOS development team. To obtain your unique manufacturer number send a support request to [mailto:support@hyperion-entertainment.com support@hyperion-entertainment.com].

Be sure and include your name and the type of expansion product you are developing.

= Your Manufacturer Number =

Attention hardware manufacturers. If you are developing a hardware expansion product for the Classic Amiga (e.g. 500, 2000, 3000) then you will need to obtain a special manufacturer ID number from the AmigaOS development team to identify your product. This manufacturer number is used by the Amiga to link your hardware with its driver software at boot time.

Your manufacturer number is part of the special protocol that the Amiga uses to automatically configure all expansion devices on the bus without the user having to cut jumpers or adjust dip switches. This is called auto-config.

At start-up time, the system first polls each board in the system and assigns the board its own address space. If it is a memory board, its RAM is linked into the memory free pool. Later in the boot sequence, after DOS is initialized, the binddrivers program is run. Binddrivers will search the directory SYS:Expansion for the drivers that go with the boards.

To do this binddrivers looks in the Tool Type field of all icon files in SYS:Expansion. If the first seven bytes of the Tool Type field are "PRODUCT", then this is an icon file for a driver.

Binddrivers will then attempt to match the drivers it has found with the boards that were found earlier. This is where your manufacturer number comes in.

Your manufacturer number goes in two places. First, it is burned in hex form into the PAL which is part of ALL auto-config expansion products. Second, it appears in ASCII in the Tool Type field of the icon file for your product's driver. By matching these two numbers, the Amiga can automatically configure your board and bind it's software driver into the system as well.

The manufacturer's number is a 16-bit ID which appears in PAL offsets $10-$17. There is also an 8-bit product number which you assign. The product number is for uniquely identifying different products from the same vendor. The product number will appear in PAL offsets $04-$07. This gives you a total of 24 bits to identify each of your products.

These 24 bits of information in the PAL which identify your product are matched against the information in the Tool Type field of all icon files in the SYS:Expansion drawer. For example, suppose you are manufacturer #1019. You have two products, #1 and #2 which both use the same driver. The icon for your driver for these two products would have a Tool Type set to "PRODUCT=1019/1|1019/2". This means: I am an icon for a driver that works with product number 1 or 2 from manufacturer 1019, now bind me. Spaces are not legal. Here are two other examples:

; PRODUCT=1208/11
: is the Tool Type for a driver for product 11 from manufacturer number 1208.

; PRODUCT=1017
: is the Tool Type for a driver for any product from manufacturer number 1017.

For an informal explanation of the auto-configuration process, see the chapter on Software Expansion Architecture from the 2nd Annual Amiga Developer's Conference Notes (available on ADCD 2.1). For the details of timing, power, the PAL equations and PAL address specifications and the expansion library documentation, see sections 3.1 to 3.3 of the A500/A2000 Technical Reference Manual. The original auto-config spec appears in the A1000 Schematics and Expansion Specification.

The auto-config process makes the addition of expansion products to the system very easy. All the user has to do is put the board in any slot and copy the driver from the release disk to his own SYS:Expansion drawer. Everything else is automatic. There are no jumpers or dip switches to set. Best of all, you will get a lot less support calls asking how to make your product work with the XYZ-Corp-battery-backed-clock.

= Notes =

Some notes on hardware manufacturer ID assignment.

* Manufacturer ID numbers are assigned free of charge.
* Please provide the following information when requesting an ID:
*# Name of the company or person
*# Postal address/contact address
*# Name of the contact person, with a corresponding e-mail address
*# A brief description of the kind of products you want to produce
* All ID numbers smaller than 5000 must be considered unsafe because no information exists on which numbers exactly were taken during the time Commodore, Inc. disintegrated.
* ID numbers in the range 8192 to 18841 must be considered unsafe because some hardware developers mistook the numbers assigned to them to be given in hexadecimal format. Hence 0x2000 = 8192 and 0x4999 = 18841.

= Example code =

<syntaxhighlight lang="C" line>
/*-----------------------------------------------*/
/* Here is a short program which will tell you */
/* about the expansion boards configured in your */
/* system without you opening up the machine. */
/* Code by Bill Koester of CATS */
/*-----------------------------------------------*/
#include <libraries/configvars.h>
#include <libraries/expansion.h>

struct ExpansionBase *ExpansionBase;

void cleanup();
void printdev();

int main()
{
struct ConfigDev *MyConfigDev;

/*----------------------------------*/
/* Open the expansion library, */
/* if there is a problem then exit */
/*----------------------------------*/

ExpansionBase =(struct ExpansionBase *) OpenLibrary(EXPANSIONNAME,0);
if(ExpansionBase==NULL)
{
printf("Error opening expansion library!!\n");
cleanup();
exit(0);
}

/*--------------------------------------------*/
/* Use FindConfigDev to get info on the first */
/* expansion board on the list maintained by */
/* Exec. If there are no expansion boards in */
/* the system then exit. */
/*--------------------------------------------*/

MyConfigDev = NULL;

/*--------------------------------------------------*/
/* FindConfigDev(oldConfigDev,manufacturer,product) */
/* oldConfigDev = NULL for the top of the list */
/* manufacturer = -1 for any manufacturer */
/* product = -1 for any product */
/*--------------------------------------------------*/

MyConfigDev = FindConfigDev(NULL,-1,-1);

if(MyConfigDev==NULL)
{
printf("No Configured Devices found!!\n");
cleanup();
exit(0);
}

printdev(MyConfigDev);

/*-----------------------------------*/
/* OK, there is at least one board, */
/* so loop and get the entire list */
/* printing as we go with printdev() */
/*-----------------------------------*/

while(MyConfigDev = FindConfigDev(MyConfigDev,-1,-1))
{
printdev(MyConfigDev);
}
cleanup();
return 0;
}

/*-------------------*/
/* Close up shop... */
/*-------------------*/
void cleanup()
{
if(ExpansionBase)
CloseLibrary(ExpansionBase);
}

/*----------------------------------*/
/* Print out the contents of the */
/* dev structure for this expansion */
/* product. */
/*----------------------------------*/

void printdev(dev)
struct ConfigDev *dev;
{
char buff[200];

printf("Flags = ");
if(dev->cd_Flags==NULL)
printf("NULL ");
if(dev->cd_Flags&CDF_SHUTUP)
printf("CDF_SHUTUP ");
if(dev->cd_Flags&CDF_CONFIGME)
printf("CDF_CONFIGME ");
printf("\n");
printf("Board Address = %x\n",dev->cd_BoardAddr);
printf("Board Size = %d bytes\n",dev->cd_BoardSize);
printf("Slot Address = %d\n",dev->cd_SlotAddr);
printf("Slot Size = %d\n",dev->cd_SlotSize);
printf("Driver code at %x\n",dev->cd_Driver);

printf("er_Type = %x\n",dev->cd_Rom.er_Type);
printf("er_Product = %x\n",dev->cd_Rom.er_Product);
printf("er_Flags = %x\n",dev->cd_Rom.er_Flags);
printf("er_Reserved03 = %x\n",dev->cd_Rom.er_Reserved03);
printf("er_Manufacturer = %x\n",dev->cd_Rom.er_Manufacturer);
printf("er_SerialNumber = %x\n",dev->cd_Rom.er_SerialNumber);
printf("er_InitDiagVec = %x\n",dev->cd_Rom.er_InitDiagVec);
printf("er_Reserved0c = %x\n",dev->cd_Rom.er_Reserved0c);
printf("er_Reserved0d = %x\n",dev->cd_Rom.er_Reserved0d);
printf("er_Reserved0e = %x\n",dev->cd_Rom.er_Reserved0e);
printf("er_Reserved0f = %x\n",dev->cd_Rom.er_Reserved0f);

printf("Hit Return to continue:\n");
gets(buff);
}
</syntaxhighlight>

= Registry =

{| class="wikitable"
! ID (decimal)
! ID (hexadecimal)
! Manufacturer
! Notes
|-
| 1
| 0001
| Micronik
|-
| 211
| 00D3
| Pacific Peripherals/Profex
|-
| 221
| 00DD
| Kupke Computertechnik GmbH
|-
| 256
| 0100
| Memphis
| Originally registered to MacroSystems US
|-
| 512
| 0200
| 3-State Computertechnik
|-
| 513
| 0201
| Commodore (Braunschweig)
|-
| 514
| 0202
| Commodore (West Chester)
|-
| 515
| 0203
| Commodore (West Chester)
| Originally registered to Combitech/Macrosystem
|-
| 756
| 02F4
| Progressive Peripherals & Software
|-
| 767
| 02FF
| Kolff Computer Supplies
|-
| 1001
| 03E9
| Tecmar
|-
| 1002
| 03EA
| Telesys
|-
| 1003
| 03EB
| The Micro-Forge
|-
| 1004
| 03EC
| Kronos/C Ltd.
| Originally registered to Card Co. (Supra)
|-
| 1005
| 03ED
| A-Squared
|-
| 1006
| 03EE
| Comspec Communications
|-
| 1007
| 03EF
| HT Electronics
|-
| 1008
| 03F0
| RDS Software
|-
| 1009
| 03F1
| Anakin Research
|-
| 1010
| 03F2
| MicroBotics
|-
| 1011
| 03F3
| Bob Krauth
|-
| 1012
| 03F4
| Access Associates (Alegra)
|-
| 1013
| 03F5
| Mini Comp Systems Ltd.
|-
| 1014
| 03F6
| Cypress Technology
|-
| 1015
| 03F7
| Fuller Computers
|-
| 1016
| 03F8
| Galaxy Computers
|-
| 1017
| 03F9
| ADA Research
|-
| 1018
| 03FA
| Computer Service Italia
|-
| 1019
| 03FB
| Amigo
|-
| 1020
| 03FC
| Micro-Solutions Inc.
|-
| 1021
| 03FD
| Stacar International
|-
| 1022
| 03FE
| Video Precisions
|-
| 1023
| 03FF
| ASDG, Inc.
|-
| 1025
| 0401
| Ing. Buero Kalawsky
|-
| 1026
| 0402
| Computer Tuning
|-
| 1027
| 0403
| Interplan Unternehmensberatung
|-
| 1028
| 0404
| Imtronics/Memphis
| Originally registered to Peter Ohlich
|-
| 1030
| 0406
| Commodore (Lowell University)
| Originally registered to Productivity Center
|-
| 1041
| 0411
| Design Labs
|-
| 1042
| 0412
| MCS
|-
| 1043
| 0413
| B. J. Freeman
|-
| 1044
| 0414
| Side Effects Inc.
|-
| 1045
| 0415
| Oklahoma Personal Comp.
|-
| 1046
| 0416
| Advanced Micro Innovations
|-
| 1047
| 0417
| Industrial Support Services
|-
| 1048
| 0418
| Technisoft
|-
| 1049
| 0419
| Prolific, Inc.
|-
| 1050
| 041A
| Softeam, Inc.
|-
| 1051
| 041B
| GRC Electronics
|-
| 1052
| 041C
| David Lai
|-
| 1053
| 041D
| Ameristar Technologies
|-
| 1054
| 041E
| Cline Refrigeration
|-
| 1055
| 041F
| Cardiac Pacemakers, Inc.
|-
| 1056
| 0420
| Supra Corp. (Creative Microsystems)
|-
| 1057
| 0421
| Wayne Diener
|-
| 1058
| 0422
| Computer Systems Associates (CSA)
|-
| 1059
| 0423
| Trionix, Inc.
|-
| 1060
| 0424
| David Lucas
|-
| 1061
| 0425
| Analog Precision
| Also assigned to D & L Distributing
|-
| 1267
| 04F3
| RBM Digitaltechnik
|-
| 1282
| 0502
| M-TEC Hardware Design
|-
| 1337
| 0539
| Thomas Stenzel (DaFR34K)
|-
| 1576
| 0628
| Boris Križma
|-
| 1761
| 06E1
| Great Valley Products
|-
| 1803
| 070B
| UAE Amiga Emulator
|-
| 2002
| 07D2
| Mimetics Corp.
|-
| 2003
| 07D3
| ACDA
|-
| 2004
| 07D4
| Finn R. Jacobsen
|-
| 2005
| 07D5
| Elthen Electronics
|-
| 2006
| 07D6
| Nine Tiles Computer Systems Ltd.
|-
| 2007
| 07D7
| Analog Electronics
|-
| 2008
| 07D8
| Bell & Howell
|-
| 2009
| 07D9
| Roland Kochler
|-
| 2010
| 07DA
| Byte Corp.
|-
| 2011
| 07DB
| Reserved
|-
| 2012
| 07DC
| DKB, Inc.
| Previously named Michigan Software
|-
| 2013
| 07DD
| Pacific Peripherals
|-
| 2014
| 07DE
| Sysaphus Software
|-
| 2015
| 07DF
| Digitronics
|-
| 2016
| 07E0
| Akron Systems
|-
| 2017
| 07E1
| Great Valley Products
|-
| 2018
| 07E2
| Calmos
|-
| 2019
| 07E3
| Dover Research
|-
| 2020
| 07E4
| David Krehbiel
|-
| 2021
| 07E5
| Synergy Peripheral Systems
| Also known as California Access
|-
| 2022
| 07E6
| Xetec
|-
| 2023
| 07E7
| Micron Technology
|-
| 2024
| 07E8
| CH Electronics
|-
| 2025
| 07E9
| American Liquid Light
|-
| 2026
| 07EA
| Progressive Peripherals & Software
| Also used by Ateo
|-
| 2027
| 07EB
| Wicat Systems
|-
| 2028
| 07EC
| Applied Systems & Peripherals
|-
| 2029
| 07ED
| Delaware Valley Software
|-
| 2030
| 07EE
| Palomax
|-
| 2031
| 07EF
| Incognito Software
|-
| 2032
| 07F0
| Jadesign
|-
| 2033
| 07F1
| BVR
|-
| 2034
| 07F2
| Spirit Technology
|-
| 2035
| 07F3
| Spirit Technology
|-
| 2036
| 07F4
| Atronic
|-
| 2037
| 07F5
| Scott Karlin
|-
| 2038
| 07F6
| Howitch
|-
| 2039
| 07F7
| Sullivan Brothers Visual Engineers
|-
| 2040
| 07F8
| G I T
|-
| 2041
| 07F9
| Amigo Business Computers
|-
| 2042
| 07FA
| Micro E Ab
|-
| 2043
| 07FB
| Ralph Kruse
|-
| 2044
| 07FC
| Clearpoint Research
|-
| 2045
| 07FD
| Kodiak
|-
| 2046
| 07FE
| BSC
| Originally registered to Phoenix Electronics
|-
| 2047
| 07FF
| No Name Shown
|-
| 2048
| 0800
| Commodore Braunschweig
|-
| 2049
| 0801
| BSC
| Originally registered to Elaborate Bytes
|-
| 2050
| 0802
| Kronos/C Ltd.
|-
| 2051
| 0803
| Spartanics
|-
| 2052
| 0804
| Jochheim Computer Tuning
|-
| 2053
| 0805
| Trans Data Systems
|-
| 2054
| 0806
| Applied Systems & Peripherals Ltd.
|-
| 2055
| 0807
| Checkpoint Technologies
| Originally registered to Amiga Solutions
|-
| 2056
| 0808
| Adept Development
|-
| 2057
| 0809
| Advanced Computer Design
|-
| 2058
| 080A
| Sir Netics
|-
| 2059
| 080B
| Expert Services
|-
| 2060
| 080C
| Digital Art Systems
|-
| 2061
| 080D
| Adept Development
|-
| 2062
| 080E
| Expansion Technologies (Expansion Systems)
|-
| 2063
| 080F
| Alphatech
|-
| 2064
| 0810
| Edotronik GmbH
|-
| 2065
| 0811
| California Access/Synergy
| Originally registered to Logical Design Works
|-
| 2066
| 0812
| Bowden, Williams, Full & Assoc.
|-
| 2067
| 0813
| NES, Inc.
|-
| 2068
| 0814
| Amdev
|-
| 2069
| 0815
| Big Brother Security Systems
|-
| 2070
| 0816
| Active Circuits Inc.
|-
| 2071
| 0817
| ICD, Inc.
|-
| 2072
| 0818
| Multi-Meg Electronique
|-
| 2073
| 0819
| Kupke Computertechnik GmbH
|-
| 2074
| 081A
| The Checkered Ball
|-
| 2075
| 081B
| Hi Tension Computer Services Ltd. (UK)
|-
| 2076
| 081C
| Alfa Data
| Originally assigned to Elmtech Research, Ltd. (UK)
|-
| 2077
| 081D
| Great Valley Products
| Originally registered to Clartscreen, Ltd. (UK)
|-
| 2078
| 081E
| Interworks
|-
| 2079
| 081F
| Galysh Enterprises
|-
| 2080
| 0820
| Hardital Synthesis
| Originally registered to Realtime Games Software Ltd.
|-
| 2081
| 0821
| GBS
|-
| 2082
| 0822
| Circum Design Inc.
|-
| 2083
| 0823
| Alberta Micro Electronic Center
|-
| 2084
| 0824
| Bestech
|-
| 2085
| 0825
| Lasar Fantasy
|-
| 2086
| 0826
| Pulsar
|-
| 2087
| 0827
| Ivis
|-
| 2088
| 0828
| Applied Engineering
|-
| 2089
| 0829
| Solid-State Design & Development
|-
| 2090
| 082A
| Vison Quest
|-
| 2091
| 082B
| Seaview Software
|-
| 2092
| 082C
| BSC
| Mistakenly used by ADS (Advanced Development Software)
|-
| 2093
| 082D
| Bernd Culenfeld
|-
| 2094
| 082E
| American Liquid Light
|-
| 2095
| 082F
| CEGITES
|-
| 2096
| 0830
| Quadlite Computers Ltd.
| Originally registered to EV Industries
|-
| 2097
| 0831
| Silicon Peace
|-
| 2098
| 0832
| Black Belt Systems
|-
| 2099
| 0833
| Village Tronic
| Originally registerd to Steve Yaeger
|-
| 2100
| 0834
| ReadySoft
|-
| 2101
| 0835
| Phoenix Micro Technologies
|-
| 2102
| 0836
| Advanced Systems & Software
| Orignally assigned to Preferred Technology
|-
| 2103
| 0837
| Rombo Productions
|-
| 2104
| 0838
| Impulse Inc.
|-
| 2105
| 0839
| Beta Unlimited
|-
| 2106
| 083A
| Memory Expansion System, Ltd.
|-
| 2107
| 083B
| Vortex Computer Systems GmbH
|-
| 2108
| 083C
| Platypus Systems
|-
| 2109
| 083D
| Gigatron OHG
|-
| 2110
| 083E
| PG Electronics
|-
| 2111
| 083F
| New Technologies Group
|-
| 2112
| 0840
| Interactive Video Systems (IVS)
| Pacific Peripherals
|-
| 2113
| 0841
| Vector
| Originally registered to H. K. Computer
|-
| 2114
| 0842
| Pacific Digital
| Originally registered to C. H. Helfrich Elektronik
|-
| 2115
| 0843
| Xanadu
|-
| 2116
| 0844
| Pacific Digital
| Originally registered to AMS
|-
| 2117
| 0845
| X-Pert
|-
| 2118
| 0846
| The Amiga Centre
|-
| 2119
| 0847
| Digital Pacific
|-
| 2120
| 0848
| Solid State Leisure
|-
| 2121
| 0849
| Hydra Systems
| Originally registered to Analog Electronics
|-
| 2122
| 084A
| Cumana
|-
| 2123
| 084B
| KAPS 2C Conception
|-
| 2124
| 084C
| Mike Mason
|-
| 2125
| 084D
| For Your Eyes
|-
| 2126
| 084E
| Volkmar Breitfeld Computersysteme
|-
| 2127
| 084F
| Sunrize Industries
|-
| 2128
| 0850
| Scott Advanced Micro Designs
|-
| 2129
| 0851
| Digital Micronics
|-
| 2130
| 0852
| Alfa-Laval
|-
| 2131
| 0853
| Multigros A/S
|-
| 2132
| 0854
| Archos
|-
| 2133
| 0855
| Icom Simulations
|-
| 2134
| 0856
| Commodore Test Engineering Group
|-
| 2135
| 0857
| Microcreations
|-
| 2136
| 0858
| Shoestring Productions
|-
| 2137
| 0859
| Faberushi
|-
| 2138
| 085A
| Evesham Micro Ltd.
|-
| 2139
| 085B
| Panagolin Laser Software
|-
| 2140
| 085C
| Thomas Rudloff
|-
| 2141
| 085D
| Daniel Hohabir
|-
| 2142
| 085E
| GfxBase, Inc.
|-
| 2143
| 085F
| Axellabs
|-
| 2144
| 0860
| Roctec Electronics Inc.
|-
| 2145
| 0861
| Omega Datentechnik
|-
| 2146
| 0862
| Atlantis
|-
| 2147
| 0863
| Skytec Computers
|-
| 2148
| 0864
| Protar Electronics
|-
| 2149
| 0865
| ACS
|-
| 2150
| 0866
| Software Results Enterprises
| Originally registered to University of Illinois
|-
| 2151
| 0867
| Infinity Systems Design Group
|-
| 2152
| 0868
| Trade It
|-
| 2153
| 0869
| Suntec, Inc.
|-
| 2154
| 086A
| DJW Micro Systems
| Originally registered to Tritec Marketing
|-
| 2155
| 086B
| Power Computing Ltd.
|-
| 2156
| 086C
| MacroSystems
|-
| 2157
| 086D
| Masoboshi GmbH (DCE)
|-
| 2158
| 086E
| HAL Software Hardware Handel
|-
| 2159
| 086F
| Mainhattan Data
| Originally registered to Michael Lamm Computersysteme
|-
| 2160
| 0870
| Digital Processing System
| Originally registered to bbdp Electronics
|-
| 2161
| 0871
| Blue Ribbon Soundworks
| Originally registered to Design Computer Systems
|-
| 2162
| 0872
| XPert
| Originally registered to The Station
|-
| 2163
| 0873
| DelaComp
| Originally registered to Bryan Williams
|-
| 2164
| 0874
| Superformance Computer Engineering GmbH
|-
| 2165
| 0875
| Overland Engineering
|-
| 2166
| 0876
| Thomas Hamren
|-
| 2167
| 0877
| Village Tronic
|-
| 2168
| 0878
| Toolbox Design
|-
| 2169
| 0879
| Digital Processing System
|-
| 2170
| 087A
| Superformance
|-
| 2171
| 087B
| Utilities Unlimited
|-
| 2172
| 087C
| phase 5
|-
| 2173
| 087D
| Juergen Kommos
|-
| 2174
| 087E
| Electronic Design
|-
| 2175
| 087F
| James Cook University of North Queensland
|-
| 2176
| 0880
| AmiTrix Development
|-
| 2177
| 0881
| Ferranti
|-
| 2178
| 0882
| Leviathan Development
|-
| 2179
| 0883
| United Video Inc.
|-
| 2180
| 0884
| GPSoft Pty. Ltd.
| Originally registered to Juergen Kommos
|-
| 2181
| 0885
| ArMAX
| Oliver Bausch
|-
| 2182
| 0886
| CP Computer
|-
| 2183
| 0887
| AMOK - Amiga Module & Oberon Klub
|-
| 2184
| 0888
| ITEK Neser & Sieber GbR
|-
| 2185
| 0889
| Phillip C. Lello
|-
| 2186
| 088A
| Cyborg Design Services
|-
| 2187
| 088B
| G2 Systems
|-
| 2188
| 088C
| Pro System Computersysteme
|-
| 2189
| 088D
| ZEUS Electronic
| Originally registered to MSPI (Markt & Technik)
|-
| 2190
| 088E
| Altatech
|-
| 2191
| 088F
| NewTek
|-
| 2192
| 0890
| M-TEC Hardware Design
| Originally registered to Hardware Design Udo Neuroth
|-
| 2193
| 0891
| Great Valley Products
| Originally registered to Viona Development
|-
| 2194
| 0892
| Amitek
| Originally assigned to Marpet Developments
|-
| 2195
| 0893
| Ingenieurbuero Helfrich
|-
| 2196
| 0894
| The Neo Group
|-
| 2197
| 0895
| Cyon
|-
| 2198
| 0896
| Bob Research Group
|-
| 2199
| 0897
| Richmond Sound Design Ltd.
|-
| 2200
| 0898
| US Cybernetics
|-
| 2201
| 0899
| Fulvio Ieva
|-
| 2202
| 089A
| Silicon Studio
|-
| 2203
| 089B
| MacroSystems (USA)
| Was named Micro System Devices
|-
| 2204
| 089C
| Conspector Entertainment
|-
| 2205
| 089D
| Laserforum
|-
| 2206
| 089E
| Elbox Computer
| Mistakenly used by Index Information Ltd.
|-
| 2207
| 089F
| Applied Magic Inc.
|-
| 2208
| 08A0
| SDL Ltd.
|-
| 2560
| 0A00
| Harms
|-
| 2588
| 0A1C
| A1K.org Community
|-
| 2640
| 0A50
| Micronik
|-
| 3084
| 0C0C
| Team 4
|-
| 3643
| 0E3B
| E3B
| Michael Boehmer
|-
| 3855
| 0F0F
| Micronik
|-
| 4096
| 1000
| MegaMicro
|-
| 4110
| 100E
| DigiFeX
|-
| 4136
| 1028
| Imtronics/Memphis
|-
| 4149
| 1035
| PROTAR
|-
| 4369
| 1111
| Frank Strauß Elektronik
| Also used by Kupke
|-
| 4626
| 1212
| Individual Computers
|-
| 4648
| 1228
| Flesch Hornemann Computer Elec.
|-
| 4680
| 1248
| Kupke Computertechnik GmbH
|-
| 4711
| 1267
| RBM digitaltechnik
|-
| 4754
| 1292
| MacroSystems
|-
| 5000
| 1388
| ITH
|-
| 5001
| 1389
| VMC
|-
| 5010
| 1392
| Ambience Creation Technology
|-
| 5011
| 1393
| Creative Development
|-
| 5012
| 1394
| Georg Braun
|-
| 5013
| 1395
| Swedish User Group of Amiga
|-
| 5014
| 1396
| Jakub Bednarski
|-
| 5015
| 1397
| KryoFlux, Ltd.
|-
| 5016
| 1398
| Igor Majstorovic
|-
| 5017
| 1399
| Alastair M. Robinson
|-
| 5018
| 139A
| Austex Software
|-
| 5019
| 139B
| Sören Gust
|-
| 5020
| 139C
| Rok Krajnc
|-
| 5030
| 13A6
| Tim Tashpulatov
|-
| 5040
| 13B0
| 7-bit
|-
| 5050
| 13BA
| Sakura IT
|-
| 5060
| 13C4
| FPGAArcade
|-
| 5070
| 13CE
| CancerSoft Inc.
|-
| 5080
| 13D8
| Stephen Leary
|-
| 5090
| 13E2
| DMA Softlab LLC
|-
| 5100
| 13EC
| Brookhouse Engineering
|-
| 5110
| 13F6
| Eduardo Arana
|-
| 5120
| 1400
| CS-LAB
|-
| 5130
| 140A
| Robert Miranda
|-
| 5140
| 1414
| RastPort
|-
| 5132
| 140C
| UAS Interface Ltd6
|-
| 5150
| 141E
| Amiga Kit
|-
| 5160
| 1428
| Central Texas Commodore User Group
|-
| 5170
| 1432
| Confusion Research Center
|-
| 5180
| 143C
| Solar Soyuz Zaibatsu
|-
| 5500
| 157C
| Inhouse Information
|-
| 5768
| 1688
| Bio Con
|-
| 6148
| 1804
| HK-Computer
|-
| 6502
| 1966
| Cloanto
|-
| 6520
| 1978
| Oliver Gantert
|-
| 7777
| 1E61
| Rafal Gabriel Chyla
|-
| 8215
| 2017
| Vortex
|-
| 8244
| 2034
| Spirit Technology
|-
| 8290
| 2062
| Expansion Systems
|-
| 8448
| 2100
| ReadySoft
|-
| 8512
| 2140
| Phase 5 Digital Products
|-
| 8553
| 2169
| Digital Processing Systems Inc.
|-
| 8704
| 2200
| ACT Elektronik
|-
| 8738
| 2222
| ACT Elektronik
|-
| 9512
| 2528
| Tower Technologies
|-
| 10676
| 29B4
| Electronic Design
|-
| 14195
| 3773
| Media-net-Point
|-
| 14501
| 38A5
| Petsoff, Finland
|-
| 16375
| 3FF7
| Uwe Gerlach
|-
| 16707
| 4143
| Ateo Concepts
|-
| 16708
| 4144
| ALiENDESiGN
|-
| 16945
| 4231
| A.C.T.
|-
| 17740
| 454C
| HK-Computer (ELSAT)
|-
| 18260
| 4754
| MacroSystems (Germany)
|-
| 19796
| 4D54
| Markt & Technik
|-
| 22359
| 5757
| Markt & Technik
|-
| 26464
| 6760
| Combitec
|-
| 26470
| 6766
| Combitec
|-
| 28014
| 6D6E
| MNT Media and Technology UG
|-
| 32768
| 8000
| M.A.S.T.
|-
| 42240
| A500
| Aethreum Digital
|-
| 43437
| A9AD
| Reis-Ware
|-
| 43521
| AA01
| Cameron
|-
| 43537
| AA11
| Reis-Ware
|-
| 44359
| AD47
| Matay
|-
| 46504
| B5A8
| Phoenix
|-
| 49160
| C008
| Combitec
|-
| 61453
| F00D
| Forefront Technologies Inc.
|}

For any changes/additions to this registry please use the [http://www.amigaos.net/contact AmigaOS web site contact form].

AmigaOS Manual: AmigaDOS Using the Editors

2026-02-12T07:21:56Z

Costel Mincea: /* EDIT */ Set the defaults of PREVIOUS and WIDTH to new 4.1 Final Edition Update 3 values

A text editor or word processing program is necessary for creating or editing text files and script files. Amiga Workbench software comes with three text editors. This chapter describes them in the following order:

* ED
* MEmacs
* EDIT

Each of the Amiga editors can be used separately for editing AmigaDOS scripts and programs; ED and MEmacs can be used for creating these files. If you are comfortable with the UNIX Emacs editor, you may prefer using the MEmacs editor. If you need to edit files containing binary code or you need to edit files too large to fit into memory, use EDIT. If you are not familiar with any of the editors, we recommend that you use the ED editor.

Each editor has the basic functionality of a word processor, however, none of these editors support style formatting options, such as italics, page numbering, or different fonts. If you need these features, you can purchase third party word processing software containing such features for your Amiga.

= ED =

ED is a full screen ASCII text editor that uses menus and function keys to access its features. It is easy to use and is suitable for editing scripts, startup files, MountLists, and other simple files. Use either a mouse or the keyboard to perform operations with ED. Although ED's menus are preprogrammed, when you are familiar with the program, you can reconfigure them as needed.

{{Note|ED does not accept files containing binary code. To edit this type of file, use EDIT or MEmacs.}}

The bottom line of the ED window is the status line used for displaying messages, prompts, and commands. Error messages displayed on the status line remain until you enter another ED command. Figure 4-1 illustrates the ED window showing the status line.

[[File:DosFig4-1.png|none|frame|ED Window with Status Line]]

== Starting ED ==

Start ED from a Shell or with the Workbench Execute Command menu item. Open ED at the prompt by entering ED and a new or existing file name, as follows:

1> ED <filename>

where <filename> is the name of an existing file or a new file to be used for saving your work. If the file name specified cannot be found in the current directory, ED opens a blank window and displays the message Creating new file.

The format for ED is the following:

<nowiki>ED [FROM] <filename> [SIZE <n>] [WITH <filename>]
[WINDOW <window specification>] [TABS <n>] [WIDTH | COLS <n>]
[HEIGHT | ROWS <n>]</nowiki>

The FROM argument specifies the source file to be edited. This argument is required, but the FROM keyword is optional.

The SIZE argument changes the ED buffer size. ED has a default text buffer size of 40,000 bytes. For example:

1> ED Script SIZE 55000

increase the size of the buffer to 55,000 bytes.

The WITH argument specifies an ED command file that can contain any sequence of ED extended mode commands. When WITH is specified, ED executes the commands contained in the command file. The WITH argument's keywords is required if you use WITH.

The WINDOW argument specifies the console type, such as RAX:0/0/640/256/EdWindow or CONSOLE:. The WINDOW argument's keyword is required if you use WINDOW.

TABS sets the tab stop interval, which is the number of spaces to the right that the cursor moves when you press the Tab key. The default value for TABS is 3.

The WIDTH and HEIGHT arguments adjust the size of the ED window by specifying the number of characters to display horizontally and vertically. By default the ED window is 640 x 200 picels or approximately 88 characters wide by 21 lines high.

== Using ED ==

All ED commands have key sequences and many are available through menus. You can enter ED commands in either of the following ways:

* By choosing the command's menu item.
* By typing in the command's key sequence and pressing Return.

In addition, you can use the mouse to perform some commands, such as those that control cursor movement.

You can work on files in ED with the following two command modes:

; Immediate
: Commands are executed as soon as typed. EP opens in immediate mode.

; Extended
: Commands are not executed until you press Return or Esc.

=== Immediate Commands ===

In immediate mode, ED executes commands right away. Specify an immediate command by pressing a single key or Ctrl+key combination or by using the mouse. All immediate commands have corresponding extended versions.

Immediate commands control the following:

* Cursor movement
* Text scrolling
* Text insertion
* Text deletion
* Repetition of commands

=== Moving the Cursor in Immediate Mode ===

The cursor can be positioned anywhere in text by moving the pointer to the desired spot and clicking the selection button. To move the cursor with the keyboard, use the arrow keys, Tab, and Ctrl+key combinations.

{{Note|In ED, the Tab key only moves the cursor. It does not insert Tab characters or spaces in a line.}}

Move the cursor one position in any direction by pressing the appropriate arrow key. If the cursor is on the right edge of the screen, ED scrolls the text to the left do display the rest of the line. ED scrolls the text vertically one line at a time and horizontally ten characters at a time. You cannot move the cursor beyond the left edge of the line. If you try to move the cursor beyond the top or bottom of the file, ED displays a Top of File or Bottom of File message.

Additional key combinations that control cursor movement are:

{| class="wikitable"
| Shift+up arrow || Top of the file.
|-
| Shift+down arrow || Bottom of the file.
|-
| Shift+left arrow || Left edge of the ED window (regardless of the margin setting).
|-
| Sift+right arrow || End of the current line.
|-
| Ctrl+] || Right edge of current line (if cursor is already there, it is moved to the left edge).
|-
| Ctrl+E || Start of the first line on the screen (if cursor is already there, it is moved to the end of the last line on the screen).
|-
| Ctrl+T || Start of the next word.
|-
| Ctrl+R || Space following the previous word.
|-
| Tab || The next tab position (multiple of the TABS value; 3 by default).
|}

If your file has more lines than can fit in the ED window, you can scroll through the file vertically. Scroll one line at a time by pressing the up or down cursor key to move in the corresponding direction. Move the text in jumps by pressing:

{| class="wikitable"
| Ctrl+D || Moves 12 lines down through the file.
|-
| Ctrl+U || Moves 12 lines up through the file.
|}

These commands do not move the cursor position in the window; they redraw the text in the window with the new line at the cursor position.

If something disturbs your screen, such as an alert from another program appearing in the ED window or message remarks in the status line, press:

{| class="wikitable"
| Ctrl+V || Refreshes the window display.
|}

=== Inserting Text in Immediate Mode ===

Any characters typed in immediate mode are inserted at the current cursor position and the cursor is shifted to the right. Any characters to the right of the cursor are shifted to make room for new text. If the line is wider than the width of the window, the window scrolls to the right to show what you are typing. If you move the cursor beyond the end of the line, ED inserts spaces between the end of the line and any new characters inserted.

There is maximum limit of 255 characters in a line. If you add more characters, ED displays a Line Too Long message.

To split the current line at the cursor, press Return. Any text to the left of the cursor remains on the original line. All text under and to the right of the cursor moves down onto a new line. Pressing Return at the end of the line creates a new blank line.

=== Deleting Text in Immediate Mode ===

ED has no type over mode. To replace a word or line, you must delete the existing words and insert new information with the following keys and key combinations:

{| class="wikitable"
| Backspace || Deletes the character to the left of the cursor.
|-
| Del || Deletes the character highlighted by the cursor.
|-
| Ctrl+O || If the cursor is over a space, all spaces up to the next character are deleted. If the cursor is over a character, all characters up to the next space are deleted.
|-
| Ctrl+Y || Deletes all characters from the cursor to the end of the line.
|}

When text is deleted, any characters remaining on the line shift to the left and any text beyond the right edge of the screen becomes visible.

=== Changing Case in Immediate Mode ===

You can change the case of text by positioning the cursor and pressing Ctrl+F. If the letter is lower case, it becomes upper case and vice versa. Ctrl+F does not change non-alphabetic characters or symbols.

After you press Ctrl+F, the cursor moves to the right. You can hold down Ctrl+F to repeat the command until you change all the letters on the line.

=== Extended Commands ===

In extended mode, commands are displayed on the command line - or status line - at the bottom of the window. ED does not execute these commands until you press Return or Esc. If you use Esc to execute extended commands, ED remains in extended mode. If you use Return to execute extended commands, ED returns to immediate mode.

Extended commands manage the following:

* Program control
* Cursor movement
* Text modification
* Block control
* Searching and exchanging text

To enter extended mode, press Esc. An asterisk appears as a prompt in the status line. Extended commands consist of one or two characters. Multiple extended commands can be typed on a single command line by separating them with a semicolon. Commands can be grouped together for ED to repeat automatically. Use Backspace to correct mistakes.

You can also execute commands through the programmable menu and function keys. Reconfigure the menus and functions keys by assigning a command to the key or menu item of your choice as described on page 4-21.

=== Using String Delimiters ===

In some cases, commands require arguments, such as a number or a text strig. A string argument for an ED command must be enclosed in a pair of identical delimiter characters. In unambiguous situations you may omit the trailing delimiter. Valid delimiters include ", /, \, !, :, +, -, and %. You cannot use the same delimiter character inside your string. Invalid delimiter characters include letters, numbers, spaces, semicolons, question marks, brackets, and control characters.

=== Using a File Requester ===

You can also ask ED to use a file requester, allowing you to view the contents of the drives and directories in your system.

To invoke a file requester for a load or save command, you must place a question mark (?) before the required string argument. Be sure to include a space before the question mark (for example, sa ?/Text/). Normally, when a command is followed by a string. ED treats the string as the file to be loaded or saved and attempts the operation immediately. However, the question mark indicates that you want to specify the file through a file requester. You must still specify a string after the question mark, but the string becomes the text that appears in the file requester title bar.

== ED Menus ==

ED has two sets of command menu assignments: default and expanded. The default menu assignments, as illustrated in Figure 4-2, are set up by the S:Ed-startup file, which is automatically executed each time you run ED. The S:Ed-startup file is a command file of ED extended mode commands, without the Escape characters. You can edit this file to set up custom menus, as described on page 4-21, or define preprogrammed function key assignments with the Set FN Key menu item.

[[File:DosFig4-2.png|none|frame|Default Menu Assignments]]

=== Enabling Expanded Menus ===

The expanded command menu assignments, as illustrated in Figure 4-3, can be enabled by renaming or deleting the default S:Ed-startup file. If ED cannot find a file named S:Ed-startup, it opens with the expanded set of menus, providing more options.

[[File:DosFig4-3.png|none|frame|Expanded Menu Assignments]]

Rather then deleting your S-Ed-startup file, we recommend that you rename it as follows:

# In the Workbench window, go to the Window menu and select Show All Files.
# Double-click on the S drawer icon.
# Click on the Ed-startup icon.
# Go to the Icons menu and choose Rename.
# Delete the name in the Rename requester's New Name text gadget and enter a new name for Ed-startup.
# Select OK.

You can also create your own customized file of startup options. Avoid including Quit commands in the S:Ed-startup file since they can cause ED to quit immediately after opening.

The menu items in both the default and expanded menus have the same function regardless of which set you use. All of the ED commands are available through the keyboard using extended mode commands even if they do not appear in any menu.

The following sections describe the menu items found in the expanded menus and their corresponding extended and immediate mode commands. An ellipsis (...) indicates that an argument is required or that a menu item opens a requester or prompt.

=== Project Menu ===

The following are the expanded Project menu items:

{| class="wikitable"
| New || Esc,N,W || Creates a new file, replacing the existing file. The message Edits will be lost-type Y to confirm: is displayed. Press any key (except Y) to abort the command.
|-
| Open... || Esc,O,P... || Opens a file. Specify the file by entering the path to the file as a properly delimited string. (If slashes appear in the path to a file, do not use the slash as a delimiter.) The message Edits will be lost-type Y to confirm: reminds you that you are replacing the current file.
|-
| Insert File... || Esc,I,F... || Inserts a file into the current file. ED reads into memory the specified file at the point immediately following the current line.
|-
| Write Block... || Esc,W,B... || Writes the currently marked block to a specified file. ED overwrites any other files with that name and copies the block to the file.
|-
| Save || Esc,S,A || Saves the text to the current file, overwriting the existing text in the file. Use Save As to save to different file. SA followed by Q is equivalent to the X command.
|-
| Save As... || Esc,S,A... || Saves the text to the specified file name.
|-
| Save & Exit || Esc,X || Exits ED, saving the current file to the designated file name. ED writes the text it is holding in memory to the file that was specified when ED was opened and then terminates.
|-
| About || Esc,S,H || Shows the current state of the editor. The screen display information, such as the value of tab stops, current margins, block marks, and the name of the file being edited.
|-
| Quit || Esc,Q || Exits ED without saving changes. If you made any changes to the file, ED asks if you want to quit. If you press Y, ED terminates immediately without saving the changes to the file.
|}

=== Edit Menu ===

The following are commands used for editing:

{| class="wikitable"
| Undo Line || Esc,U || Reverses changes made to the current line. However, ED cannot undo a line deletion. Once you have moved from the current line, the U command cannot undo a change.
|-
| Star Block || Esc,B,S || Identify the beginning and end of a block of text. To specify a block of text to be moved, inserted, or deleted, place the cursor on the first line that you want in the block and enter the BS command. Move the cursor to the last line that you want in the block and enter the BE command. You cannot start or finish a block in the middle of a line.
|-
| Show Block || Esc,S,B || Redraws the display so the block is at the top of the screen.
|-
| Insert Block || Esc,I,B || Inserts a copy of the block after the current line. The block remains defined until you change the text. Use IB to insert copies of the block throughout the document.
|-
| Delete Block || Esc,D,B || Deletes a block.
|-
| Delete Line || Esc,D Ctrl+B || Deletes the entire line.
|}

=== Movement Menu ===

The following commands move the cursor around the screen:

{| class="wikitable"
| Top || Esc,T || Top of the file; first line of the file is brought to the top of the window.
|-
| Bottom || Esc,B || Bottom of the file; last line of the file is brought to the bottom of the window.
|-
| Go To Line... || Esc,M... || Move the cursor to the specified line. Enter the line number on the status line and press Return. The line specified is brought to the top of the window. If no number is given, the cursor goes to the top of the window.
|-
| Next Page || Esc,P,D Ctrl+D || Go to next page.
|-
| Previous Page || Esc,P,U Ctrl+U || Go to previous page.
|}

=== Search Menu ===

The following commands let you search through the file for specific instances of text. You can substitute one pattern of text with another (search and replace) and have ED request confirmation of (query) each replace. If the specified text is not found or there are no more instances of the text, the message Search failed is displayed. When using the Find and Replace menu commands, ED prompts for the text strings. Enter the text without delimiters. When using extended mode, include delimited strings with the command.

{| class="wikitable"
| Find... Find Next || Esc,s... || Finds the next occurrence of the specified string of text. The search starts one character beyond the current cursor position and continues forward through the file. If the string is found, the cursor moves to the start of the located string. The search is case-sensitive, unless the Ignore Case command is used. Find Next repeats the command.
|-
| Reverse Find... Reverse Find Next || Esc,B,F... || Searches backwards through the file for the specified string. This command finds the last occurrence of the string before the current cursor position. The search continues through to the beginning of the file. Reverse Find Next repeats the command.
|-
| Replace... || Esc,E... || Exchanges one occurrence of text with another. In extended mode, enter the strings enclosed by three delimiters. For example, to replace the word to with too, enter "to"too". Specify empty strings by typing two delimiters with nothing between them. If the first string is empty, ED inserts the second string at the current cursor position. If the second string is empty, ED searches for the next occurrence of the first string and then deletes it. Note that ED ignores margin settings when exchanging text.
|-
| Global Replace || Esc,R,P,E... || Exchanges all occurrences of text.
|-
| Query-Replace... || Esc,E,Q... || Searches for the text to be exchanged and requests verification by displaying Exchange?. Enter Y to exchange or another other key to abort.
|-
| Global Query-Replace... || Esc,R,P,E,Q... || Searches for all occurrences of the text to be exchanged and requests verification for each. Enter Y to exchange or any other key to abort.
|}

=== Settings Menu ===

The following commands are used for setting up your ED environment:

{| class="wikitable"
| Set FN Key... || Esc,S,F... || Defines the function keys and other programmable keys. Defining function key and Ctrl+key commands is similar to defining menu items. See page 4-15 for instructions for defining function keys and an example of the Set FN Key command.
|-
| Show FN Key... || Esc,D,F <nowiki><key></nowiki> || Displays the setting for the function key specified by <nowiki><key></nowiki>. Enter a space and a key slot number for <nowiki><key></nowiki>.
|-
| Reset Keys || Esc,R,K || Resets the key definitions to the default. See page 4-16 for a table of special key mappings.
|-
| Right Margin... || Esc,S,R... || Sets the right margin. Use the SR command followed by a number indicating the column position.
|-
| Left Margin... || Esc,S,L... || Sets the left margin. Use the SL command followed by a number indicating the column position. The left margin should not be set beyond the right edge of the screen.
|-
| Ignore Case || Esc,U,C || Specifies a case-insensitive search. UC instructs all subsequent searches not to make any distinction between upper and lower case next. To make searches case-sensitive again, use the LC command.
|-
| Case Sensitive || Esc,L,C || Specifies a case-sensitive search.
|}

=== Set FN Key ===

Set FN Key is used to define function keys and other programmable keys. There are 57 immediate command key slots ranging from 1 to 57. Any slot number can be redefined and any numbers within the range that do not appear in the special key mappings on page 4-16 are not defined.

The following is the syntax for the Set FN Key command:

SF <slot number> /command string/

Define Ctrl+key combinations by substituting a caret (^) and the other character for the slot number.

==== Example Script ====

This example script assigns function keys to cursor control commands. You can also enter these as a series of extended mode commands. The Top of File, Bottom of File, End of Page, Next Page, Next Line, and Previous Line commands are assigned to the F1 through F6 keys, respectively. Quotation marks are used as delimiters.

SF 1 "t"
SF 2 "b"
SF 3 "ep"
SF 4 "pd"
SF 5 "n"
SF 6 "p"

=== Special Key Mappings ===

The following table shows the default key definitions used in the Reset Keys command:

{| class="wikitable"
! Slot# !! Key/Key Sequence !! Function
|-
| 1-10 || F1 through F10 || Not defined
|-
| 11-20 || Shift+F1 to Shift+F10 || Not defined
|-
| 21 || Shift+left arrow || Move to beginning of line
|-
| 22 || Shift+right arrow || Move to end of line
|-
| 23 || Shift+up arrow || Move to top of document
|-
| 24 || Shift+down arrow || Move to bottom of document
|-
| 25 || Del || Delete character at cursor
|-
| 26 || Not defined || Not defined
|-
| 27 || Ctrl+A || Insert line
|-
| 28 || Ctrl+B || Delete line
|-
| 29 || Ctrl+C || Not defined
|-
| 30 || Ctrl+D || Move down 12 lines
|-
| 31 || Ctrl+E || Move to top or bottom of screen
|-
| 32 || Ctrl+F || Change case
|-
| 33 || Ctrl+G || Repeat last extended command line
|-
| 34 || Ctrl+H || Delete character left of cursor
|-
| 35 || Ctrl+I || Move cursor to next tab position
|-
| 36 || Ctrl+J || Not defined
|-
| 37 || Ctrl+K || Not defined
|-
| 38 || Ctrl+L || Not defined
|-
| 39 || Ctrl+M || Return
|-
| 40 || Ctrl+N || Not defined
|-
| 41 || Ctrl+O || Delete word or spaces
|-
| 42 || Ctrl+P || Not defined
|-
| 43 || Ctrl+Q || Not defined
|-
| 44 || Ctrl+R || Move to end of previous word
|-
| 45 || Ctrl+S || Not defined
|-
| 46 || Ctrl+T || Move start of next word
|-
| 47 || Ctrl+U || Move up 12 lines
|-
| 48 || Ctrl+V || Redisplay window
|-
| 49 || Ctrl+W || Not defined
|-
| 50 || Ctrl+X || Not defined
|-
| 51 || Ctrl+Y || Delete to end of line
|-
| 52 || Ctrl+Z || Not defined
|-
| 53 || Ctrl+[ || Esc (enter extended command mode)
|-
| 54 || Not defined || Not defined
|-
| 55 || Ctrl+] || Move to end or start of line, depending on cursor position
|-
| 56 || Not defined || Not defined
|-
| 57 || Not defined || Not defined
|}

=== Command Menu ===

The following commands are for manipulating files:

{| class="wikitable"
| Extended Command... || Esc,C,M... || Enters extended command mode; equivalent to pressing Ctrl+[ or Esc.
|-
| Repeat Last || Esc,R,E || Attempts to repeat the last command.
|-
| Run File... || Esc,R,F... || Loads and executes a command file of extended mode commands.
|-
| ARexx Command... || Esc,R,X... || Runs the specified ARexx program.
|-
| Redisplay || Esc,V,W || Redraws the ED window and clears the status line; equivalent to pressing Ctrl+V.
|}

=== Other ED Commands ===

There are also ED commands that do not appear in menus. These commands are listed here in functional groups. Use them in extended mode by entering the following key sequences.

==== Program Control ====

The following are program control commands:

{| class="wikitable"
| Extend Margins || Esc,E,X || Extends the margins for the current line. Once you enter the EX command, ED ignores the right margin on the current line.
|-
| Status Line Message || Esc,S,M... || Prints a given string on the status line.
|-
| Exit with Query || Esc,X,Q || Exits ED unless changes were made to the file. If changes have been made, the message File has been changed-type Y to save and exit: is displayed. Press any key (except Y) to abort the exit. XQ is equivalent to clicking the close gadget on the ED window.
|}

==== Cursor Control ====

The following commands are used for controlling the cursor:

{| class="wikitable"
| End Page || Esc,E,P || End of a page.
|-
| Previous || Esc,P || Start of the previous line.
|-
| Character Left || Esc,C,L || One place to the left.
|-
| Character Right || Esc,C,R || One place to the right.
|-
| Current End || Esc,C,E || End of the current line.
|-
| Current Start || Esc,C,S || Start of the current line.
|-
| Tab || Esc,T,B || Next tab position.
|-
| Word Next || Esc,W,N || Start of the next word.
|-
| Word Previous || Esc,W,P || Space after previous word.
|}

==== Modifying Text ====

The following commands edit text on the screen:

{| class="wikitable"
| Insert Before || Esc,I || Inserts the specified string on the line before the cursor. Specify a new line's string after the I command to insert text before the current line containing the cursor.
|-
| Insert After || Esc,A || Inserts the specified string on the line after the cursor. This command works in the same way as I, except that the string is inserted on a new line beneath the current cursor position.
|-
| Split || Esc,S || Splits the current line at the cursor position.
|-
| Join || Esc,J || Joins the next line to the end of the current line.
|-
| Delete || Esc,D || Deletes the current line.
|-
| Delete Character || Esc,D,C || Deletes the character under the cursor.
|-
| Delete Left || Esc,D,L || Deletes the character to the left of the cursor.
|-
| Delete Word || Esc,D,W || Deletes to the end of the current word.
|-
| End Line || Esc,E,L || Deletes to the end of the current line.
|-
| Flip Case || Esc,F,C || Switches the case of the selected letters, one at a time.
|-
| Set Tab || Esc,S,T || Sets the tab stop. To change the current setting of tabs, use the ST command followed by a number.
|-
| Next || Esc,N || Start of the next line.
|}

== Repeating Commands in Extended Mode ==

Pressing Ctrl+G repeats a command line. You can set up execute complex sets of editing commands many times.

You can repeat a command a specified number of times by entering the number before the command. For example:

4 E/rename/copy/

exchanges the next four occurrences of "rename" to "copy".

Use the RP (Repeat) extended command to repeat a command until ED returns an error, such as reaching the end of the file. For example:

T;RP E/rename/copy/

moves the cursor to the top of the file, then exchanges all occurrences of "rename" with "copy". The T command (Top of File) changes all occurrences of Rename in the whole file. Otherwise, only the occurrences after the current cursor position are changed.

To execute command groups repeatedly, you can group the commands together in parentheses. You can also nest command groups. For example:

RP (F/Workbench/;3A//)

inserts three blank lines (the null string//) after every line containing Workbench.

To interrupt any sequence of extended commands, press any key during execution. If an error occurs, ED abandons the command sequence.

== Customizing ED ==

You can customize ED with commands that change the menus and function key setup. These commands can be entered individually within ED. They can also be saved as a script, such as S:Ed-startup, or as a file specified using the WITH argument. To execute the file from within ED, use the Run File (Esc,R,F) extended command. For information about changing the function keys, see page 4-15.

{| class="wikitable"
\ Set Menu Item || Esc,S,I || Defines the menu headings and items. There are 120 menu item slots ranging from 0 to 119. The slot type identifies the contents of the slot and is a number from 0 to 4. The 0 slot type must be the last defined slot. Do not create a menu without items; if you specify a menu heading, include menu items after it. See below for the syntax of the Set Menu Item command and a table of the slot types.
|-
| Enable Menu || Esc,E,M || Enables menus. You must follow the Set Menu Item commands with EM to enable the menu commands. See page 4-22 for an example script using the Enable Menu command.
|}

=== Set Menu Item ===

The following is the syntax for the Set Menu Item command:

SI <slot number> <slot type> /string1/string2/

The following table shows the slot types and functions used with the Set Menu Item command:

{| class="wikitable"
! Type !! Function !! String Input
|-
| 0 || End of Menus || No arguments
|-
| 1 || Menu Heading || String1 = heading name
|-
| 2 || Menu Item || String1 = item name String2 = command string
|-
| 3 || Submenu Heading || String1 = heading name String2 = command string
|-
| 4 || Separator bar || No arguments
|}

=== Example Script ===

The following is an example script using the Set Menu Item and Enable Menu commands. Quotation marks are used as the delimiters.

SI 0 1 "Project"
SI 1 2 "Open . . . " "op ? /Open file:/"
SI 2 2 "Save ... " "sa"
SI 3 4
SI 4 2 "Quit!" "q"
SI 5 1 "Move"
SI 6 2 "Top" "t"
SI 7 2 "Bottom" "b"
SI 8 0
EM

This script produces the menus illustrated in Figure 4-4:

[[File:DosFig4-4.png|none|frame|ED Custom Menu Example]]

== Printing From ED ==

Use the following steps to print a file that is open in the current ED window:

# Choose the Save As menu item to display a file requester.
# Enter prt: in the Drawer field.
# Select OK.

This prints the file, but does not save it to disk. If you wish to save the file you must select the Save menu item or Save As and a file name.

== Quitting ED ==

You can exit ED in one of the following three ways:

* Esc,X. This method exits ED and saves the current file to a designated file name that was specified when ED was opened.
* Esc,X,Q or click on the ED window's close gadget. This method exits ED if no changes were made to the file. If changes were made to the file, ED lets you save the changes or exit without saving.
* Esc,Q or select the Quit item in the Project menu. This method exits ED without saving any changes if you confirm the status line warning that changes will be lost.

== ARexx Support ==

You can also control ED from ARexx by sending and receiving commands through ED's ARexx port. Each copy of ED running concurrently has an individual ARexx port name that must be specified to handle information for the correct session. The ARexx port names are assigned as follows:

* The first session's port name is ED
* The second session's is ED_1
* The third session's is Ed_2 and so on

Many of ED's extended commands can be used from ARexx. By using ED's RV command in ARexx programs, you can send information from ED to ARexx. This gives information about the status of ED, such as the current line number of the name of the file being edited.

The RV command accepts the name of the ARexx stem variable to store its argument information. For example, in ARexx:

address 'Ed' 'RV /stem/'

assigns values to the following variables:

{| class="wikitable"
| stem.LEFT || Current left margin
|-
| stem.RIGHT || Current right margin
|-
| stem.TABSTOP || Current tab stop setting
|-
| stem.LMAX || Maximum number of lines visible on screen
|-
| stem.WIDTH || Width of the screen in characters
|-
| stem.X || Cursor X position in the ED window (1 is the left edge)
|-
| stem.Y || Cursor Y position in the ED window (1 is the top line)
|-
| stem.BASE || Window base (normally 0, but non-zero when the screen is shifted to the right)
|-
| stem.EXTEND || Extended margin value (Extend Margins command)
|-
| stem.FORCECASE || Case sensitivity flag (Ignore Case = 1, Case Sensitive = 0)
|-
| stem.LINE || Current line number in the file (1 is the first line)
|-
| stem.FILENAME || Name of the file being edited
|-
| stem.CURRENT || Text of the current line
|-
| stem.LASTCMD || Last extended command issued
|-
| stem.SEARCH || Lst string searched for
|}

Any valid ARexx symbol can be substituted for "stem". Enclose the name in proper delimiters. These variables can be treated as ordinary ARexx stem variables.

== ED/ARexx Example Program ==

The example program, Transpose.ed, illustrates the use of several extended commands from ARexx. This program transposes two characters when launched from ED. For example, if a line contains the string 123 and the cursor is highlighted the 3, Transpose.ed changes the string to 213.

Enter this program and save it as REXX:Transpose.ed. Then, open ED and edit an existing file or create a new one. Place the cursor one character to the right of the ones to be transposed, press Esc, and enter:

RX /transpose.ed/

The program executes and the characters are transposed if ARexx is running and everything is entered correctly. The entire file name, including the extension, must be specified to run the program.

<syntaxhighlight lang="C" line>
/*Transpose.ed: An example program to transpose two characters. */
/*Given string '123', if cursor is on 3, this macro converts */
/*string into '213'. */
HOST = address () /*find out which ED session invoked this program*/
address VALUE HOST /*...and talk to that session */
'rv''/CURR/' /*Ask ED to store info in stem variable CURR */
/*Obtain two pieces of information: */
currpos = CURR.X /*1.position of cursor on line */
currling = CURR.CURRENT /*2. Contents of current line */
if /currpos >2) then /*Work only on the current line */
currpos = currpos - 1
else do /*Otheriwse, report error and exit */
'sm/Cusor must be at position 2 or further to the right/'
exit 10
end

/*Next the code needs to reverse the CURRPOSth and CURRPOSth-1 */
/*characters and then replace the current line with the new one. */
/*drop CURR. CURR is no longer needed; dropping it saves some */
/*memory. */
'd' /*Tell ED to delete current line */
currlin = swapch (currpos,currlin) /*Swap the two characters */
'i/'||currlin||'/' /*Insert modified line */
do i = 1 to currpos /*Place cursor back where it started */
'cr' /*ED's `cursor right' command */
end
exit /*Program has finished */

/*Function to swap two characters */
Swapch: procedure */
parse arg cpos,clin
ch1 = substr(clin,cpos1) /*Get character */
clin = delstr(clin,cpos1) /*Delete it from string */
clin = insert(ch1,clin,cpos-2,1) /*Insert to create transposition */
return clin /*Return modified string */
</syntaxhighlight>

= MEmacs =

MEmacs (MicroEmacs), which is similar to the UNIX-based Emacs editor, is a screen-oriented editor in which you can edit multiple files at the same time. MEmacs performs all operations on memory-resident text, requiring that entire text files be able to fit into memory at once.

Line length, generally 80 characters long, is limited to the right edge of the screen. You can enter characters beyond the limit, however, they are not displayed. To see these characters, break the line or delete some of the displayed characters. A dollar sign ($) at the right edge of the screen indicates that there are characters beyond what is displayed.

The format for the MEmacs command is the following:

MEMACS [<filename>] [GOTO <n>] [OPT W]

The <filename> argument is optional.

The GOTO <n> option specifies the line on which the cursor is to appear when the file is opened.

Specifying OPT W opens MEmacs in a Workbench window rather than on its own screen, which saves memory.

== Starting MEmacs ==

MEmacs can be run from either the Workbench or the Shell. From the Workbench, double-click on the MEmacs icon in the Tools window of the Extras disk. If you have a hard disk, the Tools drawer is in your Workbench window.

From the Shell, enter:

MEmacs <filename>

where <filename> specifies the file to read into MEmacs. If a file with that name does not previously exist, a new file is created when you save your work.

== MEmacs Commands ==

The line at the bottom of the MEmacs screen identifies either the current file name or the name of the current buffer if no file name is specified. Figure 4-5 illustrates the MEmacs opening screen .

[[File:DosFig4-5.png|none|frame|MEmacs Opening Screen]]

Several buffers can be in use at the same time and one or more can be displayed on the screen simultaneously. Menu options switch between them. At all times, the screen displays what is actually in the buffer.

MEMacs has two conditions of operation:

; Normal
: When you enter and manipulate text directly in the file without special functions.

; Command
: When you enter a command through a menu selection or the keyboard shortcut for it. In the command condition, the cursor jumps to the bottom line of the display and waits for you to supply additional information following the prompt. You cannot return to the normal condition until you satisfy or cancel the command by pressing Return.

In the MEmacs normal condition, you can:

* Move the cursor using the arrow keys.
* Move the cursor to the edge of the window by holding down Shift and pressing the appropriate arrow key.
* Move the cursor by clicking the left mouse button at the desired place on the screen.
* Insert characters at the current cursor position by typing them.
* Delete the character at the current cursor position by pressing Del.
* Delete the character to the left of the cursor by pressing Backspace.
* Perform other special menu and command functions.

When using MEmacs, you should be familiar with the following special terms:

; Buffer
: A memory area that MEmacs controls. There is always at least one buffer used by MEmacs containing zero or more text characters.

; Dot
: The current cursor position.

; Mark
: A specified cursor position. (Each buffer has its own dot and mark.) The Set-mark menu item marks the current cursor position (described on page 4-33). You can move forward or backward in the file, adding or deleting text. To return to the marked place, select the Swap-dot&mark menu item (described on page 4-36).

: You can also set a mark to indicate the beginning of a block of text that you want to duplicate, move, or delete. The block encompasses all the characters starting with the mark and continuing to the current cursor position.

; Kill
: Kill commands remove text from the screen to save in a kill buffer. This text can be retrieved and inserted into your document by using the Yank command. Issuing successive Kill commands (without selecting Yank in between) adds each block of the text to the existing text in the kill buffer. If you select Yank, the next block of killed text otherwise the current block.

; Window
: MEmacs screens can be split into multiple layers for editing and displaying more than one buffer or two or more portions of the same buffer. Each layer is a MEmacs window.

; Modified Buffers
: Buffers are marked as modified when any changes are made. The modified status is removed when the buffer is saved.

: To see modified buffers, use the List-buffers command (described on page 4-33); modified buffers are identified with an asterisk (*). If you exit MEmacs without saving any changes, a prompt tells you that modified buffers exist and asks if you really want to quit.

== Menu Commands ==

MEmacs has the following menus:

{| class="wikitable"
| Project || Contains system and file-oriented items.
|-
| Edit || Contains buffer editing commands.
|-
| Window || Controls the characteristics of the MEmacs windows.
|-
| Move || Controls the placement of the cursor.
|-
| Line || Controls line-oriented operations.
|-
| Word || Controls word-oriented operations.
|-
| Search || Controls search and search/replace options.
|-
| Extras || Controls the numerical value of arguments and lets you execute a series of operations as though it were a single special command.
|}

Figure 4-6 illustrates the MEmacs expanded menu bar.

[[File:DosFig4-6.png|none|frame|Expanded Menus]]

=== Project Menu ===

The commands in the Project menu, except for Visit-file, affect the buffer associated with the current cursor position.

{| class="wikitable"
| Rename || Ctrl+X,F || Changes the name of the file associated with the current buffer. Pressing Return without specifying a file name disassociates the buffer from any file name.
|-
| Read-file || Ctrl+X, Ctrl+R || Replaces the contents of the current buffer with the contents of a file. Enter a complete file path. Press Return without specifying a file name to ignore the request and return to normal mode.
|-
| Visit-file || Ctrl+X, Ctrl+V || Allows you to work with additional files other than the one you are currently editing. Enter the complete file path.
|-
| Insert-file || Ctrl+X, Ctrl+I || Insert the contents of a file into the current buffer at a point one line above the current cursor position. Enter the complete file path.
|-
| Save-file || Ctrl+X, Ctrl+S || Writes the contents of the current buffer to the file name associated with that buffer. Issues the file's line count following a successful save. MEmacs does not save the file if no name is provided; it displays this error message: No file name.
|-
| Save-as-file || Ctrl+X, Ctrl+W || Allows you to specify the name and path of a file associated with a buffer.
|-
| Save-mod || Ctrl+X, Ctrl+M || Writes the contents of all modified buffers to the disk. Do not accidentally modify a buffer that you did not intend to change.
|-
| Save-exit || Ctrl+X, Ctrl+F || Saves all modified buffers and exits MEmacs.
|-
| New-Cli || Ctrl+- || Opens a new Shell window known as a Spawn Window. Enter AmigaDOS commands in the Spawn Window without interfering with MEmacs. Close the window with ENDSHELL.
|-
| Cli-Command || Ctrl+X,! || Lets you execute an AmigaDOS command while in MEmacs. Enter a command following the ! prompt at the bottom of the screen. Command output is placed in the spawn.output buffer.
|-
| Quit || Ctrl+C || Exits MEmacs. You are given an opportunity to save modified buffers or quit without saving. Alternative keyboard shortcuts: Ctrl+X,Ctrl+C Esc,Ctrl+C.
|-
| About... || || Gives program copyright information
|}

=== Edit Menu ===

The commands in the Edit menu affect the editing of your buffers and their associated files.

{| class="wikitable"
| Kill-region || Ctrl+W || Deletes block of text from the current buffer and saves them in a kill buffer. Text can be retrieved with the Yank command. Make copies of a block by immediately selecting Yank without changing the cursor position after killing the block. This restores the block to its position and leaves a copy in the kill buffer.
|-
| Yank || Ctrl+Y || Copies the contents of the kill buffer to the current cursor location on the current line. Reverses the action of Kill-region without changing the contents of the kill buffer. Used with Kill-region for moving text or for repeatedly copying a single block of text.
|-
| Set-mark || Ctrl+@ || Marks the cursor position in a buffer. The subsequent cursor position is referred to as a dot. Move between the mark and the dot using the Swap-dot&mark command in the Move menu. Used for marking blocks of text. Alternative keyboard shortcut: Esc,-.
|-
| Copy-region || Esc,W || Copies the contents of the marked region to the kill buffer without deleting it, replacing any previous contents.
|-
| Upper-region || Ctrl+X, Ctrl+U || Changes the text of the entire marked region to upper case.
|-
| Lower-region || Ctrl+X, Ctrl+L || Changes the text of the entire marked region to lower case.
|-
| List-buffers || Ctrl+X, Ctrl+B || Splits the current buffer's window and displays a list of the buffers MEmacs is maintaining. To redisplay the current buffer, select the One-window command or press Ctrl+X,1. The List-Buffer fields are: 
{| class="wikitable"
| C || Displays an asterisk if the buffer has been modified since it was last saved to a file. (Stands for changed.)
|-
| Size || Shows how many characters are in the buffer.
|-
| Buffer || Shows the name given to the buffer. If you read in a file, this is the name of the file without the full path.
|-
| File || Shows the full path to the file. This is the file to which MEmacs writes the buffer if you Save-file or Save-exit while the cursor is in that buffer.
|}
|-
| Select-buffer || Ctrl+X,B || Allows you to select the buffer to edit in the current window. Replaces the contents of the window with the selected buffer or new buffer.
|-
| Insert-buffer || Esc, Ctrl+Y || Insert the contents of a named buffer into the current buffer at the line above the current cursor position.
|-
| Kill-buffer || Ctrl+X,K || Deletes the contents of one or more chosen buffers, returning the memory to the memory manager to reuse. You must specify the buffer to be deleted; a buffer cannot be killed if its contents are currently displayed.
|-
| Justify-buffer || Ctrl+X,J || Removes all blank spaces and tabs from the left edge of all the lines in the current buffer. The text realigns with the current margins.
|-
| Redisplay || Ctrl+L || Redraws the screen.
|-
| Quote-char || Ctrl+Q || Allows insertion of any literal character in the text file, except the Tab key. Alternative keyboard shortcut: Ctrl+X,Q.
|-
| Indent || Ctrl+J || Moves the cursor to the next line, automatically indenting the same amount of spaces as the previous line. Alternative keyboard shortcuts: Help or Enter on the numeric keypad.
|-
| Transpose || Ctrl+T || Swaps the positions of two adjacent characters. Place the cursor on the right-most of the two characters and execute the command.
|-
| Cancel || Ctrl+G || Ends an ongoing menu command, such as query search and replace.
|}

=== Window Menu ===

The Window menu controls how to view your buffers on the screen.

{| class="wikitable"
| One-window || Ctrl+X,1 || Makes the current buffer a single, full-sized window on the MEmacs screen.
|-
| Split-window || Ctrl+X,2 || Splits the current window in half, positioning the current buffer identically in both windows. Any changes you make in either window affect the whole buffer.
|-
| Next-window || Ctrl+X,N || Moves the cursor to the next window and makes that window available for editing.
|-
| Prev-window || Ctrl+X,P || Moves the cursor to the previous window and makes that window available for editing.
|-
| Expand-window || Ctrl+X,Z || Adds a line to the height of the current window and simultaneously subtracts a line from the height of the adjacent window.
|-
| Shrink-window || Ctrl+X, Ctrl+Z || Substracts a line from the height of the current window and adds a line to the height of the adjacent window.
|-
| Next-w-page || Esc, Ctrl+V || Displays the next page of the adjacent window. This does not make the window available for editing.
|-
| Prev-w-page || Ctrl+X,V || Displays the previous page of the adjacent window. If only one window is displayed, it displays the previous page of that window.
|}

=== Move Menu ===

These commands move the cursor rapidly through the current buffer.

{| class="wikitable"
| Top-of-buffer || Esc,< || Moves the cursor to the top line of the current buffer.
|-
| End-of-buffer || Esc,> || Moves the cursor to the bottom line of the current buffer.
|-
| Top-of-window || Esc,, || Moves the cursor to the top of the current window.
|-
| End-of-window || Esc,. || Moves the cursor to the bottom of the current window.
|-
| Goto-line || Ctrl+X, Ctrl+G || Moves the cursor to a specified line number. Specifying a line number larger than the total number of lines in a buffer moves the cursor to the last line of the buffer.
|-
| Swap-dot&mark || Ctrl+X, Ctrl+X || Marks the current cursor position (dot) and moves the cursor to the previously marked setting.
|-
| Next-page || Ctrl+V || Moves the cursor toward the end of the buffer by one full window, less one line.
|-
| Prev-page || Esc,V || Moves the cursor towards the beginning of the buffer by one full window, less one line.
|-
| Next-word || Esc,F || Moves the cursor forward to the next non-alphabetic character, such as a space or punctuation mark, following the current word.
|-
| Previous-word || Esc,B || Moves the cursor back to the first letter of the previous word.
|-
| Scroll-up || Ctrl+Z || Moves the text up one line.
|-
| Scroll-down || Esc,Z || Moves the text down one line.
|}

=== Line Menu ===

These commands move the cursor within or between lines and perform operations involving entire lines.

{| class="wikitable"
| Open-line || Ctrl+O || Splits the line containing the cursor, forcing the character at the current cursor position to become the first character of the following line. The cursor remains on the original line. Pressing the Del key cancels an accidental Open-line.
|-
| Kill-line || Ctrl+X, Ctrl+D || Deletes the line containing the cursor and places the text in the kill buffer.
|-
| Kill-to-eol || Ctrl+K || Deletes the text between the current cursor position and the end of the line and places the text in the kill buffer.
|-
| Start-of-line || Ctrl+A || Moves the cursor to the first position on a line.
|-
| End-of-line || Ctrl+E || Moves the cursor to the last position on a line.
|-
| Next-line || Ctrl+N || Moves the cursor down one line.
|-
| Previous-line || Ctrl+P || Moves the cursor up one line.
|-
| Line-to-top || Esc,! || Moves the line containing the cursor to the top of the window.
|-
| Delete-blanks || Ctrl+X, Ctrl+O || Deletes blank lines, proceeding forward from the current cursor position until MEmacs reaches the next line on which there is text. Does not delete single blank lines.
|-
| Show-Line# || Ctrl+X,= || Displays information on the present cursor position.
|}

=== Word Menu ===

The Word menu contains word-associated operations.

{| class="wikitable"
| Delete-forw || Esc,D || Deletes the character on which the cursor is positioned and all remaining characters to the right until the next non-alphanumeric character is found, such as a blank space, tab, or punctuation.
|-
| Delete-back || Esc,H || Delets all characters to the left of the cursor until it finds the first character of a word. The character at the cursor position is not deleted. Alternative keyboard shortcut: Esc,Del.
|-
| Upper-word || Esc,U || Changes a word to upper case, starting at the cursor position and proceeding to the last character of the word.
|-
| Lower-word || Esc,L || Changes a word to lower case, starting at the cursor position and proceeding to the last character of the word.
|-
| Cap-word || Esc,C || Changes the character at the cursor position to upper case. Also changes the characters to the right of the cursor, up to the end of the word, to lower case.
|-
| Switch-case || Esc,^ || Changes the case of a word, starting at the current cursor position and proceeding to the right until it reaches the end of the word. If a word is upper case or has mixed text, it changes upper to lowr case and vice versa.
|}

=== Search Menu ===

These commands search through the current buffer for specific text strings. The case (upper or lower) of the string is not significant in the search. However, if you are using text substitution (search and replace), the text is replaced in the case of the replacement string.

{| class="wikitable"
| Search-forward || Ctrl+S || Searches through the text starting at the current cursor position and moving forward to the end of the buffer. At the prompt, enter the character string for the search. Alternative keyboard shortcut: Ctrl+X,S.
|-
| Search-backward || Ctrl+R || Searches through the text from the current cursor position backwards to the beginning to the buffer. Alternative keyboard shortcut: Ctrl+X,R.
|-
| Search-replace || Esc,R || Searches the same as Search-forward, allowing you to replace the string with different text. At the prompt, enter the replacement string of characters.
|-
| Query-s-r || Esc,Q || Operates the same as Search-replace, except it asks for confirmation to replace each time it finds the specified string. The options are Y (yes), N (no), C (change all occurrences), and Ctrl+G (abort).
|-
| Fence-match || Esc, Ctrl+F || Finds the closest occurrence of the fence character to match the one at the current cursor position. Fence characters are parenthesis, brackets, braces, and angle brackets.
|}

=== Extras Menu ===

These commands are MEmacs operational commands and macro commands. Specific numeric arguments may be required before selecting a command; an * indicate that an argument is required. Macro commands are executed by selecting the Execute-macro menu item.

{| class="wikitable"
| Set-arg || Ctrl+U || Lets you specify a numeric argument for a command.
|-
| Set || Esc,S || Lets you set the following MEmacs parameters:
{| class="wikitable"
| Screen || Places the MEmacs display in a Workbench window or back onto a custom screen.
|-
| Interlace || Turns the interlace mode on or off.
|-
| Mode || Results in a second prompt "Mode:"; you can enter Cmode (for editing C programs) or Wrap (to enable automatic word-wrap when the text reaches a set cursor position). Cmode provides automatic fence matching. Use +mode or -mode to add or subtract a mode.
|-
| Left || Determines the left margin. Prompts for a numerical argument if not provided with the entry.
|-
| Right || Determines the right margin. Prompts for a numerical argument if not provided with the entry.
|-
| Tab || Sets the increment for tab spacing. Prompts for a numerical argument if not provided with the entry.
|-
| Indent || Determines how far to indent each level of nesting (used in Cmode). Prompts for a numerical argument if not provided with the entry.
|-
| Case || Turns case-sensitive searches on of off; default is off.
|-
| Backup || Turns the MEmacs backup function on or off. Your options are: ON (renames the current file <filename>.bak and saves that bakkup file to the T: directory); SAFE (this option checks to see if a file already exists for the buffer - if so, it displays an error and does not overwrite the existing file, Ctrl+X clears the display); and OFF (this is the default option - MEmacs does not perform any backup).
|}
|-
| Start-macro || Ctrl+X,( || Tells MEmacs to start recording any subsequent keystrokes. Used with the Stop-macro and Execute-macro commands.
|-
| Stop-macro || Ctrl+X,) || Tells MEmacs to stop recording keystrokes.
|-
| Execute-macro || Ctrl+X,E || Repeats keystrokes that were entered between Start-macro and Stop-macro.
|-
| Set-key || Ctrl+X, Ctrl+K || Allows you to redefine all of the function keys, the Shifted function keys, the Help key, or any key on the numeric keypad as keyboard macros. You cannot use the menu shortcut of Ctrl+@ to insert the Set-mark command into any keyboard macro definitions.
|-
| Reset-keys || Esc,K || Returns any keys defined by Set-keys to their original default state.
|-
| Execute-file || Esc,E || Allows you to execute a program file within MEmacs.
|-
| Execute-line || Ctrl+[, Ctrl+[ || Sets MEmacs to command mode. At the prompt enter any menu command and its parameters. Alternate keyboard shortcut: Esc,Esc.
|}

The following table contains the default values of the Set-key/function keys when used in macro commands.

{| class="wikitable"
! Key !! Assignment !! Key Sequence
|-
| F1 || Clone line || Ctrl+A,Ctrl+K,Ctrl+Y,Ctrl+M,Ctrl+Y
|-
| F2 || Delete line || Ctrl+X,Ctrl+D
|-
| F3 || Execute keyboard macro || Ctrl+X,E
|-
| F4 || Next screen || Ctrl+V
|-
| F5 || Previous screen || Esc,V
|-
| F6 || Split window || Ctrl+X,2
|-
| F7 || One window || Ctrl+X,1
|-
| F8 || Scroll window up || Ctrl+Z
|-
| F9 || Scroll window down || Esc,Z
|-
| F10 || Save file and exit || Ctrl+X,Ctrl+F
|-
| Help || Insert line || Ctrl+J
|-
| Enter (keypad) || Insert line || Ctrl+J
|}

== Commands Not in Menus ==

The following commands are only accessible through the keyboard.

Keys are bound when they can be used to perform a function. For example, any key or key sequence that can be used as a shortcut for a menu item is bound to that menu item.

{| class="wikitable"
| Describe Key || Esc, Ctrl+D || Tells you if any functions are bound to a key or key sequence. At the prompt enter the specific key or key sequence.
|-
| Bind Key || Esc, Ctrl+B || Allows you to bind a key to a function. At the prompt, enter the key or key sequence.
|-
| Unbind Key || Esc, Ctrl+U || Allows you to return a bound key to an unbound state. At the prompt, enter the key or key sequence. Standard bound keys cannot be unbound.
|-
| Echo || Esc, Ctrl+E || Displays the string entered in the command line.
|-
| Move to Edge of Window || Shift+Arrow || Moves the cursor to the top, bottom, left, or right edge of the screen.
|-
| Delete the Next Character || Ctrl+D || Deletes the character at the current position. Same as pressing Del.
|-
| Delete the Previous Character || Ctrl+H || Deletes the character to the left of the current cursor position. Same as pressing Backspace.
|-
| Move to Next Line || Ctrl+M || Inserts a newline character after the current cursor position and moves the cursor to the start of the new line.
|-
| Move x number of Characters || Ctrl+F, Ctrl+B || Allows you to move the cursor forward or backward a specified number of spaces. Providing no value moves the cursor only one character.
|}

== Customizing MEmacs ==

MEmacs looks for an Emacs_pro file when it is opened to see if there are any command or local files that it should automatically execute. You can customize the Emacs_pro file by adding commands to it that you use often, command sequences, or text strings. If an Emacs_pro file does not already exist, you can create one.

To create a global file of commands, place the Emacs_pro file in the S: directory. Local files can be out in any directory. If that directory is the current directory when MEmacs is opened, the commands in that particular local file are executed.

When both local and global Emacs_pro files are present, the local file overrides the global file.

For example:

Set Case On
Set-Key F11 "Dear Sirs:"
Set-Key F12 "^S Workbench"
Set-Key F13 "^X^B"

makes the following assignments:

{| class="wikitable"
| Shift+F1 || Enter the text string "Dear Sirs:".
|-
| Shift+F2 || Search forward for the next occurrence of the word Workbench. (The Set Case On commands make any text searches case-sensitive.)
|-
| Shift+F3 || Display the list of buffers.
|}

You must use Ctrl+Q to enter a Ctrl+key sequence. For example, to enter the ^S character shown in the example, press Ctrl+Q, Ctrl+S.

== Quitting MEmacs ==

You can exit MEmacs by selecting the Quit menu item in the Project menu or by entering Ctrl+C. MEmacs lets you save any modified buffers or quit without saving.

= EDIT =

EDIT is a line editor designed for the automated editing of files, particularly binary files or files that are larger than available memory. You cannot create a new file with EDIT.

EDIT processes files line by line. As EDIT moves through the input, or source file, each line is passed after alteration to a sequential output file, the destination file.

EDIT processes the lines in files in a forward direction; however, you can move backward a limited number of lines. EDIT holds the lines in an output queue before writing them to the destination file. The size of this queue depends on the amount of memory available. You can increase the size of the queue with the OPT P and OPT W options.

The format for EDIT is the following:

EDIT [FROM] <filename> [[TO] <filename>] [WITH <filename>] [VER <filename>]
[OPT P <lines> | W <chars> | P<lines>W<chars>] [WIDTH <chars>] [PREVIOUS <lines>]

The FROM argument specifies the source file to be edited. You must specify a source file with EDIT, although the FROM keyword is optional.

The TO argument specifies the destination file to which EDIT sends its output, including editing changes. If you omit the TO argument, EDIT uses a temporary file. This temporary file is renamed with the name of the FROM file and overwrites the FROM file when editing is complete.

The WITH keyword specifies a file containing editing commands.

The VER keyword specifies the file to which EDIT sends error messages and line verifications. If the VER argument is not given, EDIT uses the screen.

Use OPT P <n> and OPT W <n> to specify the PREVIOUS and WIDTH options. However, do nit use the OPT keyword with PREVIOUS and WIDTH.

You can use the PREVIOUS and WIDTH options to increase or decrease the amount of available memory. The PREVIOUS option sets the number of previous lines available to EDIT to the integer <n>. The WIDTH option sets the maximum number of characters allowed on a line to <n>. EDIT multiples the number of previous lines by the maximum number of characters (PREVIOUS * WIDTH) to determine the available memory. The default values are PREVIOUS 100 WIDTH 1200.

== Starting EDIT ==

Start EDIT through a Shell using the following command:

1.< EDIT <filename>

Where <filename> is the name of an existing file to be edited.

== EDIT Commands ==

The following list provides background information about EDIT commands:

{| class="wikitable"
| Current line || Refers to the line that EDIT is working on at any time. Every command entered refers to the current line, all text changes are made to the current line, and new lines are inserted before the current line.
|-
| Original lines || The lines of the source file. Lines retain their original number until you renumber them with the REWIND or = commands.
|-
| Non-original lines || Any lines that are inserted into the source file or original lines that are split. These are not assigned line numbers.
|-
| Line verification || When using commands that change information in a line, EDIT displays the revised line after the command is executed.
|-
| Arguments || Strings, qualified strings, numbers, and switch values used with EDIT commands.
|}

Enter commands in one of the following three ways:

* Enter the commands, then press Return
* Enter the final command argument, then press Return
* Enter a semicolon or closing parenthesis

The text conventions used in the command description are the following:

* Command names are shown in upper case, although EDIT is not case-sensitive.
* Angle brackets indicate that information must be substituted. For example, <string> indicates that the command takes a string argument.
* An <n> represents a numeric argument.
* Square brackets indicate that the argument is optional. For example, [<n>] indicates that the command can take an optional numeric argument.
* Slashes are used as delimiters for strings; use one slash between two strings.
* Periods are used as delimiters for file names (slashes cannot be used since they are used to separate strings).

== Selecting the Current Line ==

The following commands let you move through the file and select the current line.

{| class="wikitable"
| Move to a specific line number || M <n> || Specify a new current line by entering its line number, a period, and an asterisk as M's argument. Only original lines can be accessed by line number.
|-
| Move to next line in the source file || N || Move forward one line. Entering a number and N indicates the number of lines to move forard. When used as the last line of the source file, EDIT creates an extra line at the end of the file. If you are already on this extra line, using N causes an error message to be displayed.
|-
| Move to the previous line in the source file || P || Moves back one line. Entering P repeatedly moves more than one line. Entering a number + P indicates how many lines to move back. You can only move back to previous lines that have not yet been written to the destination file. The default is 100 lines, which can be changed with the PREVIOUS option.
|-
| Find || F<string> || Lets you select a current line by specifying some of its content.
|-
| Search Backward || B,F<string> || Looks backward starting from the current line through the source file for a line containing the specified string.
|}

== Editing the Current Line ==

The following commands add new material or replace material on the current line.

{| class="wikitable"
| Insert <string2> after <string1> || A <string1> <string2> || Insert <string2> after the first occurrence of <string1>.
|-
| Insert <string2> before <string1> || B <string2> <string1> || Insert <string2> before the first occurrence of <string1>.
|-
| Exchange <string2> for <string1> || E <string2> <string1> || Replaces the first occurrence of <string1> with <string2>.
|}

== Inserting and Deleting Lines ==

The following commands insert new material (non-original lines) and delete lines from the source file. You can also insert complete files into the source file.

{| class="wikitable"
| Insert one or more lines || I [<n>] || If given alone or with a line number, inserts text before the current line. 
If given with an asterisk, the text is inserted at the end of the file. 
Indicate the end of the insertion by pressing Return, Z, and Return.
|-
| Delete one or more lines || D [<n>] || Deletes the current line if entered with no arguments. Deletes a specific line if entered with a line number. Deletes a set of lines if entered with a range of line numbers; do not use punctuation between the numbers. Deletes everything from the current line through the end of the source file of entered with a period and an asterisk as arguments.
|-
| Delete all lines until the specified string is found || D,F<string> || Deletes successive lines from the source file until the line containing the matching string is found. If no argument is specified, it deletes all lines until it finds the last string specified.
|-
| Delete existing lines and replace with new text || R [<n>] || Lets you delete line and then insert new ones. Entering a line number following R indicates a specific line to replace.
|-
| Change the terminator || Z <string> || Tells EDIT that it has reached the end of any new text that is being inserted. Entering a string after Z changes it from the default.
|-
| Show current information about EDIT || S,H,D || Displays saved information values, such as the last string searched for, the last command entered, and the input terminator.
|-
| Turn trailing spaces on/off || <nowiki>T,R,+|-</nowiki> || Preserves any blanks that fall at the end of lines.
|}

== Editing Line Windows ==

You can define subsections of the line, called line windows, on which EDIT executes all subsequent commands. In the descriptions of EDIT qualifiers, the beginning of the line always indicates the beginning of the line window.

Whenever EDIT verifies a current line, it indicates the position of the line window by displaying a > character directly beneath the line. EDIT omits the pointer if the line window begins at the start of the line.

The following commands control the position of the character pointer:

{| class="wikitable"
| > || Moves the pointer one character to the right.
|-
| < || Moves the pointer one character to the left.
|-
| PR || Resets the pointer to the start of the line.
|-
| PA <string> || Moves the pointer to the first character after the specified string.
|-
| <string> || Moves the pointer to the first character before the specified string.
|}

The following commands change the character at the current pointer, then move the pointer.

{| class="wikitable"
| $ || Makes the character at the pointer lower case, then moves the pointer one character to the right.
|-
| % || Makes the character at the pointer upper case, then moves the pointer one character to the right.
|-
| _ || The _ (underscore) command deletes the character at the pointer, turning it into a space, then moves the pointer one character to the right.
|-
| # || Deletes the character at the pointer, then moves the rest of the line one character to the left. To delete several characters, specify a number before the #. For example, 5# deletes the next five characters in the window.
|}

A combination of these commands can be used to edit a line character by character.

The following commands insert and exchange text on the current line, similar to the A, B, and E commands; however, the character pointer is moved on completion.

{| class="wikitable"
| Insert <string2> after <string1> || A,P <string1> <string2> || Inserts <string2> after the first occurrence of <string1>. The pointer is then positioned after <string2>.
|-
| Insert <string2> before <string1> || B,P <string1> <string2> || Inserts <string2> before the first occurrence of <string1>. The pointer is then positioned after <string2>.
|-
| Exchange <string1> with <string2> || E,P, <string1> <string2> || Replaces the first occurrence of <string1> with <string2>. The pointer is then positioned after <string2>.
|-
| Delete Till After || D,T,A <string> || Deletes all text from the beginning of the line or the character pointer to the end of the specified string.
|-
| Delete Till Before || D,T,B <string> || Deletes all text from the beginning of the line or the character pointer; stops before the specified string.
|-
| Delete From After || D,F,A <string> || Deletes all text starting after a specified string to the end of the line.
|-
| Delete From Before || D,F,B <string> || Deletes all text starting with the specified string to the end of the line.
|}

== Splitting and Joining Lines ==

These commands split a line into more than one line and join together two or more successive lines.

{| class="wikitable"
| Split line before <string> || S,B <string> || Splits the current line before the specified string. The first part of the line is sent to the output queue; the second part is made into a new non-original current line. Qualifiers can be used to restrict the context of the string.
|-
| Split line after <string> || S,A <string> || Splits the current line after the specified string. The first part of the line is sent to the output queue; the remainder of the line becomes the new current line. Qualifiers can be used to restrict the context of the string.
|-
| Join two lines || C,L [<string>] || Joins the current line with the next line of the source file. The string argument is optional; however, if a string is specified it is added to the end of the current line and that whole line is joined with the next line in the source file.
|}

== Renumbering Lines ==

These commands renumber the source file's lines to include non-original lines and to update a file that has been edited.

{| class="wikitable"
| Renumber source lines || = <n> || Sets the current line number to <n>. All subsequent original and non-original lines below <n> are renumbered you move to them.
|-
| Return to the beginning source file || REWIND || Moves back through the source file to make line 1 the current line. EDIT scans the rest of the source file and writes the lines to the destination file. This file is closed and reopened as a new source file. Non-original lines are now recognized as original lines. Can be entered as REWI.
|}

== Verifying Lines ==

These commands describe different ways of verifying lines.

{| class="wikitable"
| Turn Verification on/off || V + <nowiki>|</nowiki> - || Turns line verification on or off. If off, the lines are not displayed on the screen. To turn off, enter V -. To turn on, enter V +.
|-
| Verify the current line || ? || Verifies the current line by displaying the line number and the contents of the line.
|-
| Verify the current line with character indicators || ! || Produces two lines of verification. In the first line all non-graphic characters are replaced with the first character of their hexadecimal value In the second line, a minus sign is displayed under all positions corresponding to upper case letters and the second hexadecimal digit corresponds to non-graphic characters. All other positions contain spaces. In binary files, non-graphic characters are represented with question marks (??).
|}

== Inspecting the Source File ==

These commands advance through the source file, sending the lines it passes to the verification file, as well as to the normal output. They are known as Type commands because they display lines on the screen.

{| class="wikitable"
| Type <n> lines to the screen || T <n> || Types the specified number of lines to the screen. The first line typed is the current line. Omitting the <n> continues typing to the end of the source file. Interrupt the command with Ctrl+C.
|-
| Type the lines in the output queue || T,P || Displays the lines currently held in the output queue.
|-
| Type until EDIT has replaced all the lines in the output queue || T,N || Types from the current line forward until all the lines in the output queue are replaced. The previous contents are sent to the destination file.
|-
| Type with line numbers || T,L <n> || Similar to the T command. Types a specified number of lines, displaying the line numbers. EDIT displays + + + + for inserted or split lines since they do not have line numbers.
|}

== Making Global Changes ==

These commands start and stop global changes. Global changes take place automatically as EDIT scans the source file in forward direction. These commands automatically apply an A, B, or E command, as appropriate, to any occurrence of <string1> in a new current line. They also apply to the current line that is in effect when the command is given.

GA [qualifier] <string1> <string2>
GB [qualifier] <string1> <string2>
GE [qualifier] <string1> <string2>

For example, if you want to change DF0: to DF2: throughout an entire file, enter:

GE /DF0:/DF2:/

{| class="wikitable"
| Cancel a global command || CG [<id number>] || Cancels a global command. The identification number set with a GA, GB, or GE command is output to the verification file or the serene if EDIT is interactive. If no argument is specified, all global operations are cancelled. To cancel a specific operation, enter the identification number of the CG command.
|-
| Suspend a global command || SG [<id number>] || Suspends a global command. All global operations are suspended if no argument is given. Enter the identification number to suspend a specific operation.
|-
| Enable a global command || EG [<id number>] || Resumes global operation that had been suspended with the SG command. Unless a specific identification number is provided, all global commands are resumed.
|-
| Show global commands || SHG || Displays the current global commands and their identification numbers. Also provides the number of times each global string was matched.
|}

== Changing Command, Input, and Output Files ==

These commands change the files set up when you started EDIT from the Shell. These files are:

* the command file - started with the WITH option.
* the input file - the source file specified with FROM.
* the output file - the destination file specified with TO.

{| class="wikitable"
| Changing the Command File || C <filename> || Reads EDIT commands from a specified file. Delimit the file using a character other than a slash (/) since AmigaDOS uses these characters to separate file names. When all commands in the specified file are executed, the file is closed. You can then enter the commands through the keyboard.
|-
| Changing the Input File || FROM <filename> || Reads lines from another source file. EDIT does not close the original source file. Reselect the source file by entering the FROM command without an argument. For example of the FROM command, see page 4-54.
|-
| Closing a File || CF <filename> || Closes the destination file that was originally specified with the TO command. You can then open that file for input. CF can also close a new input file that is open. For examples of the CF command, see page 4-54.
|-
| Changing the Output File || TO <filename> || Specifies a different file as the destination file. The TO command writes the existing queue of output lines to the new TO file. The new TO file is used until another file is specified. Reselect the original destination file by using the TO command with no argument. The alternate output file remains open, but unused. For examples of the TO command, see page 4-54.
|-
| Stop executing the command file || Q || Stops EDIT from executing the current command file specified with the WITH keyword or with the C command. EDIT reverts to any previous command file. Using Q at the outermost level is equivalent to using the W command.
|}

The FROM, CF, and TO commands are used as follows:

{| class="wikitable"
! Command !! Action
|-
| M10 || Pass lines 1-9 in the original source file to the output queue.
|-
| FROM .XYZ. || Select the XYZ file for new input; line 10 of the original source file remains current.
|-
| M6 || Pass line 10 from the original file, then pass lines 1-5 from the XYZ file to the output queue. Line 6 of XYZ is the new current line.
|-
| FROM || Reselect the original source file.
|-
| M14 || Pass line 6 from XYZ, then lines 11-13 from the original source file to the output queue. Line 14 of the source file is the new current line.
|-
| FROM .XYZ. || Reselect file XYZ. Line 14 of the source file is still the current line.
|-
| M* || Pass line 14 of the source file and all remaining lines of file XYZ to the output queue. An extra line is added to the end of file XYZ. That line is the new current line.
|-
| FROM || Reselect the original source file. The extra line added to file XYZ is still the current line.
|-
| CF .XYZ. || Close file XYZ.
|-
| M* || Pass the remaining lines of the source file (lines 15 to the end of the file) to the output queue.
|-
| M11 || Pass lines 1-10 of the source file to the original destination file.
|-
| TO .XYZ. || Make XYZ the new output file.
|-
| M21 || Pass lines 11-20 to file XYZ.
|-
| TO M31 || Make the original destination file current, and pass lines 21 to 30 to it.
|-
| TO .XYZ. || Make XYZ the current output file.
|-
| M41 || Pass lines 31 to 40 to XYZ.
|-
| TO || Make the original destination file current.
|-
| TO .XYZ. || Send the output queue to file XYZ.
|-
| 1000N || Advance through the next 1000 lines of the source file.
|-
| TO || Select the original destination file.
|-
| CF .XYZ. || Close the XYZ file.
|-
| I2000 .XYZ. || Insert the 1000 lines from the source file that were sent to file XYZ back into the source file above line 2000.
|}

== Ending EDIT ==

These commands exit EDIT.

{| class="wikitable"
| Exit, saving changes || W || Exits EDIT, saving all changes to the destination file specified by TO. EDIT exits after reaching the end of the source, closing all the files, and relinquishing memory. If you started EDIT without specifying a destination file, it renames the temporary destination with the same name as the original source file, which is renamed. T/Edit-backup. This backup is only available until the next time you run EDIT.
|-
| Exit, without saving changes || STOP || Stops EDIT immediately without saving any changes to the source file. Prevents EDIT from overwriting to original source file, ensuring that no changes are made to the original input information.
|}

MediaWiki:Sidebar

2025-09-12T05:33:18Z

Costel Mincea:

* Navigation
** mainpage|mainpage-description
** recentchanges-url|recentchanges
* Developers
** Autodocs:Main|Autodocs
** Tutorials:Main|Tutorials
** DeveloperDoc:Registries|Registries
** DeveloperDoc:Standards|Standards
** DeveloperDoc:Main|Reference
** https://www.amigaos.net/viewforum.php?f=25|AmigaOS Support Forums
** https://os4coding.net/forum|OS4Coding Forum
** https://www.hyperion-entertainment.com/index.php/downloads?view=files&parent=30|Get the SDK
* Users
** AmigaOS_Manual:_Workbench|Workbench
** AmigaOS_Manual:_AmigaDOS|DOS
** AmigaOS_Manual:_ARexx|ARexx
** Bars_%26_Pipes_Professional|Bars & Pipes Professional
* Links
** https://www.hyperion-entertainment.com/|Hyperion Entertainment
** https://www.amigaos.net/|AmigaOS Web Site
** http://support.amigaos.net/|AmigaOS Support Forums
* SEARCH
* TOOLBOX

MediaWiki:Sidebar

2025-09-12T05:32:44Z

Costel Mincea:

* Navigation
** mainpage|mainpage-description
** recentchanges-url|recentchanges
* Developers
** Autodocs:Main|Autodocs
** Tutorials:Main|Tutorials
** DeveloperDoc:Registries|Registries
** DeveloperDoc:Standards|Standards
** DeveloperDoc:Main|Reference
** https://www.amigaos.net/viewforum.php?f=25|AmigaOS Support Forums (*)
** https://os4coding.net/forum|OS4Coding Forum (*)
** https://www.hyperion-entertainment.com/index.php/downloads?view=files&parent=30|Get the SDK (*)
* Users
** AmigaOS_Manual:_Workbench|Workbench
** AmigaOS_Manual:_AmigaDOS|DOS
** AmigaOS_Manual:_ARexx|ARexx
** Bars_%26_Pipes_Professional|Bars & Pipes Professional
* Links
** https://www.hyperion-entertainment.com/|Hyperion Entertainment (*)
** https://www.amigaos.net/|AmigaOS Web Site (*)
** http://support.amigaos.net/|AmigaOS Support Forums (*)
* (*) external
* SEARCH
* TOOLBOX

MediaWiki:Sidebar

2025-09-12T05:32:10Z

Costel Mincea:

* Navigation
** mainpage|mainpage-description
** recentchanges-url|recentchanges
* Developers
** Autodocs:Main|Autodocs
** Tutorials:Main|Tutorials
** DeveloperDoc:Registries|Registries
** DeveloperDoc:Standards|Standards
** DeveloperDoc:Main|Reference
** https://www.amigaos.net/viewforum.php?f=25|AmigaOS Support Forums (*)
** https://os4coding.net/forum|OS4Coding Forum (*)
** https://www.hyperion-entertainment.com/index.php/downloads?view=files&parent=30|Get the SDK (*)
* Users
** AmigaOS_Manual:_Workbench|Workbench
** AmigaOS_Manual:_AmigaDOS|DOS
** AmigaOS_Manual:_ARexx|ARexx
** Bars_%26_Pipes_Professional|Bars & Pipes Professional
* Links
** https://www.hyperion-entertainment.com/|Hyperion Entertainment*
** https://www.amigaos.net/|AmigaOS Web Site*
** http://support.amigaos.net/|AmigaOS Support Forums*
* SEARCH
* TOOLBOX

MediaWiki:Sidebar

2025-09-12T05:31:49Z

Costel Mincea:

* Navigation
** mainpage|mainpage-description
** recentchanges-url|recentchanges
* Developers
** Autodocs:Main|Autodocs
** Tutorials:Main|Tutorials
** DeveloperDoc:Registries|Registries
** DeveloperDoc:Standards|Standards
** DeveloperDoc:Main|Reference
** https://www.amigaos.net/viewforum.php?f=25|AmigaOS Support Forums[*]
** https://os4coding.net/forum|OS4Coding Forum[*]
** https://www.hyperion-entertainment.com/index.php/downloads?view=files&parent=30|Get the SDK[*]
* Users
** AmigaOS_Manual:_Workbench|Workbench
** AmigaOS_Manual:_AmigaDOS|DOS
** AmigaOS_Manual:_ARexx|ARexx
** Bars_%26_Pipes_Professional|Bars & Pipes Professional
* Links
** https://www.hyperion-entertainment.com/|Hyperion Entertainment*
** https://www.amigaos.net/|AmigaOS Web Site*
** http://support.amigaos.net/|AmigaOS Support Forums*
* SEARCH
* TOOLBOX

MediaWiki:Sidebar

2025-09-12T05:31:09Z

Costel Mincea:

* Navigation
** mainpage|mainpage-description
** recentchanges-url|recentchanges
* Developers
** Autodocs:Main|Autodocs
** Tutorials:Main|Tutorials
** DeveloperDoc:Registries|Registries
** DeveloperDoc:Standards|Standards
** DeveloperDoc:Main|Reference
** https://www.amigaos.net/viewforum.php?f=25|AmigaOS Support Forums*
** https://os4coding.net/forum|OS4Coding Forum*
** https://www.hyperion-entertainment.com/index.php/downloads?view=files&parent=30|Get the SDK*
* Users
** AmigaOS_Manual:_Workbench|Workbench
** AmigaOS_Manual:_AmigaDOS|DOS
** AmigaOS_Manual:_ARexx|ARexx
** Bars_%26_Pipes_Professional|Bars & Pipes Professional
* Links
** https://www.hyperion-entertainment.com/|Hyperion Entertainment*
** https://www.amigaos.net/|AmigaOS Web Site*
** http://support.amigaos.net/|AmigaOS Support Forums*
* SEARCH
* TOOLBOX

(*) external site

MediaWiki:Sidebar

2025-09-12T05:29:20Z

Costel Mincea:

* Navigation
** mainpage|mainpage-description
** recentchanges-url|recentchanges
* Developers
** Autodocs:Main|Autodocs
** Tutorials:Main|Tutorials
** DeveloperDoc:Registries|Registries
** DeveloperDoc:Standards|Standards
** DeveloperDoc:Main|Reference
** https://www.amigaos.net/viewforum.php?f=25|AmigaOS Support Forums (ext)
** https://os4coding.net/forum|OS4Coding Forum (ext)
** https://www.hyperion-entertainment.com/index.php/downloads?view=files&parent=30|Get the SDK (ext)
* Users
** AmigaOS_Manual:_Workbench|Workbench
** AmigaOS_Manual:_AmigaDOS|DOS
** AmigaOS_Manual:_ARexx|ARexx
** Bars_%26_Pipes_Professional|Bars & Pipes Professional
* Links
** https://www.hyperion-entertainment.com/|Hyperion Entertainment (ext)
** https://www.amigaos.net/|AmigaOS Web Site (ext)
** http://support.amigaos.net/|AmigaOS Support Forums (ext)
* SEARCH
* TOOLBOX

MediaWiki:Sidebar

2025-09-12T05:26:33Z

Costel Mincea:

* Navigation
** mainpage|mainpage-description
** recentchanges-url|recentchanges
* Developers
** Autodocs:Main|Autodocs
** Tutorials:Main|Tutorials
** DeveloperDoc:Registries|Registries
** DeveloperDoc:Standards|Standards
** DeveloperDoc:Main|Reference
** [https://www.amigaos.net/viewforum.php?f=25 AmigaOS Support Forums]
** [https://os4coding.net/forum OS4Coding Forum]
** [https://www.hyperion-entertainment.com/index.php/downloads?view=files&parent=30 SDK]
* Users
** AmigaOS_Manual:_Workbench|Workbench
** AmigaOS_Manual:_AmigaDOS|DOS
** AmigaOS_Manual:_ARexx|ARexx
** Bars_%26_Pipes_Professional|Bars & Pipes Professional
* Links
** [https://www.hyperion-entertainment.com/ Hyperion Entertainment]
** [https://www.amigaos.net/ AmigaOS Web Site]
** [http://support.amigaos.net/ AmigaOS Support Forums]
* SEARCH
* TOOLBOX

Writing Datatype Classes

2025-01-26T19:46:12Z

Costel Mincea: Text replacement - "<syntaxhighlight>" to "<syntaxhighlight lang="C" line>"

= Subclassing =

For each of the DataType categories, there is a class that handles the data. Handlers for explicit data are subclasses under the appropriate class. For example, a class that handles ILBM pictures would be a subclass of the Picture class.

In order to fully understand the class concept used by DataTypes it helps to have a basic understanding of BOOPSI.

A subclass must provide an OM_NEW method that converts the source data into the data format required by the superclass. The subclass must optionally have a OM_DISPOSE method that discards any of the data constructed in the OM_NEW method. All other methods must be passed to the superclass.

Following is a listing of a example class dispatcher for a subclass of the picture class:

<syntaxhighlight lang="C" line>
uint32 Dispatch(Class *cl, Object *o, Msg msg)
{
struct ClassBase *cb = (struct ClassBase *) cl->cl_UserData;
uint32 retval;

switch (msg->MethodID)
{
case OM_NEW:
if (retval = IIntuition->IDoSuperMethodA(cl, o, msg))
{
/* Convert the source data to required data format */
if (!GetObjectData (cb, cl, (Object *)retval,
((struct opSet *) msg)->ops_AttrList))
{
/* Force disposal of the object */
IIntuition->ICoerceMethod (cl, (Object *) retval, OM_DISPOSE);
retval = NULL;
}
}
break;

/* Let the superclass handle everything else */
default:
retval = (uint32) IIntuition->IDoSuperMethodA (cl, o, msg);
break;
}

return (retval);
}
</syntaxhighlight>

== Obtaining a Handle to the Source Data ==

The first step that a class has to perform in order to convert the source data, is to get a handle on the data. This is obtained by passing the DTA_Handle tag to the superclass using the OM_GET method. For example:

<syntaxhighlight lang="C" line>
Object *o;
BPTR fh;

IDataTypes->GetDTAttrs(o, DTA_Handle, &fh, TAG_END);
</syntaxhighlight>

If the source Type is DTF_IFF, then DTA_Handle points to a struct IFFHandle that is already initialized and opened for reading, otherwise the handle points to a BPTR file handle.

== Handling Errors ==

Whenever an error occurs and the class is unable to continue converting the data, then it must set an appropriate error using the DOS SetIoErr() function and the <dos/dos.h> error codes or the error codes defined in <datatypes/datatypes.h>.

For example, if the class is unable to allocate memory:

<syntaxhighlight lang="C" line>
if (buf = IExec->AllocVecTags(size, AVT_ClearWithValue, 0, TAG_END))
{
... continue with conversion ...
}
else
{
IDOS->SetIoErr (ERROR_NO_FREE_STORE);
</syntaxhighlight>

== Data Format ==

The following sections outline the required data format for each of the main object types.

=== Picture Class ===

The picture class is the superclass for any static graphic classes. The structures and tags used by this class are defined in <datatypes/pictureclass.h>.

A picture subclass must fill out a BitMapHeader structure as well as provide a Mode ID, a BitMap and a ColorMap during the OM_NEW method of the class. There is no need to provide any other methods, as the remainder is handled by the picture class itself.

The picture subclass needs to fill in any fields of the BitMapHeader structure that the class has data for. This will ensure that the picture data can then be saved to a file or copied to the clipboard.

<syntaxhighlight lang="C" line>
struct BitMapHeader *bmh;

/* Obtain a pointer to the BitMapHeader structure from the picture class */
if (IDataTypes->GetDTAttrs (dto, PDTA_BitMapHeader, &bmh, TAG_END) && bmh)
{
/* Fill in some fields */
bmh->bmh_Width = 640;
bmh->bmh_Height = 200;
bmh->bmh_Depth = 2;
}
</syntaxhighlight>

Before manipulating any color information, the picture subclass must first tell the picture class how many colors it has, so that the information required for color remapping can be established.

<syntaxhighlight lang="C" line>
IDataTypes->SetDTAttrs (dto, PDTA_NumColors, ncolors, TAG_END);
</syntaxhighlight>

After the number of colors have been established, the palette information can be filled in for the picture. The following fragment illustrates filling in the palette information.

<syntaxhighlight lang="C" line>
struct ColorRegister *cmap;
int16 n, ncolors;
int32 *cregs;

/* Get a pointer to the color registers that need to be
* filled in */
IDataTypes->GetDTAttrs (dto,
PDTA_ColorRegisters, &cmap,
PDTA_CRegs, &cregs,
TAG_END);

/* Set the color information */
for (n = 0; n < ncolors; n++)
{
if (IDOS->Read (fh, &rgb, QSIZE) == QSIZE)
{
/* Set the master color table */
cmap->red = rgb.rgbRed;
cmap->green = rgb.rgbGreen;
cmap->blue = rgb.rgbBlue;
cmap++;

/* Set the color table used for remapping */
cregs[n * 3 + 0] = rgb.rgbRed << 24;
cregs[n * 3 + 1] = rgb.rgbGreen << 24;
cregs[n * 3 + 2] = rgb.rgbBlue << 24;
}
else
{
/* Indicate that we encountered an error. DOS Read
* will have already filled in the IoErr() value */
return FALSE;
}
}
</syntaxhighlight>

The picture class must get the actual picture information in standard Amiga bitmap format. If the bitmap is allocated using the graphics AllocBitMap() function, then the picture class can dispose of the bitmap at OM_DISPOSE time.

<syntaxhighlight lang="C" line>
struct BitMap *bm;

if (bm = IGraphics->AllocBitMap (bmh->bmh_Width, bmh->bmh_Height, bmh->bmh_Depth, BMF_CLEAR, NULL))
{
/* Tell the picture class about the picture data */
IDataTypes->SetDTAttrsA (dto, PDTA_BitMap, bm, TAG_END);
}
else
{
/* Indicate the error and that we encountered an error */
IDOS->SetIoErr (ERROR_NO_FREE_STORE);
return FALSE;
}
</syntaxhighlight>

A picture subclass needs to provide the following fields to the superclass, during the OM_NEW method:

{| class="wikitable"
| DTA_NominalHoriz || (int32) Set to the width of the picture.
|-
| DTA_NominalVert || (int32) Set to the height of the picture.
|-
| PDTA_ModeID || (uint32) A valid mode ID for the BitMap.
|-
| DTA_ObjName || (STRPTR) The name, or title, of the picture
|-
| DTA_ObjAuthor || (STRPTR) The author of the picture.
|-
| DTA_ObjAnnotation || (STRPTR) Notes on the picture.
|-
| DTA_ObjCopyright || (STRPTR) Copyright notice for the picture.
|-
| DTA_ObjVersion || (STRPTR) Version of the picture.
|}

If a picture subclass uses something other than AllocBitMap() to allocate the bitmap, then it must free the bitmap itself. This is done by implementing an OM_DISPOSE method for the subclass.

<syntaxhighlight lang="C" line>
uint32 Dispatch (Class *cl, Object *o, Msg msg)
{
struct ClassBase *cb = (struct ClassBase *) cl->cl_UserData;
struct localData *lod;
uint32 retval;

switch (msg->MethodID)
{
case OM_NEW:
/* ... */
break;

case OM_DISPOSE:
/* Get a pointer to our object data */
lod = INST_DATA (cl, o);

/* Tell the picture class that it doesn't have a
* bitmap to free any more */
IDataTypes->SetDTAttrs (o, PDTA_BitMap, NULL, TAG_END);

/* Free the bitmap ourself */
myfreebitmap (lod->lod_BitMap);

/* Let the superclass handle everything else */
default:
retval = (uint32) IIntuition->DoSuperMethodA (cl, o, msg);
break;
}

return retval;
}
</syntaxhighlight>

=== Sound Class ===

The sound class is the superclass for any sampled audio classes. The structures and tags used by this class are defined in
<datatypes/soundclass.h>.

A sound subclass needs to provide the following fields to the superclass, during the OM_NEW method:

{| class="wikitable"
| SDTA_Sample || (uint8 *) 8-bit sound data. The sound class will FreeVec() the sample data.
|-
| SDTA_SampleLength || (uint32) Number of 8-bit bytes in the sound data.
|-
| SDTA_Volume || (uint16) Number ranging from 0 being the quietest to 64 being the loudest.
|-
| SDTA_Period || (uint16) Amount of time to play the sound.
|-
| SDTA_Cycles || (uint16) Number of times to play the sound. 0 being an infinite loop.
|-
| DTA_ObjName || (STRPTR) The name, or title, of the sound
|-
| DTA_ObjAuthor || (STRPTR) The author of the sound.
|-
| DTA_ObjAnnotation || (STRPTR) Notes on the sound.
|-
| DTA_ObjCopyright || (STRPTR) Copyright notice for the sound.
|-
| DTA_ObjVersion || (STRPTR) Version of the sound.
|}

No methods other OM_NEW are need, as the remainder is handled by the sound class itself.

The sound subclass also needs to fill in any fields of the VoiceHeader structure that the class has data for. This will ensure that the sound data can then be saved to a file or copied to the clipboard.

<syntaxhighlight lang="C" line>
struct VoiceHeader *vh;

/* Obtain a pointer to the VoiceHeader structure from the sound class */
if (IDataTypes->GetDTAttrs (dto, SDTA_VoiceHeader, &vh, TAG_END) && vh)
{
/* Fill in some fields */
vh->vh_Octaves = 1;
vh->vh_Compression = 0;
vh->vh_Volume = 63;
}
</syntaxhighlight>

If a sound subclass uses something other than AllocVec() to allocate the sound data, then it must free the sample itself. This is done by implementing an OM_DISPOSE method for the subclass.

<syntaxhighlight lang="C" line>
uint32 Dispatch (Class *cl, Object *o, Msg msg)
{
struct ClassBase *cb = (struct ClassBase *) cl->cl_UserData;
struct localData *lod;
uint32 retval;

switch (msg->MethodID)
{
case OM_NEW:
/* ... */
break;

case OM_DISPOSE:
/* Get a pointer to our object data */
lod = INST_DATA (cl, o);

/* Tell the sound class that it doesn't have a
* sample to free any more */
IDataTypes->SetDTAttrs (o, SDTA_Sample, NULL, TAG_END);

/* Free the sample ourself */
IExec->FreeVec(lod->lod_Sample);

/* Let the superclass handle everything else */
default:
retval = (uint32) IIntuition->IDoSuperMethodA (cl, o, msg);
break;
}

return retval;
}
</syntaxhighlight>

=== Text Class ===

The text class is the superclass for any formatted or non-formatted text classes. The structures and tags used by this class are defined in <datatypes/textclass.h>.

The text class provides the subclass with a buffer that contains the text data. The subclass must then provide the text class with a list of Line segments during the layout method. This Line list should only be created at gpl_Initial time, unless the TDTA_WordWrap attribute is TRUE.

<syntaxhighlight lang="C" line>
struct Line
{
struct MinNode ln_Link;
STRPTR ln_Text;
ULONG ln_TextLen;
UWORD ln_XOffset;
UWORD ln_YOffset;
UWORD ln_Width;
UWORD ln_Height;
UWORD ln_Flags;
BYTE ln_FgPen;
BYTE ln_BgPen;
ULONG ln_Style;
APTR ln_Data;
};
</syntaxhighlight>

The Line structure fields are as follows:

;ln_Link
: MinNode used to link to the line list.

; ln_Text
: Pointer to the text for this line segment.

; ln_TextLen
: Number of bytes of text in this line segment.

; ln_XOffset
: Left pixel offset from the left edge of the object for this line segment.

; ln_YOffset
: Top pixel offset from the top edge of the object for this line segment.

; ln_Width
: Width of the line segment in pixels.

; ln_Height
: Height of the line segment in pixels.

; ln_Flags
: Control flags for this line segment.
:: LNF_LF -- Used to indicate that this segment is the end of a line.

; ln_FgPen
: Pen to use for the foreground (the text color) for this line segment.

; ln_BgPen
: Pen to use for the background color for this line segment.

; ln_Style
: Text attribute soft style to use for this line segment.

As each Line segment is allocated it must be added to the Line list.

<syntaxhighlight lang="C" line>
struct List *linelist;
struct Line *line;

/* Get a pointer to the line list */
if (IDataTypes->GetDTAttrs (o, TDTA_LineList, (uint32) &linelist, TAG_END) && linelist)
{
/* Create a Line segment */
if (line = AllocVecTags(sizeof (struct Line), AVT_ClearWithValue, 0, TAG_END))
{
/* Add it to the list */
IExec->AddTail (linelist, (struct Node *)&line->ln_Link);
}
}
</syntaxhighlight>

Currently, this is the hardest class to subclass, due to the number of methods that must be implemented. Following is the shell for a dispatcher and the layout method for a text subclass.

<syntaxhighlight lang="C" line>
struct localData
{
VOID *lod_Pool;
uint32 lod_Flags;
};

uint32 Dispatch (Class * cl, Object * o, Msg msg)
{
struct ClassBase *cb = (struct ClassBase *) cl->cl_UserData;
struct localData *lod;
struct List *linelist;
uint32G retval = 0;

switch (msg->MethodID)
{
case OM_NEW:
if (retval = IIntuition->IDoSuperMethodA (cl, o, msg))
{
uint32 len, estlines, poolsize;
BOOL success = FALSE;
STRPTR buffer;

/* Get a pointer to the object data */
lod = INST_DATA (cl, (Object *) retval);

/* Get the attributes that we need to determine memory pool size */
IDataTypes->GetDTAttrs ((Object *) retval,
TDTA_Buffer, &buffer,
TDTA_BufferLen, &len,
TAG_END);

/* Make sure we have a text buffer */
if (buffer && len)
{
/* Estimate the pool size that we will need */
estlines = (len / 80) + 1;
estlines = (estlines > 200) ? 200 : estlines;
poolsize = sizeof (struct Line) * estlines;

/* Create a memory pool for the line list */
lod->lod_Pool = IExec->AllocSysObjectTags(ASOT_MEMPOOL,
ASOPOOL_MFlags, MEMF_SHARED | MEMF_CLEAR,
ASOPOOL_Puddle, poolsize,
ASOPOOL_Threshold, poolsize,
TAG_END);
if (lod->lod_Pool != NULL)
success = TRUE;
else
IDOS->SetIoErr (ERROR_NO_FREE_STORE);
}
else
{
/* Indicate that something was missing that we needed */
IDOS->SetIoErr (ERROR_REQUIRED_ARG_MISSING);
}

if (!success)
{
IIntuition->ICoerceMethod (cl, (Object *) retval, OM_DISPOSE);
retval = NULL;
}
}
break;

case OM_UPDATE:
case OM_SET:
/* Pass the attributes to the text class and force a refresh if we need it */
if ((retval = IIntuition->IDoSuperMethodA (cl, o, msg)) && (OCLASS (o) == cl))
{
struct RastPort *rp;

/* Get a pointer to the rastport */
if (rp = IGraphics->ObtainGIRPort (((struct opSet *) msg)->ops_GInfo))
{
IIntuition->DoRender(o, ((struct opSet *) msg)->ops_GInfo, GREDRAW_UPDATE);

/* Release the temporary rastport */
IGraphics->ReleaseGIRPort (rp);
}
retval = 0;
}
break;

case GM_LAYOUT:
/* Tell everyone that we are busy doing things */
notifyAttrChanges (o, ((struct gpLayout *) msg)->gpl_GInfo, NULL,
GA_ID, G(o)->GadgetID,
DTA_Busy, TRUE,
TAG_END);

/* Let the superclass partake */
retval = (uint32) IIntuition->IDoSuperMethodA (cl, o, msg);

/* We need to do this one asynchronously */
retval += IDataTypes->DoAsyncLayout (o, (struct gpLayout *) msg);
break;

case DTM_PROCLAYOUT:
/* Tell everyone that we are busy doing things */
notifyAttrChanges (o, ((struct gpLayout *) msg)->gpl_GInfo, NULL,
GA_ID, G(o)->GadgetID,
DTA_Busy, TRUE,
TAG_END);

/* Let the superclass partake and then fall through to our layout method */
retval = (uint32) IDataTypes->DoSuperMethodA (cl, o, msg);

case DTM_ASYNCLAYOUT:
/* Layout the text */
retval = layoutMethod (cb, cl, o, (struct gpLayout *) msg);
break;

case OM_DISPOSE:
/* Get a pointer to our object data */
lod = INST_DATA (cl, o);

/* Don't let the super class free the line list */
if (IIntuition->GetDTAttrs (o, TDTA_LineList, &linelist, TAG_END) && linelist)
IExec->NewList (linelist);

/* Delete the line pool */
IExec->FreeSysObject(ASOT_MEMPOOL, lod->lod_Pool);

/* Let the superclass handle everything else */
default:
retval = (uint32) IIntuition->DoSuperMethodA (cl, o, msg);
break;
}

return (retval);
}

uint32 layoutMethod (struct ClassBase *cb, Class * cl, Object * o, struct gpLayout * gpl)
{
struct DTSpecialInfo *si = (struct DTSpecialInfo *) G (o)->SpecialInfo;
struct localData *lod = INST_DATA (cl, o);
uint32 visible = 0, total = 0;
struct RastPort trp;
uint32 hunit = 1;
uint32 bsig = 0;

/* Switches */
BOOL linefeed = FALSE;
BOOL newseg = FALSE;
BOOL abort = FALSE;

/* Attributes obtained from superclass */
struct TextAttr *tattr;
struct TextFont *font;
struct List *linelist;
struct IBox *domain;
uint32 wrap = FALSE;
uint32 bufferlen;
STRPTR buffer;
STRPTR title;

/* Line information */
uint32 num, offset, swidth;
uint32 anchor, newanchor;
uint32 style = FS_NORMAL;
struct Line *line;
uint32 yoffset = 0;
uint8 fgpen = 1;
uint8 bgpen = 0;
uint32 tabspace;
uint32 numtabs;
uint32 i, j;

uint32 nomwidth, nomheight;

/* Get all the attributes that we are going to need for a successful layout */
if (IDataTypes->GetDTAttrs (o,
DTA_TextAttr, &tattr,
DTA_TextFont, &font,
DTA_Domain, &domain,
DTA_ObjName, &title,
TDTA_Buffer, &buffer,
TDTA_BufferLen,&bufferlen,
TDTA_LineList, &linelist,
TDTA_WordWrap, &wrap,
TAG_END) == 8)
{
/* Lock the global object data so that nobody else can manipulate it */
IExec->ObtainSemaphore (&(si->si_Lock));

/* Make sure we have a buffer */
if (buffer)
{
/* Initialize the temporary RastPort */
IGraphics->InitRastPort (&trp);
IGraphics->SetFont (&trp, font);

/* Calculate the nominal size */
nomheight = (ULONG) (24 * font->tf_YSize);
nomwidth = (ULONG) (80 * font->tf_XSize);

/* Calculate the tab space */
tabspace = font->tf_XSize * 8;

/* We only need to perform layout if we are doing word wrap, or this
* is the initial layout call */
if (wrap || gpl->gpl_Initial)
{
/* Delete the old line list */
while (line = (struct Line *) IExec->RemHead (linelist))
IExec->FreePooled (lod->lod_Pool, line, sizeof (struct Line));

/* Step through the text buffer */
for (i = offset = num = numtabs = 0;
(i <= bufferlen) && (bsig == 0) && !abort;
i++)
{
/* Check for end of line */
if (buffer[i]==13 && buffer[i+1]==10)
{
newseg = linefeed = TRUE;
newanchor = i + 2;
i++;
}
/* Check for end of page */
else if (buffer[i] == 12)
{
newseg = linefeed = TRUE;
newanchor = i + 1;
}
/* Check for tab */
else if (buffer[i] == 9)
{
/* See if we need to terminate a line segment */
if ((numtabs == 0) && num)
newseg = TRUE;
numtabs++;
}
else
{
/* See if we have any TABs that we need to finish out */
if (numtabs)
{
offset += (((offset / tabspace) + 1) * tabspace) - offset;
num = numtabs = 0;
anchor = i;
}

/* Compute the width of the line. */
swidth = IGraphics->TextLength (&trp, &buffer[anchor], num+1);
if (offset + swidth > domain->Width)
{
/* Search for a whitespace character */
for (j = i; (j >= anchor) && !newseg; j--)
{
if (buffer[j] == ' ')
{
num -= (i - j);
newseg = TRUE;
i = j + 1;
}
}

newseg = linefeed = TRUE;
newanchor = i;
i--;
}
else
{
num++;
}
}

/* Time for a new text segment yet? */
if (newseg)
{
/* Allocate a new line segment from our memory pool */
if (line = IExec->AllocPooled (lod->lod_Pool, sizeof (struct Line)))
{
swidth = IGraphics->TextLength (&trp, &buffer[anchor], num);
line->ln_Text = &buffer[anchor];
line->ln_TextLen = num;
line->ln_XOffset = offset;
line->ln_YOffset = yoffset + font->tf_Baseline;
line->ln_Width = swidth;
line->ln_Height = font->tf_YSize;
line->ln_Flags = (linefeed) ? LNF_LF : NULL;
line->ln_FgPen = fgpen;
line->ln_BgPen = bgpen;
line->ln_Style = style;
line->ln_Data = NULL;

/* Add the line to the list */
IExec->AddTail (linelist, (struct Node *) line);

/* Increment the line count */
if (linefeed)
{
yoffset += font->tf_YSize;
offset = 0;
total++;
}
else
{
/* Increment the offset */
offset += swidth;
}
}
else
{
abort = TRUE;
}

/* Clear the variables */
newseg = linefeed = FALSE;
anchor = newanchor;
num = 0;

/* Check to see if layout has been aborted */
bsig = IDOS->CheckSignal (SIGBREAKF_CTRL_C);
}
}
}
else
{
/* No layout to perform */
total = si->si_TotVert;
}
}

/* Compute the lines and columns type information */
si->si_VertUnit = font->tf_YSize;
si->si_VisVert = visible = domain->Height / si->si_VertUnit;
si->si_TotVert = total;

si->si_HorizUnit = hunit = 1;
si->si_VisHoriz = (int32) domain->Width / hunit;
si->si_TotHoriz = domain->Width;

/* Release the global data lock */
IExec->ReleaseSemaphore (&si->si_Lock);

/* Were we aborted? */
if (bsig == 0)
{
/* Not aborted, so tell the world of our newest attributes */
notifyAttrChanges (o, gpl->gpl_GInfo, NULL,
GA_ID, G(o)->GadgetID,

DTA_VisibleVert, visible,
DTA_TotalVert, total,
DTA_NominalVert, nomheight,
DTA_VertUnit, font->tf_YSize,

DTA_VisibleHoriz, (uint32) (domain->Width / hunit),
DTA_TotalHoriz, domain->Width,
DTA_NominalHoriz, nomwidth,
DTA_HorizUnit, hunit,

DTA_Title, title,
DTA_Busy, FALSE,
DTA_Sync, TRUE,
TAG_END);
}
}

return total;
}
</syntaxhighlight>

= Writing a Superclass =

(relevant text to be provided)

= Defining a DataType Descriptor =

DataTypes uses a simple descriptor to determine what type of data a file contains and what class, if any, is used to handle that data.

The DTDesc utility is used to define a DataType descriptor. The following steps describe how to use this utility to define a descriptor.

1. Load several sample files of the type being defined. This can be done by dropping their icons into the DTDesc window or by using the "Extras/Load Samples..." menu item.

2. The view area in the bottom right side of the DTDesc window will show the first 64 characters of the files. This area is used to define the Mask. The characters that don't match will be blotted out and only the similar characters will be shown. If more characters are shown as similar than really are, then they can easily be blotted out by rubbing over them.

3. DataTypes can be broken out into several different categories. Use the Group menu to select the category that the DataType descriptor belongs in.

4. The remaining fields must be filled out. Following is a table describing the fields and the information they require.

:{| class="wikitable"
! Name !! Description
|-
| File Type || User description of the DataType.
|-
| Base Name || The base name of the DataType. The class library name is derived from this.
|-
| Name Pattern || The name of the file can be used to indicate the DataType. AmigaDOS wildcards can be used to specify the file name.
|-
| Function || A function can be used to further define a data type. This function must be a stand-alone executable that uses the DataType Descriptor Function Interface.
|-
| Case Sensitive? || The Mask can be either case sensitive or not.
|-
| Priority || Descriptors are sorted by Type, Function, Name Pattern and Mask. The priority field allows a DataType descriptor to be assigned a different priority than a similar DataType descriptor.
|-
| Type || This is a read-only field and is used to indicate what basic type a DataType is. Types include IFF, Binary and ASCII.
|}

5. Once a DataType descriptor has been defined, it must be saved. Select the "Project/Save As..." menu item for the file requester used to save a DataType descriptor. The default name for a DataType descriptor is the text entered into File Type field.

6. In order for a new DataType descriptor to be loaded, the datatypes.library must be flushed from the system. This can either be done with the [[SDK_Developer_Tools#Expunge|Expunge]] command included in the SDK. Another way that the new DataType descriptor can be loaded is by using the AddDataTypes command with the REFRESH option.

== DataType Descriptor Function Interface ==

Sometimes the fields within the DTDesc utility are not enough to define a DataType descriptor. In this case it is necessary to use a Function to
further narrow down a DataType.

A Function is a stand-alone executable that expects the following arguments.

<syntaxhighlight lang="C" line>
BOOL retval = Function(struct DTHookContext *dthc);
</syntaxhighlight>

The function must return TRUE if the data matches, FALSE if it doesn't.

The DTHookContext structure contains the fields that are necessary for narrowing down the DataType. Following is a listing of the DTHookContext
structure.

<syntaxhighlight lang="C" line>
struct DTHookContext
{
struct Library *dthc_SysBase;
struct Library *dthc_DOSBase;
struct Library *dthc_IFFParseBase;
struct Library *dthc_UtilityBase;

/* File context */
BPTR dthc_Lock; /* Lock on the file */
struct FileInfoBlock *dthc_FIB; /* Pointer to a FileInfoBlock */
BPTR dthc_FileHandle; /* Pointer to the file handle (may be NULL) */
struct IFFHandle *dthc_IFF; /* Pointer to an IFFHandle (may be NULL) */
STRPTR dthc_Buffer; /* Buffer */
ULONG dthc_BufferLength; /* Length of the buffer */

ULONG dthc_Length; /* size of this structure */
struct ExecIFace * dthc_IExec;
struct DOSIFace * dthc_IDOS;
struct IFFParseIFace * dthc_IIFFParse;
struct UtilityIFace * dthc_IUtility;
};
</syntaxhighlight>

The DTHookContext structure fields are as follows:

; dthc_SysBase
; dthc_DOSBase
; dthc_IFFParseBase
; dthc_UtilityBase
: These are library bases that your function can utilize. It will need to open any other libraries that it needs.

; dthc_Lock
: If the source data is a DOS file, then this is a lock on the file.

; dthc_FIB
: If the source data is a DOS file, then this is a filled in FileInfoBlock for the file.

; dthc_FileHandle
: If the source data is a DOS file, then this is the file handle for the file otherwise the handle will be NULL. The file is guaranteed to be at the beginning.

; dthc_IFF
: If the source data is IFF, then this is the IFFHandle for accessing the data, otherwise the handle will be NULL. The position is guaranteed to be at the beginning of the data. The DOS file fields must not be accessed if the data is IFF.

; dthc_Buffer
: This buffer contains the first dthc_BufferLength bytes of data.

; dthc_BufferLength
: Indicates the number of bytes in dthc_Buffer, up to 64.

; dthc_Length
: Size in bytes of struct DTHookContext

; dthc_IExec
; dthc_IDOS
; dthc_IIFFParse
; dthc_IUtility
: These are interface pointers that your function can utilize.

The following example shows how to write a simple DataTypes Descriptor Function.

<syntaxhighlight lang="C" line>
/* This example must not be linked with any startup code so that
* DTHook is the entry point for the executable.
*
*/
#include <exec/types.h>
#include <dos/dos.h>
#include <dos/dosextens.h>
#include <datatypes/datatypes.h>

#include <proto/exec.h>
#include <proto/dos.h>
#include <proto/utility.h>

BOOL DTHook (struct DTHookContext * dthc)
{
BOOL retval = FALSE;
uint32 i;
uint8 ch;

/* Make sure we have a buffer */
if (dthc->dthc_Buffer)
{
for (i = 0; (i < dthc->dthc_BufferLength) && !retval; i++)
{
ch = dthc->dthc_Buffer[i];

/* Look at the data... */
}
}
return retval;
}
</syntaxhighlight>

The next example shows how to write a DataTypes Descriptor that looks into an IFF file for needed chunk information.

<syntaxhighlight lang="C" line>
/* This example must not be linked with any startup code
* so that DTHook is the entry point for the executable.
*/
#include <exec/types.h>
#include <dos/dos.h>
#include <dos/dosextens.h>
#include <datatypes/datatypes.h>
#include <datatypes/pictureclass.h>
#include <libraries/iffparse.h>

#include <proto/exec.h>
#include <proto/dos.h>
#include <proto/iffparse.h>
#include <proto/utility.h>

#define BMH_SIZE (sizeof (struct BitMapHeader))

BOOL DTHook(struct DTHookContext * dthc)
{
struct BitMapHeader bmh;
struct ContextNode *cn;
struct IFFHandle *iff;
BOOL retval = FALSE;

/* Make sure that this is an IFF data type */
if (iff = dthc->dthc_IFF)

/* Stop on the BitMapHeader (type, id) */
if (dthc->dthc_IIFFParse->StopChunk (iff, ID_ILBM, ID_BMHD) == 0)

/* Scan through the IFF handle */
if (dthc->dthc_IIFFParse->ParseIFF (iff, IFFPARSE_SCAN) == 0L)

/* Make sure we have a current chunk */
if (cn = dthc->dthc_IIFFParse->CurrentChunk (iff))

/* Make sure the current chunk is ILBM BMHD */
if ((cn->cn_Type == ID_ILBM) && (cn->cn_ID == ID_BMHD))

/* Read the chunk data */
if (dthc->dthc_IIFFParse->ReadChunkBytes (iff, &bmh, BMH_SIZE) == BMH_SIZE)

/* See if the depth is set to 24 */
if (bmh.bmh_Depth == 24)
retval = TRUE;

return (retval);
}
</syntaxhighlight>

Exec Messages and Ports

2025-01-26T19:40:03Z

Costel Mincea: Text replacement - "<syntaxhighlight>" to "<syntaxhighlight lang="C" line>"

== Exec Messages and Ports ==

For inter-process communication, Exec provides a consistent, high-performance mechanism of messages and ports. This mechanism is used to pass message structures of arbitrary sizes from task to task, interrupt to task, or task to software interrupt. In addition, messages are often used to coordinate operations between cooperating tasks. This section describes many of the details of using messages and ports that the casual Amiga programmer won't need. See [[Introduction_to_Exec|Introduction to Exec]] for a general introduction to using messages and ports.

A ''message'' data structure has two parts: system linkage and message body. The system linkage is used by Exec to attach a given message to its destination. The message body contains the actual data of interest. The message body is any arbitrary data up to 64K bytes in size. The message body data can include pointers to other data blocks of any size.

Messages are always sent to a predetermined destination ''port''. At a port, incoming messages are queued in a first-in-first-out (FIFO) order. There are no system restrictions on the number of ports or the number of messages that may be queued to a port (other than the amount of available system memory).

Messages are always queued by ''reference'', i.e., by a pointer to the message. For performance reasons message copying is not performed. In essence, a message between two tasks is a temporary license for the receiving task to use a portion of the memory space of the sending task; that portion being the message itself. This means that if task A sends a message to task B, the message is still part of the task A context. Task A, however, should not access the message until it has been ''replied''; that is, until task B has sent the message back, using the ReplyMsg() function. This technique of message exchange imposes important restrictions on message access.

== Message Ports ==

Message ports are rendezvous points at which messages are collected. A port may contain any number of outstanding messages from many different originators. When a message arrives at a port, the message is appended to the end of the list of messages for that port, and a pre-specified arrival action is invoked. This action may do nothing, or it may cause a predefined task signal or software interrupt (see [[Exec_Interrupts|Exec Interrupts]]).

Like many Exec structures, ports may be given a symbolic name. Such names are particularly useful for tasks that must rendezvous with dynamically created ports. They are also useful for debugging purposes.

A message port consists of a MsgPort structure as defined in the <exec/ports.h> and <exec/ports.i> include files. The C structure for a port is as follows:

<syntaxhighlight lang="C" line>
struct MsgPort {
struct Node mp_Node;
UBYTE mp_Flags;
UBYTE mp_SigBit;
struct Task *mp_SigTask;
struct List mp_MsgList;
};
</syntaxhighlight>

; mp_Node
: is a standard Node structure. This is useful for tasks that might want to rendezvous with a particular message port by name.

; mp_FLags
: are used to indicate message arrival actions. See the explanation below.

; mp_SigBit
: is the signal bit ''number'' when a port is used with the task signal arrival action.

; mp_SigTask
: is a pointer to the task to be signaled. If a software interrupt arrival action is specified, this is a pointer to the interrupt structure.

; mp_MsgList
: is the list header for all messages queued to this port. (See [[Exec_Lists_and_Queues|Exec Lists and Queues]]).

The mp_Flags field contains a subfield indicated by the PF_ACTION mask. This sub-field specifies the message arrival action that occurs when a port receives a new message.

The possibilities are as follows:

; PA_SIGNAL
: This flag tells Exec to signal the mp_SigTask using signal number mp_SigBit on the arrival of a new message. Every time a message is put to the port another signal will occur regardless of how many messages have been queued to the port.

; PA_SOFTINT
: This flag tells Exec to Cause() a software interrupt when a message arrives at the port. In this case, the mp_SigTask field must contain a pointer to a struct Interrupt rather than a Task pointer. The software interrupt will be Caused every time a message is received.

; PA_IGNORE
: This flag tells Exec to perform no operation other than queuing the message. This action is often used to stop signaling or software interrupts without disturbing the contents of the mp_SigTask field.

It is important to realize that a port's arrival action will occur for each new message queued, and that there is not a one-to-one correspondence between messages and signals. Task signals are only single-bit flags so there is no record of how many times a particular signal occurred. There may be many messages queued and only a single task signal; sometimes however there may be a signal, but no messages. All of this has certain implications when designing code that deals with these actions. Your code should not depend on receiving a signal for every message at your port. All of this is also true for software interrupts.

=== Creating a Message Port ===

To create a new message port use AllocSysObject() with an object type of ASOT_PORT. If you want to make the port ''public'', you will need to use the ASOPORT_Name tag. Don't make a port public when it is not necessary for it to be so.

Prior to V50 of the operating system, functions such as CreatePort() and CreateMsgPort() were often used. Some older applications may even have created their own static message ports by hand. Although all of the older methods still function for backwards compatibility, they should no longer be used.

Using dynamic message ports with ASOT_PORT is the only way to ensure your applications will remain compatible and its message ports automatically freed by the system when required.

=== Deleting a Message Port ===

Before a message port is deleted, all outstanding messages from other tasks must be returned. This is done by getting and replying to all messages at the port until message queue is empty. Of course, there is no need to reply to messages owned by the current task (the task performing the port deletion). Public ports must be removed from the system properly before deallocation. If a signal was allocated for the message port, it must also be freed. FreeSysObject() handles all of this automatically.

Prior to V50 of the operating system, message ports must be freed using the correct corresponding function such as DeletePort() or DeleteMsgPort(). The FreeSysObject() function must only be used on ports which were allocated with AllocSysObject().

=== How to Rendezvous at a Message Port ===

The FindPort() function provides a means of finding the address of a public port given its symbolic name. For example, FindPort("Griffin") will return either the address of the message port named "Griffin" or NULL indicating that no such public port exists. Since FindPort() does not do any arbitration over access to public ports, the usage of FindPort() must be protected with Forbid()/Permit(). Names should be unique to prevent collisions among multiple applications. It is a good idea to use your application name as a prefix for your port name. FindPort() does not arbitrate for access to the port list. The owner of a port might remove it at any time. For these reasons a Forbid()/Permit() pair is required for the use of FindPort(). The port address can no longer be regarded as being valid after Permit() unless your application knows that the port cannot go away (for example, if your application created the port).

The following is an example of how to safely put a message to a specific port:

<syntaxhighlight lang="C" line>
#include <exec/types.h>
#include <exec/ports.h>

BOOL SafePutToPort(struct Message *message, CONST_STRPTR portname)
{
IExec->Forbid();

struct MsgPort *port = IExec->FindPort(portname);
if (port != NULL)
IExec->PutMsg(port,message);

IExec->Permit();

return(port ? TRUE : FALSE); /* If FALSE, the port was not found */

/* Once we've done a Permit(), the port might go away and leave us with
an invalid port address. So we return just a BOOL to indicate whether
the message has been sent or not. */
}
</syntaxhighlight>

== Messages ==

As mentioned earlier, a message contains both system header information and the actual message content. The system header is of the Message form defined in <exec/ports.h>. This structure is as follows:

<syntaxhighlight lang="C" line>
struct Message {
struct Node mn_Node;
struct MsgPort *mn_ReplyPort;
UWORD mn_Length;
};
</syntaxhighlight>

; mn_Node
: is a standard Node structure used for port linkage.

; mn_ReplyPort
: is used to indicate a port to which this message will be returned when a reply is necessary.

; mn_Length
: indicates the total length of the message, including the Message structure itself.

This structure is always attached to the head of all messages. For example, if you want a message structure that contains the ''x'' and ''y'' coordinates of a point on the screen, you could define it as follows:

<syntaxhighlight lang="C" line>
struct XYMessage {
struct Message xy_Msg;
UWORD xy_X;
UWORD xy_Y;
}
</syntaxhighlight>

For this structure, the mn_Length field should be set to sizeof(struct XYMessage).

=== Creating a Message ===

Messages are allocated using AllocSysObject() with an object type of ASOT_MESSAGE. The ASOMSG_ReplyPort tag is set to the reply port if desired. Some messages may be sent in one direction in which case the ASOMSG_ReplyPort tag is not used. The size of the message is indicated with ASOMSG_Length and includes the size of the payload.

<syntaxhighlight lang="C" line>
struct XYMessage xymsg = IExec->AllocSysObjectTags(ASOT_MESSAGE,
ASOMSG_Size, sizeof(struct XYMessage),
ASOMSG_ReplyPort, replyPort,
TAG_END);
</syntaxhighlight>

=== Deleting a Message ===

Messages are freed using FreeSysObject(). Programmers should be careful not to free a message which is still in use or queues in a message port.

=== Putting a Message ===

A message is delivered to a given destination port with the PutMsg() function. The message is queued to the port, and that port's arrival action is invoked. If the action specifies a task signal or a software interrupt, the originating task may temporarily lose the processor while the destination processes the message. If a reply to the message is required, the mn_ReplyPort field must be set up prior to the call to PutMsg().

Here is a code fragment for putting a message to a public port. A complete example is at the end of the article.

<syntaxhighlight lang="C" line>
#include <exec/types.h>
#include <exec/memory.h>
#include <exec/ports.h>
#include <libraries/dos.h>

BOOL SafePutToPort(struct Message *, CONST_STRPTR);

struct XYMessage {
struct Message xy_Msg;
uint16 xy_X;
uint16 xy_Y;
};

int main()
{
struct MsgPort *xyport, *xyreplyport;
struct XYMessage *msg;
BOOL foundport;

/* Allocate the message we're going to send. */
struct XYMessage *xymsg = IExec->AllocSysObjectTags(ASOT_MESSAGE,
ASOMSG_Size, sizeof(struct XYMessage),
TAG_END);

if (xymsg != NULL)
{
/* The replyport we'll use to get response */
if (xyreplyport = IExec->AllocSysObject(ASOT_PORT, NULL)) {

xymsg->xy_Msg.mn_ReplyPort = xyreplyport;
xymsg->xy_X = 10;
xymsg->xy_Y = 20;

/* Now try to send that message to a public port named "xyport".
* If foundport eq 0, the port isn't out there.
*/
if (foundport = SafePutToPort((struct Message *)xymsg, "xyport"))
{

. . . /* Now let's wait till the someone responds... */

}
else IDOS->Printf("Couldn't find 'xyport'\n");

IExec->FreeSysObject(ASOT_PORT, xyreplyport);
else IDOS->Printf("Couldn't create message port\n");

IExec->FreeSysObject(ASOT_MESSAGE, xymsg);
}
else IDOS->Printf("Couldn't get memory for xymessage\n");

return 0;
}
</syntaxhighlight>

=== Waiting for a Message ===

A task may go to sleep waiting for a message to arrive at one or more ports. This technique is widely used on the Amiga as a general form of event notification. For example, it is used extensively by tasks for I/O request completion.

The MsgPort.mp_SigTask field contains the address of the task to be signaled and mp_SigBit contains a preallocated signal number (as described in [[Exec_Tasks|Exec Tasks]]).

You can call the WaitPort() function to wait for a message to arrive at a port. This function will return the first message (it may not be the only) queued to a port. Note that your application must still call GetMsg() to remove the message from the port. If the port is empty, your task will go to sleep waiting for the first message. If the port is not empty, your task will not go to sleep. It is possible to receive a signal for a port without a message being present yet. The code processing the messages should be able to handle this. The following code illustrates WaitPort().

<syntaxhighlight lang="C" line>
struct MsgPort *xyport = IExec->AllocSysObjectTags(ASOT_PORT,
ASOPORT_Name, "xyport",
TAG_END);

if (xyport == NULL)
{
IDOS->Printf("Couldn't create xyport\n");
return RETURN_FAIL;
}

struct XYMessage *xy_msg = IExec->WaitPort(xyport); /* go to sleep until message arrives */
</syntaxhighlight>

A more general form of waiting for a message involves the use of the Wait() function (see [[Exec_Signals|Exec Signals]]). This function waits for task event signals directly. If the signal assigned to the message port occurs, the task will awaken. Using the Wait() function is more general because you can wait for more than one signal. By combining the signal bits from each port into one mask for the Wait() function, a loop can be set up to process all messages at all ports.

Here's an example using Wait():

<syntaxhighlight lang="C" line>
struct XYMessage *xy_msg;
BOOL ABORT = FALSE;

struct MsgPort *xyport = IExec->AllocSysObjectTags(ASOT_PORT,
ASOPORT_Name, "xyport",
TAG_END);

if (xyport != NULL)
{
uint32 portsig = 1 << xyport->mp_SigBit;
uint32 usersig = SIGBREAKF_CTRL_C; /* User can break with CTRL-C. */
for (;;)
{
uint32 signal = IExec->Wait(portsig | usersig); /* Sleep till someone signals. */

if (signal & portsig) /* Got a signal at the msgport. */
{ . . .
}
if (signal & usersig) /* Got a signal from the user. */
{
ABORT = TRUE; /* Time to clean up. */
. . .
}
if (ABORT) break;
}
IExec->FreeSysObject(ASOT_PORT, xyport);
}
else IDOS->Printf("Couldn't create xyport\n");
</syntaxhighlight>

{{Note|text=WaitPort() only returns a pointer to the first message in a port. It does not actually remove the message from the port queue.|title=WaitPort() Does Not Remove A Message}}

=== Getting a Message ===

Messages are usually removed from ports with the GetMsg() function. This function removes the next message at the head of the port queue and returns a pointer to it. If there are no messages in a port, this function returns a zero.

The example below illustrates the use of GetMsg() to print the contents of all messages in a port:

<syntaxhighlight lang="C" line>
while (xymsg = IExec->GetMsg(xyport))
IDOS->Printf("x=%ld y=%ld\n", xymsg->xy_X, xymsg->xy_Y);
</syntaxhighlight>

Certain messages may be more important than others. Because ports impose FIFO ordering, these important messages may get queued behind other messages regardless of their priority. If it is necessary to recognize more important messages, it is easiest to create another port for these special messages.

=== Replying ===

When the operations associated with receiving a new message are finished, it is usually necessary to send the message back to the originator. The receiver replies the message by returning it to the originator using the ReplyMsg() function. This is important because it notifies the originator that the message can be reused or deallocated.

The ReplyMsg() function serves this purpose. It returns the message to the port specified in the mn_ReplyPort field of the message. If this field is zero, no reply is returned.

The previous example can be enhanced to reply to each of its messages:

<syntaxhighlight lang="C" line>
while (xymsg = IExec->GetMsg(xyport)) {
IDOS->Printf("x=%ld y=%ld\n", xymsg->xy_X, xymsg->xy_Y);
IExec->ReplyMsg(xymsg);
}
</syntaxhighlight>

Notice that the reply does not occur until ''after'' the message values have been used.

Often the operations associated with receiving a message involve returning ''results'' to the originator. Typically this is done within the message itself. The receiver places the results in fields defined (or perhaps reused) within the message body before replying the message back to the originator. Receipt of the replied message at the originator reply port indicates it is once again safe for the originator to use or change the values found within the message.

The following are two short example tasks that communicate by sending, waiting for and replying to messages. Run these two programs together.

==== Port1.c ====

<syntaxhighlight lang="C" line>
// port1.c - port and message example, run at the same time as port2.c

#include <exec/types.h>
#include <exec/ports.h>
#include <dos/dos.h>
#include <proto/exec.h>
#include <proto/dos.h>

struct XYMessage {
struct Message xym_Msg;
int16 xy_X;
int16 xy_Y;
};

int main()
{
BOOL ABORT = FALSE;

struct MsgPort *xyport = IExec->AllocSysObjectTags(ASOT_PORT,
ASOPORT_Name, "xyport",
TAG_END);

if (xyport != NULL)
{
uint32 portsig = 1U << xyport->mp_SigBit; /* Give user a `break' signal. */
uint32 usersig = SIGBREAKF_CTRL_C;

IDOS->Printf("Start port2 in another shell. CTRL-C here when done.\n");
do
{ /* port1 will wait forever and reply */
uint32 signal = IExec->Wait(portsig | usersig); /* to messages, until the user breaks. */
struct XYMessage *xymsg = 0;

/* Since we only have one port that might get messages we */
if (signal & portsig) /* have to reply to, it is not really necessary to test for */
{ /* the portsignal. If there is not message at the port, xymsg */

while(xymsg = (struct XYMessage *)IExec->GetMsg(xyport)) /* simply will be NULL. */
{
IDOS->Printf("port1 received: x = %d y = %d\n", xymsg->xy_X, xymsg->xy_Y);

xymsg->xy_X += 50; /* Since we have not replied yet to the owner of */
xymsg->xy_Y += 50; /* xymsg, we can change the data contents of xymsg. */

IDOS->Printf("port1 replying with: x = %d y = %d\n", xymsg->xy_X, xymsg->xy_Y);
IExec->ReplyMsg((struct Message *)xymsg);
}
}

if (signal & usersig) /* The user wants to abort. */
{
while(xymsg = (struct XYMessage *)IExec->GetMsg(xyport)) /* Make sure port is empty. */
IExec->ReplyMsg((struct Message *)xymsg);
ABORT = TRUE;
}
}
while (ABORT == FALSE);
IExec->FreeSysObject(ASOT_PORT, xyport);
}
else IDOS->Printf("Couldn't create 'xyport'\n");
return 0;
}
</syntaxhighlight>

==== Port2.c ====

<syntaxhighlight lang="C" line>
// port2.c - port and message example, run at the same time as port1.c

#include <exec/types.h>
#include <exec/ports.h>
#include <exec/memory.h>
#include <dos/dos.h>
#include <proto/exec.h>
#include <proto/dos.h>

BOOL SafePutToPort(struct Message *, CONST_STRPTR);

struct XYMessage {
struct Message xy_Msg;
int16 xy_X;
int16 xy_Y;
};

int main()
{
struct MsgPort *xyreplyport = IExec->AllocSysObjectTags(ASOT_PORT, TAG_END);

if (xyreplyport != NULL)
{
struct XYMessage *reply = NULL;

struct XYMessage *xymsg = IExec->AllocSysObjectTags(ASOT_MESSAGE,
ASOMSG_Size, sizeof(struct XYMessage),
ASOMSG_ReplyPort, xyreplyport,
TAG_END);

if (xymsg != NULL)
{
xymsg->xy_X = 10; /* our special message information. */
xymsg->xy_Y = 20;

IDOS->Printf("Sending to port1: x = %d y = %d\n", xymsg->xy_X, xymsg->xy_Y);

/* port2 will simply try to put */
if (SafePutToPort((struct Message *)xymsg, "xyport")) /* one message to port1 wait for */
{ /* the reply, and then exit */
IExec->WaitPort(xyreplyport);
if (reply = (struct XYMessage *)IExec->GetMsg(xyreplyport))
IDOS->Printf("Reply contains: x = %d y = %d\n", /* We don't ReplyMsg since */
xymsg->xy_X, xymsg->xy_Y); /* WE initiated the message. */

/* Since we only use this private port for receiving replies, and we sent */
/* only one and got one reply there is no need to cleanup. For a public port, */
/* or if you pass a pointer to the port to another process, it is a very good */
/* habit to always handle all messages at the port before you delete it. */
}
else IDOS->Printf("Can't find 'xyport'; start port1 in a separate shell\n");
IExec->FreeSysObject(ASOT_MESSAGE, xymsg);
}
else IDOS->Printf("Couldn't get memory\n");
IExec->FreeSysObject(ASOT_PORT, xyreplyport);
}
else IDOS->Printf("Couldn't create xyreplyport\n");
return 0;
}

BOOL SafePutToPort(struct Message *message, CONST_STRPTR portname)
{
IExec->Forbid();
struct MsgPort *port = IExec->FindPort(portname);
if (port != NULL) IExec->PutMsg(port, message);
IExec->Permit();
return(port ? TRUE : FALSE); /* FALSE if the port was not found */

/* Once we've done a Permit(), the port might go away and leave us with an invalid port */
} /* address. So we return just a BOOL to indicate whether the message has been sent or not. */
</syntaxhighlight>

== Function Reference ==

The following chart gives a brief description of the Exec functions that control inter-task communication with messages and ports. See the SDK for details about each call.

{| class="wikitable"
! Function
! Description
|-
| AddPort()
| Add a public message port to the system list.
|-
| AllocSysObject(ASOT_PORT)
| Allocate and initialize a new message port.
|-
| FindPort()
| Find a public message port in the system list.
|-
| FreeSysObject(ASOT_PORT)
| Free a message port.
|-
| GetMsg()
| Get next message from the message port.
|-
| PutMsg()
| Put a message to a message port.
|-
| RemPort()
| Remove a message port from the system list.
|-
| ReplyMsg()
| Reply to a message on its reply port.
|}

Audio Device

2025-01-26T19:37:57Z

Costel Mincea: Text replacement - "<syntaxhighlight>" to "<syntaxhighlight lang="C" line>"

[[Category:Devices|Audio]]{{CodeReview}}
== Audio Device ==

The Amiga has four hardware audio channels—two of the channels produce audio output from the left audio connector, and two from the right. These channels can be used in many ways. You can combine a right and a left channel for stereo sound, use a single channel, or play a different sound through each of the channels to create four-part harmony.

== About Amiga Audio ==

Most personal computers that produce sound have hardware designed for one ''specific'' synthesis technique. The Amiga computer uses a very general method of digital sound synthesis that is quite similar to the method used in digital hi-fi components and state-of-the-art keyboard and drum synthesizers.

For programs that can afford the memory, playing sampled sounds gives you a simple and very CPU-efficient method of sound synthesis. A sampled sound is a table of numbers which represents a sound digitally. When the sound is played back by the Amiga, the table is fed by a DMA channel into one of the four digital-to-analog converters in the custom chips. The digital-to-analog converter converts the samples into voltages that can be played through amplifiers and loudspeakers, reproducing the sound.

On the Amiga you can create sound data in many other ways. For instance, you can use trigonometric functions in your programs to create the more traditional sounds—sine waves, square waves, or triangle waves—by using tables that describe their shapes. Then you can combine these waves for richer sound effects by adding the tables together. Once the data are entered, you can modify them with techniques described below. For information about the limitations of the audio hardware and suggestions for improving system efficiency and sound quality, refer to the ''Amiga Hardware Reference Manual''.

Some commands enable your program to co-reside with other programs using the audio device at the same time. Programs can co-reside because the audio device handles allocation of audio channels and arbitrates among programs competing for the same resources. When properly used, this allows many programs to use the audio device simultaneously.

The audio device commands help isolate the programmer from the idiosyncrasies of the custom chip hardware and make it easier to use. But you can also produce sound on the Amiga by directly accessing the hardware registers if you temporarily lock out other users first. For certain types of sound synthesis, this is more CPU-efficient.

=== Definitions ===

Terms used in the following discussions may be unfamiliar. Some of the more important ones are defined below.
;Amplitude
:The height of a waveform, which corresponds to the amount of voltage or current in the electronic circuit.
;Amplitude modulation
:A means of producing special audio effects by using one channel to alter the amplitude of another.
;Channel
:One “unit” of the audio device.
;Cycle
:One repetition of a waveform.
;Frequency
:The number of times per second a cycle repeats.
;Frequency modulation
:A means of producing special audio effects by using one channel to affect the period of the waveform produced by another channel.
;Period
:The time elapsed between the output of successive sound samples, in units of system clock ticks.
;Precedence
:Priority of the user of a sound channel.
;Sample
:Unit of audio data, one of the fixed-interval points on the waveform.
;Waveform
:Graph that shows a model of how the amplitude of a sound varies over time—usually over one cycle.

== Audio Device Commands and Functions ==

{| class="wikitable"
!Command!!Command Operation
|-
|'''ADCMD_ALLOCATE'''||Allocate one or more of the four audio channels.
|-
|'''ADCMD_FINISH'''||Abort the current write request on one or more of the channels. Can be done immediately or at the end of the current cycle.
|-
|'''ADCMD_FREE'''||Free one or more audio channels.
|-
|'''ADCMD_LOCK'''||Lock one or more audio channels.
|-
|'''ADCMD_PERVOL'''||Change the period and volume for writes in progress. Can be done immediately or at the end of the cycle.
|-
|'''ADCMD_SETPREC'''||Set the allocation precedence of one or more channels.
|-
|'''ADCMD_WAITCYCLE'''||Wait for the current write cycle to complete on a single channel. Returns at the end of the cycle or immediately if no cycle is active on the channel.
|-
|'''CMD_FLUSH'''||Purge all write cycles and waitcycles (in-progress and queued) for one or more channels.
|-
|'''CMD_READ'''||Return a pointer to the I/O block currently writing on a single channel.
|-
|'''CMD_RESET'''||Reset one or more channels their initialized state. All active and queued requests will be aborted.
|-
|'''CMD_START'''||Resume writes to one or more channels that were stopped.
|-
|'''CMD_STOP'''||Stop any write cycle in progress on one or more channels.
|-
|'''CMD_WRITE'''||Start a write cycle on a single channel.
|}

== Device Interface ==

The audio device operates like the other Amiga I/O devices. To make sound, you first open the audio device, then send I/O requests to it, and then close it when finished. See [[Exec_Device_I/O|Exec Device I/O]] for general information on device usage.

Audio device commands use an extended I/O request block named IOAudio to send commands to the audio device. This is the standard IORequest block with some extra fields added at the end.

<syntaxhighlight lang="C" line>
struct IOAudio
{
struct IORequest ioa_Request; /* I/O request block. See exec/io.h. */
WORD ioa_AllocKey; /* Alloc. key filled in by audio device */
UBYTE *ioa_Data; /* Pointer to a sample or allocation mask */
ULONG ioa_Length; /* Length of sample or allocation mask. */
UWORD ioa_Period; /* Sample playback speed */
UWORD ioa_Volume; /* Volume of sound */
UWORD ioa_Cycles; /* # of times to play sample. 0=forever. */
struct Message ioa_WriteMsg; /* Filled in by device - usually not used */
};
</syntaxhighlight>

See the include file devices/audio.h for the complete structure definition.

=== Opening the Audio Device ===

Before you can use the audio device, you must first open it with a call to OpenDevice(). Four primary steps are required to open the audio device:

* Create a message port using CreatePort. Reply messages from the device must be directed to a message port.
* Allocate memory for an extended I/O request structure of type IOAudio using AllocMem().
* Fill in io_Message.mn_ReplyPort with the message port created by CreatePort().
* Open the audio device. Call OpenDevice(), passing IOAudio.

<pre>
struct MsgPort *AudioMP; /* Define storage for port pointer */
struct IOAudio *AudioIO; /* Define storage for IORequest pointer */

if (AudioMP = CreatePort(0,0) )
{
AudioIO = (struct IOAudio *)
AllocMem(sizeof(struct IOAudio), MEMF_PUBLIC | MEMF_CLEAR);
if (AudioIO)
{
AudioIO->ioa_Request.io_Message.mn_ReplyPort = AudioMP;
AudioIO->ioa_AllocKey = 0;
}

if (OpenDevice(AUDIONAME,0L,(struct IORequest *)AudioIO,0L) )
printf("%s did not open\n",AUDIONAME);
</pre>

A special feature of the OpenDevice() function with the audio device allows you to automatically allocate channels for your program to use when the device is opened. This is convenient since you ''must'' allocate one or more channels before you can produce sound.

This is done by setting the value of ioa_AllocKey to zero, setting the value of ioa_Request.io_Message.mn_Node.ln_Pri to the appropriate precedence, setting io_Data to the address of a channel combination array, and setting ioa_Request.ioa_Length to a non-zero value (the length of the channel combination array). The audio device will attempt to allocate channels just as if you had sent the ADCMD_ALLOCATE command (see below). If the allocation fails, the OpenDevice() call will return immediately.

If you want to allocate channels at some later time, set the value of the ioa_Request.ioa_Length field of the IOAudio block to zero when you call OpenDevice(). For more on channel allocation and the ADCMD_ALLOCATE command, see the section on “Allocation and Arbitration” below.

<pre>
UBYTE chans[] = {1,2,4,8}; /* get any of the four channels */

if (AudioIO)
{
AudioIO->ioa_Request.io_Message.mn_ReplyPort = AudioMP;
AudioIO->ioa_AllocKey = 0;
AudioIO->ioa_Request.io_Message.mn_Node.ln_Pri= 120;
AudioIO->ioa_Data = chans;
AudioIO->ioa_Length = sizeof(chans);
}

if (OpenDevice(AUDIONAME,0L,(struct IORequest *)AudioIO,0L) )
printf("%s did not open\n", AUDIONAME);
</pre>

=== Audio Device Command Types ===

Commands for audio use can be divided into two categories: allocation/arbitration commands and hardware control commands.

There are four allocation/arbitration commands. These do not actually produce any sound. Instead they manage and arbitrate the audio resources for the many tasks that may be using audio in the Amiga’s multitasking environment.

{|
|-
|ADCMD_ALLOCATE||Reserves an audio channel for your program to use.
|-
|ADCMD_FREE||Frees an audio channel.
|-
|ADCMD_SETPREC||Changes the precedence of a sound in progress.
|-
|ADCMD_LOCK||Tells if a channel has been stolen from you.
|}

The hardware control commands are used to set up, start, and stop sounds on the audio device:

{|
|-
|CMD_WRITE||The main command. Starts a sound playing.
|-
|ADCMD_FINISH||Aborts a sound in progress.
|-
|ADCMD_PERVOL||Changes the period (speed) and volume of a sound in progress.
|-
|CMD_FLUSH||Clears the audio channels.
|-
|CMD_RESET||Resets and initializes the audio device.
|-
|ADCMD_WAITCYCLE||Signals you when a cycle finishes.
|-
|CMD_STOP||Temporarily stops a channel from playing.
|-
|CMD_START||Restarts an audio channel that was stopped.
|-
|CMD_READ||Returns a pointer to the current IOAudio request.
|}

=== Scope of Audio Commands ===

Most audio commands can operate on multiple channels. The exceptions are ADCMD_WAITCYCLE, CMD_WRITE and CMD_READ, which can only operate on one channel at a time. You specify the channel(s) that you want to use by setting the appropriate bits in the ioa_Request.io_Unit field of the IOAudio block. If you send a command for a channel that you do not own, your command will be ignored. For more details, see the section on “Allocation and Arbitration” below.

=== Audio and System I/O Functions ===

==== BeginIO() ====

All the commands that you can give to the audio device should be sent by calling the BeginIO() function. This differs from other Amiga devices which generally use SendIO() or DoIO(). You should not use SendIO() or DoIO() with the audio device because these functions clear some special flags used by the audio device; this might cause audio to work incorrectly under certain circumstances. To be safe, you should always use BeginIO() with the audio device.

==== Wait() and WaitPort() ====

These functions can be used to put your task to sleep while a sound plays. Wait() takes a wake-up mask as its argument. The wake-up mask is usually the mp_SigBit of a MsgPort that you have set up to get replies back from the audio device.

'''WaitPort()''' will put your task to sleep while a sound plays. The argument to WaitPort() is a pointer to a MsgPort that you have set up to get replies back from the audio device.

'''Wait()''' and WaitPort() will not remove the message from the reply port. You must use GetMsg() to remove it.

You must always use Wait() or WaitPort() to wait for I/O to finish with the audio device.

==== AbortIO() ====

This function can be used to cancel requests for ADCMD_ALLOCATE, ADCMD_LOCK, CMD_WRITE, or ADCMD_WAITCYCLE. When used with the audio device, AbortIO() always succeeds.

=== Closing the Audio Device ===

An OpenDevice() must eventually be matched by a call to CloseDevice().

All I/O requests must be complete before CloseDevice(). If any requests are still pending, abort them with AbortIO():

<pre>AbortIO((struct IORequest *)AudioIO); /* Abort any pending requests */
WaitPort(AudioMP); /* Wait for abort message */
GetMsg(AudioMP); /* Get abort message */
CloseDevice((struct IORequest *)AudioIO);</pre>
'''CloseDevice()''' performs an ADCMD_FREE command on any channels selected by the ioa_Request.io_Unit field of the IOAudio request. This means that if you close the device with the same IOAudio block that you used to allocate your channels (or a copy of it), the channels will be automatically freed.

If you allocated channels with multiple allocation commands, you cannot use this function to close all of them at once. Instead, you will have to issue one ADCMD_FREE command for each allocation that you made. After issuing the ADCMD_FREE commands for each of the allocations, you can call CloseDevice().

== A Simple Audio Example ==

The Amiga’s audio software has a complex allocation and arbitration system which is described in detail in the sections below. At this point, though, it may be helpful to look at a simple audio example:

== Audio Allocation and Arbitration ==

The first command you send to the audio device should always be ADCMD_ALLOCATE. You can do this when you open the device, or at a later time. You specify the channels you want in the '''ioa_Data''' field of the '''IOAudio''' block. If the allocation succeeds, the audio device will return the channels that you now own in the lower four bits of the '''ioa_Request.io_Unit''' field of your '''IOAudio''' block. For instance, if the '''io_Unit''' field equals 5 (binary 0101) then you own channels 2 and 0. If the '''io_Unit''' field equals 15 (binary 1111) then you own all the channels.

When you send the ADCMD_ALLOCATE command, the audio device will also return a unique allocation key in the '''ioa_AllocKey''' of the '''IOAudio''' block. You must use this allocation key for all subsequent commands that you send to the audio device. The audio device uses this unique key to identify which task issued the command. If you do not use the correct allocation key assigned to you by the audio device when you send a command, your command will be ignored.

When you request a channel with ADCMD_ALLOCATE, you specify a precedence number from -128 to 127 in the '''ioa_Request.io_Message.mn_Node.ln_Pri''' field of the '''IOAudio''' block. If a channel you want is being used and you have specified a higher precedence than the current user, ADCMD_ALLOCATE will “steal” the channel from the other user. Later on, if your precedence is lower than that of another user who is performing an allocation, the channel may be stolen from you.

If you set the precedence to 127 when you open the device or raise the precedence to 127 with the ADCMD_SETPREC command, no other tasks can steal a channel from you. When you have finished with a channel, you must relinquish it with the ADCMD_FREE command to make it available for other users.

The following table shows suggested precedence values.

{| class="wikitable"
|+Suggested Precedences for Channel Allocation
!Predecence!!Type of Sound
|-
|127||''Unstoppable''. Sounds first allocated at lower precedence, then set to this highest level.
|-
|90 – 100||''Emergencies''. Alert, urgent situation that requires immediate action.
|-
|80 – 90||''Annunciators''. Attention, bell (Ctrl-G).
|-
|75||''Speech''. Synthesized or recorded speech (narrator.device).
|-
|50 – 70||''Sonic cues''. Sounds that provide information that is not provided by graphics. Only the beginning of each sound (enough to recognize it) should be at this level; the rest should be set to sound effects level.
|-
| -50 – 50||''Music program''. Musical notes in music-oriented program. The higher levels should be used for the attack portions of each note.
|-
| -70 – -50||''Sound effects''. Sounds used in conjunction with graphics. More important sounds should use higher levels.
|-
| -100 – -80||''Background''. Theme music and restartable background sounds.
|-
| -128||''Silence''. Lowest level (freeing the channel completely is preferred)
|}

If you attempt to perform a command on a channel that has been stolen from you by a higher priority task, an AUDIO_NOALLOCATION error is returned and the bit in the ioa_Request.io_Unit field corresponding to the stolen channel is cleared so you know which channel was stolen.

If you want to be warned before a channel is stolen so that you have a chance to stop your sound gracefully, then you should use the ADCMD_LOCK command after you open the device. This command is also useful for programs which write directly to the audio hardware. For more on ADCMD_LOCK, see the section below.

== Allocation and Arbitration Commands ==

These commands allow the audio channels to be shared among different tasks and programs. None of these commands can be called from interrupt code.

=== ADCMD_ALLOCATE ===

This command gives your program a channel to use and should be the first command you send to the audio device. You specify the channels you want by setting a pointer to an array in the '''ioa_Data''' field of the '''IOAudio''' structure. This array uses a value of 1 to allocate channel 0, 2 for channel 1, 4 for channel 2, and 8 for channel 3. For multiple channels, add the values together. For example, if you want to allocate all channels, use a value of 15.

If you want a pair of stereo channels and you have no preference about which of the left and right channels the system will choose for the allocation, you can pass a pointer to an array containing 3, 5, 10, and 12. Channels 1 and 2 produce sound on the left side and channels 0 and 3 on the right side. The table below shows how this array corresponds to all the possible combinations of a right and a left channel.

{| class="wikitable"
|+Possible Channel Combinations
!Channel 3
right
!Channel 2
left
!Channel 1
left
!Channel 0
right
!Decimal Value
of
Allocation Mask
|-
|0||0||1||1||3
|-
|0||1||0||1||5
|-
|1||0||1||0||10
|-
|1||1||0||0||12
|}

==== How ADCMD_ALLOCATE Operates ====

The ADCMD_ALLOCATE command tries the first combination, 3, to see if channels 0 and 1 are not being used. If they are available, the 3 is copied into the '''io_Unit''' field and you get an allocation key for these channels in the '''ioa_AllocKey''' field. You copy the key into other I/O blocks for any other commands you may want to perform on these channels.

If channels 0 and 1 are being used, ADCMD_ALLOCATE tries the other combinations in turn. If all the combinations are in use, ADCMD_ALLOCATE checks the precedence number of the users of the channels and finds the combination that requires it to steal the channel or channels of the lowest precedence. If all the combinations require stealing a channel or channels of equal or higher precedence, the ADCMD_ALLOCATE request fails. Precedence is in the '''ln_Pri''' field of the '''io_Message''' in the '''IOAudio''' block you pass to ADCMD_ALLOCATE; it has a value from -128 to 127.

==== The ADIOF_NOWAIT Flag ====

If you need to produce a sound right now and otherwise don’t want to allocate, set the ADIOF_NOWAIT flag to 1. This will cause the command to return an IOERR_ALLOCFAILED error if it cannot allocate any of the channels. If you are producing a non-urgent sound and you can wait, set the ADIOF_NOWAIT flag to 0. Then, the '''IOAudio''' block returns only when you get the allocation. If ADIOF_NOWAIT is set to 0, the audio device will continue to retry the allocation request whenever channels are freed until it is successful. If the program decides to cancel the request, '''AbortIO'''() can be used.

==== ADCMD_ALLOCATE Examples ====

The following are more examples of how to tell ADCMD_ALLOCATE your channel preferences. If you want any channel, but want a right channel first, use an array containing 1, 8, 2, and 4:

{|
|0001
|-
|1000
|-
|0010
|-
|0100
|}

If you only want a right channel, use 1 and 8 (channels 0 and 3):

{|
|0001
|-
|1000
|}
If you want only a left channel, use 2 and 4 (channels 1 and 2):

{|
|0010
|-
|0100
|}

If you want to allocate a channel and keep it for a sound that can be interrupted and restarted, allocate it at a certain precedence. If it is stolen, allocate it again with the ADIOF_NOWAIT flag set to 0. When the channel is relinquished, you will get it again.

==== The Allocation Key ====

If you want to perform multi-channel commands, all the channels must have the same key since the '''IOAudio''' block has only one allocation key field. The channels must all have that same key even when they were not allocated simultaneously. If you want to use a key you already have, you can pass that key in the '''ioa_AllocKey''' field and ADCMD_ALLOCATE can allocate other channels with that existing key. The ADCMD_ALLOCATE command returns a new and unique key only if you pass it a zero in the allocation key field.

=== ADCMD_FREE ===

ADCMD_FREE is the opposite of ADCMD_ALLOCATE. When you perform ADCMD_FREE on a channel, it does a CMD_RESET command on the hardware and “unlocks” the channel. It also checks to see if there are other pending allocation requests. You do not need to perform ADCMD_FREE on channels stolen from you. If you want channels back after they have been stolen, you must reallocate them with the same allocation key.

=== ADCMD_SETPREC ===

This command changes the precedence of an allocated channel. As an example of the use of ADCMD_SETPREC, assume that you are making the sound of a chime that takes a long time to decay. It is important that user hears the chime but not so important that he hears it decay all the way. You could lower precedence after the initial attack portion of the sound to let another program steal the channel. You can also set the precedence to maximum (127) if you do not want the channel(s) stolen from you.

=== ADCMD_LOCK ===

The ADCMD_LOCK command performs the “steal verify” function. When another application is attempting to steal a channel or channels, ADCMD_LOCK gives you a chance to clean up before the channel is stolen. You perform a ADCMD_LOCK command right after the ADCMD_ALLOCATE command. ADCMD_LOCK does not return until a higher-priority user attempts to steal the channel(s) or you perform an ADCMD_FREE command. If someone is attempting to steal, you must finish up and ADCMD_FREE the channel as quickly as possible.

You must use ADCMD_LOCK if you want to write directly to the hardware registers instead of using the device commands. If your channel is stolen, you are not notified unless the ADCMD_LOCK command is present. This could cause problems for the task that has stolen the channel and is now using it at the same time as your task. ADCMD_LOCK sets a switch that is not cleared until you perform an ADCMD_FREE command on the channel. Canceling an ADCMD_LOCK request with '''AbortIO()''' will not free the channel.

The following outline describes how ADCMD_LOCK works when a channel is stolen and when it is not stolen.

# ''User A'' allocates a channel.
# ''User A'' locks the channel.
#:If ''User B'' allocates the channel with a higher precedence:
## ''User B''’s ADCMD_ALLOCATE command is suspended (regardless of the setting of the ADIOF_NOWAIT flag).
## ''User A''’s lock command is replied to with an error (this will be ADIOERR_CHANNELSTOLEN).
## ''User A'' does whatever is needed to finish up when a channel is stolen.
## ''User A'' frees the channel with ADCMD_FREE.
## ''User B''’s ADCMD_ALLOCATE command is replied to. Now user B has the channel.
#:If the channel is not allocated by another user:
## ''User A'' finishes the sound.
## ''User A'' performs the ADCMD_FREE command.
## ''User A''’s ADCMD_LOCK command is replied to.

Never make the freeing of a channel (if the channel is stolen) dependent on allocating another channel. This may cause a deadlock. If you want channels back after they have been stolen, you must reallocate them with the same allocation key. To keep a channel and never let it be stolen, set precedence to maximum (127). Do not use a lock for this purpose.

== Hardware Control Commands ==

The following commands change hardware registers and affect the actual sound output.

=== CMD_WRITE ===

This is a single-channel command and is the main command for making sounds. You pass the following to CMD_WRITE:

* A pointer to the waveform to be played (must start on a word boundary and must be in memory accessible by the custom chips, MEMF_CHIP)
* The length of the waveform in bytes (must be an even number)
* A count of how many times you want to play the waveform

If the count is 0, CMD_WRITE will play the waveform from beginning to end, then repeat the waveform continuously until something aborts it.

If you want period and volume to be set at the start of the sound, set the WRITE command’s ADIOF_PERVOL flag. If you do not do this, the previous volume and period for that channel will be used. This is one of the flags that is cleared by '''DoIO()''' and '''SendIO()'''. The '''ioa_WriteMsg''' field in the '''IOAudio''' block is an extra message field that can be replied to at the start of the CMD_WRITE. This second message is used only to tell you when the CMD_WRITE command ''starts'' processing, and it is used only when the ADIOF_WRITEMESSAGE flag is set to 1.

If a CMD_STOP has been performed, the CMD_WRITE requests are queued up. The CMD_WRITE command does not make its own copy of the waveform, so any modification of the waveform before the CMD_WRITE command is finished may affect the sound. This is sometimes desirable for special effects. To splice together two waveforms without clicks or pops, you must send a separate, second CMD_WRITE command while the first is still in progress. This technique is used in double-buffering, which is described below.

By using two waveform buffers and two CMD_WRITE requests you can compute a waveform continuously. This is called double-buffering. The following describes how you use double-buffering.

# Compute a waveform in memory buffer A.
# Issue CMD_WRITE A with '''io_Data''' pointing to buffer A.
# Continue the waveform in memory buffer B.
# Issue CMD_WRITE B with '''io_Data''' pointing to Buffer B.
# Wait for CMD_WRITE A to finish.
# Continue the waveform in memory buffer A.
# Issue CMD_WRITE A with '''io_Data''' pointing to Buffer A.
# Wait for CMD_WRITE B to finish.
# Loop back to step 3 until the waveform is finished.
# At the end, remember to wait until both CMD_WRITE A and B are finished.

=== ADCMD_FINISH ===

The ADCMD_FINISH command aborts (calls '''AbortIO()''') the current write request on a channel or channels. This is useful if you have something playing, such as a long buffer or some repetitions of a buffer, and you want to stop it.

ADCMD_FINISH has a flag you can set (ADIOF_SYNCCYCLE) that allows the waveform to finish the current cycle before aborting it. This is useful for splicing together sounds at zero crossings or some other place in the waveform where the amplitude at the end of one waveform matches the amplitude at the beginning of the next. Zero crossings are positions within the waveform at which the amplitude is zero. Splicing at zero crossings gives you fewer clicks and pops when the audio channel is turned off or the volume is changed.

=== ADCMD_PERVOL ===

ADCMD_PERVOL lets you change the volume and period of a CMD_WRITE that is in progress. The change can take place immediately or you can set the ADIOF_SYNCCYCLE flag to have the change occur at the end of the cycle. This is useful to produce vibratos, glissandos, tremolos, and volume envelopes in music or to change the volume of a sound.

=== CMD_FLUSH ===

CMD_FLUSH aborts (calls AbortIO()) all CMD_WRITEs and all ADCMD_WAITCYCLEs that are queued up for the channel or channels. It does not abort ADCMD_LOCKs (only ADCMD_FREE clears locks).

=== CMD_RESET ===

CMD_RESET restores all the audio hardware registers. It clears the attach bits, restores the audio interrupt vectors if the programmer has changed them, and performs the CMD_FLUSH command to cancel all requests to the channels. CMD_RESET also unstops channels that have had a CMD_STOP performed on them. CMD_RESET does not unlock channels that have been locked by ADCMD_LOCK.

=== ADCMD_WAITCYCLE ===

This is a single-channel command. ADCMD_WAITCYCLE is replied to when the current cycle has completed, If there is no CMD_WRITE in progress, it returns immediately.

=== CMD_STOP ===

This command stops the current write cycle immediately. If there are no CMD_WRITEs in progress, it sets a flag so any future CMD_WRITEs are queued up and do not begin processing (playing).

=== CMD_START ===

CMD_START undoes the CMD_STOP command. Any cycles that were stopped by the CMD_STOP command are actually lost because of the impossibility of determining exactly where the DMA ceased. If the CMD_WRITE command was playing two cycles and the first one was playing when CMD_STOP was issued, the first one is lost and the second one will be played.

This command is also useful when you are playing the same wave form with the same period out of multiple channels. If the channels are stopped when the CMD_WRITE commands are issued, CMD_START exactly synchronizes them, avoiding cancellation and distortion. When channels are allocated, they are effectively started by the CMD_START command.

=== CMD_READ ===

CMD_READ is a single-channel command. Its only function is to return a pointer to the current CMD_WRITE command. It enables you to determine which request is being processed.

== Double Buffered Sound Example ==

The program listed below demonstrates double buffering with the audio device. Run the program from the CLI. It takes one parameter—the name of an IFF 8SVX sample file to play on the Amiga’s audio device. The maximum size for a sample on the Amiga is 128K. However, by using double-buffering and queueing up requests to the audio device, you can play longer samples smoothly and without breaks.

<pre>/*
* Audio_8SVX.c
*
* 8SVX example - double buffers >128K samples
*
* Compile with SAS C 5.10 lc -b1 -cfistq -v -y -L
*
* Run from CLI only
*/

#include <exec/types.h>
#include <exec/memory.h>
#include <devices/audio.h>
#include <dos/dos.h>
#include <dos/dosextens.h>
#include <graphics/gfxbase.h>
#include <iff/iff.h>
#include <iff/8svx.h>

#include <clib/exec_protos.h>
#include <clib/alib_protos.h>
#include <clib/dos_protos.h>
#include <clib/graphics_protos.h>

#include <stdlib.h>
#include <stdio.h>

#ifdef LATTICE
int CXBRK(void) { return(0); } /* Disable SAS CTRL/C handling */
int chkabort(void) { return(0); } /* really */
#endif

#define VHDR MakeID('V','H','D','R')
#define BODY MakeID('B','O','D','Y')
#define MY8S MakeID('8','S','V','X')

void kill8svx(char *);
void kill8(void);

/*--------------------*/ /* These globals are needed */
/* G L O B A L S */ /* by the clean up routines */
/*--------------------*/
struct IOAudio *AIOptr1, /* Pointers to Audio IOBs */
*AIOptr2,
*Aptr;
struct Message *msg; /* Msg, port and device for */
struct MsgPort *port, /* driving audio */
*port1,*port2;
ULONG device;
UBYTE *sbase,*fbase; /* For sample memory allocation */
ULONG fsize,ssize; /* and freeing */

struct FileHandle *v8handle;
UBYTE chan1[] = { 1 }; /* Audio channel allocation arrays */
UBYTE chan2[] = { 2 };
UBYTE chan3[] = { 4 };
UBYTE chan4[] = { 8 };
UBYTE *chans[] = {chan1,chan2,chan3,chan4};

BYTE oldpri,c; /* Stuff for bumping priority */

struct Task *mt=0L;
struct GfxBase *GfxBase = NULL;

/*-----------*/
/* M A I N */
/*-----------*/

void main(int argc,char **argv)
{

/*-------------*/
/* L O C A L S */
/*-------------*/

char *fname; /* File name and data pointer*/
UBYTE *p8data; /* for file read. */
ULONG clock; /* Clock constant */
ULONG length[2]; /* Sample lengths */
BYTE iobuffer[8], /* Buffer for 8SVX header */
*psample[2]; /* Sample pointers */
Chunk *p8Chunk; /* Pointers for 8SVX parsing */
Voice8Header *pVoice8Header;
ULONG y,rd8count,speed; /* Counters, sampling speed */
ULONG wakebit; /* A wakeup mask */

/*-------------*/
/* C O D E */
/*-------------*/

/*------------------------------*/
/* Check Arguments, Initialize */
/*------------------------------*/

fbase=0L;
sbase=0L;
AIOptr1=0L;
AIOptr2=0L;
port=0L;
port1=0L;
port2=0L;
v8handle=0L;
device=1L;

if (argc < 2)
{
kill8svx("No file name given.\n");
exit(1L);
}
fname=argv[1];

/*---------------------------*/
/* Initialize Clock Constant */
/*---------------------------*/

GfxBase=(struct GfxBase *)OpenLibrary("graphics.library",0L);
if (GfxBase==0L)
{
puts("Can't open graphics library\n");
exit(1L);
}

if (GfxBase->DisplayFlags & PAL)
clock=3546895L; /* PAL clock */
else
clock=3579545L; /* NTSC clock */

if (GfxBase)
CloseLibrary( (struct Library *) GfxBase);

/*---------------*/
/* Open the File */
/*---------------*/

v8handle= (struct FileHandle *) Open(fname,MODE_OLDFILE);
if (v8handle==0)
{
kill8svx("Can't open 8SVX file.\n");
exit(1L);
}

/*-------------------------------------------*/
/* Read the 1st 8 Bytes of the File for Size */
/*-------------------------------------------*/
rd8count=Read((BPTR)v8handle,iobuffer,8L);
if (rd8count==-1)
{
kill8svx ("Read error.\n");
exit(1L);
}

if (rd8count<8)
{
kill8svx ("Not an IFF 8SVX file, too short\n");
exit(1L);
}

/*-----------------*/
/* Evaluate Header */
/*-----------------*/
p8Chunk=(Chunk *)iobuffer;
if (p8Chunk->ckID != FORM )
{
kill8svx("Not an IFF FORM.\n");
exit(1L);
}

/*--------------------------------------------*/
/* Allocate Memory for File and Read it in. */
/*--------------------------------------------*/
fbase= (UBYTE *)AllocMem(fsize=p8Chunk->ckSize , MEMF_PUBLIC|MEMF_CLEAR);
if (fbase==0)
{
kill8svx("No memory for read.\n");
exit(1L);
}

p8data=fbase;

rd8count=Read((BPTR)v8handle,p8data,p8Chunk->ckSize);
if (rd8count==-1)
{
kill8svx ("Read error.\n");
exit(1L);
}

if (rd8count<p8Chunk->ckSize)
{
kill8svx ("Malformed IFF, too short.\n");
exit(1L);
}

/*-------------------*/
/* Evaluate IFF Type */
/*-------------------*/
if (MakeID( *p8data, *(p8data+1) , *(p8data+2) , *(p8data+3) ) != MY8S )
{
kill8svx("Not an IFF 8SVX file.\n");
exit(1L);
}

/*----------------------*/
/* Evaluate 8SVX Chunks */
/*----------------------*/
p8data=p8data+4;

while( p8data < fbase+fsize )
{
p8Chunk=(Chunk *)p8data;

switch(p8Chunk->ckID)
{
case VHDR:
/*------------------------------------------------*/
/* Get a pointer to the 8SVX header for later use */
/*------------------------------------------------*/
pVoice8Header=(Voice8Header *)(p8data+8L);
break;

case BODY:
/*-------------------------------------------------*/
/* Create pointers to 1-shot and continuous parts */
/* for the top octave and get length. Store them. */
/*-------------------------------------------------*/
psample[0] = (BYTE *)(p8data + 8L);
psample[1] = psample[0] + pVoice8Header->oneShotHiSamples;
length[0] = (ULONG)pVoice8Header->oneShotHiSamples;
length[1] = (ULONG)pVoice8Header->repeatHiSamples;
break;

default:
break;
}
/* end switch */

p8data = p8data + 8L + p8Chunk->ckSize;

if (p8Chunk->ckSize&1L == 1)
p8data++;
}

/* Play either the one-shot or continuous, not both */
if (length[0]==0)
y=1;
else
y=0;

/*---------------------------------------*/
/* Allocate chip memory for samples and */
/* copy from read buffer to chip memory. */
/*---------------------------------------*/
if (length[y]<=102400)
ssize=length[y];
else
ssize=102400;

sbase=(UBYTE *)AllocMem( ssize , MEMF_CHIP | MEMF_CLEAR);
if (sbase==0)
{
kill8svx("No chip memory.\n");
exit(1L);
}

CopyMem(psample[y],sbase,ssize);
psample[y]+=ssize;

/*----------------------------------*/
/* Calculate playback sampling rate */
/*----------------------------------*/
speed = clock / pVoice8Header->samplesPerSec;

/*-------------------*/
/* Bump our priority */
/*-------------------*/
mt=FindTask(NULL);
oldpri=SetTaskPri(mt,21);

/*--------------------------------*/
/* Allocate two audio I/O blocks */
/*--------------------------------*/
AIOptr1=(struct IOAudio *)
AllocMem( sizeof(struct IOAudio),MEMF_PUBLIC|MEMF_CLEAR);
if (AIOptr1==0)
{
kill8svx("No IO memory\n");
exit(1L);
}

AIOptr2=(struct IOAudio *)
AllocMem( sizeof(struct IOAudio),MEMF_PUBLIC|MEMF_CLEAR);
if (AIOptr2==0)
{
kill8svx("No IO memory\n");
exit(1L);
}

/*----------------------*/
/* Make two reply ports */
/*----------------------*/

port1=CreatePort(0,0);
if (port1==0)
{
kill8svx("No port\n");
exit(1L);
}

port2=CreatePort(0,0);
if (port2==0)
{
kill8svx("No port\n");
exit(1L);
}

c=0;
while(device!=0 && c<4)
{
/*---------------------------------------*/
/* Set up audio I/O block for channel */
/* allocation and Open the audio device */
/*---------------------------------------*/
AIOptr1->ioa_Request.io_Message.mn_ReplyPort = port1;
AIOptr1->ioa_Request.io_Message.mn_Node.ln_Pri = 127; /* No stealing! */
AIOptr1->ioa_AllocKey = 0;
AIOptr1->ioa_Data = chans[c];
AIOptr1->ioa_Length = 1;

device=OpenDevice(AUDIONAME,0L,(struct IORequest *)AIOptr1,0L);
c++;
}

if (device!=0)
{
kill8svx("No channel\n");
exit(1L);
}

/*-------------------------------------------*/
/* Set Up Audio IO Blocks for Sample Playing */
/*-------------------------------------------*/

AIOptr1->ioa_Request.io_Command =CMD_WRITE;
AIOptr1->ioa_Request.io_Flags =ADIOF_PERVOL;

/*--------*/
/* Volume */
/*--------*/

AIOptr1->ioa_Volume=60;

/*---------------*/
/* Period/Cycles */
/*---------------*/

AIOptr1->ioa_Period =(UWORD)speed;
AIOptr1->ioa_Cycles =1;

*AIOptr2 = *AIOptr1; /* Make sure we have the same allocation keys, */
/* same channels selected and same flags */
/* (but different ports...) */

AIOptr1->ioa_Request.io_Message.mn_ReplyPort = port1;
AIOptr2->ioa_Request.io_Message.mn_ReplyPort = port2;

/*--------*/
/* Data */
/*--------*/

AIOptr1->ioa_Data =(UBYTE *)sbase;
AIOptr2->ioa_Data =(UBYTE *)sbase + 51200;

/*-----------------*/
/* Run the sample */
/*-----------------*/

if (length[y]<=102400)
{
AIOptr1->ioa_Length=length[y]; /* No double buffering needed */
BeginIO((struct IORequest *)AIOptr1); /* Begin the sample, wait for */
wakebit=0L; /* it to finish, then quit. */
wakebit=Wait(1 << port1->mp_SigBit);
while((msg=GetMsg(port1))==0){};
}
else
{
length[y]-=102400; /* It's a real long sample so */
AIOptr1->ioa_Length=51200L; /* double buffering is needed */
AIOptr2->ioa_Length=51200L;
BeginIO((struct IORequest *)AIOptr1); /* Start up the first 2 blocks... */
BeginIO((struct IORequest *)AIOptr2);
Aptr=AIOptr1;
port=port1; /* Set the switch... */

while(length[y]>0)
{ /* We Wait() for one IO to finish, */
wakebit=Wait(1 << port->mp_SigBit); /* then reuse the IO block & queue */
while((msg=GetMsg(port))==0){}; /* it up again while the 2nd IO */
/* block plays. Switch and repeat. */
/* Set length of next IO block */
if (length[y]<=51200)
Aptr->ioa_Length=length[y];
else
Aptr->ioa_Length=51200L;

/* Copy sample fragment from read buffer to chip memory */
CopyMem(psample[y],Aptr->ioa_Data,Aptr->ioa_Length);

/* Adjust size and pointer of read buffer*/
length[y]-=Aptr->ioa_Length;
psample[y]+=51200;

BeginIO((struct IORequest *)Aptr);

if (Aptr==AIOptr1)
{
Aptr=AIOptr2; /* This logic handles switching */
port=port2; /* between the 2 IO blocks and */
} /* the 2 ports we are using. */
else
{
Aptr=AIOptr1;
port=port1;
}
}

/*-------------------------------------------------*/
/* OK we are at the end of the sample so just wait */
/* for the last two parts of the sample to finish */
/*-------------------------------------------------*/
wakebit=Wait(1 << port->mp_SigBit);
while((msg=GetMsg(port))==0){};
if (Aptr==AIOptr1)
{
Aptr=AIOptr2; /* This logic handles switching */
port=port2; /* between the 2 IO blocks and */
} /* the 2 ports we are using. */
else
{
Aptr=AIOptr1;
port=port1;
}
wakebit=Wait(1 << port->mp_SigBit);
while((msg=GetMsg(port))==0){};
}

kill8();
exit(0L);
}

/*----------------*/
/* Abort the Read */
/*----------------*/
void
kill8svx(kill8svxstring)
char *kill8svxstring;
{
puts(kill8svxstring);
kill8();
}

/*-------------------------*/
/* Return system resources */
/*-------------------------*/
void
kill8()
{
if (device ==0)
CloseDevice((struct IORequest *)AIOptr1);
if (port1 !=0)
DeletePort(port1);
if (port2 !=0)
DeletePort(port2);
if (AIOptr1!=0)
FreeMem( AIOptr1,sizeof(struct IOAudio) );
if (AIOptr2!=0)
FreeMem( AIOptr2,sizeof(struct IOAudio) );

if (mt!=0)
SetTaskPri(mt,oldpri);

if (sbase !=0)
FreeMem (sbase, ssize);
if (fbase !=0)
FreeMem(fbase,fsize);
if (v8handle!=0)
Close((BPTR)v8handle);
}</pre>
== Additional Information on the Audio Device ==

Additional programming information on the audio device can be found in the include files and the Autodocs for the audio device. Both are contained in the [[Autodocs:Main|Autodocs]]. Information can also be found in the ''Amiga Hardware Reference Manual''.

{| class="wikitable"
!colspan="2"|Audio Device Information
|-
|Includes||devices/audio.h devices/audio.i
|-
|[[Autodocs:Main|Autodocs]]||[[audio.doc]]
|}

Intuition Menu Class

2025-01-26T19:36:51Z

Costel Mincea: Text replacement - "<syntaxhighlight>" to "<syntaxhighlight lang="C" line>"

= An overview =

Starting with version 54.6, Intuition features a built-in BOOPSI menu class ("menuclass") which aims to fully replace the traditional way of setting up and handling menus in applications.

Its object-oriented API allows to easily build complex menu trees, freeing a program from the need to use gadtools.library for that job. It also provides extensive control over menus, making it possible to define, read and change their properties thanks to simple yet flexible methods and attributes.

Moreover, menuclass extends the capabilities of the original Intuition menu system. For instance, it can handle any number of sub-menu levels, as well as any amount of items in menus and sub-menus. For nearly all operations, it transparently synchronizes itself with Intuition and performs menu relayout if needed. Automatic placement of custom images in front of menu item labels is also supported.

== BOOPSI menus vs. traditional menus ==

BOOPSI menus may look and feel identical to traditional ones from the point of view of the user, but are handled quite differently in application code.

The old-style, white-box Menu and MenuItem structures are replaced by abstract objects (instances of menuclass) accessed through an object-oriented interface, removing the need for manual poking or dedicated menu functions.

Such BOOPSI menu objects are able to perform automatically most operations for which their traditional counterparts would require special assistance from the application.

== Types of menuclass objects ==

There exist three distinct types of menuclass objects -- menu root, menu and menu item. Any instance of the class belongs to one of these types, specified at OM_NEW time through the MA_Type attribute.

The possible values for MA_Type are:

; T_ROOT
: A menu root object, also known as a menu strip as it is the parent of all menu objects. This differs from the old-style menu system, where a "menu strip" was just a linked list of Menu structures. Besides being the actual root of a menu tree, a menu root object also holds essential state information on the tree as a whole. It may be used in any place an old-style menu strip can, except for the ItemAddress() function (replaced by the MM_FINDID method). A menu root object can have any number of menu objects as children.

; T_MENU
: A menu object, equivalent to the old-style Menu structure. A menu object can have any number of menu item objects as children (and should always have at least one).

; T_ITEM
: A menu item object, equivalent to the old-style MenuItem structure. A menu item object can have any number of menu item objects as children (sub-items), even in the case it is itself a sub-item of some other menu item. Only a menu (sub-)item having no children (i.e. a leaf item) can be actually selected by the user.

== Compatibility ==

Save where explicitly allowed, menu and menu item objects instantiated from menuclass cannot be transparently used in place of the equivalent old-style Intuition elements, as not all of the traditional menu-related functions and rules apply to them.

A limited form of compatibility exists due to menuclass objects having Menu or MenuItem structures embedded in them, just like gadgetclass ones do with the (Ext)Gadget structure. However, such structures should never be directly accessed by user code unless otherwise documented.

Under most circumstances, applications should treat menuclass instances as "black boxes", the only exception to this rule currently being that it is permitted to read certain bits from the Flags field of their embedded legacy structure (see also next subsection).

== Recognizing a BOOPSI menu object ==

Although an application normally should know if it is using BOOPSI menus, it may happen that a library or a class needs to check the type of menus passed to it by a client. This is easily done with the following test:

<syntaxhighlight lang="C" line>
if ((((struct Menu *)menu_object_ptr)->Flags & BOOPSIMENU) != 0)
...
</syntaxhighlight>

If the flag BOOPSIMENU is set, the object is a menuclass instance, otherwise it is a traditional Menu or MenuItem structure.

{{Note|text=In the above test it would have been exactly the same if we had chosen to cast the object to a struct MenuItem * rather than to a struct Menu * because the Flags field is located at the same offset (and has the same size) in both structures.}}

= Adding BOOPSI menus to an application =

In this section we'll cover the basics of using the new menuclass in a typical application, and the main differences between BOOPSI and traditional menus.

The first step in adding BOOPSI menus to your application is to build a tree of menuclass objects, each with its appearance and behavior defined by attributes that can be set at NewObject() time.

== Label and ID of menus and menu items ==

For menu and menu item objects, the application should specify at least a label string and an ID number as a minimal set of attributes.

The label is assigned via MA_Label and is the text Intuition will display to represent a menu or menu item on the screen. A special value for this attribute is the constant ML_SEPARATOR, which turns a menu item into a separator line.

The ID, passed with the MA_ID tag, is a 32-bit unsigned integer that uniquely identifies a particular menu or menu item object. This number is passed back to the application through the IDCMP mechanism whenever the user picks a menu item or asks for help on a menu or menu item.

Any number may be chosen as an ID for a menuclass object, except for 0 (zero): this constant has the alias NO_MENU_ID in <intuition/menuclass.h> and is always an invalid value for an object's MA_ID attribute. Also, when an IDCMP_MENUPICK or IDCMP_MENUHELP ExtIntuiMessage reports NO_MENU_ID in its eim_LongCode field, this is to be interpreted as "no menu selection" (i.e. it has the same meaning MENUNULL has for old-style menus).

Menu root objects, as well as menu items acting as separator lines, don't need to have an ID number. Menu root objects don't need a label string either.

== Building a menu tree with menuclass ==

A menu tree is organized as a hierarchy of nested menuclass objects.

At the very top of the tree there is the menu root, having one or more menus as children. These make up the menu strip that appears on the screen when the user presses the right mouse button.

Each menu is the parent of one or more menu items. A menu item can have other menu items as children as well, thus forming a sub-menu. A menu item which is part of a sub-menu (also called a sub-item, i.e. the child of another menu item) can in turn have children (sub-items) of its own.

The leaf nodes of the tree are menu items or sub-items with no children. These are the actually selectable menu options.

There is no limit to the depth of the menu tree other than the available system memory.

You can append children to a menuclass object at OM_NEW or OM_SET time with the MA_AddChild tag, or by using the OM_ADDMEMBER method (more on this later).

An example of a very simple menu tree generation could be:

<syntaxhighlight lang="C" line>
Object *menustripobj;

menustripobj = IIntuition->NewObject(NULL,"menuclass",MA_Type,T_ROOT,
MA_AddChild, IIntuition->NewObject(NULL,"menuclass",MA_Type,T_MENU,
MA_Label, "Project",
MA_AddChild, IIntuition->NewObject(NULL,"menuclass",MA_Type,T_ITEM,
MA_Label, "Open...",
MA_ID, MID_PROJECT_OPEN,
TAG_END),
MA_AddChild, IIntuition->NewObject(NULL,"menuclass",MA_Type,T_ITEM,
MA_Label, "Save",
MA_ID, MID_PROJECT_SAVE,
TAG_END),
MA_AddChild, IIntuition->NewObject(NULL,"menuclass",MA_Type,T_ITEM,
MA_Label, "Save as...",
MA_ID, MID_PROJECT_SAVEAS,
TAG_END),
MA_AddChild, IIntuition->NewObject(NULL,"menuclass",MA_Type,T_ITEM,
MA_Label, ML_SEPARATOR,
TAG_END),
MA_AddChild, IIntuition->NewObject(NULL,"menuclass",MA_Type,T_ITEM,
MA_Label, "About...",
MA_ID, MID_PROJECT_ABOUT,
TAG_END),
MA_AddChild, IIntuition->NewObject(NULL,"menuclass",MA_Type,T_ITEM,
MA_Label, ML_SEPARATOR,
TAG_END),
MA_AddChild, IIntuition->NewObject(NULL,"menuclass",MA_Type,T_ITEM,
MA_Label, "Quit",
MA_ID, MID_PROJECT_QUIT,
TAG_END),
TAG_END),
TAG_END);
</syntaxhighlight>

If you prefer a more compact style of coding, <intuition/menuclass.h> offers a number of macros allowing to simplify the tree description a little. Using said macros, the above code could be rewritten as follows:

<syntaxhighlight lang="C" line>
Object *menustripobj;

menustripobj = MStrip,
MA_AddChild, MTitle("Project"),
MA_AddChild, MItem("Open..."),
MA_ID, MID_PROJECT_OPEN,
MEnd,
MA_AddChild, MItem("Save"),
MA_ID, MID_PROJECT_SAVE,
MEnd,
MA_AddChild, MItem("Save as..."),
MA_ID, MID_PROJECT_SAVEAS,
MEnd,
MA_AddChild, MSeparator,
MEnd,
MA_AddChild, MItem("About..."),
MA_ID, MID_PROJECT_ABOUT,
MEnd,
MA_AddChild, MSeparator,
MEnd,
MA_AddChild, MItem("Quit"),
MA_ID, MID_PROJECT_QUIT,
MEnd,
MEnd,
MEnd;
</syntaxhighlight>

{{Note|text=When using the MTitle() and MItem() macros, the label is passed as an argument to the macro itself rather than via an explicit MA_Label tag.}}

We'll use the compact style in the rest of this document, except in cases where the more verbose one provides greater clarity.

== Menu item keyboard shortcuts ==

As with traditional Intuition menus, menuclass item objects can have a keyboard shortcut which is displayed next to the item's label. Shortcuts can have one or more characters; a shortcut of more than one character is also called "command string" (for instance, "ctrl z").

A single-character shortcut is processed directly by Intuition, and appears at the right side of the menu item with an "Amiga key" symbol prepended to it. When using a command string of more than one character, however, Intuition will display it at the right side of the item (without the "Amiga key" symbol) but won't process the corresponding key combination; the application has to handle that on its own.

There are two ways to specify a keyboard shortcut for a menuclass item object.

You can pass it with the MA_Key attribute, as in the following example:

<syntaxhighlight lang="C" line>
item = MItem("Save"),
MA_ID, MID_SAVE,
MA_Key, "S",
MEnd;
</syntaxhighlight>

Alternatively, you can prepend it to the item's label string, separed by a '|' character, this way:

<syntaxhighlight lang="C" line>
item = MItem("S|Save"),
MA_ID, MID_SAVE,
MEnd;
</syntaxhighlight>

If you opt for the latter approach, you may also use a NUL ('\0') character in place of the '|'. This can prove useful when converting to BOOPSI menu usage an existing application employing such a method to embed shortcuts in its catalog strings.

{{Note|text=The NUL byte solution only works for single-letter shortcuts and requires that no item in the menu tree has a label of just one letter, as any such label would be mistaken for a shortcut followed by random bytes. When you have single-letter labels, therefore, you cannot use this feature and must disable it for the whole tree. That's done by passing { MA_EmbeddedKey, FALSE } to the menu root object; this attribute will be inherited by all objects.}}

== Inheritance of menu attributes ==

There are some attributes of menuclass objects that are automatically inherited by all their descendants, except those for which they're explicitly set to some different value. For instance, if you want your menus to use a particular font, you only need to set the MA_TextAttr attribute for the menu root, and all items (and sub-items) of all menus will be displayed with that font.

Any menuclass attribute which is automatically inherited from the parent object when not specified explicitly is clearly described as such, both in the autodoc and in the <intuition/menuclass.h> header file.

== Attaching the menu tree to a window ==

You can attach a menu tree built with menuclass to a window just like you would do with traditional non-BOOPSI menus, i.e. by calling SetMenuStrip(). Starting with Intuition V54, this function accepts a BOOPSI menu root object as the menu strip pointer.
Therefore, once you've opened your window, you can simply do the following:

<syntaxhighlight lang="C" line>
IIntuition->SetMenuStrip(window,menustripobj);
</syntaxhighlight>

and the menu tree will be ready to use, after undergoing an automatic layout to adapt itself to the window's screen.

An alternative to the above is passing the menus to the window at opening time, via the new V54 tag WA_MenuStrip. This way your window will open with the menus already attached and laid out.

When using window.class, you can achieve the same by passing the class-specific tag WINDOW_MenuStrip. (Starting with V54, window.class supports WA_MenuStrip as well, as an alias for WINDOW_MenuStrip.)

== Detaching the menu tree from a window ==

BOOPSI menus, like traditional ones, can be detached from a window at any time with ClearMenuStrip(). After having been detached, they can also be reattached by way of ResetMenuStrip(), as usual.

In many cases, however, you don't need to remove BOOPSI menus as you would with old-style menus. Changing the selection state of "checkmarkable" items, as well as disabling or enabling single items or whole menus, may be performed by just setting the appropriate attribute of the menu object in question, regardless of whether or not the menus are in use. Any needed synchronization with Intuition is handled internally by menuclass.

The above is generally true for all operations you can do on menuclass objects, such as changing their label, image, font or charset, or even their position in the menu tree. In fact, a BOOPSI menu tree even supports addition or removal of menus and items on-the-fly without any clearing and resetting of the menus.

Whenever a change requires a relayout of some part of the menu tree, menuclass will automatically take care of that.

Additionally, as of Intuition V54 it is no longer mandatory to remove the menus with ClearMenuStrip() before closing the window. CloseWindow() itself will take care of clearing the menus if needed (no matter if BOOPSI or old-style).

{{Note|text=It is still required, however, to use ClearMenuStrip() to remove the menu strip of a window before setting a different one with SetMenuStrip().}}

== Handling menu item selections by the user ==

Upon receiving a menu pick event such as IDCMP_MENUPICK (or WMHI_MENUPICK if using window.class), your application can find out which menu items the user selected by invoking repeatedly the MM_NEXTSELECT method on the root object of the menu tree (i.e. the menu strip object). This will return all selected item IDs in sequence; in many cases there will be only one, but there may be more if the user performed multiple selection.

Once all IDs have been retrieved, MM_NEXTSELECT will return NO_MENU_ID which means there are no more selections in the list.

{{Note|text=MM_NEXTSELECT might even return NO_MENU_ID immediately on the first invocation; this would mean the user initiated and terminated a menu session without picking any item. Be prepared to handle this case.}}

The MM_NEXTSELECT method uses the following mpNextSelect message structure:

<syntaxhighlight lang="C" line>
struct mpNextSelect
{
uint32 MethodID;
uint32 mpns_Reserved;
uint32 mpns_CurrentID;
};
</syntaxhighlight>

where MethodID is MM_NEXTSELECT, mpns_Reserved should be always set to zero, and mpns_CurrentID is the menu item ID the method returned on the previous invocation. To obtain the first ID in the selection list, pass NO_MENU_ID in the mpns_CurrentID field.

An example of this method's usage would be:

<syntaxhighlight lang="C" line>
uint32 id = NO_MENU_ID;

while ((id = IIntuition->IDoMethod(menustripobj,MM_NEXTSELECT,0,id)) != NO_MENU_ID)
{
switch (id)
{
/* Process menu selections */

case MID_PROJECT_OPEN:
...
}
}
</syntaxhighlight>

An alternative way to get the ID of the first (or only) selected menu item is to read it from the eim_LongCode field of the ExtIntuiMessage reporting the IDCMP_MENUPICK event (IntuiMessages generated by Intuition are always really ExtIntuiMessages, and can be cast as such). Since a menuclass object's ID is a 32-bit value, it can't fit in the 16-bit IntuiMessage.Code field, the value of which is currently undefined for IDCMP events coming from BOOPSI menus.

The above example could thus be modified as follows:

<syntaxhighlight lang="C" line>
uint32 id = ((struct ExtIntuiMessage *)intuimsg)->eim_LongCode;

while (id != NO_MENU_ID)
{
switch (id)
{
/* Process menu selections */

case MID_PROJECT_OPEN:
...
}

id = IIntuition->IDoMethod(menustripobj,MM_NEXTSELECT,0,id);
}
</syntaxhighlight>

The first approach is probably more convenient when using window.class since in that case you would need an additional IDCMP hook to access the ExtIntuiMessage in order to read its eim_LongCode field.

== Handling menu help requests by the user ==

If your window has the WA_MenuHelp attribute set to TRUE, and it's listening to IDCMP_MENUHELP events, the user can request help on a menu item or a menu title by pressing the [Help] key when that item or title is being highlighted by the mouse pointer. Upon reception of a menu help event, your application can easily find out the ID of the item or title the help request was about by querying the MA_MenuHelpID attribute of the menu root object.

An example of this might be:

<syntaxhighlight lang="C" line>
uint32 help_id;

IIntuition->GetAttr(MA_MenuHelpID,menustripobj,&help_id);
</syntaxhighlight>

{{Note|text=The menu help ID value may be NO_MENU_ID, which means the [Help] key was pressed by the user while no menu item or title was highlighted.}}

Menu help doesn't support multiple selection, so you have to deal with just one ID per event. As with menu pick, you can also retrieve the ID value by reading the ExtIntuiMessage.eim_LongCode field.

== Menu pick hooks and menu help hooks ==

Any menuclass object can have custom hooks associated to it with dedicated code to handle menu selections or help requests for that specific object. Such hooks can be invoked automatically by the main event handling loop every time a menu pick or menu help event occurs.

The hook that handles menu item selections is specified through the MA_PickHook attribute; similarly, you can use the MA_HelpHook attribute to specify the hook handling menu help requests.

These two attributes are inherited by all children of a menuclass object. This allows, if desired, to reuse the same hook for all the items of a menu (or all the sub-items of an item) simply by setting it for that menu (or item), rather than having to pass it to each child explicitly. Such a "common" hook could act as a dispatcher, calling the appropriate individual handling function according to the ID of the object it is invoked on.

A menuclass object's pick or help hook will be invoked as follows:

<syntaxhighlight lang="C" line>
HookFunction(struct Hook *hook, Object *obj, struct MenuEventMessage *msg)
</syntaxhighlight>

where 'obj' is the object itself and 'msg' is a pointer to a MenuEventMessage structure.

The MenuEventMessage structure is defined as follows:

<syntaxhighlight lang="C" line>
struct MenuEventMessage
{
uint32 StructSize; /* For future expansion */
uint32 EventType; /* ET_MENUPICK or ET_MENUHELP */
struct Window *Window; /* Event window pointer */
APTR UserData; /* Custom data pointer */
};
</syntaxhighlight>

The EventType field is useful to distinguish between the two types of event the hook could be invoked for, in case the same hook function is used for both. The Window field holds the address of the event's window (i.e. the window your menu tree is associated to) and the UserData field is used to pass to the hook any kind of context information it might require, as explained a little below.

The pick or help hook can use the supplied information (menu object, window and custom data pointer) to process the event. The return value of the hook is not currently defined; it's recommended to set it to zero for future compatibility.

To have menuclass invoke the pick hook of a menuclass object, your application needs to use the MM_HANDLEPICK method in its event loop.

Like MM_NEXTSELECT, MM_HANDLEPICK can be invoked repeatedly to browse through all items in the menu selection chain. The difference is that this method only returns the ID of selected items that don't have a pick hook; whenever it finds a selected item whose pick hook is non-NULL, it invokes that hook and proceeds to the next item without returning anything. When there are no more items left in the menu selection chain, MM_HANDLEPICK returns NO_MENU_ID.

The mechanism is exactly the same for help hooks, except in that case you have to use the MM_HANDLEHELP method, which only needs to invoked once as menu help events don't support multiple selection: if the menu object the user asked help about doesn't have a help hook, MM_HANDLEHELP will return its ID, otherwise it will invoke the hook and return NO_MENU_ID.

Both the MM_HANDLEPICK and MM_HANDLEHELP methods should be invoked on the menu root object, and use the same message structure:

<syntaxhighlight lang="C" line>
struct mpHandleEvent
{
uint32 MethodID;
uint32 mphe_Reserved;
uint32 mphe_CurrentID;
struct Window *mphe_Window;
APTR mphe_UserData;
};
</syntaxhighlight>

where MethodID is MM_HANDLEPICK or MM_HANDLEHELP, mphe_Reserved should always be set to zero, and mphe_CurrentID is the ID returned by the method's previous invocation (ignored by MM_HANDLEHELP; pass NO_MENU_ID on the first invocation of MM_HANDLEPICK). Additionally, you should store the event's window address in mphe_Window (e.g. IntuiMessage->IDCMPWindow) and any custom data to be passed to the pick or help hook in mphe_UserData; your hook will be able to read back this information from the MenuEventMessage.

A simple example of how to take advantage of the custom pick hook feature might be the following:

<syntaxhighlight lang="C" line>
uint32 id = NO_MENU_ID;

while ((id = IIntuition->IDoMethod(menustripobj,MM_HANDLEPICK,
0,
id,
imsg->IDCMPWindow,
mycustomdata)) != NO_MENU_ID)
{
/* This selected menu object doesn't have
* a pick hook, so let's handle it here.
*/
switch (id)
{
/* Process menu selections */

case MID_PROJECT_OPEN:
...
}
}
</syntaxhighlight>

It goes without saying that if none of your application's menuclass object has a pick hook or help hook, you never need to invoke MM_HANDLEPICK/MM_HANDLEHELP in your event handling code; you can just use the simpler MM_NEXTSELECT method and MA_MenuHelpID attribute instead, as covered in previous subsections.

== Retrieving a menuclass object's address from its ID number ==

Once you have found out which menu item was picked by the user by examining its ID, you may want to do some operations on the item object itself, and thus need its actual address. One way to achieve this could be to keep a look-up table in your application, initialized as the menu tree gets built, and using the IDs as indices. For instance, something like the following:

<syntaxhighlight lang="C" line>
...
MA_AddChild, mtable[MID_PROJECT_OPEN] = MItem("Open..."),
MA_ID, MID_PROJECT_OPEN,
MEnd,
MA_AddChild, mtable[MID_PROJECT_SAVE] = MItem("Save"),
MA_ID, MID_PROJECT_SAVE,
MEnd,
...
</syntaxhighlight>

The drawbacks of such an approach are increased memory consumption and reduced code readability. A simpler solution is offered by menuclass in the form of the MM_FINDID method. This uses the mpFindID structure, defined as:

<syntaxhighlight lang="C" line>
struct mpFindID
{
uint32 MethodID;
uint32 mpfi_Reserved;
uint32 mpfi_ID;
};
</syntaxhighlight>

where MethodID is MM_FINDID, mpfi_Reserved should always be set to zero, while mpfi_ID is the ID of the menu object whose address you're looking for. Here's a simple example of this method's invocation on the menu root object:

<syntaxhighlight lang="C" line>
m_obj = (Object *)IIntuition->IDoMethod(menustripobj,MM_FINDID,0,id);
</syntaxhighlight>

If a menu object with the specified ID is found within the menu tree, MM_FINDID will return its address, otherwise it will return NULL.

The MM_FINDID method doesn't actually need to be invoked on the menu root as in the above example. It just searches for an object having a given ID within the menu (sub-)tree hanging from the object it's invoked on. So if you already know the address of an object whose local sub-tree contains the one you want, it is possible to invoke MM_FINDID directly on that object and restrict the search to only a part of the menu tree.

Invoking the MM_FINDID method is the BOOPSI equivalent of calling ItemAddress() with traditional menus.

== Enabling and disabling menus and menu items ==

By default, a BOOPSI menu or item is enabled, meaning it looks clearly readable and can be selected by the user. When disabled, it is instead rendered with low contrast or a recessed appearance and is not selectable.

The MA_Disabled attribute is used to control the enable state of BOOPSI menu or item objects. It is possible to disable a menuclass object right from the start by passing { MA_Disabled, TRUE } to NewObject(), or change the object's enable state later at any time via SetAttrs(). Setting MA_Disabled to TRUE or FALSE is the BOOPSI equivalent of calling OnMenu() or OffMenu() on old-style menus.

Disabling a menu or a menu item will make all of its children show up disabled as well, down to the deepest sub-menu levels. Additionally, you can disable all your menus at once (i.e. make the entire menu tree disabled and not selectable) simply by disabling the menu strip object.

Another way to examine and modify the enable state of a menu or menu item is to invoke the MM_GETSTATE and MM_SETSTATE methods (see below for more on this).

== Selection state of toggle select and mutual exclude items ==

Whenever a toggle select or mutual exclude menu item is picked by the user, you can examine its selection state by reading the item's MA_Selected attribute. If its value is TRUE, the item is currently selected (checked) and is displayed with some small checkmark or radio button symbol drawn in front of it.

You can also programmatically change the selection state of this kind of items at any time by setting the value of MA_Selected with SetAttrs(), without having to clear and then reset the menu strip as you would with non-BOOPSI menus.

This attribute has no meaning for action items, i.e. items that don't represent the "on" or "off" state of some option.

Another way to examine and modify the selection state of a menu or menu item is to invoke the MM_GETSTATE and MM_SETSTATE methods (see below for more on this).

== Methods for controlling the enable and selection state of menu items ==

It is possible to examine and modify the enable state of a menu or menu item by invoking the MM_GETSTATE and MM_SETSTATE methods. These may prove more handy in many cases since they take an ID number to specify the target object instead of the object's actual address. This means they can be directly fed the result of MM_NEXTSELECT without having to go through MM_FINDID first.

Both these methods use the bitmask constants MS_CHECKED and MS_DISABLED to read or modify the corresponding MA_Selected and MA_Disabled attributes.

The MM_GETSTATE method uses the following message structure:

<syntaxhighlight lang="C" line>
struct mpGetState
{
uint32 MethodID;
uint32 mpgs_Reserved;
uint32 mpgs_ID;
};
</syntaxhighlight>

where MethodID is MM_GETSTATE, mpgs_Reserved should always be set to zero, and mpgs_ID is the ID number of the menuclass object whose state you want to read. The method should be invoked on the menu root object (or on the parent of the target object, if you have its address) and will return a bit mask whose value can be MS_CHECKED, MS_DISABLED, both constants ORed together, or zero. For instance, if MS_CHECKED is set in the method's return value it means that the object's MA_Selected attribute is currently TRUE.

The MM_SETSTATE method uses the following message structure:

<syntaxhighlight lang="C" line>
struct mpSetState
{
uint32 MethodID;
uint32 mpss_Reserved;
uint32 mpss_ID;
uint32 mpss_ApplyMask;
uint32 mpss_StateMask;
};
</syntaxhighlight>

where the first three fields are analogous to those of the mpGetState structure while mpss_ApplyMask is used to specify which attribute(s) should be modified, and mpss_StateMask contains the new values. For instance, if MS_DISABLED is set in mpss_ApplyMask, but not in mpss_StateMask, the object will become enabled as its MA_Disabled attribute will be set to FALSE. If MS_CHECKED is cleared in the mpss_ApplyMask field, on the other hand, the object's selection state will stay unchanged no matter what the value of mpss_StateMask is.

== Disposing of the menu tree ==

Due to its dynamic nature, usually a BOOPSI menu tree doesn't need to be freed and rebuilt by your application on environment changes or each time it has to undergo some significant modification. You may for instance reuse the same menu tree on different screens (as long as it's used on one screen at a time).

This means that all important state information stored in the menu tree such as which items are checked, disabled, etc. is never lost while the application is running, and that the menu tree can be disposed of just once on program's exit.

To free an entire menu tree, you just have to call DisposeObject() on its root object. Whatever disposable object you attached to some menu item, such as e.g. a BOOPSI image, will be freed as well unless you asked not to do so.

= Further menuclass features =

This section will outline a number of attributes and methods giving access to some more specialized functionality of menuclass.

== Specifying the menu font ==

Each menu item object can be displayed in its own font and size, although this is strongly discouraged as such an arrangement would look quite unprofessional. Still, if you for any reason need to set the font used by a menu item, you can do so with the MA_TextAttr attribute.

The font specified this way will be opened and closed by menuclass as needed.

If you set MA_TextAttr for a menuclass object, it will be inherited by all of its children. To specify a font for the entire menu tree, therefore, just set MA_TextAttr for the menu root object.

Whenever there isn't any specific reason to do otherwise, it's recommended not to use MA_TextAttr at all and just let the menus be displayed in the font that was chosen in the user's preferences for the screen they appear on.

== Adding images to menu items ==

A BOOPSI menu item can have an image displayed at the left side of (or in place of) the item's label. The image is specified through the MA_Image attribute; it may be either traditional or BOOPSI.

The item's height is adjusted if needed to make enough room for the image.

If the image is BOOPSI, it will be automatically disposed of when the menu item object is; to avoid that, you should set the item's MA_FreeImage attribute to FALSE. However, if you want to prevent automatic disposal for ALL images in the menu tree, it is more practical to set MA_FreeImage to FALSE for the menu root object since this way it will be inherited by all objects.

If the menu item has no label (i.e. it's an image-only item), you can still use MA_TextAttr to specify the font used for its keyboard shortcut character.

== Hiding menus and menu items ==

Any member of a BOOPSI menu tree can be hidden or revealed again at any time by your application. A hidden menuclass object is still physically present in the menu tree, but does not appear on the screen when menus are displayed, as if it had been actually removed.

The MA_Hidden attribute is used to control the hiding of a BOOPSI menu or item objects. It is possible to make a menu or item hidden right from the start by passing { MA_Hidden, TRUE } to NewObject(), or change the object's hiding state later via SetAttrs().

Hiding a menu or a menu item will (obviously) hide all of its children as well. Unlike disabling, however, you cannot hide the menu strip object -- if you want to make the entire menu tree disappear, just call ClearMenuStrip().

== Dynamic menu localization ==

So far, we've only examined the simple case where you pass an actual string as the value of a menuclass object's MA_Label attribute. There is however another possibility, and that is to specify a numeric index as MA_Label's value, which is later used to look up the appropriate string in the currently open catalog.

To be able to pass an integer value for MA_Label instead of a string, you need to tell menuclass what is the numeric range of string IDs. Any value outside of that range will be considered a string, and used directly as such. Values lying in the range, on the other hand, will be treated as catalog indices. The string ID range is specified with the MA_MinStringID and MA_MaxStringID attributes. (By default, the string ID range is empty and MA_Label is always interpreted as a string.)

Whenever an object's MA_Label attribute is actually a numeric index, its value is passed on each menu layout to a "localization hook" which will convert it to the correct string for the current language and charset.

The localization hook (aka string hook) is supplied by your application via the MA_StringHook attribute. You can simply set it for the root object, and it will be inherited by all objects in the menu tree.

Your hook will be invoked as follows:

<syntaxhighlight lang="C" line>
HookFunction(struct Hook *hook, Object *obj, struct MenuStringMessage *msg)
</syntaxhighlight>

where 'obj' is the menu or item the string ID to be converted belongs to, and 'msg' is a pointer to a MenuStringMessage structure (see below for definition) which carries the string ID.

You can also specify the address of an open catalog and/or a charset by setting the MA_Catalog and MA_CharSet attributes for the menu root object; if supplied, this information is also passed back to the hook in the MenuStringMessage.

The MenuStringMessage structure is defined as follows:

<syntaxhighlight lang="C" line>
struct MenuStringMessage
{
uint32 StructSize; /* For future expansion */
uint32 StringID; /* The string ID number */
struct Catalog *Catalog; /* Catalog pointer, may be NULL */
uint32 CharSet; /* Charset number, may be zero */
};
</syntaxhighlight>

Your string hook should return the correct catalog string for the passed string ID, or a default string if no catalog is available.

{{Note|text=All of the above is equally valid for the MA_Key attribute, which can be a string ID instead of an actual string just like MA_Label. Its string ID range is the same one of MA_Label (as defined by MA_MinStringID and MA_MaxStringID).}}

{{Note|title=Also Note|text=If you don't use a string hook, MA_Label and MA_Key should always be real strings and not numeric IDs, otherwise they'll get converted by menuclass to "????", which isn't very meaningful. The same will happen if the string hook returns a NULL string pointer.}}

== Adding and removing menus and menu items ==

A BOOPSI menu tree built with menuclass allows for dynamic addition and removal of menus and items at any time. As with other modifications, there's no need to detach the menu tree from the window in order to perform these operations; it's menuclass that takes care of synchronizing each change with Intuition and doing any necessary relayout afterwards.

To add a child to a menuclass object, you can simply call SetAttrs() to pass it the MA_AddChild tag with the address of the new child as data, the same way you would at OM_NEW time.

Here's an example of adding a sub-item to an item:

<syntaxhighlight lang="C" line>
/* Append a new entry to our "recent files" sub-menu */

new_item = MItem(filename), MA_ID, new_id++, MEnd;

IIntuition->SetAttrs(recentfiles_itemobj,MA_AddChild,new_item,TAG_END);
</syntaxhighlight>

A NULL pointer can safely be passed with MA_AddChild, and is simply ignored.

{{Note|text=In this example we're using a simple counter variable to generate an unique ID for each new sub-item -- we don't care about the ID value itself, we simply want to take notice if the item gets selected, and be able to retrieve its address with MM_FINDID whenever needed. This requires the new item to have a valid and unique ID number.}}

Just like they can be added, menus and menu items can also be removed from the menu tree as needed. This is achieved by passing the MA_RemoveChild tag to the parent menu object via SetAttrs(), with the address of the child as data.

For instance, we could remove an item from a menu this way:

<syntaxhighlight lang="C" line>
/* Close a window and remove its entry from our "open windows" menu */

id = (uint32)window->UserData; /* We stored the menu item's ID there */

IIntuition->CloseWindow(window);

item = (Object *)IIntuition->IDoMethod(openwindows_menuobj,MM_FINDID,0,id);

IIntuition->SetAttrs(openwindows_menuobj,MA_RemoveChild,item,TAG_END);

IIntuition->DisposeObject(item); /* Accepts a NULL argument */
</syntaxhighlight>

As with MA_AddChild, you can safely pass a NULL pointer with MA_RemoveChild.

Another way to perform addition and removal of children with menuclass objects is to use rootclass' OM_ADDMEMBER and OM_REMMEMBER methods. The above examples could thus be rewritten by replacing the SetAttrs() calls with:

<syntaxhighlight lang="C" line>
IIntuition->IDoMethod(recentfiles_itemobj,OM_ADDMEMBER,new_item);

IIntuition->IDoMethod(openwindows_menuobj,OM_REMMEMBER,item);
</syntaxhighlight>

As you would when dealing with Exec lists, you must be careful to avoid adding or removing the same child twice, or removing a child which was never added in the first place, since doing so will cause memory corruption.

== Browsing through all children of a menu object ==

You can obtain the addresses of all children of a menuclass object in sequence by invoking the MM_NEXTCHILD method in a loop. Once all the object's children have been been retrieved, MM_NEXTCHILD will return NULL to signal there are no more children.

The MM_NEXTCHILD method uses the following message structure:

<syntaxhighlight lang="C" line>
struct mpNextChild
{
uint32 MethodID;
uint32 mpnc_Reserved;
Object *mpnc_Current;
};
</syntaxhighlight>

where MethodID is MM_NEXTCHILD, mpnc_Reserved should always be set to zero, and mpnc_Current is the child object address the method did return on the previous invocation. Pass NULL in mpnc_Current to get the address of the first child.

An example of a loop retrieving all items of a menu:

<syntaxhighlight lang="C" line>
Object *obj = NULL;

while ((obj = (Object *)IIntuition->IDoMethod(menuobj,MM_NEXTCHILD,0,obj)) != NULL)
{
/* Do something with the item object */
}
</syntaxhighlight>

If you use MM_NEXTCHILD in a loop to remove an object's children one by one, be careful not to pass the method the address of an already removed object.

The correct way to do a sequential child removal is the following:

<syntaxhighlight lang="C" line>
while ((obj = (Object *)IIntuition->IDoMethod(menuobj,MM_NEXTCHILD,0,NULL)) != NULL)
{
IIntuition->IDoMethod(menuobj,OM_REMMEMBER,obj);
}
</syntaxhighlight>

This is analogous to performing a RemHead() loop on an Exec list.

== Scanning the menu tree ==

You can perform a scan of the whole menu tree, or even just a subsection of it, and have a custom function called on each object that is part of it. This makes it possible to implement any kind of operation that is not already provided by the existing menuclass methods.

To scan a menu (sub-)tree, you invoke the MM_SCAN method on its root object and specify a callback function and some parameters that will be passed back to it on each call. The MM_SCAN method uses the following message structure:

<syntaxhighlight lang="C" line>
struct mpScan
{
uint32 MethodID;
uint32 mps_Reserved;
struct Hook *mps_Hook;
uint32 mps_Args[4];
};
</syntaxhighlight>

where MethodID is MM_SCAN, mps_Reserved should always be set to zero, mps_Hook is a pointer to your custom hook, and mps_Args[0] to mps_Args[3] are (optional) arguments for the hook's function. Your hook will be invoked as follows:

<syntaxhighlight lang="C" line>
HookFunction(struct Hook *hook, Object *obj, struct MenuScanMessage *msg)
</syntaxhighlight>

where 'obj' is a menuclass object (whose exact type you can inspect by reading its MA_Type attribute) and 'msg' is a pointer to a MenuScanMessage structure.

The MenuScanMessage structure is defined as follows:

<syntaxhighlight lang="C" line>
struct MenuScanMessage
{
uint32 StructSize; /* For future expansion */
int32 Level; /* How deep we are in the menu tree */
uint32 Args[4]; /* Custom arguments */
};
</syntaxhighlight>

The Level field indicates the depth in the tree of the current object, starting from -1 for the root object. The four Args variables hold the same values which were passed upon invocation of the MM_SCAN method and can be used to feed your custom arguments back to the hook.

If your hook returns a non-zero value, the scan stops with the method returning the address of the object on which it stopped. If the hook always returns zero, all objects are scanned and the MM_SCAN method returns NULL.

An example of this method's usage could be the following:

<syntaxhighlight lang="C" line>
/* A simple function to count how many items a menu has, using MM_SCAN */

uint32 HookFunction(struct Hook *h, Object *o, struct MenuScanMessage *msg)
{
if (msg->Level == 1)
*((uint32 *)msg->Args[0]) += 1;
return (0);
}

uint32 CountMenuItems(Object *menuobj)
{
struct Hook hook;
uint32 count = 0;

memset(&hook,0,sizeof(struct Hook));

hook.h_Entry = (HOOKFUNC)HookFunction;

IIntuition->IDoMethod(menuobj,MM_SCAN,0,&hook,&count,0,0,0);

return (count);
}
</syntaxhighlight>

In this example we pass as the only custom argument the address of an variable which, once the MM_SCAN method returns, will hold the amount of children of the specified menu object. In the hook function we check that the object's level is 1, to make sure we only take it into account if it is a direct child of a menu (menus have a level of zero), rather than being a sub-item of an item, or even the menu object itself on which the method is invoked.

== Generating a whole menu (sub-)tree from a single tag list ==

So far we have only seen menu trees built by way of a series of nested calls to NewObject(). This is certainly a working approach to putting together a tree of BOOPSI objects organized in a hierarchy. Still, it presents a few drawbacks:

* It can consume a significant amount of stack with very deep trees;
* It may produce code which is hard to read unless special macros are used;
* It makes error checking not very easy.

All in all, nesting NewObject() calls is quite acceptable with relatively small menu trees, while it can become less manageable as the tree's size grows.

A different technique for building menu trees, which attempts to overcome these issues, is provided by menuclass' MM_NEWMENU method. This allows to generate an entire tree, or a sub-tree, out of a flat description of its structure given in the form of a single tag list.

The MM_NEWMENU method uses the following message structure:

<syntaxhighlight lang="C" line>
struct mpNewMenu
{
uint32 MethodID;
uint32 mpnm_Reserved;
struct TagItem *mpnm_AttrList;
};
</syntaxhighlight>

where MethodID is MM_NEWMENU, mpnm_Reserved should always be set to zero, and mpnm_AttrList is the tag list describing the menu tree to be generated.

Said tag list is made up for the most part of the usual menuclass tags that are used to specify attributes of the individual objects; however, the menu objects themselves are introduced by special tags prepended with NM_ which are actually directives for the method.

MM_NEWMENU understands three directives: NM_Menu / NM_Item, indicating to add a new menu or item object at the current level (the tag data is the object's text label), and NM_SubItems, indicating to move down or up by one level before the next item object is added. If the tag data of NM_SubItems is SI_BEGIN, the next item will become a child of the most recent one added (i.e. we move down by one level); if it is SI_END, the next item will become a sibling of the most recent one's parent (i.e. we move up by one level).

{{Note|text=NM_SubItems is not needed to add menus to a menu strip object, nor to add items to a menu object -- its only purpose is to act as a "delimiter" for a list of sub-items of an item object.}}

Any menuclass tag that is encountered in the tag list is passed as an attribute to the most recently added object.

The method should be invoked on an existing menuclass object, which in case of success will become the new tree's root. MM_NEWMENU returns FALSE to indicate failure, the exact reasons for which can be inspected through the MA_ErrorCode and MA_ErrorTagItem tags. See <intuition/menuclass.h> for a list of menuclass error codes and their explanation.

Here's a simple example to illustrate the method's usage:

<syntaxhighlight lang="C" line>
/* Service function allowing to pass varargs tag list to MM_NEWMENU
*/
static BOOL VARARGS68K DoNewMenu(Object *root, ...)
{
va_list ap;
struct TagItem *tags;
BOOL result;

va_startlinear(ap,root);
tags = (struct TagItem *)va_getlinearva(ap,struct TagItem *);
result = IIntuition->IDoMethod(root,MM_NEWMENU,0,tags);
va_end(ap);

return (result);
}

/* Build a menu tree with the MM_NEWMENU method
*/
Object *BuildMenuTree(void)
{
Object *menustripobj;
uint32 success, error;
struct TagItem *error_ti;

menustripobj = IIntuition->NewObject(NULL,"menuclass",MA_Type,T_ROOT,TAG_END);

if (menustripobj)
{
success = DoNewMenu(menustripobj,
MA_ErrorCode, &error,
MA_ErrorTagItem, &error_ti,
NM_Menu, "Project", MA_ID, MID_PROJECT,
NM_Item, "O|Open", MA_ID, MID_OPEN,
NM_Item, "S|Save", MA_ID, MID_SAVE,
NM_Item, "A|Save as...", MA_ID, MID_SAVEAS,
NM_Item, ML_SEPARATOR,
NM_Item, "Q|Quit", MA_ID, MID_QUIT,
NM_Menu, "Options", MA_ID, MID_OPTIONS,
NM_Item, "F|Font...", MA_ID, MID_FONT,
NM_Item, "Style", MA_ID, MID_STYLE,
NM_SubItems, SI_BEGIN,
NM_Item, "B|Bold", MA_ID, MID_BOLD, MA_Toggle, TRUE,
NM_Item, "I|Italic", MA_ID, MID_ITALIC, MA_Toggle, TRUE,
NM_Item, "U|Underline", MA_ID, MID_UNDERLINE, MA_Toggle, TRUE,
NM_SubItems, SI_END,
NM_Item, "W|Word wrap", MA_ID, MID_WORDWRAP, MA_Toggle, TRUE,
TAG_END);

if (!success)
{
IDOS->Printf("Failed with error %ld, at tag %08lX\n",error,error_ti->ti_Tag);
IIntuition->IDoMethod(menustripobj,MM_DELETEMENU,0);
IIntuition->DisposeObject(menustripobj);
menustripobj = NULL;
}
}

return (menustripobj);
}
</syntaxhighlight>

In this example we make use of a small service function to pass the tag list on the stack as varargs; of course the tag list can also be allocated statically. Also, the above tree is rather small for the sake of keeping the example short, so it does not benefit much from using MM_NEWMENU instead of nested NewObject() calls, but obviously the same technique can be used to build trees of any size.

As you can see, with MM_NEWMENU you can write compact and quite readable code to describe your menu trees, without having to resort to using macros on top of nested calls. The tree's description can even be made somewhat reminiscent of traditional NewMenu arrays as used with GadTools, which may look more familiar to long-time developers.

To free a menu (sub-)tree generated with MM_NEWMENU, you invoke MM_DELETEMENU on the root object. This method uses the following message structure:

<syntaxhighlight lang="C" line>
struct mpDeleteMenu
{
uint32 MethodID;
uint32 mpdm_Reserved;
};
</syntaxhighlight>

where MethodID is MM_DELETEMENU, and mpdm_Reserved should (as usual) be set to zero. Therefore, the correct way to invoke the method is the following:

<syntaxhighlight lang="C" line>
IIntuition->IDoMethod(menustripobj,MM_DELETEMENU,0);
</syntaxhighlight>

{{Note|text=This call only disposes of all of the object's children, not of the root object itself. This way you can reuse the object in case you need to build another menu tree with MM_NEWMENU. To free the root object (and its children if you didn't already do that), simply use DisposeObject().}}

Preferences

2025-01-26T19:36:36Z

Costel Mincea: Text replacement - "<syntaxhighlight>" to "<syntaxhighlight lang="C" line>"

{{WIP}}
== Preferences ==

To make the Amiga operating system easily configurable by the user, the OS comes with a family of editors and associated data files known collectively as Preferences. Preferences allows the user to set system-wide configuration options such as the printer driver to use, serial port baud rate and other items. To make an application appealing to the user, the system-wide Preferences settings should be respected as much as possible by applications. This article describes how to use the Preferences system in your programs.

== Preferences Editors and Storage ==

In AmigaOS there can be any number of Preferences editors each with its own separate configuration file covering a specific area. All these Preferences editors have the same look and feel. Using separate Preferences editors and configuration files allows for adding new Preferences items (and editors) in future versions of the OS.

Preferences are store in various ".prefs" files located in the "ENV:sys" and "ENVARC:sys" directories. Preferences options currently in use are located in "ENV:sys". Permanent, saved copies of Preferences files are stored in "ENVARC:sys". These are copied to "ENV:" on an as-needed basis. Applications may also store their own preference files in "ENV:" but should use a sub-directory for that purpose.

Currently the following Preferences editors and files are available:

{| class="wikitable"
|+ Preferences Editors
! Preferences Editor
! Preferences Configuration File
|-
| IControl
| icontrol.prefs
|-
| Input
| input.prefs
|-
| Palette
| palette.ilbm
|-
| Pointer
| pointer.ilbm
|-
| Printer
| printer.prefs
|-
| PrinterGfx
| printergfx.prefs
|-
| Overscan
| overscan.prefs
|-
| ScreenMode
| screenmode.prefs
|-
| Serial
| serial.prefs
|-
| -
| wbconfig.prefs
|-
| Font
| wbfont.prefs, sysfont.prefs and screenfont.prefs
|-
| Time
| -
|-
| WBPattern
| wb.pat and win.pat
|}

Each .prefs file is managed by editor with the same name, except for wbconfig.prefs, which is written directly by Workbench and has no editor. One Preferences editor has no .prefs file, Time. That Preferences editor writes directly to the battery backed clock.

When the user makes a change to a Preferences item with one of the editors, the changes will be saved in either "ENV:sys" or ''both'' "ENV:sys" and "ENVARC:sys" depending on whether the user saves the changes with the "Use" gadget or "Save" gadget of the Preferences editor.

The "Use" gadget is for making temporary changes and the new preferences will be stored only in "ENV:sys". If the user reboots, the old preferences will be restored from the permanent copy in "ENVARC:sys".

The "Save" gadget is for making permanent changes and the new preferences will be stored in both "ENV:sys" and "ENVARC:sys". That way, if the user reboots, the new preferences will still be in effect since the system looks in "ENVARC:sys" to find out what preferences should be set to at boot time.

=== The ENV: Directory and Notification ===

One advantage of the new Preferences system is file notification. File notification is a form of inter-process communication that allows an application to be automatically notified if a change is made to a specific file or directory. This makes it easy for the application to react to changes the user makes to Preferences files. See [[Notification]] for more complete information about the notification feature.

File notification is also used by the system itself. The Preferences control program, IPrefs, sets up notification on most of the Preferences files in "ENV:sys". If the user alters a Preferences item (normally this is done with a Preferences editor), the system will notify IPrefs about the change and IPrefs will attempt to alter the user's environment to reflect the change.

For example, if the user opens the ScreenMode Preferences editor and changes the Workbench screen mode to high-resolution, the new settings are saved in "screenmode.prefs" in the "ENV:sys" directory. IPrefs sets up notification on this file at boot time, so the file system will notify IPrefs of the change. IPrefs will read in the Screenmode.prefs file and reset the Workbench screen to high resolution mode.

Here's a short example showing how to set up notification on the "serial.prefs" file in "ENV:sys". The program displays a message in a window whenever this file is changed (e.g., when the user selects the "Use" or "Save" gadget in the Serial Preferences editor).

<syntaxhighlight lang="C" line>
/*
** prefnotify.c - notified if serial prefs change
*/
#include <exec/types.h>
#include <exec/memory.h>
#include <dos/dos.h>
#include <dos/notify.h>

#include <proto/exec.h>
#include <proto/dos.h>

#define PREFSFILENAME "ENV:sys/serial.prefs"

int main(int argc, char **argv)
{
/* Allocate a NotifyRequest structure */
struct NotifyRequest *notifyrequest = IExec->AllocMem(sizeof(struct NotifyRequest), MEMF_CLEAR);

if (notifyrequest != NULL)
{
/* And allocate a signalsbit */
int8 signum;
if ((signum = IExec->AllocSignal(-1L)) != -1)
{
/* Initialize notifcation request */
CONST_STRPTR filename = PREFSFILENAME;
notifyrequest->nr_Name = filename;
notifyrequest->nr_Flags = NRF_SEND_SIGNAL;
/* Signal this task */
notifyrequest->nr_stuff.nr_Signal.nr_Task = (struct Task *) IExec->FindTask(NULL);
/* with this signals bit */
notifyrequest->nr_stuff.nr_Signal.nr_SignalNum = signum;

if ((IDOS->StartNotify(notifyrequest)) == DOSTRUE)
{
IDOS->Printf("Select Serial Prefs SAVE or USE to notify this program\n");
IDOS->Printf("CTRL-C to exit\n\n");

BOOL done = FALSE;

/* Loop until Ctrl-C to exit */
while(!done)
{
uint32 signals = IExec->Wait( (1L << signum) | SIGBREAKF_CTRL_C );
if (signals & (1L << signum))
IDOS->Printf("Notification signal received.\n");

if (signals & SIGBREAKF_CTRL_C)
{
IDOS->EndNotify(notifyrequest);
done = TRUE;
}
}
}
else IDOS->Printf("Can't start notification\n");
IExec->FreeSignal(signum);
}
else IDOS->Printf("No signals available\n");

IExec->FreeMem(notifyrequest, sizeof(struct NotifyRequest));
}
else IDOS->Printf("Not enough memory for NotifyRequest.\n");

return 0;
}
</syntaxhighlight>

=== Preference File Format ===

To understand the format of Preferences files, you must be familiar with IFF file standard (see [[IFF_Standard|IFF Standard]] for the complete specification).

In general all Preferences files are stored in the IFF format with a type of PREF (see the exceptions noted below). Each file contains at least two Chunks, a header Chunk and a data Chunk.

==== The Header Chunk ====

The PRHD header chunk, contains a PrefHeader structure:

<syntaxhighlight lang="C" line>
struct PrefHeader
{
UBYTE ph_Version;
UBYTE ph_Type;
ULONG ph_Flags;
};
</syntaxhighlight>

Currently all the fields are set to NULL. In future revisions these fields may be used to indicate a particular version and contents of a PREF chunk.

==== The Data Chunk ====

The data Chunk that follows the header Chunk depends on the kind of Preferences data the file contains. The types of Preferences data Chunks that are currently part of the system are:

{| class="wikitable"
|+ IFF Chunk Types in Preferences Data Files
! Chunk Name
! Used With
|-
| FONT
| Fonts, used for all font Preferences files. In future the PrefHeader may indicate what the font is used for.
|-
| ICTL
| IControl
|-
| INPT
| Input
|-
| OSCN
| Overscan
|-
| PGFX
| PrinterGfx
|-
| PTXT
| PrinterText
|-
| SCRM
| ScreenMode
|-
| SERL
| Serial
|}

Each chunk contains a structure applicable to the type.

=== FONT ===

<syntaxhighlight lang="C" line>
struct FontPrefs
{
LONG fp_Reserved[4];
UBYTE fp_FrontPen; /* Textcolor */
UBYTE fp_BackPen; /* Character background color */
UBYTE fp_DrawMode;
struct TextAttr fp_TextAttr;
BYTE fp_Name[FONTNAMESIZE]; /* Font name */
};
</syntaxhighlight>

=== ICTL ===

<syntaxhighlight lang="C" line>
struct IControlPrefs
{
LONG ic_Reserved[4]; /* System reserved */
UWORD ic_TimeOut; /* Verify timeout */
WORD ic_MetaDrag; /* Meta drag mouse event */
ULONG ic_Flags; /* IControl flags (see below) */
UBYTE ic_WBtoFront; /* CKey: WB to front */
UBYTE ic_FrontToBack; /* CKey: front screen to back */
UBYTE ic_ReqTrue; /* CKey: Requester TRUE */
UBYTE ic_ReqFalse; /* CKey: Requester FALSE */
};
</syntaxhighlight>

The ic_Flags field can have the following values:

; ICF_COERCE_COLORS
: This indicates that a displaymode with a matching number of colors has preference over a correct aspect ration when screen coercing takes place.

; ICF_COERCE_LACE
: This indicates that choosing an interlaced display mode is allowed when coercing screens. Otherwise a non-interlaced display mode will be selected.

; ICF_STRGAD_FILTER
: This indicates that control characters should be filtered out of string gadget user input.

; ICF_MENUSNAP
: This indicates that an auto-scroll screen should be snapped back to origin when the mouse menu-button is selected.

Note that the command key values in the last four fields of the IControlPrefs structure are ANSI codes, not RAWKEY codes.

=== INPT ===

<syntaxhighlight lang="C" line>
struct InputPrefs
{
LONG ip_Reserved[4];
UWORD ip_PointerTicks; /* Sensitivity of the pointer */
struct timeval ip_DoubleClick; /* Interval between clicks */
struct timeval ip_KeyRptDelay; /* keyboard repeat delay */
struct timeval ip_KeyRptSpeed; /* Keyboard repeat speed */
WORD ip_MouseAccel; /* Mouse acceleration */
};
</syntaxhighlight>

=== OSCN ===

<syntaxhighlight lang="C" line>
struct OverscanPrefs
{
ULONG os_Reserved[4];
ULONG os_DisplayID; /* Displaymode ID */
Point os_ViewPos; /* View X/Y Offset */
Point os_Text; /* TEXT overscan dimension */
struct Rectangle os_Standard; /* STANDARD overscan dimension */
};
</syntaxhighlight>

=== PGFX ===

<syntaxhighlight lang="C" line>
struct PrinterGfxPrefs
{
LONG pg_Reserved[4];
UWORD pg_Aspect; /* Horizontal or vertical */
UWORD pg_Shade; /* B&W, Greyscale, Color */
UWORD pg_Image; /* Positive or negative image */
WORD pg_Threshold; /* Black threshold */
UBYTE pg_ColorCorrect; /* RGB color correction */
UBYTE pg_Dimensions; /* Dimension type */
UBYTE pg_Dithering; /* Type of dithering */
UWORD pg_GraphicFlags; /* Rastport dump flags */
UBYTE pg_PrintDensity; /* Print density 1 - 7 */
UWORD pg_PrintMaxWidth; /* Maximum width */
UWORD pg_PrintMaxHeight; /* Maximum height */
UBYTE pg_PrintXOffset; /* X Offset */
UBYTE pg_PrintYOffset; /* Y Offset */
};
</syntaxhighlight>

The possible values of each field are defined in <prefs/printergfx.h>. Note that your application is responsible for checking if the supplied values are valid.

=== PTXT ===

<syntaxhighlight lang="C" line>
struct PrinterTxtPrefs
{
LONG pt_Reserved[4]; /* System reserved */
UBYTE pt_Driver[DRIVERNAMESIZE]; /* printer driver filename */
UBYTE pt_Port; /* printer port connection */

UWORD pt_PaperType; /* Fanfold or single */
UWORD pt_PaperSize; /* Standard, Legal, A4, A3 etc. */
UWORD pt_PaperLength; /* Paper length in # of lines */

UWORD pt_Pitch; /* Pica or Elite */
UWORD pt_Spacing; /* 6 or 8 LPI */
UWORD pt_LeftMargin; /* Left margin */
UWORD pt_RightMargin; /* Right margin */
UWORD pt_Quality; /* Draft or Letter */
};
</syntaxhighlight>

=== SCRM ===

<syntaxhighlight lang="C" line>
struct ScreenModePrefs
{
ULONG sm_Reserved[4];
ULONG sm_DisplayID; /* Displaymode ID */
UWORD sm_Width; /* Screen width */
UWORD sm_Height; /* Screen height */
UWORD sm_Depth; /* Screen depth */
UWORD sm_Control; /* BIT 0, Autoscroll yes/no */
};
</syntaxhighlight>

=== SERL ===

<syntaxhighlight lang="C" line>
struct SerialPrefs
{
LONG sp_Reserved[4]; /* System reserved */
ULONG sp_BaudRate; /* Baud rate */

ULONG sp_InputBuffer; /* Input buffer: 0 - 64K */
ULONG sp_OutputBuffer; /* Future: Output: 0 - 64K, def 0 */

UBYTE sp_InputHandshake; /* Input handshaking */
UBYTE sp_OutputHandshake; /* Future: Output handshaking */

UBYTE sp_Parity; /* Parity */
UBYTE sp_BitsPerChar; /* I/O bits per character */
UBYTE sp_StopBits; /* Stop bits */
};
</syntaxhighlight>

=== Other Preferences File Formats ===

Not every Preferences file is stored as an IFF file of type PREF. The palette.ilbm and pointer.ilbm files contain a regular ILBM FORM to store their imagery. The win.pat and wb.pat files use a raw format with 16 bytes reserved, followed by a WORD giving the total size of the pattern, a WORD giving the bitplane count, and byte arrays (currently 32 bytes) for each bitplane. The format of the wbconfig.prefs file is private.

=== Reading a Preferences File ===

The following example shows a way to read a Preferences file.

<syntaxhighlight lang="C" line>
/*
** showprefs.c - parse and show some info from an IFF Preferences file
**
*/

#include <exec/types.h>
#include <dos/dos.h>
#include <libraries/dos.h>
#include <libraries/iffparse.h>
#include <prefs/prefhdr.h>
#include <prefs/font.h>
#include <prefs/icontrol.h>
#include <prefs/input.h>
#include <prefs/overscan.h>
#include <prefs/printergfx.h>
#include <prefs/printertxt.h>
#include <prefs/screenmode.h>
#include <prefs/serial.h>

#include <proto/exec.h>
#include <proto/dos.h>
#include <proto/iffparse.h>

struct IFFParseIFace *IIFF;

static uint8 *IFFErrTxt[] = {
"EOF", /* (end of file, not an error) */
"EOC", /* (end of context, not an error) */
"no lexical scope",
"insufficient memory",
"stream read error",
"stream write error",
"stream seek error",
"file corrupt",
"IFF syntax error",
"not an IFF file",
"required call-back hook missing",
NULL, /* (return to client, never shown) */
};

int main()
{
struct RDArgs *readargs;
int32 rargs[2];
struct IFFHandle *iffhandle;
struct ContextNode *cnode;
struct StoredProperty *hdrsp;
struct StoredProperty *sp;
uint8 *filename;
int32 ifferror, error = 0, rc = RETURN_OK;

struct Library *IFFParseBase = IExec->OpenLibrary ("iffparse.library", 50);
IIFF = (struct IFFParseIFace*)IExec->GetInterface(IFFParseBase, "main", 1, NULL);

if (IIFF != NULL) {
if (readargs = IDOS->ReadArgs("FILE/A", rargs, NULL)) {

/* Test later if valid */
filename = (uint8 *)rargs[0];

/* allocate an IFF handle */
if (iffhandle = IIFF->AllocIFF()) {
/* Open the file for reading */
if (iffhandle->iff_Stream = (int32)IDOS->Open(filename, MODE_OLDFILE)) {
/* initialize the iff handle */
IIFF->InitIFFasDOS (iffhandle);
if ((ifferror = IIFF->OpenIFF (iffhandle, IFFF_READ)) == 0) {
IIFF->PropChunk(iffhandle, ID_PREF, ID_PRHD);

IIFF->PropChunk(iffhandle, ID_PREF, ID_FONT);
IIFF->PropChunk(iffhandle, ID_PREF, ID_ICTL);
IIFF->PropChunk(iffhandle, ID_PREF, ID_INPT);
IIFF->PropChunk(iffhandle, ID_PREF, ID_OSCN);
IIFF->PropChunk(iffhandle, ID_PREF, ID_PGFX);
IIFF->PropChunk(iffhandle, ID_PREF, ID_PTXT);
IIFF->PropChunk(iffhandle, ID_PREF, ID_SCRM);
IIFF->PropChunk(iffhandle, ID_PREF, ID_SERL);

for (;;) {
ifferror = IIFF->ParseIFF(iffhandle, IFFPARSE_STEP);

if (ifferror == IFFERR_EOC)
continue;
else if (ifferror)
break;

/* Do nothing is this is a PrefHeader chunk,
* we'll pop it later when there is a pref
* chunk.
*/
if (cnode = IIFF->CurrentChunk(iffhandle))
if (cnode->cn_ID == ID_PRHD || cnode->cn_ID == ID_FORM)
continue;

/* Get the preferences header, stored previously */
hdrsp = IIFF->FindProp(iffhandle, ID_PREF, ID_PRHD);

if (sp = IIFF->FindProp(iffhandle, ID_PREF, ID_FONT)) {
IDOS->Printf("FrontPen: %ld\n",
((struct FontPrefs *)sp->sp_Data)->fp_FrontPen);
IDOS->Printf("BackPen: %ld\n",
((struct FontPrefs *)sp->sp_Data)->fp_BackPen);
IDOS->Printf("DrawMode: %ld\n",
((struct FontPrefs *)sp->sp_Data)->fp_DrawMode);
IDOS->Printf("Font: %s\n",
(LONG)((struct FontPrefs *)sp->sp_Data)->fp_Name);
IDOS->Printf("ta_YSize: %ld\n",
((struct FontPrefs *)sp->sp_Data)->fp_TextAttr.ta_YSize);
IDOS->Printf("ta_Style: %ld\n",
((struct FontPrefs *)sp->sp_Data)->fp_TextAttr.ta_Style);
IDOS->Printf("ta_Flags: %ld\n",
((struct FontPrefs *)sp->sp_Data)->fp_TextAttr.ta_Flags);
} else if (sp = FindProp(iffhandle, ID_PREF, ID_ICTL)) {
IDOS->Printf("TimeOut: %ld\n",
((struct IControlPrefs *)sp->sp_Data)->ic_TimeOut);
IDOS->Printf("MetaDrag: %ld\n",
((struct IControlPrefs *)sp->sp_Data)->ic_MetaDrag);
IDOS->Printf("WBtoFront: %ld\n",
((struct IControlPrefs *)sp->sp_Data)->ic_WBtoFront);
IDOS->Printf("FrontToBack: %ld\n",
((struct IControlPrefs *)sp->sp_Data)->ic_FrontToBack);
IDOS->Printf("ReqTrue: %ld\n",
((struct IControlPrefs *)sp->sp_Data)->ic_ReqTrue);
IDOS->Printf("ReqFalse: %ld\n",
((struct IControlPrefs *)sp->sp_Data)->ic_ReqFalse);
/* etc */
} else if (sp = IIFF->FindProp(iffhandle, ID_PREF, ID_INPT)) {
IDOS->Printf("PointerTicks: %ld\n",
((struct InputPrefs *)sp->sp_Data)->ip_PointerTicks);
IDOS->Printf("DoubleClick/Secs: %ld\n",
((struct InputPrefs *)sp->sp_Data)->ip_DoubleClick.tv_secs);
IDOS->Printf("DoubleClick/Micro: %ld\n",
((struct InputPrefs *)sp->sp_Data)->ip_DoubleClick.tv_micro);
/* etc */
} else if (sp = IIFF->FindProp(iffhandle, ID_PREF, ID_OSCN)) {
IDOS->Printf("DisplayID: 0x%lx\n",
((struct OverscanPrefs *)sp->sp_Data)->os_DisplayID);
/* etc */
} else if (sp = IIFF->FindProp(iffhandle, ID_PREF, ID_PGFX)) {
IDOS->Printf("Aspect: %ld\n",
((struct PrinterGfxPrefs *)sp->sp_Data)->pg_Aspect);
/* etc */
} else if (sp = IIFF->FindProp(iffhandle, ID_PREF, ID_PTXT)) {
IDOS->Printf("Driver: %s\n",
(LONG)((struct PrinterTxtPrefs *)sp->sp_Data)->pt_Driver);
/* etc */
} else if (sp = IIFF->FindProp(iffhandle, ID_PREF, ID_SCRM)) {
IDOS->Printf("DisplayID: 0x%lx\n",
((struct ScreenModePrefs *)sp->sp_Data)->sm_DisplayID);
/* etc */
} else if (sp = IIFF->FindProp(iffhandle, ID_PREF, ID_SERL)) {
IDOS->Printf("BaudRate: %ld\n",
((struct SerialPrefs *)sp->sp_Data)->sp_BaudRate);
/* etc */
}
}

IIFF->CloseIFF(iffhandle);
}

if (ifferror != IFFERR_EOF) {
rargs[1] = (LONG)IFFErrTxt[-ifferror - 1];
IDOS->VFPrintf(IDOS->Output(), "%s: %s\n", rargs);
rc = RETURN_FAIL;
}

IDOS->Close(iffhandle->iff_Stream);
} else
error = IoErr();

IIFF->FreeIFF(iffhandle);
} else {
IDOS->VFPrintf(Output(), "Can't allocate IFF handle\n", NULL);
rc = RETURN_FAIL;
}

IDOS->FreeArgs(readargs);
} else
error = IoErr();

IDOS->SetIoErr(error);
if (error) {
rc = RETURN_FAIL;
IDOS->PrintFault(error, filename);
}
} else {
rc = RETURN_FAIL;
}

IExec->DropInterface((struct Interface*)IIFF);
IExec->CloseLibrary(IFFParseBase);

return(rc);
}
</syntaxhighlight>

== Preferences in 1.3 and Older Versions of the OS ==

In 1.3, the Preferences program allows the user to see and change many system wide parameters, like the Workbench colors, pointer image, printer settings etc. When a Preferences item is changed, the new setting can be used temporarily (until a reset occurs) or stored permanently in the "DEVS:system-configuration" file. Under 1.3, all Preferences items are stored in this file which the system reads at boot time to find out how to set various system-wide options.

<syntaxhighlight lang="C" line>
struct Preferences *GetPrefs(struct Preferences *preferences, LONG size);
struct Preferences *GetDefPrefs(struct Preferences *preferences, LONG size);
struct Preferences *SetPrefs( struct Preferences *preferences, LONG size, BOOL inform );
</syntaxhighlight>

None of these functions should be used in any new programs. They are only present for backwards compatibility.

== Function Reference ==

The following are brief descriptions of the system functions that relate to the use of Preferences. See the SDK for details on each function call.

{| class="wikitable"
! Function
! Description
|-
| GetPrefs()
| Old 1.3 (V34) function for making a copy of the Preferences structure
|-
| SetPrefs()
| Old 1.3 (V34) function for overwriting Preferences with new data
|-
| GetDefPrefs()
| Old 1.3 (V34) function for copying default Preferences from ROM
|-
| StartNotify()
| DOS library function for monitoring a .prefs file for changes
|-
| EndNotify()
| Ends notification started with StartNotify()
|-
| AllocIFF()
| IFFParse library function that creates an IFFHandle for parsing
|-
| InitIFFasDOS()
| Initialize the IFFHandle as a DOS stream
|-
| OpenIFF()
| Initialize an IFFHandle for reading or writing a new stream
|-
| PropChunk()
| Specify a property chunk to store
|-
| ParseIFF()
| Parse an IFF file from the IFFHandle stream
|-
| CurrentChunk()
| Returns the top level context of an IFF stream
|-
| FindProp()
| Search for a property chunk previously declared with PropChunk()
|-
| CloseIFF()
| Closes an IFF context opened with OpenIFF()
|-
| FreeIFF()
| Frees the IFFHandle created with AllocIFF()
|}

Console Device

2025-01-26T19:36:02Z

Costel Mincea: Text replacement - "<syntaxhighlight>" to "<syntaxhighlight lang="C" line>"

[[Category:Devices|Console]]
== Console Device ==

The console device provides the text-oriented interface for Intuition windows. It acts like an enhanced ASCII terminal obeying many of the standard ANSI sequences as well as special sequences unique to the Amiga. The console device also provides a copy-and-paste facility and an internal character map to redraw a window when it is resized.

== Console Device Commands and Functions ==

{| class="wikitable"
! Command
! Command Operation
|-
| CD_ASKDEFAULTKEYMAP || Get the current default keymap.
|-
| CD_ASKKEYMAP || Get the current key map structure for this console.
|-
| CD_ASKKEYMAP_POINTERS || Get pointers to the current key map structures for this console. (V51.19)
|-
| CD_GETATTRS || Get attributes for this console. (V53)
|-
| CD_SETATTRS || Set attributes for this console. (V53)
|-
| CD_SETDEFAULTKEYMAP || Set the current default keymap.
|-
| CD_SETKEYMAP || Set the current key map structure for this console.
|-
| CD_SETKEYMAP_POINTERS || Set the current key map structures for the console. (V51.19)
|-
| CMD_CLEAR || Remove any reports waiting to satisfy read requests from the console input buffer.
|-
| CMD_READ || Read the next input, generally from the keyboard. The form of this input is as an ANSI byte stream.
|-
| CMD_WRITE || Write a text record to the display interpreting any ANSI control characters in the record.
|}

Console Device Functions:

{| class="wikitable"
| CDInputHandler() || Handle an input event for the console device.
|-
| RawKeyConvert() || Decode raw input classes and convert input events of type IECLASS_RAWKEY to ANSI bytes based on the keymap in use.
|}

== Device Interface ==

The console device operates like the other Amiga devices. To use it, you must first open the console device, then send I/O requests to it, and then close it when finished. See [[Exec_Device_I/O|Exec Device I/O]] for general information on device usage.

The I/O request used by the console device is called IOStdReq.

<syntaxhighlight lang="C" line>
struct IOStdReq
{
struct Message io_Message;
struct Device *io_Device; /* device node pointer */
struct Unit *io_Unit; /* unit (driver private)*/
UWORD io_Command; /* device command */
UBYTE io_Flags;
BYTE io_Error; /* error or warning num */
ULONG io_Actual; /* actual number of bytes transferred */
ULONG io_Length; /* requested number bytes transferred*/
APTR io_Data; /* points to data area */
ULONG io_Offset; /* offset for block structured devices */
};
</syntaxhighlight>

See the include file exec/io.h for the complete structure definition.

=== Console Device Units ===

The console device provides four units, three that require a console window and one that does not. The unit type is specified when you open the device. See the [[#Opening the Console Device|Opening the Console Device]] section below for more details.

The CONU_STANDARD unit (0) is generally used with a SMART_REFRESH window. This unit has the least amount of overhead (e.g., memory usage and rendering time), and is highly compatible with all versions of the operating system.

There are two variations of character mapped console units. Both must be used with SIMPLE_REFRESH windows and both have the ability to automatically redraw a console window when resized or revealed.

A character mapped console can be opened which allows the user to drag-select text with the mouse and '''Copy''' the highlighted area. The copied text can then be '''Paste'''d into other console windows or other windows which support reading data from the [[Clipboard_Device|clipboard device]].

Character mapped console units have more overhead than standard consoles (e.g., rendering times and memory usage).

The CONU_LIBRARY unit (-1) does not require a console window. It is designed to be primarily used with the console device functions and also with the console device commands that do not require a console window.

The Amiga uses the [http://www.ecma-international.org/publications/standards/Ecma-094.htm ECMA-94 Latin 1 International 8-bit] character set.

=== Opening the Console Device ===

Four primary steps are required to open the console device:

# Create a message port using AllocSysObject(ASOT_PORT). Reply messages from the device must be directed to a message port.
# Create an I/O request structure of type IOStdReq. The IOStdReq structure is created by the AllocSysObject(ASOT_IOREQUEST) function. AllocSysObject() will initialize your I/O request to point to your reply port.
# Open an Intuition window and set a pointer to it in the io_Data field of the IOStdReq and the size of the window in the io_Length field. This is the window to which the console will be attached. The window must be SIMPLE_REFRESH for use with the CONU_CHARMAP and CONU_SNIPMAP units.
# Open the console device. Call OpenDevice() passing it the I/O request and the type of console unit set in the unit and flags fields. Console unit types and flag values are listed below.

Console device units:

; CONU_LIBRARY
: Return the device library vector pointer used for calling console device functions. No console is opened.

; CONU_STANDARD
: Open a standard console.

; CONU_CHARMAP
: Open a console with a character map.

; CONU_SNIPMAP
: Open a console with a character map and copy-and-paste support.

; CONU_HISTORY (V53)
: Similar to CONU_SNIPMAP with content history and tabbed windows.

See the include file devices/conunit.h for the unit definitions and the SDK for an explanation of each unit.

{{Note|title=No Changes Required|text=CONU_STANDARD has a numeric value of zero to insure compatibility with pre-V36 applications. CONU_LIBRARY has a numeric value of negative one and is also compatible with pre-V36 applications.}}

Console device flags:

; CONFLAG_DEFAULT
: The console device will redraw the window when it is resized.

; CONFLAG_NODRAW_ON_NEWSIZE
: The console device will not redraw the window when it is resized

; CONFLAG_CREATE_WINDOW and CONFLAG_TABBED_WINDOW (V53)
: These bits define the combinations of window source, tabs and sharing. These are only applicable when using CONUNIT_HISTORY or greater.

; CONFLAG_SYNC_WRITES (V53)
: Forces a task issuing a Write request to wait until the request is complete before returning to the caller.

The character map units are the only units which use the flags parameter to set how the character map is used. CONU_STANDARD units ignore the flags parameter. See the console.doc autodoc for the most up to date information.

See the include file devices/conunit.h for the flag definitions and the SDK for an explanation of the flags.

<syntaxhighlight lang="C" line>
struct NewWindow nw =
{
10, 10, /* starting position (left,top) */
620,180, /* width, height */
-1,-1, /* detailpen, blockpen */
CLOSEWINDOW, /* flags for idcmp */
WINDOWDEPTH|WINDOWSIZING|
WINDOWDRAG|WINDOWCLOSE|
SIMPLE_REFRESH|ACTIVATE, /* window flags */
NULL, /* no user gadgets */
NULL, /* no user checkmark */
"Console Test", /* title */
NULL, /* pointer to window screen */
NULL, /* pointer to super bitmap */
100,45, /* min width, height */
640,200, /* max width, height */
WBENCHSCREEN /* open on workbench screen */
};

/* Create reply port console */
struct MsgPort *ConsoleMP = IExec->AllocSysObjectTags(ASOT_PORT,
ASOPORT_Name, "RKM.Console",
TAG_END);
if (ConsoleMP == NULL)
cleanexit("Can't create write port\n", RETURN_FAIL);

/* Create message block for device I/O */
struct IOStdReq *ConsIO = IExec->AllocSysObjectTags(ASOT_IOREQUEST,
ASOIOR_Size, sizeof(struct IOStdReq),
ASOIOR_ReplyPort, ConsoleMP,
TAG_END);
if (ConsIO == NULL)
cleanexit("Can't create IORequest\n", RETURN_FAIL);

/* Open a window --- we assume intuition.library is already open */
struct Window *win = IIntuition->OpenWindow(&nw);
if (win == NULL)
cleanexit("Can't open window\n",RETURN_FAIL);

/* Set window pointer and size in I/O request */
ConsIO->io_Data = (APTR) win;
ConsIO->io_Length = sizeof(struct Window);

/* Open the console device */
if (error = IExec->OpenDevice("console.device", CONU_CHARMAP, ConsIO, CONFLAG_DEFAULT))
cleanexit("Can't open console.device\n",RETURN_FAIL);
</syntaxhighlight>

=== Closing the Console Device ===

Each OpenDevice() must eventually be matched by a call to CloseDevice().

All I/O requests must be complete before CloseDevice(). If any requests are still pending, abort them with AbortIO().

<syntaxhighlight lang="C" line>
if (!(IExec->CheckIO(ConsIO)))
IExec->AbortIO(ConsIO); /* Ask device to abort any pending requests */

IExec->WaitIO(ConsIO); /* Wait for abort, then clean up */
IExec->CloseDevice(ConsIO); /* Close console device */
</syntaxhighlight>

== About Console I/O ==

The console device may be thought of as a kind of terminal. You send character streams to the console device; you also receive them from the console device. These streams may be characters, control sequences or a combination of the two.

Console I/O is closely associated with the Amiga Intuition interface; a console must be tied to a window that is already opened. From the Window data structure, the console device determines how many characters it can display on a line and how many lines of text it can display in a window without clipping at any edge.

You can open the console device many times, if you wish. The result of each open call is a new console unit. AmigaDOS and Intuition see to it that only one window is currently active and its console, if any, is the only one (with a few exceptions) that receives notification of input events, such as keystrokes. Later in this article you will see that other Intuition events can be sensed by the console device as well.

{{Note|title=Introducing...|text=For this entire article the characters <CSI> represent the ''control sequence introducer''. For output you may use either the two-character sequence <Esc>[ (0x1B 0x5B) or the one-byte value 0x9B. For input you will receive 0x9B unless the sequence has been typed by the user.}}

=== Exec Functions and the Console Device ===

The various Exec functions such as DoIO(), SendIO(), AbortIO() and CheckIO() operate normally. The only caveats are that CMD_WRITE may cause your application to wait internally, even with SendIO(), and a task using CMD_READ to wait on a response from a console is at the user’s mercy. If the user never reselects that window, and the console response provides the only wake-up call, that task will sleep forever.

=== General Console Screen Output ===

Console character screen output (as compared to console command sequence transmission) outputs all standard printable characters (character values hex 20 through 7E and A0 through FF) normally.

Many control characters such as '''Backspace''' (0x08) and '''Return''' (0x0D) are translated into their exact ANSI equivalent actions. The '''Line feed''' character (0x0A) is a bit different in that it can be translated into a '''Return/Line feed''' action. The net effect is that the cursor moves to the first column of the next line whenever an <LF> is displayed. This option is set via the mode control sequences discussed under “Control Sequences for Window Output.”

=== Console Keyboard Input ===

If you read from the console device, the keyboard inputs are preprocessed for you and you will get ASCII characters, such as “B.” Most normal text-gathering programs will read from the console device in this manner. Some programs may also ask to receive raw events in their console stream. Keypresses are converted to ASCII characters or CSI sequences via the keymap associated with the unit.

== Writing to the Console Device ==

You write to the console device by passing an I/O request to the device with a pointer to the write buffer set in io_Data, the number of bytes in the buffer set in io_Length and CMD_WRITE set in io_Command.

<syntaxhighlight lang="C" line>
CONST_STRPTR outstring= "Make it so";

ConsIO->io_Data = outstring;
ConsIO->io_Length = IUtility->Strlen(outstring);
ConsIO->io_Command = CMD_WRITE;
IExec->DoIO(ConsIO);
</syntaxhighlight>

You may also send NULL-terminated strings to the console device in the same manner except that io_Length must be set to -1.

<syntaxhighlight lang="C" line>
ConsIO->io_Data = "\033[3mOh boy.";
ConsIO->io_Length = -1;
ConsIO->io_Command = CMD_WRITE;
IExec->DoIO(ConsIO);
</syntaxhighlight>

The fragment above will output the string “Oh boy.” in italics. Keep in mind that setting the text rendition to italics will remain in effect until you specifically instruct the console device to change it to another text style.

=== Synchronized Writes ===

Synchronized writes were the only option for Console Device before version 53.38. Returning from the Write call means that the data has been transferred from the caller's buffer and the IORequest structure contents are no longer required. The data may not yet have been written to the display and any effects caused by the data (e.g. change of cursor position) may not yet have started or been completed.

If the Console was opened in legacy mode (no TABBED or HISTORY options), then the SYNCWRITES option is forced for greater compatibility with older applications. Otherwise, the Console is opened with synchronized writes disabled. This enables the application to continue to do work while the Console works in parallel.

You can still force the Write operation to block until completed by opening the Console with the CONFLAG_SYNC_WRITES set or (for a Shell) including the option SYNCWRITES in the command line.

If you do not want to wait for all Write requests, you can set the IOF_WAIT_WRITE bit in the io_Flags byte before calling CMD_WRITE. This flag bit has the same effect as opening the console with the CONFLAG_SYNC_WRITES set, but its scope is limited to the current IORequest.

=== Control Sequences for Window Output ===

The following table lists functions that the console device supports, along with the character stream that you must send to the console to produce the effect. For more information on the control sequences, consult the console.doc in the SDK. The table uses the second form of <CSI>, that is, the hex value 0x9B, to minimize the number of characters to be transmitted to produce a function.

A couple of notes about the table. If an item is enclosed in square brackets, it is optional and may be omitted. For example, for '''Insert [N] Characters''' the value for ''N'' is shown as optional. The console device responds to such optional items by treating the value of ''N'' as 1 if it is not specified. The value of ''N'' or ''M'' is always a decimal number, having one or more ASCII digits to express its value.

{| class="wikitable"
|+ ANSI Console Control Sequences
! Console Command
! Comment
! Sequence of Characters (in Hexadecimal Form)
|-
| Bell || Flash the display—do an Intuition DisplayBeep() || 07
|-
| Backspace || Move left one column || 08
|-
| Horizontal Tab || Move right one tab stop || 09
|-
| Line Feed || Move down one text line as specified by the mode function || 0A
|-
| Vertical Tab || Move up one text line || 0B
|-
| Form Feed || Clear the console’s window || 0C
|-
| Carriage Return || Move to first column || 0D
|-
| Shift In || Undo Shift Out || OE
|-
| Shift Out || Set MSB of each character before displaying || 0F
|-
| Esc || Escape can be part of the control sequence introducer || 1B
|-
| Index || Move the active position down one line || 84
|-
| Next Line || Go to the beginning of the next line || 85
|-
| Horizontal Tabulation || Set a tab at the active cursor position || 88
|-
| Reverse Index || Move the active position up one line || 8D
|-
| CSI || Control sequence introducer || 9B
|-
| Reset to Initial State || || 1B 63
|-
| Insert [N] Characters || Insert one or more spaces, shifting the remainder of the line to the right || 9B [N] 40
|-
| Cursor Up [N] Character Positions || (default = 1) || 9B [N] 41
|-
| Cursor Down [N] Character Positions || (default = 1) || 9B [N] 42
|-
| Cursor Forward [N] Character Positions || (default = 1) || 9B [N] 43
|-
| Cursor Backward [N] Character Positions || (default = 1) || 9B [N] 44
|-
| Cursor Position || Where ''N'' is row, ''M'' is column, and semicolon (hex 3B) must be present as a separator, or if row is left out, so the console device can tell that the number after the semicolon actually represents the column number || 9B [N] [3B M] 48
|-
| Cursor Horizontal Tabulation || move cursor forward to ''N''th tab position || 9B [N] 49
|-
| Cursor Next Line [N] || (to column 1) || 9B [N] 45
|-
| Cursor Preceding Line [N] || (to column 1) || 9B [N] 46
|-
| Erase in Display || (only to end of display) || 9B 4A
|-
| Erase in Line || (only to end of line) || 9B 4B
|-
| Insert Line || Above the line containing the cursor || 9B 4C
|-
| Delete Line || Remove current line, move all lines up one position to fill gap, blank bottom line || 9B 4D
|-
| Delete Character [N] || That cursor is sitting on and to the right if [N] is specified || 9B [N] 50
|-
| Scroll up [N] Lines || Remove line(s) from top of window, move all other lines up, blanks [N] bottom lines || 9B [N] 53
|-
| Scroll down [N] Lines || Remove line(s) from bottom of window, move all other lines down, blanks [N] top lines || 9B [N] 54
|-
| Cursor Tabulation Control || where ''N''=0 set tab, ''N''=2 clear tab, ''N''=5 clear all tabs || 9B [N] 57
|-
| Cursor Backward Tabulation || move cursor backward to ''N''th tab position || 9B [N] 5A
|-
| Set Line Feed Mode || Cause '''Line Feed''' to respond as Return-Line Feed || 9B 32 30 68
|-
| Reset Newline Mode || Cause '''Line Feed''' to respond only as Line Feed || 9B 32 30 6C
|-
| Device Status Report || Cause console device to insert a '''Cursor''' Position Report into your read stream; see “Reading from the Console Device” for more information || 9B 36 6E
|-
| Select Graphic Rendition || Select text style (K), character color (L), character cell color (M), background color (N). See note below. || 9B K 3B 3L 3B 4M 3B >N 6D
|}

For '''Select Graphic Rendition''', any number of parameters, in any order, are valid. They are separated by semicolons. The parameters follow:

{| class="wikitable"
| 0 || Plain text
|-
| 1 || Boldface
|-
| 2 || faint (secondary color)
|-
| 3 || Italic
|-
| 4 || Underscore
|-
| 5 || Set slow character blink (V53.5)
|-
| 6 || Set fast character blink (V53.5)
|-
| 7 || Reversed character/cell colors
|-
| 8 || Concealed mode
|-
| 22 || Normal color, not bold (V36)
|-
| 23 || Italic off (V36)
|-
| 24 || Underscore off (V36)
|-
| 25 || Slow blink off (V53.5)
|-
| 26 || Fast blink off (V53.5)
|-
| 27 || Reversed off (V36)
|-
| 28 || Concealed off (V36)
|-
| 29 || Strike-through off (V53.5)
|}

{| class="wikitable"
| 30–37 || System colors 0–7 for character color.
|-
| 39 || Reset to default character color
|}

{| class="wikitable"
|+ Transmitted as two ASCII characters.
| 40–47 || System colors 0–7 for character cell color.
|-
| 39 || Reset to default character color
|}

{| class="wikitable"
|+ Transmitted as two ASCII characters
| >0–7 || System colors 0–7 for background color. (V36)
|}

You must specify the “>” in order for this to be recognized and it must be the last parameter.

For example, to select bold face, with color 3 as the character color, and color 0 as the character cell color and the background color, send the hex sequence:

<pre>9B 31 3B 33 33 3B 34 30 3B 3E 30 6D</pre>
representing the ASCII sequence:

<pre><CSI>1;33;40;>0m</pre>
where <CSI> is the control sequence introducer, here used as the single character value 0x9B.

{{Note|title=Go Easy On The Eyes|text=In most cases, the character cell color and the background color should be the same.}}

==== Set Graphic Rendition Implementation Notes ====

The sequences in the next table are not ANSI standard sequences, they are private Amiga sequences. In these command descriptions, length, width, and offset are comprised of one or more ASCII digits, defining a decimal value.

{| class="wikitable"
|+ Amiga Console Control Sequences
! Console Command
! Comment
! Sequence of Characters (in Hexadecimal Form)
|-
| Enable Scroll || (this is the default) || 9B 3E 31 68
|-
| Disable Scroll || || 9B 3E 31 6C
|-
| Autowrap On || (the default) || 9B 3F 37 68
|-
| Autowrap Off || || 9B 3F 37 6C
|-
| Set Page Length || In character raster lines, causes console to recalculate, using current font, how many text lines will fit on the page || 9B <length> 74
|-
| Set Line Length || In character positions, using current font, how many characters should be placed on each line
|| 9B <width> 75
|-
| Set Left Offset || In raster columns, how far from the left of the window should the text begin || 9B <offset> 78
|-
| Set Top Offset || In raster lines, how far from the top of the window’s RastPort should the topmost line of the character begin || 9B <offset> 79
|-
| Set Raw Events || Set the raw input events that will trigger an '''Input Event Report'''. see the “Selecting Raw Input Events” section below for more details. || 9B <events> 7B
|-
| Input Event Report || Returned by the console device in response to a raw event set by the '''Set Raw Event''' sequence. See the “Input Event Reports” section below for more details. || 9B <parameters> 7C
|-
| Reset Raw Events || Reset the raw events set by the '''Set Raw Event''' sequence. see the “Selecting Raw Input Events” section below. || 9B <events> 7D
|-
| Special Key Report || Returned by the console device whenever '''Help''', or one of the function keys or arrow keys is pressed. Some sequences do not end with 7E || 9B <keyvalue> 7E
|-
| Set Cursor Rendition || Make the cursor visible or invisible; turning off the cursor increases text output speed || 9B N 20 70 Invisible = 9B 30 20 70 Visible = 9B 20 70
|-
| Window Status Request || Ask the console device to tell you the current bounds of the window, in upper and lower row and column character positions. User may have resized or repositioned it. See “Window Bounds Report” below. || 9B 30 20 71
|-
| Window Bounds Report || Returned by the console device in response to a '''Window Status Request''' sequence || 9B 31 3B 31 3B <bottom margin> 3B <right margin> 72
|-
| Right ‘Amiga V’ Press || Returned by the console device when the user presses '''Right-Amiga-V'''. See the “Copy and Paste Support” section below for more details. || 9B 30 20 76
|}

{{Note|title=Give Back What You Take|text=The console device normally handles the '''Set Page Length''', '''Set Line Length''', '''Set Left Offset''', and '''Set Top Offset''' functions automatically. To allow it to do so again after setting your own values, send the functions without a parameter.}}

=== Example Console Control Sequences ===

{| class="wikitable"
| Move cursor right by 1 || <CSI>C or <CSI>1C || 9B 43 9B 31 43
|-
| Move cursor right by 20 || <CSI>20C || 9B 32 30 43
|-
| Move cursor to upper-left corner (Home Position) || <CSI>H or <CSI>1;1H or <CSI>;1H or <CSI>1;H || 9B 48 9B 31 3B 31 48 9B 3B 31 48 9B 31 3B 48
|-
| Move cursor to the fourth column of the first line of the window || <CSI>1;4H or <CSI>;4H || 9B 31 3B 34 48 9B 3B 34 48
|-
| Clear the window || <FF> or Ctrl-L (clear window) or <CSI>H<CSI>J (home and clear to end of window) || 0C 9B 48 9B 4A
|}

== Reading from the Console Device ==

Reading input from the console device returns an ANSI 3.64 standard byte stream. This stream may contain normal characters and/or raw input event information. You may also request other raw input events using the '''Set Raw Events''' and '''Reset Raw Events''' control sequences discussed below. See “Selection of Raw Input Events.”

Generally, console reads are performed asynchronously so that your program can respond to other events and other user input (such as menu selections) when the user is not typing on the keyboard. To perform asynchronous I/O, an I/O request is sent to the console using the SendIO() function (rather than a synchronous DoIO() which would wait until the read request returned with a character).

You read from the console device by passing an I/O request to the device with a pointer to the read buffer set in io_Data, the number of bytes in the buffer set in io_Length and CMD_READ set in io_Command.

<syntaxhighlight lang="C" line>
#define READ_BUFFER_SIZE 25
char ConsoleReadBuffer[READ_BUFFER_SIZE];

ConsIO->io_Data = (APTR)ConsoleReadBuffer;
ConsIO->io_Length = READ_BUFFER_SIZE;
ConsIO->io_Command = CMD_READ;
IExec->SendIO(ConsIO);
</syntaxhighlight>

{{Note|title=You May Get Less Than You Bargained For|text=A request for more than one character may be satisfied by the receipt of only one character. If you request more than one character, you will have to examine the io_Actual field of the request when it returns to determine how many characters you have actually received.}}

After sending the read request, your program can wait on a combination of signal bits including that of the reply port you created. The following fragment demonstrates waiting on both a queued console read request, and Window IDCMP messages:

<syntaxhighlight lang="C" line>
uint32 conreadsig = 1 << ConsoleMP->mp_SigBit;
uint32 windowsig = 1 << win->UserPort->mp_SigBit;

/* A character, or an IDCMP msg, or both will wake us up */
ULONG signals = IExec->Wait(conreadsig | windowsig);

if (signals & conreadsig)
{
/* Then check for a character */
};

if (signals & windowsig)
{
/* Then check window messages */
};
</syntaxhighlight>

=== Information About the Input Stream ===

For the most part, keys whose keycaps are labeled with ANSI-standard characters will ordinarily be translated into their ASCII-equivalent character by the console device through the use of its keymap. Keymap information can be found in [[Keymap_Library|Keymap Library]].

For keys other than those with normal ASCII equivalents, an escape sequence is generated and inserted into your input stream. For example, in the default state (no raw input events selected) the function, arrow and special keys (reserved for 101 key keyboards) will cause the sequences shown in the next table to be inserted in the input stream.

{| class="wikitable"
|+ Special Key Report Sequences
! Key
! Unshifted Sends
! Shifted Sends
! Comment
|-
| F1 || <CSI>0 || <CSI>10 ||
|-
| F2 || <CSI>1 || <CSI>11 ||
|-
| F3 || <CSI>2 || <CSI>12 ||
|-
| F4 || <CSI>3 || <CSI>13 ||
|-
| F5 || <CSI>4 || <CSI>14 ||
|-
| F6 || <CSI>5 || <CSI>15 ||
|-
| F7 || <CSI>6 || <CSI>16 ||
|-
| F8 || <CSI>7 || <CSI>17 ||
|-
| F9 || <CSI>8 || <CSI>18 ||
|-
| F10 || <CSI>9 || <CSI>19 ||
|-
| F11 || <CSI>20 || <CSI>30 || (101 key keyboard)
|-
| F12 || <CSI>21 || <CSI>31 || (101 key keyboard)
|-
| Help || <CSI>? || <CSI>? || (same sequence for both)
|-
| Insert || <CSI>40 || <CSI>50 || (101 key keyboard)
|-
| Page Up || <CSI>41 || <CSI>51 || (101 key keyboard)
|-
| Page Down || <CSI>42 || <CSI>52 || (101 key keyboard)
|-
| Pause/Break || <CSI>43 || <CSI>53 || (101 key keyboard)
|-
| Home || <CSI>44 || <CSI>54 || (101 key keyboard)
|-
| End || <CSI>45 || <CSI>55 || (101 key keyboard)
|-
| Cursor Up || <CSI>A || <CSI>T ||
|-
| Cursor Down || <CSI>B || <CSI>S ||
|-
| Cursor Left || <CSI>D || <CSI> A || (notice the space after <CSI>)
|-
| Cursor Right || <CSI>C || <CSI> @ || (notice the space after <CSI>)
|}

=== Cursor Position Report ===

If you have sent the '''Device Status Report''' command sequence, the console device returns a cursor position report into your input stream. It takes the form:

<pre>
<CSI><row>;<column>R
</pre>

For example, if the cursor is at column 40 and row 12, here are the ASCII values (in hex) you receive in a stream:

<pre>
9B 34 30 3B 31 32 52
</pre>

=== Window Bounds Report ===

A user may have either moved or resized the window to which your console is bound. By issuing a '''Window Status Report''' to the console, you can read the current position and size in the input stream. This window bounds report takes the following form:

<pre>
<CSI>1;1;<bottom margin>;<right margin> r
</pre>

The bottom and right margins give you the window row and column dimensions as well. For a window that holds 20 lines with 60 characters per line, you will receive the following in the input stream:

<pre>
9B 31 3B 31 3B 32 30 3B 36 30 20 72
</pre>

== Copy and Paste Support ==

As noted above, opening the console device with a unit of CONU_SNIPMAP allows the user to drag-select text with the mouse and copy the selection with '''Right-Amiga-C'''.

Internally, the snip is copied to a private buffer managed by the console device where it can be copied to other console device windows by pressing '''Right-Amiga-V'''.

However, your application should assume that the user is running the “Conclip” utility which is part of the standard Workbench 2.0 environment. Conclip copies snips from the console device to the clipboard device where they can be used by other applications which support reading from the clipboard.

When Conclip is running and the user presses '''Right-Amiga-V''', the console device puts an escape sequence in your read stream—<CSI>0 v (Hex 9B 30 20 76)—which tells you that the user wants to paste text from the clipboard.

Upon receipt of this sequence, your application should read the contents of the clipboard device, make a copy of any text found there and then release the clipboard so that it can be used by other applications. See [[Clipboard_Device|Clipboard Device]] for more information on reading data from it.

You paste what you read from the clipboard by using successive writes to the console. In order to avoid problems with excessively long data in the clipboard, you should limit the size of writes to something reasonable. (We define reasonable as no more than 1K per write with the ideal amount being 256 bytes.) You should also continue to monitor the console read stream for additional use input, paster requests and, possibly, '''Raw Input Events''' while you are doing this.

You should ''not'' open a character mapped console unit with COPY capability if you are unable to support '''Paste''' from the clipboard device. The user will reasonably expect to be able to '''Paste''' into windows from which a '''Copy''' can be done.

Keep in mind that users do make mistakes, so an '''Undo''' mechanism for aborting a '''Paste''' is highly desirable—particularly if the user has just accidentally pasted text into an application like a terminal program which is sending data at a slow rate.

{{Note|title=Use “CON:”, You’ll Be Glad You Did|text=It is highly recommended that you consider using the console-handler (CON:) if you want a console window with '''Copy''' and '''Paste''' capabilities. CON: provides you with free '''Paste''' support and is considerably easier to open and use than using the console device directly.}}

== Selecting Raw Input Events ==

If the keyboard information–including “cooked” keystrokes–does not give you enough information about input events, you can request additional information from the console driver.

The command to '''Set Raw Events''' is formatted as:

<pre>
<CSI>[event-types-separated-by-semicolons]{
</pre>

If, for example, you need to know when each key is pressed and released, you would request “Raw keyboard input.” This is done by writing <CSI>1<math>\{</math> to the console. In a single '''Set Raw Events''' request, you can ask the console to set up for multiple event types at one time. You must send multiple numeric parameters, separating them by semicolons (;). For example, to ask for gadget pressed, gadget released, and close gadget events, write:

<pre>
<CSI>7;8;11{
</pre>

You can reset, that is, delete from reporting, one or more of the raw input event types by using the '''Reset Raw Events''' command, in the same manner as the '''Set Raw Events''' was used to establish them in the first place. This command stream is formatted as:

<pre>
<CSI>[event-types-separated-by-semicolons]}
</pre>

So, for example, you could reset all of the events set in the above example by transmitting the command sequence:

<pre>
<CSI>7;8;11}
</pre>

{{Note|title=The Read Stream May Not Be Dry|text=There could still be pending '''Raw Input Events''' in your read stream after turning off one or more '''Raw Input Events'''.}}

The following table lists the valid raw input event types.

{| class="wikitable"
|+ Raw Input Event Types
! Request Number
! Request Description
|-
| 0 || No-op (used internally)
|-
| 1 || RAW keyboard input (Intuition swallows all except the select button)
|-
| 2 || RAW mouse input
|-
| 3 || Private Console Event
|-
| 4 || Pointer position
|-
| 5 || (unused)
|-
| 6 || Timer
|-
| 7 || Gadget pressed
|-
| 8 || Gadget released
|-
| 9 || Requester activity
|-
| 10 || Menu numbers
|-
| 11 || Close Gadget
|-
| 12 || Window resized
|-
| 13 || Window refreshed
|-
| 14 || Preferences changed
|-
| 15 || Disk removed
|-
| 16 || Disk inserted
|-
| 17 || Active window
|-
| 18 || Inactive window
|-
| 19 || New pointer position
|-
| 20 || Menu help
|-
| 21 || Window changed (zoom, move)
|}

The event types—requester, window refreshed, active window, inactive window, window resized and window changed—are dispatched to the console unit which owns the window from which the events are generated, even if it is not the active (selected ) window at the time the event is generated. This ensures that the proper console unit is notified of those events. All other events are dispatched to the active console unit (if it has requested those events).

== Input Event Reports ==

If you select any of these events you will start to get information about the events in the following form:

<pre>
<CSI><class>;<subclass>;<keycode>;<qualifiers>;<x>;<y>;<seconds>;<microseconds>|
</pre>

; <CSI>
: is a one-byte field. It is the “control sequence introducer,” 0x9B in hex.

; <class>
: is the raw input event type, from the above table.

; <subclass>
: is usually 0. If the mouse is moved to the right controller, this would be 1.

; <keycode>
: indicates which raw key number was pressed. This field can also be used for mouse information.

: {{Note|title=The Raw Key Might Be The Wrong Key|text=National keyboards often have different keyboard arrangements. This means that a particular raw key number may represent different characters on different national keyboards. The normal console read stream (as opposed to raw events) will contain the proper ASCII character for the keypress as translated according to the user’s keymap.}}

; <qualifiers>
: indicates the state of the keyboard and system. The qualifiers are defined as follows:

:{| class="wikitable"
|+ Input Event Qualifiers
! Bit
! Mask
! Key
! Comment
|-
| 0 || 0001 || Left shift
|-
| 1 || 0002 || Right shift
|-
| 2 || 0004 || Caps Lock || Associated keycode is special; see below
|-
| 3 || 0008 || Ctrl
|-
| 4 || 0010 || Left Alt
|-
| 5 || 0020 || Right Alt
|-
| 6 || 0040 || Left Amiga key pressed
|-
| 7 || 0080 || Right Amiga key pressed
|-
| 8 || 0100 || Numeric pad
|-
| 9 || 0200 || Repeat
|-
| 10 || 0400 || Interrupt || Not currently used.
|-
| 11 || 0800 || Multibroadcast || This window (active one) or all windows.
|-
| 12 || 1000 || Middle mouse button || (Not available on standard mouse)
|-
| 13 || 2000 || Right mouse button
|-
| 14 || 4000 || Left mouse button
|-
| 15 || 8000 || Relative mouse || Mouse coordinates are relative, not absolute.
|}

: The '''Caps Lock''' key is handled in a special manner. It generates a keycode only when it is pressed, not when it is released. However, the up/down bit (80 hex) is still used and reported. If pressing the '''Caps Lock''' key causes the LED to light, keycode 62 ('''Caps Lock''' pressed) is sent. If pressing the '''Caps Lock''' key extinguishes the LED, keycode 190 ('''Caps Lock''' released) is sent. In effect, the keyboard reports this key as held down until it is struck again.

; <x> and <y>
: filled by some classes with an Intuition address: x<<16+y.

; <seconds> and <microseconds>
: contain the system time stamp taken at the time the event occurred. These values are stored as longwords by the system.

With RAW keyboard input selected, keys will no longer return a simple one-character “A” to “Z” but will instead return raw keycode reports of the form:

<pre>
<CSI>1;0;<keycode>;<qualifiers>;<prev1>;<prev2>;<seconds>;<microseconds>|
</pre>

For example, if the user pressed and released the '''A''' key with the '''Left Shift''' and '''Right Amiga''' keys also pressed, you might receive the following data:

<pre>
<CSI>1;0;32;32769;14593;5889;421939940;316673|
<CSI>1;0;160;32769;0;0;421939991;816683|
</pre>

The <keycode> field is an ASCII decimal value representing the key pressed or released. Adding 128 to the pressed key code will result in the released keycode.

The <prev1> and <prev2> fields are relevant for the interpretation of keys which are modifiable by dead-keys (see “Dead-Class Keys” section). The <prev1> field shows the previous key pressed. The lower byte shows the qualifier, the upper byte shows the key code. The <prev2> field shows the key pressed before the previous key. The lower byte shows the qualifier, the upper byte shows the key code.

== Using the Console Device Without a Window ==

Most console device processing involves a window, but there are functions and special commands that may be used without a window. To use the console device without a window, you call OpenDevice() with the console unit CONU_LIBRARY.

The console device functions are CDInputHandler() and RawKeyConvert(); they may only be used with the CONU_LIBRARY console unit. The console device commands which do not require a window are CD_ASKDEFAULTKEYMAP and CD_SETDEFAULTKEYMAP; they be used with any console unit. The advantage of using the commands with the CONU_LIBRARY unit is the lack of overhead required for CONU_LIBRARY because it doesn’t require a window.

To use the functions requires the following steps:

* Declare the console device base address variable ConsoleDevice in the global data area.
* Declare storage for an I/O request of type IOStdReq.
* Open the console device with CONU_LIBRARY set as the console unit.
* Set the console device base address variable to point to the device library vector which is returned in io_Device.
* Call the console device function(s).
* Close the console device when you are finished.

<syntaxhighlight lang="C" line>
#include <devices/conunit.h>

int main()
{
struct IOStdReq ConsIO = {0};

/* Open the device with CONU_LIBRARY for function use */
if (0 == IExec->OpenDevice("console.device", CONU_LIBRARY, (struct IORequest *)&ConsIO, 0))
{
/* Set the base address variable to the device library vector */
struct ConsoleDevice *ConsoleDevice = (struct ConsoleDevice *)ConsIO.io_Device;
struct ConsoleIFace *IConsole = (struct ConsoleIFace*)
IExec->GetInterface((struct Library*)ConsoleDevice, "main", 1, NULL);

.
. (console device functions would be called here)
.

IExec->DropInterface((struct Interface *)IConsole);
IExec->CloseDevice(ConsIO);
}
}
</syntaxhighlight>

The code fragment shows only the steps outlined above, it is not complete in any sense of the word. For a complete example of using a console device function, see the ''rawkey.c'' code example in the [[Intuition_Keyboard|Intuition Keyboard]]. The example uses the RawKeyConvert() function.

To use the commands with the CONU_LIBRARY console unit, you follow the same steps that were outlined in [[#Opening the Console Device|Opening the Console Device]].

<syntaxhighlight lang="C" line>
struct KeyMap *keymap; /* pointer to keymap */

/* Create the message port */
struct MsgPort *ConsoleMP = IExec->AllocSysObjectTags(ASOT_PORT, TAG_END);
if (ConsoleMP != NULL)
{
/* Create the I/O request */
struct IOStdReq *ConsoleIO = IExec->AllocSysObjectTags(ASOT_IOREQUEST,
ASOIOR_Size, sizeof(struct IOStdReq),
ASOIOR_ReplyPort, ConsoleMP,
TAG_END);

if (ConsoleIO != NULL)
{
/* Open the Console device */
if (IExec->OpenDevice("console.device", CONU_LIBRARY, (struct IORequest *)ConsoleIO, 0))

/* Inform user that it could not be opened */
IDOS->Printf("Error: console.device did not open\n");
else
{
/* Allocate memory for the keymap */
if (keymap = (struct KeyMap *)
AllocVecTags(sizeof(struct KeyMap), AVT_ClearWithValue, 0, TAG_END))
{
/* device opened, send CD_ASKKEYMAP command to it */
ConsoleIO->io_Length = sizeof(struct KeyMap);
ConsoleIO->io_Data = (APTR)keymap; /* where to put it */
ConsoleIO->io_Command = CD_ASKKEYMAP;
IExec->DoIO((struct IORequest *)ConsoleIO))
}

IExec->CloseDevice(ConsIO);
}
</syntaxhighlight>

Again, as in the previous code fragment, this is not complete and you should only use it as a guide.

== Console Device Caveats ==

<ul>
<li>Only one console unit can be attached per window. Sharing a console window must be done at a level higher than the device.</li>
<li>Do not mix graphics.library calls with console rendering in the same areas of a window. It is permissible to send console sequences to adjust the area in which console renders, and use graphics.library calls to render outside of the area console is using.
For example, do not render text with console sequences and scroll using the graphics.library ScrollRaster() function.</li>
<li>The character map feature is private and cannot be accessed by the programmer. Implementation details and behaviors of the character map my change in the future.</li>
<li>Do not use an IDCMP with character mapped consoles. All Intuition messages should be obtained via '''Raw Input Events''' from the console device.</li></ul>

== Console Device Example Code ==

The following is a console device demonstration program with supporting routines:

<syntaxhighlight lang="C" line>
/*
* Console.c
*
* Example of opening a window and using the console device
* to send text and control sequences to it. The example can be
* easily modified to do additional control sequences.
*
* Run from CLI only.
*/

#include <exec/types.h>
#include <exec/io.h>
#include <exec/memory.h>
#include <intuition/intuition.h>
#include <libraries/dos.h>
#include <devices/console.h>

#include <proto/exec.h>
#include <proto/dos.h>
#include <proto/intuition.h>
#include <proto/utility.h>

/* Note - using two character <CSI> ESC[. Hex 9B could be used instead */
#define RESETCON "\033c"
#define CURSOFF "\033[0 p"
#define CURSON "\033[ p"
#define DELCHAR "\033[P"

/* SGR (set graphic rendition) */
#define COLOR02 "\033[32m"
#define COLOR03 "\033[33m"
#define ITALICS "\033[3m"
#define BOLD "\033[1m"
#define UNDERLINE "\033[4m"
#define NORMAL "\033[0m"

/* our functions */
void cleanexit(uint8 *,LONG);
void cleanup(void);
int8 OpenConsole(struct IOStdReq *,struct IOStdReq *, struct Window *);
void CloseConsole(struct IOStdReq *);
void QueueRead(struct IOStdReq *, uint8 *);
uint8 ConGetChar(struct MsgPort *, uint8 *);
LONG ConMayGetChar(struct MsgPort *, uint8 *);
void ConPuts(struct IOStdReq *, uint8 *);
void ConWrite(struct IOStdReq *, uint8 *, LONG);
void ConPutChar(struct IOStdReq *, uint8);

struct NewWindow nw =
{
10, 10, /* starting position (left,top) */
620,180, /* width, height */
-1,-1, /* detailpen, blockpen */
CLOSEWINDOW, /* flags for idcmp */
WINDOWDEPTH|WINDOWSIZING|
WINDOWDRAG|WINDOWCLOSE|
SMART_REFRESH|ACTIVATE, /* window flags */
NULL, /* no user gadgets */
NULL, /* no user checkmark */
"Console Test", /* title */
NULL, /* pointer to window screen */
NULL, /* pointer to super bitmap */
100,45, /* min width, height */
640,200, /* max width, height */
WBENCHSCREEN /* open on workbench screen */
};

/* Opens/allocations we'll need to clean up */
struct Library *IntuitionBase = NULL;
struct IntuitionIFace *IIntuition = NULL;
struct Window *win = NULL;
struct IOStdReq *writeReq = NULL; /* IORequest block pointer */
struct MsgPort *writePort = NULL; /* replyport for writes */
struct IOStdReq *readReq = NULL; /* IORequest block pointer */
struct MsgPort *readPort = NULL; /* replyport for reads */
BOOL OpenedConsole = FALSE;

BOOL FromWb;

int main(int argc, char **argv)
{
struct IntuiMessage *winmsg;
ULONG signals, conreadsig, windowsig;
LONG lch;
SHORT InControl = 0;
BOOL Done = FALSE;
uint8 ch, ibuf;
uint8 obuf[200];
int8 error;

FromWb = (argc==0) ? TRUE : FALSE;

IntuitionBase = IExec->OpenLibrary("intuition.library", 50);
IIntuition = (struct IntuitionIFace*)IExec->GetInterface(IntuitionBase, "main", 1, NULL);
if(IIntuition == NULL)
cleanexit("Can't open intuition\n",RETURN_FAIL);

/* Create reply port and io block for writing to console */
writePort = IExec->AllocSysObjectTags(ASOT_PORT,
ASOPORT_Name, "RKM.console.write",
TAG_END);
if(writePort == NULL)
cleanexit("Can't create write port\n",RETURN_FAIL);

writeReq = IExec->AllocSysObjectTags(ASOT_IOREQUEST,
ASOIOR_Size, sizeof(struct IOStdReq),
ASOIOR_ReplyPort, writePort,
TAG_END);
if(writeReq == NULL)
cleanexit("Can't create write request\n",RETURN_FAIL);

/* Create reply port and io block for reading from console */
readPort = IExec->AllocSysObjectTags(ASOT_PORT,
ASOPORT_Name, "RKM.console.read",
TAG_END);
if(readPort == NULL)
cleanexit("Can't create read port\n",RETURN_FAIL);

readReq = IExec->AllocSysObjectTags(ASOT_IOREQUEST,
ASOIOR_Size, sizeof(struct IOStdReq),
ASOIOR_ReplyPort, readPort,
TAG_END);
if(readReq == NULL)
cleanexit("Can't create read request\n",RETURN_FAIL);

/* Open a window */
if(!(win = IIntuition->OpenWindow(&nw)))
cleanexit("Can't open window\n",RETURN_FAIL);

/* Now, attach a console to the window */
if(error = OpenConsole(writeReq, readReq, win))
cleanexit("Can't open console.device\n",RETURN_FAIL);
else OpenedConsole = TRUE;

/* Demonstrate some console escape sequences */
ConPuts(writeReq,"Here's some normal text\n");
IUtility->SNPrintf(obuf, sizeof(obuf), "%s%sHere's text in color 3 and italics\n", COLOR03, ITALICS);
ConPuts(writeReq,obuf);
ConPuts(writeReq,NORMAL);
IDOS->Delay(50); /* Delay for dramatic demo effect */
ConPuts(writeReq,"We will now delete this asterisk =*=");
IDOS->Delay(50);
ConPuts(writeReq,"\b\b"); /* backspace twice */
IDOS->Delay(50);
ConPuts(writeReq,DELCHAR); /* delete the character */
IDOS->Delay(50);

QueueRead(readReq,&ibuf); /* send the first console read request */

ConPuts(writeReq,"\n\nNow reading console\n");
ConPuts(writeReq,"Type some keys. Close window when done.\n\n");

conreadsig = 1 << readPort->mp_SigBit;
windowsig = 1 << win->UserPort->mp_SigBit;

while(!Done)
{
/* A character, or an IDCMP msg, or both could wake us up */
signals = IExec->Wait(conreadsig|windowsig);

/* If a console signal was received, get the character */
if (signals & conreadsig)
{
if((lch = ConMayGetChar(readPort,&ibuf)) != -1)
{
ch = lch;
/* Show hex and ascii (if printable) for char we got.
* If you want to parse received control sequences, such as
* function or Help keys, you would buffer control sequences
* as you receive them, starting to buffer whenever you
* receive 0x9B (or 0x1B[ for user-typed sequences) and
* ending when you receive a valid terminating character
* for the type of control sequence you are receiving.
* For CSI sequences, valid terminating characters
* are generally 0x40 through 0x7E.
* In our example, InControl has the following values:
* 0 = no, 1 = have 0x1B, 2 = have 0x9B OR 0x1B and [,
* 3 = now inside control sequence, -1 = normal end esc,
* -2 = non-CSI(no [) 0x1B end esc
* NOTE - a more complex parser is required to recognize
* other types of control sequences.
*/

/* 0x1B ESC not followed by '[', is not CSI seq */
if (InControl==1)
{
if(ch=='[') InControl = 2;
else InControl = -2;
}

if ((ch==0x9B)||(ch==0x1B)) /* Control seq starting */
{
InControl = (ch==0x1B) ? 1 : 2;
ConPuts(writeReq,"=== Control Seq ===\n");
}

/* We'll show value of this char we received */
if (((ch >= 0x1F)&&(ch <= 0x7E))||(ch >= 0xA0))
IUtility->SNPrintf(obuf, sizeof(obuf), "Received: hex %02x = %c\n",ch,ch);
else IUtility->SNPrintf(obuf, sizeof(obuf), "Received: hex %02x\n",ch);
ConPuts(writeReq,obuf);

/* Valid ESC sequence terminator ends an ESC seq */
if ((InControl==3)&&((ch >= 0x40) && (ch <= 0x7E)))
{
InControl = -1;
}
if (InControl==2) InControl = 3;
/* ESC sequence finished (-1 if OK, -2 if bogus) */
if (InControl < 0)
{
InControl = 0;
ConPuts(writeReq,"=== End Control ===\n");
}
}
}

/* If IDCMP messages received, handle them */
if (signals & windowsig)
{
/* We have to ReplyMsg these when done with them */
while (winmsg = (struct IntuiMessage *)IExec->GetMsg(win->UserPort))
{
switch(winmsg->Class)
{
case CLOSEWINDOW:
Done = TRUE;
break;
default:
break;
}
IExec->ReplyMsg((struct Message *)winmsg);
}
}
}

/* We always have an outstanding queued read request
* so we must abort it if it hasn't completed,
* and we must remove it.
*/
if(!(IExec->CheckIO(readReq))) IExec->AbortIO(readReq);
IExec->WaitIO(readReq); /* clear it from our replyport */

cleanup();
return RETURN_OK;
}

void cleanexit(uint8 *s,LONG n)
{
if(*s & (!FromWb)) IDOS->Printf(s);
cleanup();
exit(n);
}

void cleanup()
{
if(OpenedConsole) CloseConsole(writeReq);
IExec->FreeSysObject(ASOT_IOREQUEST, readReq);
IExec->FreeSysObject(ASOT_PORT, readPort);
IExec->FreeSysObject(ASOT_IOREQUEST, writeReq);
IExec->FreeSysObject(ASOT_PORT, writePort);
if(IIntuition != NULL && win != NULL) IIntuition->CloseWindow(win);
IExec->DropInterface((struct Interface *)IIntuition);
IExec->CloseLibrary(IntuitionBase);
}

/* Attach console device to an open Intuition window.
* This function returns a value of 0 if the console
* device opened correctly and a nonzero value (the error
* returned from OpenDevice) if there was an error.
*/
int8 OpenConsole(struct IOStdReq *writereq, struct IOStdReq *readreq, struct Window *window)
{
int8 error;

writereq->io_Data = (APTR) window;
writereq->io_Length = sizeof(struct Window);
error = IExec->OpenDevice("console.device", 0, writereq, 0);
readreq->io_Device = writereq->io_Device; /* clone required parts */
readreq->io_Unit = writereq->io_Unit;
return(error);
}

void CloseConsole(struct IOStdReq *writereq)
{
IExec->CloseDevice(writereq);
}

/* Output a single character to a specified console
*/
void ConPutChar(struct IOStdReq *writereq, uint8 character)
{
writereq->io_Command = CMD_WRITE;
writereq->io_Data = (APTR)&character;
writereq->io_Length = 1;
IExec->DoIO(writereq);
/* command works because DoIO blocks until command is done
* (otherwise ptr to the character could become invalid)
*/
}

/* Output a stream of known length to a console
*/
void ConWrite(struct IOStdReq *writereq, uint8 *string, LONG length)
{
writereq->io_Command = CMD_WRITE;
writereq->io_Data = (APTR)string;
writereq->io_Length = length;
IExec->DoIO(writereq);
/* command works because DoIO blocks until command is done
* (otherwise ptr to string could become invalid in the meantime)
*/
}

/* Output a NULL-terminated string of characters to a console
*/
void ConPuts(struct IOStdReq *writereq,uint8 *string)
{
writereq->io_Command = CMD_WRITE;
writereq->io_Data = (APTR)string;
writereq->io_Length = -1; /* means print till terminating null */
IExec->DoIO(writereq);
}

/* Queue up a read request to console, passing it pointer
* to a buffer into which it can read the character
*/
void QueueRead(struct IOStdReq *readreq, uint8 *whereto)
{
readreq->io_Command = CMD_READ;
readreq->io_Data = (APTR)whereto;
readreq->io_Length = 1;
IExec->SendIO(readreq);
}

/* Check if a character has been received.
* If none, return -1
*/
LONG ConMayGetChar(struct MsgPort *msgport, uint8 *whereto)
{
struct IOStdReq *readreq;

if (!(readreq = (struct IOStdReq *)IExec->GetMsg(msgport))) return(-1);
int temp = *whereto; /* get the character */
QueueRead(readreq,whereto); /* then re-use the request block */
return(temp);
}

/* Wait for a character
*/
uint8 ConGetChar(struct MsgPort *msgport, uint8 *whereto)
{
struct IOStdReq *readreq;

WaitPort(msgport);
readreq = (struct IOStdReq *)GetMsg(msgport);
int temp = *whereto; /* get the character */
QueueRead(readreq,whereto); /* then re-use the request block*/
return((uint8)temp);
}
</syntaxhighlight>

== Additional Information on the Console Device ==

Additional programming information on the console device can be found in the include files and the Autodocs for the console device. Both are contained in the SDK.

{| class="wikitable"
! Includes
|-
| devices/console.h
|-
| devices/conunit.h
|}

{| class="wikitable"
! AutoDocs
|-
| console.doc
|}

Programming AmigaOS 4: Utility - Little Helpers

2025-01-26T19:35:24Z

Costel Mincea: Text replacement - "<syntaxhighlight>" to "<syntaxhighlight lang="C" line>"

''This article was adapted from Amiga Future magazine's series on developing for AmigaOS....''

The inconspicuous AmigaOS 4 utility.library has been extended with some useful functions. So it's about time we took a closer look at it.

We have sub-divided the overall description into different sections. So, let's get started with part one, the very flexible taglists.

= Tag list improvements =

Extending function-calls and their parameters can be a complicated issue, without updating all the old sources. By using a tag list, you can include new tags very flexibly, so unknown tags will be ignored. So if you are running the program on an older system, these new options are not available. That means, tag lists will become more and more important. Many of these new functions are about creating, searching and filtering the tagslists. A complete overview about all the new functions can be found in the final section of this article.

<syntaxhighlight lang="C" line>
struct TagItem *taglist;

/* allocates memory for four pairs of tag-entries */
/* the fifth entry only includes the identification for the list-ending */
if((taglist = IUtility->AllocateTagItems(5)))
{
/* Fill the taglist */
taglist[0].ti_Tag = TAG_IGNORE;
taglist[0].ti_Data = 1;
...
taglist[4].ti_Tag = TAG_END;
taglist[4].ti_Data = 0;

/* do something wiht the taglist */
...

/*at the end the taglist memory can be deallocated*/
IUtility->FreeTagItems(taglist);
}
</syntaxhighlight>

= Check-digits =

The utility.library provides a list of interesting features for check-digits. There are a great number of different check-digits and algorithms (i.e. CR32, MD5). The Amiga allows you to calculate a 160 bit (= 20 byte) check-digit via the SHA-1 algorithm. This comes in handy, if you want to check over huge data sections, without having an identical number. In comparison to check-digits with only 2 respectively 4 bytes, this can become a real problem. In detail, there are 3 steps to be made.

First of all, you have to initialise the data structure by using the IUtility->MessageDigest_SHA_Unit() command. Second comes the actual calculation via the IUtility->MessageDigest_SHA_Update() command, whereas the data and the length must be given to create the check-digit.

Lastly we type in the IUtility->MessageDigest_SHA_Final() command. After completing all three steps, it's possible to get the calculated check-digit through mdsha_Code. The example below shows you how:

<syntaxhighlight lang="C" line>
struct MessageDigest_SHA mdsha = { 0 };
STRPTR testdata = "This is just a test";

IUtility->MessageDigest_SHA_Init(&mdsha);
IUtility->MessageDigest_SHA_Update(&mdsha, testdata, IUtility->Strlen(somedata));
IUtility->MessageDigest_SHA_Final(&mdsha);

IDOS->Printf(" Checksum is: %.20s\n",mdsha.mdsha_Code);
</syntaxhighlight>

The test value will be output bit by bit, so it's not very clever to use the IDOS->Printf() command, because control-characters can be included there as well. The value can be compared with the reference value thru the IUtility->StriCmp() command.

<syntaxhighlight lang="C" line>
/*
* CalcChecksum.c
*
* gcc CalcChecksum.c -o CalcChecksum -l auto
*/

/******************************* INCLUDES *************************************/

#include <proto/exec.h>
#include <proto/dos.h>
#include <proto/utility.h>

/******************************* DEFINES **************************************/

#define BUFFER_SIZE 65536 /* 64 kByte Block */

/************************ VARIABLEN DEKLARATIONEN *****************************/

const UBYTE *gb_ArgTemplate = "FILENAME/A";
enum { ARG_filename, ARG_MAX };
ULONG gb_Args[ARG_MAX] = { 0 };

/******************************************************************************/

BOOL CalculateChecksum(CONST_STRPTR filename, UBYTE *checksum)
{
BPTR fh;
struct MessageDigest_SHA mdsha = { 0 };

/* Preparing checksum calculation */
IUtility->MessageDigest_SHA_Init(&mdsha);

if((fh = IDOS->Open((STRPTR)filename, MODE_OLDFILE)))
{
LONG character;
UBYTE *buffer;

if((buffer = (UBYTE *) IExec->AllocVecTags(BUFFER_SIZE, TAG_END)))
{
while((character = IDOS->Read(fh, buffer, BUFFER_SIZE)) > 0)
{
IUtility->MessageDigest_SHA_Update(&mdsha, buffer, character);
}

IExec->FreeVec(buffer);
}

IDOS->Close(fh);
}

IUtility->MessageDigest_SHA_Final(&mdsha);
IUtility->Strlcpy(checksum, mdsha.mdsha_Code, 20);
checksum[20] = '\0';

return fh ? TRUE : FALSE;
}

/******************************************************************************/

int main()
{
struct RDArgs *rda;

if((rda = IDOS->ReadArgs((STRPTR)gb_ArgTemplate,(LONG*)gb_Args,NULL)))
{
UBYTE keybuffer[21]; /* 20 Bytes Checksum + \0 */

if(BerechneChecksumme((STRPTR)gb_Args[ARG_filename], keybuffer))
{
/*
** The checksum is a 160-bit data stream which should
** not strictly be output like a string. We do so here
** for convenience only.
*/
IDOS->Printf("Checksum for file '%s' is %s\n",
gb_Args[ARG_filename], keybuffer);
}

IDOS->FreeArgs(rda);
}
else IDOS->PrintFault(IDOS->IoErr(),"CalcChecksum");

return 0;
}
</syntaxhighlight>

[[File:AF111_CalcChecksum.png|frame|center]]

= Standard-C-Functions =

If you don't like to include the additonal C-libraries (newlib or clib2), it's possible to get similar functions from the utility.libary. In the case of string-functions, there are IUtility->Strlcpy() and IUtility->Strlcat() functions, which seem to have a slightly strange name, but work in a similar way as strncpy and strncat from the C-libaries. Since version 53.4 there is also a function called IUtility->Strlen() which determines the length of a string. With AmigaOS 4.1 Final Edition new functions were added for handling UTF-8 coded strings.

Like the memset function, there is a function called IUtility->SetMem(), which is able to set the memory-area. The required arguments are the starting-address in the memory, the value to be set (usually 0 deletes the memory-area) and the number of bytes that have to be amended. In general the order of the arguments are the same as in the memset function. A shortcut can be taken, if you just use the IUtility->ClearMem() function. This one only needs the starting-address and the number of bytes that should be cleared to zero. One other function, that works with memory-areas, is called IUtility->MoveMem(). As the name implies, the memory-area will be moved. Well the source material stays unchanged, so it's more like copying the areas. You can compare this function to the IExec->CopyMem() function from the exec.libary, but with the difference of allowing overlapping memory-areas. Make sure that your destination has enough free space for the data and, of course, it has to be reserved in your own program as well, because without reserving it, the OS will shutdown your program, if "aggravated" memory protection is enabled.

<syntaxhighlight lang="C" line>
/*
* MemoryFunctions.c
*
* gcc MemoryFunctions.c -o MemoryFunctions -l auto
*/

/******************************* INCLUDES *************************************/

#include <proto/exec.h>
#include <proto/dos.h>
#include <proto/utility.h>

/******************************************************************************/

int main()
{
UBYTE *mem;

/* Request memory */
if((mem = (UBYTE *) IExec->AllocVecTags(512, TAG_END)))
{
IDOS->Printf("memory allocated\n");

/* Clear memory area */
IUtility->ClearMem(mem,512);

/* Set memory area */
IUtility->SetMem(mem,'@',128);

/* Move memory area */
IUtility->MoveMem(mem,mem + 128,256);

/* Free memory area */
IExec->FreeVec(mem);
}
else IDOS->Printf("Not enough memory\n");

return( 0 );
}
</syntaxhighlight>

= Randomizing =

If you ever liked to create your own lottery numbers, the new IUtility->Random() function will allow you to do just that. All you need is a number, so you can just pick the actual time or a random value from the stack. The function will return a number ranging from 1 up to 2147483647, which can be cut down via the modulo operation. Next up we see an example of how to create your own lottery numbers.
The same number can be chosen again, so there is room for improvement.

<syntaxhighlight lang="C" line>
struct RandomState state;
ULONG i, number;
IDOS->Printf("6 out of 49:\n");
for(i=1; i<7; i++)
{
/* determines a number between 1 and 49 */
number = (IUtility->Random(&state) % 48) + 1;
IDOS->Printf("%ld. Number %2ld\n",i,number);
}

number = (IUtility->Random(&state) % 48) + 1;
IDOS->Printf("Additional number %2ld\n",number);
</syntaxhighlight>

<syntaxhighlight lang="C" line>
/* LottoGenerator.c
*
* gcc LottoGenerator.c -o LottoGenerator -l auto
*/

/******************************* INCLUDES *************************************/

#include <proto/exec.h>
#include <proto/dos.h>
#include <proto/utility.h>
#include <time.h>

/******************************************************************************/

int main()
{
struct RandomState state;
uint32 i, number;

/*
** Initialize the start values so that a different
** series of random numbers are generated each time.
*/
state.rs_High = time(NULL);
state.rs_Low = time(NULL);

IDOS->Printf("Lotto 6 out of 49:\n");
for(i=1; i<7; i++)
{
/*
** Determine a number from 1 to 49.
*/
number = (IUtility->Random(&state) % 48) + 1;
IDOS->Printf("%ld. Number is %2ld\n",i,number);
}

number = (IUtility->Random(&state) % 48) + 1;
IDOS->Printf("The bonus number is %2ld\n",number);

return 0;
}
</syntaxhighlight>

[[File:AF111_LottoGenerator.png|frame|center]]

= Miscellaneous functions =

Another helpful function is called IUtility->GetUniqueID(), which determines a unique number. This comes in handy by creating temporary files using multiple processes. As long as the system isn't shutdown, this unique number will be available. By restarting the system, the numbers will be created from scratch. Here is an easy example of how to create files with unique numbers:

<syntaxhighlight lang="C" line>
ULONG id = IUtility->GetUniqueID();
BPTR fh;
TEXT filename[30];
IUtility->SNPrintf(filename,sizeof(filename),"t:tmp.%ld",id);
if(IDOS->Open(filename,MODE_NEWFILE))
{
...
IDOS->CLose(fh);
}
</syntaxhighlight>

= New utility.library functions =

== Taglist functions ==

Allocates the memory for the number of given tags.
struct TagItem *AllocateTagItems(ULONG numtags);

Changes the tag-data-values in the changelist based on the values from the list. Unknown tags in the list will be ignored.
VOID ApplyTagChanges(struct TagItem *list, struct TagItem *changelist);

Creating a taglist copy; has to be deallocated via FreeTagItems().
struct TagItem *CloneTagItems(struct TagItem *orglist);

Deallocates the memory for the taglist.
VOID FreeTagItems(struct TagItem *taglist);

Creates a skip-tag-list; has to be deallocated via DeleteSkipList().
struct SkipList * CreateSkipList(struct Hook *hook, LONG max_levels);
VOID DeleteSkipList(struct SkipList *list);

Searches the changelist and deletes all entries, which are identical to the entries in the orglist. In the case of different values, the keyword "apply" defines if the value should be assumed from the orglist.
VOID FilterTagChanges(struct TagItem *changelist, struct TagItem *orglist, ULONG apply);

Deletes the tags from the changelist, if they occur in the filter array.
ULONG FilterTagItems(struct TagItem *changelist, Tag *filterarray ,ULONG logic);

Searches the taglist for the right entry and returns the matching items.
struct TagItem *FindTagItem(Tag tag,struct TagItem *taglist);

Determines the data value of the declared tag from the list.
ULONG GetTagData(Tag tag, ULONG default, struct TagItem *taglist);

Transfers the maplist values into the corresponding fields of the taglist. Type pin-points what happens to all entries, which only occur in the taglist.
VOID MapTags(struct TagItem *taglist, struct TagItem *maplist, ULONG type);

== Splay-Tree-Functions ==

Creating a Splay-Tree-Datastructure; has to be deallocated via DeleteSplayTree()
struct SplayTree * CreateSplayTree(struct Hook *hook);
VOID DeleteSplayTree(struct SplayTree *tree);

Searches the tree for a specific key and returns the matching node
struct SplayNode * FindSplayNode(struct SplayTree *tree, APTR key);

Creates a new SplayNode and adds it to the tree
struct SplayNode * InsertSplayNode(struct SplayTree *tree, APTR key, ULONG data_size);

Removes the SplayNode from the tree, if a matching entry for the key was found.
BOOL RemoveSplayNode(struct SplayTree *tree, APTR key);

== Skip-List-Functions ==

Searches the list for a specific key and returns the matching node.
struct SkipNode * FindSkipNode(struct SkipList *list, APTR key);

Determines the first node in the list
struct SkipNode * GetFirstSkipNode(struct SkipList *list);

Determines the next node after the previous node in the list.
struct SkipNode * GetNextSkipNode(struct SkipList *list, struct SkipNode *previousnode);

Creates a new skipnode and adds it to the list.
struct SkipNode * InsertSkipNode(struct SkipList *list, APTR key, ULONG total_size);

Removes the SkipNode from the list, if a matching entry for the key was found.
BOOL RemoveSkipNode(struct SkipList *list, APTR key);

== Miscellaneous functions ==

Calculates a 160 bit checksum
VOID MessageDigest_SHA_Init(struct MessageDigest_SHA *mdsha);
VOID MessageDigest_SHA_Update(struct MessageDigest_SHA *mdsha, APTR data, LONG num_bytes);
VOID MessageDigest_SHA_Final(struct MessageDigest_SHA *mdsha);

A hook-function for an object to send a message
ULONG CallHookPkt(struct Hook *hook, APTR object, APTR message);

Provides a unique number (as long as the computer is running)
ULONG GetUniqueID(void);

A random number between 1 ... 2147483647 will be returned
LONG Random(struct RandomState *state);

Adds a value to the memory-area
APTR SetMem(APTR destination, UBYTE value, LONG length);

Deletes a memory-area (it will be filled with 0 bytes):
VOID ClearMem(APTR destination, uint32 size);

Moves parts of the memory-area (even if they are overlapping):
VOID MoveMem(APTR source, APTR destination, uint32 size);

Adds the source string to the destination, where the max length will be considered.
LONG Strlcat(STRPTR destination, CONST_STRPTR source, LONG destination_size);

Copies the string from its source to its destination, where the max length will be considered.
LONG Strlcpy(STRPTR destination, CONST_STRPTR source, LONG destination_size);

Determines the length of a string
uint32 Strlen(CONST_STRPTR string);

Searches a node based on its name. Lower and Upper case will be ignored.
struct Node *node = FindNameNC(struct Node *start, STRPTR name);

Creates a string based on a specific format and the required args, (the returned string has to be deallocated via FreeVec)
STRPTR VASPrintf(CONST_STRPTR format, APTR args);
STRPTR ASPrintf(CONST_STRPTR format, ...);

Creates a Format-String, where the result is stored in the buffer.
LONG VSNPrintf(STRPTR buffer, LONG buffer_size, CONST_STRPTR format, APTR args);
LONG SNPrintf(STRPTR buffer, LONG buffer_size, CONST_STRPTR format, ...);

= Authors =

Written by Michael Christoph 
Translation by Florian Hanel 
Copyright (c) 2013 Michael Christoph

SANA-II Revision 7

2025-01-26T19:34:56Z

Costel Mincea: Text replacement - "<syntaxhighlight>" to "<syntaxhighlight lang="C" line>"

{{WIP}}
= SANA-II Network Device Driver Specification =

The "SANA-II Network Device Driver Specification" is a standard for an Amiga software interface between networking hardware and network protocol stacks (or for software tools such as network monitors). A network protocol stack is a layer of software that network applications use to address particular processes on remote machines and to send data reliably in spite of hardware errors. There are several common network protocol stacks including ''TCP/IP'', ''OSI'', ''AppleTalk'', ''DECNet'' and ''Novell''.

SANA-II device drivers are intended to allow multiple network protocol stacks running on the same machine to share one network device. For example, the TCP/IP and AppleTalk protocol stacks could both run on the same machine over one ethernet board. The device drivers are also intended to allow network protocol stacks to be written in a hardware-independent fashion so that a different version of each protocol stack doesn't have to be written for each networking hardware device.

The standard does not address the writing of network applications. Application writers must not use SANA-II Device Drivers directly. Network applications must use the API provided by the network protocol software the application supports. The Amiga standard network API for TCP/IP is provided via the bsdsocket.library which is a part of Roadshow.

To write a SANA-II device driver, you will need to be familiar with the specification documents for the hardware you are writing to and with the "SANA-II Network Device Driver Specification".

To write a network protocol stack which will use SANA-II device drivers, you should have general familiarity with common network hardware and must be very familiar with the "SANA-II Network Device Driver Specification" as well as the specification for the protocol you are developing. If you are creating a new protocol, you must obtain a protocol type number for any hardware on which your protocol will be used.

This version of the specification is final. Any new version of the standard (i.e., to add new features) is planned to be backward compatible. No SANA-II device driver or software utilizing those drivers should be written to any earlier version of the specification.

Distribution of this version of the standard is unlimited. Anyone may write Amiga software which implements a SANA-II network device driver or which calls a SANA-II network device driver without restriction and may freely distribute such software that they have written.

It is important to try to test each SANA-II device driver against all software which uses SANA-II devices. Available example programs are valuable in initial testing. The Amiga Networking Group is interested in receiving evaluation and/or beta test copies of all Amiga networking hardware, SANA-II device drivers and software which uses SANA-II devices. However, we make no assurances regarding any testing which we may or may not perform with such evaluation copies.

The SANA-II standard caters to both Motorola 68000 platforms and PowerPC platforms.

Please feel free to comment. You can contact the AmigaOS development team through the [http://www.amigaos.net/contact AmigaOS contact form].

= Driver Form =

SANA-II device drivers are Amiga Exec device drivers. They use an extended IORequest structure and a number of extended commands for tallying network statistics, sending broadcasts and multicasts, network addressing and the handling of unexpected packets. The SDK includes information on how to construct an Exec device.

= Opening a SANA-II Device =

As when opening any other Exec device, on the call to OpenDevice() a SANA-II device receives an IORequest structure which the device initializes for the opener's use. The opener must copy this structure if it desires to use multiple asynchronous requests. The SANA-II IORequest is defined as follows:

<syntaxhighlight lang="C" line>
struct IOSana2Req
{
struct IORequest ios2_Req;
ULONG ios2_WireError;
ULONG ios2_PacketType;
UBYTE ios2_SrcAddr[SANA2_MAX_ADDR_BYTES];
UBYTE ios2_DstAddr[SANA2_MAX_ADDR_BYTES];
ULONG ios2_DataLength;
APTR ios2_Data;
APTR ios2_StatData;
APTR ios2_BufferManagement;
};
</syntaxhighlight>

; ios2_Req
: A standard Exec device IORequest.
; ios2_WireError
: A more specific device code which may be set when there is an io_Error. See <devices/sana2.h> for the defined WireErrors.
; ios2_PacketType
: The type of packet requested. See the section on "Packet Types".
; ios2_SrcAddr
: The device fills in this field with the interface (network hardware) address of the source of the packet that satisfied a read command. The bytes used to hold the address will be left justified but the bit layout is dependent on the particular type of network.
; ios2_DstAddr
: Before the device user sends a packet, it fills this with the interface destination address of the packet. On receives, the device fills this with the interface destination address. Other commands may use this field differently (see the "SANA-II network device driver Autodocs" in the SDK). The bytes used to hold the address will be left justified but the bit layout is dependent on the particular type of network.
; ios2_DataLength
: The device user initializes this field with the amount of data available in the Data buffer before passing the IOSana2Req to the device. The device fills in this field with the size of the packet data as it was sent on the wire. This does not include the header and trailer information. Depending on the network type and protocol type, the driver may have to calculate this value. This is generally used only for reads and writes (including broadcast and multicast).
; ios2_Data
: A pointer to some abstract data structure containing packet data. ''Drivers may not directly manipulate or examine anything pointed to by Data!'' This is generally used only for reads and writes (including broadcast and multicast).

; ios2_StatData
: Pointer to a structure in which to place a snapshot of device statistics. The data area must be long word aligned. This is only used on calls to the statistics commands.

; ios2_BufferManagement
: The opener places a pointer to a tag list in this field before calling OpenDevice(). Functions pointed to in the tag list are called by the device when processing IORequests from the opener. When returned from OpenDevice(), this field contains a pointer to driver-private information used to access these functions. See "Buffer Management" below for more details.

: Note that the <tt>ios2_BufferManagement</tt> field provided by the driver on <tt>OpenDevice()</tt> time in conjunction with <tt>io_Device</tt> and <tt>io_Unit</tt> is the unique identifier for all requests coming from this protocol stack until <tt>CloseDevice()</tt>. The driver must not ever change the <tt>ios2_BufferManagement</tt> field for a protocol stack at run time, even if <tt>S2_SANAHOOK</tt> is called to request extended features.

The flags used with the device on OpenDevice() are (SANA2OPB_xxx):

{| class="wikitable"
! Name
! Description
|-
| SANA2OPB_MINE
| Exclusive access to the unit requested.
|-
| SANA2OPB_PROM
| Promiscuous mode requested. Hardware which supports promiscuous mode allows all packets sent over the wire to be captured whether or not they are addressed to this node.
'''''Note:''' Promiscuous mode requires exclusive opening of the device.''
|}

The flags used during I/O requests are (SANA2IOB_xxx):

{| class="wikitable"
! Name
! Description
|-
| SANA2IOB_RAW
| Raw packet read/write requested. Raw packets should include the entire data-link layer packet. Devices with the same hardware device number should have the same raw packet format.
|-
| SANA2IOB_BCAST
| Broadcast packet (received).
|-
| SANA2IOB_MCAST
| Multicast packet (received).
|-
| SANA2IOB_QUICK
| Quick IO requested.
|}

= Buffer Management =

Unlike most other Exec Device drivers, SANA-II drivers have no internal buffers. Instead, they read/write to/from an abstract data structure allocated by the driver user. The driver accesses these buffers only via functions that the driver user provides to the driver. The driver user must provide two functions: one copies data to the abstract data structure and one copies data from the abstract data structure. The driver user can therefore choose the data structure used for buffer management by both the driver and driver user in order to have efficient memory and CPU usage overall.

The IOSana2Req contains a pointer to data and the length of said data. A driver is not allowed to make assumptions about how the data is stored. The driver cannot directly manipulate or examine the buffer in any manner. The driver can only access the buffer by calling the functions provided by the driver user.

Before calling OpenDevice(), the driver user points ios2_BufferManagement to a list of tags (defined in <devices/sana2.h>) which include pointers to the buffer management functions required by the driver (defined below). The driver will fail to open if the driver user does not supply all of the required functions. If the device opens successfully, the driver sets ios2_BufferManagement to a value which this opener must use in all future calls to the driver. This "magic cookie" is used from then on to access these functions (a "magic cookie" is a value which one software entity passes to another but which is only meaningful to one of the software entities). The driver user may not use the "magic cookie" in any way--it is for the driver to do with as it wishes. The driver could in theory choose to just copy the tag list to driver-owned memory and then parse the list for every IORequest, but it is much more efficient for the driver to create some sort of table of functions and to point ios2_BufferManagement to that table.

Another recommendation for the ``magic cookie`` is to use it to maintain a separate packet read queue for each device opener. This would allow multiple protocol stacks that all wish to receive the same packet type to work together without having to "know" about each other as ''Envoy'' and ''AS225'' do right now. What does multiple protocol stack support mean? Basically this means that each opener gets all the packets necessary. If a packet comes in that fills a request for more than one opener of the device, all of them will get a copy of the packet. This feature should never be left out of a device design. If it is missing, the usefulness of the device is severely limited.

In order to help system load, a packet filter callback allows protocol stacks to reject packets that are known to not be useful. ''Envoy'''s nipc.library (for example) could be modified to reject TCP packets (as it never uses them).

The specification currently defines the following tags for the OpenDevice() ios2_BufferManagement tag list:

{| class="wikitable"
|+ Copy data from network interface to protocol stack buffer
! Tag
! Description
|-
| S2_CopyToBuff (mandatory)
| This is a pointer to a function which conforms to the CopyToBuff Autodoc.
|-
| S2_CopyToBuff16 (optional)
| Copy to a 16 bit aligned buffer using 16 bit data words.
|-
| S2_CopyToBuff32 (optional)
| Copy to a 32 bit aligned buffer using 32 bit data words.
|-
| S2_DMACopyToBuff32 (optional)
| Perform a DMA copy to a 32 bit aligned contiguous buffer using 32 bit data words.
|-
| S2_DMACopyToBuff64 (optional)
| Perform a DMA copy to a 64 bit aligned contiguous buffer using 64 bit data words.
|}

{| class="wikitable"
|+ Copy data from protocol stack buffer to network interface
! Tag
! Description
|-
| S2_CopyFromBuff (mandatory)
| This is a pointer to a function which conforms to the CopyFromBuff Autodoc.
|-
| S2_CopyFromBuff16 (optional)
| Copy from a 16 bit aligned buffer using 16 bit data words.
|-
| S2_CopyFromBuff32 (optional)
| Copy from a 32 bit aligned buffer using 32 bit data words.
|-
| S2_DMACopyFromBuff32 (optional)
| Perform a DMA copy from a 32 bit aligned contiguous buffer using 32 bit data words.
|-
| S2_DMACopyFromBuff64 (optional)
| Perform a DMA copy from a 64 bit aligned contiguous buffer using 64 bit data words.
|}

{| class="wikitable"
|+ Filter data before protocol stack buffer
! Tag
! Description
|-
| S2_PacketFilter (optional)
| This is a pointer to a standard Hook to be called before S2_CopyToBuff is done. See the PacketFilter Autodoc for more information.
|}

{| class="wikitable"
|+ Logging messages from the driver
! Tag
! Description
|-
| S2_Log (optional)
| This is a pointer to a standard Hook to be called when the driver logs events.
|}

== Better buffer management ==

The mandatory buffer management callbacks may not be very efficient for certain types of hardware. They also do not allow driver DMA access.

All the new features are completely optional and do not collide with existing features. They may be used only when the protocol stack asks for them on opening a driver.

The enhancements consist of several new tags that may be specified by a protocol stack on OpenDevice() to offer certain data transfer options. It is up to the device driver to chose which callbacks to use at what time. These tags are advisory only and may be ignored by the driver for any data buffer at any time:

{| class="wikitable"
| S2_CopyToBuff16
|-
| S2_CopyFromBuff16
|-
| S2_CopyToBuff32
|-
| S2_CopyFromBuff32
|}

These are optional callbacks presented to the device with the same calling interface as for S2_CopyToBuff or S2_CopyFromBuff, respectively. The difference to the original callbacks is the required and guaranteed transfer size and alignment for accessing the device's buffer for a single piece of a data of either 16 or 32 bits, a data word. The copy function called may only use 16/32 bit aligned read/write commands of 16/32 bits at once to transfer the data words, respectively. If the buffer data length is not a multiple of the required data word transfer size, the last data word transfer may contain garbage padding in either transfer direction.

The following tags have been added to support direct writes into hardware buffers that do not allow arbitrarily sized or aligned accesses:

{| class="wikitable"
| S2_DMACopyToBuff32
|-
| S2_DMACopyFromBuff32
|}

If the protocol stack wants to optionally enhance data transfer efficiency with DMA supporting devices, it may pass any of these optional tags to the device on OpenDevice().

If the device driver supports DMA, it may call the respective callback with the abstract magic cookie ios2_Data in register A0. The callback may return NULL in D0. In this case, the driver may not use DMA for this buffer. Alternatively, the callback may return the address of the actual data buffer in D0, if it has these characteristics:

* The buffer is in contiguous memory. Depending on the intended data direction, it shall be readable or writable.
* The buffer is aligned on a 32 bit boundary.
* The buffer size shall be a multiple of 32 bit and it is at least = ios2_DataLength.
* It is up to the driver to decide if it can use DMA for this buffer and it shall fall back to the standard CPU callbacks if necessary. The data transfer method actually used by the driver will not be known in advance by the protocol stack.

The following tags have been added to allow for 64 bit aligned PCI DMA accesses to take place:

{| class="wikitable"
| S2_DMACopyToBuff64
|-
| S2_DMACopyFromBuff64
|}

These two callbacks are identical in operation to the <tt>S2_DMACopyToBuff32</tt> and <tt>S2_DMACopyFromBuff32</tt> callbacks. The difference is in that the memory region DMA is to take place in must be aligned to a 64 bit boundary and must be large enough to hold data that is a multiple of 64 bits in size.

== Best buffer management ==

The SANA-II driver interface is intended to transform data between the hardware layer and the link layer, to be used by networking software such as TCP/IP stacks. This transformation is performed by callback functions which are supplied by the networking software at the time the device driver is opened. The device driver then invokes these functions later in order to transfer data received and data to be sent.

The function parameters used by these callbacks are passed in 68000 registers for the lowest overhead. The problem with 68000 register parameters is that on the PowerPC platform, this form of parameter passing may require the use of emulation code. This is costly and may incur a severe performance penalty. It is an even greater problem if PowerPC native networking software is calling PowerPC native networking driver software and the other way round. In both cases the runtime environment will have to enter emulation mode, return to to PowerPC native execution, dip into emulation mode and return to native PowerPC execution. It would be much better if the chain of execution would stay in PowerPC mode all the time.

Alternatively, if a hook function is used, the operating system may be able to decide whether the function to be invoked needs emulating or called directly. The <tt>Hook</tt> effectively works as an abstraction which makes the function invocation platform independent.

The following standard wraps the copying and logging functions into the standardized <tt>Hook</tt> interface.

==== The hook function ====

The hook function itself is invoked with the following parameters:

<syntaxhighlight lang="C" line>
result = hook_function(hook, sana2req, sana2hookmsg)

ULONG hook_function(struct Hook *hook,
struct IOSana2Req *sana2req,
struct SANA2HookMsg *sana2hookmsg);
</syntaxhighlight>

Note that the result is not necessarily of type <tt>ULONG</tt>. It is a 32 bit value, which can be a boolean result code (for <tt>CopyFromBuff</tt>, <tt>CopyToBuff</tt> and their like) or a pointer to a memory address (for <tt>DMACopyToBuff</tt>, <tt>DMACopyFromBuff</tt> and their like).

=== Data structures ===

The following hook messages are to be used:

<syntaxhighlight lang="C" line>
struct SANA2HookMsg
{
ULONG shm_Method;
ULONG shm_MsgSize;
};
</syntaxhighlight>

In this data structure the <tt>shm_Method</tt> field would indicate the task to be performed. This can be a request to copy data or to store a log message. The <tt>shm_MsgSize</tt> field tells you how large the data structure is for future enhancements which may cause the data structure to grow.

==== Copying operations ====

For copying operations the message is:

<syntaxhighlight lang="C" line>
struct SANA2CopyHookMsg
{
ULONG schm_Method;
ULONG schm_MsgSize;

APTR schm_To;
APTR schm_From;
ULONG schm_Size;
};
</syntaxhighlight>

The structure members are as follows:

; schm_Method
: This must be one <tt>S2_CopyToBuff</tt>, <tt>S2_CopyFromBuff</tt>, <tt>S2_CopyToBuff16</tt>, <tt>S2_CopyFromBuff16</tt>, <tt>S2_CopyToBuff32</tt>, <tt>S2_CopyFromBuff32</tt>, <tt>S2_DMACopyToBuff32</tt>, <tt>S2_DMACopyFromBuff32</tt>, <tt>S2_DMACopyToBuff64</tt> or <tt>S2_DMACopyFromBuff64</tt> to identify the function to be performed.

; schm_MsgSize
: Size of this message data structure in bytes. This must be >= 20 for this message type.
: The driver shall set <tt>schm_MsgSize</tt> always correctly to be compliant. The protocol stack shall use this field to validate the message and to reject/ignore bad messages via a <tt>FALSE</tt> hook function return value. For DMA related hooks, a <tt>FALSE</tt> return value is equivalent to a <tt>NULL</tt> pointer.

; schm_To
: Equivalent to the <tt>to</tt> parameter of the <tt>CopyFromBuff</tt>, <tt>CopyToBuff</tt> and <tt>DMACopyToBuff</tt> functions.

; schm_From
: Equivalent to the <tt>from</tt> parameter of the <tt>CopyFromBuff</tt> and <tt>CopyToBuff</tt> functions.

; schm_Size
: Equivalent to the <tt>n</tt> parameter of the <tt>CopyFromBuff</tt>, <tt>CopyToBuff</tt>, functions.

==== Logging operations ====

For logging operations the message is:

<syntaxhighlight lang="C" line>
struct SANA2LogHookMsg
{
ULONG slhm_Method;
ULONG slhm_MsgSize;

ULONG slhm_Priority;
STRPTR slhm_Name;
STRPTR slhm_Message;
};
</syntaxhighlight>

The structure members would be used as follows:

; slhm_Method
: This must be <tt>S2_Log</tt>, as defined in the SANA-IIR4 specification.

; slhm_MsgSize
: Size of this message data structure in bytes. This must be >= 20 for this message type.
: The driver shall set <tt>slhm_MsgSize</tt> always correctly to be compliant. The protocol stack shall use this field to validate the message and to reject/ignore bad messages via a <tt>FALSE</tt> hook function return value. For DMA related hooks, a <tt>FALSE</tt> return value is equivalent to a <tt>NULL</tt> pointer.

; slhm_Priority
: The smaller this value, the more important the message to be logged or displayed. The following priority levels are defined (similar to the Unix syslog() mechanism):
:{| class="wikitable"
| S2LOG_Emergency || A panic condition.
|-
| S2LOG_Alert || A condition that should be corrected immediately.
|-
| S2LOG_Critical || Critical conditions.
|-
| S2LOG_Error || A plain error.
|-
| S2LOG_Warning || A warning message.
|-
| S2LOG_Notice || Conditions that are not error conditions, but should possibly be handled specially.
|-
| S2LOG_Information || An informational message.
|-
| S2LOG_Debug || Messages that contain information normally of use only when debugging.
|}
: Only these priority values may be used by a driver. It is suggested that a driver is configurable to generate different types of messages or not, e.g., a driver may be configured to only emit <tt>S2LOG_Emergency</tt> and <tt>S2LOG_Debug</tt> messages

; slhm_Name
: Pointer to a <tt>NUL</tt>-terminated string which identifies the source of this message. This can be <tt>NULL</tt> in which case the OS device name of the driver shall be used by the protocol stack.

; slhm_Message
: Pointer to a <tt>NUL</tt>-terminated string which contains the log message. The text should not contain any formatting characters such as line feeds or carriage returns. The <tt>slhm_Message</tt> member must never be <tt>NULL</tt>.
: All message texts shall preferably be formatted in the current user's locale. If that is not possible, the english language shall be used. <tt>slhm_Name</tt> and <tt>slhm_Message</tt> shall only contain printable characters.

=== Application and driver software use of the new functions ===

Since plenty of software exists which uses the 'traditional' <tt>TagItem</tt> list provided at <tt>OpenDevice()</tt> time, drivers must always examine these parameters and not expect a <tt>S2_SANA2HOOK</tt> command to be sent later.

If the new <tt>Hook</tt>-based callback functions are used then the driver must invoke the Hooks via <tt>utility.library/CallHookPkt</tt>. It must never invoke the hook functions through local assembly language stubs or the <tt>amiga.lib/CallHook</tt> and <tt>amiga.lib/CallHookA</tt> functions.

=== Caveats ===

The functionality above suggests that one could do entirely without the <tt>TagItem</tt> list passed in at <tt>OpenDevice()</tt> time. However, at this time it is hard to tell how existing driver software will react to empty <tt>TagItem</tt> lists or even a NULL pointer in the <tt>IOSana2Req->ios2_BufferManagement</tt> field. It is therefore important to always provide for a <tt>TagItem</tt> list which includes proper (i.e. they must point to working functions and may not be <tt>NULL</tt>) function pointers for the <tt>S2_CopyToBuff</tt> and <tt>S2_CopyFromBuff</tt> tags. Once the device has been opened successfully, the next step is to try and install the copy <tt>Hook</tt> through the proposed <tt>S2_SANA2HOOK</tt> command. If the command fails, the application can still expect that the <tt>S2_CopyToBuff</tt> and <tt>S2_CopyFromBuff</tt> tags supplied at <tt>OpenDevice()</tt> time will work.

== Packet filtering ==

With the original "SANA-II Network Device Driver Specification", a protocol stack could open a device and ask for certain packet types. It got all the packets that matched this type. As it turned out, this could be mighty inefficient if there were packets that the protocol stack did not use at all. These would go into read processing of the protocol stack and waste CPU time even though they could have been easily identified on arrival.

== Driver event logging ==

A driver may want to report an important event for the user to see. Adding a log message to a file or opening a window to display a message in may not be the optimum approach as the user may be unaware of the context into which the message belongs. It may be advisable for the driver to use the message reporting and logging facilities used by the client software that uses its services, such as a TCP/IP stack. The <tt>S2_Log</tt> callback hook is intended to provide for such a link.

If present, the driver must use this callback hook rather than whatever logging methods it implements itself. Note that unlike the other SANA-II callbacks, this is a regular hook, as to be invoked using <tt>utility.library</tt>/<tt>CallHookPkt()</tt>. The hook function is invoked using the following parameters:

<syntaxhighlight lang="C" line>
log_hook_function(hook, reserved, message)

void log_hook_function(struct hook * hook,APTR reserved,
struct S2LogMessage * message);
</syntaxhighlight>

The <tt>reserved</tt> parameter '''must''' be set to <tt>NULL</tt>. The <tt>S2LogMessage</tt> structure passed as the third parameter looks like this:

<syntaxhighlight lang="C" line>
struct S2LogMessage
{
LONG s2lm_Size;
ULONG s2lm_Priority;
STRPTR s2lm_Name;
STRPTR s2lm_Message;
};
</syntaxhighlight>

The individual structure members serve the following functions:

; s2lm_Size
: Size of the <tt>S2LogMessage</tt> structure, in bytes. The idea is to extend this data structure in the future, and the size stored in here tells you how long the structure is. The size '''must''' always be >= 16.

;s2lm_Priority
: The smaller this value, the more important the message to be logged or displayed. The following priority levels are defined (similar to the Unix <tt>syslog()</tt> mechanism):
:{| class="wikitable"
| S2LOG_Emergency || A panic condition.
|-
| S2LOG_Alert || A condition that should be corrected immediately.
|-
| S2LOG_Critical || Critical conditions.
|-
| S2LOG_Error || A plain error.
|-
| S2LOG_Warning || A warning message.
|-
| S2LOG_Notice || Conditions that are not error conditions, but should possibly be handled specially.
|-
| S2LOG_Information || An informational message.
|-
| S2LOG_Debug || Messages that contain information normally of use only when debugging.
|}

; s2lm_Name</tt>
: Pointer to a <tt>NUL</tt>-terminated string which identifies the source of this message. This can be <tt>NULL</tt> in which case the name is treated as being unknown.

; s2lm_Message
: Pointer to a <tt>NUL</tt>-terminated string which contains the log message. The text should not contain any formatting characters such as line feeds or carriage returns. The <tt>s2lm_Message</tt> member '''must never''' be <tt>NULL</tt>.

All error messages issued by the device driver should use the current system locale wherever this is possible. The purpose of an error message is, after all, to assist the user in recovering from the error. Which may be difficult if the user does not even know the language in which the message is written.

The log message string is valid until the log hook function returns. If the driver needs to retain the message any longer, it must make a copy of it.

Since the client software into which the log hook calls may have to allocate memory to hold and display the log message, the log hook '''must not''' be called from interrupt code. The log hook shall not <tt>Wait()</tt> and it shall assume only a <tt>Task</tt> calling context of unknown priority. <tt>dos.library</tt> functions may not be called. Also, stack space is provided only to call <tt>exec.library</tt> and <tt>utility.library</tt> functions. The callback shall not place excessive data on the stack. Stack space should be considered limited and the callback should be designed to be fast and short.

This hook is installed at <tt>OpenDevice()</tt> time, which means that the hook is used for the unit that was opened, and not just for the I/O request it was opened with. The hook must remain installed until the I/O request that installed it is eventually used to close the device. When this happens, the device should fall back to use no log hook at all. No nesting is permitted or required.

= Packet Type =

Network frames always have a type field associated with them. These type fields vary in length, position and meaning by frame type (frame types generally correspond one-to-one with hardware types, but see "Ethernet Packet Types" below). The meanings of the type numbers are always carefully defined and every type number is registered with some official body. Do not use a type number which is not registered for any standard hardware you use or in a manner inconsistent with that registration.

The type field allows the SANA-II device driver to fulfill CMD_READs based on the type of packet the driver user wants. Multiple protocols can therefore run over the same wire using the same driver without stepping on each other's toes.

Packet types are specified as a long word. Unfortunately, the type field means different things on different wires. Driver users must allow their software to be configured with a SANA-II device name, unit number and the type number(s) used by the protocol stack with each device. This way, if new hardware becomes available, a hardware manufacturer can supply a listing of type assignments to configure pre-existing software.

== Ethernet Packet Types ==

Ethernet has a special problem with packet types. Two types of ethernet frames can be sent over the same wire: ethernet and 802.3. These frames differ in that the Type field of an ethernet frame is the Length field of an 802.3 frame. This creates a problem in that demultiplexing incoming packets can be cumbersome and inefficient, as well as requiring driver users to be aware of the frame type used.

All 802.3 frames have numbers less than 1500 in the Type field. The only frames with numbers less than 1500 in the type field are 802.3 frames. SANA-II ethernet drivers abnormally return packets contained in ethernet frames when the requested Type falls within the 802.3 range-if the Type requested is within the 802.3 range, the driver returns the next packet contained within an 802.3 frame, regardless of the type specified for the packet within the 802.3 frame. This requires that there be no more than one driver user requesting 802.3 packets and that it do its own interpretation of the frames.

== ARCNET Frames ==

ARCNET also has a special problem with framing. ARCNET frames consist of a hardware header and a software header. The software header is in the data area of the hardware packet, and includes at least the protocol ID.

There are two types of software header. Old-style ARCNET software headers consist entirely of a one or two byte protocol ID. New ARCNET software headers (defined in RFC 1201 and in the paper "ARCNET Packet Header Definition Standard", Novell, Inc., 1989) include more information. They allow more efficient use of ARCNET through data link layer fragmentation and reassembly (ARCNET has a small Maximum Transmission Unit) and allow sending any size packet up to the MTU (rather than requiring that packets of size 253, 254 and 255 be padded to at least 256 bytes).

SANA-II device drivers for ARCNET should implement the old ARCNET packet headers. Driver users which wish to interoperate with platforms using the new software headers must add the new fields to the data to be sent and must process it for incoming data. A SANA-II driver which implemented the data link layer fragmentation internally (and advertised a large MTU) could be more efficient than requiring the driver user to do it. This would make driver writing more difficult and reduce interoperability, but if there is ever a demand for that extra performance, a new hardware type may be assigned by Amiga for SANA-II ARCNET device drivers which implement the new framing.

= Addressing =

In the SANA-II standard, network hardware addresses are stored in an array of ''n'' bytes. No meaning is ascribed by the standard to the contents of the array.

In case there exists a network which does not have an address field consisting of a number of bits not divisible by eight, add pad bits at the end of the bit stream. For example, if an address is ten bits long it will be stored like this:

<pre>
98765432 10PPPPPP
BYTE 0 BYTE 1
</pre>

Where the numerals are bit numbers and "P" is a pad (ignored) bit.

Driver users which do not implement the bit shifting necessary to use a network with such addressing (if one exists) should at least check the number of significant bits in the address field (returned from the device's S2_DEVICEQUERY function) to make sure that it is evenly divisible by eight.

Driver users will map hardware addresses to protocol addresses in a protocol and hardware dependent manner, as described by the relevant standards (i.e., RFC 826 for TCP/IP over Ethernet, RFC 1201 or RFC 1051 for TCP/IP over ARCNET). Some protocols will always use the same mapping on all hardware, but other protocols will have particular address mapping schemes for some particular hardware and a reasonable default for other (unknown) hardware.

Some SANA-II devices will have "hardware addresses" which aren't really hardware addresses. As an example, consider ''PPP'' (Point-to-Point Protocol). PPP is a standard for transmitting IP packets over a serial line. It uses IP addresses negotiated during the establishment of a connection. In a SANA-II driver implementation of PPP, the driver would negotiate the address at S2_CONFIGINTERFACE. Thus, the address in SrcAddr returned by the device on an S2_CONFIGINTERFACE (or in a subsequent S2_GETSTATIONADDRESS) will be a protocol address, not a true hardware address.

'''Note:''' Some hardware always uses a ROM hardware address. Other hardware which has a ROM address or is configurable with DIP switches may be overridden by software. Some hardware always dynamically allocates a new hardware address at initialization. See "Configuration" for details on how this is handled by driver writers and by driver users.

= Hardware Type =

The HardwareType returned by the device's S2_DEVICEQUERY function is necessary for those protocols whose standards require different behavior on different hardware. It is also useful for determining appropriate packet type numbers to use with the device. The HardwareType values already issued for standard network hardware are the same as those in RFC 1060 (assigned numbers). Hardware developers implementing networks without a SANA-II hardware number must contact the AmigaOS development team to have a new hardware type number assigned. Driver users should all have reasonable defaults which can be used for hardware with which they are not familiar.

= Errors =

The SANA-II extended IORequest structure (struct IOSana2Req) includes both the ios2_Error and ios2_WireError fields. Driver users must always check IOSana2Reqs on return for an error in ios2_Error. ios2_Error will be zero if no error occurred, otherwise it will contain a value from <exec/errors.h> or <devices/sana2.h>. If there was an error, there may be more specific information in ios2_WireError. Drivers are required to fill in the WireError if there is an applicable error code.

Error codes are #define'd in the "defined errors" sections of the file <devices/sana2.h>: 

{| class="wikitable"
! IOSana2Req S2io_Error field
! Description
|-
| S2ERR_NO_RESOURCES
| Insufficient resources available.
|-
| S2ERR_BAD_ARGUMENT
| Noticeably bad argument.
|-
| S2ERR_BAD_STATE
| Command inappropriate for current state.
|-
| S2ERR_BAD_ADDRESS
| Noticeably bad address.
|-
| S2ERR_MTU_EXCEEDED
| Write data too large.
|-
| S2ERR_NOT_SUPPORTED
| Command is not supported by this driver. This is similar to IOERR_NOCMD as defined in <exec/errors.h> but S2ERR_NOT_SUPPORTED indicates that the requested command is a valid SANA-II command and that the driver does not support it because the hardware is incapable of supporting it (e.g., S2_MULTICAST). Note that IOERR_NOCMD is still valid for reasons other than a lack of hardware support (i.e., commands which are no-ops in a SANA-II driver).
|-
| S2ERR_SOFTWARE
| Software error of some kind.
|-
| S2ERR_OUTOFSERVICE
| When a hardware device is taken off-line, any pending requests are returned with this error.
|}

See also the standard errors in <exec/errors.h>.

{| class="wikitable"
! IOSana2Req S2io_WireError field
! Description
! Value
|-
| S2WERR_NOT_CONFIGURED
| Command requires unit to be configured.
|-
| S2WERR_UNIT_ONLINE
| Command requires that the unit be off-line.
|-
| S2WERR_UNIT_OFFLINE
| Command requires that the unit be on-line.
|-
| S2WERR_ALREADY_TRACKED
| Protocol is already being tracked.
|-
| S2WERR_NOT_TRACKED
| Protocol is not being tracked.
|-
| S2WERR_BUFF_ERROR
| Buffer management function returned an error.
|-
| S2WERR_SRC_ADDRESS
| Problem with the source address field.
|-
| S2WERR_DST_ADDRESS
| Problem with destination address field.
|-
| S2WERR_BAD_BROADCAST
| Problem with an attempt to broadcast.
|-
| S2WERR_BAD_MULTICAST
| Problem with an attempt to multicast.
|-
| S2WERR_MULTICAST_FULL
| Multicast address list full.
|-
| S2WERR_BAD_EVENT
| Event specified is unknown.
|-
| S2WERR_BAD_STATDATA
| The ios2_StatData pointer or the data it points to failed a sanity check.
|-
| S2WERR_IS_CONFIGURED
| Attempt to reconfigure the unit.
|-
| S2WERR_NULL_POINTER
| A NULL pointer was detected in one of the arguments. S2ERR_BAD_ARGUMENT should always be the S2ERR.
|-
| S2WERR_UNIT_DISCONNECTED
| This error code is a counterpart to <tt>S2WERR_UNIT_OFFLINE</tt>. It indicates that the associated command could not be executed because the link layer is not connected.
| 19
|-
| S2WERR_UNIT_CONNECTED
| This error code is a counterpart to <tt>S2WERR_UNIT_ONLINE</tt>. It indicates that the associated command could not be executed because the link layer is already connected.
| 20
|-
| S2WERR_INVALID_OPTION
| This error code indicates that an option, such as passed by the <tt>S2_CONNECT</tt> command, is not acceptable. The option's value may be out of range or may not match the syntax specifications. To indicate which option that may be, a different mechanism '''must''' be used; a simple indication that something was wrong is '''not sufficient'''.
| 21
|-
| S2WERR_MISSING_OPTION
| This error code indicates that a mandatory option, such as passed by the <tt>S2_CONNECT</tt> command, is not present. To indicate which option that may be, a different mechanism '''must''' be used; a simple indication that something was wrong is '''not sufficient'''.
| 22
|-
| S2WERR_AUTHENTICATION_FAILED
| Some drivers run protocols that require them to authenticate to a server. That process may fail. This wire error code is to indicate this fact.
| 23
|}

= Standard Commands =

See the "SANA-II network device driver Autodocs" for full details on each of the SANA-II device commands. Extended commands are explained in the sections below.

Many of the Exec device standard commands are no-ops in SANA-II devices, but this may not always be the case. For example, CMD_RESET might someday be used for dynamically reconfiguring hardware. This should present no compatibility problems for properly written drivers.

== Broadcast and Multicast ==

Some hardware supports broadcast and/or multicast. A broadcast is a packet sent to all other machines. A multicast is a packet sent to a set of machines. Drivers for hardware which does not allow broadcast or multicast will return ios2_Error S2ERR_NOT_SUPPORTED as appropriate.

To send a broadcast, use S2_BROADCAST instead of CMD_WRITE. Broadcasts are received just like any other packets (using a CMD_READ for the appropriate packet type).

To send a multicast, use S2_MULTICAST instead of CMD_WRITE. The device keeps a list of addresses that want to receive multicasts. You add a receiver's address to this list by using S2_ADDMULTICASTADDRESS. The receiver then posts a CMD_READ for the type of packet to be received. Some SANA-II devices which support multicast may have a limit on the number of addresses that can simultaneously wait for packets. Always check for an S2WERR_MULTICAST_FULL error return when adding a multicast address.

Note that when the device adds a multicast address, it is usually added for all users of the device, not just the driver user which called S2_ADDMULTICASTADDRESS. In other words, received multicast packets will fill a read request of the appropriate type regardless of whether the requesting driver user is the same one which added the multicast address.

In general, driver users should not care how received packets were sent (normally or broadcast/multicast), only that it was received. If a driver user really must know, however, it can check for SANA2IOB_BCAST and/or SANA2IOB_MCAST in the ios2_Flags field.

Drivers should keep a count for the number of opens on a multicast address so that they don't actually remove it until it has been S2_DELMULTICASTADDRESS'd as many times as it has been S2_ADDMULTICASTADDRESS'd.

== Stats ==

There are many statistics which may be very important to someone trying to debug, tune or optimize a protocol stack, as well as to the end user who may need to tune parameters or investigate a problem. Some of these statistics can only be kept by the SANA-II driver, thus there are several required and optional statistics and commands for this purpose.

S2_TRACKTYPE tells the device driver to gather statistics for a particular packet type. S2_UNTRACKTYPE tells it to stop (keeping statistics by type causes the driver to use additional resources). S2_GETTYPESTATS returns any statistics accumulated by the driver for a type being tracked (stats are lost when a type is S2_UNTRACKTYPE'd). Drivers are required to implement the functionality of type tracking. The stats are returned in a struct Sana2PacketTypeStats:

<syntaxhighlight lang="C" line>
struct Sana2PacketTypeStats
{
ULONG PacketsSent;
ULONG PacketsReceived;
ULONG BytesSent;
ULONG BytesReceived;
ULONG PacketsDropped;
};
</syntaxhighlight>

; PacketsSent
: Number of packets of a particular type sent.
; PacketsReceived
: Number of packets of a particular type that satisfied a read command.
; BytesSent
: Number of bytes of data sent in packets of a particular type.
; BytesReceived
: Number of bytes of data of a particular packet type that satisfied a read command.
; PacketsDropped
: Number of packets of a particular type that were received while there were no pending reads of that packet type.

returns global statistics kept by the driver. Drivers are required to keep all applicable statistics. Since all are applicable to most hardware, most drivers will maintain all statistics. The stats are returned in a struct Sana2DeviceStats:

<syntaxhighlight lang="C" line>
struct Sana2DeviceStats
{
ULONG PacketsReceived;
ULONG PacketsSent;
ULONG BadData;
ULONG Overruns;
ULONG UnknownTypesReceived;
ULONG Reconfigurations;
struct timeval LastStart;
};
</syntaxhighlight>

; PacketsReceived
: Number of packets that this unit has received.
; PacketsSent
: Number of packets that this unit has sent.
; BadData
: Number of bad packets received (i.e., hardware CRC failed).
; Overruns
: Number of packets dropped due to insufficient resources available in the network interface.
; UnknownTypeReceived
: Number of packets received that had no pending read command with the appropriate packet type.
; Reconfigurations
: Number of network reconfigurations since this unit was last configured.
; LastStart
: The time when this unit last went on-line.

returns any special statistics kept by a particular driver. Each new wire type will have a set of documented, required statistics for that wire type and a standard set of optional statistics for that wire type (optional because they might not be available from all hardware). The data returned by S2_GETSPECIALSTATS will require wire-specific interpretation. See <devices/sana2specialstats.h> on page devicessana2specialstatspage for currently defined special statistics. The statistics are returned in the following structures:

<syntaxhighlight lang="C" line>
struct Sana2SpecialStatRecord
{
ULONG Type;
ULONG Count;
char * String;
};
</syntaxhighlight>

; Type
: Statistic identifier.
; Count
: Statistic itself.
; String
: An identifying, null-terminated string for the statistic. Should be plain ASCII with no formatting characters.

<syntaxhighlight lang="C" line>
struct Sana2SpecialStatHeader
{
ULONG RecordCountMax;
ULONG RecordCountSupplied;
struct Sana2SpecialStatRecord[RecordCountMax];
};
</syntaxhighlight>

; RecordCountMax
: There is space for this many records into which statistics may be placed.
; RecordCountSupplied
: Number of statistic records supplied.

is not, strictly speaking, a statistical function. It is a request to read any packet of a type for which there is no outstanding CMD_READ. S2_READORPHAN might be used in the same manner as many statistics, though, such as to determine what packet types are causing overruns, etc.

== Configuration ==

The device driver needs to configure the hardware before using it. The driver user must know some network hardware parameters (hardware address and MTU, for example) when using it. These commands address those needs.

When a driver user is initialized, it should try to S2_CONFIGINTERFACE even though an interface can only be configured once and someone else may have done it. Before you call S2_CONFIGINTERFACE, first call S2_GETSTATIONADDRESS to determine the factory address (if any). Also provide for user-override of the factory address (that address may be optional and the user may need to override it). When S2_CONFIGINTERFACE returns, check the ios2_SrcAddr for the actual address the hardware has been configured with. This is because some hardware (or serial line standards such as PPP) always dynamically allocates an address at initialization.

Driver users will want to use S2_DEVICEQUERY to determine the MTU and other characteristics of the network. The structure returned from S2_DEVICEQUERY is defined as:

<syntaxhighlight lang="C" line>
struct Sana2DeviceQuery
{
/*
** Standard information
*/
ULONG SizeAvailable; /* bytes available */
ULONG SizeSupplied; /* bytes supplied */
LONG DevQueryFormat; /* this is type 0 */
LONG DeviceLevel; /* this document is level 0 */

/*
** Common information
*/
UWORD AddrFieldSize; /* address size in bits */
ULONG MTU; /* maximum packet data size */
LONG BPS; /* line rate (bits/sec) */
LONG HardwareType; /* what the wire is */
ULONG RawMTU; /* maximum raw packet data size */

/*
** Format specific information
*/
};
</syntaxhighlight>

; SizeAvailable
: Size, in bytes, of the space available in which to place device information. This includes both size fields.
; SizeSupplied
: Size, in bytes, of the data supplied.
; DevQueryFormat
: The format defined here is format 0.
; DeviceLevel
: This spec defines level 0.
; AddrFieldSize
: The number of bits in an interface address.
; MTU
: Maximum Transmission Unit, the size, in bytes, of the maximum packet size, not including header and trailer information.
; BPS
: Best guess at the raw line rate for this network in bits per second.

; HardwareType
: Specifies the type of network hardware the driver controls.

; RawMTU
: The <tt>RawMTU</tt> member is new as of SANA-II Revision 4. Devices which do not know and support this structure member may fill in the <tt>Sana2DeviceQuery</tt> structure only up to and including the <tt>HardwareType</tt> member.

: In this context 'raw' means the number of bytes that are available for reading and writing when using the <tt>SANA2IOB_RAW</tt> flag with a <tt>CMD_READ</tt>/<tt>CMD_WRITE</tt> request on a device that supports these access methods. Currently, software developers can only make assumptions on how many bytes might comprise the 'raw' MTU by checking the <tt>Sana2DeviceQuery.HardwareType</tt> member and hoping that the driver supports raw <tt>CMD_READ</tt>/<tt>CMD_WRITE</tt> access.

: Devices which know and support the <tt>RawMTU</tt> member must fill it with a well-defined value. For Amiga Ethernet drivers, that value would be 1514, which is the standard MTU value of 1500 bytes plus the size of the Ethernet frame header, as per RFC894 (six bytes for the destination address, six bytes for the source address and two bytes for the frame type; the eight byte preamble and the terminating four byte CRC value are typically not under the control of the driver). Drivers which do not support raw read or write access must set the <tt>RawMTU</tt> member to zero.

: If the <tt>RawMTU</tt> member is not provided, all bets are off and the application software must fall back to making estimates based upon the hardware type and the raw frame types it wishes to read and write. Ultimatively, the driver itself must decide whether it can accept raw read and write commands (or has to reject them with <tt>S2ERR_NOT_SUPPORTED</tt>) and whether the raw packet size is still covered by the underlying hardware MTU (or must be rejected with <tt>S2ERR_MTU_EXCEEDED</tt>).

: A word of warning: a little testing with various Ethernet hardware drivers has revealed that the A2065 driver <tt>a2065.device</tt> does not handle the <tt>S2_DEVICEQUERY</tt> command properly if the <tt>Sana2DeviceQuery</tt> structure provided is larger than 30 bytes. In other words, the command will fail if the proposed <tt>RawMTU</tt> member is present in the query data structure to be filled in.

== On-line ==

In order to run hardware tests on an otherwise live system, the S2_OFFLINE command allows the SANA-II device driver to be "turned off" until the tests are complete and an S2_ONLINE is sent to the driver. S2_ONLINE causes the interface to re-configure and re-initialize. Any packets destined for the hardware while the device is off-line will be lost. All pending and new requests to the driver shall be returned with S2ERR_OUTOFSERVICE when a device is off-line.

All driver users must understand that any IO request may return with S2ERR_OUTOFSERVICE because the driver is off-line (any other program may call S2_OFFLINE to make it so). In such an event, the driver will usually want to wait until the unit comes back on-line (for the program which called S2_OFFLINE to call S2_ONLINE). It may do this by calling S2_ONEVENT to wait for S2EVENT_ONLINE. S2_ONEVENT allows the driver user to wait on various events.

A driver must track events, but may not distinguish between some types of events. Drivers return S2_ONEVENT with S2ERR_NOT_SUPPORTED and S2WERR_BAD_EVENT for unsupported events. One error may cause more than one event (see below). Errors which seem to have been caused by a malformed or unusual request should not generally trigger an event. 

{| class="wikitable"
! Event type
! Description
|-
| S2EVENT_ERROR
| Return when any error occurs.
|-
| S2EVENT_TX
| Return on any transmit error (always an error).
|-
| S2EVENT_RX
| Return on any receive error (always an error).
|-
| S2EVENT_ONLINE
| Return when unit goes on-line or return immediately if unit is already on-line (not an error).
|-
| S2EVENT_OFFLINE
| Return when unit goes off-line or return immediately if unit is already off-line (not an error.)
|-
| S2EVENT_BUFF
| Return on any buffer management function error (always an error).
|-
| S2EVENT_HARDWARE
| Return when any hardware error occurs (always an error, may be a S2EVENT_TX or S2EVENT_RX, too).
|-
| S2EVENT_SOFTWARE
| Return when any software error occurs (always an error, may be a S2EVENT_TX or S2EVENT_RX, too).
|-
| S2EVENT_CONFIGCHANGED
| Return when client-visible configuration information changes (not an error).
|-
| S2EVENT_CONNECT
| Return when the driver has successfully established a link layer connection (not an error).
|-
| S2EVENT_DISCONNECT
| Return when the driver has closed the link layer connection previously established by the S2_CONNECT command (not an error).
|}

=== S2EVENT_CONFIGCHANGED ===

For drivers such as those which implement the <tt>S2_GETPEERADDRESS</tt> and <tt>S2_GETDNSADDRESS</tt> commands it is vital that such changes can take place and be noticed by the client software. For this purpose a new event type is introduced, to be used with the SANA-II <tt>S2_ONEVENT</tt> command, using the following definition:

<tt>#define S2EVENT_CONFIGCHANGED (1L<<8)</tt>

This event should be triggered whenever client-visible configuration information changes, as can be queried via the <tt>S2_DEVICEQUERY</tt>, <tt>S2_GETSTATIONADDRESS</tt>, <tt>S2_GETSPECIALSTATS</tt>, <tt>S2_GETGLOBALSTATS</tt>, <tt>S2_GETPEERADDRESS</tt> and <tt>S2_GETDNSADDRESS</tt> commands. Here is a short list of what could change:

# S2_DEVICEQUERY: <tt>AddrFieldSize</tt>, <tt>MTU</tt>, <tt>BPS</tt>
# S2_GETSTATIONADDRESS: <tt>ios2_SrcAddr</tt>
# S2_GETGLOBALSTATS: <tt>Reconfigurations</tt>, <tt>LastStart</tt>
# S2_GETPEERADDRESS: <tt>ios2_SrcAddr</tt>, <tt>ios2_DstAddr</tt>
# S2_GETDNSADDRESS: <tt>ios2_SrcAddr</tt>, <tt>ios2_DstAddr</tt>

The purpose of this event '''is not''' to post a notification whenever another byte or event counter has changed so that a monitoring program may update its display. The purpose '''is''' to convey to the client software that an important device configuration option has changed and that it is supposed to react and adapt to it. For example, a TCP/IP stack may, upon learning that a device's IP address has changed, rebuild its routing table.

Since the <tt>S2EVENT_CONFIGCHANGED</tt> event may arrive at any time and does not indicate what exactly has changed, application software should query the information it expects to change during its life time, and keep a copy of it around for later reference. When the <tt>S2EVENT_CONFIGCHANGED</tt> event arrives, it can compare the contents of the copy against the current state of affairs and act according to the differences it finds.

=== S2EVENT_CONNECT ===

This event is a counterpart to <tt>S2EVENT_ONLINE</tt>, and is associated with the <tt>S2_CONNECT</tt> command. It has the following semantics:

<tt>#define S2EVENT_CONNECT (1L<<9) /* Driver has opened session */</tt>

The event is to be sent when the driver has successfully established a link layer connection.

=== S2EVENT_DISCONNECT ===

This event is a counterpart to <tt>S2EVENT_OFFLINE</tt>, and is associated with the <tt>S2_DISCONNECT</tt> command. It has the following semantics:

<tt>#define S2EVENT_DISCONNECT (1L<<10) /* Driver has closed session */</tt>

The event is to be sent when the driver has closed the link layer connection previously established by the <tt>S2_CONNECT</tt> command.

== S2_ONLINE and S2_OFFLINE ==

The <tt>S2_CONNECT</tt> and <tt>S2_DISCONNECT</tt> commands are somewhat related to the <tt>S2_ONLINE</tt> and <tt>S2_OFFLINE</tt> commands. How this relation works out shall be explained below. Note that the following text assumes that both the <tt>S2_CONNECT</tt>/<tt>S2_DISCONNECT</tt> and <tt>S2_ONLINE</tt>/<tt>S2_OFFLINE</tt> command pairs are implemented.

<tt>S2_CONNECT</tt> implies <tt>S2_ONLINE</tt> and, if successful, may report <tt>S2EVENT_ONLINE</tt> and <tt>S2EVENT_CONNECT</tt> events. If the unit is currently disconnected, but still online, only the <tt>S2EVENT_CONNECT</tt> event shall be sent. Invoking the <tt>S2_CONNECT</tt> command on a driver which is already connected must be rejected with <tt>ios2_Req.io_Error=S2ERR_BAD_STATE</tt> and <tt>ios2_WireError=S2WERR_UNIT_CONNECTED</tt>.

<tt>S2_DISCONNECT</tt> implies <tt>S2_OFFLINE</tt> and, if successful, may report <tt>S2EVENT_OFFLINE</tt> and <tt>S2EVENT_DISCONNECT</tt> events. If the unit is currently connected and offline, then only the <tt>S2EVENT_DISCONNECT</tt> event shall be sent. Invoking the <tt>S2_DISCONNECT</tt> command on a driver which is already disconnected must be rejected with <tt>ios2_Req.io_Error=S2ERR_BAD_STATE</tt> and <tt>ios2_WireError=S2WERR_UNIT_DISCONNECTED</tt>.

<tt>S2_OFFLINE</tt> may be used after the <tt>S2_CONNECT</tt> has successfully connected the unit. In this case the driver will release control over the link layer and report the <tt>S2EVENT_OFFLINE</tt> event. The connection established using the <tt>S2_CONNECT</tt> will, however, persist.

<tt>S2_ONLINE</tt> may be used after <tt>S2_CONNECT</tt> has successfully connected the unit and the <tt>S2_OFFLINE</tt> was used. In this case the driver will again try to obtain control over the link layer and report the <tt>S2EVENT_ONLINE</tt> event if successful.

If the <tt>S2_CONNECT</tt> command was never successfully executed, then the commands <tt>S2_ONLINE</tt> and <tt>S2_OFFLINE</tt> must be rejected with <tt>ios2_Req.io_Error=S2ERR_BAD_STATE</tt> and <tt>ios2_WireError=S2WERR_UNIT_DISCONNECTED</tt>.

== Wireless (IEEE 802.11) ==

Several new commands have been added to the SANA-II API to facilitate use of IEEE 802.11 wireless network devices in client and ad-hoc modes. The new commands are split into two overlapping sets. One set needs to be implemented by drivers for Soft-MAC wireless devices, while the other is implemented for Hard-MAC devices.

{| class="wikitable"
! Soft-MAC commands
|-
| S2_SETOPTIONS
|-
| S2_SETKEY
|-
| S2_WRITEMGMT
|-
| S2_READMGMT
|}

{| class="wikitable"
! Hard-MAC commands
|-
| S2_SETOPTIONS
|-
| S2_SETKEY
|-
| S2_GETNETWORKS
|-
| S2_GETNETWORKINFO
|-
| S2_GETSIGNALQUALITY
|}

=== sana2wireless.h ===

<syntaxhighlight lang="C" line>
#ifndef DEVICES_SANA2WIRELESS_H
#define DEVICES_SANA2WIRELESS_H

#include <exec/types.h>
#include <utility/tagitem.h>

/* Constants */
/* ========= */

/* Tags to get and set information */

#define S2INFO_SSID (TAG_USER + 0)
#define S2INFO_BSSID (TAG_USER + 1)
#define S2INFO_AuthTypes (TAG_USER + 2)
#define S2INFO_AssocID (TAG_USER + 3)
#define S2INFO_Encryption (TAG_USER + 4)
#define S2INFO_PortType (TAG_USER + 5)
#define S2INFO_BeaconInterval (TAG_USER + 6)
#define S2INFO_Channel (TAG_USER + 7)
#define S2INFO_Signal (TAG_USER + 8)
#define S2INFO_Noise (TAG_USER + 9)
#define S2INFO_Capabilities (TAG_USER + 10)
#define S2INFO_InfoElements (TAG_USER + 11)
#define S2INFO_WPAInfo (TAG_USER + 12)
#define S2INFO_Band (TAG_USER + 13)
#define S2INFO_DefaultKeyNo (TAG_USER + 14)

/* Wireless Commands */

#define S2_GETSIGNALQUALITY 0xc010
#define S2_GETNETWORKS 0xc011
#define S2_SETOPTIONS 0xc012
#define S2_SETKEY 0xc013
#define S2_GETNETWORKINFO 0xc014
#define S2_READMGMT 0xc015
#define S2_WRITEMGMT 0xc016
#define S2_GETRADIOBANDS 0xc017

/* Encryption types */

#define S2ENC_NONE 0
#define S2ENC_WEP 1
#define S2ENC_TKIP 2
#define S2ENC_CCMP 3

/* Radio modes */

#define S2BAND_A 0
#define S2BAND_B 1
#define S2BAND_G 2
#define S2BAND_N 3

/* Network topologies */

#define S2PORT_MANAGED 7
#define S2PORT_ADHOC 8

/* Structures */
/* ========== */

/* Structure for returning signal quality */

struct Sana2SignalQuality
{
LONG SignalLevel; /* signal level in dBm */
LONG NoiseLevel; /* noise level in dBm */
};

#endif
</syntaxhighlight>

= Driver requirements =

This section is an attempt to clarify parts of the specification and to lay down a few rules that every SANA-II driver must follow.

* A driver that does not use a broadcast medium, such as Ethernet, must not implement the <tt>S2_BROADCAST</tt> command. Likewise, if no multicast mechanism is supported, the <tt>S2_MULTICAST</tt> must not be implemented either.

* SANA-II standard commands which the driver does not implement must be rejected with the <tt>IOERR_NOCMD</tt> error code. Commands that are implemented, but which cannot perform the requested services, must be rejected with the <tt>S2ERR_NOT_SUPPORTED</tt> error code. The difference between the two cases is in when the decision is made whether a command can be handled or not. Which commands should return <tt>IOERR_NOCMD</tt> is decided upon at the time the driver is designed and implemented. At this stage the implementer knows for sure which capabilities the driver will have and which it will not have. Commands which the driver will never be able to execute will be made to return the <tt>IOERR_NOCMD</tt> error code. If the decision whether a command can be executed is made only at run time, by evaluating the conditions under which a command can be executed, then the error code <tt>S2ERR_NOT_SUPPORTED</tt> should be returned in case of failure.

* It must be possible to open the driver with an ordinary <tt>struct IOStdReq</tt>. This is necessary for the NewStyleDevices query command to work. In the command dispatcher, the driver must verify that all SANA-II commands are invoked with a proper size <tt>struct IOSana2Req</tt> I/O request. If the I/O request is shorter (as can be verified by looking at the embedded Message's <tt>mn_Length</tt> member), the command must be rejected with <tt>ios2_Req.io_Error=IOERR_BADLENGTH</tt>.

* A driver must implement the NewStyleDevices <tt>NSCMD_DEVICEQUERY</tt> command, in conformance with the NSD specification 1.6 or newer. The motivation for this is to have a mechanism available for probing the capabilities of the driver, and the supported command set can provide for vital clues. In this context, the absence of the <tt>S2_BROADCAST</tt> command would suggest that the driver cannot send or receive broadcast messages.

* A driver that does not allow its station address to be set with the <tt>S2_CONFIGINTERFACE</tt> command may silently ignore the command (returning it without setting an error condition) and even pretend that it can be configured more than once.

* In response to the <tt>S2_DEVICEQUERY</tt>, <tt>S2_GETSPECIALSTATS</tt> and <tt>S2_GETGLOBALSTATS</tt> commands a driver may return information that is not entirely correct if it has to go online before it can provide for the correct data. For example, the maximum transmission unit for PPP is a number in the range of [1..1500] which is negotiated during the protocol configuration process. It is unlikely that numbers greater than 1500 will be used, yet it is still not impossible. Since the actual number will be known only after the driver has configured the protocol, the MTU value returned before the session was opened can differ from the MTU value valid after it has been opened. A driver should therefore attempt to return 'safe' defaults in place of information that is unavailable at the time it is queried. The 'safe' values shall be set up to allow the driver to work even if the protocol stack is not aware of later changes to those values. Beware of zero-length buffer sizes or time intervals that may cause client software to perform zero-length memory allocations or divisions by zero.

* SANA-II assigns packet type numbers according to the underlying transport media. For example, Ethernet uses packet type 2048 for IP frames. No such packet type definition exists for PPP yet, which is why this standard proposes to assign packet type 31 for IP packets transmitted via PPP. To simplify client software configuration, drivers may treat packet type 2048 as equivalent to the packet number associated with IP frames. This association is permitted only if it does not introduce ambiguity. For example, this association would not be permitted if the driver would receive and transmit IP packets in two different frame types or if the driver already associates packet type 2048 with non-IP packets.

= Driver Installation =

The standard system location for SANA-II network device driver is in a directory called "Networks" which exists in the "DEVS:" directory.

Example:

<blockquote>
DEVS:Networks/eth3com.device
</blockquote>

This is the official location for the drivers. It may be necessary for your install program/script to create this directory if it doesn't exist in a user's system.

= Unresolved Issues =

* Unfortunately, it isn't possible to completely isolate network protocols from the hardware they run on. Hardware types and addressing both remain somewhat hardware-dependent in spite of our efforts. See the "Packet Type" section for an explanation of how packet types are handled and why protocols cannot be isolated from them. See the "Addressing" section for an explanation of how addressing is handled any why protocols cannot be isolated from it.

* Additionally, there are at least two cases where a hardware type has multiple framing methods in use (ethernet/802.3 and arcnet/(Novell) "ARCNET Packet Header Definition Standard"). In both cases, software which must interoperate with other platforms on this hardware may need to be aware of the distinctions and may have to do extra processing in order to use the appropriate frame type. See the sections on "Ethernet Packet Types" and on "ARCNET frames" for more details.

* Protocols like PPP can provide both for IPv4 and IPv6 addresses that should be used by the local client, the peer or any of the domain name servers. While the two addressing families are interoperable, there is a problem in how the driver should report them. Can you assume 128 bit addresses and encapsulate 32 bit addresses in them? If so, how do you make sure that the address format is unambiguous?

* Currently, only the device's hardware type provides a clue as to what packet type responds to which protocol transported via the link. For Ethernet, IP packets are encapsulated in type 2048 frames, PPP encapsulates IP packets in type 31 frames, Arcnet can use type 240 or 212. Matching a protocol with a frame type is not an easy process which could be handled more elegantly.

* How to extend the <tt>Sana2DeviceQuery</tt> structure in the future? The current layout separates standard, common and format specific information, but there is no hint as to where which each section starts and where the next begins. Now that there is a proposal to add a new field to the common section, how would you add fields to the format specific section?

= SANA-II network device driver Autodocs =

== AbortIO ==

<pre>
NAME
AbortIO -- Remove an existing device request.

SYNOPSIS
error = AbortIO(Sana2Req)
D0 A1

LONG AbortIO(struct IOSana2Req *);

FUNCTION
This is an exec.library call.

This function aborts an ioRequest. If the request is active, it may or
may not be aborted. If the request is queued it is removed. The
request will be returned in the same way as if it had normally
completed. You must WaitIO() after AbortIO() for the request to
return.

INPUTS
Sana2Req - Sana2Req to be aborted.

RESULTS
error - Zero if the request was aborted, non-zero otherwise.
io_Error in Sana2Req will be set to IOERR_ABORTED
if it was aborted.

SEE ALSO
exec.library/AbortIO(), exec.library/WaitIO()
</pre>

== CloseDevice ==

<pre>
NAME
CloseDevice -- Close the device.

SYNOPSIS
CloseDevice(Sana2Req)
A1

void CloseDevice(struct IOSana2Req *);

FUNCTION
This function is called by exec.library CloseDevice().

This function performs whatever cleanup is required at device closes.

Note that all IORequests MUST be complete before closing. If any are
pending, your program must AbortIO() then WaitIO() each outstanding
IORequest to complete them.

INPUTS
Sana2Req - Pointer to IOSana2Req initialized by OpenDevice().

SEE ALSO
exec.library/CloseDevice(), exec.library/OpenDevice()
</pre>

== CMD_CLEAR ==

<pre>
NAME
CMD_CLEAR -- Clear internal network interface read buffers.

FUNCTION
There are no device internal buffers, so CMD_CLEAR does not apply to
this class of device.

IO REQUEST
ios2_Command - CMD_CLEAR.

RESULTS
ios2_Error - IOERR_NOCMD.
</pre>

== CMD_FLUSH ==

<pre>
NAME
CMD_FLUSH -- Clear all queued I/O requests for the SANA-II device.

FUNCTION
This command aborts all I/O requests in both the read and write
request queues of the device. All pending I/O requests are
returned with an error message (IOERR_ABORTED). CMD_FLUSH does not
affect active requests.

IO REQUEST
ios2_Command - CMD_FLUSH.

RESULTS
ios2_Error - Zero if successful; non-zero otherwise.
</pre>

== CMD_INVALID ==

<pre>
NAME
CMD_INVALID -- Return with error IOERR_NOCMD.

FUNCTION
This command causes device driver to reply with an error IOERR_NOCMD
as defined in <exec/errors.h> indicating the command is not supported.

IO REQUEST
ios2_Command - CMD_INVALID.

RESULTS
ios2_Error - IOERR_NOCMD.

BUGS
Not known to be useful.
</pre>

== CMD_READ ==

<pre>
NAME
CMD_READ -- Get a packet from the network.

FUNCTION
Get the next packet available of the requested packet type. The data
copied (via a call to the requestor-provided CopyToBuffer function)
into ios2_Data is normally the Data Link Layer packet data only. If
bit SANA2IOB_RAW is set in ios2_Flags, then the entire physical frame
will be returned.

Unlike most Exec devices, SANA-II device drivers do not have internal
buffers. If you wish to read data from a SANA-II device you should
have multiple CMD_READ requests pending at any given time. The
functions provided by you the requestor will be used for any incoming
packets of the type you've requested. If no read requests are
outstanding for a type which comes in and no read_orphan requests are
outstanding, the packet will be lost.

IO REQUEST
ios2_Command - CMD_READ
ios2_Flags - Supported flags are:
SANA2IOB_RAW
SANA2IOB_QUICK
ios2_PacketType - Packet type desired.
ios2_Data - Abstract data structure to hold packet data.

RESULTS
ios2_Error - Zero if successful; non-zero otherwise.
ios2_WireError - More specific error number.
ios2_Flags - The following flags may be returned:
SANA2IOB_RAW
SANA2IOB_BCAST
SANA2IOB_MCAST
ios2_SrcAddr - Source interface address of packet.
ios2_DstAddr - Destination interface address of packet.
ios2_DataLength - Length of packet data.
ios2_Data - Abstract data structure which packet data is
contained in.

NOTES
The driver may not directly examine or modify anything pointed to by
ios2_Data. It *must* use the requester-provided functions to access
this data.

SEE ALSO
S2_READORPHAN, CMD_WRITE, any_protocol/CopyToBuffer
</pre>

== CMD_RESET ==

<pre>
NAME
CMD_RESET -- Reset the network interface to initialized state.

FUNCTION
Currently, SANA-II devices can only be configured once (with
CMD_CONFIGINTERFACE) and cannot be re-configured, hence,
CMD_RESET does not apply to this class of device.

IO REQUEST
ios2_Command - CMD_RESET.

RESULTS
ios2_Error - IOERR_NOCMD.
</pre>

== CMD_START ==

<pre>
NAME
CMD_START -- Restart device operation.

FUNCTION
There is no way for the driver to keep queuing requests without
servicing them, so CMD_STOP does not apply to this class of device.
S2_OFFLINE and S2_ONLINE do perform a similar function to CMD_STOP
and CMD_START

IO REQUEST
ios2_Command - CMD_START.

RESULTS
ios2_Error - IOERR_NOCMD.

SEE ALSO
S2_ONLINE, S2_OFFLINE
</pre>

== CMD_STOP ==

<pre>
NAME
CMD_STOP -- Pause device operation.

FUNCTION
There is no way for the driver to keep queuing requests without
servicing them, so CMD_STOP does not apply to this class of device.
S2_OFFLINE and S2_ONLINE do perform a similar function to CMD_STOP
and CMD_START

IO REQUEST
ios2_Command - CMD_STOP.

RESULTS
ios2_Error - IOERR_NOCMD.

NOTES

SEE ALSO
S2_ONLINE, S2_OFFLINE
</pre>

== CMD_UPDATE ==

<pre>
NAME
CMD_UPDATE -- Force packets out to device.

FUNCTION
Since there are no device internal buffers, CMD_UPDATE does not
apply to this class of device.

IO REQUEST
ios2_Command - CMD_UPDATE.

RESULTS
ios2_Error - IOERR_NOCMD.
</pre>

== CMD_WRITE ==

<pre>
NAME
CMD_WRITE -- Send packet to the network.

FUNCTION
This command causes the packet to be sent to the specified network
interface. Normally, appropriate packet header and trailer information
will be added to the packet data when it is sent. If bit SANA2IOB_RAW
is set in io_Flags, then the ios2_Data is assumed to contain an entire
physical frame and will be sent (copied to the wire via
CopyFromBuffer() unmodified.

Note that the device should not check to see if the destination
address is on the local hardware. Network protocols should realize
that the packet has a local destination long before it gets to a
SANA-II driver.

IO REQUEST
ios2_Command - CMD_WRITE.
ios2_Flags - Supported flags are:
SANA2IOB_RAW
SANA2IOB_QUICK
ios2_PacketType - Packet type to send.
ios2_DstAddr - Destination interface address for this packet.
ios2_DataLength - Length of the Data to be sent.
ios2_Data - Abstract data structure which packet data is
contained in.

RESULTS
ios2_Error - Zero if successful; non-zero otherwise.
ios2_WireError - More specific error number.

NOTES
The driver may not directly examine or modify anything pointed to by
ios2_Data. It *must* use the requester-provided functions to access
this data.

SEE ALSO
CMD_READ, S2_BROADCAST, S2_MULTICAST, any_protocol/CopyFromBuffer
</pre>

== OpenDevice ==

<pre>
NAME
Open -- Request an opening of the network device.

SYNOPSIS
error = OpenDevice(unit, IOSana2Req, flags)
D0 D0 A1 D1

BYTE OpenDevice(ULONG, struct IOSana2Req *, ULONG);

FUNCTION
This function is called by exec.library OpenDevice().

This function performs whatever initialization is required per
device open and initializes the Sana2Req for use by the
device.

INPUTS
unit - Device unit to open.
Sana2Req - Pointer to IOSana2Req structure to be initialized by
the sana2.device.
flags - Supported flags are:
SANA2OPB_MINE
SANA2OPB_PROM
ios2_BufferManagement - A pointer to a tag list containing
pointers to buffer management functions.

RESULTS
error - same as io_Error
io_Error - Zero if successful; non-zero otherwise.
io_Device - A pointer to whatever device will handle the calls
for this unit. This pointer may be different
depending on what unit is requested.
ios2_BufferManagement - A pointer to device internal information
used to call buffer management functions.

NOTES
A SANA-II device must reject all open requests with a request
structure that is too short, e.g. an IOStdReq. A simple check of the
mn_Length field in the Message part of the request is needed to make
sure that a device does not dereference invalid data due to a wrong
device configuration.

A SANA-II device may open if no buffer management tags are provided to
make the configuration process and obtaining statistics easier. Buffer
management tags with a NULL value must be treated as not specified.
The device shall fail requests gracefully depending on the missing
tags in this case. Any malfunction is not acceptable.

SEE ALSO
exec.library/OpenDevice(), exec.library/CloseDevice()
</pre>

== S2_ADDMULTICASTADDRESS ==

<pre>
NAME
S2_ADDMULTICASTADDRESS -- Enable an interface multicast address.

FUNCTION
This command causes the device driver to enable multicast packet
reception for the requested address.

IO REQUEST
ios2_Command - S2_ADDMULTICASTADDRESS.
ios2_SrcAddr - Multicast address to enable.

RESULTS
ios2_Error - Zero if successful; non-zero otherwise.
ios2_WireError - More specific error number.

NOTES
Multicast addresses are added globally -- anyone using the device
may receive packets as a result of any multicast address which has
been added for the device.

Since multicast addresses are not "bound" to a particular packet type,
each enabled multicast address has an "enabled" count associated with
it so that if two protocols add the same multicast address and later
one removes it, it is still enabled until the second removes it.

SEE ALSO
S2_MULTICAST, S2_DELMULTICASTADDRESS
</pre>

== S2_BROADCAST ==

<pre>
NAME
S2_BROADCAST -- Broadcast a packet on network.

FUNCTION
This command works the same as CMD_WRITE except that it also performs
whatever special processing of the packet is required to do a
broadcast send. The actual broadcast mechanism is neccessarily
network/interface/device specific.

IO REQUEST
ios2_Command - S2_BROADCAST.
ios2_Flags - Supported flags are:
SANA2IOB_RAW
SANA2IOB_QUICK
ios2_PacketType - Packet type to send.
ios2_DataLength - Length of the Data to be sent.
ios2_Data - Abstract data structure which packet data is
contained in.

RESULTS
ios2_DstAddr - The contents of this field are to be
considered trash upon return of the IOReq.
ios2_Error - Zero if successful; non-zero otherwise.
This command can fail for many reasons and
is not supported by all networks and/or
network interfaces.
ios2_WireError - More specific error number.

NOTES
The DstAddr field may be trashed by the driver because this function
may be implemented by filling DstAddr with a broadcast address and
internally calling CMD_WRITE.

SEE ALSO
CMD_WRITE, S2_MULTICAST
</pre>

== S2_CONFIGINTERFACE ==

<pre>
NAME
S2_CONFIGINTERFACE -- Configure the network interface.

FUNCTION
This command causes the device driver to initialize the interface
hardware and to set the network interface address to the address in
ios2_SrcAddr. This command can only be executed once and, if
successful, will leave the driver and network interface fully
operational and the network interface in ios2_SrcAddr.

To set the interface address to the factory address, the network
management software must use GetStationAddress first and then call
ConfigInterface with the result. If there is no factory address then
the network software must pick an address to use.

Until this command is executed the device will not listen for any
packets on the hardware.

IO REQUEST
ios2_Command - S2_CONFIGINTERFACE.
ios2_Flags - Supported flags are:
SANA2IOB_QUICK
ios2_SrcAddr - Address for this interface.

RESULTS
ios2_Error - Zero if successful; non-zero otherwise.
ios2_WireError - More specific error number.
ios2_SrcAddr - Address of this interface as configured.

NOTES
Some networks have the interfaces choose a currently unused interface
address each time the interface is initialized. The caller must check
ios2_SrcAddr for the actual interface address after configuring the
interface.

SEE ALSO
S2_GETSTATIONADDRESS
</pre>

== S2_CONNECT ==

The driver model specified by the SANA-II standard really only covers networking hardware well. Software-only drivers, such as for dial-up networking, are, well, somehow mentioned in the standard, but they don't receive much attention. In particular, this means that a networking driver is assumed to be practically always attached to its link layer and no provisions exist to specify what kind of link layer that might be and how it might be accessed. This small oversight can probably be explained by the fact that at the time the SANA-II standard was adopted, dial-up networking had not yet gained the prominence it has today.

To bridge this gap, I propose a new command which will make a driver connect to its link layer and go online, which uses the following data structure:

<syntaxhighlight lang="C" line>
struct Sana2Connection
{
ULONG s2c_Size;
struct MinList s2c_Options;
struct Hook s2c_ErrorHook;
struct Hook s2c_ConnectHook;
struct Hook s2c_DisconnectHook;
STRPTR s2c_Login;
STRPTR s2c_Password;
};
</syntaxhighlight>

The individual structure members have the following purposes:

<tt>s2c_Size</tt>

The size of the entire data structure is stored here. This value '''must''' be >= 84. Smaller values '''must''' be rejected with <tt>ios2_Req.io_Error</tt>=<tt>IOERR_BADLENGTH</tt>. The purpose of <tt>s2c_Size</tt> is to allow for future expansion during which the structure may grow in size.

<tt>s2c_Options</tt>

This list contains options, to be used during the connection process. Each node has the following format:

<syntaxhighlight lang="C" line>
struct Sana2ConnectionOption
{
struct MinNode s2co_MinNode;
STRPTR s2co_Name;
STRPTR s2co_Value;
};
</syntaxhighlight>

The <tt>s2co_Name</tt> and <tt>s2co_Value</tt> entries point to <tt>NUL</tt>-terminated strings, which contain the name and the value of a parameter. ''Note that for numeric values, the respective number will be encoded in a text string.'' A number of parameters are reserved, which are [[#s2c_options|listed later]] in this text.

<tt>s2c_ErrorHook</tt>

This hook is called whenever an error message is to be reported during the connection/disconnection process. The hook function is invoked using the following parameters:

<pre>error_hook_func(hook,reserved,message);

VOID error_hook_func(struct Hook *hook,APTR reserved,
STRPTR message);</pre>
The <tt>reserved</tt> parameter '''must''' be <tt>NULL</tt>. The <tt>message</tt> parameter points to a <tt>NUL</tt>-terminated string. It '''must not''' be <tt>NULL</tt>.

Because the hook function may have to allocate memory, it '''must not''' be called from interrupt code.

<tt>s2c_ConnectHook</tt>

This hook is called when the link level device has been set up, but further initializations are necessary, such as telling a modem to dial out. The hook function is invoked with the following parameters:

<pre>
success = connect_hook_func(hook,reserved,s2cm);

BOOL connect_hook_func(struct Hook *hook,APTR reserved,
struct Sana2ConnectionMessage *s2cm);
</pre>

The <tt>reserved</tt> parameter '''must''' be <tt>NULL</tt>. The <tt>s2cm</tt> parameter points to a data structure, as follows:

<syntaxhighlight lang="C" line>
struct Sana2ConnectionMessage
{
ULONG s2cm_Size;
struct Sana2Connection * s2cm_Connection;
struct IORequest * s2cm_Request[2];
LONG s2cm_RequestType;
};
</syntaxhighlight>

In this structure, the members have the following purposes:

<tt>s2cm_Size</tt>

The size of this data structure; it '''must''' be at least 20 bytes in size. The purpose of <tt>s2cm_Size</tt> is to allow for future expansion, which may cause the size of this structure to grow.

<tt>s2cm_Connection</tt>

This points back to the <tt>Sana2Connection</tt> structure which the hook that was invoked with the <tt>Sana2ConnectionMessage</tt> is embedded in.

<tt>s2cm_Request</tt>

Here you will find two I/O requests which can be used for reading and writing data to the link layer. These pointers '''must not''' be <tt>NULL</tt> and they '''must''' refer to different I/O requests, it is not permitted to pass the same request twice.

The dialer can use these requests for communicating with the modem, but it is also permitted to clone these requests by creating new I/O requests of the same size, copying the original contents and filling in different reply ports.

There is a danger in that the hook code may not receive the right kind of I/O request, which is why the <tt>s2cm_RequestType</tt> field identifies the kind of device the requests were created for.

When the hook function returns, it '''must''' make sure that none of the I/O requests are still pending, i.e. asynchronous I/O '''must''' have been stopped.

<tt>s2cm_RequestType</tt>

This identifies the type of device the I/O requests passed in <tt>s2cm_Request</tt> were created for. Possible values for this entry come from the New Style Device specification, e.g. <tt>NSDEVTYPE_SERIAL</tt> for a <tt>serial.device</tt>-like device or <tt>NSDEVTYPE_SANA2</tt> for a networking driver.

The hook function '''must''' return <tt>TRUE</tt> if the connection could be established, and <tt>FALSE</tt> otherwise. Note that it is ''not'' sufficient to just return <tt>FALSE</tt> in case of failure. Your code '''must''' have called the <tt>s2c_ErrorHook</tt> with an explanation why things went wrong first.

<tt>s2c_DisconnectHook</tt>

This hook is called by <tt>S2_CONNECT</tt> when the connection could not be established (the <tt>s2c_ConnectHook</tt> returned <tt>FALSE</tt>), or by <tt>S2_DISCONNECT</tt>, shortly before the link level device is to be closed. The hook function is invoked with the following parameters:

<pre>
disconnect_hook_func(hook,reserved,s2cm);

VOID disconnect_hook_func(struct Hook *hook,APTR reserved,
struct Sana2ConnectionMessage *s2cm);
</pre>

The <tt>reserved</tt> parameter '''must''' be <tt>NULL</tt>. The <tt>s2cm</tt> parameter points to a data structure, as was described for the <tt>s2c_ConnectHook</tt>.

<tt>s2c_Login</tt>

<tt>s2c_Password</tt>

The purpose of these entries is to transport the authentication information the protocol may require. These entries are either <tt>NULL</tt> or contain pointers to <tt>NUL</tt>-terminated strings. If <tt>s2c_Login</tt> is <tt>NULL</tt>, then both login and password '''must''' be assumed to be empty. If <tt>s2c_Login</tt> is not <tt>NULL</tt> and <tt>s2c_Password</tt> is <tt>NULL</tt>, then the password '''must''' be assumed to be empty.

The list of options in <tt>s2c_Options</tt> supplies the necessary information on how the driver is to connect to the link layer. Each node contains an option, which bears a name and contains a value. This pair is what I call a ''parameter''. A number of parameter names are reserved, as will be listed below:

<tt>ppp</tt>.async.device

Name of device driver to use for asynchronous PPP.

Example: <tt>serial.device</tt>

<tt>ppp</tt>.async.unit

Device unit number to use for asynchronous PPP.

Example: <tt>0</tt>

<tt>ppp</tt>.async.speed

Transmission speed to use for asynchronous PPP in bits per second.

Example: <tt>115200</tt>

<tt>ppp.async.buffersize</tt>

Receive buffer size for asynchronous PPP.

Example: <tt>50000</tt>

<tt>ppp.async.checkcarrier</tt>

Whether the carrier signal of the link layer should be tested or not. This can be either 0 (do not test) or 1 (test the carrier signal).

Example: <tt>1</tt>

<tt>ppp.async.rtscts</tt>

Whether or not hardware handshaking should be used by the link layer. This can be either <tt>0</tt> (off) or <tt>1</tt> (on).

Example: <tt>1</tt>

<tt>ppp.async.shared</tt>

Whether or not the link layer device should be opened in shared mode. This can be either <tt>0</tt> (off) or <tt>1</tt> (on).

Example: <tt>0</tt>

<tt>ppp.async.nullmodem</tt>

Whether or not the link layer is a direct connection, such as a nullmodem. This can be either <tt>0</tt> (off) or <tt>1</tt> (on).

Example: <tt>0</tt>

<tt>ppp.async.eof</tt>

Whether or not the underlying serial device driver's 'EOF mode' should be enabled. This can be either <tt>0</tt> (off) or <tt>1</tt> (on).

Example: <tt>0</tt>

<tt>ppp.async.readrequests</tt>

Number of read requests to be used for asynchronous PPP.

Example: <tt>16</tt>

<tt>ppp.async.writerequests</tt>

Number of write requests to be used for asynchronous PPP.

Example: <tt>16</tt>

<tt>ppp.async.accm</tt>

Asynchronous control character map, expressed as a hexadecimal value.

Example: <tt>$000A0000</tt>

<tt>ppp.async.pfc</tt>

Whether or not protocol field compression should be used. This can be either <tt>0</tt> (off) or <tt>1</tt> (on).

Example: <tt>1</tt>

<tt>ppp.async.aacfc</tt>

Whether or not address and control field compression should be used. This can be either <tt>0</tt> (off) or <tt>1</tt> (on).

Example: <tt>1</tt>

<tt>ppp.async.vjhc</tt>

Whether or not Van Jacobson header compression should be used. This can be either <tt>0</tt> (off) or <tt>1</tt> (on).

Example: <tt>1</tt>

<tt>ppp.async.ignorefcs</tt>

Whether or not frame check sequences should be ignored upon reception. This can be either <tt>0</tt> (off) or <tt>1</tt> (on).

Example: <tt>0</tt>

<tt>ppp.async.initialize</tt>

The modem initialization command, with embedded control sequences, if possible.

Example: <tt>AT\r</tt>

<tt>ppp.async.dial</tt>

The modem dial command, with embedded control sequences, if possible.

Example: <tt>ATD12345\r</tt>

<tt>ppp.async.dialtimeout</tt>

The dial timeout, i.e. the number of seconds to wait after the dial command has been sent for the modem to establish a connection.

Example: <tt>60</tt>

<tt>ppp.async.hangup</tt>

The modem hangup command, with embedded control sequences, if possible.

Example: <tt>ATH0\r</tt>

<tt>ppp.idletimeout</tt>

Number of seconds the local host may remain idle, i.e. send no data to the peer, before a watchdog timeout elapses and proceeds to verify that the line is still operational.

Example: <tt>30</tt>

<tt>ppp.localaddress</tt>

The IP address to assign to the local host, as part of the PPP negotiation process. This must be given in dotted decimal notation (RFC1700).

Example: <tt>1.2.3.4</tt>

<tt>ppp.remoteaddress</tt>

The IP address to assume for the peer, as part of the PPP negotiation process. This must be given in dotted decimal notation (RFC1700).

Example: <tt>1.2.3.4</tt>

<tt>ppp.dns1address</tt>

The IP address to be used by the primary domain name server, as part of the PPP negotiation process. This must be given in dotted decimal notation (RFC1700).

Example: <tt>1.2.3.4</tt>

<tt>ppp.dns2address</tt>

The IP address to be used by the secondary domain name server, as part of the PPP negotiation process. This must be given in dotted decimal notation (RFC1700).

Example: <tt>1.2.3.4</tt>

<tt>ppp.maxfail</tt>

The maximum number of negative configuration acknowledgements to be sent before the PPP negotiation process switches to reject those options.

Example: <tt>5</tt>

<tt>ppp.maxterm</tt>

The maximum number of termination requests to be sent before the respective PPP network or link protocol gives up.

Example: <tt>2</tt>

<tt>ppp.maxconfig</tt>

The maximum number of configuration requests to be sent before the respective PPP network or link protocol gives up.

Example: <tt>10</tt>

<tt>ppp.timeout</tt>

The number of seconds that have to pass before the respective PPP network or link protocol will retry to do whatever didn't work during the last attempt.

Example: <tt>3</tt>

<tt>ppp.mtu</tt>

The maximum transmission unit to use.

Example: <tt>1500</tt>

<tt>ppp.peeridletimeout</tt>

Number of seconds the peer may remain idle, i.e. send no data to the local host, before a watchdog timeout elapses and proceeds to verify that the line is still operational.

Example: <tt>30</tt>

<tt>ppp.rejectpap</tt>

Whether or not the Password Authentication Protocol should be accepted, if offered by the peer. This can be either <tt>0</tt> (accept) or <tt>1</tt> (reject).

Example: <tt>0</tt>

<tt>ppp.sendid</tt>

A flag which controls whether the local host should send LCP identification packets or not. This can be either <tt>0</tt> (off) or <tt>1</tt> (on).

Example: <tt>0</tt>

<tt>ppp.pap.timeout</tt>

The Password Authentication Protocol requires that the server answers to the client's request to log in. The server may be unable to respond immediately, which means that the client will have to repeat its request. A short delay should separate each request sent, such as three seconds.

Example: <tt>3</tt>

<tt>ppp.pap.retry</tt>

If the client does not manage to authenticate with the server immediately, it may resend the authentication request several times. But the attempts have to stop eventually, such as after having resent the message ten times.

Example: <tt>10</tt>

<tt>ppp.dummyremoteaddress</tt>

Whether or not the PPP driver should make up an IP address if the peer refuses to state its own IP address.

Example: <tt>1</tt>

<tt>logfile</tt>

The name of a log file to create. If the file already exists, then new data should be appended to it.

Example: <tt>t:logfile</tt>

<tt>logoptions</tt>

A list of options which control what exactly should be logged.

<tt>ppp.ethernet.device</tt>

Name of device driver to use for PPPoE (PPP over Ethernet).

Example: <tt>a2065.device</tt>

<tt>ppp.ethernet.unit</tt>

Device unit number to use for PPPoE.

Example: <tt>0</tt>

<tt>ppp.ethernet.raw</tt>

Whether or not raw link layer frames should be constructed for transmission or not. This can be either <tt>0</tt> (off) or <tt>1</tt> (on).

Example: <tt>1</tt>

<tt>ppp.ethernet.bypass</tt>

Whether or not the IP packet transmission and reception should bypass several copying steps. This can be either <tt>0</tt> (off) or <tt>1</tt> (on).

Example: <tt>1</tt>

<tt>ppp.ethernet.readpackets</tt>

The number of read requests to queue for the link layer.

Example: <tt>16</tt>

<tt>ppp.ethernet.writepackets</tt>

The number of write requests to queue for the link layer.

Example: <tt>16</tt>

<tt>ppp.ethernet.service</tt>

The name of the PPPoE service to request.

Example: <tt>?</tt>

<tt>ppp.ethernet.ac</tt>

The name of the PPPoE access concentrator to request.

Example: <tt>?</tt>

<tt>ppp.ethernet.connecttimeout</tt>

The number of seconds to wait for the PPPoE server to allow a session to be opened.

Example: <tt>3</tt>

While this list of parameters may suggest that the command described above can be used solely with the PPP protocol, do not let that put you off. This list is merely the starting point, but it is not set in stone that it cannot be extended.

The names of the parameters are not case sensitive. As the names suggest, the name space itself is hierarchic in construction, i.e. everything related to the PPP protocol bears a name starting with the letters 'ppp' with the dot '.' separating the individual items. By this rule, ppp.async refers to options that concern asynchronous PPP and ppp.ethernet to options that concern PPP over Ethernet wire.

To add your own parameter, register it with the maintainer of the SANA-II standard or prefix its name with the letters 'x-'. For example, to use your own kind of 'ppp.ethernet.connecttimeout' parameter, change the name of the last component like this: ppp.ethernet.x-connecttimeout. No officially-registered parameter will ever begin with the prefix 'x-'.

The command should work as follows:

# The client must set up the <tt>Sana2Connection</tt> data structure, initialize the <tt>s2c_Size</tt>, <tt>s2c_Options</tt>, <tt>s2c_ErrorHook</tt>, <tt>s2c_ConnectHook</tt>, <tt>s2c_DisconnectHook</tt>, <tt>s2c_Login</tt> and <tt>s2c_Password</tt> fields.
# The connection options must be filled in, which means that nodes containing the respective information must be stored in the <tt>s2c_Options</tt> list. The client must make sure that the syntax of the parameters conforms to the specifications described above.
# A pointer to the <tt>Sana2Connection</tt> data structure is placed in the <tt>ios2_Data</tt> member of an <tt>IOSana2Req</tt>, the command is set to <tt>S2_CONNECT</tt> and the request is sent via <tt>DoIO()</tt> or <tt>SendIO()</tt>.
# The driver receives the request and begins to examine the contents of the <tt>s2c_Options</tt> list, as provided in the data structure pointed to by the <tt>ios2_Data</tt> member of the request. Unknown options are ignored, options whose values do not conform to the syntax specification are rejected; this is done by calling the <tt>s2c_ErrorHook</tt> with an error message referring to the option in question and by returning the <tt>IOSana2Req</tt> with an error code of <tt>S2ERR_BAD_ARGUMENT</tt> and wire error code of <tt>S2WERR_INVALID_OPTION</tt>.
# If the options are all in good order, the driver proceeds to verify that all mandatory options are provided. If this is not the case, the <tt>s2c_ErrorHook</tt> is called with an error message referring to the option in question and the <tt>IOSana2Req</tt> is returned with an error code of <tt>S2ERR_BAD_ARGUMENT</tt> and wire error code of <tt>S2WERR_MISSING_OPTION</tt>.
# The driver proceeds to do its local initialization, which involves opening the link layer device, etc. If this initialization fails, the <tt>s2c_ErrorHook</tt> is called with an error message referring to the problem and the <tt>IOSana2Req</tt> is returned with an appropriate error code.
# When the initialization has finished, the driver may invoke the <tt>s2c_ConnectHook</tt> callback. Some drivers may require this, such as asynchronous PPP, some may not, such as PPPoE. The purpose of the hook function is to give the client a chance to perform modem initializations and connect to the peer. If the <tt>s2c_ConnectHook</tt> cannot perform its duties, it has to invoke the <tt>s2c_ErrorHook</tt> with an error message and eventually return <tt>FALSE</tt>. If <tt>FALSE</tt> is returned, the driver must invoke the <tt>s2c_DisconnectHook</tt>, reverse any initializations it had made and eventually returned the <tt>IOSana2Req</tt> with an appropriate error code. If the <tt>s2c_ConnectHook</tt> returned <tt>TRUE</tt>, then the driver must proceed with the actions that require that the link layer is operational. A protocol negotiation may follow, which, if successful, will make the driver return the <tt>IOSana2Req</tt> with an error code of zero, indicating success. If successful, the SANA-II events <tt>S2EVENT_CONNECT</tt> and <tt>S2EVENT_ONLINE</tt> must be sent.
# The command will eventually return, but the client '''must not''' release the memory allocated for the <tt>Sana2Connection</tt> structure and the option nodes in the <tt>s2c_Options</tt> list. This is because the driver may have to invoke the <tt>s2c_DisconnectHook</tt> hook due to the connection shutting down on its own accord.

The connect and disconnect hook functions '''must not''' be called from interrupt code. For each hook only a <tt>Task</tt> calling context of unknown priority must be assumed. Also, stack space is provided only to call <tt>exec.library</tt> and <tt>utility.library</tt> functions. The callback shall not place excessive data on the stack. Stack space should be considered limited.

I propose a command with the following semantics:

<pre>
NAME
S2_CONNECT -- Establish a link layer connection and go
online.

FUNCTION
This command is for use by networking devices which require
a special link layer device to transmit their data, such as
an asynchronous serial line and need to know about the
configuration parameters necessary to open the connection.

IO REQUEST
ios2_Command - S2_CONNECT
ios2_Data - Pointer to Sana2Connection structure
ios2_BufferManagement - Magic cookie as returned when opening the
driver with a struct IOSana2Req

RESULTS
ios2_Req.io_Error - Zero if successful; non-zero otherwise
ios2_WireError - More specific error number

NOTES
If successful, this command implies S2_ONLINE, i.e. the
link layer is allocated and used by the driver.

The contents of the Sana2Connection structure must be valid
until the connection is eventually shut down. The driver will
need to cache it, so it must not be deallocated or otherwise
modified.

Note that S2_ONLINE does not necessarily imply S2_CONNECT, if
the S2_CONNECT command is listed as supported by the driver via
NSCMD_DEVICEQUERY. If S2_CONNECT is not listed as supported,
S2_ONLINE obviously implies connect functionality.

S2_CONNECT/S2_DISCONNECT do not nest.

SEE ALSO
S2_DISCONNECT</pre>
I propose that the following command number should be assigned:

<tt>#define S2_CONNECT 0xC005</tt>

== S2_DELMULTICASTADDRESS ==

<pre>
NAME
S2_DELMULTICASTADDRESS -- Disable an interface multicast address.

FUNCTION
This command causes device driver to disable multicast packet
reception for the requested address.

It is an error to disable a multicast address that is not enabled.

IO REQUEST
ios2_Command - S2_DELMULTICASTADDRESS
ios2_SrcAddr - Multicast address to disable.

RESULTS
ios2_Error - Zero if successful; non-zero otherwise.
ios2_WireError - More specific error number.

NOTES
Multicast addresses are added globally -- anyone using the device
may receive packets as a result of any multicast address which has
been added for the device.

Since multicast addresses are not "bound" to a particular packet type,
each enabled multicast address has an "enabled" count associated with
it so that if two protocols add the same multicast address and later
one removes it, it is still enabled until the second removes it.

SEE ALSO
S2_ADDMULTICASTADDRESS
</pre>

== S2_DEVICEQUERY ==

<pre>
NAME
S2_DEVICEQUERY -- Return parameters for this network interface.

FUNCTION
This command causes the device driver to report information about the
device. Up to SizeAvailable bytes of the information is copied
into a buffer pointed to by ios2_StatData. The format of the data is
as follows:

struct Sana2DeviceQuery
{
/*
** Standard information
*/
ULONG SizeAvailble; /* bytes available */
ULONG SizeSupplied; /* bytes supplied */
LONG DevQueryFormat; /* this is type 0 */
LONG DeviceLevel; /* this document is level 0 */

/*
** Common information
*/
UWORD AddrFieldSize; /* address size in bits */
ULONG MTU; /* maximum packet data size */
LONG bps; /* line rate (bits/sec) */
LONG HardwareType; /* what the wire is */

/*
** Format specific information
*/
};

The SizeAvailable specifies the number of bytes that the caller
is prepared to accomodate, including the standard information fields.

SizeSupplied is the number of bytes actually supplied,
including the standard information fields, which will not exceed
SizeAvailable.

<devices/sana2.h> includes constants for these values. If your
hardware does not have a number assigned to it, you must contact
the AmigaOS development team to get a hardware number.

IO REQUEST
ios2_Command - S2_DEVICEQUERY.
ios2_StatData - Pointer to Sana2DeviceQuery structure to fill in.

RESULTS
ios2_Error - Zero if successful; non-zero otherwise.
ios2_WireError - More specific error number.
</pre>

== S2_DISCONNECT ==

This command complements <tt>S2_CONNECT</tt> in that it tears down a connection. It uses the same <tt>Sana2Connection</tt> structure and hooks, but most of these members are ignored.

The command should work as follows:

# The client must set up the <tt>Sana2Connection</tt> data structure, initialize the <tt>s2c_Size</tt>, <tt>s2c_Options</tt>, <tt>s2c_ErrorHook</tt>, <tt>s2c_ConnectHook</tt>, <tt>s2c_DisconnectHook</tt>, <tt>s2c_Login</tt> and <tt>s2c_Password</tt> fields. The <tt>s2c_Options</tt>, <tt>s2c_ConnectHook</tt>, <tt>s2c_Login</tt> and <tt>s2c_Password</tt> fields will be ignored, but the client should play things safe.
# A pointer to the <tt>Sana2Connection</tt> data structure is placed in the <tt>ios2_Data</tt> member of an <tt>IOSana2Req</tt>, the command is set to <tt>S2_DISCONNECT</tt> and the request is sent via <tt>DoIO()</tt> or <tt>SendIO()</tt>.
# The driver receives the request and proceeds to reverse the steps that previously allowed it to establish a connection. This includes telling the peer to shut down the link, but it does not include cleaning up the link layer device access, i.e. no I/O requests used for accessing a modem may be shut down yet.
# The <tt>s2c_DisconnectHook</tt> may be invoked with the proper parameters. Some drivers, such as for asynchronous PPP, will need the hook to tell the modem to hang up the line. Some drivers, such as for PPPoE, may not need this hook and thus ignore it.
# The initialization is reversed completely, all resources allocated when the connection was previously opened are released. The <tt>IOSana2Req</tt> is returned with an error code of zero, indicating success. The SANA-II event <tt>S2EVENT_DISCONNECT</tt> must be sent, and, if necessary, <tt>S2EVENT_OFFLINE</tt>.

The connect and disconnect hook functions must not be called from interrupt code. For each hook only a <tt>Task</tt> calling context of unknown priority must be assumed. Also, stack space is provided only to call <tt>exec.library</tt> and <tt>utility.library</tt> functions. The callback shall not place excessive data on the stack. Stack space should be considered limited.

I propose a command with the following semantics:

<pre>
NAME
S2_DISCONNECT -- Go offline and close a link layer connection
previously established with S2_CONNECT.

FUNCTION
This command complements the S2_CONNECT command in that it
reverses the steps taken to establish a link layer connection.

IO REQUEST
ios2_Command - S2_DISCONNECT
ios2_Data - Pointer to Sana2Connection structure
ios2_BufferManagement - Magic cookie as returned when opening the
driver with a struct IOSana2Req

RESULTS
ios2_Req.io_Error - Zero if successful; non-zero otherwise
ios2_WireError - More specific error number

NOTES
If successful, this command implies S2_OFFLINE, i.e. the
link layer is deallocated.

The driver must ignore the S2_DISCONNECT command and
recover gracefully if the S2_CONNECT was never sent or
returned with an error.

The contents of the Sana2Connection structure are valid only
until the device driver has processed the command and returned
the IOSana2Req. Any data the driver may need to retain beyond
that point of time must be copied.

Once the S2_DISCONNECT command has returned, it is safe to dispose
of the Sana2Connection structure provided at S2_CONNECT time.

Note that S2_OFFLINE does not necessarily imply S2_DISCONNECT, if
the S2_DISCONNECT command is listed as supported by the driver via
NSCMD_DEVICEQUERY. If S2_DISCONNECT is not listed as supported,
S2_OFFLINE obviously implies disconnect functionality.

S2_CONNECT/S2_DISCONNECT do not nest.

SEE ALSO
S2_CONNECT
</pre>

I propose that the following command number should be assigned:

<tt>#define S2_DISCONNECT 0xC006</tt>

== S2_GETDNSADDRESS ==

The PPP negotiation process may produce information on which domain name and NetBIOS name servers are available to the client. I think that it is doubtful that the availability of NetBIOS name servers will be useful for Amiga software (let alone whether NetBIOS name resolution has a future), which is why I suggest that a SANA-II command for returning only the domain name servers is introduced.

I propose a command with the following semantics:

<pre>
NAME
S2_GETDNSADDRESS -- Obtain the addresses of the primary
and secondary domain name servers.

FUNCTION
Obtain the addresses of the domain name servers available to the
client using this driver's address.

IO REQUEST
ios2_Command - S2_GETDNSADDRESS
ios2_Flags - Supported flags are:
SANA2IOB_QUICK
ios2_BufferManagement - Magic cookie as returned when opening the
driver with a struct IOSana2Req

RESULTS
ios2_Req.io_Error - Zero if successful; non-zero otherwise
ios2_WireError - More specific error number
ios2_SrcAddr - Address of primary domain name server
ios2_DstAddr - Address of secondary domain name server

NOTES
The size of the address returned by S2_GETPEERADDRESS must not be
different from the size as returned by the S2_DEVICEQUERY command. For
example, if a 32 bit IPv4 address was advertized, the driver must not
return a 128 bit IPv6 address instead.

If the driver is unable to return the primary domain name server
address (ios2_SrcAddr) or the secondary domain name server address
(ios2_DstAddr) it must fill the respective address fields with zeroes.
It is legal for a driver to respond to the S2_GETDNSADDRESS command
with two zero addresses (both ios2_SrcAddr and ios2_DstAddr filled
with zeroes).
</pre>

I propose that the following command number should be assigned:
<tt>#define S2_GETDNSADDRESS 0xC003</tt>

This command may be useful beyond the typical application (PPP) described above.

== S2_GETEXTENDEDGLOBALSTATS ==

There already exists a SANA-II command for querying global device statistics (<tt>S2_GETGLOBALSTATS</tt>) which should be common to all kinds of networking devices. Statistics that are particular to a certain device type are intended to be returned through the <tt>S2_GETSPECIALSTATS</tt> command. I feel that these mechanisms both fail to cater well enough for dial-up or session-oriented networking applications such as PPP or PPPoE. Since the data structure used by <tt>S2_GETGLOBALSTATS</tt> is of a fixed size and not intended to accomodate for new fields, I propose to introduce a new command which uses a different data structure, as follows:

<syntaxhighlight lang="C" line>
struct Sana2ExtDeviceStats
{
ULONG s2xds_Length;
ULONG s2xds_Actual;

S2QUAD s2xds_PacketsReceived;
S2QUAD s2xds_PacketsSent;
S2QUAD s2xds_BadData;
S2QUAD s2xds_Overruns;
S2QUAD s2xds_UnknownTypesReceived;
S2QUAD s2xds_Reconfigurations;
struct timeval s2xds_LastStart;

struct timeval s2xds_LastConnected;
struct timeval s2xds_LastDisconnected;
struct timeval s2xds_TimeConnected;
};
</syntaxhighlight>

Before I proceed to explain what purposes the individual members serve, a few words on the <tt>S2QUAD</tt> type, which is defined as follows:
<tt>typedef struct { ULONG s2q_High; ULONG s2q_Low; } S2QUAD;</tt>

In other words, the <tt>S2QUAD</tt> type stands for an unsigned 64 bit big endian integer, as expressed in ISO 'C' terms.

The structure members have the following purposes:

<tt>s2xds_Length</tt>

This is the size of the data structure to be filled in and should be initialized by the caller to <tt>sizeof(struct Sana2ExtDeviceStats)</tt>. Smaller values are permitted, but these '''must not''' be smaller than 8 (which covers the <tt>s2xds_Length</tt> and <tt>s2xds_Actual</tt> members). A driver which finds an <tt>s2xds_Length</tt> < 8 '''must''' treat this as an error and reject the command with <tt>ios2_Req.io_Error</tt>=<tt>IOERR_BADLENGTH</tt>.

<tt>s2xds_Actual</tt>

The size of the data structure filled with information. This member is initialized by the driver and '''must''' be <= <tt>s2xds_Length</tt>.

<tt>s2xds_PacketsReceived</tt>

Number of packets that this unit has received. This is a 64 bit integer.

<tt>s2xds_PacketsSent</tt>

Number of packets that this unit has sent. This is a 64 bit integer.

<tt>s2xds_BadData</tt>

Number of bad packets received (i.e., hardware CRC failed). This is a 64 bit integer.

<tt>s2xds_Overruns</tt>

Number of packets dropped due to insufficient resources available in the network interface. This is a 64 bit integer.

<tt>s2xds_UnknownTypesReceived</tt>

Number of packets received that had no pending read command with the appropriate packet type. This is a 64 bit integer.

<tt>s2xds_Reconfigurations</tt>

Number of network reconfigurations since this unit was last configured. This is a 64 bit integer.

<tt>s2xds_LastStart</tt>

The time when this unit last went on-line.

<tt>s2xds_LastConnected</tt>

The time when this unit last established a connection. For dial-up connections, this should be the time when the underlying serial line started to accumulate costs. <tt>s2xds_LastConnected</tt> '''must''' be set to zero if the unit never managed to make a connection.

<tt>s2xds_LastDisconnected</tt>

The time when this unit last shut down a connection. For dial-up connections, this should be the time when the underlying serial line stopped accumulating costs, e.g. when the modem's carrier signal was lost. <tt>s2xds_LastDisconnected</tt> '''must''' be set to zero if the unit never disconnected.

<tt>s2xds_TimeConnected</tt>

The time this unit has been connected. For dial-up connections this should be the time between now and when the underlying serial line started accumulating costs.

If this unit is not currently connected, then <tt>s2xds_TimeConnected</tt> '''must''' be set to zero. This means in particular that when the connection is lost, <tt>s2xds_TimeConnected</tt> '''must''' be immediately set to zero and <tt>s2xds_LastDisconnected</tt> '''must''' be filled in so that client software can query how long the unit was connected by subtracting <tt>s2xds_LastConnected</tt> from <tt>s2xds_LastDisconnected</tt>.

If this unit is currently connected, <tt>s2xds_TimeConnected</tt> '''must never''' be zero; if necessary, set <tt>s2xds_TimeConnected.tv_secs=0</tt> and <tt>s2xds_TimeConnected.tv_micros=1</tt>.

If <tt>s2xds_TimeConnected</tt> is zero, check <tt>s2xds_LastConnected</tt> and <tt>s2xds_LastDisconnected</tt>; if the latter two are not zero, you can calculate the previous connection time by subtracting <tt>s2xds_LastConnected</tt> from <tt>s2xds_LastDisconnected</tt>.

The layout and semantics used by the <tt>Sana2ExtDeviceStats</tt> data structure suggest that there is a difference between the underlying networking media (the link layer) and the state of the protocol that is running on top of it. With drivers for networking hardware such as Ethernet there was no difference between these two, but for protocols like SLIP, PPP or PPPoE there is a difference. The difference is in that a session or connection may exist for a certain time whereas the protocol running inside that session may be switched 'online' later. The primary purpose of the <tt>s2xds_LastConnected</tt>, <tt>s2xds_LastDisconnected</tt> and <tt>s2xds_TimeConnected</tt> fields is to allow for cost accounting and traffic monitoring (so that, for example, a driver may be disconnected after it has been idle for a while) to be written.

I propose a command with the following semantics:

<pre>
NAME
S2_GETEXTENDEDGLOBALSTATS -- Get interface accumulated statistics;
updated version.

FUNCTION
This command causes the device driver to retrieve various global
runtime statistics for this network interface. The format of the data
returned is as follows:

struct Sana2ExtDeviceStats
{
ULONG s2xds_Length;
ULONG s2xds_Actual;

S2QUAD s2xds_PacketsReceived;
S2QUAD s2xds_PacketsSent;
S2QUAD s2xds_BadData;
S2QUAD s2xds_Overruns;
S2QUAD s2xds_UnknownTypesReceived;
S2QUAD s2xds_Reconfigurations;
struct timeval s2xds_LastStart;

struct timeval s2xds_LastConnected;
struct timeval s2xds_LastDisconnected;
struct timeval s2xds_TimeConnected;
};

IO REQUEST
ios2_Command - S2_GETEXTENDEDGLOBALSTATS
ios2_StatData - Pointer to Sana2ExtDeviceStats structure
to fill in
ios2_BufferManagement - Magic cookie as returned when opening the
driver with a struct IOSana2Req

RESULTS
ios2_Req.io_Error - Zero if successful; non-zero otherwise
ios2_WireError - More specific error number
</pre>

I propose that the following command number should be assigned:
<tt>#define S2_GETEXTENDEDGLOBALSTATS 0xC004</tt>

== S2_GETGLOBALSTATS ==

<pre>
NAME
GetGlobalStats -- Get interface accumulated statistics.

FUNCTION
This command causes the device driver to retrieve various global
runtime statistics for this network interface. The format of the
data returned is as follows:

struct Sana2DeviceStats
{
ULONG PacketsReceived;
ULONG PacketsSent;
ULONG BadData;
ULONG Overruns;
ULONG UnknownTypesReceived;
ULONG Reconfigurations;
timeval LastStart;
};

IO REQUEST
ios2_Command - S2_GETGLOBALSTATS.
ios2_StatData - Pointer to Sana2DeviceStats structure to fill.

RESULTS
ios2_Error - Zero if successful; non-zero otherwise.
ios2_WireError - More specific error number.

SEE ALSO
S2_GETSPECIALSTATS
</pre>

== S2_GETNETWORKINFO ==

<pre>
NAME
S2_GETNETWORKINFO -- Get information on current network.

FUNCTION
This command provides information on the status of the currently
used network. If this command completes successfully, ios2_StatData
will contain a pointer to a tag list that contains information on
the network. The S2INFO_#? tags used are defined in the
devices/sana2wireless.h include file.

The returned taglist is allocated from the supplied memory pool.
To discard the results of this command, the entire memory pool
should be destroyed.

INPUTS
ios2_Data - Pointer to an Exec memory pool.

RESULTS
ios2_Data - Remains unchanged.
ios2_StatData - Pointer to a tag list.
io_Error - Zero if successful; non-zero otherwise.
ios2_WireError - More specific error code.
</pre>

== S2_GETNETWORKS ==

<pre>
NAME
S2_GETNETWORKS -- Scan for available networks.

FUNCTION
This command supplies details of available networks. If the scan
should be limited to one specific network, the S2INFO_SSID tag
should specify its name.

If this command completes successfully, ios2_StatData will contain
an array of pointers to tag lists, each of which contains
information on a single network. The device will set ios2_DataLength
to the number of elements in this array.

The returned taglists are allocated from the supplied memory pool.
To discard the results of this command, the entire memory pool
should be destroyed.

The S2INFO_#? tags used with this command are defined in the
devices/sana2wireless.h include file.

INPUTS
ios2_Data - Pointer to an Exec memory pool.
ios2_StatData - Pointer to taglist that specifies parameters to use.

RESULTS
ios2_DataLength - Number of tag lists returned.
ios2_Data - Remains unchanged.
ios2_StatData - Pointer to an array of tag lists.
io_Error - Zero if successful; non-zero otherwise.
ios2_WireError - More specific error code.
</pre>

== S2_GETPEERADDRESS ==

As part of the negotiation process, the PPP protocol can return the addresses used by the peer (the other side of the point-to-point connection PPP establishes; typically a dial-in server) and assigned to the client establishing the connection. The SANA-II standard does not provide for a mechanism to return such information. Existing drivers therefore had to resort to other means, such as by setting global environment variables containing this information.

I propose a command with the following semantics:

<pre>
NAME
S2_GETPEERADDRESS -- Obtain the addresses used by the peer
(server) and the client of a point-to-point connection.

FUNCTION
Obtain the address used by the peer of a point-to-point connection and
the address assigned to the local driver.

IO REQUEST
ios2_Command - S2_GETPEERADDRESS
ios2_Flags - Supported flags are:
SANA2IOB_QUICK
ios2_BufferManagement - Magic cookie as returned when opening the
driver with a struct IOSana2Req

RESULTS
ios2_Req.io_Error - Zero if successful; non-zero otherwise
ios2_WireError - More specific error number
ios2_SrcAddr - Address assigned to the local driver
ios2_DstAddr - Address used by the peer

NOTES
The size of the address returned by S2_GETPEERADDRESS must not be
different from the size returned by the S2_DEVICEQUERY command. For
example, if a 32 bit IPv4 address was advertized, the driver must not
return a 128 bit IPv6 address instead.

If the driver is unable to return the local driver address
(ios2_SrcAddr) or the peer's address (ios2_DstAddr) it must fill the
respective address fields with zeroes. It is legal for a driver to
respond to the S2_GETPEERADDRESS command with two zero addresses (both
ios2_SrcAddr and ios2_DstAddr filled with zeroes).
</pre>

I propose that the following command number should be assigned:
<tt>#define S2_GETPEERADDRESS 0xC002</tt>

This command may be useful beyond the typical application (PPP) described above.

== S2_GETSIGNALQUALITY ==

<pre>
NAME
S2_GETSIGNALQUALITY -- Get signal quality statistics.

FUNCTION
This command fills in the supplied Sana2SignalQuality structure with
current signal and noise levels. The unit for these figures is dBm.
Typically, they are negative values.

INPUTS
ios2_StatData - Pointer to Sana2SignalQuality structure.

RESULTS
io_Error - Zero if successful; non-zero otherwise.
ios2_WireError - More specific error code.
ios2_StatData - Pointer to filled Sana2SignalQuality structure.
</pre>

== S2_GETSPECIALSTATS ==

<pre>
NAME
S2_GETSPECIALSTATS -- Get network type specific statistics.

FUNCTION
This function returns statistics which are specific to the type of
network medium this driver controls. For example, this command could
return statistics common to all Ethernets which are not common to all
network mediums in general.

The supplied Sana2SpecialStatData structure is given below:

struct Sana2SpecialStatData
{
ULONG RecordCountMax;
ULONG RecordCountSupplied;
struct Sana2StatRecord[RecordCountMax];
};

The format of the data returned is:

struct Sana2StatRecord
{
ULONG Type; /* Amiga registered */
LONG Count; /* the stat itself */
char *String; /* null terminated */
};

The RecordCountMax field specifies the number of records that the
caller is prepared to accomodate.

RecordCountSupplied is the number of record actually supplied which
will not exceed RecordCountMax.

IO REQUEST
ios2_Command - S2_GETSPECIALSTATS.
ios2_StatData - Pointer to a Sana2SpecialStatData structure to fill.
RecordCountMax must be initialized.

RESULTS
ios2_Error - Zero if successful; non-zero otherwise.
ios2_WireError - More specific error number.

NOTES
Amiga will maintain registered statistic Types.

SEE ALSO
S2_GETGLOBALSTATS, <devices/sana2specialstats.h>
</pre>

== S2_GETSTATIONADDRESS ==

<pre>
NAME
S2_GETSTATIONADDRESS -- Get default and interface address.

FUNCTION
This command causes the device driver to copy the current interface
address into ios2_SrcAddr, and to copy the factory default station
address (if any) into ios2_DstAddr.

IO REQUEST
ios2_Command - S2_GETSTATIONADDRESS.

RESULTS
ios2_Error - Zero if successful; non-zero otherwise.
ios2_WireError - More specific error number.
ios2_SrcAddr - Current interface address.
ios2_DstAddr - Default interface address (if any).

SEE ALSO
S2_CONFIGINTERFACE
</pre>

== S2_GETTYPESTATS ==

<pre>
NAME
S2_GETTYPESTATS -- Get accumulated type specific statistics.

FUNCTION
This command causes the device driver to retrieve various packet type
specific runtime statistics for this network interface. The format of
the data returned is as follows:

struct Sana2TypeStatData
{
LONG PacketsSent;
LONG PacketsReceived;
LONG BytesSent;
LONG BytesReceived;
LONG PacketsDropped;
};

IO REQUEST
ios2_Command - S2_GETTYPESTATS.
ios2_PacketType - Packet type of interest.
ios2_StatData - Pointer to TypeStatData structure to fill in.

RESULTS
ios2_Error - Zero if successful; non-zero otherwise.
ios2_WireError - More specific error number.

NOTES
Statistics for a particular packet type are only available while that
packet type is being ``tracked''.

SEE ALSO
S2_TRACKTYPE, S2_UNTRACKTYPE
</pre>

== S2_MULTICAST ==

<pre>
NAME
S2_MULTICAST -- Multicast a packet on network.

FUNCTION
This command works the same as CMD_WRITE except that it also performs
whatever special processing of the packet is required to do a
multicast send. The actual multicast mechanism is neccessarily
network/interface/device specific.

IO REQUEST
ios2_Command - S2_MULTICAST.
ios2_Flags - Supported flags are:
SANA2IOB_RAW
SANA2IOB_QUICK
ios2_PacketType - Packet type to send.
ios2_DstAddr - Destination interface address for this packet.
ios2_DataLength - Length of the Data to be sent.
ios2_Data - Abstract data structure which packet data is
contained in.

RESULTS
ios2_Error - Zero if successful; non-zero otherwise.
This command can fail for many reasons and
is not supported by all networks and/or
network interfaces.
ios2_WireError - More specific error number.

NOTES
The address supplied in ios2_DstAddr will be sanity checked (if
possible) by the driver. If the supplied address fails this sanity
check, the multicast request will fail immediately with ios2_Error
set to S2WERR_BAD_MULTICAST.

Another Amiga will not receive a multicast packet unless it has had
the particular multicast address being used S2_ADDMULTICASTADRESS'd.

SEE ALSO
CMD_WRITE, S2_BROADCAST, S2_ADDMULTICASTADDRESS
</pre>

== S2_OFFLINE ==

<pre>
NAME
S2_OFFLINE -- Remove interface from service.

FUNCTION
This command removes a network interface from service.

IO REQUEST
ios2_Command - S2_OFFLINE.

RESULTS
ios2_Error - Zero if successful; non-zero otherwise.
ios2_WireError - More specific error number.

NOTES
Aborts all pending reads and writes with ios2_Error set to
S2ERR_OUTOFSERVICE.

While the interface is offline, all read, writes and any other
command that touches interface hardware will be rejected with
ios2_Error set to S2ERR_OUTOFSERVICE.

This command is intended to permit a network interface to be
tested on an otherwise live system.

SEE ALSO
S2_ONLINE
</pre>

== S2_ONEVENT ==

<pre>
NAME
S2_ONEVENT -- Return when specified event occures.

FUNCTION
This command returns when a particular event condition has occured
on the network or this network interface.

IO REQUEST
ios2_Command - S2_ONEVENT.
ios2_Flags - Supported flags are:
SANA2IOB_QUICK
ios2_WireError - Mask of event(s) to wait for
(from <devices/sana2.h>).

RESULTS
ios2_Error - Zero if successful; non-zero otherwise.
ios2_WireError - Mask of events that occured.

NOTES
If this device driver does not understand the specified event
condition(s) then the command returns immediately with
ios2_Req.io_Error set to S2_ERR_NOT_SUPPORTED and ios2_WireError
S2WERR_BAD_EVENT. A successful return will have ios2_Error set to
zero ios2_WireError set to the event number.

All pending requests for a particular event will be returned when
that event occurs.

All event types that cover a particular condition are returned when
that condition occures. For instance, if an error is returned by
a buffer management function during receive processing, events of
types S2EVENT_ERROR, S2EVENT_RX and S2EVENT_BUFF would be returned if
pending.

Types ONLINE and OFFLINE return immediately if the device is
already in the state to be waited for.
</pre>

== S2_ONLINE ==

<pre>
NAME
S2_ONLINE -- Put a network interface back in service.

FUNCTION
This command places an offline network interface back into service.

IO REQUEST
ios2_Command - S2_ONLINE.

RESULTS
ios2_Error - Zero if successful; non-zero otherwise.
ios2_WireError - More specific error number.

NOTES
This command is responsible for putting the network interface
hardware back into a known state (as close as possible to the
state before S2_OFFLINE) and resets the unit global and special
statistics.

SEE ALSO
S2_OFFLINE
</pre>

== S2_READMGMT ==

<pre>
NAME
S2_READMGMT -- Read a management frame.

FUNCTION
Reads a raw IEEE 802.11 management frame from the device. The buffer
management mechanism used is simpler than that used for data
packets (e.g. with CMD_READ): a buffer pointer and a length value
are passed to the device.

As with CMDREAD/S2_READORPHAN, multiple S2_READMGMT requests can
(and should) be queued concurrently to ensure no incoming frames are
missed.

INPUTS
ios2_DataLength - size of frame buffer.
ios2_Data - pointer to a frame buffer.

RESULTS
io_Error - Zero if successful; non-zero otherwise.
ios2_WireError - More specific error code.
ios2_DataLength - actual size of received frame.
ios2_Data - pointer to the filled frame buffer.
</pre>

== S2_READORPHAN ==

<pre>
NAME
S2_READORPHAN -- Get a packet for which there is no reader.

FUNCTION
Get the next packet available that does not satisfy any then-pending
CMD_READ requests. The data returned in the ios2_Data structure is
normally the Data Link Layer packet type field and the packet data. If
bit SANA2IOB_RAW is set in ios2_Flags, then the entire Data Link Layer
packet, including both header and trailer information, will be
returned.

IO REQUEST
ios2_Command - CMD_READORPHAN.
ios2_Flags - Supported flags are:
SANA2IOB_RAW
SANA2IOB_QUICK
ios2_DataLength - Length of the Data to be sent.
ios2_Data - Abstract data structure which packet data is
contained in.

RESULTS
ios2_Error - Zero if successful; non-zero otherwise.
ios2_WireError - More specific error number.
ios2_Flags - The following flags may be returned:
SANA2IOB_RAW
SANA2IOB_BCAST
SANA2IOB_MCAST
ios2_SrcAddr - Source interface address of packet.
ios2_DstAddr - Destination interface address of packet.
ios2_DataLength - Length of the Data to be sent.
ios2_Data - Abstract data structure which packet data is
contained in.

NOTES
This is intended for debugging and management tools. Protocols should
not use this.

As with 802.3 packets on an ethernet, to determine which protocol
family the returned packet belongs to you may have to specify
SANA2IOB_RAW to get the entire data link layer wrapper (which is where
the protocol type may be kept). Notice this necessarily means that
this cannot be done in a network interface independent fashion. The
driver will, however, fill in the PacketType field to the best of its
ability.

SEE ALSO
CMD_READ, CMD_WRITE
</pre>

== S2_SAMPLE_THROUGHPUT ==

The SANA-II standard already allows for statistics to be returned on the amount of data that has passed through a driver. Unfortunately, that information is not very accurate in that no information is provided on the time span in which the data was accumulated. Such information would be helpful in trying to determine as accurately as possible how large the data throughput actually is. I therefore propose a new command which can be used to obtain that information, which uses the following data structure:

<syntaxhighlight lang="C" line>
struct Sana2ThroughputStats
{
ULONG s2ts_Length;
ULONG s2ts_Actual;

struct Task * s2ts_NotifyTask;
ULONG s2ts_NotifyMask;

struct timeval s2ts_StartTime;
struct timeval s2ts_EndTime;
S2QUAD s2ts_BytesSent;
S2QUAD s2ts_BytesReceived;
S2QUAD s2ts_Updates;
};
</syntaxhighlight>

Before I proceed to explain what purposes the individual members serve, a few words on the <tt>S2QUAD</tt> type, which is defined as follows:

<tt>typedef struct { ULONG s2q_High; ULONG s2q_Low; } S2QUAD;</tt>

In other words, the <tt>S2QUAD</tt> type stands for an unsigned 64 bit big endian integer, as expressed in ISO 'C' terms.

The structure members have the following purposes:

<tt>s2ts_Length</tt>

This is the size of the data structure to be filled in and should be initialized by the caller to <tt>sizeof(struct Sana2ThroughputStats)</tt>. Smaller values are permitted, but these must not be smaller than 8 (which covers the <tt>s2ts_Length</tt> and <tt>s2ts_Actual</tt> members). A driver which finds an <tt>s2ts_Length</tt> < 8 must treat this as an error and reject the command with <tt>ios2_Req.io_Error</tt>=<tt>IOERR_BADLENGTH</tt>.

<tt>s2ts_Actual</tt>

The size of the data structure filled with information. This member is initialized by the driver and must be <= <tt>s2ts_Length</tt>.

<tt>s2ts_NotifyTask</tt>

The <tt>Task</tt> to notify whenever the contents of this data structure change. This must be <tt>NULL</tt> if no notification is desired.

'''Note:''' This feature should be used carefully, as so much data may arrive that the driver will almost be constantly signalling this <tt>Task</tt> that a change has taken place.

It is recommend that periodic polling be used, such as to update displays of a link monitoring program.

<tt>s2ts_NotifyMask</tt>

The signal mask to use for notifying the <tt>Task</tt> whose address is found in <tt>s2ts_NotifyTask</tt> (via <tt>Signal(s2ts->s2ts_NotifyTask,s2ts->s2ts_NotifyMask);</tt>). This must be zero if no notification is desired.

<tt>s2ts_StartTime</tt>

The time when the driver started to fill in this data structure.

<tt>s2ts_EndTime</tt>

The time when the driver last updated the contents of this data structure.

<tt>s2ts_BytesSent</tt>

Total number of bytes sent since the driver started to fill in this data structure. This is a 64 bit integer.

<tt>s2ts_BytesReceived</tt>

Total number of bytes received since the driver started to fill in this data structure. This is a 64 bit integer.

<tt>s2ts_Updates</tt>

Number of times the driver has updated this data structure. This value will increase with every change. This is a 64 bit integer.

A driver implementing this command should take care to update the members <tt>s2ts_EndTime</tt>, <tt>s2ts_BytesSent</tt>, <tt>s2ts_BytesReceived</tt> and <tt>s2ts_Updates</tt> atomically each time changes are made.

I propose a command with the following semantics:

<pre>
NAME
S2_SAMPLE_THROUGHPUT -- Obtain accurate information on
driver data throughput.

FUNCTION
This command installs a data structure which is updated every time
data is sent or received by the driver.

This command must be sent via SendIO() or BeginIO(); until
the associated I/O request is recalled using AbortIO(), the
device unit will continue to update the Sana2ThroughputStats
structure in real time.

IO REQUEST
ios2_Command - S2_SAMPLE_THROUGHPUT
ios2_StatData - Pointer to Sana2ThroughputStats structure
to fill in
ios2_BufferManagement - Magic cookie as returned when opening the
driver with a struct IOSana2Req

RESULTS
ios2_Req.io_Error - Zero if successful; non-zero otherwise

NOTES
If this device driver does not understand this command,
it will immediately return the IOSana2Req with
ios2_Req.io_Error set to IOERR_NOCMD. Otherwise, the request will
remain queued until it is removed with AbortIO() later.
</pre>

I propose that the following command number should be assigned:

<tt>#define S2_SAMPLE_THROUGHPUT 0xC007</tt>

== S2_SANA2HOOK ==

The 'traditional' copy call-back functions are installed at <tt>OpenDevice()</tt> time, and they are found in a <tt>TagItem</tt> list which is passed along with the <tt>IOSana2Req</tt>. For the new <tt>Hook</tt>-based call-back functionality, I propose to introduce a new command. This command would take care of installing one single <tt>Hook</tt> which will be invoked with the parameters described in section 3.1. The hook function can key off the <tt>SANA2HookMsg->schm_Method</tt> field to figure out which function should be performed. Once the <tt>Hook</tt> is installed via the command as follows, the driver shall ignore any and all tags passed to it during <tt>OpenDevice()</tt> time.

<pre>
NAME
S2_SANA2HOOK -- Install a Hook to perform operations such as copying,
overriding the call-back functions installed at
OpenDevice() time.

FUNCTION
The S2_SANA2HOOK command is to replace the 'traditional' call-back
functions installed through the TagItem list found in the
IOSana2Req->ios2_BufferManagement field. Instead of assigning a
function pointer for each copying function, all operations are
to be performed through a Hook. This is intended to make the
interface more portable and less dependant on a certain hardware
architecture.

The hook message and the hook data structures allow for more than
copying to be done.

IO REQUEST
ios2_Command - S2_SANA2HOOK
ios2_Data - Points to a struct Sana2Hook, which looks
like this:

struct Sana2Hook
{
struct Hook s2h_Hook;
Tag * s2h_Methods;
};

The structure fields have the following purposes:

s2h_Hook
A standard Hook structure, ready to be
called. Once installed, the complete Hook
structure including its Node structure is
off limits! The s2h_Hook remains installed
until CloseDevice().

s2h_Methods
Points to a table of Tag values, each
identifying a copy method supported
(S2_CopyToBuff, S2_CopyFromBuff,
S2_CopyToBuff16, S2_CopyFromBuff16,
S2_CopyToBuff32, S2_CopyFromBuff32,
S2_DMACopyToBuff32, S2_DMACopyFromBuff32,
S2_DMACopyToBuff64 or S2_DMACopyFromBuff64)
or the logging facility (S2_Log).
The table must be terminated by TAG_END.

The driver will check the table and
verify that the mandatory S2_CopyToBuff
and S2_CopyFromBuff commands are present.
Additional functionality is used as
available if the driver supports it.

ios2_DataLength - Must be >= 20, which is the default length of
the Sana2Hook structure. This may grow in
the future, and larger values for ios2_DataLength
may indicate additional functionality associated
with the Sana2Hook.

RESULTS
ios2_Error - IOERR_NOCMD if this command is not supported
by the driver.

IOERR_BADLENGTH if IOSana2Req->ios2_DataLength
is < 20.

IOERR_UNITBUSY if the Hook was already
installed or if any of the CMD_READ, CMD_WRITE,
S2_MULTICAST or S2_BROADCAST have already been
invoked.

S2WERR_FUNCTIONS_MISSING if the table pointed
to by Sana2Hook->s2h_Methods does not
include the S2_CopyToBuff and S2_CopyFromBuff
tags.

NOTES
The S2_SANA2HOOK command shall be invoked right after OpenDevice()
as very first command.

When the command has been executed, the driver must use the
newly installed Hook for all its copying or logging and cease to
use the call-back functions provided at OpenDevice() time.

The contents of the Sana2Hook structure, as passed to the
driver, must not be modified. This includes the MinNode
at the beginning of the Hook structure which the driver may
need to use for its own purposes.

The table pointed to by Sana2Hook->s2h_Methods must
include at least the S2_CopyToBuff and S2_CopyFromBuff tags.
It must be valid until CloseDevice() is called.

This field is to be treated as private by a protocol stack.
IOSana2Req structures may be duplicated by copying
ios2_BufferManagement, io_Device, and io_Unit.
</pre>

The new command value is defined as follows:

<pre>
#define S2_SANA2HOOK 0xC008
</pre>

The new error code is defined as follows:

<pre>
#define S2WERR_FUNCTIONS_MISSING 24 /* mandatory copy functions are missing */
</pre>

== S2_SETKEY ==

<pre>
NAME
S2_SETKEY -- Set an encryption key.

FUNCTION
Sets one of the encryption keys for the device. Note that
ios2_StatData, if used, points to a byte array representing the RX
RX counter value.

INPUTS
ios2_WireError - Key index.
ios2_PacketType - Encryption type (e.g. S2ENC_WEP).
ios2_DataLength - Key length.
ios2_Data - Key.
ios2_StatData - RX counter number (NULL if unused).

RESULTS
io_Error - Zero if successful; non-zero otherwise.
ios2_WireError - More specific error code.
</pre>

== S2_SETOPTIONS ==

<pre>
NAME
S2_SETOPTIONS -- Set network options.

FUNCTION
Set various parameters for the network interface. This command
should be called before going online to set any essential parameters
not covered elsewhere. The S2INFO_#? tags used are defined in the
devices/sana2wireless.h include file.

INPUTS
ios2_Data - Pointer to a taglist that specifies parameters to use.

RESULTS
io_Error - Zero if successful; non-zero otherwise.
ios2_WireError - More specific error code.
</pre>

== S2_TRACKTYPE ==

<pre>
NAME
S2_TRACKTYPE -- Accumulate statistics about a packet type.

FUNCTION
This command causes the device driver to accumulate statistics about
a particular packet type. Packet type statistics, for the particular
packet type, are zeroed by this command.

IO REQUEST
ios2_Command - S2_TRACKTYPE.
ios2_PacketType - Packet type of interest.

RESULTS
ios2_Error - Zero if successful; non-zero otherwise.
ios2_WireError - More specific error number.

SEE ALSO
S2_UNTRACKTYPE, S2_GETTYPESTATS
</pre>

== S2_UNTRACKTYPE ==

<pre>
NAME
S2_UNTRACKTYPE -- End statistics about a packet type.

FUNCTION
This command causes the device driver to stop accumulating
statistics about a particular packet type.

IO REQUEST
ios2_Command - S2_UNTRACKTYPE.
ios2_PacketType - Packet type of interest.

RESULTS
ios2_Error - Zero if successful; non-zero otherwise.
ios2_WireError - More specific error number.

SEE ALSO
S2_TRACKTYPE, S2_GETTYPESTATS
</pre>

== S2_WRITEMGMT ==

<pre>
NAME
S2_WRITEMGMT -- Write a management frame.

FUNCTION
Writes a raw IEEE 802.11 management frame to the device. The buffer
management mechanism used is simpler than that used for data
packets (e.g. with CMD_WRITE): a buffer pointer and a length value
are passed to the device.

INPUTS
ios2_DataLength - full frame length.
ios2_Data - pointer to a complete IEEE 802.11 management frame.

RESULTS
io_Error - Zero if successful; non-zero otherwise.
ios2_WireError - More specific error code.
</pre>

= Callback mechanisms =

== CopyFromBuff ==

<pre>
NAME
CopyFromBuff -- Copy n bytes from an abstract data structure.

SYNOPSIS
success = CopyFromBuff(to, from, n)
d0 a0 a1 d0

BOOL CopyToBuff(VOID *, VOID *, ULONG);

FUNCTION
This function copies 'n' bytes of data in the abstract data structure
pointed to by 'from' into the contigous memory pointed to by 'to'.
'to' must contain at least 'n' bytes of usable memory or innocent
memory will be overwritten.

INPUTS
to - pointer to contiguous memory to copy to.
from - pointer to abstract structure to copy from.
n - number of bytes to copy.

RESULT
success - TRUE if operation was successful, else FALSE.

NOTES
This function must be callable from interrupts. In particular, this
means that this function may not directly or indirectly call any
system memory functions (since those functions rely on Forbid() to
protect themselves) and that you must not compile this function
with stack checking enabled. See the Exec Interrupts
chapter for more details on what is legal in a routine called from
an interrupt handler.

'C' programmers should not compile with stack checking (option '-v'
in SAS) and should geta4() or __saveds.</pre>

== CopyToBuff ==

<pre>
NAME
CopyToBuff -- Copy n bytes to an abstract data structure.

SYNOPSIS
success = CopyToBuff(to, from, n)
d0 a0 a1 d0

BOOL CopyToBuff(VOID *, VOID *, ULONG);

FUNCTION
This function first does any initialization and/or allocation
required to prepare the abstract data structure pointed at by 'to'
to be filled with 'n' bytes of data from 'from'. It then executes
the copy operation.

If, for example, there is not enough memory available to prepare
the abstract data structure, the call is failed and FALSE is returned.

The buffer management scheme should be such that any memory needed
to fulfill CopyToBuff() calls is already allocated from the system
before the call to CopyToBuff() is made.

INPUTS
to - pointer to abstract structure to copy to.
from - pointer to contiguous memory to copy from.
n - number of bytes to copy.

RESULT
success - TRUE if operation was successful, else FALSE.

NOTES
This function must be callable from interrupts. In particular, this
means that this function may not directly or indirectly call any
system memory functions (since those functions rely on Forbid() to
protect themselves) and that you must not compile this function
with stack checking enabled. See the Exec Interrupts
chapter for more details on what is legal in a routine called from
an interrupt handler.

'C' programmers should not compile with stack checking (option '-v'
in SAS) and should geta4() or __saveds.</pre>

== PacketFilter ==

<pre>
NAME
PacketFilter -- Perform filtering operation on CMD_READ's.

SYNOPSIS
keep = PacketFilter(hook, ios2, data)
d0 a0 a2 a1

BOOL PacketFilter(struct Hook *, struct IOSana2Req *, APTR);

FUNCTION
This function (if supplied by a protocol stack) may be used to
reject packets before they are copied into a protocol stack's
internal buffers.

The IOSana2Req structure should be set up to look (almost) exactly
as it would if it was successfully returned for the current packet.
Specifically, the fields that should be set up correctly are:

ios2->ios2_DataLength
ios2->ios2_SrcAddr
ios2->ios2_DstAddr

The "data" pointer must point to the beginning of the packet data
that is stored in contiguous memory. The data should NOT include
any hardware specific headers (unless of course the CMD_READ
request wanted RAW packets).

INPUTS
hook - pointer to the Hook originally supplied during
OpenDevice().
ios2 - The IOSana2Req CMD_READ request that will be used
(the "object" of the Hook call).
data - The packet data (the "message" of the Hook call).

RESULT
success - TRUE if the driver should provide the packet to
the protocol stack, FALSE if the packet should be
ignored.

NOTES
This function must be callable from interrupts. In particular, this
means that this function may not directly or indirectly call any
system memory functions (since those functions rely on Forbid() to
protect themselves) and that you must not compile this function
with stack checking enabled. See the Exec Interrupts
chapter for more details on what is legal in a routine called from
an interrupt handler.

'C' programmers should not compile with stack checking (option '-v'
in SAS) and should geta4() or __saveds.

What does packet filtering do? With the original ``SANA-II Network
Device Driver Specification'', a protocol stack could open a device
and ask for certain packet types. It got all the packets that matched
this type. As it turned out, this could be mighty inefficient if there
were packets that the protocol stack did not use at all. These would
go into read processing of the protocol stack and waste CPU time even
though they could have been easily identified on arrival.</pre>

= Ethernet description =

<pre>#define S2WireType_Ethernet 1

ios2_DataLength:
valid ethernet packets have 64 to 1500 bytes of data.

Address format:
Ethernet addresses consist of 47 bits of address information and
a 1 bit multicast flag. The standard for expressing ethernet
addresses is as 6 bytes (octets) in the order in which the bytes
are transmitted with the low-order bits in a byte transmitted
first. The multicast flag bit is the least-significant bit of the
first byte.

Ethernet addresses in a Sana2IOReq occupy the first 6 bytes of
an address field in transmission order with the low-order bits in
a byte transmitted first.

Station Address:
Each ethernet board must have a unique ethernet hardware address.
Drivers will override any attempt to set the address to anything
other than the ROM address.

Raw reads and writes:
6 bytes of destination address,
6 bytes of source address,
2 bytes of type,
64 to 1500 bytes of data
(followed by 4 byte CRC value covering all of the above
which is hardware generated and checked, hence not included
in even raw packets)

Multicast: Supported

Broadcast: Supported

Promiscuous: Supported

Packet Type Numbers for Ethernet are assigned by:

Xerox Corporation
Xerox Systems Institute
475 Oakmead Parkway, Sunnyvale, CA 94086
Attn: Ms. Fonda Pallone
(408) 737-4652

Some Common Packet Type Numbers:

decimal Hex Description
------- --- -----------
000 0000-05DC IEEE 802.3 Length Field
2048 0800 TCP/IP -- IP
2054 0806 TCP/IP -- ARP
32821 8035 TCP/IP -- RARP
32923 809B Appletalk
33011 80F3 AppleTalk AARP (Kinetics)
33100 814C SNMP
33079 8137-8138 Novell, Inc.</pre>
= ARCNET description =

<pre>S2WireType_Arcnet 7

ios2_DataLength:
506 byte MTU (because of the possibility of two byte Types).
Packets of size 254, 255, or 256 bytes are padded to 257 bytes before
transmition.

Station Address:
ARCNET hardware may have addresses set with jumpers, DIP switches
or software. Different drivers may therefore behave differently
with S2_CONFIGINTERFACE.

Hardware addresses should be assigned by users from highest to lowest
because there is some efficiency gained in the token passing scheme
this way. For example, on a three node network, hardware numbers 254,
253 and 252 should be used rather than 1, 2 and 3.

Raw reads and writes:
Short Packets (1-253 bytes)
Destination Address (1 byte)
Source Address (1 byte)
Count (256-N-Type length) (1 byte)
Padding (to byte number Count)
Type (1 or 2 bytes)
Data (N bytes)

Long Packets (257-506 bytes)
Destination Address (1 byte)
Source Address (1 byte)
zero (1 byte)
Count (512-N-Type length) (1 byte)
Padding (to byte number Count)
Type (1 or 2 bytes)
Data (N bytes)

Multicast: Not Supported

Broadcast: Supported

Promiscuous: Generally Not Supported

Packet Type Numbers for ARCNET are assigned by:
Datapoint Corporation

Some Common Packet Type Numbers

decimal hex description
------- --- -----------
221 DD AppleTalk
240 F0 TCP/IP -- IP (RFC 1051)
241 F1 TCP/IP -- ARP (RFC 1051)
212 F0 TCP/IP IP (RFC 1201, proposed)
213 F1 TCP/IP -- ARP (RFC 1201, proposed)
214 D6 TCP/IP -- RARP (RFC 1201, proposed)
247 F7 Banyan Vines
250 FA Novell IPX
</pre>

= Authors =

== Revision 2 & 3 ==

Copyright © 1992-2000 Amiga, Inc. All Rights Reserved 

Amiga is a registered trademark of Amiga, Inc. Ethernet is a trademark of Xerox Corporation. ARCNET is a trademark of Datapoint Corporation. DECNet is a trademark of Digital Equipment Corporation. AppleTalk is a trademark of Apple Computer, Inc.

== Revision 4 ==

Extending the SANA-II network driver specification 
by Olaf Barthel

(Last updated 02-Mar-2003)

== Revision 5 ==

Hook-based callback function extensions for SANA-II (SANA-IIR5) 
by Olaf Barthel and Heinz Wrobel

== Revision 6 ==

SANA-II IEEE 802.11 wireless API 
by Neil Cafferkey

= Acknowledgments =

== Revision 2 & 3 ==

Many people and companies have contributed to the "SANA-II Network Device Driver Specification". The original SANA-II Autodocs and includes were put together by Ray Brand, Perry Kivolowitz (ASDG) and Martin Hunt. Those original documents evolved to their current state and grew to include this document at the hands of Dale Larson and Greg Miller. Brian Jackson and John Orr provided valuable editing. Randell Jesup has provided sage advice on several occasions. The buffer management callback mechanism was his idea. Dale Luck (GfxBase) and Rick Spanbauer (Ameristar Technologies) have provided valuable comments throughout the process. Nicolas Benezan (ADONIS) provided many detailed and useful comments on weaknesses in late drafts of the specification. The enhancements for better buffer management, clarifications and notes for device implementers were added to the specification by Heinz Wrobel whilst consulting for Amiga Technologies GmbH, yielding revision 3.0 of the specification.

Thanks to all the above and the numerous others who have contributed with their comments, questions and discussions.

= Changes =

== Revision 4 ==

Changes since 24-Dec-2002:

* The <tt>Sana2Connection</tt> data structure used by the <tt>S2_CONNECT</tt> command now must remain valid until the <tt>S2_DISCONNECT</tt> command is sent (see [[#2.4|section 2.4]]).

Changes since 01-May-2002:

* Added the <tt>ppp.async.readrequests</tt> and <tt>ppp.async.eof</tt> configuration keywords.

Changes since 04-Jan-2002:

* Added the <tt>ppp.dummyremoteaddress</tt> and <tt>ppp.ethernet.ac</tt> configuration keywords.

Changes since 10-Dec-2001:

* Converted to HTML format.
* Added the <tt><devices/sana2.h></tt> header file to the appendix.
* The memory alignment for the <tt>S2_DMACopyToBuff64</tt> and <tt>S2_DMACopyFromBuff64</tt> hooks refers to bits and not to bytes.

Changes since 19-Nov-2001:

* Added to the list of reserved configuration keywords (<tt>ppp.idletimeout</tt>, <tt>ppp.peeridletimeout</tt>, <tt>ppp.sendid</tt>).
* Renamed the fields of the <tt>Sana2ExtDeviceStats</tt> structure.
* Clarified that the <tt>S2QUAD</tt> type is a big endian integer.
* More clarifications for the <tt>S2_CONNECT</tt>/<tt>S2_DISCONNECT</tt> and <tt>S2_ONLINE</tt>/<tt>S2_OFFLINE</tt> commands.
* Updated the discussion of the <tt>Sana2DeviceQuery.RawMTU</tt> field, clarifying what is included in the the Ethernet <tt>RawMTU</tt>.
* Updated the <tt><devices/sana2.h></tt> header file. Note that there is no equivalent <tt>"devices/sana2.i"</tt> header file yet.

Changes since 12-Nov-2001:

* Changed the command numbers of <tt>S2_GETPEERADDRESS</tt>, <tt>S2_GETDNSADDRESS</tt>, <tt>S2_GETEXTENDEDGLOBALSTATS</tt>, <tt>S2_CONNECT</tt>, <tt>S2_DISCONNECT</tt> and <tt>S2_SAMPLE_THROUGHPUT</tt> to be NSD-compliant. Also assigned a new number to the <tt>S2_SAMPLE_THROUGHPUT </tt> command.
* Added section 4 ("Extensions for existing commands").
* Added the last paragraph to section 9, relating to the future extension of the <tt>Sana2DeviceQuery</tt> structure.

Changes since 03-Nov-2001:

* Renamed <tt>S2_GETNEWGLOBALSTATS</tt> to <tt>S2_GETEXTENDEDGLOBALSTATS</tt> (see [[#2.3|section 2.3]]).
* The <tt>S2_GETEXTENDEDGLOBALSTATS</tt> now uses 64 bit quantities for the <tt>s2xds_PacketsReceived</tt>, <tt>s2xds_PacketsSent</tt>, <tt>s2xds_BadData</tt>, <tt>s2xds_Overruns</tt>, <tt>s2xds_UnknownTypesReceived</tt> and <tt>s2xds_Reconfigurations</tt> counters.
* In section 2.6 the <tt>S2_SAMPLE_THROUGHPUT</tt> command was modified to use 64 bit integers for all members of the <tt>Sana2ThroughputStats</tt> structure.
* All proposed commands are now listed with their numeric IDs.
* The command autodocs specifically mention the <tt>ios2_BufferManagement</tt> field.
* All references to <tt>ios2_Error</tt> have been replaced with <tt>ios2_Req.io_Error</tt>.
* In section 7 the use of the <tt>IOERR_NOCMD</tt>/<tt>S2ERR_NOT_SUPPORTED</tt> error codes is clarified.
* Section 7 takes a more detailed look at safe default values returned by the query commands.
* Inserted section 3 ("Annotations for existing commands").
* The <tt>S2_CONNECT</tt> and <tt>S2_DISCONNECT</tt> commands now specifically mention the life time of the data they have to deal with.

Changes since 14-Oct-2001:

* Added <tt>S2_CONNECT</tt> and <tt>S2_DISCONNECT</tt> commands.
* Added <tt>S2EVENT_CONNECT</tt> and <tt>S2EVENT_DISCONNECT</tt> events.
* Added section 4 ("New wire error codes").
* In section 5.2 the originally proposed log callback function has been wrapped into a standard Hook structure.
* Removed item on <tt>S2_CONNECT</tt>/<tt>S2_DISCONNECT</tt> from section 7 ("Unsolved problems").
* Added section 8 ("Changes").

== Revision 5 ==

22-Mar-2004:

* Conversion to HTML

21-Jan-2004:

* Added clarifications for <tt>schm_MsgSize</tt>, <tt>slhm_MsgSize</tt>, <tt>slhm_Priority</tt>, <tt>slhm_Name</tt>, <tt>slhm_Message</tt> and <tt>s2h_Hook</tt>.
* Updated the <tt>S2_SANA2HOOK</tt> documentation.
* Shortened section 4.
* Updated section 5.

30-Nov-2003:

* Extended the applicability of the <tt>Hook</tt> to logging.
* Renamed <tt>S2_COPYHOOK</tt> to <tt>S2_SANA2HOOK</tt>, which matches the extended scope it should cover.
* The message passed to the <tt>Hook</tt> now includes a size field which holds the size of the message, expressed in bytes.

06-Oct-2003:

* Replaced the list of new tag items with a single <tt>Hook</tt>, which is installed through a new command.
* Added "Caveats" and "Changes" sections
* Removed the documentation for the originally proposed <tt>TagItem</tt> (sections 3.2.1 through 3.2.10)

= History =

== Revision 2 and 3 ==

This standard has undergone several drafts with long periods for comment from developers and the Amiga community at large. These drafts include a UseNet release which was also distributed on the Fish Disks in June, 1991 (as well as published in the '91 DevCon notes), and the November 7 Draft for Final Comment and Approval distributed via Bix, ADSP and UseNet. There were also several intermediate drafts with more limited distribution.

== Revision 4 ==

(Olaf Barthel)

I've been working on a TCP/IP stack and PPP drivers to go with them for a while and found that there were some things that SANA-II did specifically not address, and which ought to be covered by it. In other areas clarification was needed. Also, discussions I had with Harald Frank suggested that the extensions made by Heinz Wrobel and Stefan Sticht in the SANA-IIR3 specification could need extending.

Layers Library

2025-01-26T19:34:52Z

Costel Mincea: Text replacement - "<syntaxhighlight>" to "<syntaxhighlight lang="C" line>"

{{WIP}}
== Layers Library ==

This article describes the layers library which provides routines that are used to manage overlapping rectangular drawing areas that share a common display. Intuition uses the layers library to manage its system of windows.

The Graphics Library describes the use of ''regions'', special structures used to mask off areas where drawing can take place. Regions are installed through the layers library function InstallClipRegion() but the routines for the creation, disposal and manipulation of regions are part of the graphics library.

== Layers ==

The concept of a ''layer'' is closely tied to Intuition windows. A layer is a rectangular drawing area. A layer can overlap other layers and has a display priority that determines whether it will appear in front or behind other layers. Every Intuition window has an associated Layer structure. Layers allow Intuition and application programs to :

* Share a display's BitMap among various tasks in an orderly way by creating layers, separate drawing rectangles, within the BitMap.
* Move, size or depth-arrange a layer while automatically keeping track of which portions of other layers are hidden or revealed by the operation.
* Manage the remapping of coordinates, so the application need not track the layer's offset into the BitMap.
* Maintain each layer as a separate entity, which may optionally have its own BitMap.
* Automatically update same newly visible portions.

The layers library takes care of housekeeping: the low level, repetitive tasks which are required to keep track of where to place bits. The layers library also provides a locking mechanism which coordinates display updating when multiple tasks are drawing graphics to layers. The windowing environment provided by the Intuition library is largely based on layers.

{{Note|title=WARNING|text=Layers may not be created or used directly with Intuition screens. Intuition windows are the only supported method of adding layers to Intuition screens. ''Only'' the layer locking and unlocking functions are safe to use with Intuition. An application must create and manage its own View if it will be creating layers directly on the display.}}

=== The Layer Structure ===

The internal representation of layers is essentially a set of clipping rectangles. Each layer is represented by an instance of the Layer structure. All the layers in a display are linked together through the Layer_Info structure. Any display shared by multiple layers (such as an Intuition screen) requires one Layer_Info data structure to handle interactions between the various layers.

Here is a partial listing of the Layer structure from <graphics/clip.h>. (For a complete listing refer to the SDK.)

<syntaxhighlight lang="C" line>
struct Layer
{
struct Layer *front,*back;
struct ClipRect *ClipRect; /* read by ROMs to find first cliprect */
struct RastPort *rp;
struct Rectangle bounds;
...

UWORD Flags; /* obscured ?, Virtual BitMap? */
struct BitMap *SuperBitMap;
...

struct Region *DamageList; /* list of rectangles to refresh through */
};
</syntaxhighlight>

{{Note|title=The Layer Structure is Read-Only|text=Applications should never directly modify any of the elements of the Layer structure. In addition, applications should only read the front, back, rp, bounds, Flags, SuperBitMap and DamageList elements of the Layer structure. (Some of these elements are subject to dynamic change by the system so proper layer locking procedures must be followed when relying on what the application has read.)}}

=== The Layer's RastPort ===

When a layer is created, a RastPort is automatically to go along with it. The pointer to the RastPort is contained in the layer data structure. Using this RastPort, the application may draw anywhere into the layer's bounds rectangle. If the application tries to draw outside of this rectangle, the graphics routines will clip the graphics.

Here is sample code showing how to access the layer's RastPort:

<syntaxhighlight lang="C" line>
struct RastPort *myRPort; /* allocate a RastPort pointer for each layer */

myRPort = layer->rp;

/* The layer's RastPort may be used with any of the graphics library calls
** that require this structure. For instance, to fill layer with color:
*/
IGraphics->SetRast(layer->rp, color);

/* set up for writing text into layer */
IGraphics->SetDrMd(layer->rp, JAM1);
IGraphics->SetAPen(layer->rp, 0);
IGraphics->Move(layer->rp, 5, 7);

/* write into layer */
IGraphics->Text(layer->rp, string, strlen(string));
</syntaxhighlight>

=== Types of Layers ===

The layers library supports three types of layers: simple refresh, smart refresh and super bitmap. The type of the layer, specified by the Flags field in the Layers structure, determines what facilities the layer provides.

{{Note|title=Use Only One Layer Type Flag|text=The three layer-type Flags are mutually exclusive. That is, only one layer-type flag (LAYERSIMPLE, LAYERSMART and LAYERSUPER) should be specified.}}

==== Simple Refresh Layer ====

When an application draws into the layer, any portion of the layer that is visible (not obscured) will be rendered into the common BitMap of the viewing area. All graphics rendering routines are "clipped" so that only exposed sections of the layer are drawn into. No back-up of obscured areas is provided.

If another layer operation is performed that causes an obscured part of a simple refresh layer to be exposed, the application must determine if the section need be refreshed, re-drawing the newly exposed part of the layer as required.

The basic advantage of simple refresh is that it does not require back-up area to save drawing sections that cannot be seen, saving memory. However, the application needs to monitor the layer to see if it needs refreshing. This is typically performed with statements like:

<syntaxhighlight lang="C" line>
if (layer->Flags & LAYERREFRESH)
refresh(layer);
</syntaxhighlight>

When an application restores the layer by performing a full-layer redraw, only the damaged areas are redrawn, making the operation fairly time efficient.

==== Smart Refresh Layer ====

Under smart refresh, the system provides dynamic backup of obscured sections of the layer. The graphics routines will automatically draw into these backup areas when they encounter an obscured part of the layer. The backup memory will be used to automatically update the display when obscured sections later become exposed.

With smart refresh layers, the system handles all of the refresh requirements of the layer, except when the layer is made larger. When parts of the layer are exposed by a sizing operation, the application must refresh the newly exposed areas.

The advantage of smart refresh is the speed of updating exposed regions of the layer and the ability of the system to manage part of the updating process for the application.. Its main disadvantage is the additional memory required to handle this automatic refresh.

==== Super Bitmap Layer ====

A super bitmap layer is similar to a smart refresh layer. It too has a back-up area for rendering graphics for currently obscured parts of the display. Whenever an obscured area is made visible, the corresponding part of the backup area is copied to the display automatically.

However, it differs from smart refresh in that:

<ul>
<li>The back-up BitMap is user-supplied, rather than being allocated dynamically by the system.
</li>
<li>The back-up BitMap may be as large or larger than the the current size of the layer. It may also be larger than the maximum size of the layer.</li></ul>

To see a larger portion of a super bitmap on-display, use SizeLayer(). To see a different portion of the super bitmap in the layer, use ScrollLayer().

When the graphics routines perform drawing commands, part of the drawing appears in the common BitMap (the on-display portion). Any drawing outside the displayed portion itself is rendered into the super bitmap. When the layer is scrolled or sized, the layer contents are copied into the super bitmap, the scroll or size positioning is modified, and the appropriate portions are then copied back into the layer. (Refer to the graphics library functions SyncSBitMap() and CopySBitMap().

==== Backdrop Layer ====

A layer of any type may be designated a backdrop layer which will always appear behind all other layers. They may not be moved, sized, or depth-arranged. Non-backdrop layers will always remain in front of backdrop layers regardless of how the non-backdrop layer is moved, sized or depth-arranged.

=== Opening the Layers Library ===

Like all libraries, the layers library must be opened before it may be used. Check the Layers Autodocs to determine what version of the library is required for any particular Layers function.

<syntaxhighlight lang="C" line>
#include <proto/layers.h>

struct Library *LayersBase = IExec->OpenLibrary("layers.library", 50);

struct LayersIFace *ILayers = (struct LayersIFace*)IExec->GetInterface(LayersBase, "main", 1, NULL);

if (ILayers != NULL)
{
/* use Layers library */
}

IExec->DropInterface((struct Interface*)ILayers);
IExec->CloseLibrary(LayersBase);
</syntaxhighlight>

=== Working With Existing Layers ===

A common operation performed by applications is to render text or graphics into an existing layer such as an Intuition window. To prevent Intuition from changing the layer (for instance when the user resizes or moves the window) during a series of graphic operations, the layers library provides locking functions for obtaining exclusive access to a layer.

These locking functions are also useful for applications that create their own layers if the application has more than one task operating on the layers asynchronously. These calls coordinate multiple access to layers.

{| class="wikitable"
|+ Functions for Intertask Control of Layers (Layers Library)
| LockLayer()
| Lock out rendering in a single layer.
|-
| UnlockLayer()
| Release LockLayer() lock.
|-
| LockLayers()
| Lock out rendering in all layers of a display.
|-
| UnlockLayers()
| Release LockLayers() lock.
|-
| LockLayerInfo()
| Gain exclusive access to the display's layers.
|-
| UnlockLayerInfo()
| Release LockLayerInfo() lock.
|}

The following routines from the graphics library also allow multitasking access to layer structures:

{| class="wikitable"
|+ Functions for Intertask Control of Layers (Graphics Library)
| LockLayerRom()
| Same as LockLayer(), from layers library.
|-
| UnlockLayerRom()
| Release LockLayerRom() lock.
|-
| AttemptLockLayerRom()
| Lock layer only if it is immediately available.
|}

These functions are similar to the layers LockLayer() and UnlockLayer() functions, but do not require the layers library to be open. See the SDK for details.

==== Intertask Operations ====

If multiple tasks are manipulating layers on the same display they will be sharing a Layer_Info structure and their use of it and its related data structures need to be coordinated. To ensure that a structure remains cohesive, it should be operated on by only one task at a time. The Layer_Info encompasses all the layers existing on a single display.

LockLayerInfo() must be called whenever the visible portions of layers may be affected, or when the Layer_Info structure is changed.

<syntaxhighlight lang="C" line>
VOID LockLayerInfo( struct Layer_Info *li );
</syntaxhighlight>

The lock should be obtained whenever a layer is created, deleted sized or moved, as the list of layers that is being managed by the Layer_Info data structure must be updated.

It is not necessary to lock the Layer_Info data structure while rendering, or when calling routines like ScrollLayer(), because layer sizes and on-display positions are not being affected.

Use UnlockLayerInfo() when you have finished the layer operation:

<syntaxhighlight lang="C" line>
VOID UnlockLayerInfo( struct Layer_Info *li );
</syntaxhighlight>

If you don't unlock the Layer_Info then any other task calling LockLayerInfo() on the same Layer_Info structure will be blocked creating a potential deadlock situation.

In addition to locking the Layer_Info structure, the layer itself should be locked if it is shared between tasks so that only one task at a time renders graphics to it. LockLayer() is used to get exclusive graphics output to a layer.

<syntaxhighlight lang="C" line>
VOID LockLayer( long dummy, struct Layer *layer );
</syntaxhighlight>

If a graphics function is in process, the lock will return when the function is completed. Other tasks are blocked only if they attempt to draw graphics into this layer, or try to obtain a lock on this layer. The MoveLayer(), SizeLayer() and ScrollLayer() functions automatically lock and unlock the layer they operate on.

UnlockLayer() should be used after the graphics operation to make the layer available to other tasks again.

<syntaxhighlight lang="C" line>
VOID UnlockLayer( struct Layer *layer );
</syntaxhighlight>

If more than one layer must be locked, then the LockLayer() calls should be surrounded by LockLayerInfo() and UnlockLayerInfo() calls, to prevent deadlock situations.

The layers library provides two additional functions, LockLayers() and UnlockLayers(), for locking multiple layers.

<syntaxhighlight lang="C" line>
VOID LockLayers( struct Layer_Info *li );
VOID UnlockLayers( struct Layer_Info *li );
</syntaxhighlight>

LockLayers() is used to lock all layers in a single command. UnlockLayers() releases the layers lock. The system calls these routines during the BehindLayer(), UpfrontLayer() and MoveLayerInFrontOf() operations (described below).

==== Determining Layer Position ====

If the viewing area has been separated into several layers, the application may need to find out which layer is topmost at a particular ''x,y'' coordinate. Use the WhichLayer() function for this:

<syntaxhighlight lang="C" line>
struct Layer *WhichLayer( struct Layer_Info *li, int32 x, int32 y );
</syntaxhighlight>

To be sure that no task adds, deletes, or changes the sequence of layers before this information is used, call LockLayerInfo() before calling WhichLayer(), and call UnlockLayerInfo() when the operation is complete. In this way, the program may ensure that it is acting on valid information. Always check for a NULL return value (coordinate not in a layer) from WhichLayer().

=== Creating and Using New Layers ===

The functions described in this section are generally not safe to use with Intuition. To create new layers for Intuition you use Intuition window calls (see [[Intuition_Windows|Intuition Windows]]).

Only applications that create and mange their own View will be able to call the layer creation and updating functions discussed here.

{| class="wikitable"
|+ Functions for Creating and Updating Layers
| NewLayerInfo() || Allocating a Layer_Info structure.
|-
| DisposeLayerInfo() || Deallocating a Layer_Info structure.
|-
| CreateUpfrontLayer() || Make a new layer in front of others.
|-
| CreateBehindLayer() || Make a new layer behind others.
|-
| DeleteLayer() || Remove and delete an existing layer.
|-
| MoveLayer() || Change the position (not depth) of a layer.
|-
| SizeLayer() || Change the size of a layer.
|-
| ScrollLayer() || Change the internal coordinates of a layer.
|-
| BehindLayer() || Depth arrange a layer behind others.
|-
| UpfrontLayer() || Depth arrange a layer in front of others.
|-
| MoveLayerInFrontOf() || Depth arrange a layer to a specific position.
|-
| SwapBitsRastPortClipRect() || Fast, non-layered and non-damaging display operation.
|-
| BeginUpdate() || Synchronize optimized refreshing for layer.
|-
| EndUpdate() || End optimized layer refresh.
|}

==== Creating a Viewing Workspace ====

A viewing workspace may be created by using the primitives InitVPort(), InitView(), MakeVPort(), MrgCop(), and LoadView(). Please reference [[Graphics_Primitives|Graphics Primitives]] for details on creating a low-level graphics display. Do not create Layers directly on Intuition screens. Windows are the only supported method of creating a layer on a screen.

==== Creating the Layers ====

The application must first allocate and initialize a Layer_Info data structure which the system uses to keep track of layers that are created, use statements like:

<syntaxhighlight lang="C" line>
struct Layer_Info *theLayerInfo;

if (NULL != (theLayerInfo = ILayers->NewLayerInfo()))
{
/* use Layer_Info */

ILayers->DisposeLayerInfo(theLayerInfo);
}
</syntaxhighlight>

Layers may be created in the common bit map by calling CreateUpfrontLayer() or CreateBehindLayer(), with a sequence such as the following:

<syntaxhighlight lang="C" line>
struct Layer *layer;
struct Layer_Info *theLayerInfo;
struct BitMap *theBitMap;

/* requests construction of a smart refresh layer. */
if (NULL == (layer = ILayers->CreateUpfrontLayer(theLayerInfo, theBitMap, 20, 20, 100, 80, LAYERSMART, NULL)))
error("CreateUpfrontLayer() failed.");
else
{
; /* layer successfully created here. */
}
</syntaxhighlight>

==== Allocating and Deallocating Layer_Info ====

Use NewLayerInfo() to allocate and initialize a Layer_Info structure and associated sub-structures.

<syntaxhighlight lang="C" line>
struct Layer_Info *NewLayerInfo( VOID );
</syntaxhighlight>

You ''must'' call this function before attempting to use any of the other layers functions described below. When you have finished with a Layer_Info structure, use DisposeLayerInfo() to deallocate it.

<syntaxhighlight lang="C" line>
VOID DisposeLayerInfo( struct Layer_Info *li );
</syntaxhighlight>

This function deallocates a Layer_Info and associated structures previously allocated with NewLayerInfo().

==== Allocating and Deallocating Layers ====

Layers are created using the routines CreateUpfrontLayer() and CreateBehindLayer(). CreateUpfrontLayer() creates a layer that will appear in front of any existing layers.

<syntaxhighlight lang="C" line>
struct Layer *CreateUpfrontLayer( struct Layer_Info *li, struct BitMap *bm, int32 x0, int32 y0, int32 x1, int32 y1, int32 flags, struct BitMap *bm2 );
</syntaxhighlight>

CreateBehindLayer() creates a layer that appears behind existing layers, but in front of backdrop layers.

<syntaxhighlight lang="C" line>
struct Layer *CreateBehindLayer( struct Layer_Info *li, struct BitMap *bm, int32 x0, int32 y0, int32 x1, int32 y1, int32 flags, struct BitMap *bm2 );
</syntaxhighlight>

Both of these routines return a pointer to a Layer data structure (as defined in the include file <graphics/layers.h>), or NULL if the operation was unsuccessful.

{{Note|title=A New Layer Also Gets a RastPort|text=When a layer is created, the routine automatically creates a RastPort to go along with it. If the layer's RastPort is passed to the drawing routines, drawing will be restricted to the layer. See "The Layer's RastPort" section above.}}

Use the DeleteLayer() call to remove a layer:

<syntaxhighlight lang="C" line>
int32 DeleteLayer( int32 dummy, struct Layer *layer );
</syntaxhighlight>

DeleteLayer() removes a layer from the layer list and frees the memory allocated by the layer creation calls listed above.

==== Moving and Sizing Layers ====

The layers library includes three functions for moving and sizing layers:

<syntaxhighlight lang="C" line>
int32 MoveLayer( int32 dummy, struct Layer *layer, int32 dx, int32 dy );
int32 SizeLayer( int32 dummy, struct Layer *layer, int32 dx, int32 dy );
int32 MoveSizeLayer( struct Layer *layer, int32 dx, int32 dy, int32 dw, int32 dh);
</syntaxhighlight>

MoveLayer() moves a layer to a new position relative to its current position. SizeLayer() changes the size of a layer by modifying the coordinates of the lower right corner of the layer. MoveSizeLayer() changes both the size and position of a layer in a single call.

==== Changing a Viewpoint ====

The ScrollLayer() function changes the portion of a super bitmap that is shown by a layer:

<syntaxhighlight lang="C" line>
VOID ScrollLayer( int32 dummy, struct Layer *layer, int32 dx, int32 dy );
</syntaxhighlight>

This function is most useful with super bitmap layers but can also simulate the effect on other layer types by adding the scroll offset to all future rendering.

==== Reordering Layers ====

The layers library provides three function calls for reordering layers:

<syntaxhighlight lang="C" line>
int32 BehindLayer ( int32 dummy, struct Layer *layer );
int32 UpfrontLayer( int32 dummy, struct Layer *layer );
int32 MoveLayerInFrontOf( struct Layer *layer_to_move, struct Layer *other_layer );
</syntaxhighlight>

BehindLayer() moves a layer behind all other layers. This function considers any backdrop layers, moving a current layer behind all others except backdrop layers. UpfrontLayer() moves a layer in front of all other layers. MoveLayerInFrontOf() is used to place a layer at a specific depth, just in front of a given layer.

As areas of simple refresh layers become exposed, due to layer movement or sizing for example, the newly exposed areas have not been drawn into, and need refreshing. The system keeps track of these areas by using a DamageList. To update only those areas that need it, the BeginUpdate() EndUpdate() functions are called.

<syntaxhighlight lang="C" line>
int32 BeginUpdate( struct Layer *l );
VOID EndUpdate ( struct Layer *layer, uint32 flag );
</syntaxhighlight>

BeginUpdate() saves the pointer to the current clipping rectangles and installs a pointer to a set of ClipRects generated from the DamageList in the layer structure. To repair the layer, use the graphics rendering routines as if to redraw the entire layer, and the routines will automatically use the new clipping rectangle list. So, only the damaged areas are actually rendered into, saving time.

{{Note|title=Never Modify the DamageList|text=The system generates and maintains the DamageList region. All application clipping should be done through the InstallClipRegion() function.}}

To complete the update process call EndUpdate() which will restore the original ClipRect list.

==== Sub-Layer Rectangle Operations ====

The SwapBitsRastPortClipRect() routine is for applications that do not want to worry about clipping rectangles.

<syntaxhighlight lang="C" line>
VOID SwapBitsRastPortClipRect( struct RastPort *rp, struct ClipRect *cr );
</syntaxhighlight>

For instance, you may use The SwapBitsRastPortClipRect() to produce a menu without using Intuition. There are two ways to produce such a menu:

# Create an up-front layer with CreateUpfrontLayer(), then render the menu in it. This could use lots of memory and require a lot of (very temporary) "slice-and-dice" operations to create all of the clipping rectangles for the existing windows and so on.
# Use SwapBitsRastPortClipRect(), directly on the display drawing area:
#* Render the menu in a back-up area off the display, then lock all of the on-display layers so that no task may use graphics routines to draw over the menu area on the display.
#* Next, swap the on-display bits with the off-display bits, making the menu appear.
#* When finished with the menu, swap again and unlock the layers.

The second method is faster and leaves the clipping rectangles and most of the rest of the window data structures untouched.

{{Note|title=Warning|text=All of the layers must be locked while the menu is visible if you use the second method above. Any task that is using any of the layers for graphics output will be halted while the menu operations are taking place. If, on the other hand, the menu is rendered as a layer, no task need be halted while the menu is up because the lower layers need not be locked.}}

=== Layers Example ===

For the sake of brevity, the example is a single task. No Layer locking is done. Also note that the routine myLabelLayer() is used to redraw a given layer. It is called only when a layer needs refreshing.

<syntaxhighlight lang="C" line>
/* Layers.c */

/* Force use of new variable names to help prevent errors */
#define INTUI_V36_NAMES_ONLY

#include <exec/types.h>
#include <graphics/gfxbase.h>
#include <graphics/layers.h>
#include <graphics/displayinfo.h>

#include <proto/exec.h>
#include <proto/dos.h>
#include <proto/graphics.h>
#include <proto/layers.h>

#include <stdio.h>
#include <stdlib.h>
#include <string.h>

#define L_DELAY (100)
#define S_DELAY (50)

#define DUMMY (0L)

#define RED_PEN (1)
#define GREEN_PEN (2)
#define BLUE_PEN (3)

#define SCREEN_D (2)
#define SCREEN_W (320)
#define SCREEN_H (200)

/* the starting size of example layers, offsets are used for placement */
#define W_H (50)
#define W_T (5)
#define W_B ((W_T+W_H)-1)
#define W_W (80)
#define W_L ((SCREEN_W/2) - (W_W/2))
#define W_R ((W_L+W_W)-1)

/* size of the superbitmap */
#define SUPER_H SCREEN_H
#define SUPER_W SCREEN_W

/* starting size of the message layer */
#define M_H (10)
#define M_T (SCREEN_H-M_H)
#define M_B ((M_T+M_H)-1)
#define M_W (SCREEN_W)
#define M_L (0)
#define M_R ((M_L+M_W)-1)

struct GraphicsIFace *IGraphics = 0;
struct LayersIFace *ILayers = 0;

/* global constant data for initializing the layers */
LONG theLayerFlags[3] = { LAYERSUPER, LAYERSMART, LAYERSIMPLE };
UWORD colortable[] = { 0x000, 0xf44, 0x4f4, 0x44f };

/*
** Clear the layer then draw in a text string.
*/
VOID myLabelLayer(struct Layer *layer, LONG color, UBYTE *string)
{
/* fill layer with color */
IGraphics->SetRast(layer->rp, color);

/* set up for writing text into layer */
IGraphics->SetDrMd(layer->rp,JAM1);
IGraphics->SetAPen(layer->rp,0);
IGraphics->Move(layer->rp, 5, 7);

/* write into layer */
IGraphics->Text(layer->rp, string, strlen(string));
}

/*
** write a message into a layer with a delay.
*/
VOID pMessage(struct Layer *layer, UBYTE *string)
{
IDOS->Delay(S_DELAY);
myLabelLayer(layer, GREEN_PEN, string);
}

/*
** write an error message into a layer with a delay.
*/
VOID error(struct Layer *layer, UBYTE *string)
{
myLabelLayer(layer, RED_PEN, string);
IDOS->Delay(L_DELAY);
}

/*
** do some layers manipulations to demonstrate their abilities.
*/
VOID doLayers(struct Layer *msgLayer, struct Layer *layer_array[])
{
WORD ktr;
WORD ktr_2;

pMessage(msgLayer, "Label all Layers");
myLabelLayer(layer_array[0], RED_PEN, "Super");
myLabelLayer(layer_array[1], GREEN_PEN, "Smart");
myLabelLayer(layer_array[2], BLUE_PEN, "Simple");

pMessage(msgLayer, "MoveLayer 1 InFrontOf 0");
if (!ILayers->MoveLayerInFrontOf(layer_array[1], layer_array[0]))
error(msgLayer, "MoveLayerInFrontOf() failed.");

pMessage(msgLayer, "MoveLayer 2 InFrontOf 1");
if (!ILayers->MoveLayerInFrontOf(layer_array[2], layer_array[1]))
error(msgLayer, "MoveLayerInFrontOf() failed.");

pMessage(msgLayer, "Refresh Simple Refresh Layer");
myLabelLayer(layer_array[2], BLUE_PEN, "Simple");

pMessage(msgLayer, "Incrementally MoveLayers...");
for(ktr = 0; ktr < 30; ktr++)
{
if (!ILayers->MoveLayer(DUMMY, layer_array[1], -1, 0))
error(msgLayer, "MoveLayer() failed.");
if (!ILayers->MoveLayer(DUMMY, layer_array[2], -2, 0))
error(msgLayer, "MoveLayer() failed.");
}

pMessage(msgLayer, "Refresh Simple Refresh Layer");
myLabelLayer(layer_array[2], BLUE_PEN, "Simple");

pMessage(msgLayer, "make Layer 0 the UpfrontLayer");
if (!ILayers->UpfrontLayer(DUMMY, layer_array[0]))
error(msgLayer, "UpfrontLayer() failed.");

pMessage(msgLayer, "make Layer 2 the BehindLayer");
if (!ILayers->BehindLayer(DUMMY, layer_array[2]))
error(msgLayer, "BehindLayer() failed.");

pMessage(msgLayer, "Incrementally MoveLayers again...");
for(ktr = 0; ktr < 30; ktr++)
{
if (!ILayers->MoveLayer(DUMMY, layer_array[1], 0, 1))
error(msgLayer, "MoveLayer() failed.");
if (!ILayers->MoveLayer(DUMMY, layer_array[2], 0, 2))
error(msgLayer, "MoveLayer() failed.");
}

pMessage(msgLayer, "Refresh Simple Refresh Layer");
myLabelLayer(layer_array[2], BLUE_PEN, "Simple");

pMessage(msgLayer, "Big MoveLayer");
for(ktr = 0; ktr < 3; ktr++)
{
if (!ILayers->MoveLayer(DUMMY, layer_array[ktr], -layer_array[ktr]->bounds.MinX, 0))
error(msgLayer, "MoveLayer() failed.");
}

pMessage(msgLayer, "Incrementally increase size");
for(ktr = 0; ktr < 5; ktr++)
{
for(ktr_2 = 0; ktr_2 < 3; ktr_2++)
{
if (!ILayers->SizeLayer(DUMMY, layer_array[ktr_2], 1, 1))
error(msgLayer, "SizeLayer() failed.");
}
}

pMessage(msgLayer, "Refresh Smart Refresh Layer");
myLabelLayer(layer_array[1], GREEN_PEN, "Smart");
pMessage(msgLayer, "Refresh Simple Refresh Layer");
myLabelLayer(layer_array[2], BLUE_PEN, "Simple");

pMessage(msgLayer, "Big SizeLayer");
for(ktr = 0; ktr < 3; ktr++)
{
if (!ILayers->SizeLayer(DUMMY,layer_array[ktr],
SCREEN_W-(layer_array[ktr]->bounds.MaxX)-1,0))
error(msgLayer, "SizeLayer() failed.");
}

pMessage(msgLayer, "Refresh Smart Refresh Layer");
myLabelLayer(layer_array[1], GREEN_PEN, "Smart");
pMessage(msgLayer, "Refresh Simple Refresh Layer");
myLabelLayer(layer_array[2], BLUE_PEN, "Simple");

pMessage(msgLayer, "ScrollLayer down");
for(ktr = 0; ktr < 30; ktr++)
{
for(ktr_2 = 0; ktr_2 < 3; ktr_2++)
{
ILayers->ScrollLayer(DUMMY, layer_array[ktr_2], 0, -1);
}
}

pMessage(msgLayer, "Refresh Smart Refresh Layer");
myLabelLayer(layer_array[1], GREEN_PEN, "Smart");
pMessage(msgLayer, "Refresh Simple Refresh Layer");
myLabelLayer(layer_array[2], BLUE_PEN, "Simple");

pMessage(msgLayer, "ScrollLayer up");
for(ktr = 0; ktr < 30; ktr++)
{
for(ktr_2 = 0; ktr_2 < 3; ktr_2++)
{
ILayers->ScrollLayer(DUMMY, layer_array[ktr_2], 0, 1);
}
}

pMessage(msgLayer, "Refresh Smart Refresh Layer");
myLabelLayer(layer_array[1], GREEN_PEN, "Smart");
pMessage(msgLayer, "Refresh Simple Refresh Layer");
myLabelLayer(layer_array[2], BLUE_PEN, "Simple");

IDOS_>Delay(L_DELAY);
}

/*
** delete the layer array created by allocLayers().
*/
VOID disposeLayers(struct Layer *msgLayer, struct Layer *layer_array[])
{
WORD ktr;

for (ktr = 0; ktr < 3; ktr++)
{
if (layer_array[ktr] != NULL)
{
if (!ILayers->DeleteLayer(DUMMY, layer_array[ktr]))
error(msgLayer, "Error deleting layer");
}
}
}

/*
** Create some hard-coded layers. The first must be super-bitmap, with
** the bitmap passed as an argument. The others must not be super-bitmap.
** The pointers to the created layers are returned in layer_array.
**
** Return FALSE on failure. On a FALSE return, the layers are
** properly cleaned up.
*/
BOOL allocLayers(struct Layer *msgLayer, struct Layer *layer_array[],
struct BitMap *super_bitmap, struct Layer_Info *theLayerInfo,
struct BitMap *theBitMap)
{
WORD ktr;
BOOL create_layer_ok = TRUE;

for (ktr = 0;
(ktr < 3) && (create_layer_ok);
ktr++)
{
pMessage(msgLayer, "Create BehindLayer");
if (ktr == 0)
{
if ((layer_array[ktr] = ILayers->CreateBehindLayer(theLayerInfo, theBitMap,
W_L+(ktr*30), W_T+(ktr*30), W_R+(ktr*30), W_B+(ktr*30),
theLayerFlags[ktr], super_bitmap)) == NULL)
create_layer_ok = FALSE;
}
else
{
if ((layer_array[ktr] = ILayers->CreateBehindLayer(theLayerInfo, theBitMap,
W_L+(ktr*30), W_T+(ktr*30), W_R+(ktr*30), W_B+(ktr*30),
theLayerFlags[ktr], NULL)) == NULL)
create_layer_ok = FALSE;
}

if (create_layer_ok)
{
pMessage(msgLayer, "Fill the RastPort");
IGraphics->SetRast(layer_array[ktr]->rp, ktr + 1);
}
}

if (!create_layer_ok)
disposeLayers(msgLayer, layer_array);

return(create_layer_ok);
}

/*
** Free the bitmap and all bitplanes created by allocBitMap().
*/
VOID disposeBitMap(struct BitMap *bitmap, LONG depth, LONG width, LONG height)
{
WORD ktr;

if (NULL != bitmap)
{
for (ktr = 0; ktr < depth; ktr++)
{
if (NULL != bitmap->Planes[ktr])
IGraphics->FreeRaster(bitmap->Planes[ktr], width, height);
}

IExec->FreeMem(bitmap, sizeof(*bitmap));
}
}

/*
** Allocate and initialize a bitmap structure.
*/
struct BitMap *allocBitMap(LONG depth, LONG width, LONG height)
{
WORD ktr;
BOOL bit_map_failed = FALSE;
struct BitMap *bitmap = NULL;

if (NULL != (bitmap = IExec->AllocMem(sizeof(*bitmap),NULL)))
{
IGraphics->InitBitMap(bitmap,depth,width,height);

for (ktr = 0; ktr < depth; ktr++)
{
if (NULL == (bitmap->Planes[ktr] = (PLANEPTR)IGraphics->AllocRaster(width,height)))
bit_map_failed = TRUE;
else
IGraphics->BltClear(bitmap->Planes[ktr], RASSIZE(width,height), 1);
}
if (bit_map_failed)
{
disposeBitMap(bitmap,depth,width,height);
bitmap = NULL;
}
}
return(bitmap);
}

/*
** Set up to run the layers example, doLayers(). Clean up when done.
*/
VOID startLayers(struct Layer_Info *theLayerInfo, struct BitMap *theBitMap)
{
struct Layer *msgLayer;
struct BitMap *theSuperBitMap;
struct Layer *theLayers[3] = { NULL, NULL, NULL, };

if (NULL != (msgLayer = ILayers->CreateUpfrontLayer(theLayerInfo, theBitMap,
M_L, M_T, M_R, M_B, LAYERSMART, NULL)))
{
pMessage(msgLayer, "Setting up Layers");

if (NULL != (theSuperBitMap = allocBitMap(SCREEN_D, SUPER_W, SUPER_H)))
{
if (allocLayers(msgLayer, theLayers, theSuperBitMap, theLayerInfo, theBitMap))
{
doLayers(msgLayer, theLayers);

disposeLayers(msgLayer, theLayers);
}
disposeBitMap(theSuperBitMap, SCREEN_D, SUPER_W, SUPER_H);
}
if (!ILayers->DeleteLayer(DUMMY, msgLayer))
error(msgLayer, "Error deleting layer");
}
}

/*
** Set up a low-level graphics display for layers to work on. Layers
** should not be built directly on Intuition screens, use a low-level
** graphics view. If you need mouse or other events for the layers
** display, you have to get them directly from the input device. The
** only supported method of using layers library calls with Intuition
** (other than the InstallClipRegion() call) is through Intuition windows.
**
** See graphics primitives articles for details on creating and using the
** low-level graphics calls.
*/
VOID runNewView(VOID)
{
struct View theView;
struct View *oldview;
struct ViewPort theViewPort;
struct RasInfo theRasInfo;
struct ColorMap *theColorMap;
struct Layer_Info *theLayerInfo;
struct BitMap *theBitMap;
UWORD *colorpalette;
WORD ktr;

/* save current view, to be restored when done */
if (NULL != (oldview = GfxBase->ActiView))
{
/* get a LayerInfo structure */
if (NULL != (theLayerInfo = ILayers->NewLayerInfo()))
{
if (NULL != (theColorMap = IGraphics->GetColorMap(4)))
{
colorpalette = (UWORD *)theColorMap->ColorTable;
for(ktr = 0; ktr < 4; ktr++)
*colorpalette++ = colortable[ktr];

if (NULL != (theBitMap = allocBitMap(SCREEN_D, SCREEN_W, SCREEN_H)))
{
IGraphics->InitView(&theView);
IGraphics->InitVPort(&theViewPort);

theView.ViewPort = &theViewPort;

theViewPort.DWidth = SCREEN_W;
theViewPort.DHeight = SCREEN_H;
theViewPort.RasInfo = &theRasInfo;
theViewPort.ColorMap = theColorMap;

theRasInfo.BitMap = theBitMap;
theRasInfo.RxOffset = 0;
theRasInfo.RyOffset = 0;
theRasInfo.Next = NULL;

IGraphics->MakeVPort(&theView, &theViewPort);
IGraphics->MrgCop(&theView);
IGraphics->LoadView(&theView);
IGraphics->WaitTOF();

startLayers(theLayerInfo, theBitMap);

/* put back the old view, wait for it to become
** active before freeing any of our display
*/
IGraphics->LoadView(oldview);
IGraphics->WaitTOF();

/* free dynamically created structures */
IGraphics->FreeVPortCopLists(&theViewPort);
IGraphics->FreeCprList(theView.LOFCprList);

disposeBitMap(theBitMap, SCREEN_D, SCREEN_W, SCREEN_H);
}
IGraphics->FreeColorMap(theColorMap); /* free the color map */
}
ILayers->DisposeLayerInfo(theLayerInfo);
}
}
}

/*
** Open the libraries used by the example. Clean up when done.
*/
int main(int argc, char **argv)
{
struct Library *GfxBase = IExec->OpenLibrary("graphics.library", 50);
struct Library *LayersBase = IExec->OpenLibrary("layers.library", 50);
IGraphics = (struct GraphicsIFace*)IExec->GetInterface(GfxBase, "main", 1, NULL);
ILayers = (struct LayersIFace*)IExec->GetInterface(LayersBase, "main", 1, NULL);

if (IGraphics != NULL && ILayers != NULL)
{
runNewView();
}

IExec->DropInterface((struct Interface*)ILayers);
IExec->DropInterface((struct Interface*)IGraphics);
IExec->CloseLibrary(LayersBase);
IExec->CloseLibrary(GfxBase);

return 0;
}
</syntaxhighlight>

== Function Reference ==

The following are brief descriptions of the layers library functions. See the SDK for details on each function call.

{| class="wikitable"
|+ Layers Library Functions
! Function
! Description
|-
| NewLayerInfo()
| Allocating a Layer_Info structure.
|-
| DisposeLayerInfo()
| Deallocating a Layer_Info structure.
|-
| CreateUpfrontLayer()
| Make a new layer in front of others.
|-
| CreateBehindLayer()
| Make a new layer behind others.
|-
| DeleteLayer()
| Remove and delete an existing layer.
|-
| MoveLayer()
| Change the position (not depth) of a layer.
|-
| SizeLayer()
| Change the size of a layer.
|-
| ScrollLayer()
| Change the internal coordinates of a layer.
|-
| BehindLayer()
| Depth arrange a layer behind others.
|-
| UpfrontLayer()
| Depth arrange a layer in front of others.
|-
| MoveLayerInFrontOf()
| Depth arrange a layer to a specific position.
|-
| WhichLayer()
| Find the frontmost layer at a position.
|-
| SwapBitsRastPortClipRect()
| Fast, non-layered and non-damaging display operation.
|-
| BeginUpdate()
| Synchronize optimized refreshing for layer.
|-
| EndUpdate()
| End optimized layer refresh.
|-
| LockLayer()
| Lock out rendering in a single layer.
|-
| UnlockLayer()
| Release LockLayer() lock.
|-
| LockLayers()
| Lock out rendering in all layers of a display.
|-
| UnlockLayers()
| Release LockLayers() lock.
|-
| LockLayerInfo()
| Gain exclusive access to the display‚Äôs layers.
|-
| UnlockLayerInfo()
| Release LockLayerInfo() lock.
|-
| InstallClipRegion()
| Add a clipping region to a layer.
|}

Using Crash-Logs for Debugging

2025-01-26T19:33:28Z

Costel Mincea: Text replacement - "<syntaxhighlight>" to "<syntaxhighlight lang="C" line>"

[[Category:Debug]]
= Introduction =

Bugs in software are a fact of life. It is almost impossible to write software with zero bugs. To date, no-one has come up with a method of even proving that a computer program is bug-free. Given these facts, it would be desirable to obtain as much information as possible about any crash that occurs. This is essential for debugging purposes.

AmigaOS provides substantial information via the Grim-Reaper. The Grim-Reaper pops up whenever a program performs an illegal operation, and provides a whole host of information about the crash. Details that are listed include the name of the program/library in which the crash occurred is listed along with the state of the CPU, a stack trace, and other state information. This information could be used in order to isolate the specific line of code at which the program crashed. However, this requires suitable preparation.

[[File:UsingCrashLogs1.jpg|center|frame|The Grim Reaper displaying a DSI error.]]

It is possible to embed debug information into a binary. However, this is undesirable in software being released to consumers as the binaries are inflated to several times the original size (tens of megabytes in size is easily obtainable in this manner). From the customers perspective, this is completely wasted space. Also, it gives a wealth of information about the internals of your program, which is undesirable. As will be shown below, there is a methodt hat can be used to provide compact binaries to end-users whilst still being able to use their crash-logs in order to locate and fix bugs.

= Enabling Debugging =

It is very easy to enable debugging in GCC. Simply add the compiler flag "-gstabs" when compiling and linking. This tells GCC that you wish to include debugging symbols in the binary, and even works if optimizations are enabled. "Stabs" is a particular format in which the debugging symbol; "-ggdb" is another option that also adds debugging symbols, but in a different format. However, I have been told that there are issues with "-ggdb" and large applications, so it is best to stick to "-gstabs."

= Debug Binaries =

As was mentioned previously, enabling debug symbols inflates the binray size significantly. What many people do not realize is that it is possible to create a separate file that contains all the debug information; here is an excerpt from the make-file that achieves this:

$(TARGET): $(OBJS)
$(CC) $(CFLAGS) -o $@.debug $(OBJS) $(LIBS) $(LINK)
$(STRIP) $@.debug -o $@

Where CFLAGS = -mcrt=newlib $(OPTIMIZE) -Wall -gstabs

In the [[Media:usingcrashlogs.lha|example template]] this translates to:
gcc -mcrt=newlib -O3 -Wall -gstabs -c -o badboy.o badboy.c
gcc -mcrt=newlib -O3 -Wall -gstabs -o badboy.debug badboy.o
strip badboy.debug badboy

The first line compiles the single source-file, badboy.c. The next one links it, and creates an executable called badboy.debug, which contains all the debugging symbols. Finally, strip removes all the debugging symbols and creates a binary called badboy. This stripped binary can then be distributed to end-users; badboy.debug is kept by the developer for interpreting crash-logs.

= Interpreting Crash-Logs =

This is best understood by example. Download and extract the [[Media:usingcrashlogs.lha|example template]]. Open a shell window and change to the directory containing the template code. Type make, and press enter. This will compile a program called badboy that deliberately performs an illegal operation. It performs a classical NULL-pointer dereferencing for a write operation; a very common bug. Now run badboy; the grim-reaper should pop up and display the error message below.

[[File:UsingCrashLogs1.jpg|center|frame|The Grim Reaper displaying a DSI error.]]

''Note about the "redzone" message:''
The lower part of the stack is made up of unmapped virtual pages that throw an exception when accessed, to prevent the program from wreaking havoc.
A redzone is a stack barrier that makes the program exhausting it's stack space crash. With memory, the term "electric fence" has been established for "hot" barriers (due to the name given to a tool under Linux that was used for this purpose).

Now click on "More..." and select the "Stack Trace" tab. Clicking on the "Generate Stack Trace" button will generate a stack trace.

[[File:UsingCrashLogs2.jpg|center|frame|A stack trace for the program "badboy"]]

This shows that the crash occurred within "badboy" in section 5 at 0x608. Open a new shell window and change to the directory containing "badboy" once again. Enter the following line:

addr2line -e badboy.debug --section=.text 0x608

This performs a lookup of 0x608 inside "badboy.debug," which contains the debug symbols. Addr2line will respond by giving the file and line number of this address.

[[File:UsingCrashLogs3.jpg|center|frame|A stack trace for the program "badboy"]]

Line 25 performs a write to address zero:

<syntaxhighlight lang="C" line>
int *a = NULL;
*a = 0;
</syntaxhighlight>

The procedure above has identified the exact source-line at which the crash occurred. In this case the crash was deliberate in order to present an easy to understand example. However, in a real application, the*.debug version of each release would be kept by the developer so that crash-logs submitted by users can be used in order to identify the source-line at which the crash occurred. If you look at the [http://hdrlab.org.nz/articles/amiga-os-articles/minigl-templates/ MiniGL templates] that I have written, you will notice that all of them use this technique.

= Download =

[[Media:usingcrashlogs.lha|Using crash-logs template and example]]

= Wish-List =

Whilst the technique above works, a more automated bug tracking system would be nice. The first component of such a system would be an automated crash-log submission system. If Grim Reaper provided a singl-click method of submitting a bug report to the developer via the internet, more crash-logs are likely to be submitted. Having a tool that would parse the crash-log and automatically find file names and line numbers for the entry in the crash-log would also be useful.

= Author =

Copyright (c) 2008 Hans de Ruiter. 
Reproduced with permission. 
See the original article [http://hdrlab.org.nz/articles/amiga-os-articles/using-crash-logs/ here].

AmiWest Setup

2025-01-26T19:33:15Z

Costel Mincea: Text replacement - "<syntaxhighlight>" to "<syntaxhighlight lang="C" line>"

= Setup =

Developing software on and for AmigaOS involves three major components: the '''AmigaOS SDK''' or "Software Development Kit", a source code '''Editor''' and your '''imagination'''.

The first part of this equation, the AmigaOS Software Development Kit or '''AmigaOS SDK''', is a collection of files and tools that will convert your source code into an Amiga application. The SDK consists of a collection of the latest documentation, "include" files, example code, utilities and the GCC compiler. With each major version of AmigaOS a new SDK is issued that allows developers and their applications take advantage of the latest OS features.

The second part of the equation is a means to edit and manage your programming project and its source code. While you can edit source code in the AmigaOS '''NotePad''' text editor, there are much better & easier ways. The most powerful programming environment on AmigaOS is called [http://codebench.co.uk/ CodeBench]. In addition to providing a source code editor that provide syntax highlighting, help as you type and context sensitive help, CodeBench takes care of building "makefiles", runs the compiler, collects & presents errors and can interact to remote source code servers.

Finally there is '''you'''! Obviously, developing AmigaOS applications with the SDK requires a working understanding of the C language. To take advantage of the specific powers of AmigaOS, there are more methodologies and functions to learn. The SDK provides a number of example programs to learn from and a bounty of "autodocs" that document AmigaOS functions. Every day there are new things to learn.

== Installing the SDK ==

The latest version of the SDK can be downloaded from the Hyperion Entertainment [http://www.hyperion-entertainment.biz/index.php?option=com_registration&view=files&parent=30&Itemid=63 SDK webpage].

Once downloaded, you can double-click on the SDK archive file to use the AmigaOS '''Unarc''' utility to decompress the SDK to your RAM Disk. This will create a directory that includes all the SDK files to be installed.

In that directory you will find the '''Install SDK''' installer program. If you run that, it will ask you what you want to install and for a location to install to. Unless you have a severe limitation on hard disk space, it's recommended you make a "Full" install. As part of the install process, a few commands will be added to your "user-startup" script to assign SDK: to your system.

Once the SDK installation is complete, your SDK: path will include the following directories:

* '''Documentation''' - This drawer contains various documentation, AutoDocs, and other information related to the SDK. It also contains documentation on the various tools and compilers.

* '''Examples''' - This drawer contains example source code on how to program for AmigaOS 4.x. Examples are sorted by theme/topic.

* '''Local''' - The Local drawer is our means of isolating the compilers and third-party additions. See SDK documentation PDF file for more information on the Local drawer.

* '''gcc''' - The gcc drawer contains the GNU C/C++ compiler. It is set up in a way that there are no user-serviceable parts inside. This makes it easy to exchange the compiler when later versions become available.

* '''Include''' - This drawer contains system-level include files. Like the gcc drawer, it should not need to be modified.

* '''Contrib''' - The Contrib drawer contains various files that where contributed to the SDK. Among other things, it contains the latest source code for the static C runtime library clib2.

You can test the installation of SDK and its GCC compiler by opening a shell and typing the following command:

gcc --version

This should cause a text to be printed by the compiler, including the version number.

== Testing the SDK ==

Open the '''NotePad''' text editor and type the following text:

<syntaxhighlight lang="C" line>
#include <proto/dos.h>

int main(void)
{
IDOS->Printf("Hello, World\n");
return 0;
}
</syntaxhighlight>

Then save the file to "hello_world.c" and go back to the shell, CD to the directory with your file and enter this command:

gcc -o hello_world hello_world.c

After a few seconds, the gcc compiler should return. As long the source was correctly entered and no errors or warnings were displayed by GCC, then you will have successfully compiled your first Amiga program. Just type "hello_world" into the command line to see it run. Congratulations!

== Installing CodeBench ==

You may have used the '''NotePad''' text editor and your Shell console to create the sample C program above, but there are much better ways to edit and compile C programs. Such development systems provide more specialized editors suited for coding and means for managing compilation, handling warnings and errors, etc.

On AmigaOS we have '''CodeBench''' to improve and automate our coding sessions. CodeBench provides a text editor with "syntax highlighting" which means that it color-codes text on the basis of what it is: comments, commands, strings, etc. CodeBench also provides a GUI for GCC - click a button to compile, review the results in a window. There are even more features for more serious projects.

CodeBench can be downloaded from the [http://codebench.co.uk/downloads.php website] of the developer, SImon Archer. Once downloaded, you can double-click on the archive to open it in the AmigaOS '''Unarc''' utility and decompress the files to your RAM Disk. Once finished, you will find an "Install CodeBench" installer program icon. When you run the installer, it will confirm whether you are upgrading or making a new install and ask you for a location.

Once this process is done, you're ready to start a project in CodeBench. CodeBench comes with comprehensive documentation on itself in web format (that can also be accessed [http://codebench.co.uk/docs/codebench.html here]).

== Testing CodeBench: Hello World ==

The first thing you can do with CodeBench is to start a test project to how things work. At [http://codebench.co.uk/docs/started.html this page] you can find information on on starting a project. Basically, it's a matter of clicking the Start Project button, setting a few names and variables and entering a path for your project.

Once the new project is established, then you can use the "Editor/Create New File..." menu item to start a new source file. If you copy the above "Hello World" source code and paste it into the editor and save the source as "hello-world.c" then you will be ready for compiling.

In the CodeBench tool bar window, click the green "Build" button and CodeBench will automatically prepare, compile and link your project into an executable program.
A Build window will appear that will show the status of the building of your project. Assuming your code compiles without errors, you will then see a Run button with a play icon in the CodeBench toolbar. Clicking that button will bring up a window to let you run your program.

== Testing CodeBench: Hello with a GUI ==

Once you start coding with CodeBench, you will find it provides a number of aids to help with coding: such as highlighting or coloring the source code by type, letting you work with a number of sources at one time, letting you access AmigaOS documents by shift-double-clicking on AmigaOS functions and providing a quick way to track compiling errors into the source code.

With CodeBench you can easily jump into more advanced coding, such as our old "Hello World" program with a modern GUI. Just copy and paste the following source into a new project and try to compile it:

<syntaxhighlight lang="C" line>
#include <dos/dos.h>
#include <classes/window.h>
#include <gadgets/button.h>
#include <gadgets/layout.h>
#include <images/label.h>

#include <proto/intuition.h>
#include <proto/exec.h>

int main(void)
{
// Create a window with a label and button.

Object* winobj = IIntuition->NewObject(NULL, "window.class",
WA_Title, "Hello World Example",
WA_Activate, TRUE,
WA_DepthGadget, TRUE,
WA_DragBar, TRUE,
WA_CloseGadget, TRUE,
WA_SizeGadget, TRUE,
WINDOW_Position, WPOS_CENTERMOUSE,

WINDOW_Layout, IIntuition->NewObject(NULL, "layout.gadget",
LAYOUT_Orientation, LAYOUT_ORIENT_VERT,
LAYOUT_SpaceOuter, TRUE,
LAYOUT_DeferLayout, TRUE,

LAYOUT_AddImage, IIntuition->NewObject(NULL, "label.image",
LABEL_Text, "Hello, World",
TAG_END),

LAYOUT_AddChild, IIntuition->NewObject(NULL, "button.gadget",
GA_RelVerify, TRUE,
GA_Text, "Quit",
TAG_END),
TAG_END),
TAG_END);

if (winobj != NULL)
{
// Open the window.
struct Window *window = (struct Window *) IIntuition->IDoMethod(winobj, WM_OPEN);

if (window != NULL)
{
// Obtain the window wait signal mask.

uint32 signal = 0;
IIntuition->GetAttr(WINDOW_SigMask, winobj, &signal);

// Input Event Loop

BOOL done = FALSE;

while (!done)
{
uint32 wait = IExec->Wait(signal | SIGBREAKF_CTRL_C);

if ( wait & SIGBREAKF_CTRL_C )
{
done = TRUE;
break;
}

if ( wait & signal )
{
uint32 result = WMHI_LASTMSG;
int16 code = 0;

while ((result = IIntuition->IDoMethod(winobj, WM_HANDLEINPUT, &code)) != WMHI_LASTMSG)
{
switch (result & WMHI_CLASSMASK)
{
case WMHI_GADGETUP:
done = TRUE;
break;

case WMHI_CLOSEWINDOW:
window = NULL;
done = TRUE;
break;
}
}
}
}
}

/* Disposing of the window object will also close the window if it is
* already opened and all attached objects.
*/
IIntuition->DisposeObject(winobj);
}

return RETURN_OK;
}
</syntaxhighlight>

Once you have built and run this example program the following GUI will be produced:

[[File:HelloWorldWindow.png]]

Intuition Borders

2025-01-26T19:32:23Z

Costel Mincea: Text replacement - "<syntaxhighlight>" to "<syntaxhighlight lang="C" line>"

= Creating Borders =

This data type is called a Border since it was originally used to create border lines around display objects. It is actually a general purpose structure for drawing connected lines between any series of points.

A Border is easier to use than an Image structure. Only the following need be specified to define a border:

* An internal position component which is used in determining the final position of the border.
* A set of coordinate pairs for each vertex.
* A color for the lines.
* One of several drawing modes.

== Border Structure Definition ==

To use a border, the application must create one or more instances of the Border structure. Here is the specification:

<syntaxhighlight lang="C" line>
struct Border
{
WORD LeftEdge, TopEdge;
UBYTE FrontPen, BackPen;
UBYTE DrawMode;
BYTE Count;
WORD *XY;
struct Border *NextBorder;
};
</syntaxhighlight>

Here is a brief description of the fields of the Border structure.

; LeftEdge, TopEdge
: These fields are used to determine the position of the Border relative to its base position (the base position is the upper left corner for requesters, menus, or gadgets and is specified in the call to DrawBorder() for windows and screens).

; FrontPen, BackPen
: These fields contain color registers numbers. FrontPen is the color used to draw the lines. BackPen is currently unused.

;DrawMode
: Set the DrawMode field to one of the following:
:{| class="wikitable"
| JAM1
| Use FrontPen to draw the line.
|-
| COMPLEMENT
| Change the pixels within the lines to their complement color.
|}

; Count
: Specify the number of data points used in this border. Each data point is described by two words of data in the XY array.

; XY
: A pointer to an array of coordinate pairs, one pair for each point. These coordinates are measured relative to the position of the border.

; NextBorder
: This field is a pointer to another instance of a Border structure. Set this field to NULL if this is the last Border structure in the linked list.

= Directly Drawing the Borders =

Borders may be directly drawn by the application by calling the function DrawBorder().

<syntaxhighlight lang="C" line>
VOID DrawBorder( struct RastPort *rp, struct Border *border,
LONG leftOffset, LONG topOffset );
</syntaxhighlight>

The rp argument is a pointer to the RastPort into which the border should be drawn. This rastport may come from a Window or Screen structure.

The border argument is a pointer to a list of Border structures which are to be rendered. The list may contain a single Border structure.

The leftOffset and topOffset arguments are the external component, or base position, for this list of Borders. The LeftEdge and TopEdge values of each Border structure are added to these to determine the Border position.

Borders may also be indirectly drawn by attaching them to gadgets, menus or requesters.

= Border Example =

The following example draws a double border using two pens to create a shadow effect. The border is drawn in two positions to show the flexibility in positioning borders, note that it could also be attached to a menu, gadget or requester.

<syntaxhighlight lang="C" line>
/*
** shadowborder.c - program to show the use of an Intuition Border.
*/
#include <exec/types.h>
#include <intuition/intuition.h>

#include <proto/exec.h>
#include <proto/dos.h>
#include <proto/intuition.h>

struct Library *IntuitionBase = NULL;

#define MYBORDER_LEFT (0)
#define MYBORDER_TOP (0)

/* This is the border data. */
int16 myBorderData[] =
{
0,0, 50,0, 50,30, 0,30, 0,0,
};

/*
** main routine. Open required library and window and draw the images.
** This routine opens a very simple window with no IDCMP. See the
** articles on "Windows" and "Input and Output Methods" for more info.
** Free all resources when done.
*/
int main()
{
struct Screen *screen;
struct DrawInfo *drawinfo;
struct Window *win;
struct Border shineBorder;
struct Border shadowBorder;

uint32 mySHADOWPEN = 1; /* set default values for pens */
uint32 mySHINEPEN = 2; /* in case can't get info... */

struct Library *IntuitionBase = IExec->OpenLibrary("intuition.library", 50);
IIntuition = (struct IntuitionIFace*)IExec->GetInterface(IntuitionBase, "main", 1, NULL);

if (IIntuition != NULL)
{
if (screen = IIntuition->LockPubScreen(NULL))
{
if (drawinfo = IIntuition->GetScreenDrawInfo(screen))
{
/* Get a copy of the correct pens for the screen.
** This is very important in case the user or the
** application has the pens set in a unusual way.
*/
mySHADOWPEN = drawinfo->dri_Pens[SHADOWPEN];
mySHINEPEN = drawinfo->dri_Pens[SHINEPEN];

IIntuition->FreeScreenDrawInfo(screen,drawinfo);
}

IIntuition->UnlockPubScreen(NULL,screen);
}

/* open a simple window on the workbench screen for displaying
** a border. An application would probably never use such a
** window, but it is useful for demonstrating graphics...
*/
if (win = IIntuition->OpenWindowTags(NULL,
WA_PubScreen, screen,
WA_RMBTrap, TRUE,
TAG_END))
{
/* set information specific to the shadow component of the border */
shadowBorder.LeftEdge = MYBORDER_LEFT + 1;
shadowBorder.TopEdge = MYBORDER_TOP + 1;
shadowBorder.FrontPen = mySHADOWPEN;
shadowBorder.NextBorder = &shineBorder;

/* set information specific to the shine component of the border */
shineBorder.LeftEdge = MYBORDER_LEFT;
shineBorder.TopEdge = MYBORDER_TOP;
shineBorder.FrontPen = mySHINEPEN;
shineBorder.NextBorder = NULL;

/* the following attributes are the same for both borders. */
shadowBorder.BackPen = shineBorder.BackPen = 0;
shadowBorder.DrawMode = shineBorder.DrawMode = JAM1;
shadowBorder.Count = shineBorder.Count = 5;
shadowBorder.XY = shineBorder.XY = myBorderData;

/* Draw the border at 10,10 */
IIntuition->DrawBorder(win->RPort,&shadowBorder,10,10);

/* Draw the border again at 100,10 */
IIntuition->DrawBorder(win->RPort,&shadowBorder,100,10);

/* Wait a bit, then quit.
** In a real application, this would be an event loop, like the
** one described in the Intuition Input and Output Methods article.
*/
IDOS->Delay(200);

IIntuition->CloseWindow(win);
}
}

IExec->DropInterface((struct Interface*)IIntuition);
IExec->CloseLibrary(IntuitionBase);

return 0;
}
</syntaxhighlight>

= Border Colors and Drawing Modes =

Borders can select their colors from the values set in the color registers for the screen in which they are rendered. The available number of colors and palette settings are screen attributes and may not be changed through border rendering.

Two drawing modes pertain to border lines: JAM1 and COMPLEMENT. To draw the line in a specific color, use the JAM1 draw mode. This mode converts each pixel in the line to the color set in the FrontPen field.

Selecting the COMPLEMENT draw mode causes the line to be drawn in an exclusive-or mode that inverts the color of each pixel within the line. The data bits of the pixel are changed to their binary complement. This complement is formed by reversing all bits in the binary representation of the color register number. In a three bitplane display, for example, color 6 is 110 in binary. In COMPLEMENT draw mode, if a pixel is color 6, it will be changed to the 001 (binary), which is color 1. Note that a border drawn in COMPLEMENT mode can be removed from a static display by drawing the border again in the same position.

= Border Coordinates =

Intuition draws lines between points that are specified as sets of X, Y coordinates. Border data does not have to be in Chip memory.

The XY field contains a pointer to an array of coordinate pairs. All of these coordinates are offsets relative to the Border position, which is determined by the sum of the external and internal position components as described above. The coordinate pairs are ordered sequentially. The first two numbers make up the first coordinate pair, the next two numbers make up the second pair, and so on. Within a coordinate pair, the first number is the X offset and the second number is the Y offset.

The first coordinate pair describes the starting point of the first line. When the Border is rendered, a line is drawn between each pair of points. The first line is drawn from point one to point two, the second line is drawn from point two to point three, and so on, until the final point is reached.

The numbers specified in the XY array may be positive or negative. Negative values move up and to the left relative to the Border position, positive values move down and to the right. Again, the Border position is determined by adding the external position component and the internal position component. For example, a Border attached to a Gadget has an external component equal to the upper left corner of the gadget’s select box. The internal component is set within the Border structure itself. These two components are added together and offsets from the resulting position, specified within the XY array, determine where the lines of the Border will appear.

Suppose the top left corner of the select box of the gadget is at window position (10,5). If the Border has LeftEdge set to 10 and TopEdge set to 10, then the Border is positioned at (10+10,5+10), that is (20,15). All XY coordinates will be relative to this Border position. If the XY array contains ‘0,5, 15,5, 15,0’, then the relative coordinates will be (0,5), (15,5) and (15,0). Adding each coordinate to the Border position gives the absolute position of the lines within the window. This Border will draw two lines in the window, one from (20,20) to (35,20) and the second from (35,20) to (35,15).

[[File:LibFig8-3.png|frame|center|Example of Border Relative Position]]

To create a border that is outside the select box of a gadget, specify negative values in the internal component or use negative values for the initial XY values. For example, setting LeftEdge to -1 and TopEdge to -1 moves the position of the Border one pixel above and one pixel to the left of the gadget’s select box.

= Linking Borders =

The NextBorder field can point to another instance of a Border structure. This allows complex graphic objects to be created by linking together Border structures, each with its own data points, color and draw mode. This might be used, for instance, to draw a double border around a requester or gadget where the outer border is a second Border structure, linked to the first inner border.

Note that the borders can share data. For instance, to create a border with a shadow, link two borders together each of which points to the same XY data. Set the first border to draw in a dark pen (such as the SHADOWPEN from the screen’s DrawInfo structure) and position the border down and to the right a few pixels by changing LeftEdge and TopEdge in the Border structure.

The second border should be set to a bright pen (such as the SHINEPEN in the screen’s DrawInfo structure). When the border is drawn, the first border will draw in a dark color and then the second border will be drawn over it in a light color. Since they use the same data set, and the dark border is shifted down and to the right, the border will have a three dimensional appearance. This technique is demonstrated in the example listed earlier in this section.

Gameport Device

2025-01-26T19:32:20Z

Costel Mincea: Text replacement - "<syntaxhighlight>" to "<syntaxhighlight lang="C" line>"

[[Category:Devices|Gameport]]{{NeedUpdate}}
== Gameport Device ==

The gameport device manages access to the Amiga gameport connectors for the operating system. It enables the Amiga to interface with various external pointing devices like mice (two and three button), joysticks, trackballs and light pens. There are two units in the gameport device, unit 0 and unit 1.

'''Amiga Gameport Controllers'''

{| class="wikitable"
!
! Unit 0
! Unit 1
|-
| A3000
| Front Connector
| Back Connector
|-
| A2000
| Left Connector
| Right Connector
|-
| A1000
| 1
| 2
|-
| A500
| 1 JOYSTICK
| 2 JOYSTICK
|}

== Gameport Device Commands and Functions ==

{| class="wikitable"
! Command
! Command Operation
|-
| CMD_CLEAR
| Clear the gameport input buffer.
|-
| GPD_ASKCTYPE
| Return the type of gameport controller being used.
|-
| GPD_ASKTRIGGER
| Return the conditions that have been preset for triggering.
|-
| GPD_READEVENT
| Read one or more gameport events.
|-
| GPD_SETCTYPE
| Set the type of the controller to be used.
|-
| GPD_SETTRIGGER
| Preset the conditions that will trigger a gameport event.
|}

{{Note|title=Who Runs The Mouse?|text=When the input device or Intution is operating, unit 0 is usually dedicated to gathering mouse events. The input device uses the gameport device to read the mouse events. (For applications that take over the machine without starting up the input device or Intuition, unit 0 can perform the same functions as unit 1.) See [[Input_Device|Input Device]] for more information on the input device.}}

== Device Interface ==

The gameport device operates like the other Amiga devices. To use it, you must first open the gameport device, then send I/O requests to it, and then close it when finished. See [[Exec_Device_I/O|Exec Device I/O]] for general information on device usage.

The I/O request used by the gameport device is called IOStdReq.

<syntaxhighlight lang="C" line>
struct IOStdReq
{
struct Message io_Message;
struct Device *io_Device; /* device node pointer */
struct Unit *io_Unit; /* unit (driver private)*/
UWORD io_Command; /* device command */
UBYTE io_Flags;
BYTE io_Error; /* error or warning num */
ULONG io_Actual; /* actual number of bytes transferred */
ULONG io_Length; /* requested number bytes transferred*/
APTR io_Data; /* points to data area */
ULONG io_Offset; /* offset for block structured devices */
};
</syntaxhighlight>

See the include file exec/io.h for the complete structure definition.

=== Opening the Gameport Device ===

Three primary steps are required to open the gameport device:

* Create a message port using CreatePort(). Reply messages from the device must be directed to a message port.
* Create an I/O request structure of type IOStdReq. The IOStdReq structure is created by the CreateExtIO() function. CreateExtIO() will initialize the I/O request with your reply port.
* Open the gameport device. Call OpenDevice(), passing the I/O request and and indicating the unit you wish to use.

<pre>struct MsgPort *GameMP; /* Message port pointer */
struct IOStdReq *GameIO; /* I/O request pointer */

/* Create port for gameport device communications */
if (!(GameMP = CreatePort("RKM_game_port",0)))
cleanexit(" Error: Can't create port\n",RETURN_FAIL);

/* Create message block for device I/O */
if (!(GameIO = CreateExtIO(GameMP,sizeof(struct IOStdReq))))
cleanexit(" Error: Can't create I/O request\n",RETURN_FAIL);

/* Open the right/back (unit 1, number 2) gameport.device unit */
if (error=OpenDevice("gameport.device",1,GameIO,0))
cleanexit(" Error: Can't open gameport.device\n",RETURN_FAIL);</pre>
The gameport commands are unit specific. The unit number specified in the call to OpenDevice() determines which unit is acted upon.

=== Gameport Device Controllers ===

The Amiga has five gameport device controller types.

'''Gameport Device Controllers'''

{| class="wikitable"
! Controller Type
! Description
|-
| GPCT_MOUSE
| Mouse controller
|-
| GPCT_ABSJOYSTICK
| Absolute (digital) joystick
|-
| GPCT_RELJOYSTICK
| Relative (digital) joystick
|-
| GPCT_ALLOCATED
| Custom controller
|-
| GPCT_NOCONTROLLER
| No controller
|}

To use the gameport device, you must define the type of device connected to the gameport and define how the device is to respond. The gameport device can be set up to return the controller status immediately or only when certain conditions have been met.

When a gameport device unit reponds to a request for input, it creates an input event. The contents of the input event will vary based on the type of device and the trigger conditions you have declared.

* A mouse controller can report input events for one, two, or three buttons and for positive or negative (x,y) movements. A trackball controller or car-driving controller is generally of the same type and can be declared as a mouse controller.

* An absolute joystick reports one single event for each change of its current location. If, for example, the joystick is centered and the user pushes the stick forward and holds it in that position, only one single forward-switch event will be generated.

* A relative joystick, on the other hand, is comparable to an absolute joystick with “autorepeat” installed. As long as the user holds the stick in a position other than centered, the gameport device continues to generate position reports.

* There is currently no system software support for proportional joysticks or proportional controllers (e.g., paddles). If you write custom code to read proportional controllers or other controllers (e.g., light pen) make certain that you issue GPD_SETCTYPE (explained below) with controller type GPCT_ALLOCATED to insure that other applications know the connector is being used.

{| class="wikitable"
| ''GPCT_NOCONTROLLER'' The controller type GPCT_NOCONTROLLER is not a controller at all, but a flag to indicate that the unit is not being used at the present time.
|}

=== Closing the Gameport Device ===

Each OpenDevice() must eventually be matched by a call to CloseDevice().

All I/O requests must be complete before CloseDevice(). If any requests are still pending, abort them with AbortIO() and remove them with WaitIO().

<pre>if (!(CheckIO(GameIO)))
{
AbortIO(GameIO); /* Ask device to abort request, if pending */
}
WaitIO((GameIO); /* Wait for abort, then clean up */
CloseDevice(GameIO);</pre>

== Gameport Events ==

A gameport event is an InputEvent structure which describes the following:

* The class of the event - always set to IECLASS_RAWMOUSE for the gameport device.
* The subclass of the event - 0 for the left port; 1 for the right port.
* The code - which button and its state. (No report = 0xFF)
* The qualifier - only button and relative mouse bits are set.
* The position - either a data address or mouse position count.
* The time stamp - delta time since last report, returned as frame count in tv_secs field.
* The next event - pointer to next event.

<pre>struct InputEvent GameEV
{
struct InputEvent *ie_NextEvent; /* next event */
UBYTE ie_Class; /* input event class */
UBYTE ie_SubClass; /* subclass of the class */
UWORD ie_Code; /* input event code */
UWORD ie_Qualifier; /* event qualifiers in effect */
union
{
struct
{
WORD ie_x; /* x position for the event */
WORD ie_y; /* y position for the event */
} ie_xy;
APTR ie_addr;
} ie_position;
struct timeval ie_TimeStamp; /* delta time since last report
}</pre>
See the include file devices/inputevent.h for the complete structure definition and listing of input event fields.

=== Reading Gameport Events ===

You read gameport events by passing an I/O request to the device with GPD_READEVENT set in io_Command, the address of the InputEvent structure to store events set in io_Data and the size of the structure set in io_Length.

<pre>struct InputEvent GameEV;
struct IOStdRequest *GameIO; /* Must be initialized prior to using */

void send_read_request()
{
GameIO->io_Command = GPD_READEVENT; /* Read events */
GameIO->io_Length = sizeof (struct InputEvent);
GameIO->io_Data = (APTR)&GameEV; /* put events in GameEV*/
SendIO(GameIO); /* Asynchronous */
}</pre>
=== Setting Gameport Event Trigger Conditions ===

You set the conditions that can trigger a gameport event by passing an I/O request to the device with GPD_SETTRIGGER set in io_Command and the address of a GamePortTrigger structure set in io_Data.

The information needed for gameport trigger setting is placed into a GamePortTrigger data structure which is defined in the include file devices/gameport.h.

<syntaxhighlight lang="C" line>
struct GamePortTrigger
{
UWORD gpt_Keys; /* key transition triggers */
UWORD gpt_Timeout; /* time trigger (vertical blank units) */
UWORD gpt_XDelta; /* X distance trigger */
UWORD gpt_YDelta; /* Y distance trigger */
}
</syntaxhighlight>

A few points to keep in mind with the GPD_SETTRIGGER command are:

* Setting GPTF_UPKEYS enables the reporting of upward transitions. Setting GPTF_DOWNKEYS enables the reporting of downward transitions. These flags may both be specified.

* The field gpt_Timeout specifies the time interval (in vertical blank units) between reports in the absence of another trigger condition. In other words, an event is generated every gpt_Timeout ticks. Vertical blank units may differ from country to country (e.g 60 Hz NTSC, 50 Hz PAL). To find out the exact frequency use this code fragment:

<pre>
#include <exec/execbase.h>
extern struct ExecBase *SysBase;

UBYTE get_frequency(void)
{
return((UBYTE)SysBase->VBlankFrequency);
}
</pre>

* The gpt_XDelta and gpt_YDelta fields specify the x and y distances which, if exceeded, trigger a report.

For a mouse controller, you can trigger on a certain minimum-sized move in either the x or y direction, on up or down transitions of the mouse buttons, on a timed basis, or any combination of these conditions.

For example, suppose you normally signal mouse events if the mouse moves at least 10 counts in either the x or y directions. If you are moving the cursor to keep up with mouse movements and the user moves the mouse less than 10 counts, after a period of time you will want to update the position of the cursor to exactly match the mouse position. Thus the timed report of current mouse counts would be preferred. The following structure would be used:

<pre>
#define XMOVE 10
#define YMOVE 10

struct GamePortTrigger GameTR =
{
GPTF_UPKEYS | GPTF_DOWNKEYS, /* trigger on all key transitions */
1800, /* and every 36(PAL) or 30(NTSC) seconds */
XMOVE, /* for any 10 in an x or y direction */
YMOVE
};
</pre>

For a joystick controller, you can select timed reports as well as button-up and button-down report trigger conditions. For an absolute joystick specify a value of one (1) for the GameTR_XDelta and GameTR_YDelta fields or you will not get any direction events. You set the trigger conditions by using the following code or its equivalent:

<pre>
struct IOStdReq *GameIO;

void set_trigger_conditions(struct GamePortTrigger *GameTR)
{
GameIO->io_Command = GPD_SETTRIGGER; /* set trigger conditions */
GameIO->io_Data = (APTR)GameTR; /* from GameTR */
GameIO->io_Length = sizeof(struct GamePortTrigger);
DoIO(GameIO);
}
</pre>

{| class="wikitable"
| ''Triggers and Reads.'' If a task sets trigger conditions and does not ask for the position reports the gameport device will queue them up anyway. If the trigger conditions occur again and the gameport device buffer is filled, the additional triggers will be ignored until the buffer is read by a device read request (GPD_READEVENT) or a system CMD_CLEAR command flushes the buffer.
|}

=== Determining the Trigger Conditions ===

You determine the conditions required for triggering gameport events by passing an I/O request to the device with GPD_ASKTRIGGER set in io_Command, the length of the GamePortTrigger structure set in io_Length and the address of the structure set in io_Data. The gameport device will respond with the event trigger conditions currently set.

<pre>struct IOStdReq *GameIO; /* Must be initialized prior to using */

struct GamePortTrigger GameTR;

void get_trigger_conditions(struct GamePortTrigger *GameTR)
{
GameIO->io_Command = GPD_ASKTRIGGER; /* get type of triggers */
GameIO->io_Data = (APTR)GameTR; /* place data here */
GameIO->io_Length= sizeof(GameTR);
DoIO(GameIO);
}</pre>
== Setting and Reading the Controller Type ==

=== Determining the Controller Type ===

You determine the type of controller being used by passing an I/O request to the device with GPD_ASKCTYPE set in io_Command, 1 set in io_Length and the number of the unit set in io_Unit. The gameport device will respond with the type of controller being used.

<pre>struct IOStdReq *GameIO; /* Must be initialized prior to using */

BYTE GetControllerType()
{
BYTE controller_type = 0;

GameIO->io_Command = GPD_ASKCTYPE; /* get type of controller */
GameIO->io_Data = (APTR)&controller_type; /* place data here */
GameIO->io_Length = 1;
DoIO(GameIO);
return (controller_type);
}</pre>
The BYTE value returned corresponds to one of the five controller types noted above.

=== Setting the Controller Type ===

You set the type of gameport controller by passing an I/O request to the device with GPD_SETCTYPE set in io_Command, 1 set in io_Length and the address of the byte variable describing the controller type set in io_Data.

The gameport device is a shared device; many tasks may have it open at any given time. Hence, a high level protocol has been established to prevent multiple tasks from reading the same unit at the same time.

==== Three Step Protocol for Using the Gameport Device ====

Send GPD_ASKCTYPE to the device and check for a GPCT_NOCONTROLLER return. ''Never'' issue GPD_SETCTYPE without checking whether the desired gameport unit is in use.

If GPCT_NOCONTROLLER is returned, you have access to the gameport. Set the allocation flag to GPCT_MOUSE, GPCT_ABSJOYSTICK or GPCT_RELJOYSTICK if you use a system supported controller, or GPCT_ALLOCATED if you use a custom controller.

<pre>
struct IOStdReq *GameIO; /* Must be initialized prior to using */

BOOL set_controller_type(type)
BYTE type;
{

BOOL success = FALSE;
BYTE controller_type = 0;

Forbid(); /*critical section start */
GameIO->io_Command = GPD_ASKCTYPE; /* inquire current status */
GameIO->io_Length = 1;
GameIO->io_Flags = IOF_QUICK;
GameIO->io_Data = (APTR)&controller_type; /* put answer in here */
DoIO(GameIO);

/* No one is using this device unit, let's claim it */
if (controller_type == GPCT_NOCONTROLLER)
{
GameIO->io_Command = GPD_SETCTYPE;/* set controller type */
GameIO->io_Length = 1;
GameIO->io_Data = (APTR)&type; /* set to input param */
DoIO( GameIO);
success = TRUE;
UnitOpened = TRUE;
}
Permit(); /* critical section end */

/* success can be TRUE or FALSE, see above */
return(success);
}
</pre>

The program must set the controller type back to GPCT_NOCONTROLLER upon exiting your program:

<pre>
struct IOStdReq *GameIO; /* Must be initialized prior to using */

void free_gp_unit()
{
BYTE type = GPCT_NOCONTROLLER;
GameIO->io_Command = GPD_SETCTYPE; /* set controller type */
GameIO->io_Length = 1;
GameIO->io_Data = (APTR)&type; /* set to unused */
DoIO( GameIO);
}
</pre>

This three step protocol allows applications to share the gameport device in a system compatible way.

{| class="wikitable"
| ''A Word About The Functions.'' The functions shown above are designed to be included in any application using the gameport device. The first function, set_controller_type(), would be the first thing done after opening the gameport device. The second function, free_gp_unit(), would be the last thing done before closing the device.
|}

== Joystick Example Program ==

<pre>/*
* Absolute_Joystick.c
*
* Gameport device absolute joystick example
*
* Compile with SAS 5.10 lc -b1 -cfistq -v -y -L
*
* Run from CLI only
*/

#include <exec/types.h>
#include <exec/io.h>
#include <exec/memory.h>
#include <intuition/intuition.h>
#include <exec/exec.h>
#include <dos/dos.h>
#include <devices/gameport.h>
#include <devices/inputevent.h>

#include <clib/exec_protos.h>
#include <clib/alib_protos.h>
#include <clib/dos_protos.h>
#include <clib/intuition_protos.h>

#include <stdio.h>

#ifdef LATTICE
int CXBRK(void) { return(0); } /* Disable SAS CTRL/C handling */
int chkabort(void) { return(0); } /* really */
#endif

#define JOY_X_DELTA (1)
#define JOY_Y_DELTA (1)
#define TIMEOUT_SECONDS (10)

extern struct ExecBase *SysBase;

/*-----------------------------------------------------------------------
** Routine to print out some information for the user.
*/
VOID printInstructions(VOID)
{
printf("\n >>> gameport.device Absolute Joystick Demo <<<\n\n");

if (SysBase->VBlankFrequency==60)
printf(" Running on NTSC system (60 Hz).\n");
else if (SysBase->VBlankFrequency==50)
printf(" Running on PAL system (50 Hz).\n");

printf( " Attach joystick to rear connector (A3000) and (A1000).\n"
" Attach joystick to right connector (A2000).\n"
" Attach joystick to left connector (A500).\n"
" Then move joystick and click its button(s).\n\n"
" To exit program press and release fire button 3 consecutive times. \n"
" The program also exits if no activity occurs for 1 minute.\n\n");
}

/*-----------------------------------------------------------------------
** print out information on the event received.
*/
BOOL check_move(struct InputEvent *game_event)
{
WORD xmove, ymove;
BOOL timeout=FALSE;

xmove = game_event->ie_X;
ymove = game_event->ie_Y;

if (xmove == 1)
{
if (ymove == 1) printf("RIGHT DOWN\n");
else if (ymove == 0) printf("RIGHT\n");
else if (ymove ==-1) printf("RIGHT UP\n");
else printf("UNKNOWN Y\n");
}
else if (xmove ==-1)
{
if (ymove == 1) printf("LEFT DOWN\n");
else if (ymove == 0) printf("LEFT\n");
else if (ymove ==-1) printf("LEFT UP\n");
else printf("UNKNOWN Y\n");
}
else if (xmove == 0)
{
if (ymove == 1) printf("DOWN\n");
/* note that 0,0 can be a timeout, or a direction release. */
else if (ymove == 0)
{
if (game_event->ie_TimeStamp.tv_secs >=
(UWORD)(SysBase->VBlankFrequency) * TIMEOUT_SECONDS)
{
printf("TIMEOUT\n");
timeout=TRUE;
}
else printf("RELEASE\n");
}
else if (ymove ==-1) printf("UP\n");
else printf("UNKNOWN Y\n");
}
else
{
printf("UNKNOWN X ");
if (ymove == 1) printf("unknown action\n");
else if (ymove == 0) printf("unknown action\n");
else if (ymove ==-1) printf("unknown action\n");
else printf("UNKNOWN Y\n");
}

return(timeout);

}

/*-----------------------------------------------------------------------
** send a request to the gameport to read an event.
*/
VOID send_read_request( struct InputEvent *game_event,
struct IOStdReq *game_io_msg)
{
game_io_msg->io_Command = GPD_READEVENT;
game_io_msg->io_Flags = 0;
game_io_msg->io_Data = (APTR)game_event;
game_io_msg->io_Length = sizeof(struct InputEvent);
SendIO(game_io_msg); /* Asynchronous - message will return later */
}

/*-----------------------------------------------------------------------
** simple loop to process gameport events.
*/
VOID processEvents( struct IOStdReq *game_io_msg,
struct MsgPort *game_msg_port)
{
BOOL timeout;
SHORT timeouts;
SHORT button_count;
BOOL not_finished;
struct InputEvent game_event; /* where input event will be stored */

/* From now on, just read input events into the event buffer,
** one at a time. READEVENT waits for the preset conditions.
*/
timeouts = 0;
button_count = 0;
not_finished = TRUE;

while ((timeouts < 6) && (not_finished))
{
/* Send the read request */
send_read_request(&game_event,game_io_msg);

/* Wait for joystick action */
Wait(1L << game_msg_port->mp_SigBit);
while (NULL != GetMsg(game_msg_port))
{
timeout=FALSE;
switch(game_event.ie_Code)
{
case IECODE_LBUTTON:
printf(" FIRE BUTTON PRESSED \n");
break;

case (IECODE_LBUTTON | IECODE_UP_PREFIX):
printf(" FIRE BUTTON RELEASED \n");
if (3 == ++button_count)
not_finished = FALSE;
break;

case IECODE_RBUTTON:
printf(" ALT BUTTON PRESSED \n");
button_count = 0;
break;

case (IECODE_RBUTTON | IECODE_UP_PREFIX):
printf(" ALT BUTTON RELEASED \n");
button_count = 0;
break;

case IECODE_NOBUTTON:
/* Check for change in position */
timeout = check_move(&game_event);
button_count = 0;
break;

default:
break;
}

if (timeout)
timeouts++;
else
timeouts=0;
}
}
}

/*-----------------------------------------------------------------------
** allocate the controller if it is available.
** you allocate the controller by setting its type to something
** other than GPCT_NOCONTROLLER. Before you allocate the thing
** you need to check if anyone else is using it (it is free if
** it is set to GPCT_NOCONTROLLER).
*/
BOOL set_controller_type(BYTE type, struct IOStdReq *game_io_msg)
{
BOOL success = FALSE;
BYTE controller_type = 0;

/* begin critical section
** we need to be sure that between the time we check that the controller
** is available and the time we allocate it, no one else steals it.
*/
Forbid();

game_io_msg->io_Command = GPD_ASKCTYPE; /* inquire current status */
game_io_msg->io_Flags = IOF_QUICK;
game_io_msg->io_Data = (APTR)&controller_type; /* put answer in here */
game_io_msg->io_Length = 1;
DoIO(game_io_msg);

/* No one is using this device unit, let's claim it */
if (controller_type == GPCT_NOCONTROLLER)
{
game_io_msg->io_Command = GPD_SETCTYPE;
game_io_msg->io_Flags = IOF_QUICK;
game_io_msg->io_Data = (APTR)&type;
game_io_msg->io_Length = 1;
DoIO( game_io_msg);
success = TRUE;
}

Permit(); /* critical section end */
return(success);
}

/*-----------------------------------------------------------------------
** tell the gameport when to trigger.
*/
VOID set_trigger_conditions(struct GamePortTrigger *gpt,
struct IOStdReq *game_io_msg)
{
/* trigger on all joystick key transitions */
gpt->gpt_Keys = GPTF_UPKEYS | GPTF_DOWNKEYS;
gpt->gpt_XDelta = JOY_X_DELTA;
gpt->gpt_YDelta = JOY_Y_DELTA;
/* timeout trigger every TIMEOUT_SECONDS second(s) */
gpt->gpt_Timeout = (UWORD)(SysBase->VBlankFrequency) * TIMEOUT_SECONDS;

game_io_msg->io_Command = GPD_SETTRIGGER;
game_io_msg->io_Flags = IOF_QUICK;
game_io_msg->io_Data = (APTR)gpt;
game_io_msg->io_Length = (LONG)sizeof(struct GamePortTrigger);
DoIO(game_io_msg);
}

/*-----------------------------------------------------------------------
** clear the buffer. do this before you begin to be sure you
** start in a known state.
*/
VOID flush_buffer(struct IOStdReq *game_io_msg)
{
game_io_msg->io_Command = CMD_CLEAR;
game_io_msg->io_Flags = IOF_QUICK;
game_io_msg->io_Data = NULL;
game_io_msg->io_Length = 0;
DoIO(game_io_msg);
}

/*-----------------------------------------------------------------------
** free the unit by setting its type back to GPCT_NOCONTROLLER.
*/
VOID free_gp_unit(struct IOStdReq *game_io_msg)
{
BYTE type = GPCT_NOCONTROLLER;

game_io_msg->io_Command = GPD_SETCTYPE;
game_io_msg->io_Flags = IOF_QUICK;
game_io_msg->io_Data = (APTR)&type;
game_io_msg->io_Length = 1;
DoIO(game_io_msg);
}

/*-----------------------------------------------------------------------
** allocate everything and go. On failure, free any resources that
** have been allocated. this program fails quietly--no error messages.
*/
VOID main(int argc,char **argv)
{
struct GamePortTrigger joytrigger;
struct IOStdReq *game_io_msg;
struct MsgPort *game_msg_port;

/* Create port for gameport device communications */
if (game_msg_port = CreatePort("RKM_game_port",0))
{
/* Create message block for device IO */
if (game_io_msg = (struct IOStdReq *)
CreateExtIO(game_msg_port,sizeof(*game_io_msg)))
{
game_io_msg->io_Message.mn_Node.ln_Type = NT_UNKNOWN;

/* Open the right/back (unit 1, number 2) gameport.device unit */
if (!OpenDevice("gameport.device",1,game_io_msg,0))
{
/* Set controller type to joystick */
if (set_controller_type(GPCT_ABSJOYSTICK,game_io_msg))
{
/* Specify the trigger conditions */
set_trigger_conditions(&joytrigger,game_io_msg);

printInstructions();

/* Clear device buffer to start from a known state.
** There might still be events left
*/
flush_buffer(game_io_msg);

processEvents(game_io_msg,game_msg_port);

/* Free gameport unit so other applications can use it ! */
free_gp_unit(game_io_msg);
}
CloseDevice(game_io_msg);
}
DeleteExtIO(game_io_msg);
}
DeletePort(game_msg_port);
}
}</pre>
== Additional Information on the Gameport Device ==

Additional programming information on the gameport device can be found in the include files and the Autodocs for the gameport and input devices. Both are contained in the SDK.

{| class="wikitable"
! Includes
|-
| devices/gameport.h
|-
| devices/inputevent.h
|}

{| class="wikitable"
! AutoDocs
|-
| gameport.doc
|}

AmiWest 2013 Lesson 4

2025-01-26T19:31:42Z

Costel Mincea: Text replacement - "<syntaxhighlight>" to "<syntaxhighlight lang="C" line>"

= Simple IP Clients & Servers =

Simple network access is easy!

Developing applications that use TCP/IP "sockets" for network communications
have a reputation of being a challenging task. But AmigaOS and its Roadshow
TCP/IP stack provides a couple of built-in shorthand mechanisms for easily
creating simple network clients and servers: the TCP: handler and Roadshow's
Superserver.

Using these Roadshow shortcuts, creating simple network client and server
applications for single user or light-duty uses is no more complicated than
reading or writing a file. The real challenge is understanding the protocol
to be used (f.e. HTTP communications with web browsers) and being careful not
to create a security risk on your or another user's Amiga.

==An Internet Client==

First, we will look at creating a small client to retrieve some simple
information from an Internet website. Such applications could be made
to retrieve basic information like stock quotes, email contents,
server conditions or other basic interactions.

The Roadshow shortcut we will use is its built-in TCP: handler. This is
mechanism that creates a virtual file system device ("TCP:") whenever
Roadhsow gets online. To interact with a remote server, one3 opens a
file with the name being the URL of the server and port to be accessed.

===Connect to the Server===

When Roadshow gets online, it creates a virtual TCP: device. To open
a connection, one opens a virtual file on the TCP: device to the URL and
port in question using this format:

<syntaxhighlight lang="C" line>
TCP:<server URL>/<port number>
</syntaxhighlight>

For example, to connect to the website "www.wunderground.com" one would
use:

<syntaxhighlight lang="C" line>
fileh = fopen("TCP:www.wunderground.com/80","r+");
</syntaxhighlight>

The file name starts with TCP:, then the website URL and finally the
port number - here "80" is site's HTTP port (used by almost all websites).

Typically, the port number reflects the type of port or protocol that
is to be used. Such protocols could be FTP (file transfer), POP/SMTP
(email) or many others. Port 80 is usually used for HTTP communications
with websites.

If the file open request is successful, your Amiga is then connected to
that server and any further interaction with the "fileh" file handle
communicates directly with that port on that server. In this case,
we would have connected to a web server of the "Weather Underground"
website.

===Talk to the Server===

Once one has connected to a server, knowledge of the communications
protocol for that type of connection is required.

For each of those, a server expects a certain format of interaction to
proceed and respond. Fortunately, common protocols are publicly
documented.

http://en.wikipedia.org/wiki/List_of_TCP_and_UDP_port_numbers

For each protocol there is usually an "RFC" document that describes how one
uses the protocol, interacts with the port and accomplishes that protocol's
goals.

In the case of an "HTTP" (or a "Hypertext Transfer Protocol") connection to
a web server, we are usually expected to submit a "GET" request. Here are
a couple more complete references on the HTTP protocol:

http://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol

http://tools.ietf.org/html/rfc2616

To keep things simple, lets mimic submitting a "GET" request (as if from IBrowse).
A simple HTTP version 1.1 GET request would include the following lines:

<syntaxhighlight lang="C" line>
GET /<path> HTTP/1.1
host: <domain>
user-agent: IBrowse/2.4 (AmigaOS 4.1; PPC; 68K build)
Pragma: no-cache
Accept-Language: en, *
Accept: text/html;level=3
Accept: text/html;version=3.0
Accept: */*
<blank line>
</syntaxhighlight>

The '''<path>''' would be the rest of the URL (if any) on that system and
'''<domain>''' is the name of the server.

Using the "WeatherUnderground" website URL from above and their path name for
searching for airport conditions, we can find the current conditions at
Washington's Dulles International Airport with these domain & path values:

<syntaxhighlight lang="C" line>
URL = www.wunderground.com
PATH = cgi-bin/findweather/getForecast?query=IAD
</syntaxhighlight>

Such a GET request syntax can be transcribed into C code which builds the entire
request in a string and then sends it to the server with a simple "fprintf" to our open
TCP: file handle, as follows:

<syntaxhighlight lang="C" line>
// build web req text
strcpy(line,"GET /");
strcat(line,path);
strcat(line," HTTP/1.1\r\n");
strcat(line,"host: ");
strcat(line,domain);
strcat(line,"\r\n");
strcat(line,"user-agent: IBrowse/2.4 (AmigaOS 4.1; PPC; 68K build)\r\n");
strcat(line,"Pragma: no-cache\r\n");
strcat(line,"Accept-Language: en, *\r\n");
strcat(line,"Accept: text/html;level=3\r\n");
strcat(line,"Accept: text/html;version=3.0\r\n");
strcat(line,"Accept: */*\r\n");
strcat(line,"\r\n");

// send web req line to server
fprintf(fileh,"%s",line);
</syntaxhighlight>

As you can see, the variables "path" and "domain" are used to fill in some
blanks in the request. The empty line at the end (with just a "\r\n") completes the
GET request, after which the server will reply to your program.

===Listen to the Server===

Once the GET request has been sent to the web server, the server will start
sending back either the requested webpage (or other content) or an error page.
To see what sort of content is returned by the server in this example, you can
combine the domain and path values above and enter them in your web
browser's URL string gadget, like this:

<syntaxhighlight lang="C" line>
www.wunderground.com/cgi-bin/findweather/getForecast?query=IAD
</syntaxhighlight>

Once the page is loaded in your browser, viewing the page source (f.e., IBrowse
menu item "Page/Display Source...") will show you the same HTML text that your
program will receive after sending the GET request.

As such, your program needs to start reading from the file handle
the request was sent with. This loop will print out the first hundred
lines returned:

<syntaxhighlight lang="C" line>
// read in the response
count = 0;
while( (fgets(inStr,MAX_STR,fileh) != NULL) && (count<100) )
{
++ count;
printf("line %ld = %s\n",count,inStr);

// process lines received here !
}
</syntaxhighlight>

Within this loop your application can parse the received lines for whatever
data your application is trying to obtain. In the case of our example program below,
the program searches for a string precedes the weather information we want to find.

After the returned content has been read, output or otherwise processed,
simply closing the file handle will close the connection to the server:

<syntaxhighlight lang="C" line>
fclose(fileh);
</syntaxhighlight>

===EXAMPLE ONE: IPClient.c===

All of the above elements are combined in the following example program
"IPClient.c" that asks you for an IATA airport code (f.e., IAD = Washington
Dulles, FRA=Frankfurt, SYD=Sydney), then parses & prints out the weather
conditions from the returned WeatherUnderground.com web page.

Please Note: this example program worked with the wunderground.com
website in 2013-2014, as the served webpages change over time, it is
likely the parsing in this example is likely to fail and the program
no longer return useful information. Should this happen, you get to use what
you learned above to upgrade or replace this example.

<syntaxhighlight lang="C" line>
/*
************************************************************
**
** Created by: CodeBench 0.41 (12.10.2013)
** Project: IPclient
** Date: 12-10-2013 18:51:10
**
************************************************************
*/

#include <stdio.h>
#include <string.h>

#include <proto/exec.h>
#include <proto/dos.h>

/*****************************************************************************
* GLOBAL VARIABLES
*****************************************************************************/

STATIC CONST_STRPTR version USED = "$VER: IPclient v.02 (12.10.2013)";

char URL[200] = "www.wunderground.com/cgi-bin/findweather/getForecast?query=";
char domain[200];
char path[200];
char fname[256] = "";
#define MAX_STR 2056
char line[MAX_STR] = "";
char inStr[MAX_STR];
uint16 uLen;
uint16 dLen;
uint16 count = 0;
char *found;
FILE *fileh;

/*****************************************************************************
* PROGRAM START
*****************************************************************************/

int main(int argc,char **argv)
{
// get URL from user
printf("IPclient example\n");
printf("======================\n");

printf(" enter airport code >");
fgets(line,sizeof(line),stdin);
line[strlen(line)-1] = '\0'; // strip \n off end of string
printf("======================\n");

// append airport code on URLprefix
strcat(URL,line);

// parse domain from path
uLen = strlen(URL) - 2;
strcpy(domain,strtok(URL,"/\n"));
dLen = strlen(domain);
if (uLen>dLen)
strcpy(path,strtok(NULL,"\n"));
else
printf(" No chars remain for path\n");
printf(" URL domain >%s<\n",domain);
printf(" URL path >%s<\n",path);

// build URL filename from domain name
strcpy(fname,"TCP:");
strcat(fname,domain);
strcat(fname,"/80");

// open file access to URL
printf(" Opening URL >%s<\n",fname);
fileh = fopen(fname,"r+");
if (fileh == NULL)
{
printf("Couldn't open connection domain server via \"%s\"\n",fname);
return RETURN_ERROR;
};
printf(" TCP: file opened\n");

// build web req text
strcpy(line,"GET /");
strcat(line,path);
strcat(line," HTTP/1.1\r\n");
strcat(line,"host: ");
strcat(line,domain);
strcat(line,"\r\n");
strcat(line,"user-agent: IBrowse/2.4 (AmigaOS 4.1; PPC; 68K build)\r\n");
strcat(line,"Pragma: no-cache\r\n");
strcat(line,"Accept-Language: en, *\r\n");
strcat(line,"Accept: text/html;level=3\r\n");
strcat(line,"Accept: text/html;version=3.0\r\n");
strcat(line,"Accept: */*\r\n");
strcat(line,"\r\n");

// send web req line to server
fprintf(fileh,"%s",line);
strcpy(line,"");
printf(" Web req sent\n");
printf("======================\n");

// read in the response
while( (fgets(inStr,MAX_STR,fileh) != NULL) && (count<100) )
{
++ count;
//printf("line %d = %s\n",count,inStr);

// look for name of airport
found = strstr(inStr,"og:title");
if (found != NULL)
{
found = strtok(inStr,"=");
found = strtok(NULL,"=");
printf("WeatherUnderground.com reports:\n");
printf(" Airport = %s\n",strtok(NULL,"|")+1);
printf(" Temp =%s F\n",strtok(NULL,"&"));
found = strtok(NULL,"|");
printf(" Condition =%s\n",strtok(NULL,"\""));
}
}
printf("======================\n");

// close file
fclose(fileh);

return RETURN_OK;
}
</syntaxhighlight>

===Designing Your Network Client===

As you see, the above code and the example program, the mechanics
of connecting to a internet server and obtaining data are relatively
trivial. The real challenge for the developer lies in understanding
the protocol used, in formatting the request and processing
received data.

Public web servers make for fairly rich and easy targets to interact
with. You can explore simple interaction with any web browser and mimic
that interaction with your code. In many cases, you can control the
feedback just by crafting the web request as we did above and then
parse the results.

Naturally, the more complicated the interactions, like logging into
a website, would require much more knowledge of the protocols used
and more complicated code that is beyond the scope of this tutorial.

But there are a number of basic topics you should consider when
designing a web client!

====Server Suitability:====

Unless you are connecting to your own server or one which invites such
connections (some even publish API's and example code for you to use),
your application's "visit" may not be welcome or even legal.

At the very least, your program should "tread lightly" - do not abuse
the server with unnecessary or intrusive requests. Furthermore, if
your client uses the resources of someone else's server, you should
credit the server within your application and documentation.

====Server Changes:====

As with any programming that interacts with external elements, your
code should provide for the possibility things may not
succeed or the returned results may not be what was expected.

As servers and websites change over time, the processing and
parsing of your program may often have to change accordingly.
To maintain your program and deal with such changes, you may want
to consider how to make modifying those things easy as possible (even
by the user?).

For example, the parsing strings could be kept in the program's tooltype
or a config text file, you could provide a GUI for managing the strings, or
employ an external, editable ARexx macro for processing.

====Protocol Details & Vagaries:====

Our example code presented a very simple interaction with a web
server using the a widely supported version of the HTTP protocol.
As one develops an application and uses a protocol, one should get
familiar with the details of that protocol. Typically a "RFC"
document (as linked above) will describe the details of how things
are to work and how they might fail. Your application should be
careful to comply with the details of the protocol ("Are we sending
a CR-LF or LF-CR?!").

===Ideas===

The above example was just a quick, simple exercise in demonstrating
the use of the AmigaOS Roadshow TCP: handler to access a web server.
There are many ways applications could be created to have simple
interactions with all sorts internet services, such as:

* Check stock quotes from a financial site.
* Get package tracking information from a shipping site.
* Check for new emails on a POP email server.
* Convert currencies with a financial or travel web site.
* Check for files on an FTP server.
* Send messages with a SMTP email server.
* Look up words on a dictionary website.

You could also write your own server for another Amiga and interact
with your own client. A remote controlled media player? The AmiNet
also has many examples of simple clients (with C source code or in
readable ARexx) that can be studied for means and methods.

==An Internet Server==

Next we will look at creating a simple internet server program that relies on AmigaOS Roadshow's "SuperServer" to receive the incoming
internet connection and share it with our application.

Simply speaking, once Roadshow is configured to recognize the incoming
request and that your application is there to handle it; our program
just has to deal with another case of simple file-like interaction.

For this example, we will create a simple server that accepts an HTTP
protocol request (like from IBrowse) and then responds to it with a
simple webpage. Of course, you could write a server to serve an
interactive webpage, some machine information, media files, etc.
Just be careful.

===Receive the Request===

When Roadshow receives an internet request on the designated port that
corresponds to our server, it starts our server program and routes the
network connection to our program using the "standard" input stream
(otherwise known as "stdin").

Our application then reads the stream almost like reading from any
other file or user input, like this:

<syntaxhighlight lang="C" line>
// read in the response
while( (fgets(inStr,MAX_STR,(FILE *)stdin) != NULL) && (count<100) )
{
if (strlen(inStr)<3)
{
IExec->DebugPrintF(" received nearly empty line, ending read loop.\n",NULL,NULL);
break;
}
++ count;
IExec->DebugPrintF(" %s\n",inStr,NULL,NULL,NULL);
}
</syntaxhighlight>

As you can see, we loop reading incoming lines until we encounter a
line with two or fewer characters (essentially an empty line with
what should be a CR-LF). There is also a counter that kicks us out
of the loop if we read 100 lines - that's a sign something else is
wrong, we should never see so long a request with the HTTP protocol.

With the HTTP protocol, the first line is where we would see what is
being requested. Were our server to use another protocol, the processing of
the received data would likely happe3n elsewhere.

As you see, we do all our diagnostics output using the "DebugPrintf". Which
means we either need to run Sashimi or watch output on the serial port
(with your second Amiga, naturally). With the above code, the diagnostics
output will show the entire incoming request on the serial port. Of course,
there's a reason why we have to use "DebugPrintf" for diagnostics output...

===Respond to the Visitor===

Once we've read the (almost) empty line at the end of the incoming
web request, we will use another "standard" stream (know as "stdout") to respond to our
internet visitor.

Anything we output to "stdout" will be sent by Roadshow back to our
internet visitor. This is the reason why we used the serial port for
diagnostic print outs, since a simple "printf" would have gone to
our web visitor.

In this example, we create a basic loop that feeds a predefined series of strings (in the '''lines''' array)
of a very simple webpage through Roadshow, to our web visitor:

<syntaxhighlight lang="C" line>
//loop thru text writing to stdout
do
{
if (strlen(lines[l]) > 0)
{
IExec->DebugPrintF(" printing line = %s\n",lines[l],NULL,NULL);
if (fprintf(stdout,"%s\n",lines[l]) < 0)
{
IExec->DebugPrintF("ERROR printing line\n",NULL,NULL);
break;
}
fflush(stdout);
}
else
{
IExec->DebugPrintF(" empty line, loop end\n",NULL,NULL);
break;
}
++l;
} while (l < 25); // emergency loop escape to stop endlessness
</syntaxhighlight>

As you can see, our loop ends when we hit an empty line in our webpage
definition or a maximum of 25 lines (a fail-safe). Then we "flush" the output
stream and quit our program.

While our two samples of code simply receive and respond to an incoming web request,
one can imagine where this code can be expanded provide useful service and more
complex interactions.

===EXAMPLE TWO: IPserver.c===

We can see all these pieces and the definition of our simple webpage in
the full program here:

<syntaxhighlight lang="C" line>
/*
************************************************************
**
** Created by: CodeBench 0.41 (12.10.2013)
** Project: IPserver
** Date: 13-10-2013 23:41:17
**
************************************************************
*/

#include <string.h>
#include <stdio.h>
#include <proto/exec.h>
#include <proto/dos.h>

/*****************************************************************************
* GLOBAL VARIABLES
*****************************************************************************/

STATIC CONST_STRPTR version USED = "$VER: IPserver 0.14 (13.10.2013)";

// define maximum web request lines & length
#define MAX_STR 2048

// ARS path & file name
uint16 count = 0;
char inStr[MAX_STR];

CONST_STRPTR lines[] =
{
"HTTP/1.0\015",
"Content-Type: text/html\015",
"\015",
"<HTML><HEAD><TITLE>IPserver</TITLE></HEAD><BODY BGCOLOR=\"cccccc\">\015",
"<TABLE WIDTH=100%><TD ALIGN=\"center\" BGCOLOR=\"cccccc\">\015",
" <TABLE WIDTH=90%><TR><TD><H1>WELCOME</H1> </TD></TR></TABLE>\015",
"<TR><TD BGCOLOR=\"6688ee\"><H3>AmigaOS IPserver example</TD></TR>\015",
"<TR><TD ALIGN=\"center\" BGCOLOR=\"cccccc\">\015",
" <TABLE CELLSPACING=0 WIDTH=90%><TR BGCOLOR=\"ffffff\"><TD WIDTH=100><H4>And so it begins...</TD><TD> Your Amiga internet server! </TD></TR></TABLE>\015",
"</TR></TD></TABLE></BODY></HTML>\015",
""
};
uint16 l = 0;

/*****************************************************************************
* PROGRAM START
*****************************************************************************/

// Starting program
int main(int argc,char **argv)
{

IExec->DebugPrintF("======================================\n");
IExec->DebugPrintF("IPserver starting\n");
IExec->DebugPrintF("======================================\n");

// Was program started from shell or WB ?
if (argc > 0)
{

// read in the response
while( (fgets(inStr,MAX_STR,(FILE *)stdin) != NULL) && (count<100) )
{
// #### Test for CR-LR only line
if (strlen(inStr)<3)
{
IExec->DebugPrintF(" received nearly empty line, ending read loop.\n",NULL,NULL);
break;
}

++ count;
IExec->DebugPrintF(" %s\n",inStr,NULL,NULL,NULL);
}

IExec->DebugPrintF("======================================\n");
IExec->DebugPrintF("FINISHED READING WEB REQUEST\n");
IExec->DebugPrintF("SERVING WEB PAGE...\n");
IExec->DebugPrintF("======================================\n");

//loop thru text writing to stdout
do
{
if (strlen(lines[l]) > 0)
{
IExec->DebugPrintF(" printing line = %s\n",lines[l],NULL,NULL);

if (fprintf(stdout,"%s\n",lines[l]) < 0)
{
IExec->DebugPrintF("ERROR printing line\n",NULL,NULL);
break;
}

fflush(stdout);
}
else
{
IExec->DebugPrintF(" empty line, loop end\n",NULL,NULL);
break;
}
++l;
} while (l < 25); // emergency loop escape to stop endlessness

IExec->DebugPrintF("======================================\n");
IExec->DebugPrintF("Web service finished... \n");
}
else
printf("IPserver started from Workbench - Don't do it again, this is a Roadshow app!\n");

IExec->DebugPrintF("IPserver Quitting!\n");
IExec->DebugPrintF("======================================\n");

return RETURN_OK;
}
</syntaxhighlight>

As you can see there's also a bit of housekeeping code at the beginning
to check if the program was run from the Workbench and to tell the user not to.
As it stands, this is program is only meant to be used by Roadshow for
serving your Amiga's internet visitors.

But how do we test this server out? First we have to let Roadshow know that
we've created this server and where visitors will find it.

===Roadshow Configuration===

There are two areas where Roadshow needs to be told about your server
and the service it is going to provide, as described below. Both of these can
be configured using Internet Prefs. You can also make this configuration by
manually editing the "servers" and "services" files in the "DEVS:internet/" directory.
Configuration of these files is described in the file:

<syntaxhighlight lang="C" line>
SYS:Documentation/Roadshow/README
</syntaxhighlight>

If you would like to spare your user from having to do either of those
chores, your application can even modify those files. As soon as
Roadshow sees those files have been modified, it will reconfigure itself
accordingly.

====Services====

First, we need to tell Roadshow about the "service" we are providing.
If one opens Internet Prefs and clicks on the "Services" page, one will
see a list of standard internet services with their TCPIP port numbers,
types and aliases.

Click the "New..." button to define a new Service. An "Add service"
window will open where we can define how our server will be accessed.
Critically, we need to pick a port number that is not already in use.
Such settings could be:

<syntaxhighlight lang="C" line>
Name = IPserver
Port = 7600
Type = tcp
</syntaxhighlight>

Then we click "Use" to accept our new values. As soon as one clicks
"Save" in Internet Prefs, this service will be recognized by Roadshow.

The same configuration could manually be added to Roadshow by adding this line
(in port number location) into the file "DEVS:Internet/Services":

<syntaxhighlight lang="C" line>
IPServer 7600/tcp
</syntaxhighlight>

As soon as one saves the file, Roadshow will be notified and adjust
itself for the service.

====Servers====

Before we can use the service above, we also need to tell Roadshow
about our server app and where to find it. Again, this can be done
while in Internet Prefs. Click on the "Servers" page and one will see
any servers configured with the services they provide (as set above),
their type, wait method and program path.

Click on the "New..." button to define a new Server. In the "Add server"
window we can define what sort of service our server is for, the
characteristics of how it will be called and where it is located on
our Amiga system. Such settings could be:

<syntaxhighlight lang="C" line>
Service = IPserver
Type = Stream
Stack = 65536
Program = data:Projects/C/OS4ex-IPserver/IPserver.debug
Arguments = <empty>
Active = <checked>
Wait for completion = <not checked>
Use socket I/O streams = <checked>
</syntaxhighlight>

Naturally, you should enter the server program path & name for your own system.
Again we click "Use" to accept our new Server entry and saving Internet
Prefs will adjust Roadshow.

We can otherwise make this adjustment to Roadshow's server list by manually adding the
following line to the "DEVS:Internet/servers" file:

<syntaxhighlight lang="C" line>
IPServer stream dos stack=65536 data:Projects/C/OS4ex-IPserver/IPserver.debug
</syntaxhighlight>

Again, saving the file is automatically noticed by Roadhsow.

Once both the service and server are correctly configured, Roadshow is ready
to use our new server.

===Let's See Our Server!===

To test our new server example, you can access it by connecting to your
Amiga and the designated IP port number. On the same machine, you can
enter this in your browser URL line:

<syntaxhighlight lang="C" line>
http://localhost:7600/
</syntaxhighlight>

From another machine, you will need to have the IP address or defined host
name for your Amiga running the test server program. The URL should
look something like this:

<syntaxhighlight lang="C" line>
http://192.168.1.07:7600/
</syntaxhighlight>

In any case, the browser will connect to your Amiga (at the port number
following the colon - ":") and Roadshow will call up your server program
and let it talk to your browser and send it the preset webpage.

===Where to go? Webpages? More?===

Clearly the above example does little more than say "Hello World" to a
visiting web browser user. It offers no interactivity, performs no task
and serves no media.

When this web server receives the incoming web request, the first line
(starting with "GET") tells the server what the browser is looking for.
For example, if you watch the serial output and connect with a newer browser than
IBrowse, you can see most browsers actually make two connections to the
server, with one of them saying:

<syntaxhighlight lang="C" line>
GET /favicon.ico HTTP/1.1
</syntaxhighlight>

In that case, the browser is requesting your server send an image file
that it can display on the browser tab. Just like that, anything in the URL
after the machine's network name (or IP address) and the port number
is taken as a requested path and your server will receive it after "GET" in
the first line of the request.

This just scratches the surface of requests your server may receive and
how it can process them and respond to web visitors. To dig deeper you can
search the many sources online or in your local bookstore on HTTP communications
and the formatting of HTML webpages. Of course, you should make sure your
server can optionally send diagnostics output so you know what requests are
being received and how they are responded to.

===Just Webpages?===

There's also no reason why your server needs to be limited to dealing
with browsers and sending webpages. The internet is full of other
protocols and services that you could write a server for. Or you could
create your own online client and server pair of applications that
talked with each other.

Just as we discussed with creating an Internet client, there are many
topics you should consider when designing an internet server program.
It's not just about the coding!

====Security====

Obviously, opening your Amiga with an internet server represents more of a
risk than if you had done nothing. So it is critically important one
considers security when creating a server. While it's beyond the scope
of this article to inclusively discuss all the issues involved, here are some
basics to consider.

Don't blindly serve sensitive information to visitors. How can you be
sure who's at the other end of the connection and who might be watching
along the way? Even if randomized path names and requests are used by
your server, there's no guarantee the connection is 100% secure.

Limit commands and functions served to visitors. Obviously, creating a
means of offering anything like command line access or unfettered file
editing/deleting powers to a web visitor would represent dangerous hole
in any system's security. But one also has to make sure no whatsoever holes
or bugs exist in the server design that would let such access slip
through.

====Server Instances & Load====

One has to keep in mind the "SuperServer" method where Roadshow runs
your server also means your server program will be executed with each and every
request Roadshow receives for that port. In each case, your server
will do its duty and then be expected to quit. That should be fine for
light duty, personal server tasks.

But one should focus server development on keeping things as
"lightweight" and simple as possible. If the server needs to
read data files or perform other complicated initialization, this may
slow reaction time for each incoming request to an unacceptable level.

To avoid time consuming chores, one might considering using inter-process
communications (such as ARexx messages) to interact with a separate
master program that handles all the housekeeping and remains continuously running
while each instance of the internet server handles each incoming request, quickly
relays the necessary information from the master program and quits.

Naturally, at some point usage requirements may require one bypasses the
Roadshow SuperServer method of running servers and goes to using
longhand socket programming that is better suited to heavy duty use
- like running a serious public server. That's beyond the scope of this tutorial.

Furthermore, there are whole areas of study and technology involved with the
handling of network user load that should be explored in implementing a serious
server system.

====Protocols and Compatibility====

As one develops a more a complex or interactive server meant to handle
a wider group of users (even those on lesser platforms!), one needs
to pay much closer attention to the protocols involved. With each new client
and platform encountered, the more important implementation details of a
protocol are likely to be.

As mentioned in elsewhere in this text, there are RFC's that describe the
formal protocols and there are likely countless webpages that address
idiosyncrasies of implementing the protocols.

Beyond all those, a developer will need to do serious testing with as
wide a pool of possible clients to refine a server's operation. "You
aren't in Kansas anymore!"

==General Issues==

Whether creating a server or a client program, there are many general
issues that one should consider in developing such programs.

====Complexity and Speed====

These days it seems like few developers on lesser platforms care terribly
much about optimization and speed. Those platforms typically just throw
more horsepower & memory at their chores and try to go about their business.

In the Amiga world, without the glut of idle horsepower, development of
any applications and internet clients & servers in particular should be
mindful of overhead. For every client or server transaction, there is
likely some user that clicked a button and is waiting for an answer.
Keep things simple and optimize!

====Incomplete transactions====

Since all these programs are dependent on communications over many links,
these programs need to have a robustness for failed links. Transfers can
be interrupted mid-stream. Received data can be incomplete or corrupted.
These applications need to have the error trapping to deal with such real
possibilities - that isn't reflected in the simple examples above.

====Statelessness====

Given the nature of internet communications and web browsing in particular,
servers and clients need to be "stateless" as possible. While a visitor
may have just "logged in" to your server, it's not guaranteed
the next transaction your server receives is that logged-in user, that
the user hasn't left or hit the back or reload button on their browser
(reloading the log-in page again). So a server should avoid making
assumptions about the state of the connection and status of a
visitor whenever possible or provide explicit means for addressing such
things, if possible.

Programming AmigaOS 4: GUI Toolkit ReAction

2025-01-26T19:31:21Z

Costel Mincea: Text replacement - "<syntaxhighlight>" to "<syntaxhighlight lang="C" line>"

''This article was adapted from Amiga Future magazine's series on developing for AmigaOS....''

We mainly worked with shell programs or simple windows in the previous parts of this workshop. However, today's topic will be how to create a completely interactive GUI.

For this purpose we will use ReAction, which provides great flexibility for defined windows and controls that lay themselves out automatically. But before we dive into this subject, let us take a look at the past and see how interface development on the Amiga has changed over the years.

= History =

With Kickstart 1.x you had to create gadgets (the controls, which were back then - a button, a panel and a slide bar) directly as a structure and connect them with each other as well as calculate their positions. This procedure was very time consuming and a different font or another window size could sometimes cause significant trouble. Therefore, the gadtools.library, which was supplied with Kickstart 2.x, greatly simplified the creation of gadgets and menus. Additionally, a great number of new gadget types (e.g. ListView, Checkbox, Cycle) was launched. However, there was still a problem with the fixed positions. In this step the BOOPSI (Basic Object Oriented Programming System for Intuition) was also created. It offered an object-orientated approach, that could readily be used with Workbench 3.5 in the form of ReAction gadgets. This made it possible for windows to lay themselves out correctly automatically. That means that the gadgets automatically re-position themselves and their size is adjusted, if needed, when the window size is changed. The calculation of the minimized window size when opening a window is handled automatically by the system.

= The end of Gadtools =

By introducing ReAction all gadget types from the gadtools.library became superfluous. The same procedure is still used with AmigaOS 4, but this time it is used to create menus. All the functions required to create and layout menus are now available in the window class and no longer need to be made automatically. In other words, gadtools.library no longer has this role to perform!

A side note: the MUI (Magic User Interface) is used as a second GUI library and it is provided with the Operating System since AmigaOS 4. However, it remains an external toolkit. Its standard appearance has been made in the style of AmigaOS 4 so it would not look like an 'alien element'. In principle, it applies the same approach as for ReAction, but it is programmed differently.

= ReAction step by step =

After that brief introduction it is now time for our first example, a window with a gadget and a menu. What used to take a long time, is now done in just a few steps. These necessary steps will be explained here in detail, because you can create big applications with them as well.

All ReAction objects (gadgets, window and Requester) are set up with IIntuition->NewObject(). The result is a generic 'Object' pointer. However, most of the old functions still expect a pointer on a gadget structure (or a window structure), so that you must decide whether you want to cast the return value immediately, or once you activate the respective functions. There is no standard notation in SDK at the moment. Right now, casting the result pointer is the best option. This way you can immediately see what it is about, in case you have selected an unfavourable name for the variable. You can create a button as follows:

<syntaxhighlight lang="C" line>
struct Gadget *gb_ButtonGad;
#define GAD_ID_Quit 2

if((gb_ButtonGad = (struct Gadget *) IIntuition->NewObject(IButton->BUTTON_GetClass(),NULL,
GA_ID, GAD_ID_Quit,
GA_RelVerify, TRUE,
GA_Text, "_end",
TAG_DONE)))
</syntaxhighlight>

There is an example for various gadget classes at the end of this article. The GA_xxx tags are general and applicable to all kinds of gadgets. A specific gadget for a button would be, for instance, BUTTON_BevelStyle, which you can find under "gadgets/...". With the underscore in the button text the shortcut is defined, which can start the button without a mouse.

You can also use the same procedure to create a window, but this time you must use the WINDOW_xxx Defines from "classes/window.h". In addition, you can also use a great number of old WA tags.

<syntaxhighlight lang="C" line>
Object *gb_WindowObj;
if((gb_WindowObj = (Object *) IIntuition->NewObject(IWindow->WINDOW_GetClass(),NULL,
WA_IDCMP, IDCMP_GADGETUP | IDCMP_CLOSEWINDOW | IDCMP_MENUPICK,
WA_SizeGadget, TRUE,
WA_DepthGadget, TRUE,
WA_DragBar, TRUE,
WA_CloseGadget, TRUE,
WA_Activate, TRUE,
WA_Title, "Example with reaction gadgets and window class",
WINDOW_Position, WPOS_CENTERSCREEN,
</syntaxhighlight>

A ReAction window requires implicitly a layout object, which automatically handles the size adjustment and distribution of the individual gadgets. In our example with only one gadget we need a central layout method. The layout object serves the horizontal and vertical arrangement of several gadgets within the window. This way, you can also realise very complex layouts by dividing them into horizontal and vertical groups.

<syntaxhighlight lang="C" line>
struct Gadget *gb_MainLayout;
WINDOW_ParentGroup, gb_MainLayout = (struct Gadget *)
IIntuition->NewObject(ILayout->LAYOUT_GetClass(),NULL,
LAYOUT_Orientation, LAYOUT_ORIENT_VERT,
LAYOUT_SpaceOuter, TRUE,
LAYOUT_SpaceInner, TRUE,
LAYOUT_AddChild, gb_ButtonGad,
TAG_DONE),
TAG_DONE)))
</syntaxhighlight>

As already mentioned, creating menus has become a very simple task in the meantime. All you need to do is create the NewMenu structure (from "libraries/gadtools.h") dating from gadtools times, which describes the individual menu points. This structure is given then when you create the window object. You no longer need to take care of deleting the menu structure; this happens automatically when the window object is released.

<syntaxhighlight lang="C" line>
struct NewMenu gb_MenuDescribe[] =
{
{ NM_TITLE, "Project", NULL, 0, 0, NULL },
{ NM_ITEM, "Quit", NULL, 0, 0, NULL },
{ NM_END, NULL, NULL, 0, 0, NULL }
};

#define MENU_ID_Quit FULLMENUNUM(0,0,NOSUB)

IIntuition->NewObject(IWindow->WINDOW_GetClass(),
WINDOW_NewMenu, gb_MenuDescribe,
</syntaxhighlight>

Since AmigaOS 4's release the ReAction gadgets have been included in the BubbleHelp. If you move the mouse cursor over such an element, a bubble with help text will be displayed soon afterwards. You need to do just a little bit of programming for this. Mainly, you must fill out the HintInfo structure from "classes/window.h":

<syntaxhighlight lang="C" line>
struct HintInfo gb_HintInfo[] =
{
{ GAD_ID_Help, -1, "activate/deactivate the BubbleHelp hints", 0 },
{ GAD_ID_Quit, -1, "quit program", 0 },
{ -1, -1, NULL, 0 }
};
</syntaxhighlight>

The fourth value is reserved for the future flags and a 0 is assigned to it at the moment. The structure must be indicated when you create the window object.

<syntaxhighlight lang="C" line>
IIntuition->NewObject(IWindow->WINDOW_GetClass(),
WINDOW_HintInfo, gb_HintInfo,
WINDOW_GadgetHelp, TRUE,
</syntaxhighlight>

With the WINDOW_GadgetHelp you can turn on/off the help. With 'WINDOW_GadgetHelp, FALSE' you can deactivate it, so it will not be displayed again. With TRUE you can re-activate it. You can change this tag during runtime. Other settings such as influencing the waiting time until the display, the display duration, the colour, etc. are still not possible, but users should be able to change them by using a global Prefs adjuster in the future.

<syntaxhighlight lang="C" line>
IIntuition->SetAttrs(gb_WindowObj, WINDOW_GadgetHelp, FALSE, TAG_DONE);
</syntaxhighlight>

We will add a checkbox to the sample program in order to put this possibility to use. We can turn on and off the help any time with it. In reality, you will set this option on a menu point or in the program settings, if there are any. A tooltype in the icon information is also an alternative.

<syntaxhighlight lang="C" line>
struct Gadget *gb_CheckboxGad;
#define GAD_ID_Help 1

if((gb_CheckboxGad = (struct Gadget *) IIntuition->NewObject(ICheckBox->CHECKBOX_GetClass(),NULL,
GA_ID, GAD_ID_Help,
GA_RelVerify, TRUE,
GA_Text, "Bubble_Help active",
TAG_DONE)))

WINDOW_ParentGroup,
LAYOUT_AddChild, gb_CheckboxGad,
</syntaxhighlight>

All GUI elements are now created, but they are still not visible. You should certainly check, whether the window pointer is present. If not, a gadget could probably not be created. To display the window you can use the RA_OpenWindow() macros from "reaction/reaction_macros.h", to close it RA_CloseWindow() and to edit news RA_HandleInput().

Since these are macros, you cannot use the typical interface notation. The news editing loop looks in practice as follows:

<syntaxhighlight lang="C" line>
if((gb_Win = RA_OpenWindow(gb_WindowObj)))
{
ULONG winsig;
IIntuition->GetAttr(WINDOW_SigMask,gb_WindowObj,&winsig);

BOOL run = TRUE;
while(run)
{
ULONG result, code, val;

const ULONG sigs = IExec->Wait(winsig | SIGBREAKF_CTRL_C);

while((result = RA_HandleInput(gb_WindowObj,&code)) != WMHI_LASTMSG)
{
switch(result & WMHI_CLASSMASK)
{
case WMHI_GADGETUP:
switch(result & WMHI_GADGETMASK)
{
case GAD_ID_Help:
IIntuition->GetAttr(CHECKBOX_Checked,gb_CheckboxGad,(ULONG*)&val);
IIntuition->SetAttrs(gb_WindowObj,
WINDOW_GadgetHelp, val,
TAG_DONE);
break;

case GAD_ID_Quit:
run = FALSE;
break;
}
break;

case WMHI_CLOSEWINDOW:
run = FALSE;
break;

case WMHI_MENUPICK:
switch(result & WMHI_MENUMASK)
{
case MENU_ID_Quit:
run = FALSE;
break;
}
break;
}
}

if(sigs & SIGBREAKF_CTRL_C) run = FALSE;
}

RA_CloseWindow(gb_WindowObj);
}
</syntaxhighlight>

You can see the various news types like press gadget (WMHI_GADGETUP), select menu (WMHI_MENUPICK) and the closing symbol for the window (WMHI_CLOSEWINDOW). But you can only get news, which has been defined explicitly as IDCMP_xxx Bits when creating the window.

To close the program, that is, to release all created objects all you need to do is activate IIntuition->DisposeObject(). It automatically makes sure that all elements included in the object are also released. If you specify the window pointer here, all included gadgets, menus and helptexts will be also deleted and can no longer be used!

<syntaxhighlight lang="C" line>
IIntuition->DisposeObject(gb_WindowObj);
</syntaxhighlight>

What is missing now are only the Includes and a main function. Then the program is complete and can be found as an example below.

== ReAction Example ==

<syntaxhighlight lang="C" line>
/* Michael Christoph
* ReActionEx.c
*
* gcc ReActionEx.c -o ReActionEx -l auto
*/

/******************************* INCLUDES *************************************/

#include <intuition/gadgetclass.h>
#include <classes/window.h>
#include <reaction/reaction_macros.h>
#include <libraries/gadtools.h>
#include <gadgets/checkbox.h>

#include <proto/exec.h>
#include <proto/dos.h>
#include <proto/intuition.h>
#include <proto/window.h>
#include <proto/layout.h>
#include <proto/button.h>
#include <proto/checkbox.h>

#define MENU_ID_Quit FULLMENUNUM(0,0,NOSUB)

#define GAD_ID_Help 1
#define GAD_ID_Quit 2

/******************************************************************************/

static const char *version USED = "\0$VER: ReActionEx 1.00 (16.12.2004) - (c) Dec.2004 by Meicky-Soft\n";

/******************************************************************************/

Object *gb_WindowObj;
struct Window *gb_Win;
struct Gadget *gb_MainLayout;
struct Gadget *gb_ButtonGad;
struct Gadget *gb_CheckboxGad;

struct NewMenu gb_MenuDescribe[] =
{
{ NM_TITLE, "Project", NULL, 0, 0, NULL },
{ NM_ITEM, "Quit", NULL, 0, 0, NULL },

{ NM_END, NULL, NULL, 0, 0, NULL }
};

struct HintInfo gb_HintInfo[] =
{
{ GAD_ID_Help, -1, "Activate/Deactive BubbleHelp Tips", 0 },
{ GAD_ID_Quit, -1, "Quit Program", 0 },
{ -1, -1, NULL, 0 }
};

/******************************************************************************/

int main()
{
/* create a Checkbox Gadget */
if((gb_CheckboxGad = (struct Gadget *) IIntuition->NewObject(ICheckBox->CHECKBOX_GetClass(),NULL,
GA_ID, GAD_ID_Help,
GA_RelVerify, TRUE,
GA_Text, "Bubble_Help Active",
TAG_DONE)))
{
/* create the Button */
if((gb_ButtonGad = (struct Gadget *) IIntuition->NewObject(IButton->BUTTON_GetClass(),NULL,
GA_ID, GAD_ID_Quit,
GA_RelVerify, TRUE,
GA_Text, "_Quit",
TAG_DONE)))
{
/* create the Window Object */
if((gb_WindowObj = (Object *) IIntuition->NewObject(IWindow->WINDOW_GetClass(),NULL,
WA_IDCMP, IDCMP_GADGETUP | IDCMP_CLOSEWINDOW | IDCMP_MENUPICK,
WA_SizeGadget, TRUE,
WA_DepthGadget, TRUE,
WA_DragBar, TRUE,
WA_CloseGadget, TRUE,
WA_Activate, TRUE,
WA_Title, "Example with ReAction gadgets and window class",
WINDOW_Position, WPOS_CENTERSCREEN,
WINDOW_NewMenu, gb_MenuDescribe,
WINDOW_HintInfo, gb_HintInfo,
WINDOW_GadgetHelp, FALSE,

/* create the Layout Object and include it into the Window */
WINDOW_ParentGroup, gb_MainLayout = (struct Gadget *)
IIntuition->NewObject(ILayout->LAYOUT_GetClass(),NULL,
LAYOUT_Orientation, LAYOUT_ORIENT_VERT,
LAYOUT_SpaceOuter, TRUE,
LAYOUT_SpaceInner, TRUE,
LAYOUT_AddChild, gb_CheckboxGad,
LAYOUT_AddChild, gb_ButtonGad,
TAG_DONE),
TAG_DONE)))
{
/* open the Window */
if((gb_Win = RA_OpenWindow(gb_WindowObj)))
{
/* query the Signal Bit of the Window */
ULONG winsig;
IIntuition->GetAttr(WINDOW_SigMask,gb_WindowObj,&winsig);

BOOL laufen = TRUE;
while(laufen)
{
ULONG result, code, val;

/* wait till either Button or Close Icon are clicked */
const ULONG sigs = IExec->Wait(winsig | SIGBREAKF_CTRL_C);

/* process the received Messages */
while((result = RA_HandleInput(gb_WindowObj,&code)) != WMHI_LASTMSG)
{
/* mask out the Messages part */
switch(result & WMHI_CLASSMASK)
{
/* process the Gadget Messages */
case WMHI_GADGETUP:
switch(result & WMHI_GADGETMASK)
{
case GAD_ID_Help:
IIntuition->GetAttr(CHECKBOX_Checked,
(Object*)gb_CheckboxGad,
(ULONG*)&val);
IIntuition->SetAttrs(gb_WindowObj,
WINDOW_GadgetHelp, val,
TAG_DONE);
break;

case GAD_ID_Quit:
laufen = FALSE;
break;
}
break;

/* query the Window Close Icon */
case WMHI_CLOSEWINDOW:
laufen = FALSE;
break;

/* query the Menu Selection */
case WMHI_MENUPICK:
switch(result & WMHI_MENUMASK)
{
case MENU_ID_Quit:
laufen = FALSE;
break;
}
break;
}
}

/* query if CTRL-C received from the Shell */
if(sigs & SIGBREAKF_CTRL_C) laufen = FALSE;
}

/* close the Window */
RA_CloseWindow(gb_WindowObj);
}
}
}

/* release Window Object, dump also Layout and Gadget Objects */
IIntuition->DisposeObject(gb_WindowObj);
}

return 0;
}
</syntaxhighlight>

[[File:AF110_reactionex.png|frame|center]]

= AllGadgets Example =

We can deal with programming with ReAction here only in theory. But for this purpose we have put "AllGadgets.c" as a bonus. Here all available gadgets are used and you can see how they can be created and queried. The use of page gadgets is also shown. In conjunction with the Clicktab gadget you can also realise tabs, which always show another 'page' with gadgets. For instance, you can divide comprehensive setting windows into individual pages.

<syntaxhighlight lang="C" line>
/* Michael Christoph
* AllGadgets.c
*
* gcc AllGadgets.c -o AllGadgets -l auto
*/

/******************************* INCLUDES *************************************/

#include <exec/types.h>
#include <intuition/gadgetclass.h>
#include <intuition/icclass.h>
#include <classes/window.h>
#include <classes/requester.h>
#include <reaction/reaction_macros.h>
#include <libraries/gadtools.h>
#include <clib/macros.h>

#include <gadgets/button.h>
#include <gadgets/space.h>
#include <gadgets/checkbox.h>
#include <gadgets/listbrowser.h>
#include <gadgets/string.h>
#include <gadgets/integer.h>
#include <gadgets/radiobutton.h>
#include <gadgets/scroller.h>
#include <gadgets/slider.h>
#include <gadgets/getfile.h>
#include <gadgets/getfont.h>
#include <gadgets/getscreenmode.h>
#include <gadgets/getcolor.h>
#include <gadgets/chooser.h>
#include <gadgets/texteditor.h>
#include <gadgets/colorwheel.h>
#include <gadgets/gradientslider.h>
#include <gadgets/datebrowser.h>
#include <gadgets/fuelgauge.h>
#include <gadgets/listview.h>
#include <gadgets/layout.h>
#include <gadgets/clicktab.h>
#include <gadgets/page.h>
#include <gadgets/palette.h>
#include <gadgets/virtual.h>

#include <images/label.h>
#include <images/bevel.h>
#include <images/bitmap.h>
#include <images/drawlist.h>
#include <images/filler.h>
#include <images/glyph.h>
#include <images/penmap.h>

#include <proto/exec.h>
#include <proto/dos.h>
#include <proto/intuition.h>
#include <proto/graphics.h>
#include <proto/utility.h>
#include <proto/asl.h>
#include <proto/locale.h>
#include <proto/application.h>
#include <proto/timer.h>
#include <proto/window.h>
#include <proto/layout.h>
#include <proto/button.h>
#include <proto/slider.h>
#include <proto/scroller.h>
#include <proto/space.h>
#include <proto/label.h>
#include <proto/integer.h>
#include <proto/string.h>
#include <proto/listbrowser.h>
#include <proto/clicktab.h>
#include <proto/chooser.h>
#include <proto/radiobutton.h>
#include <proto/checkbox.h>
#include <proto/palette.h>
#include <proto/datebrowser.h>
#include <proto/fuelgauge.h>
#include <proto/getfile.h>
#include <proto/getfont.h>
#include <proto/getscreenmode.h>
#include <proto/getcolor.h>
#include <proto/texteditor.h>
#include <proto/colorwheel.h>
#include <proto/label.h>
#include <proto/bevel.h>
#include <proto/bitmap.h>
#include <proto/drawlist.h>
#include <proto/filler.h>
#include <proto/glyph.h>
#include <proto/penmap.h>

#include <string.h>

/******************************************************************************/

static const char *version USED = "\0$VER: AllGadgets 1.01 (14.04.2014) - (c) Apr.2014 by Meicky-Soft\n";

/******************************************************************************/

enum GADIDs
{
GAD_ID_ButtonV,
GAD_ID_Button,
GAD_ID_String,
GAD_ID_Integer,
GAD_ID_Slider,
GAD_ID_Scroller,

GAD_ID_Chooser,
GAD_ID_Chooser2,
GAD_ID_Chooser3,
GAD_ID_Checkbox,
GAD_ID_Radio,
GAD_ID_Listbrowser,
GAD_ID_Palette,

GAD_ID_File,
GAD_ID_Font,
GAD_ID_Screenmode,
GAD_ID_Color,

GAD_ID_Fuelgauge,
GAD_ID_Colorwheel,
GAD_ID_Gradientslider,
GAD_ID_Texteditor,
GAD_ID_Datebrowser,

GAD_ID_Space,
GAD_ID_Page,
GAD_ID_Clicktab,

GAD_ID_Pages,
GAD_ID_PagesClicktab,
};

/******************************************************************************/

struct List gb_List;

struct ColumnInfo gb_ListbrowserColumn[] =
{
{ 30, "Nummer", 0 },
{ 170, "Eintrag", 0 },
{ -1, (STRPTR)~0, (ULONG)-1 }
};

struct Hook gb_RenderHook;
struct Hook gb_IDCMPHook;

STRPTR gb_ChooserLabels[] = { "Amiga 1000", "Amiga 1200", "AmigaOne", NULL };
STRPTR gb_Chooser2Labels[] = { "Amiga 1000", "Amiga 1200", "AmigaOne", NULL };
STRPTR gb_Chooser3Labels[] = { "Amiga 1000", "Amiga 1200", "AmigaOne", NULL };

STRPTR gb_RadioLabels[] = { "Amiga 1000", "Amiga 1200", "AmigaOne", NULL };

STRPTR gb_ClicktabLabels[] = { "Amiga 1000", "Amiga 1200", "AmigaOne", NULL };

STRPTR gb_PagesLabels[] = { "_Grundtypen", "_Auswahllisten", "ASL-Aus_wahl",
"Sonstige _Typen", "_Seitengestalltung",
"_Images", NULL };

UWORD gb_GradientArray[] = { ~0, ~0, ~0, ~0, ~0, ~0, ~0 };

/******************************************************************************/

struct Gadget *gb_ButtonVGad;
struct Gadget *gb_ButtonGad;
struct Gadget *gb_StringGad;
struct Gadget *gb_IntegerGad;
struct Gadget *gb_SliderGad;
struct Gadget *gb_ScrollerGad;
struct Gadget *gb_ChooserGad;
struct Gadget *gb_Chooser2Gad;
struct Gadget *gb_Chooser3Gad;
struct Gadget *gb_CheckboxGad;
struct Gadget *gb_RadioGad;
struct Gadget *gb_ListbrowserGad;
struct Gadget *gb_PaletteGad;
struct Gadget *gb_FileGad;
struct Gadget *gb_FontGad;
struct Gadget *gb_ScreenmodeGad;
struct Gadget *gb_ColorGad;
struct Gadget *gb_FuelgaugeGad;
struct Gadget *gb_GradientsliderGad;
struct Gadget *gb_ColorwheelGad;
struct Gadget *gb_TexteditorGad;
struct Gadget *gb_DatebrowserGad;
struct Gadget *gb_SpaceGad;
struct Gadget *gb_PageGad;
struct Gadget *gb_ClicktabGad;

struct Image *gb_LabelImg;
struct Image *gb_BevelImg;
struct Image *gb_BitmapImg;
struct Image *gb_BitmapSImg;
struct Image *gb_BitmapDImg;
struct Image *gb_DrawlistImg;
struct Image *gb_FillerImg;
struct Image *gb_GlyphImg[27];
struct Image *gb_PenmapImg;

struct Gadget *gb_MainLayout;
struct Gadget *gb_Page1Layout;
struct Gadget *gb_Page2Layout;
struct Gadget *gb_Page3Layout;
struct Gadget *gb_Page4Layout;
struct Gadget *gb_Page5Layout;
struct Gadget *gb_Page6Layout;
struct Gadget *gb_PagesLayout;
struct Gadget *gb_PagesClicktab;

Object *gb_WindowObj;
struct Window *gb_Win;
struct Screen *gb_Scr;

ULONG image_object_palette[] =
{
2,
0x00000000, 0x00000000, 0x00000000,
0xEEEEEEEE, 0xDDDDDDDD, 0x00000000
};

UBYTE happy_data[] =
{
0,16, 0,14,
0,0,0,0,0,1,1,1,1,1,1,0,0,0,0,0,
0,0,0,1,1,2,2,2,2,2,2,1,1,0,0,0,
0,0,1,2,2,2,2,2,2,2,2,2,2,1,0,0,
0,1,2,2,2,2,2,2,2,2,2,2,2,2,1,0,
0,1,2,2,2,1,1,2,2,1,1,2,2,2,1,0,
1,2,2,2,2,1,1,2,2,1,1,2,2,2,2,1,
1,2,2,2,2,1,1,2,2,1,1,2,2,2,2,1,
1,2,2,2,2,2,2,2,2,2,2,2,2,2,2,1,
1,2,2,2,2,2,2,2,2,2,2,2,2,2,2,1,
0,1,2,2,2,1,2,2,2,2,1,2,2,2,1,0,
0,1,2,2,2,2,1,1,1,1,2,2,2,2,1,0,
0,0,1,2,2,2,2,2,2,2,2,2,2,1,0,0,
0,0,0,1,1,2,2,2,2,2,2,1,1,0,0,0,
0,0,0,0,0,1,1,1,1,1,1,0,0,0,0,0
};

UBYTE scared_data[] =
{
0,16, 0,14,
0,0,0,0,0,1,1,1,1,1,1,0,0,0,0,0,
0,0,0,1,1,2,2,2,2,2,2,1,1,0,0,0,
0,0,1,2,2,2,2,2,2,2,2,2,2,1,0,0,
0,1,2,2,2,1,1,2,2,1,1,2,2,2,1,0,
0,1,2,2,1,2,2,2,2,2,2,1,2,2,1,0,
1,2,2,2,2,1,1,2,2,1,1,2,2,2,2,1,
1,2,2,2,2,1,1,2,2,1,1,2,2,2,2,1,
1,2,2,2,2,2,2,2,2,2,2,2,2,2,2,1,
1,2,2,2,2,2,2,2,2,2,2,2,2,2,2,1,
0,1,2,2,2,2,1,1,1,1,2,2,2,2,1,0,
0,1,2,2,2,1,1,1,1,1,1,2,2,2,1,0,
0,0,1,2,2,2,2,2,2,2,2,2,2,1,0,0,
0,0,0,1,1,2,2,2,2,2,2,1,1,0,0,0,
0,0,0,0,0,1,1,1,1,1,1,0,0,0,0,0
};

struct DrawList gb_DrawList[] =
{
{ DLST_LINE, 0,30,15,0, 1},
{ DLST_LINE, 30,30,15,0, 1},
{ DLST_LINE, 9,15,23,15, 1},
{ DLST_END }
};

/******************************************************************************/

BOOL CreateEntry(ULONG num, CONST_STRPTR number, CONST_STRPTR text)
{
/* create a List entry */

/* ATTENTION:
** Use this function only if the List is *not* assigned to the ListView!
** If applicable, deselect via
** SetGadgetAttrs(gad,win,NULL, LISTBROWSER_Labels,~0, TAG_END);
** then modify the List, then assign the List via
** SetGadgetAttrs(gad,win,NULL, LISTBROWSER_Labels,liste, TAG_END);
** back to the ListView.

struct Node *node;

if((node = IListBrowser->AllocListBrowserNode(2,
LBNA_Column, 0,
LBNCA_Text, number,
LBNCA_Justification, LCJ_LEFT,
LBNCA_Editable, FALSE,
LBNCA_CopyText, TRUE,
LBNCA_MaxChars, 4,
LBNA_Column, 1,
LBNCA_Text, text,
LBNCA_Justification, LCJ_LEFT,
LBNCA_Editable, FALSE,
LBNCA_CopyText, TRUE,
LBNCA_MaxChars, 100,
TAG_END)))
{
node->ln_Pri = num;
IExec->AddTail(&gb_List,node);
}
else
{
IDOS->Printf("Out of memory while creating list entry\n");
}

return( node ? TRUE : FALSE );
}

/******************************************************************************/

void FreigebenList()
{
/* release the List with all its data */

/* ATTENTION:
** Use this function only if the List is *not* assigned to the ListView!
** If applicable, deselect via
** SetGadgetAttrs(gad,win,NULL, LISTBROWSER_Labels,~0, TAG_END);
** then modify the List, then assign the (empty) List via
** SetGadgetAttrs(gad,win,NULL, LISTBROWSER_Labels,liste, TAG_END);
** back to the ListView.
*/

struct Node *node, *nextnode;
node = gb_List.lh_Head;

while((nextnode = node->ln_Succ))
{
IExec->Remove(node);
IListBrowser->FreeListBrowserNode(node);

node = nextnode;
}
}

/******************************************************************************/

void RenderHookFunc(struct Hook *hook, Object *obj, struct gpRender *gpr)
{
/*
** Hook Function to refresh the Space Gadgets
*/

/* only if the Window is visible we can draw into it */
if(gb_Win)
{
/* determine the size of our Output Area */
struct IBox *gb_DrawArea;
IIntuition->GetAttr(SPACE_AreaBox,(Object*)gb_SpaceGad,(ULONG *)&gb_DrawArea);

/* empty the complete Area with Background Color */
IGraphics->SetAPen(gpr->gpr_RPort,0);
IGraphics->RectFill(gpr->gpr_RPort,gb_DrawArea->Left,gb_DrawArea->Top,
gb_DrawArea->Left+gb_DrawArea->Width-1,gb_DrawArea->Top+gb_DrawArea->Height-1);
}
}

/******************************************************************************/

void IDCMPHookFunc(struct Hook *hook, Object *winobj, struct IntuiMessage *msg)
{
/*
** Hook Function for listening to IDCMP_UPDATE Messages
*/

struct TagItem *taglist = (struct TagItem *) msg->IAddress;
const LONG gadid = IUtility->GetTagData(GA_ID,-1,taglist);

if(msg->Class == IDCMP_GADGETDOWN)
{
/* Press Mouse Button: Set start position without drawing */
IGraphics->SetAPen(gb_Win->RPort,4);
IGraphics->Move(gb_Win->RPort,msg->MouseX,msg->MouseY);
}

if(msg->Class == IDCMP_IDCMPUPDATE && gadid == GAD_ID_Space)
{
//ULONG mx, my;
//IIntuition->GetAttr(SPACE_MouseX,gb_SpaceGad,(ULONG*)&mx);
//IIntuition->GetAttr(SPACE_MouseY,gb_SpaceGad,(ULONG*)&my);

/* determine the size of our Output Area */
/* so we don't draw outside of this area */
struct IBox *gb_DrawArea;
IIntuition->GetAttr(SPACE_AreaBox,(Object*)gb_SpaceGad,(ULONG *)&gb_DrawArea);

const LONG mx = msg->MouseX;
const LONG my = msg->MouseY;

if(mx >= gb_DrawArea->Left &&
my >= gb_DrawArea->Top &&
mx <= gb_DrawArea->Left+gb_DrawArea->Width-1 &&
my <= gb_DrawArea->Top+gb_DrawArea->Height-1)
{
IGraphics->Draw(gb_Win->RPort,msg->MouseX,msg->MouseY);
}
}
}

/******************************************************************************/

BOOL CreateAll()
{
int i;

/* Screen Pointer is needed for single Gadgets */
gb_Scr = IIntuition->LockPubScreen(NULL);

if(gb_Scr)
{
/* request and set pens for the Gradient Slider */
struct ColorMap *cm = gb_Scr->ViewPort.ColorMap;

gb_GradientArray[0] = IGraphics->ObtainPen(cm,~0,0xFF,0xFF,0xFF,PENF_EXCLUSIVE);
gb_GradientArray[1] = IGraphics->ObtainPen(cm,~0,0xCC,0xCC,0xCC,PENF_EXCLUSIVE);
gb_GradientArray[2] = IGraphics->ObtainPen(cm,~0,0x99,0x99,0x99,PENF_EXCLUSIVE);
gb_GradientArray[3] = IGraphics->ObtainPen(cm,~0,0x66,0x66,0x66,PENF_EXCLUSIVE);
gb_GradientArray[4] = IGraphics->ObtainPen(cm,~0,0x33,0x33,0x33,PENF_EXCLUSIVE);
gb_GradientArray[5] = IGraphics->ObtainPen(cm,~0,0x00,0x00,0x00,PENF_EXCLUSIVE);

struct ViewPort *vp = &gb_Scr->ViewPort;

if((WORD)gb_GradientArray[0] != ~0) IGraphics->SetRGB4(vp,gb_GradientArray[0],0xFF,0xFF,0xFF);
if((WORD)gb_GradientArray[1] != ~0) IGraphics->SetRGB4(vp,gb_GradientArray[1],0xCC,0xCC,0xCC);
if((WORD)gb_GradientArray[2] != ~0) IGraphics->SetRGB4(vp,gb_GradientArray[2],0x99,0x99,0x99);
if((WORD)gb_GradientArray[3] != ~0) IGraphics->SetRGB4(vp,gb_GradientArray[3],0x66,0x66,0x66);
if((WORD)gb_GradientArray[4] != ~0) IGraphics->SetRGB4(vp,gb_GradientArray[4],0x33,0x33,0x33);
if((WORD)gb_GradientArray[5] != ~0) IGraphics->SetRGB4(vp,gb_GradientArray[5],0x00,0x00,0x00);
}

/* create Listbrowser entries */
IExec->NewList(&gb_List);
CreateEntry(0,"1","Amiga 1000");
CreateEntry(1,"2","Amiga 1200");
CreateEntry(2,"3","AmigaOne");

/* initialize RenderHook */
gb_RenderHook.h_Entry = (ULONG (*)())RenderHookFunc;
gb_RenderHook.h_SubEntry = NULL;

/* initialize IDCMPHook for listening to IDCMP_UPDATE Messages */
gb_IDCMPHook.h_Entry = (ULONG (*)())IDCMPHookFunc;
gb_IDCMPHook.h_SubEntry = NULL;

/* create Gadget Object */
gb_ButtonVGad = (struct Gadget *) IIntuition->NewObject(IButton->BUTTON_GetClass(),NULL,
BUTTON_BevelStyle, BVS_THIN,
BUTTON_Justification, BCJ_LEFT,
GA_ID, GAD_ID_ButtonV,
GA_Text, "Info-Anzeige",
GA_ReadOnly, TRUE,
TAG_END);

gb_ButtonGad = (struct Gadget *) IIntuition->NewObject(IButton->BUTTON_GetClass(),NULL,
GA_ID, GAD_ID_Button,
GA_Text, "Button",
TAG_END);

gb_StringGad = (struct Gadget *) IIntuition->NewObject(IString->STRING_GetClass(),NULL,
GA_ID, GAD_ID_String,
GA_RelVerify, TRUE,
GA_TabCycle, TRUE,
STRINGA_MaxChars, 30+1,
STRINGA_MinVisible, 30,
STRINGA_TextVal, "Amiga 1000",
TAG_END);

gb_IntegerGad = (struct Gadget *) IIntuition->NewObject(IInteger->INTEGER_GetClass(),NULL,
GA_ID, GAD_ID_Integer,
GA_RelVerify, TRUE,
GA_TabCycle, TRUE,
INTEGER_MaxChars, 4,
INTEGER_Arrows, TRUE,
INTEGER_MinVisible, 3,
INTEGER_Minimum, 1,
INTEGER_Maximum, 100,
TAG_END);

gb_SliderGad = (struct Gadget *) IIntuition->NewObject(ISlider->SLIDER_GetClass(),NULL,
GA_ID, GAD_ID_Slider,
GA_Immediate, TRUE,
GA_RelVerify, TRUE,
SLIDER_Min, 0,
SLIDER_Max, 100,
SLIDER_Level, 10,
SLIDER_Orientation, SLIDER_HORIZONTAL,
SLIDER_Ticks, 11,
SLIDER_KnobDelta, 50,
SLIDER_LevelFormat, "%3ld",
SLIDER_LevelMaxLen, 3+1,
SLIDER_LevelPlace, PLACETEXT_IN,
TAG_END);

gb_ScrollerGad = (struct Gadget *) IIntuition->NewObject(IScroller->SCROLLER_GetClass(),NULL,
GA_ID, GAD_ID_Scroller,
GA_Immediate, TRUE,
GA_RelVerify, TRUE,
SCROLLER_Top, 1,
SCROLLER_Visible, 5,
SCROLLER_Total, 105,
SCROLLER_Orientation, SCROLLER_HORIZONTAL,
SCROLLER_Arrows, TRUE,
SCROLLER_Stretch, TRUE,
SCROLLER_ArrowDelta, 10,
TAG_END);

gb_ChooserGad = (struct Gadget *) IIntuition->NewObject(IChooser->CHOOSER_GetClass(),NULL,
GA_ID, GAD_ID_Chooser,
GA_RelVerify, TRUE,
GA_Underscore, '#',
CHOOSER_PopUp, TRUE,
CHOOSER_DropDown, FALSE,
CHOOSER_LabelArray, gb_ChooserLabels,
CHOOSER_Selected, 0,
CHOOSER_MaxLabels, 10,
TAG_END);

gb_Chooser2Gad = (struct Gadget *) IIntuition->NewObject(IChooser->CHOOSER_GetClass(),NULL,
GA_ID, GAD_ID_Chooser2,
GA_RelVerify, TRUE,
GA_Underscore, '#',
CHOOSER_PopUp, FALSE,
CHOOSER_DropDown, TRUE,
CHOOSER_Title, "Eintrâ°ge",
CHOOSER_LabelArray, gb_Chooser2Labels,
CHOOSER_Selected, 0,
CHOOSER_MaxLabels, 10,
TAG_END);

gb_Chooser3Gad = (struct Gadget *) IIntuition->NewObject(IChooser->CHOOSER_GetClass(),NULL,
GA_ID, GAD_ID_Chooser3,
GA_RelVerify, TRUE,
GA_Underscore, '#',
CHOOSER_PopUp, FALSE,
CHOOSER_DropDown, TRUE,
CHOOSER_LabelArray, gb_Chooser3Labels,
CHOOSER_Selected, 0,
CHOOSER_MaxLabels, 10,
TAG_END);

gb_CheckboxGad = (struct Gadget *) IIntuition->NewObject(ICheckBox->CHECKBOX_GetClass(),NULL,
GA_ID, GAD_ID_Checkbox,
GA_Text, "Anwahl",
CHECKBOX_TextPlace, PLACETEXT_RIGHT,
CHECKBOX_Checked, TRUE,
TAG_END);

gb_RadioGad = (struct Gadget *) IIntuition->NewObject(IRadioButton->RADIOBUTTON_GetClass(),NULL,
GA_ID, GAD_ID_Radio,
GA_RelVerify, TRUE,
GA_Text, gb_RadioLabels,
//RADIOBUTTON_LabelArray, gb_RadioLabels,
RADIOBUTTON_Selected, 2,
RADIOBUTTON_LabelPlace, PLACETEXT_RIGHT,
RADIOBUTTON_Spacing, 4,
TAG_END);

gb_ListbrowserGad = (struct Gadget *) IIntuition->NewObject(IListBrowser->LISTBROWSER_GetClass(),NULL,
GA_ReadOnly, FALSE,
GA_ID, GAD_ID_Listbrowser,
GA_RelVerify, TRUE,
LISTBROWSER_ColumnInfo, &gb_ListbrowserColumn,
LISTBROWSER_ColumnTitles, TRUE,
LISTBROWSER_Labels, &gb_List,
LISTBROWSER_VertSeparators, TRUE,
LISTBROWSER_Spacing, 1,
LISTBROWSER_ShowSelected, TRUE,
LISTBROWSER_AutoFit, TRUE,
LISTBROWSER_Editable, FALSE,
LISTBROWSER_MinVisible, 2,
TAG_END);

gb_PaletteGad = (struct Gadget *) IIntuition->NewObject(IPalette->PALETTE_GetClass(),NULL,
GA_ReadOnly, FALSE,
GA_ID, GAD_ID_Palette,
GA_RelVerify, TRUE,
PALETTE_Colour, 1,
PALETTE_ColourOffset, 0,
PALETTE_NumColours, 8,
TAG_END);

gb_FileGad = (struct Gadget *) IIntuition->NewObject(IGetFile->GETFILE_GetClass(),NULL,
GA_ID, GAD_ID_File,
GA_RelVerify, TRUE,
GA_TabCycle, TRUE,
GETFILE_TitleText, ""Select File ...",
GETFILE_Pattern, "#?",
GETFILE_DoSaveMode, FALSE,
GETFILE_RejectIcons, TRUE,
GETFILE_ReadOnly, TRUE,
GETFILE_DrawersOnly, FALSE,
TAG_END);

gb_FontGad = (struct Gadget *) IIntuition->NewObject(IGetFont->GETFONT_GetClass(),NULL,
GA_ID, GAD_ID_Font,
GA_RelVerify, TRUE,
GETFONT_TitleText, "Select Font ...",
GETFONT_MinHeight, 6,
GETFONT_MaxHeight, 30,
TAG_END);

gb_ScreenmodeGad = (struct Gadget *) IIntuition->NewObject(IGetScreenMode->GETSCREENMODE_GetClass(),NULL,
GA_ID, GAD_ID_Screenmode,
GA_RelVerify, TRUE,
GETSCREENMODE_TitleText, "Select Screen Mode ...",
GETSCREENMODE_MinDepth, 2,
GETSCREENMODE_MaxDepth, 8,
TAG_END);

gb_ColorGad = (struct Gadget *) IIntuition->NewObject(IGetColor->GETCOLOR_GetClass(),NULL,
GA_ID, GAD_ID_Color,
GA_RelVerify, TRUE,
GETCOLOR_TitleText, "Choose Color ...",
GETCOLOR_Screen, gb_Scr,
GETCOLOR_Color, 0x00aaccee,
GETCOLOR_ColorWheel, TRUE,
GETCOLOR_RGBSliders, TRUE,
GETCOLOR_ShowRGB, TRUE,
TAG_END);

gb_FuelgaugeGad = (struct Gadget *) IIntuition->NewObject(IFuelGauge->FUELGAUGE_GetClass(),NULL,
GA_ReadOnly, FALSE,
GA_ID, GAD_ID_Fuelgauge,
GA_RelVerify, TRUE,
FUELGAUGE_Min, 0,
FUELGAUGE_Max, 100,
FUELGAUGE_Level, 10,
FUELGAUGE_Orientation, FGORIENT_HORIZ,
FUELGAUGE_Percent, TRUE,
FUELGAUGE_Ticks, 10,
FUELGAUGE_ShortTicks, 10,
FUELGAUGE_Justification, FGJ_CENTER,
TAG_END);

gb_GradientsliderGad = (struct Gadget *) IIntuition->NewObject(NULL,"gradientslider.gadget",
GA_ID, GAD_ID_Gradientslider,
GA_RelVerify, TRUE,
GA_TabCycle, TRUE,
GRAD_PenArray, gb_GradientArray,
PGA_Freedom, LORIENT_VERT,
TAG_END);

/* set Color Wheel to this RGB value */
struct ColorWheelRGB rgbval = { 0xFFFFFFFF, 0xFFFFFFFF, 0xFFFFFFFF };

gb_ColorwheelGad = (struct Gadget *) IIntuition->NewObject(NULL,"colorwheel.gadget",
GA_ID, GAD_ID_Colorwheel,
GA_RelVerify, TRUE,
GA_TabCycle, TRUE,
WHEEL_Screen, gb_Scr,
//WHEEL_GradientSlider, gb_GradientsliderGad,
WHEEL_BevelBox, FALSE,
WHEEL_RGB, rgbval,
TAG_END);

gb_TexteditorGad = (struct Gadget *) IIntuition->NewObject(ITextEditor->TEXTEDITOR_GetClass(),NULL,
GA_ID, GAD_ID_Texteditor,
GA_RelVerify, TRUE,
GA_TabCycle, TRUE,
GA_TEXTEDITOR_FixedFont, FALSE,
TAG_END);

gb_DatebrowserGad = (struct Gadget *) IIntuition->NewObject(IDateBrowser->DATEBROWSER_GetClass(),NULL,
GA_ID, GAD_ID_Datebrowser,
GA_RelVerify, TRUE,
GA_TabCycle, TRUE,
DATEBROWSER_Day, 27,
DATEBROWSER_Month, 10,
DATEBROWSER_Year, 2007,
DATEBROWSER_ShowTitle, TRUE,
DATEBROWSER_ShowWeek, TRUE,
DATEBROWSER_MultiSelect, FALSE,
TAG_END);

gb_SpaceGad = (struct Gadget *) IIntuition->NewObject(ISpace->SPACE_GetClass(),NULL,
GA_ID, GAD_ID_Space,
GA_RelVerify, TRUE, /* send Gadget Up */
GA_Immediate, TRUE, /* send Gadget Down */
GA_ReadOnly, FALSE,
SPACE_Transparent, TRUE, /* Background not deleted automatically */
SPACE_MinWidth, 10,
SPACE_MinHeight, 10,
SPACE_BevelStyle, BVS_DROPBOX,
SPACE_RenderHook, &gb_RenderHook,
ICA_TARGET, ICTARGET_IDCMP, /* send a Message to the Program */
TAG_END);

gb_PageGad = (struct Gadget *) IIntuition->NewObject(ILayout->PAGE_GetClass(),NULL,
GA_ID, GAD_ID_Page,
LAYOUT_Orientation, LAYOUT_VERTICAL,
LAYOUT_FixedHoriz, FALSE,
LAYOUT_FixedVert, FALSE,
LAYOUT_SpaceInner, TRUE,

PAGE_Add, IIntuition->NewObject(ILayout->LAYOUT_GetClass(),NULL,
LAYOUT_AddChild, IIntuition->NewObject(IButton->BUTTON_GetClass(),NULL,
BUTTON_BevelStyle, BVS_NONE, BUTTON_Transparent, TRUE, GA_Text, "Amiga 1000", GA_ReadOnly, TRUE, TAG_END),
TAG_END),
PAGE_Add, IIntuition->NewObject(ILayout->LAYOUT_GetClass(),NULL,
LAYOUT_AddChild, IIntuition->NewObject(IButton->BUTTON_GetClass(),NULL,
BUTTON_BevelStyle, BVS_NONE, BUTTON_Transparent, TRUE, GA_Text, "Amiga 1200", GA_ReadOnly, TRUE, TAG_END),
TAG_END),
PAGE_Add, IIntuition->NewObject(ILayout->LAYOUT_GetClass(),NULL,
LAYOUT_AddChild, IIntuition->NewObject(IButton->BUTTON_GetClass(),NULL,
BUTTON_BevelStyle, BVS_NONE, BUTTON_Transparent, TRUE, GA_Text, "AmigaOne", GA_ReadOnly, TRUE, TAG_END),
TAG_END),
TAG_END);

gb_ClicktabGad = (struct Gadget *) IIntuition->NewObject(IClickTab->CLICKTAB_GetClass(),NULL,
GA_ID, GAD_ID_Clicktab,
GA_Text, &gb_ClicktabLabels,
GA_RelVerify, TRUE,
CLICKTAB_PageGroup, gb_PageGad,
TAG_END);

gb_LabelImg = (struct Image *) IIntuition->NewObject(ILabel->LABEL_GetClass(),NULL,
LABEL_Text, "Beschriftung",
//LABEL_SoftStyle, FSF_BOLD,
//LABEL_Justification, LJ_LEFT,
TAG_END);

gb_BevelImg = (struct Image *) IIntuition->NewObject(IBevel->BEVEL_GetClass(),NULL,
BEVEL_Style, BVS_BOX,
TAG_END);

gb_BitmapImg = (struct Image *) IIntuition->NewObject(IBitMap->BITMAP_GetClass(),NULL,
BITMAP_Screen, gb_Scr,
BITMAP_Masking, FALSE,
BITMAP_SourceFile, "amiga1000-normal.iff",
BITMAP_SelectSourceFile, "amiga1000-selected.iff",
BITMAP_DisabledSourceFile, "amiga1000-disabled.iff",
IA_SupportsDisable, TRUE,
TAG_END);

gb_BitmapSImg = (struct Image *) IIntuition->NewObject(IBitMap->BITMAP_GetClass(),NULL,
BITMAP_Screen, gb_Scr,
BITMAP_Masking, FALSE,
BITMAP_SourceFile, "amiga1000-selected.iff",
IA_SupportsDisable, TRUE,
TAG_END);

gb_BitmapDImg = (struct Image *) IIntuition->NewObject(IBitMap->BITMAP_GetClass(),NULL,
BITMAP_Screen, gb_Scr,
BITMAP_Masking, FALSE,
BITMAP_SourceFile, "amiga1000-disabled.iff",
TAG_END);

gb_DrawlistImg = (struct Image *) IIntuition->NewObject(IDrawList->DRAWLIST_GetClass(),NULL,
DRAWLIST_Directives, gb_DrawList,
TAG_END);

gb_FillerImg = (struct Image *) IIntuition->NewObject(IFiller->FILLER_GetClass(),NULL,
FILLER_Screen, gb_Scr,
FILLER_BackgroundColor, 0xffaaaaaa,
FILLER_ImageFilename, "amigaball.iff",
FILLER_ImageMode, FILLER_MODE_TILED,
IA_Width, 30,
IA_Height, 30,
TAG_END);

gb_PenmapImg = (struct Image *) IIntuition->NewObject(IPenMap->PENMAP_GetClass(),NULL,
PENMAP_RenderData, happy_data,
PENMAP_Palette, image_object_palette,
PENMAP_Screen, gb_Scr,
PENMAP_Transparent, TRUE,
TAG_END);

for(i=1; i<=26; i++)
{
/* 13-17 and 19 do not exist */
gb_GlyphImg[i] = (struct Image *) IIntuition->NewObject(IGlyph->GLYPH_GetClass(),NULL,
GLYPH_Glyph, i, /*GLYPH_xxx */
IA_Width, 20,
IA_Height, 20,
TAG_END);
}

/* create the single pages of the Drag Bar */
gb_Page1Layout = (struct Gadget *) IIntuition->NewObject(ILayout->LAYOUT_GetClass(),NULL,
LAYOUT_Orientation, LAYOUT_ORIENT_VERT,
LAYOUT_SpaceOuter, TRUE,
LAYOUT_SpaceInner, TRUE,
LAYOUT_BevelStyle, BVS_GROUP,
LAYOUT_Label, "Grundtypen",
LAYOUT_LabelPlace, BVJ_TOP_CENTER,

LAYOUT_AddChild, gb_ButtonVGad,
CHILD_WeightedHeight, 80,
LAYOUT_AddChild, gb_ButtonGad,
CHILD_WeightedHeight, 10,
LAYOUT_AddChild, gb_StringGad,
LAYOUT_AddChild, gb_IntegerGad,
LAYOUT_AddChild, gb_SliderGad,
CHILD_WeightedHeight, 10,
LAYOUT_AddChild, gb_ScrollerGad,
TAG_END);

gb_Page2Layout = (struct Gadget *) IIntuition->NewObject(ILayout->LAYOUT_GetClass(),NULL,
LAYOUT_Orientation, LAYOUT_ORIENT_VERT,
LAYOUT_SpaceOuter, TRUE,
LAYOUT_SpaceInner, TRUE,
LAYOUT_BevelStyle, BVS_GROUP,
LAYOUT_Label, "Auswahllisten",
LAYOUT_LabelPlace, BVJ_TOP_CENTER,

LAYOUT_AddChild, IIntuition->NewObject(ILayout->LAYOUT_GetClass(),NULL,
LAYOUT_Orientation, LAYOUT_ORIENT_HORIZ,
LAYOUT_AddChild, gb_ChooserGad,
LAYOUT_AddChild, gb_Chooser2Gad,
LAYOUT_AddChild, gb_Chooser3Gad,
TAG_END),
CHILD_WeightedHeight, 0,

LAYOUT_AddChild, gb_CheckboxGad,
CHILD_WeightedHeight, 0,
LAYOUT_AddChild, gb_RadioGad,
CHILD_WeightedHeight, 0,
LAYOUT_AddChild, gb_ListbrowserGad,
CHILD_WeightedHeight, 90,
LAYOUT_AddChild, gb_PaletteGad,
CHILD_WeightedHeight, 10,
TAG_END);

gb_Page3Layout = (struct Gadget *) IIntuition->NewObject(ILayout->LAYOUT_GetClass(),NULL,
LAYOUT_Orientation, LAYOUT_ORIENT_VERT,
LAYOUT_SpaceOuter, TRUE,
LAYOUT_SpaceInner, TRUE,
LAYOUT_BevelStyle, BVS_GROUP,
LAYOUT_Label, "ASL-Auswahl",
LAYOUT_LabelPlace, BVJ_TOP_CENTER,

LAYOUT_AddChild, gb_FileGad,
CHILD_WeightedHeight, 0,
LAYOUT_AddChild, gb_FontGad,
CHILD_WeightedHeight, 0,
LAYOUT_AddChild, gb_ScreenmodeGad,
CHILD_WeightedHeight, 0,
LAYOUT_AddChild, gb_ColorGad,
CHILD_WeightedHeight, 0,
TAG_END);

gb_Page4Layout = (struct Gadget *) IIntuition->NewObject(ILayout->LAYOUT_GetClass(),NULL,
LAYOUT_Orientation, LAYOUT_ORIENT_VERT,
LAYOUT_SpaceOuter, TRUE,
LAYOUT_SpaceInner, TRUE,
LAYOUT_BevelStyle, BVS_GROUP,
LAYOUT_Label, "Sonstige Typen",
LAYOUT_LabelPlace, BVJ_TOP_CENTER,

LAYOUT_AddChild, gb_FuelgaugeGad,
CHILD_WeightedHeight, 10,

LAYOUT_AddChild, IIntuition->NewObject(ILayout->LAYOUT_GetClass(),NULL,
LAYOUT_Orientation, LAYOUT_ORIENT_HORIZ,
LAYOUT_AddChild, gb_ColorwheelGad,
//CHILD_WeightedWidth, 0,
//CHILD_WeightedHeight, 0,
LAYOUT_AddChild, gb_GradientsliderGad,
LAYOUT_AddChild, IIntuition->NewObject(ISpace->SPACE_GetClass(),NULL,
SPACE_Transparent, FALSE,
SPACE_MinWidth, 10,
SPACE_MinHeight, 10,
TAG_END),
TAG_END),
CHILD_WeightedHeight, 70,

LAYOUT_AddChild, gb_TexteditorGad,
CHILD_WeightedHeight, 10,
LAYOUT_AddChild, gb_DatebrowserGad,
CHILD_WeightedHeight, 10,
TAG_END);

gb_Page5Layout = (struct Gadget *) IIntuition->NewObject(ILayout->LAYOUT_GetClass(),NULL,
LAYOUT_Orientation, LAYOUT_ORIENT_VERT,
LAYOUT_SpaceOuter, TRUE,
LAYOUT_SpaceInner, TRUE,
LAYOUT_BevelStyle, BVS_GROUP,
LAYOUT_Label, "Seitengestalltung",
LAYOUT_LabelPlace, BVJ_TOP_CENTER,

LAYOUT_AddChild, gb_SpaceGad,
LAYOUT_AddChild, gb_ClicktabGad,
TAG_END);

gb_Page6Layout = (struct Gadget *) IIntuition->NewObject(ILayout->LAYOUT_GetClass(),NULL,
LAYOUT_Orientation, LAYOUT_ORIENT_VERT,
LAYOUT_SpaceOuter, TRUE,
LAYOUT_SpaceInner, TRUE,
LAYOUT_BevelStyle, BVS_GROUP,
LAYOUT_Label, "Images",
LAYOUT_LabelPlace, BVJ_TOP_CENTER,

LAYOUT_AddImage, gb_LabelImg,

LAYOUT_AddImage, gb_BevelImg,
CHILD_MinHeight, 10,

LAYOUT_AddChild, IIntuition->NewObject(ILayout->LAYOUT_GetClass(),NULL,
LAYOUT_Orientation, LAYOUT_ORIENT_HORIZ,
LAYOUT_AddImage, gb_BitmapImg,
LAYOUT_AddImage, gb_BitmapSImg,
LAYOUT_AddImage, gb_BitmapDImg,
TAG_END),
CHILD_WeightedHeight, 0,

LAYOUT_AddImage, gb_DrawlistImg,
CHILD_MinWidth, 30,
CHILD_MinHeight, 30,
CHILD_WeightedWidth, 0,
CHILD_WeightedHeight, 0,

LAYOUT_AddImage, gb_FillerImg,
CHILD_MinWidth, 30,
CHILD_MinHeight, 30,
CHILD_MaxWidth, 200,
CHILD_MaxHeight, 60,

LAYOUT_AddImage, gb_PenmapImg,
CHILD_WeightedWidth, 0,
CHILD_WeightedHeight, 0,

LAYOUT_AddChild, IIntuition->NewObject(ILayout->LAYOUT_GetClass(),NULL,
LAYOUT_Orientation, LAYOUT_ORIENT_HORIZ,

LAYOUT_AddImage, gb_GlyphImg[ 1],
CHILD_MinWidth, 20,
LAYOUT_AddImage, gb_GlyphImg[ 2],
CHILD_MinWidth, 20,
LAYOUT_AddImage, gb_GlyphImg[ 3],
CHILD_MinWidth, 20,
LAYOUT_AddImage, gb_GlyphImg[ 4],
CHILD_MinWidth, 20,
LAYOUT_AddImage, gb_GlyphImg[ 5],
CHILD_MinWidth, 20,
LAYOUT_AddImage, gb_GlyphImg[ 6],
CHILD_MinWidth, 20,
LAYOUT_AddImage, gb_GlyphImg[ 7],
CHILD_MinWidth, 20,
LAYOUT_AddImage, gb_GlyphImg[ 8],
CHILD_MinWidth, 20,
LAYOUT_AddImage, gb_GlyphImg[ 9],
CHILD_MinWidth, 20,
LAYOUT_AddImage, gb_GlyphImg[10],
CHILD_MinWidth, 20,
LAYOUT_AddImage, gb_GlyphImg[11],
CHILD_MinWidth, 20,
LAYOUT_AddImage, gb_GlyphImg[12],
CHILD_MinWidth, 20,
LAYOUT_AddImage, gb_GlyphImg[18],
CHILD_MinWidth, 20,
LAYOUT_AddImage, gb_GlyphImg[20],
CHILD_MinWidth, 20,
LAYOUT_AddImage, gb_GlyphImg[21],
CHILD_MinWidth, 20,
LAYOUT_AddImage, gb_GlyphImg[22],
CHILD_MinWidth, 20,
LAYOUT_AddImage, gb_GlyphImg[23],
CHILD_MinWidth, 20,
LAYOUT_AddImage, gb_GlyphImg[24],
CHILD_MinWidth, 20,
LAYOUT_AddImage, gb_GlyphImg[25],
CHILD_MinWidth, 20,
LAYOUT_AddImage, gb_GlyphImg[26],
CHILD_MinWidth, 20,
TAG_END),
CHILD_MinHeight, 20,
CHILD_WeightedHeight, 10,

TAG_END);

gb_PagesLayout = (struct Gadget *) IIntuition->NewObject(ILayout->PAGE_GetClass(),NULL,
GA_ID, GAD_ID_Pages,
LAYOUT_Orientation, LAYOUT_VERTICAL,
LAYOUT_FixedHoriz, FALSE,
LAYOUT_FixedVert, FALSE,
LAYOUT_SpaceInner, TRUE,

PAGE_Add, gb_Page1Layout,
PAGE_Add, gb_Page2Layout,
PAGE_Add, gb_Page3Layout,
PAGE_Add, gb_Page4Layout,
PAGE_Add, gb_Page5Layout,
PAGE_Add, gb_Page6Layout,

TAG_END);

gb_PagesClicktab = (struct Gadget *) IIntuition->NewObject(IClickTab->CLICKTAB_GetClass(),NULL,
GA_ID, GAD_ID_PagesClicktab,
GA_Text, &gb_PagesLabels,
CLICKTAB_PageGroup, gb_PagesLayout,
TAG_END);

IIntuition->UnlockPubScreen(NULL,gb_Scr);

/* create Layout Object */
gb_MainLayout = (struct Gadget *) IIntuition->NewObject(ILayout->LAYOUT_GetClass(),NULL,
LAYOUT_Orientation, LAYOUT_ORIENT_VERT,
LAYOUT_SpaceOuter, TRUE,
LAYOUT_SpaceInner, TRUE,

LAYOUT_AddChild, gb_PagesClicktab,

TAG_END);

if(gb_MainLayout)
{

/* create the Window Object */
if((gb_WindowObj = (Object *) IIntuition->NewObject(IWindow->WINDOW_GetClass(),NULL,
WA_IDCMP, IDCMP_GADGETUP | IDCMP_GADGETDOWN |
IDCMP_MOUSEMOVE |
IDCMP_VANILLAKEY | IDCMP_RAWKEY |
IDCMP_CLOSEWINDOW,
WA_SizeGadget, TRUE,
WA_DepthGadget, TRUE,
WA_DragBar, TRUE,
WA_Activate, TRUE,
WA_Title, "All ReAction Gadgets",
WA_InnerWidth, 100,
WA_InnerHeight, 100,
WA_AutoAdjust, TRUE,
WA_CloseGadget, TRUE,
WA_RMBTrap, TRUE,
WINDOW_ParentGroup, gb_MainLayout,
WINDOW_IDCMPHook, &gb_IDCMPHook,
WINDOW_IDCMPHookBits, IDCMP_IDCMPUPDATE | IDCMP_GADGETDOWN,
TAG_END)))
{
/* everything created correctly */

/* the Window can be shown now */
gb_Win = RA_OpenWindow(gb_WindowObj);
}
}

return gb_WindowObj ? TRUE : FALSE;
}

/******************************************************************************/

void DestroyAll()
{
/* close Window and release included Objects */
RA_CloseWindow(gb_WindowObj);
IIntuition->DisposeObject(gb_WindowObj);

/* release Listview entries */
FreigebenList();

/* release the reserved pens */
struct ColorMap *cm = (gb_Scr ? gb_Scr->ViewPort.ColorMap : NULL);

if((WORD)gb_GradientArray[0] != ~0) IGraphics->ReleasePen(cm,gb_GradientArray[0]);
if((WORD)gb_GradientArray[1] != ~0) IGraphics->ReleasePen(cm,gb_GradientArray[1]);
if((WORD)gb_GradientArray[2] != ~0) IGraphics->ReleasePen(cm,gb_GradientArray[2]);
if((WORD)gb_GradientArray[3] != ~0) IGraphics->ReleasePen(cm,gb_GradientArray[3]);
if((WORD)gb_GradientArray[4] != ~0) IGraphics->ReleasePen(cm,gb_GradientArray[4]);
if((WORD)gb_GradientArray[5] != ~0) IGraphics->ReleasePen(cm,gb_GradientArray[5]);
}

/******************************************************************************/

void MsgLoop()
{
ULONG winsig;
ULONG result, code;
BOOL laufen = TRUE;

/* save Signal Bits of the Window */
IIntuition->GetAttr(WINDOW_SigMask,gb_WindowObj,&winsig);

while(laufen)
{
/* wait for user actions */
const ULONG sigs = IExec->Wait(winsig | SIGBREAKF_CTRL_C);

/* process the received Messages */
while((result = RA_HandleInput(gb_WindowObj,&code)) != WMHI_LASTMSG)
{
/* mask out the Messages part */
switch(result & WMHI_CLASSMASK)
{
/* process Gadget Messages */
case WMHI_GADGETUP:
switch(result & WMHI_GADGETMASK)
{
case GAD_ID_ButtonV:
{
}
break;

case GAD_ID_Button:
{
IDOS->Printf("Button: [released]\n");
}
break;

case GAD_ID_String:
{
STRPTR val;
IIntuition->GetAttr(STRINGA_TextVal,(Object*)gb_StringGad,(ULONG*)&val);
IDOS->Printf("String: [%s]\n",val);
}
break;

case GAD_ID_Integer:
{
ULONG val;
IIntuition->GetAttr(INTEGER_Number,(Object*)gb_IntegerGad,(ULONG*)&val);
IDOS->Printf("Integer: [%ld]\n",val);
}
break;

case GAD_ID_Slider:
{
ULONG val;
IIntuition->GetAttr(SLIDER_Level,(Object*)gb_SliderGad,(ULONG*)&val);
IDOS->Printf("Slieder: [%ld]\n",val);
}
break;

case GAD_ID_Scroller:
{
ULONG val;
IIntuition->GetAttr(SCROLLER_Top,(Object*)gb_ScrollerGad,(ULONG*)&val);
IDOS->Printf("Scroller: [%ld]\n",val);
}
break;

case GAD_ID_Chooser:
{
ULONG val;
IIntuition->GetAttr(CHOOSER_Selected,(Object*)gb_ChooserGad,(ULONG*)&val);
IDOS->Printf("Chooser: [%ld]\n",val);
}
break;

case GAD_ID_Chooser2:
{
ULONG val;
IIntuition->GetAttr(CHOOSER_Selected,(Object*)gb_Chooser2Gad,(ULONG*)&val);
IDOS->Printf("Chooser2: [%ld]\n",val);
}
break;

case GAD_ID_Chooser3:
{
ULONG val;
IIntuition->GetAttr(CHOOSER_Selected,(Object*)gb_Chooser3Gad,(ULONG*)&val);
IDOS->Printf("Chooser3: [%ld]\n",val);
}
break;

case GAD_ID_Checkbox:
{
ULONG val;
IIntuition->GetAttr(GA_Selected,(Object*)gb_CheckboxGad,(ULONG*)&val);
IDOS->Printf("Checkbox: [%s]\n",(val ? "selectet" : "not selected"));
}
break;

case GAD_ID_Radio:
{
ULONG val;
IIntuition->GetAttr(RADIOBUTTON_Selected,(Object*)gb_RadioGad,(ULONG*)&val);
IDOS->Printf("Radio: [%ld]\n",val);
}
break;

case GAD_ID_Listbrowser:
{
//ULONG action, column;
struct Node *node;
//IIntuition->GetAttr(LISTBROWSER_RelEvent,(Object*)gb_WordlistGad,(ULONG*)&action);
//IIntuition->GetAttr(LISTBROWSER_RelColumn,(Object*)gb_WordlistGad,(ULONG*)&column);
IIntuition->GetAttr(LISTBROWSER_SelectedNode,(Object*)gb_ListbrowserGad,(ULONG*)&node);
//struct UserDictEntry *ude = LBNode2UserDictNode(node);
IDOS->Printf("Listview: [%ld]\n",node->ln_Pri);
}
break;

case GAD_ID_Palette:
{
ULONG val;
IIntuition->GetAttr(PALETTE_Colour,(Object*)gb_PaletteGad,(ULONG*)&val);
IDOS->Printf("Palette: [%ld]\n",val);
}
break;

case GAD_ID_File:
{
STRPTR val;
ULONG res = gfRequestFile((Object *)gb_FileGad,gb_Win);
IIntuition->GetAttr(GETFILE_FullFile,(Object*)gb_FileGad,(ULONG*)&val);
if(res) IDOS->Printf("File: [%s]\n",val);
}
break;

case GAD_ID_Font:
{
struct TextAttr *val;
ULONG res = gfRequestFont((Object *)gb_FontGad,gb_Win);
IIntuition->GetAttr(GETFONT_TextAttr,(Object*)gb_FontGad,(ULONG*)&val);
if(res) IDOS->Printf("Font: [%s %ld]\n",val->ta_Name,val->ta_YSize);
}
break;

case GAD_ID_Screenmode:
{
ULONG id, width, height, depth;
ULONG res = RequestScreenMode((Object *)gb_ScreenmodeGad,gb_Win);
IIntuition->GetAttr(GETSCREENMODE_DisplayID,(Object*)gb_ScreenmodeGad,(ULONG*)&id);
IIntuition->GetAttr(GETSCREENMODE_DisplayWidth,(Object*)gb_ScreenmodeGad,(ULONG*)&width);
IIntuition->GetAttr(GETSCREENMODE_DisplayHeight,(Object*)gb_ScreenmodeGad,(ULONG*)&height);
IIntuition->GetAttr(GETSCREENMODE_DisplayDepth,(Object*)gb_ScreenmodeGad,(ULONG*)&depth);
if(res) IDOS->Printf("Screenmode: [$%lx %ld x %ld x %ld]\n",id,width,height,depth);
}
break;

case GAD_ID_Color:
{
ULONG val;
ULONG res = RequestColor((Object *)gb_ColorGad,gb_Win);
IIntuition->GetAttr(GETCOLOR_Color,(Object*)gb_ColorGad,(ULONG*)&val);
if(res) IDOS->Printf("Color: [$%08lx]\n",val);
}
break;

case GAD_ID_Fuelgauge:
{
ULONG val;
IIntuition->GetAttr(FUELGAUGE_Level,(Object*)gb_FuelgaugeGad,(ULONG*)&val);
IDOS->Printf("Fuelgauge: [%ld]\n",val);
}
break;

case GAD_ID_Colorwheel:
{
struct ColorWheelRGB val;
IIntuition->GetAttr(WHEEL_RGB,(Object*)gb_ColorwheelGad,(ULONG*)&val);
IDOS->Printf("Colorwheel: [red=%08lx green=%08lx blue=%08lx]\n",val.cw_Red,val.cw_Green,val.cw_Blue);

/* reset the Gradient Slider depending on the new color selection */
struct ViewPort *vp = &gb_Scr->ViewPort;

if((WORD)gb_GradientArray[0] != ~0)
IGraphics->SetRGB32(vp,gb_GradientArray[0],val.cw_Red,val.cw_Green,val.cw_Blue);
if((WORD)gb_GradientArray[1] != ~0)
IGraphics->SetRGB32(vp,gb_GradientArray[1],val.cw_Red/15*12,val.cw_Green/15*12,val.cw_Blue/15*12);
if((WORD)gb_GradientArray[2] != ~0)
IGraphics->SetRGB32(vp,gb_GradientArray[2],val.cw_Red/15*9,val.cw_Green/15*9,val.cw_Blue/15*9);
if((WORD)gb_GradientArray[3] != ~0)
IGraphics->SetRGB32(vp,gb_GradientArray[3],val.cw_Red/15*6,val.cw_Green/15*6,val.cw_Blue/15*6);
if((WORD)gb_GradientArray[4] != ~0)
IGraphics->SetRGB32(vp,gb_GradientArray[4],val.cw_Red/15*3,val.cw_Green/15*3,val.cw_Blue/15*3);
IIntuition->RefreshGadgets(gb_GradientsliderGad,gb_Win,NULL);
}
break;

case GAD_ID_Gradientslider:
{
ULONG val;
IIntuition->GetAttr(GRAD_CurVal,(Object*)gb_GradientsliderGad,(ULONG*)&val);
IDOS->Printf("Gradientslieder: [%ld]\n",val);
}
break;

case GAD_ID_Texteditor:
{
STRPTR val;
val = (STRPTR) IIntuition->DoGadgetMethod(gb_TexteditorGad,gb_Win,NULL,GM_TEXTEDITOR_ExportText,NULL);
if(val) IDOS->Printf("Texteditor: [%s]\n",val);
}
break;

case GAD_ID_Datebrowser:
{
ULONG day, month, year;
IIntuition->GetAttr(DATEBROWSER_Day,(Object*)gb_DatebrowserGad,(ULONG*)&day);
IIntuition->GetAttr(DATEBROWSER_Month,(Object*)gb_DatebrowserGad,(ULONG*)&month);
IIntuition->GetAttr(DATEBROWSER_Year,(Object*)gb_DatebrowserGad,(ULONG*)&year);
IDOS->Printf("Datebrowser: [%ld.%ld.%ld]\n",day,month,year);
}
break;

case GAD_ID_Space:
{
// ULONG mx, my;
// IIntuition->GetAttr(SPACE_MouseX,(Object*)gb_SpaceGad,(ULONG*)&mx);
// IIntuition->GetAttr(SPACE_MouseY,(Object*)gb_SpaceGad,(ULONG*)&my);
// IDOS->Printf("Space: [%ld : %ld]\n",mx,my);
}
break;

case GAD_ID_Page:
{
ULONG val;
IIntuition->GetAttr(PAGE_Current,(Object*)gb_PageGad,(ULONG*)&val);
IDOS->Printf("Page: [%ld]\n",val);
}
break;

case GAD_ID_Clicktab:
{
ULONG val;
IIntuition->GetAttr(CLICKTAB_Current,(Object*)gb_ClicktabGad,(ULONG*)&val);
IDOS->Printf("Clicktab: [%ld]\n",val);
}
break;

}
break;

/* RawKey of pressed key */
case WMHI_RAWKEY:
{
//struct InputEvent *ie;
//IIntuition->GetAttr(WINDOW_InputEvent,gb_WindowObj,(ULONG *)&ie);
// code = result & WMHI_KEYMASK
// qualifier = ie->ie_Qualifier
}
break;

/* ASCII code of pressed key */
case WMHI_MENUPICK:
switch(result & WMHI_MENUMASK)
{
//case MENU_ID_xxx:
// break;
}
break;

/* Window Close Icon clicked */
case WMHI_CLOSEWINDOW:
{
/* Window Close Icon executed */
laufen = FALSE;
}
break;
}
}

/* CTRL-C typed into the Shell or received as signal */
if(sigs & SIGBREAKF_CTRL_C) laufen = FALSE;
}
}

/******************************************************************************/

int main(int argc, char *argv[])
{

if( CreateAll() )
{
MsgLoop();

DestroyAll();
}
else IDOS->Printf("Createing GUI failed !\n");

return 0;
}
</syntaxhighlight>

Here are the support graphics files to go with it: [[Media:allgadgets-gfx.lha|allgadgets-gfx.lha]]

[[File:AF110_allgadgets.png|frame|center]]

Reactor's approach, which you could use to 'click together' graphically a GUI under the Workbench 3.5 and 3.9, hasn't been developed any further. However, as shown in the previous example, you can basically copy the required GUI elements in your own sources with copy & paste.

= ClickTab-Test Example =

Another bonus is "ClickTab-Test" which deals exclusively with the Clicktab gadget. As I already mentioned, you can use it to create tabs. The tabs can in the meantime be dynamically added and deleted again. Moreover, you can use both tags, so all tags have the same width and the tab labeling is not shortened.

<syntaxhighlight lang="C" line>
/* Michael Christoph
* ClickTab-Test.c
*
* gcc ClickTab-Test.c -o ClickTab-Test -l auto
*/

/******************************* INCLUDES *************************************/

#include <exec/types.h>
#include <intuition/gadgetclass.h>
#include <classes/window.h>
#include <classes/requester.h>
#include <reaction/reaction_macros.h>
#include <libraries/gadtools.h>
#include <gadgets/button.h>
#include <gadgets/checkbox.h>
#include <gadgets/string.h>
#include <gadgets/clicktab.h>
#include <gadgets/layout.h>
#include <gadgets/page.h>
#include <images/label.h>

#include <proto/exec.h>
#include <proto/dos.h>
#include <proto/intuition.h>
#include <proto/utility.h>
#include <proto/window.h>
#include <proto/layout.h>
#include <proto/button.h>
#include <proto/label.h>
#include <proto/string.h>
#include <proto/clicktab.h>
#include <proto/checkbox.h>
#include <proto/label.h>

/******************************************************************************/

static const char *version USED = "\0$VER: ClickTab-Test 1.0 (13.02.2009) - (c) Feb.2009 by Meicky-Soft\n";

/******************************************************************************/

enum GADID
{
GAD_ID_Name = 1,
GAD_ID_Add,
GAD_ID_Del,

GAD_ID_Evensize,
GAD_ID_Labeltruncate,

GAD_ID_Clicktab,
};

struct Gadget *gb_NameGad;
struct Gadget *gb_AddGad;
struct Gadget *gb_DelGad;
struct Gadget *gb_EvensizeGad;
struct Gadget *gb_LabeltruncateGad;
struct Gadget *gb_ClicktabGad;
struct Gadget *gb_MainLayout;

#define MAX_CLICKTABS 15
STRPTR gb_ClicktabLabels[MAX_CLICKTABS + 1] = { NULL };

Object *gb_WindowObj;
struct Window *gb_Win;
struct Screen *gb_Scr;

/******************************************************************************/

BOOL CreateGUI()
{
if((gb_ClicktabLabels[0] = (STRPTR) IExec->AllocVecTags(31, AVT_Type, MEMF_SHARED, TAG_END)))
{
IUtility->Strlcpy(gb_ClicktabLabels[0], "_Muster", 30);
}

gb_NameGad = (struct Gadget *) IIntuition->NewObject(IString->STRING_GetClass(),NULL,
GA_ID, GAD_ID_Name,
GA_RelVerify, TRUE,
GA_TabCycle, TRUE,
STRINGA_MaxChars, 30+1,
STRINGA_MinVisible, 30,
TAG_END);

gb_AddGad = (struct Gadget *) IIntuition->NewObject(IButton->BUTTON_GetClass(),NULL,
GA_ID, GAD_ID_Add,
GA_RelVerify, TRUE,
GA_Text, "_Add",
TAG_END);

gb_DelGad = (struct Gadget *) IIntuition->NewObject(IButton->BUTTON_GetClass(),NULL,
GA_ID, GAD_ID_Del,
GA_RelVerify, TRUE,
GA_Text, "_Del",
TAG_END);

gb_EvensizeGad = (struct Gadget *) IIntuition->NewObject(ICheckBox->CHECKBOX_GetClass(),NULL,
GA_ID, GAD_ID_Evensize,
GA_Text, "EvenSize",
GA_RelVerify, TRUE,
CHECKBOX_TextPlace, PLACETEXT_RIGHT,
CHECKBOX_Checked, FALSE,
TAG_END);

gb_LabeltruncateGad = (struct Gadget *) IIntuition->NewObject(ICheckBox->CHECKBOX_GetClass(),NULL,
GA_ID, GAD_ID_Labeltruncate,
GA_Text, "LabelTruncate",
GA_RelVerify, TRUE,
CHECKBOX_TextPlace, PLACETEXT_RIGHT,
CHECKBOX_Checked, TRUE,
TAG_END);

gb_ClicktabGad = (struct Gadget *) IIntuition->NewObject(IClickTab->CLICKTAB_GetClass(),NULL,
GA_ID, GAD_ID_Clicktab,
GA_Text, &gb_ClicktabLabels,
GA_RelVerify, TRUE,
CLICKTAB_EvenSize, FALSE,
CLICKTAB_LabelTruncate, TRUE,
//CLICKTAB_PageGroup, gb_PagesLayout,
TAG_END);

gb_MainLayout = (struct Gadget *) IIntuition->NewObject(ILayout->LAYOUT_GetClass(),NULL,
LAYOUT_Orientation, LAYOUT_VERTICAL,
LAYOUT_SpaceOuter, TRUE,
LAYOUT_SpaceInner, TRUE,

LAYOUT_AddChild, gb_NameGad,
LAYOUT_AddChild, gb_AddGad,
LAYOUT_AddChild, gb_DelGad,
LAYOUT_AddChild, gb_EvensizeGad,
LAYOUT_AddChild, gb_LabeltruncateGad,
LAYOUT_AddChild, gb_ClicktabGad,

TAG_END);

if(gb_MainLayout)
{

/* Create the window object */
if((gb_WindowObj = (Object *) IIntuition->NewObject(IWindow->WINDOW_GetClass(),NULL,
WA_IDCMP, IDCMP_GADGETUP |
IDCMP_VANILLAKEY |
IDCMP_CLOSEWINDOW,
WA_SizeGadget, TRUE,
WA_DepthGadget, TRUE,
WA_DragBar, TRUE,
WA_Activate, TRUE,
WA_Title, "Variable Number of Tabs",
WA_InnerWidth, 150,
WA_InnerHeight, 100,
WA_AutoAdjust, TRUE,
WA_CloseGadget, TRUE,
WINDOW_ParentGroup, gb_MainLayout,
TAG_END)))
{
/* Everything created successfully */

/* The window can be opened now */
gb_Win = RA_OpenWindow(gb_WindowObj);
}
}

return ( gb_Win ? TRUE : FALSE );
}

/******************************************************************************/

void FreeGUI()
{
RA_CloseWindow(gb_WindowObj);
IIntuition->DisposeObject(gb_WindowObj);

ULONG i;
for(i=0; i<MAX_CLICKTABS; i++)
{
if(gb_ClicktabLabels[i]) IExec->FreeVec(gb_ClicktabLabels[i]);
}
}

/******************************************************************************/

void MsgLoop()
{
ULONG winsig;
ULONG result, code;
BOOL running = TRUE;

/* Get the window signal bit mask */
IIntuition->GetAttr(WINDOW_SigMask, gb_WindowObj, &winsig);

while(running)
{
/* Wait for user actions */
const ULONG sigs = IExec->Wait(winsig | SIGBREAKF_CTRL_C);

/* Process all messages */
while((result = RA_HandleInput(gb_WindowObj, &code)) != WMHI_LASTMSG)
{
/* Mask out the message class ! */
switch(result & WMHI_CLASSMASK)
{
/* Handle gadget message */
case WMHI_GADGETUP:
switch(result & WMHI_GADGETMASK)
{
case GAD_ID_Name:
{
/* Update caption */
ULONG val;
IIntuition->GetAttr(CLICKTAB_Current,(Object*)gb_ClicktabGad,(ULONG*)&val);
STRPTR name;
IIntuition->GetAttr(STRINGA_TextVal,(Object*)gb_NameGad,(ULONG*)&name);
IUtility->Strlcpy(gb_ClicktabLabels[val],name,30);
IDOS->Printf("Update CT [%ld] <%s>\n",val,name);
IIntuition->RefreshSetGadgetAttrs(gb_ClicktabGad,gb_Win,NULL, GA_Text,gb_ClicktabLabels, TAG_END);
}
break;

case GAD_ID_Add:
{
/* Add a new tab */
ULONG max;
IIntuition->GetAttr(CLICKTAB_Total,(Object*)gb_ClicktabGad,(ULONG*)&max);
if(max < MAX_CLICKTABS-1)
{
STRPTR name;
IIntuition->GetAttr(STRINGA_TextVal,(Object*)gb_NameGad,(ULONG*)&name);
if(name[0])
{
IDOS->Printf("Add CT [%ld] <%s>\n",max,name);
if((gb_ClicktabLabels[max] = (STRPTR) IExec->AllocVecTags(31,AVT_Type,MEMF_SHARED,TAG_END)))
{
IUtility->Strlcpy(gb_ClicktabLabels[max],name,30);
}
else IDOS->Printf("out of memory\n");
IIntuition->RefreshSetGadgetAttrs(gb_ClicktabGad,gb_Win,NULL, GA_Text,gb_ClicktabLabels, TAG_END);
}
else IDOS->Printf("Name for tab required\n");
}
else IDOS->Printf("No more tabs possible\n");
}
break;

case GAD_ID_Del:
{
/* Erase the current tab */
ULONG val, i;
IIntuition->GetAttr(CLICKTAB_Current,(Object*)gb_ClicktabGad,(ULONG*)&val);
IDOS->Printf("Del CT [%ld] <%s>\n",val,gb_ClicktabLabels[val]);
IExec->FreeVec(gb_ClicktabLabels[val]);
for(i=val; i<MAX_CLICKTABS; i++)
{
gb_ClicktabLabels[i] = gb_ClicktabLabels[i + 1];
}
IIntuition->RefreshSetGadgetAttrs(gb_ClicktabGad,gb_Win,NULL, GA_Text,gb_ClicktabLabels, TAG_END);
}
break;

case GAD_ID_Evensize:
{
/* All tabs have the same width */
/* V53: WORKS ONLY DURING INITIALIZATION ! */
ULONG val;
IIntuition->GetAttr(GA_Selected,(Object*)gb_EvensizeGad,(ULONG*)&val);
IIntuition->RefreshSetGadgetAttrs(gb_ClicktabGad,gb_Win,NULL, CLICKTAB_EvenSize,val, TAG_END);
/* !!! MUST DO to layout the changed tag !!! */
IIntuition->RefreshSetGadgetAttrs(gb_ClicktabGad,gb_Win,NULL, GA_Text,gb_ClicktabLabels, TAG_END);
}
break;

case GAD_ID_Labeltruncate:
{
/* Truncates label if necessary */
/* V53: WORKS ONLY DURING INITIALIZATION ! */
ULONG val;
IIntuition->GetAttr(GA_Selected,(Object*)gb_LabeltruncateGad,(ULONG*)&val);
IIntuition->RefreshSetGadgetAttrs(gb_ClicktabGad,gb_Win,NULL, CLICKTAB_LabelTruncate,val, TAG_END);
/* !!! MUST DO to layout the changed tag !!! */
IIntuition->RefreshSetGadgetAttrs(gb_ClicktabGad,gb_Win,NULL, GA_Text,gb_ClicktabLabels, TAG_END);
}
break;

case GAD_ID_Clicktab:
{
/* Use tab name for editing */
ULONG val;
IIntuition->GetAttr(CLICKTAB_Current,(Object*)gb_ClicktabGad, (ULONG*)&val);
IDOS->Printf("Update STR [%ld] <%s>\n", val, gb_ClicktabLabels[val]);
IIntuition->SetGadgetAttrs(gb_NameGad,gb_Win,NULL, STRINGA_TextVal,gb_ClicktabLabels[val], TAG_END);
}
break;
}
break;

case WMHI_VANILLAKEY:
{
const LONG code = result & WMHI_KEYMASK;

if(code == ' ')
{
IDOS->Printf("---- Label List:\n");
ULONG i;
for(i=0; i<MAX_CLICKTABS; i++)
{
if(gb_ClicktabLabels[i]) IDOS->Printf("[%ld] <%s> $%lx\n",i,gb_ClicktabLabels[i],gb_ClicktabLabels[i]);
}
IDOS->Printf("----------------\n");
}
}
break;

/* Window close gadget clicked */
case WMHI_CLOSEWINDOW:
{
running = FALSE;
}
break;
}
}

/* CTRL-C typed in the shell or via a signal */
if(sigs & SIGBREAKF_CTRL_C) laufen = FALSE;
}
}

/******************************************************************************/

int main(int argc, char *argv[])
{
/* AmigaOS 4.1 is required */
if(SysBase->lib_Version < 53)
{
IDOS->Printf("Program requires AmigaOS 4.1\n");
return( 20 );
}

if( CreateGUI() )
{
MsgLoop();

FreeGUI();
}
else IDOS->Printf("GUI creation failed !\n");

return 0;
}
</syntaxhighlight>

[[File:AF110_clicktab-test.png|frame|center]]

Irrespective of the programing side, the user can influence the appearance and partly the behaviour of gadgets and windows system-wide using the Prefs options. Angular or rounded edges, the thickness of the window frame, and also the complex colour scheme are all widely configurable. There are ready-made styles so everything works perfectly in the visual sense.

= Authors =

Written by Michael Christoph and Aleksandra Schmidt-Pendarovska 
Copyright (c) 2013 Michael Christoph

ANIM IFF CEL Animations

2025-01-26T19:30:52Z

Costel Mincea: Text replacement - "<syntaxhighlight>" to "<syntaxhighlight lang="C" line>"

= ANIM =

An IFF Format For CEL Animations

Revision date: 6 June 2013

Originally prepared by:
: SPARTA Inc.
: 23041 de la Carlota
: Laguna Hills, Calif 92653
: (714) 768-8161
: Contact: Gary Bonham

Also by:
: Aegis Development Co.
: 2115 Pico Blvd.
: Santa Monica, Calif 90405
: (213) 392-9972

= Introduction =

The ANIM IFF format was developed at Sparta originally for the production of animated video sequences on the Amiga computer. The intent was to be able to store, and play back, sequences of frames and to minimize both the storage space on disk (through compression) and playback time (through efficient decompression algorithms). It was desired to maintain maximum compatibility with existing IFF formats and to be able to display the initial frame as a normal still IFF picture.

Several compression schemes have been introduced in the ANIM format. Most of these are strictly of historical interest as the only one currently being placed in new code is the vertical run length encoded byte encoding developed by Jim Kent.

== ANIM Format Overview ==

The general philosophy of ANIMs is to present the initial frame as a normal, run-length-encoded, IFF picture. Subsequent
frames are then described by listing only their differences from a previous frame. Normally, the "previous" frame is two frames back as that is the frame remaining in the hidden screen buffer when double-buffering is used. To better understand this, suppose one has two screens, called A and B, and the ability to instantly switch the display from one to the other. The normal playback mode is to load the initial frame into A and duplicate it into B. Then frame A is displayed on the screen. Then the differences for frame 2 are used to alter screen B and it is displayed. Then the differences for frame 3 are used to alter screen A and it is displayed, and so on. Note that frame 2 is stored as differences from frame 1, but all other frames are stored as differences from two frames back.

ANIM is an IFF FORM and its basic format is as follows (this assumes the reader has a basic understanding of IFF format
files):
FORM ANIM
. FORM ILBM first frame
. . BMHD normal type IFF data
. . ANHD optional animation header
chunk for timing of 1st frame.
. . CMAP
. . BODY
. FORM ILBM frame 2
. . ANHD animation header chunk
. . DLTA delta mode data
. FORM ILBM frame 3
. . ANHD
. . DLTA
...

The initial FORM ILBM can contain all the normal ILBM chunks, such as CRNG, etc. The BODY will normally be a standard
run-length-encoded data chunk (but may be any other legal compression mode as indicated by the BMHD). If desired, an ANHD
chunk can appear here to provide timing data for the first frame. If it is here, the operation field should be =0.

The subsequent FORMs ILBM contain an ANHD, instead of a BMHD, which duplicates some of BMHD and has additional parameters
pertaining to the animation frame. The DLTA chunk contains the data for the delta compression modes. If the older XOR compression mode is used, then a BODY chunk will be here. In addition, other chunks may be placed in each of these as deemed necessary (and as code is placed in player programs to utilize them). A good example would be CMAP chunks to alter the color palette. A basic assumption in ANIMs is that the size of the bitmap, and the display mode (e.g. HAM) will not change through the animation. Take care when playing an ANIM that if a CMAP occurs with a frame, then the change must be applied to both buffers.

Note that the DLTA chunks are not interleaved bitmap representations, thus the use of the ILBM form is inappropriate for these frames. However, this inconsistency was not noted until there were a number of commercial products either released or close to release which generated/played this format. Therefore, this is probably an inconsistency which will have to stay with us.

== Recording ANIMs ==

To record an ANIM will require three bitmaps - one for creation of the next frame, and two more for a "history" of the previous two frames for performing the compression calculations (e.g. the delta mode calculations).

There are five frame-to-frame compression methods currently defined. The first three are mainly for historical interest.
The product Aegis VideoScape 3D utilizes the third method in version 1.0, but switched to method 5 on 2.0. This is the only instance known of a commercial product generating ANIMs of any of the first three methods. The fourth method is a general short or long word compression scheme which has several options including whether the compression is horizontal or vertical, and whether or not it is XOR format. This offers a choice to the user for the optimization of file size and/or playback speed. The fifth method is the byte vertical run length encoding as designed by Jim Kent. Do not confuse this with Jim's RIFF file format which is different than ANIM. Here we utilized his compression/decompression routines within the ANIM file structure.

The following paragraphs give a general outline of each of the methods of compression currently included in this spec.

=== XOR mode ===

This mode is the original and is included here for historical interest. In general, the delta modes are far superior. The creation of XOR mode is quite simple. One simply performs an exclusive-or (XOR) between all corresponding bytes of the new frame and two frames back. This results in a new bitmap with 0 bits wherever the two frames were identical, and 1 bits where they are different. Then this new bitmap is saved using run-length-encoding. A major obstacle of this mode is in the time consumed in performing the XOR upon reconstructing the image.

=== Long Delta mode ===

This mode stores the actual new frame long-words which are different, along with the offset in the bitmap. The exact format is shown and discussed in section 2 below. Each plane is handled separately, with no data being saved if no changes take place in a given plane. Strings of 2 or more long-words in a row which change can be run together so offsets do not have to be saved for each one.

Constructing this data chunk usually consists of having a buffer to hold the data, and calculating the data as one compares the new frame, long-word by long-word, with two frames back.

=== Short Delta mode ===

This mode is identical to the Long Delta mode except that short-words are saved instead of long-words. In most instances, this mode results in a smaller DLTA chunk. The Long Delta mode is mainly of interest in improving the playback speed when used on a 32-bit 68020 Turbo Amiga.

=== General Delta mode ===

The above two delta compression modes were hastily put together. This mode was an attempt to provide a well-thought-out delta compression scheme. Options provide for both short and long word compression, either vertical or horizontal compression, XOR mode (which permits reverse playback), etc. About the time this was being finalized, the fifth mode, below, was developed by Jim Kent. In practice the short-vertical-run-length-encoded deltas in this mode play back faster than the fifth mode (which is in essence a byte-vertical-run-length-encoded delta mode) but does not compress as well - especially for very noisy data such as digitized images. In most cases, playback speed not being terrifically slower, the better compression (sometimes 2x) is preferable due to limited storage media in most machines.

Details on this method are contained in section 2.2.2 below.

=== Byte Vertical Compression ===

This method does not offer the many options that method 4 offers, but is very successful at producing decent compression even for very noisy data such as digitized images. The method was devised by Jim Kent and is utilized in his RIFF file format which is different than the ANIM format. The description of this method in this document is taken from Jim's writings. Further, he has released both compression and decompression code to public domain.

Details on this method are contained in section 2.2.3 below.

== Playing ANIMs ==

Playback of ANIMs will usually require two buffers, as mentioned above, and double-buffering between them. The frame data from the ANIM file is used to modify the hidden frame to the next frame to be shown. When using the XOR mode, the usual run-length-decoding routine can be easily modified to do the exclusive-or operation required. Note that runs of zero bytes,
which will be very common, can be ignored, as an exclusive or of any byte value to a byte of zero will not alter the original byte value.

The general procedure, for all compression techniques, is to first decode the initial ILBM picture into the hidden buffer and double-buffer it into view. Then this picture is copied to the other (now hidden) buffer. At this point each frame is displayed with the same procedure. The next frame is formed in the hidden buffer by applying the DLTA data (or the XOR data from the BODY chunk in the case of the first XOR method) and the new frame is double-buffered into view. This process continues to the end of the file.

A master colormap should be kept for the entire ANIM which would be initially set from the CMAP chunk in the initial ILBM. This colormap should be used for each frame. If a CMAP chunk appears in one of the frames, then this master colormap is updated and the new colormap applies to all frames until the occurrance of another CMAP chunk.

Looping ANIMs may be constructed by simply making the last two frames identical to the first two. Since the first two frames are special cases (the first being a normal ILBM and the second being a delta from the first) one can continually loop the animation by repeating from frame three. In this case the delta for creating frame three will modify the next to the last frame which is in the hidden buffer (which is identical to the first frame), and the delta for creating frame four will modify the last frame which is identical to the second frame.

Multi-File ANIMs are also supported so long as the first two frames of a subsequent file are identical to the last two frames of the preceeding file. Upon reading subsequent files, the ILBMs for the first two frames are simply ignored, and the remaining frames are simply appended to the preceding frames. This permits splitting ANIMs across multiple floppies and also permits playing each section independently and/or editing it independent of the rest of the ANIM.

Timing of ANIM playback is easily achieved using the vertical blank interrupt of the Amiga. There is an example of setting up such a timer in the SDK. Be sure to remember the timer value when a frame is flipped up, so the next frame can be flipped up relative to that time. This will make the playback independent of how long it takes to decompress a frame (so long as there is enough time between frames to accomplish this decompression).

= Chunk Formats =

== ANHD Chunk ==

The ANHD chunk consists of the following data structure:

; UBYTE operation
: The compression method:
:{| class="wikitable"
| 0 || set directly (normal ILBM BODY)
|-
| 1 || XOR ILBM mode
|-
| 2 || Long Delta mode
|-
| 3 || Short Delta mode
|-
| 4 || Generalized short/long Delta mode
|-
| 5 || Byte Vertical Delta mode
|-
| 6 || Stereo op 5 (third party)
|-
| 7 || short/long Vertical Delta mode
|-
| 74 (ASCII 'J') || reserved for Eric Graham's compression technique (details to be released later).
|}

; UBYTE mask
: (XOR mode only - plane mask where each bit is set =1 if there is data and =0 if not.)

; UWORD w,h
: (XOR mode only - width and height of the area represented by the BODY to eliminate unnecessary unchanged data)

; WORD x,y
: (XOR mode only - position of rectangular area represented by the BODY)

; ULONG abstime
: (currently unused - timing for a frame relative to the time the first frame was displayed - in jiffies (1/60 sec))

; ULONG reltime
: (timing for frame relative to time previous frame was displayed - in jiffies (1/60 sec))

; UBYTE interleave
: (unused so far - indicates how may frames back this data is to modify. =0 defaults to indicate two frames back (for double buffering). =n indicates n frames back. The main intent here is to allow values of =1 for special applications where frame data would modify the immediately previous frame)

; UBYTE pad0
: Pad byte, not used at present.

; ULONG bits
: 32 option bits used by options=4 and 5. At present only 6 are identified, but the rest are set =0 so they can be used to implement future ideas. These are defined for option 4 only at this point. It is recommended that all bits be set =0 for option 5 and that any bit settings used in the future (such as for XOR mode) be compatible with the option 4 bit settings. Player code should check undefined bits in options 4 and 5 to assure they are zero.

: The six bits for current use are:
:{| class="wikitable"
! bit # !! set =0 !! set =1
|-
| 0 || short data || long data
|-
| 1 || set || XOR
|-
| 2 || separate info for each plane || one info list for all planes
|-
| 3 || not RLC || RLC (run length coded)
|-
| 4 || horizontal || vertical
|-
| 5 || short info offsets || long info offsets
|}

; UBYTE pad[16]
: This is a pad for future use for future compression modes.

== DLTA Chunk ==

This chunk is the basic data chunk used to hold delta compression data. The format of the data will be dependent upon the exact compression format selected. At present there are two basic formats for the overall structure of this chunk.

=== Format for methods 2 & 3 ===

This chunk is a basic data chunk used to hold the delta compression data. The minimum size of this chunk is 32 bytes as the first 8 long-words are byte pointers into the chunk for the data for each of up to 8 bit planes. The pointer for the
plane data starting immediately following these 8 pointers will have a value of 32 as the data starts in the 33-rd byte of the chunk (index value of 32 due to zero-base indexing).

The data for a given plane consists of groups of data words. In
Long Delta mode, these groups consist of both short and long
words - short words for offsets and numbers, and long words for
the actual data. In Short Delta mode, the groups are identical
except data words are also shorts so all data is short words.
Each group consists of a starting word which is an offset. If
the offset is positive then it indicates the increment in long
or short words (whichever is appropriate) through the bit plane.
In other words, if you were reconstructing the plane, you would
start a pointer (to shorts or longs depending on the mode) to
point to the first word of the bit plane. Then the offset would
be added to it and the following data word would be placed at
that position. Then the next offset would be added to the
pointer and the following data word would be placed at that
position. And so on... The data terminates with an offset
equal to 0xFFFF.

A second interpretation is given if the offset is negative. In
that case, the absolute value is the offset+2. Then the
following short-word indicates the number of data words that
follow. Following that is the indicated number of contiguous
data words (longs or shorts depending on mode) which are to
be placed in contiguous locations of the bit plane.

If there are no changed words in a given plane, then the pointer
in the first 32 bytes of the chunk is =0.

=== Format for method 4 ===

The DLTA chunk is modified slightly to have 16 long pointers at
the start. The first 8 are as before - pointers to the start of
the data for each of the bit planes (up to a theoretical max of 8
planes). The next 8 are pointers to the start of the offset/numbers
data list. If there is only one list of offset/numbers for all
planes, then the pointer to that list is repeated in all positions
so the playback code need not even be aware of it. In fact, one
could get fancy and have some bit planes share lists while others
have different lists, or no lists (the problems in these schemes
lie in the generation, not in the playback).

The best way to show the use of this format is in a sample playback
routine.

<syntaxhighlight lang="C" line>
SetDLTAshort(bm,deltaword)
struct BitMap *bm;
WORD *deltaword;
{
int i;
LONG *deltadata;
WORD *ptr,*planeptr;
register int s,size,nw;
register WORD *data,*dest;

deltadata = (LONG *)deltaword;
nw = bm->BytesPerRow >>1;

for (i=0;i<bm->Depth;i++) {
planeptr = (WORD *)(bm->Planes[i]);
data = deltaword + deltadata[i];
ptr = deltaword + deltadata[i+8];
while (*ptr != 0xFFFF) {
dest = planeptr + *ptr++;
size = *ptr++;
if (size < 0) {
for (s=size;s<0;s++) {
*dest = *data;
dest += nw;
}
data++;
}
else {
for (s=0;s<size;s++) {
*dest = *data++;
dest += nw;
}
}
}
}
return(0);
}
</syntaxhighlight>

The above routine is for short word vertical compression with
run length compression. The most efficient way to support
the various options is to replicate this routine and make
alterations for, say, long word or XOR. The variable nw
indicates the number of words to skip to go down the vertical
column. This one routine could easily handle horizontal
compression by simply setting nw=1. For ultimate playback
speed, the core, at least, of this routine should be coded in
assembly language.

=== Format for method 5 ===

In this method the same 16 pointers are used as in option 4.
The first 8 are pointers to the data for up to 8 planes.
The second set of 8 are not used but were retained for several
reasons. First to be somewhat compatible with code for option
4 (although this has not proven to be of any benefit) and
second, to allow extending the format for more bit planes (code
has been written for up to 12 planes).

Compression/decompression is performed on a plane-by-plane basis.
For each plane, compression can be handled by the skip.c code
(provided Public Domain by Jim Kent) and decompression can be
handled by unvscomp.asm (also provided Public Domain by Jim Kent).

Compression/decompression is performed on a plane-by-plane basis.
The following description of the method is taken directly from
Jim Kent's code with minor re-wording. Please refer to Jim's
code (skip.c and unvscomp.asm) for more details:

Each column of the bit plane is compressed separately.
A 320x200 bit plane would have 40 columns of 200 bytes each.
Each column starts with an op-count followed by a number
of ops. If the op-count is zero, that's OK, it just means
there's no change in this column from the last frame.
The ops are of three classes, and followed by a varying
amount of data depending on which class:

# Skip ops - this is a byte with the hi bit clear that says how many rows to move the "dest" pointer forward, i.e. to skip. It is non-zero.
# Uniq ops - this is a byte with the hi bit set. The hi bit is masked down and the remainder is a count of the number of bytes of data to copy literally. It's of course followed by the data to copy.
# Same ops - this is a 0 byte followed by a count byte, followed by a byte value to repeat count times.

Do bear in mind that the data is compressed vertically rather
than horizontally, so to get to the next byte in the destination
we add the number of bytes per row instead of one!

= ANIM.op6 =

== OpCode 6 Addition to ANIM IFF Format ==

Stereo (3D) Animations

Submitted by William J. Coldwell (08/23/91)

Revision Date: 20.8.91

Prepared by:
: Cryogenic Software
: 13045 SouthEast Stark St
: Suite 144
: Portland, OR 97233-1557
: Contact: William J. Coldwell

: Voice: (503) 254-8147 (11a-4p PDT/PST)
: Data: (503) 257-4823 (EMail to SYSOP)
: Portal: Cryogenic
: UUCP: uunet!m2xenix!percy!cryo!billc
: Internet: billc@cryo.rain.com

== Introduction ==

In 1989, we added support into one of our commercial products to
support the Haitex X-Specs glasses. This documentation will not
go into a detailed description of this product. Contact Haitex
for more information concerning the hardware:

: Haitex Resources, Inc.
: Post Office Box 20609
: Charleston, SC 29413
: Voice: (803) 881-7518
: Fax: (803) 881-7522
: Contact: Shawn Glisson

We found that there was not a supported way to display stereo
animations using the current IFF ANIM OpCode 5 specification.

Cryogenic supported OpCode 6 as an internal format in our
commercial programs (see below) and provided Public Domain
players. It is our intention at this time, to release this
format to other developers wishing to support stereo animations
using this OpCode.

When we first started this project, the current Amiga machines
had a 512K of CHIP RAM maximum. This caused some memory problems
with some of the higher resolution stereo animations, since the
Quad Buffers were in CHIP RAM for our players. It was our
intention to attempt to do some memory magic to require only
two of the four bitmaps to be in CHIP RAM at one time. It was
our feeling that this would have caused the animations to slow
down, due to data swapping that may or may not have needed to
be done. By the end of 1989, all development had stopped on
OpCode 6. This left all buffers in CHIP, and the format has
remained the same since then.

== OpCode 6 Additions to OpCode 5 ==

The format is exactly the same as OpCode 5 but is QUAD buffered
instead of DOUBLE buffered. This allows the player to show 2
screens at one time for the X-Specs Glasses. Each picture MUST
be viewed for 1/60th of a second, therefore to see a 3-D Picture
the viewer can only play ANIMs at 30 frames per second.
(2 pictures = 1 frame).

The IFF file is stored exactly the same except that instead
of having each DLTA (delta) modify bitmap two frames back, it
modifies the bitmap four frames back.

Example:

------------------------
| |
| BMHD |
| |
------------------------
| DLTA (1) |
------------------------
| DLTA (2) |
------------------------
| DLTA (3) |
------------------------
| DLTA (4) |
------------------------
| DLTA (5) |
------------------------
| DLTA (6) |
------------------------
.
.
.
------------------------
| DLTA (x) |
------------------------

== Playing OpCode 6 ANIMs ==

Four bitmaps are allocated. Bitmaps 1 and 3 are the left views,
and bitmaps 2 and 4 are the right.

The First bitmap is gets its image from the bitmap in the file
(BMHD). The Second bitmap is a copy of the first with DLTA (1)
performed on it. The Third Bitmap is a copy of the first with
DLTA (2) performed on it. The Fourth Bitmap is a copy of the
first with DLTA (3) performed on it.

We now have the first two 3-D Pictures:

One in bitmaps 1 and 2 and the other in bitmaps 3 and 4

DLTA (6) is used to create the third left view from bitmap 1.

DLTA (7) is used to create the third right view from bitmap 2.

DLTA (8) is used to create the forth left view from bitmap 3.

DLTA (9) is used to create the forth right view from bitmap 4.

NOTE: This technique requires 4 Loop frames at the end to
perform looping.

== Chunk Changes ==

In the ANHDChunk structure the only differences between OpCode
5 and OpCode 6 are the _Operation_ field which should be set to
6, and the _Interleave_ field which should be set to 4.

== Supporting Software ==

* 3-D Professional 1.0+ (Progressive Peripherals and Software)
* View 1.7 and above (Public Domain) on a Fred Fish Disk
* MSA: Make Stereo ANIM (internal) Available upon request.
* PSA: Play Stereo ANIM (internal) Available upon request.

= ANIM.op7 =

== Appendix for Anim7 Formats ==

Anim7 (July 92) by:
: Wolfgang Hofer
: A-2722 Winzendorf
: Wr. Neustaedterstr. 140

Anim method 7 is designed for maximum playback speed and acceptable packing rates (packing usually not as good as method 5, but more efficient than methods 1 -- 4)

Method 7 was not originally in the IFF specification but supported by the Public Domain Programs AAP/AAC.

== Chunk Sequence ==

Method 7 Anims should use the same Chunk Sequence as methods 1..5. Alternatively the first frame may have a DLTA chunk instead of the BODY chunk.

In that case the DLTA is the difference to a 'black frame'. A player has to clear all bit planes of the first bitmap to zero, and then call his DLTA unpack routines for this frame.

FORM ANIM
. FORM ILBM first frame
. . BMHD normal type IFF data
. . ANHD optional animation header chunk for timing of 1st frame.
. . CMAP
. . { BODY | DLTA } full picture or difference to 'black frame'
. FORM ILBM frame 2
. . ANHD animation header chunk
. . DLTA delta mode data
. . [CMAP]
. FORM ILBM frame 3
. . ANHD
. . DLTA
. . [CMAP]
...

The initial FORM ILBM can contain all the normal ILBM chunks, such as CRNG, etc. The BODY will normally be a standard
run-length-encoded data chunk (but may be any other legal compression mode as indicated by the BMHD). If desired, an ANHD chunk can appear here to provide timing data for the first frame. If it is here, the operation field should be =0.

If the initial FORM ILBM uses a DLTA chunk, the ANHD chunk must appear, and the operation field must be set to the according anim method.

== Chunk Formats ==

=== ANHD Chunk for method 7 ===

The ANHD chunk consists of the following data structure:

UBYTE operation The compression method=7 short/long Vertical Delta mode
UBYTE mask unused
UWORD w,h unused
WORD x,y unused
ULONG abstime unused
ULONG reltime (timing for frame relative to time previous frame was displayed - in jiffies (1/60 sec))
UBYTE interleave = 0 (see ANHD description above)
UBYTE pad0 unused
ULONG bits 32 option bits used by method=4 and 5.
method 7 uses only bit #0

bit # set =0 set =1
===============================================
0 short data long data

UBYTE pad[16] unused

=== DLTA Chunk ===

The DLTA Chunks of method 7 consists of
* 8 pointers to opcode lists
* 8 pointers to data lists
* data lists (long/short)
* opcode lists (bytes)

In this method the DLTA Chunk begins with 16 pointers. The first 8 longwords are pointers to the opcode lists for up to 8 planes. The second set of 8 longwords are pointers to the corresponding data lists. If there are less than 8 Planes all unused pointers are set to zero.

Compression/decompression is performed on a plane-by-plane basis. The following description of the method is similar to
Jim Kent's method 5, except that data is stored in a separated data list (long or short, depending on bit#0 of the ANHD bits) and doesn't follow immediate after the opcode.

In method 7 the bit plane is split into vertical columns. Each column of the bit plane is compressed separately. A 320x200 bitplane would have 20 columns of 200 short datas each. (or 10 columns of 200 long datas)

Each column starts with an op-count followed by a number of ops. If the op-count is zero, that's OK, it just means
there's no change in this column from the last frame. The ops are of three classes. The ops refer to a varying
amount of data (to fetch from the corresponding data list) depending on which class:

# Skip ops - this is a byte with the hi bit clear that says how many rows to move the "dest" pointer forward, i.e. to skip. It is non-zero. Skip ops have no corresponding data-items in the data list.
# Uniq ops - this is a byte with the hi bit set. The hi bit is masked down and the remainder is a count of the number of data to copy literally from the data list to the "dest" pointer column. (Each data item to the next destination row) Data items may be long or short organized.
# Same ops - this is a 0 byte followed by a count byte. The count byte says how many rows of the current column are to be set to the same data-item. the data-item (long or short) is fetched from the data list.

{{Note|text=Do bear in mind that the data is compressed vertically rather than horizontally, so to get to the next address in the destination we have to add the number of bytes per row instead of 2 (or 4)!}}

= ANIM.op8 =

== Appendix for Anim8 ==

Joe Porkka 10-jan-92

Anim method 8 is designed for maximum playback speed and acceptable packing rates (packing usually not as good as method 5, but more efficient than methods 1 -- 4). In addition, it is easier to convert existing Anim5 code to support Anim8 than Anim7.

== Chunk Sequence ==

Method 8 Anims should use the same Chunk Sequence as methods 1..5. Alternatively the first frame may have a DLTA chunk instead of the BODY chunk.

In that case the DLTA is the difference to a 'black frame'. A player has to clear all bit planes of the first bitmap to zero, and then call his DLTA unpack routines for this frame. The same rules about copying the first frame into both frame buffers still applies in this case.

FORM ANIM
. FORM ILBM first frame
. . BMHD normal type IFF data
. . ANHD optional animation header chunk for timing of 1st frame.
. . CMAP
. . { BODY | DLTA } full picture or difference to 'black frame'
. FORM ILBM frame 2
. . ANHD animation header chunk
. . DLTA delta mode data
. . [CMAP]
. FORM ILBM frame 3
. . ANHD
. . DLTA
. . [CMAP]
...

The initial FORM ILBM can contain all the normal ILBM chunks, such as CRNG, etc. The BODY will normally be a standard run-length-encoded data chunk (but may be any other legal compression mode as indicated by the BMHD). If desired, an ANHD chunk can appear here to provide timing data for the first frame. If it is here, the operation field should be =0.

If the initial FORM ILBM uses a DLTA chunk, the ANHD chunk must appear, and the operation field must be set to the
according anim method.

Each of the frames from frame 2 on up may use an anhd->operation of 0, 5 or 8. Note that only for the first frame in the file do you copy the image data into two buffers, not every time you get an ANHD->operation==0.

== Chunk Formats ==

=== ANHD Chunk for method 8 ===

The ANHD chunk consists of the following data structure:

UBYTE operation The compression method=8 short/long Vertical Delta mode
UBYTE mask unused
UWORD w,h unused
WORD x,y unused
ULONG abstime unused
ULONG reltime (timing for frame relative to time previous frame was displayed - in jiffies (1/60 sec))
UBYTE interleave = 0 (see ANHD description above)
UBYTE pad0 unused
ULONG bits 32 option bits used by method=4 and 5.
method 8 uses only bit #0
bit # set =0 set =1
=============================================
0 short data long data
UBYTE pad[16] unused

=== DLTA Chunk ===

The DLTA Chunks of method8 consists of
* 16 pointers same as in method 5

In this method the DLTA Chunk begins with 16 pointers. The first 8 longwords are pointers to the opcode lists for up to 8
planes. The second set of 8 longwords are unused. If there are less than 8 Planes all unused pointers are set to zero.

Compression/decompression is performed on a plane-by-plane basis. The following description of the method is similar to Jim Kent's methode 5, except that data is either in WORDs or LONGS, depending on bit 0 of the ANHD bits.

In method 8 the bit plane is split into vertical columns. Each column of the bit plane is compressed separately. A 320x200 bit plane would have 20 columns of 200 short data each (or 10 columns of 200 long data).

Each column of the bit plane is compressed separately. A 320x200 bit plane would have 20 (WORD) or 10 (LONG)columns of 200 bytes each. Each column starts with an op-count followed by a number of ops. If the op-count is zero, that's OK, it just means there's no change in this column from the last frame. The ops are of three classes, and followed by a varying amount of data depending on which class:

# Skip ops - this is a word or long with the hi bit clear that says how many rows to move the "dest" pointer forward, i.e. to skip. It is non-zero. Note that the range of values is much larger for word and long data, 0x7fff and 0x7fffffff.
# Uniq ops - this is a word or long with the hi bit set. The hi bit is masked down and the remainder is a count of the number of bytes of data to copy literally. It's of course followed by the data to copy. Note that the range of values is much larger for word and long data, 0x7fff and 0x7fffffff.
# Same ops - this is a 0 word or long followed by a count word or long, followed by a word or long value to repeat count times. Note that the range of values is much larger for word and long data, 0xffff and 0xffffffff.

{{Note|text=Do bear in mind that the data is compressed vertically rather than horizontally, so to get to the next word or long in the destination we add the number of bytes per row instead of one!}}

There is a slight complication in the case of long data. Normally an Amiga BitMap is and even number of 16bit WORDs wide, so it is possible to have an image which is not an even number or LONGs wide. For example, an image which is 336 pixels wide is 42 bytes wide, 21 words wide, and 10.5 longs wide. In the case that the data is not an even number of longs wide, and the data is to be long compressed, then the last column of data is to be word compressed instead. So, that 336 pixel wide image would be compress as 10 long columns and 1 word column.

= ANIM.brush =

Dpaint Anim Brush IFF Format

From a description by the author of DPaint, Dan Silva, Electronic Arts.

The "Anim Brushes" of DPaint III are saved on disk in the IFF "ANIM" format. Basically, an ANIM Form consists of an initial ILBM which is the first frame of the animation, and any number of subsequent "ILBM"S (which aren't really ILBM's) each of which contains an ANHD animation header chunk and a DLTA chunk comprised of the encoded difference between a frame and a previous one.

To use ANIM terminology (for a description of the ANIM format, see the IFF Anim Spec, by Gary Bonham). Anim Brushes use a "type 5" encoding, which is a vertical, byte-oriented delta encoding (based on Jim Kent's RIFF). The deltas have an interleave of 1, meaning deltas are computed between adjacent frames, rather than between frames 2 apart, which is the usual ANIM custom for the purpose of fast hardware page-flipping. Also, the deltas use Exclusive Or to allow reversable play.

However, to my knowledge, all the existing Anim players in the Amiga world will only play type 5 "Anim"s which have an interleave of 0 (i.e. 2) and which use a Store operation rather than Exclusive Or, so no existing programs will read Anim Brushes anyway. The job of modifying existing Anim readers to read Anim Brushes should be simplified, however.

Here is an outline of the structure of the IFF Form output by DPaint III as an "Anim Brush". The IFF Reader should of course be flexible enough to tolerate variation in what chunks actually appear in the initial ILBM.

FORM ANIM
. FORM ILBM first frame
. . BMHD
. . CMAP
. . DPPS
. . GRAB
. . CRNG
. . CRNG
. . CRNG
. . CRNG
. . CRNG
. . CRNG
. . DPAN my own little chunk.
. . CAMG
. . BODY

. FORM ILBM frame 2
. . ANHD animation header chunk
. . DLTA delta mode data

. FORM ILBM frame 3
. . ANHD animation header chunk
. . DLTA delta mode data

. FORM ILBM frame 4
. . ANHD animation header chunk
. . DLTA delta mode data

...

. FORM ILBM frame N
. . ANHD animation header chunk
. . DLTA delta mode data

== DPAN ==

Here is the format of the DPAN chunk:

<syntaxhighlight lang="C" line>
typedef struct {
UWORD version; /* current version=4 */
UWORD nframes; /* number of frames in the animation.*/
ULONG flags; /* Not used */
} DPAnimChunk;
</syntaxhighlight>

The version number was necessary during development. At present all I look at is "nframes".

== ANHD ==

Here is the ANHD chunk format:

<syntaxhighlight lang="C" line>
typedef struct {
UBYTE operation; /* =0 set directly
=1 XOR ILBM mode,
=2 Long Delta mode,
=3 Short Delta mode
=4 Generalize short/long Delta mode,
=5 Byte Vertical Delta (riff)
=74 (Eric Grahams compression mode)
*/
UBYTE mask; /* XOR ILBM only: plane mask where data is*/
UWORD w,h;
WORD x,y;
ULONG abstime;
ULONG reltime;
UBYTE interleave; /* 0 defaults to 2 */
UBYTE pad0; /* not used */
ULONG bits; /* meaning of bits:
bit# =0 =1
0 short data long data
1 store XOR
2 separate info one info for
for each plane for all planes
3 not RLC RLC (run length encoded)
4 horizontal vertical
5 short info offsets long info offsets
-------------------------*/
UBYTE pad[16];
} AnimHdr;
</syntaxhighlight>

for Anim Brushes, I set:
<syntaxhighlight lang="C" line>
animHdr.operation = 5; /* RIFF encoding */
animHdr.interleave = 1;
animHdr.w = curAnimBr.bmob.pict.box.w;
animHdr.h = curAnimBr.bmob.pict.box.h;
animHdr.reltime = 1;
animHdr.abstime = 0;
animHdr.bits = 4; /* indicating XOR */
</syntaxhighlight>

everything else is set to 0.

{{Note|text=The "bits" field was actually intended ( by the original creator of the ANIM format, Gary Bonham of SPARTA, Inc.) for use with only with compression method 4. I am using bit 2 of the bits field to indicate the Exclusive OR operation in the context of method 5, which seems like a reasonable generalization.}}

== DLTA ==

For an Anim Brush with 10 frames, there will be an initial frame followed by 10 Delta's (i.e ILBMS containing ANHD and DLTA
chunks). Applying the first Delta to the initial frame generates the second frame, applying the second Delta to the second frame
generates the third frame, etc. Applying the last Delta thus brings back the first frame.

The DLTA chunk begins with 16 LONG plane offets, of which DPaint only uses the first 6 (at most). These plane offsets are either
the offset (in bytes ) from the beginning of the DLTA chunk to the data for the corresponding plane, or Zero, if there was no
change in that plane. Thus the first plane offset is either 0 or 64.

(The following description of the method is based on Gary Bonham's rewording of Jim Kent's RIFF documentation.)

Compression/decompression is performed on a plane-by-plane basis.

Each byte-column of the bit plane is compressed separately. A 320x200 bit plane would have 40 columns of 200 bytes each. In
general, the bit planes are always an even number of bytes wide, so for instance a 17x20 bit plane would have 4 columns of 20
bytes each.

Each column starts with an op-count followed by a number of ops. If the op-count is zero, that's OK, it just means there's no change in this column from the last frame. The ops are of three kinds, and followed by a varying amount of data depending on which kind:

# SKIP - this is a byte with the hi bit clear that says how many rows to move the "dest" pointer forward, i.e. to skip. It is non-zero.
# DUMP - this is a byte with the hi bit set. The hi bit is masked off and the remainder is a count of the number of bytes of data to XOR directly. It is followed by the bytes to copy.
# RUN - this is a 0 byte followed by a count byte, followed by a byte value to repeat "count" times, XOR'ing it into the destination.

{{Note|text=Bear in mind that the data is compressed vertically rather than horizontally, so to get to the next byte in the destination you add the number of bytes per row instead of one.}}

The Format of DLTA chunks is as described in section 2.2.2 of the Anim Spec. The encoding for type 5 is described in section 2.2.3 of the Anim Spec.

Window Display Preservation

2025-01-26T19:30:48Z

Costel Mincea: Text replacement - "<syntaxhighlight>" to "<syntaxhighlight lang="C" line>"

= Preserving the Window Display =

The layers library is what allows the display and manipulation of multiple overlapping rectangles, or ''layers''. Intuition uses the layers library to manage its windows, by associating a layer to each window.

Each window is a virtual display. When rendering, the application does not have to worry about the current size or position of its window, and what other windows might be partly or fully obscuring its window. The window's RastPort is the handle to the its virtual display space. Intuition and graphics library rendering calls will recognize that this RastPort belongs to a layer, and act accordingly.

As windows are moved, resized, rearranged, opened, or closed, the on-screen representation changes. When part of a window which was visible now needs to appear in a new location, the layers library will move that imagery without involving the application. However, when part of a window that was previously obscured is revealed, or when a window is made larger, the imagery for the newly-visible part of the window needs to be redrawn. Intuition, through layers, offers three choices for how this is managed, trading off speed, memory usage, and application complexity.

* The most basic type of window is called ''Simple Refresh''. When any graphics operation takes place in this kind of window, the visible parts are updated, but rendering to the obscured parts is discarded. When the window arrangement changes to reveal a previously obscured part of such a window, the application must refresh that area.

* Alternately, a window may be made ''Smart Refresh'', which means that when rendering occurs, the system will not only update the visible parts of the window, but it will maintain the obscured parts as well, by using off-screen buffers. This means that when an obscured part of the window is revealed, the system will restore the imagery that belongs there. The application needs only to refresh parts of the window that appear when the window is made bigger. Smart Refresh windows use more memory than Simple Refresh windows (for the storage of obscured areas), but they are faster.

* The third kind of window is called ''SuperBitMap''. In such a window, the system can refresh the window even when it is sized bigger. For this to work, the application must store a complete bitmap for the window's maximum size. Such a window is more work to manage, and uses yet more memory. SuperBitMap windows are used less often than the other two types.

Intuition helps your application manage window refresh. First, Intuition will take care of redrawing the window border and any system and application gadgets in the window. Your application never has to worry about that. Second, Intuition will notify your application when it needs to refresh its window (by sending the IDCMP_REFRESHWINDOW event). Third, Intuition provides functions that restrict your rendering to the newly-revealed (damaged) areas only, which speeds up your refresh rendering and makes it look cleaner.

The Intuition, layers, and graphics libraries work together to make rendering into and managing windows easy. You obtain your windows through Intuition, which uses the Layers library to manage the overlapping, resizing, and re-positioning of the window layers. The layers library is responsible for identifying the areas of each window that are visible, obscured but preserved off-screen, or obscured and not preserved. The rendering functions in the graphics library and Intuition library know how to render into the multiple areas that layers library establishes.

Note that you may not directly manipulate layers on an Intuition screen. You cannot create your own layers on an Intuition screen, nor can you use the layers movement, sizing, or arrangement functions on Intuition windows. Use the corresponding Intuition calls instead. Some other Layers library calls (such as the locking calls) are sometimes used on Intuition screens and windows.

= Damage Regions =

The layers library and Intuition maintain a ''damage region'' for each window, which is the part of the window whose imagery is in need of repair, or refreshing. Several things can add areas of the window to the damage region:

* Revealing an obscured part of a Simple Refresh window adds that area to the damage region
* Sizing a Simple or Smart Refresh window bigger along either axis adds the new area to the damage region
* Resizing a Simple or Smart Refresh window (smaller or bigger) adds the old and new border areas, and the areas occupied by certain gadgets (those whose position or size depend on window size) to the damage region.

= Refreshing Intuition Windows =

When the user or an application performs an Intuition operation which causes damage to a window, Intuition notifies that window's application. It does this by sending a message of the class IDCMP_REFRESHWINDOW to that window's IDCMP.

In response to this message, your application should update the damaged areas. Rendering proceeds faster and looks cleaner if it is restricted to the damaged areas only. The BeginRefresh()/EndRefresh() pair achieve that. The application should call BeginRefresh() for the window, and then do its rendering. Any rendering that would have gone into undamaged areas of the window is automatically discarded; only the area in need of repair is affected. Finally, the application should call EndRefresh(), which removes the restriction on rendering, and informs the system that the damage region has been dealt with. Even if your application intends to do no rendering, it must at least call BeginRefresh()/EndRefresh(), to inform the system that the damage region is no longer needed. If your application never needs to render in response to a refresh event, it can avoid having to call BeginRefresh()/EndRefresh() by setting the WFLG_NOCAREREFRESH flag or the WA_NoCareRefresh tag in the OpenWindowTagList() call.

Note that by the time that your application receives notification that refresh is needed, Intuition will have already refreshed your window's border and all gadgets in the window, as needed. Thus, it is unnecessary to use any of the gadget-refreshing functions in response to an IDCMP_REFRESHWINDOW event.

Operations performed between the BeginRefresh()/EndRefresh() pair should be restricted to simple rendering. All of the rendering functions in Intuition library and Graphics library are safe. Avoid RefreshGList() or RefreshGadgets(), or you risk deadlocking the computer. Avoid calls that may lock the LayerInfo or get complicated in Intuition, since BeginRefresh() leaves the window's layer or layers locked. Avoid AutoRequest() and EasyRequest(), and therefore all direct or indirect disk related DOS calls. See the [[Intuition_Gadgets|Intuition Gadgets]] section for more information on gadget restrictions with BeginRefresh() and EndRefresh().

== Simple Refresh ==

For a Simple Refresh window, only those pixels actually on-screen are maintained by the system. When part of a Simple Refresh window is obscured, the imagery that was there is lost. As well, any rendering into obscured portions of such a window is discarded.

When part of the window is newly revealed (either because the window was just made larger, or because that part used to be obscured by another window), the application must refresh any rendering it wishes to appear into that part. The application will learn that refresh is needed because Intuition sends an IDCMP_REFRESHWINDOW event.

== Smart Refresh ==

If a window is of the Smart Refresh type, then the system will not only preserve those pixels which are actually on-screen, but it will save all obscured pixels that are within the current window's size. The system will refresh those parts of the window revealed by changes in the overlapping with other windows on the screen, without involving the application. However, any part of the window revealed through the sizing of the window must be redrawn by the application. Again, Intuition will notify the application through the IDCMP_REFRESHWINDOW event.

Because the obscured areas are kept in off-screen buffers, Smart Refresh windows are refreshed faster than Simple Refresh windows are, and often without involving the application. Of course, for the same reason, they use more display memory.

== SuperBitMap Refresh ==

The SuperBitMap refresh type allows the application to provide and maintain bitmap memory for graphics in the window. The bitmap can be any size as long as the window sizing limits respect the maximum size of the bitmap.

SuperBitMap windows have their own memory for maintaining all obscured parts of the window up to the size of the defined bitmap, including those parts outside of the current window. Intuition will update all parts of the window that are revealed through changes in sizing and changes in window overlapping. The application never needs to redraw portions of the window that were revealed by sizing or positioning windows in the screen.

SuperBitMap windows require the application to allocate a bitmap for use as off-screen memory, instead of using Intuition managed buffers. This bitmap must be as large as, or larger than, the inner window's maximum dimensions (that is, the window's outside dimensions less the border sizes).

SuperBitMap windows are almost always WFLG_GIMMEZEROZERO, which renders the borders and system gadgets in a separate bitmap. If the application wishes to create a SuperBitMap window that is not GimmeZeroZero, it must make the window borderless with no system gadgets, so that no border imagery is rendered by Intuition into the application's bitmap.

= Intuition Refresh Events =

When using a Simple Refresh or a Smart Refresh windows, the program may receive refresh events, informing it to update the display. See the above discussion for information on when refresh events are sent.

A message of the class IDCMP_REFRESHWINDOW arrives at the IDCMP, informing the program of the need to update the display. The program must take some action when it receives a refresh event, even if it is just the acceptable minimum action described below.

On receiving a refresh event, BeginRefresh() must be called, then the program should redraw its display, and, finally, call EndRefresh(). The minimum required action is to call the BeginRefresh()/EndRefresh() pair. This allows Intuition and the Layers library keep things sorted and organized.

= Optimized Window Refreshing =

Bracketing the display updating in the BeginRefresh()/EndRefresh() pair automatically restricts all rendering to the "damaged" areas.

<syntaxhighlight lang="C" line>
VOID BeginRefresh( struct Window *window );
VOID EndRefresh ( struct Window *window, LONG complete );
</syntaxhighlight>

These functions makes sure that refreshing is done in the most efficient way, only redrawing those portions of the window that really need to be redrawn. The rest of the rendering commands are discarded.

Operations performed between the BeginRefresh()/EndRefresh() pair should be restricted to simple rendering. All of the rendering functions in Intuition library and Graphics library are safe. Calls to RefreshGadgets() are not permitted. Avoid calls that may lock the LayerInfo, or get complicated in Intuition, since BeginRefresh() leaves the window's layer or layers locked. Avoid AutoRequest(), and therefore all direct or indirect disk related DOS calls. See [[Intuition_Gadgets|Intuition Gadgets]] for more information on gadget restrictions with BeginRefresh()/EndRefresh().

Certain applications do not need to receive refresh events, and can avoid having to call BeginRefresh() and EndRefresh() by setting the WFLG_NOCAREREFRESH flag or the WA_NoCareRefresh tag in the OpenWindowTagList() call.

The EndRefresh() function takes a boolean value as an argument (complete in the prototype above). This value determines whether refreshing is completely finished. When set to FALSE, further refreshing may be performed between subsequent BeginRefresh()/ EndRefresh() pairs. Set the boolean to TRUE for the last call to EndRefresh().

It is critical that applications performing multiple BeginRefresh() and EndRefresh() pairs using EndRefresh(win,FALSE) hold layers locked through the entire process. The layer lock may only be released after the final call to EndRefresh(win,TRUE). See [[Layers_Library|Layers Library]] for more details.

The procedures outlined in this section take care of refreshing what is inside the window. Another function named RefreshWindowFrame() refreshes window borders, including the title region and gadgets:

<syntaxhighlight lang="C" line>
VOID RefreshWindowFrame( struct Window *window );
</syntaxhighlight>

Applications can use this function to update window borders after overwriting them with graphics.

= Setting up a SuperBitMap Window =

SuperBitMap windows are created by setting the WFLG_SUPER_BITMAP flag, or by specifying the WA_SuperBitMap tag in the OpenWindowTagList() call. A pointer to an allocated and initialized BitMap structure must be provided.

A SuperBitMap window requires the application to allocate and initialize its own bitmap. This entails allocating a BitMap structure, initializing the structure and allocating memory for the bit planes.

Allocate a BitMap structure with the Exec AllocMem() function. Then use the graphics function InitBitMap() to initialize the BitMap structure:

<syntaxhighlight lang="C" line>
VOID InitBitMap( struct BitMap *bitMap, LONG depth, LONG width, LONG height );
</syntaxhighlight>

InitBitMap() fills in fields in the BitMap structure describing how a linear memory area is organized as a series of one or more rectangular bit-planes.

Once you have allocated and initialized the BitMap structure, use the graphics library function AllocRaster() to allocate the memory space for all the bit planes.

<syntaxhighlight lang="C" line>
PLANEPTR AllocRaster( ULONG width, ULONG height );
</syntaxhighlight>

The example listed in the next section shows how to allocate a BitMap structure, initialize it with InitBitMap() and use AllocRaster() function to set up memory for the bitplanes.

= Graphics and Layers Functions for SuperBitMap Windows =

The portion of the bitmap showing within a SuperBitMap window is controlled by the application. Initially, the window shows the bitmap starting from its origin (0,0) and clipped to fit within the window layer. The visible portion of the bitmap can be scrolled around within the window using the layers library ScrollLayer() function:

<syntaxhighlight lang="C" line>
VOID ScrollLayer(LONG unused, struct Layer *layer, LONG dx, LONG dy)
</syntaxhighlight>

Pass this function a pointer to the window's layer in layer and the scroll offsets in dx and dy. (A pointer to the window's layer can be obtained from Window.RPort->Layer.)

When rendering operations are performed in a SuperBitMap window, any rendering that falls outside window boundaries is done in the application's bitmap. Rendering that falls within window bounds is done in the screen's bitmap. Before performing an operation such as a save on the application bitmap, the graphics library function SyncSBitMap() should be called:

<syntaxhighlight lang="C" line>
VOID SyncSBitMap(struct Layer *layer)
</syntaxhighlight>

Pass this function a pointer to the window's layer. SyncSBitMap() copies the window contents to the corresponding part of the application bitmap, bringing it up to date. (If no rendering operations have been performed this call is not necessary.)

Similarly, after making any changes to the application bitmap such as loading a new one, the window's layer should be locked and the CopySBitMap() function should be called.

<syntaxhighlight lang="C" line>
VOID CopySBitMap(struct Layer *)
</syntaxhighlight>

This function copies the new information in the appropriate area of the underlying bitmap to the window's layer.

For more information about bitmaps and layers, see the [[Graphics_Primitives|Graphics Primitives]] and [[Layers_Library|Layers Library]]. Also see the <graphics/clip.h>, <graphics/gfx.h>, <graphics/layers.h > files in the SDK.

== SuperBitMap Window Example ==

This example shows how to implement a superbitmap, and uses a host of Intuition facilities. Further reading of other Intuition, BOOPSI and graphics chapters may be required for a complete understanding of this example.

<syntaxhighlight lang="C" line>
/**
** lines.c -- Window SuperBitMap example.
**
** gcc -o lines lines.c
**
**/

#include <dos/dos.h>
#include <intuition/icclass.h>
#include <classes/window.h>
#include <gadgets/scroller.h>
#include <gadgets/layout.h>

#include <proto/intuition.h>
#include <proto/exec.h>
#include <proto/utility.h>
#include <proto/layers.h>
#include <proto/graphics.h>

#define WIDTH_SUPER (800)
#define HEIGHT_SUPER (600)
#define MINWIDTH (150)
#define MINHEIGHT (150)

#define LAYERXOFFSET(x) (x->RPort->Layer->Scroll_X)
#define LAYERYOFFSET(x) (x->RPort->Layer->Scroll_Y)

enum
{
WID_MAIN = 0,
WID_LAST
};

enum
{
OID_MAIN = 0,
OID_VPROP,
OID_HPROP,
OID_LAST
};

struct IntuitionIFace *IIntuition;
struct GraphicsIFace *IGraphics;
struct LayersIFace *ILayers;

static struct Window *windows[WID_LAST];
static Object *objects[OID_LAST];
static struct Hook idcmphook;

/* Prototypes for our functions */

void initBorderProps(struct Screen *screen);
void doNewSize();
void doDrawStuff();
void doMsgLoop();
void superWindow(struct Screen *screen);
void slideBitMap(struct Window *win, int16 dX, int16 dY);

int main()
{
struct Screen *screen;

struct Library *IntuitionBase = IExec->OpenLibrary("intuition.library", 50);
IIntuition = (struct IntuitionIFace *) IExec->GetInterface(IntuitionBase,
"main", 1, NULL);

struct Library *GfxBase = IExec->OpenLibrary("graphics.library", 50);
IGraphics = (struct GraphicsIFace *) IExec->GetInterface(GfxBase, "main", 1, NULL);

struct Library *LayersBase = IExec->OpenLibrary("layers.library", 50);
ILayers = (struct LayersIFace *) IExec->GetInterface(LayersBase, "main", 1, NULL);

if (IIntuition != NULL && IGraphics != NULL && ILayers != NULL) {
if ((screen = IIntuition->LockPubScreen(NULL)) != NULL) {
superWindow(screen);
IIntuition->UnlockPubScreen(NULL, screen);
}
}

IExec->DropInterface((struct Interface *) ILayers);
IExec->CloseLibrary(LayersBase);

IExec->DropInterface((struct Interface *) IGraphics);
IExec->CloseLibrary(GfxBase);

IExec->DropInterface((struct Interface *) IIntuition);
IExec->CloseLibrary(IntuitionBase);

return 0;
}

void IDCMPHook(struct Hook *hook, Object *object, struct IntuiMessage *msg)
{
if (msg->Class == IDCMP_IDCMPUPDATE) {
int16 dX = 0;
int16 dY = 0;
int32 pos;

struct Window *win = windows[WID_MAIN];
if (win != NULL) {
uint32 gadgetid = IUtility->GetTagData(GA_ID, 0, (struct TagItem *) msg->IAddress);
if (IIntuition->GetAttr(SCROLLER_Top, objects[gadgetid], (uint32 *) &pos)) {
switch (gadgetid) {
case OID_VPROP:
dY = pos - LAYERYOFFSET(win);
break;
case OID_HPROP:
dX = pos - LAYERXOFFSET(win);
break;
}
if (dX || dY) {
slideBitMap(win, dX, dY);
}
}
}
}
}

void superWindow(struct Screen *myscreen)
{
struct BitMap *bigBitMap = IGraphics->AllocBitMapTags(WIDTH_SUPER, HEIGHT_SUPER, myscreen->BitMap.Depth,
BMATags_Friend, myscreen->BitMap, BMATags_Displayable, TRUE, BMATags_Clear, 0, TAG_END);

if (bigBitMap != NULL) {
struct MsgPort *AppPort = IExec->AllocSysObjectTags(ASOT_PORT, TAG_DONE);

if ( AppPort != NULL )
{
idcmphook.h_Entry = (uint32 (*)())IDCMPHook;
idcmphook.h_SubEntry = NULL;

if ((objects[OID_MAIN] = IIntuition->NewObject(NULL, "window.class",
WA_ScreenTitle, "SuperBitmap",
WA_Title, "Lines",
WA_Activate, TRUE,
WA_DepthGadget, TRUE,
WA_DragBar, TRUE,
WA_CloseGadget, TRUE,
WA_SizeGadget, TRUE,
WA_Top, 10,
WA_Left, 10,
WA_MinWidth, MINWIDTH,
WA_MinHeight, MINHEIGHT,
WA_Width, MINWIDTH,
WA_Height, MINHEIGHT,
WA_IDCMP, IDCMP_NEWSIZE | IDCMP_IDCMPUPDATE,
WA_PubScreen, myscreen, WA_SuperBitMap, bigBitMap,
WA_NoCareRefresh, TRUE,
WA_GimmeZeroZero, TRUE,
WINDOW_IDCMPHook, &idcmphook,
WINDOW_IDCMPHookBits, IDCMP_IDCMPUPDATE,
WINDOW_HorizProp, 1,
WINDOW_VertProp, 1,
WINDOW_AppPort, AppPort, TAG_DONE)) != NULL) {
// Open the window.
if (windows[WID_MAIN] = (struct Window *) IIntuition->IDoMethod(objects[OID_MAIN], WM_OPEN)) {
/* adjust props to represent portion visible */
doNewSize();
doDrawStuff();
/* process the window, return on IDCMP_CLOSEWINDOW */
doMsgLoop();
}
IIntuition->DisposeObject(objects[OID_MAIN]);
}
IExec->FreeSysObject(ASOT_PORT, AppPort);
}
IGraphics->FreeBitMap(bigBitMap);
}
}

void slideBitMap(struct Window *win, int16 Dx, int16 Dy)
{
ILayers->ScrollLayer(0, win->RPort->Layer, Dx, Dy);
}

/*
** Update the prop gadgets and bitmap positioning when the size changes.
*/

void doNewSize()
{
struct Window *win = windows[WID_MAIN];
if (win != NULL) {
IIntuition->GetAttr(WINDOW_HorizObject, objects[OID_MAIN], (uint32 *) &objects[OID_HPROP]);
if (objects[OID_HPROP]) {
if (win->GZZWidth >= WIDTH_SUPER)
slideBitMap(win, -LAYERXOFFSET(win), 0);
IIntuition->RefreshSetGadgetAttrs((APTR) objects[OID_HPROP], win, NULL,
GA_ID, OID_HPROP,
SCROLLER_Top, LAYERXOFFSET(win),
SCROLLER_Total, WIDTH_SUPER,
SCROLLER_Visible, win->GZZWidth,
ICA_TARGET, ICTARGET_IDCMP,
TAG_DONE);
}

IIntuition->GetAttr(WINDOW_VertObject, objects[OID_MAIN], (uint32 *) &objects[OID_VPROP]);
if (objects[OID_VPROP]) {
if (win->GZZHeight >= HEIGHT_SUPER)
slideBitMap(win, 0, -LAYERYOFFSET(win));

IIntuition->RefreshSetGadgetAttrs((APTR) objects[OID_VPROP], win, NULL,
GA_ID, OID_VPROP,
SCROLLER_Top, LAYERYOFFSET(win),
SCROLLER_Total, HEIGHT_SUPER,
SCROLLER_Visible, win->GZZHeight,
ICA_TARGET, ICTARGET_IDCMP,
TAG_DONE);
}
}
}

int16 RangeRand(uint32 maxValue)
{
static struct RandomState range = {0xFFFF, 0};
return IUtility->Random(&range) % maxValue;
}

void doDrawStuff()
{
struct Window *win = windows[WID_MAIN];
if (win != NULL) {
/* clear the bitplanes */
IGraphics->SetRast(win->RPort, 0);
IGraphics->SetDrMd(win->RPort, JAM1);
int16 x1, y1, x2, y2;
int16 pen, ncolors, deltx, delty;
ncolors = 1 << win->WScreen->BitMap.Depth;
deltx = RangeRand(6) + 2;
delty = RangeRand(6) + 2;
pen = RangeRand(ncolors - 1) + 1;
IGraphics->SetAPen(win->RPort, pen);
for (x1 = 0, y1 = 0, x2 = WIDTH_SUPER - 1, y2 = HEIGHT_SUPER - 1;
x1 < WIDTH_SUPER; x1 += deltx, x2 -= deltx) {
IGraphics->Move(win->RPort, x1, y1);
IGraphics->Draw(win->RPort, x2, y2);
}

pen = RangeRand(ncolors - 1) + 1;
IGraphics->SetAPen(win->RPort, pen);
for (x1 = 0, y1 = 0, x2 = WIDTH_SUPER - 1, y2 = HEIGHT_SUPER - 1;
y1 < HEIGHT_SUPER; y1 += delty, y2 -= delty) {
IGraphics->Move(win->RPort, x1, y1);
IGraphics->Draw(win->RPort, x2, y2);
}
}
}

void doMsgLoop()
{
uint32 signal = 0;
BOOL done = FALSE;

// Obtain the window wait signal mask.
IIntuition->GetAttr(WINDOW_SigMask, objects[OID_MAIN], &signal);

// Input Event Loop
while (!done) {
uint32 wait = IExec->Wait(signal | SIGBREAKF_CTRL_C);
if ( wait & SIGBREAKF_CTRL_C ) {
done = TRUE;
break;
}

if ( wait & signal ) {
uint32 result = WMHI_LASTMSG;
int16 code = 0;
while ((result = IIntuition->IDoMethod(objects[OID_MAIN], WM_HANDLEINPUT, &code)) != WMHI_LASTMSG) {
switch (result & WMHI_CLASSMASK) {
case WMHI_NEWSIZE:
doNewSize();
doDrawStuff();
break;
case WMHI_CLOSEWINDOW:
windows[WID_MAIN] = NULL;
done = TRUE;
break;
case WMHI_ICONIFY:
IIntuition->IDoMethod(objects[OID_MAIN], WM_ICONIFY);
windows[WID_MAIN] = NULL;
break;
case WMHI_UNICONIFY:
windows[WID_MAIN] = (struct Window *) IIntuition->IDoMethod(objects[OID_MAIN], WM_OPEN);
doNewSize();
doDrawStuff();
break;
}
}
}
}
}
</syntaxhighlight>

Graphics Sprites, Bobs and Animation

2025-01-26T19:30:36Z

Costel Mincea: Text replacement - "<syntaxhighlight>" to "<syntaxhighlight lang="C" line>"

{{WIP}}
== Graphics Sprites, Bobs and Animation ==

This article describes how to use the functions provided by the graphics library to manipulate and animate Graphic Elements (also called GELs). It is divided into six sections:

* An overview of the GELs animation system, including fundamental terms and structures
* Explanation of simple (hardware) Sprites and an example showing their usage
* Explanation of VSprites and an example showing their usage
* Explanation of Bobs and an example showing their usage
* Discussion of topics that apply to all GELs such as collision detection and data structure extensions.
* Discussion of animation, using AnimComps and AnimObs and an example showing their usage

== About the GELs System ==

Before going into details, a quick glossary is in order. A ''playfield'' forms the background that GELs operate in. It encompasses the View, ViewPort, and RastPort data structures. (VSprites appear ''over'', and Bobs appear ''in'' the playfield.) Playfields can be created and controlled at several levels. Refer to [[Graphics_Primitives|Graphics Primitives]] and [[Layers_Library|Layers Library]] for details on lower-level playfield control. [[Intuition_Screens|Intuition Screens]] explains how to get higher-level access to playfields.

GELs, or graphic elements, are special graphic objects that appear in the foreground and can be moved easily around the display. They are software constructs based on the Amiga's sprite and blitter hardware. The GELs system is compatible with all playfield modes, including dual-playfield. All the various types of GELs are defined by data structures found in <graphics/gels.h>.

=== Types of GELs ===

The GEL types are (in order of increasing complexity):

; VSprites
: for Virtual Sprites. These are represented by the VSprite data structure and implemented with sprite hardware.

; Bobs
: Blitter Objects. These are represented by the VSprite and Bob data structures and implemented with blitter hardware.

; AnimComps
: Animation Components. These are represented by the VSprite, Bob and AnimComp data structures and implemented with blitter hardware.

; AnimObjs
: Animation Objects. These are used to group AnimComps. They are not strictly GELs, but are described here.

==== Simple Sprites ====

Simple Sprites (also known as hardware sprites) are not really part of the GELs system but are the basis for VSprites. Simple Sprites are graphic objects implemented in hardware that are easy to define and easy to animate. The Amiga hardware has the ability to handle up to eight such sprite objects. Each Simple Sprite is produced by one of the Amiga's eight sprite DMA channels. They are 16-bits wide and arbitrarily tall.

The Amiga system software offers a choice of how to use these hardware sprites. After a sprite DMA channel has displayed the last line of a Simple Sprite, the system can reuse the channel for a different sprite lower on the screen. This is how VSprites are implemented; as a software construct based on the sprite hardware.

Hence, Simple Sprites are not really part of the animation system (they are ''not'' GELs). In fact, if Simple Sprites and GELs are used in the same display, the GELs system must be told specifically which Simple Sprites to avoid. Simple Sprites are described in this article because they are alternatives to VSprites.

==== VSprites ====

The VSprite, or virtual sprite, is the simplest type of GEL. The VSprite data structure contains just a bit more information than is needed to define a hardware sprite. VSprites take advantage of the system's ability to reuse sprite DMA channels - each VSprite can be temporarily assigned to a hardware sprite, as needed. This makes it appear to an application program that it has a ''virtually'' unlimited supply of VSprites.

Since VSprites are based on hardware sprites, rules that apply to hardware sprites apply to VSprites too. VSprites are not rendered into the underlying BitMap of the playfield and so do not affect any bits in the BitMap. Because they are hardware based, ''they are positioned at absolute display coordinates and are not affected by the movement of screens''. The starting position of a sprite must not occur before scanline 20, because of certain hardware DMA time constraints. VSprites have the same size limitations as hardware sprites, they are 16-bits wide and arbitrarily tall.

The VSprite data structure also serves as the root structure of more complex GEL types: Bobs and AnimComps.

==== Bobs and AnimComps ====

Like VSprites, Bobs and AnimComps are graphics objects that make animation easier. They are rendered using the blitter. The blitter is a special Amiga hardware component used to move data quickly and efficiently, optionally performing logical operations as it does. It can be used to move any kind of data but is especially well suited to moving rectangular blocks of display data.

It is important to keep in mind that Bobs and AnimComps are based on the blitter hardware while VSprites use the sprite hardware. However all three GEL types use the VSprite structure as their root data structure. The system uses pointers to link the VSprite, Bob and AnimComp structures, "extending" the VSprite structure to include all GEL types.

Since Bobs and AnimComps are rendered with the blitter they actually change the underlying playfield BitMap. The BitMap area where the GEL is rendered can be saved. By moving the GEL to new locations in small increments while also saving and restoring the Bitmap as you proceed, you can create an animation effect. Bobs and AnimComps use the same coordinates as the playfield and can be any size.

==== AnimObs ====

The AnimOb (Animation Object) is a data structure that is used to group one or more AnimComps for convenient movement. For example, an AnimOb could be created that consists of two AnimComps, one that looks like a planet and another containing a sequence that describes orbiting moons. By moving just the AnimOb the image of the planet can be moved across the display and the moons will travel along with it, orbiting the planet the entire time. The system automatically manages the movement of all the AnimComps associated with the AnimOb.

==== VSprites vs. Bobs ====

If you are going to manage the movement and sequencing of GELS yourself, you need to decide if sprite animation (VSprites) or blitter animation (Bobs, AnimComps and AnimObs) best suit your needs. If you've got simple requirements or lots of coding time, you may even opt to use only Simple Sprites, and control them yourself. On the other hand if you want the system to manage your animations, AnimComps ''must'' be used and they are Bobs at heart.

Some fundamental differences between VSprites and Bobs are:

* VSprite images and coordinates currently low-resolution pixels, even on a high resolution display. Bob images and coordinates have the same resolution as the playfield they are rendered into.

* VSprites have a maximum width of 16 (low resolution) pixels. Bobs can be any width (although large Bobs tend to slow down the system). The height of either VSprites or Bobs can be as tall as the display.

* VSprites have a maximum of three colors (Simple Sprites can have fifteen if they're attached). Because the system uses the Copper to control VSprite colors on the fly, the colors are not necessarily the same as those in the background playfield. Bobs can use any or all of the colors in the background playfield. Limiting factors include playfield resolution and display time. Bobs with more colors take longer to display.

* VSprites are positioned using absolute display coordinates, and don't move with screens. Bobs follow screen movement.

In general, VSprites offer speed, while Bobs offer flexibility.

The following figure shows how the various GEL data structures, VSprites, Bobs and AnimComps are linked together.

[[File:LibFig28-1.png|frame|center|GEL Structure Layout]]

=== The GELs System ===

Before you can use the GELs system, you must set up a playfield. The GELs system requires access to a View, ViewPort, and RastPort structure. These structures may be set up through the graphics library or Intuition. For most examples in this article, the Intuition library is used for this purpose.

All GELs have a VSprite structure at their core. The system keeps track of all the GELs that it will display (the active GELs) by using a standard Exec list structure to link the VSprites. This list is accessed via the GelsInfo data structure, which in turn is associated with the RastPort. The GelsInfo structure is defined in the file <graphics/rastport.h>.

A new GEL is introduced to the system by calling AddGel() to link it into the GelsInfo list. The new GEL is added immediately ahead of the first existing GEL whose ''x,y'' value is greater than or equal to that of the new GEL, always trying to keep the list sorted.

As GELs are moved about the screen, their ''x,y'' values are constantly changing. SortGList() re-sorts this list by the ''x,y'' values. (Although this is a list of VSprite structures, bear in mind that some or all may really be Bobs or AnimComps.)

The basic set up of the GelsInfo structure requires three important fields: sprRsrvd, gelHead and gelTail. The sprRsrvd field tells the system which hardware sprites not to use when managing true VSprites. For instance, Intuition uses sprite 0 for the mouse pointer so this hardware sprite is not available for assignment to a VSprite. The gelHead and gelTail are VSprite structures that are used to manage the list of GELs. They are never displayed. To activate or deactivate a GEL, a system call is made to add it to or delete it from this list.

Other fields must be set up to provide for collision detection, color optimization, and other features. A complete example for setting up the GelsInfo structure is shown in the animtools.c lisitng at the end of this article.

==== Initializing the GEL System ====

To initialize the animation system, call the system function InitGels(). It takes the form:

<syntaxhighlight lang="C" line>
struct VSprite *vsHead;
struct VSprite *vsTail;
struct GelsInfo *gInfo;

IGraphics->InitGels(vsHead, vsTail, gInfo);
</syntaxhighlight>

The vsHead argument is a pointer to the VSprite structure to be used as the GEL list head. (You must allocate an actual VSprite structure for vsHead to point to.) The vsTail argument is a pointer to the VSprite structure to be used as the GEL list tail. (You must allocate an actual VSprite structure for vsTail to point to.) The gInfo argument is a pointer to the GelsInfo structure to be initialized.

InitGels() forms these structures into a linked list of GELs that is empty except for these two dummy elements (the head and tail). It gives the head VSprite the maximum negative ''x'' and ''y'' positions and the tail VSprite the maximum positive ''x'' and ''y'' positions. This is to aid the system in keeping the list sorted by ''x, y'' values, so GELs that are closer to the top and left of the display are nearer the head of the list. The memory space that the VSprites and Gelsinfo structures take up must already have been allocated. This can be done either by declaring them statically or explicitly allocating memory for them.

Once the GelsInfo structure has been allocated and initialized, GELs can be added to the system. Refer to the setupGelSys() and cleanupGelsys() functions in the "animtools.c" lisitng at the end of the article for examples of allocating, initializing and freeing a GelsInfo structure.

== Collisions and GEL Structure Extensions ==

This section covers two topics that are applicable to all GELs: how to extend GEL data structures for your own purposes and how to detect collisions between GELs and other graphics objects.

==== Detecting GEL Collisions ====

All GELs, including VSprites, can participate in the software collision detection features of the graphics library. Simple Sprites must use ''hardware'' collision detection. See the ''Amiga Hardware Reference Manual'' for information about hardware collision detection.

Two kinds of collisions are handled by the system routines: GEL-to-boundary hits and GEL-to-GEL hits. You can set up as many as 16 different routines to handle different collision combinations; one routine to handle the boundary hits, and up to fifteen more to handle different inter-GEL hits.

You supply the actual collision handling routines, and provide their addresses to the system so that it can call them as needed (when the hits are detected). These addresses are kept in a collision handler table pointed to by the CollHandler field of the GelsInfo list. Which routine is called depends on the 16-bit MeMask and HitMask members of the VSprite structures involved in the collision.

When you call DoCollision(), the system goes through the GelsInfo list which, is constantly kept sorted by ''x,y'' position. If a GEL intersects the display boundaries and the GELs HitMask indicates it is appropriate, the boundary collision routine is called. When DoCollision() finds that two GELs overlap, it compares the MeMask of one with the HitMask of the other. If corresponding bits are set in both, it calls the appropriate inter-GEL collision routine at the table position corresponding to the bits in the HitMask and MeMask, as outlined below.

==== Preparing for Collision Detection ====

Before you can use the system to detect collisions between GELS, you must allocate and initialize a table of collision-detection routines and place the address of the table in the GelsInfo.CollHandler field. This table is an array of pointers to the actual routines that you have provided for your collision types. You must also prepare some members of the VSprite structure: CollMask, BorderLine, HitMask, and MeMask.

==== Building a Table of Collision Routines ====

The collision handler table is a structure, CollTable, defined in <graphics/gels.h>. It is accessed as the CollHandler member of the GelsInfo structure. The table only needs to be as large as the number of bits for which you wish to provide collision processing. It is safest, though, to allocate space for all 16 entries, considering the small amount of space required.

Call the routine SetCollision() to initialize the table entries that correspond to the HitMask and MeMask bits that you plan to use. Do not set any of the table entries directly, instead give the address to SetCollision() routine and let it handle the set up of the GelsInfo.CollTable field.

For example, SetCollision() could be called as follows:

<syntaxhighlight lang="C" line>
ULONG num;
VOID (*routine)();
struct GelsInfo *GInfo;

VOID myCollisionRoutine(GELA, GELB) /* sample collision routine */
struct VSprite *GELA;
struct VSprite *GELB;
{
/* process GELs here - GELA and GELB point to the base VSprites of */
/* the GELs, you can use the user extensions to identify what hit */
/* (if you need the info). */
}

/* GelsInfo must be allocated and initialized */

routine = myCollisionRoutine;

IGraphics->SetCollision(num, routine, GInfo)
</syntaxhighlight>

The num argument is the collision table vector number (0-15). The (*routine)() argument is a pointer to your collision routine. And the GInfo argument is a pointer to the GelsInfo structure.

==== VSprite Collision Mask ====

The CollMask member of the VSprite is a pointer to a memory area allocated for holding the collision mask of that GEL. This area must be in Chip memory and its size is the equivalent of one bitplane of the GEL's image. The collision mask is ''usually'' the same as the shadow mask of the GEL, formed from a logical-'''OR''' combination of all planes of the image. The following figure shows an example collision mask.

[[File:LibFig28-3.png|frame|center|A Collision Mask]]

Alternatively, you may have a collision mask that is not derived from the image. In this case, the actual image isn't relevant. The system will not register collisions unless the other objects touch the collision mask. If the collision mask is smaller than the image, other objects will pass through the edges without a collision.

==== VSprite BorderLine ====

For faster collision detection, the system uses the BorderLine member of the VSprite structure. BorderLine specifies the location of the horizontal logical-'''OR''' combination of all of the bits of the object. It may be compared to taking the whole object's shadow/collision mask and squishing it down into a single horizontal line. You provide the system with a place to store this line. The size of the data area you allocate must be at least as large as the image width.

In other words, if it takes three 16-bit words to hold one line of a GEL, then you must reserve three words for the BorderLine. In the VSprite examples, the routine makeVSprite() correctly allocates and initializes the collision mask and borderline. For example:

<syntaxhighlight lang="C" line>
WORD myBorderLineData[3]; /* reserve space for BorderLine for this Bob */

myVSprite.BorderLine = myBorderLineData; /* tell the system where it is */
</syntaxhighlight>

Here is a sample of an object and its BorderLine image:

<pre>
011000001100 Object
001100011000
001100011000
000110110000
000010100000

011110111100 BorderLine image
</pre>

Using this squished image, the system can quickly determine if the image is touching the left or rightmost boundary of the drawing area.

To establish default BorderLine and CollMask data, call the InitMasks() function.

==== VSprite HitMask and MeMask ====

Software collision detection is independently enabled and disabled for each GEL. Further, you can specify which of 16 possible collision routines you wish to have automatically executed. DoCollision(), in addition to sensing an overlap between objects, uses these masks to determine which routine (if any) the system will call when a collision occurs.

When the system determines a collision, it performs a logical-'''AND''' of the HitMask of the upper-leftmost object in the colliding pair with the MeMask of the lower-rightmost object of the pair. The bits that are 1s after the logical-'''AND''' operation choose which one of the 16 possible collision routines to perform.

* If the collision is with the boundary, bit 0 is always a 1 and the system calls the collision handling routine number 0. Always assign the routine that handles boundary collisions to vector 0 in the collision handling table.

* The system uses the flag called BORDERHIT to indicate that an object has landed on or moved beyond the outermost bounds of the drawing area (the edge of the clipping region). The VSprite example earlier in this article uses collision detection to check for border hits.

* If any one of the other bits (1 to 15) is set, then the system calls your collision handling routine corresponding to the bit set.

* If more than one bit is set in both masks, the system calls the vector corresponding to the rightmost (the least significant) bit ''only''.

==== Using HitMask and MeMask ====

This section illustrates the use of the HitMask and MeMask to define one type of collision.

Suppose there are two classes of objects that you wish to control on the display: ENEMYTANK and MYMISSILE. Objects of class ENEMYTANK should be able to pass across one another without registering any collisions. Objects of class MYMISSILE should also be able to pass across one another without collisions. However, when MYMISSILE and ENEMYTANK collide, the system should generate a call to a collision routine.

Choose a pair of collision detect bits not yet assigned within MeMask, one to represent ENEMYTANK, the other to represent MYMISSILE. You will use the same two bits in the corresponding HitMask. In this example, bit 1 represents ENEMYTANK objects and bit 2 represents MYMISSLE objects.

{| class="wikitable"
!
! colspan="2"|MeMask
! colspan="2"|HitMask
|-
! Bit Number !! 2 !! 1 !! 2 !! 1
|-
| ENEMYTANK 1 || align="center"|0 || align="center"|1 || align="center"|1 || align="center"|0
|-
| ENEMYTANK 2 || align="center"|0 || align="center"|1 || align="center"|1 || align="center"|0
|-
| MYMISSLE || align="center"|1 || align="center"|0 || align="center"|0 || align="center"|1
|}

In the MeMask, bit 1 is set to indicate that this object is an ENEMYTANK. Bit 2 is clear (zero) indicating this object is ''not'' a MYMISSILE object. In the HitMask for ENEMYTANK objects, bit 1 is clear (zero) which means, "I will not register collisions with other ENEMYTANK objects." However, bit 2 is set (one) which means, "I ''will'' register collisions with MYMISSILE objects."

Thus when a call to DoCollision() occurs, for any objects that appear to be colliding, the system '''AND'''s the MeMask of one object with the HitMask of the other object. If there are non-zero bits present, the system will call one of your collision routines.

In this example, suppose that the system senses a collision between ENEMYTANK 1 and ENEMYTANK 2. Suppose also that ENEMYTANK 1 is the top/leftmost object of the pair. Here is the way that the collision testing routine performs the test to see if the system will call any collision-handling routines:

{| class="wikitable"
! Bit Number !! 2 !! 1
|-
| ENEMYTANK 1 MeMask || 0 || 1
|-
| ENEMYTANK 2 HitMask || 1 || 0
|-
| Result of logical-AND || 0 || 0
|}

Therefore, the system does not call a collision routine. But suppose that DoCollision() finds an overlap between ENEMYTANK 1 and MYMISSILE, where MYMISSILE is the top/leftmost of the pair:

{| class="wikitable"
! Bit Number !! 2 !! 1
|-
| MYMISSLE MeMask || 1 || 0
|-
| ENEMYTANK 2 HitMask || 1 || 0
|-
| Result of logical-AND || 1 || 0
|}

Therefore, the system calls the collision routine at position 2 in the table of collision-handling routines.

=== Setting up for Boundary Collisions ===

To specify the region in the playfield that the system will use to define the outermost limits of the GEL boundaries, you use these GelsInfo members: topmost, bottommost, leftmost, and rightmost.

The DoCollision() routine tests these boundaries when determining boundary collisions within this RastPort. They have nothing whatsoever to do with graphical clipping. Graphical clipping makes use of the RastPort's clipping rectangle.

Here is a typical program segment that assigns the members correctly (for boundaries 50, 100, 80, 240). It assumes that you already have a RastPort structure pointer named myRastPort.

<syntaxhighlight lang="C" line>
myRastPort->GelsInfo->topmost = 50;
myRastPort->GelsInfo->bottommost = 100;
myRastPort->GelsInfo->leftmost = 80;
myRastPort->GelsInfo->rightmost = 240;
</syntaxhighlight>

==== Parameters To Your Boundary Collision Routine ====

During the operation of the DoCollision() routine, if you have enabled boundary collisions for a GEL (by setting the least significant bit of its HitMask) and it has crossed a boundary, the system calls the boundary routine you have defined. The system will call the routine once for every GEL that has hit, or gone outside of the boundary. The system will call your routine with the following two arguments:

* A pointer to the VSprite structure of the GEL that hit the boundary
* A flag word containing one to four bits set, representing top, bottom, left and right boundaries, telling you which of the boundaries it has hit or exceeded.
* To test these bits, compare to the constants TOPHIT, BOTTOMHIT, LEFTHIT, and RIGHTHIT.

See the VSprite example given earlier for an example of using boundary collision.

==== Parameters To Your Inter-GEL Collision Routines ====

If, instead of a GEL-to-boundary collision, DoCollision() senses a GEL-to-GEL collision, the system calls your collision routine with the following two arguments:

* Address of the VSprite that is the uppermost (or leftmost if ''y'' coordinates are identical) GEL of a colliding pair.
* Address of the VSprite that is the lowermost (or rightmost if ''y'' coordinates are identical) GEL of the pair.

==== Handling Multiple Collisions ====

When multiple elements collide within the same display field, the following set of sequential calls to the collision routines occurs:

* The system issues each call in a sorted order for GELs starting at the upper left-hand corner of the screen and proceeding to the right and down the screen.
* For any colliding GEL pair, the system issues only one call, to the collision routine for the object that is the topmost and leftmost of the pair.

=== Adding User Extensions to GEL Data Structures ===

This section describes how to expand the size and scope of the VSprite, Bob and AnimOb data structures. In the definition for these structures, there is an item called UserExt at the end of each. If you want to expand these structures (to hold your own special data), you define the UserExt member before the <graphics/gels.h> file is included. If this member has already been defined when the <graphics/gels.h> file is parsed, the compiler preprocessor will extend the structure definition automatically. If these members have not been defined, the system will make them SHORTs, and you may still consider these as being reserved for your private use.

To show the kind of use you can make of this feature, the example below adds speed and acceleration figures to each GEL by extending the VSprite structure. When your collision routine is called, it could use these values to transfer energy between the two colliding objects (say, billiard balls). You would have to set up additional routines, executed between calls to DoCollision(), that would add the values to the GELs position appropriately. You could do this with code similar o the following:

<syntaxhighlight lang="C" line>
struct myInfo
{
short xvelocity;
short yvelocity;
short xaccel;
short yaccel;
};
</syntaxhighlight>

These members are for example only. You may use any definition for your user extensions. You would then also provide the following line, to extend the VSprites structure, use:

<syntaxhighlight lang="C" line>
/* Redefine VUserStuff for my own use. */
#define VUserStuff struct myInfo
</syntaxhighlight>

To extend the Bobs structure, use:

<syntaxhighlight lang="C" line>
#define BUserStuff struct myInfo
</syntaxhighlight>

To extend the AnimObs structure, use:

<syntaxhighlight lang="C" line>
#define AUserStuff struct myInfo
</syntaxhighlight>

When the system is compiling the <graphics/gels.h> file with your program, the compiler preprocessor substitutes "struct myInfo" everywhere that UserExt is used in the header. The structure is thereby customized to include the items you wish to associate with it.

{{Note|title=Typedef Cannot Be Used|text=You cannot use the C-language construct typedef for the above statements. If you want to substitute your own data type for one of the UserStuff variables, you must use a #define.}}

== Animation with GELs ==

An animation sequence is composed of a series of drawings. Each drawing differs from the preceding one so that when they are arranged in a stack and viewed sequentially, the images appear to flow naturally.

In classic film animation, image drawing is done in two stages. The background for each scene is painted just once. Then, the cartoon characters and any other foreground objects are painted on transparent sheets of celluloid called ''cells'' which are placed over the background. With cells, animation can be achieved by redrawing only the parts of the scene that move while the background stays the same. Animation on the Amiga works similarly. The background is formed by the playfield while the objects that move can be conveniently handled with the GELs system.

=== Animation Data Structures ===

There are two main data structures involved in Amiga animation: AnimComp and AnimOb.

The AnimComp (Animation Component), is an extension of the Bob structure discussed in the previous section. An AnimComp provides a convenient way to link together a series of images so that they can be sequenced automatically, and so multiple sequences can be grouped together. An AnimComp is analogous to one sheet of celluloid representing a single image to be placed over the background.

<syntaxhighlight lang="C" line>
struct AnimComp
{
WORD Flags; /* AnimComp flags for system & user */
WORD Timer;
WORD TimeSet;
struct AnimComp *NextComp;
struct AnimComp *PrevComp;
struct AnimComp *NextSeq;
struct AnimComp *PrevSeq;
WORD (*AnimCRoutine)();
WORD YTrans;
WORD XTrans;
struct AnimOb *HeadOb; /* Pointer back to the controlling AnimOb */
struct Bob *AnimBob; /* Underlying Bob structure for this AnimComp */
};
</syntaxhighlight>

The AnimComp structure contains pointers, PrevSeq and NextSeq, that lets you group these cells into stacks that will be viewed sequentially. The AnimComp structure also has PrevComp and NextComp pointers that let you group stacks into complex objects containing multiple independently moving parts.

The second animation data structure is the AnimOb which provides the variables needed for overall control over a group of AnimComps. The AnimOb itself contains no imagery; it simply provides a common reference point for the sequenced images and specifies how the system should move that point.

<syntaxhighlight lang="C" line>
struct AnimOb
{
struct AnimOb *NextOb, *PrevOb;
LONG Clock;
WORD AnOldY, AnOldX; /* old y,x coordinates */
WORD AnY, AnX; /* y,x coordinates of the AnimOb*/
WORD YVel, XVel; /* velocities of this object */
WORD YAccel, XAccel; /* accelerations of this object */
WORD RingYTrans, RingXTrans; /* ring translation values */
WORD (*AnimORoutine)(); /* address of user procedure */
struct AnimComp *HeadComp; /* pointer to first component */
AUserStuff AUserExt; /* AnimOb user extension */
};
</syntaxhighlight>

These structures can be used in various ways. A simple animation of a rotating ball could be created with three or four AnimComps linked together in a circular list by their NextSeq and PrevSeq fields. The system displays the initial AnimComp (the "top of the stack"), then switches to the AnimComp pointed to by NextSeq, and then switches to ''its'' NextSeq and so on until it reaches the end of the sequence. The sequence starts over again automatically if the last AnimComp.NextSeq points back to the first AnimComp in the stack.

For a more complex animation of a walking human, you could use five stacks, i.e., five circular lists of AnimComps; four stacks for the arms and legs and a single stack for the head and torso. To group these stacks into one cohesive unit showing a human figure, you use the PrevComp and NextComp pointers in the AnimComp structure. All the stacks would also share a common AnimOb, so that the combined sequences can be moved as a single object.

[[File:LibFig28-4.png|frame|center|Linking AnimComps For a Multiple Component AnimOb]]

=== Animation Types ===

The GELs system provides several ways of setting up automatic animation, loosely based on some categories of movement in real life. Some things (like balls or arrows) can move independently of the background, and look even more realistic if they tumble or rotate as they move; other things (like worms, wheels, and people) must be anchored to the background, or they will appear to ''slide'' unnaturally.

The system software allows these types of animation through simple motion control, motion control with sequenced drawing, and sequenced drawing using Ring Motion Control.

==== Simple Motion Control ====

To produce motion of a simple object, such as a ball, the object is simply moved relative to a background display, a little at a time. This is simple motion control, and can be accomplished with one AnimComp and one AnimOb, by simply changing the AnimOb's position every N video frames. The apparent speed of the object is a combination of how often it is moved (every frame, every other frame, etc.) and how far it is moved (how much the AnimOb's AnX and AnY are changed).

==== Sequenced Drawing ====

To make the ball appear to rotate is a little more complex. To produce apparent movement within the image, sequencing is used. This is done by having a stack of AnimComp's that are laid down one after the other, a frame at a time. The stack can be arranged in a circular list for repeating movement. So, when you combine a sequence of drawings using AnimComps with simple motion control using an AnimOb, you can perform more complex animations such as having a rotating ball bounce around.

==== Ring Motion Control ====

Making a worm appear to crawl is similar to the rotating ball. There is still a stack of AnimComps that are sequenced automatically, and one controlling AnimOb. But each AnimCop image is drawn so that it appears to move relative to an internal point that remains stationary throughout the stack. So instead of the Anim's common reference point moving in each frame, you tell the system how far to move only ''at the end'' of each AnimComp sequence.

[[File:LibFig28-5.png|frame|center|Ring Motion Control]]

As illustrated in the figure, the sequence of events for Ring Motion Control look like this:

Draw AnimComp1, Draw AnimComp2, Draw AnimComp3, Move AnimOb, 
Draw AnimComp1, Draw AnimComp2, Draw AnimComp3, Move AnimOb, 
Draw AnimComp1 ...

=== Specifying Animation Components ===

For each AnimComp, you initially specify:

* A pointer to the AnimComp's controlling AnimOb.
* Initial and alternate views, their timing and order.
* The initial inter-component drawing priorities (for multiple AnimComp sequences, this specifies which sequence to display frontmost).
* A pointer to a special animation routine related to this component (optional).
* Your own extensions to this structure (optional).

==== Sequencing AnimComps ====

To specify the sequencing of AnimComp images, the pointers called PrevSeq and NextSeq are used to build a doubly-linked list. The sequence can be made circular (and usually is) by linking the first and last AnimComps in the sequence: the NextSeq of the last AnimComp must point back to the first AnimComp, and the PrevSeq of the first AnimComp must point to the last AnimComp. If the list is a loop, then the system will continue to cycle through the list until it is stopped. If the list is not a loop, then the program must act to restart the sequence after the last item is displayed. The AnimCRoutine field of the last AnimComp can be used to do this.

==== Position of an AnimComp ====

To specify the placement of each AnimComp relative to its controlling AnimOb, you set the AnimComp members XTrans and YTrans. These values can be positive or negative.

The system is designed so that only one of the AnimComps in any given sequence is "active" (being displayed) at a given point in time. It is the only image in the sequence that is (or is about to be) linked into the GelsInfo list. The Timer determines how long each Component in the sequence remains active, as described below.

==== Specifying Time for Each Image ====

The AnimComp members Timer and TimeSet are used to specify how long the system should keep each sequential image on the screen.

When the system makes an animation component active, it copies the value you have put in the TimeSet member into the Timer member. As the animation proceeds, the system decrements Timer; as long as it is greater than zero, then that AnimComp remains active. When the Timer value reaches zero, the system makes the next AnimComp in the sequence active, and the process repeats.

If you initialize the value in TimeSet to zero, the system will ''not sequence this component at all'' (and Timer will remain zero).

==== Linking Multiple AnimComp Sequences ====

When an AnimOb is built from multiple AnimComp sequences, the sequences are linked together by the the PrevComp and NextComp fields of the AnimComps. These pointers must be initialized ''only in the initial'' AnimComp ''of each sequence''. The other components that are not initially active should have their PrevComp and NextComp pointers set to NULL.

{{Note|title=Do Not Use Empty Fields|text=You cannot store data in the empty PrevComp and NextComp fields. As the system cycles through the AnimComps, the NextComp and PrevComp fields are set to NULL when an old AnimComps is replaced by a new AnimComp. The new AnimComp is then linked in to the list of sequences ''in place of the old one''.}}

==== Component Ordering ====

The PrevSeq, NextSeq, PrevComp and NextComp linkages have no bearing on the order in which AnimComps in any given video frame are drawn. To specify the inter-component priorities (so that the closest objects appear frontmost) the Before and After pointers in the initially active AnimComp's underlying Bob structure are linked in to the rest of the system, as described previously in the discussion of Bobs.

This setup needs to be done once, ''for the initially active AnimComps of the AnimOb only''.

The animation system adjusts the Before and After pointers of all the underlying Bob structures to constantly maintain the inter-component drawing sequence, even though different components are being made active as sequencing occurs.

These pointers also assure that one complete ''object'' always has priority over another object. The Bob Before and After pointers are used to link together the last AnimComp's Bob of one AnimOb to the first AnimComp's Bob of the next AnimOb.

=== Specifying the Animation Object ===

For each AnimOb, you initially specify:

* The starting position of this object
* Its velocity and acceleration (optional).
* A pointer to the first of its AnimComps.
* A pointer to a special animation routine related to this object (optional).
* Your own extensions to this structure (optional).

==== Linking the AnimComp Sequences to the AnimOb ====

Within each AnimOb there may be one or more AnimComp sequences. The HeadComp of the AnimOb points to the first AnimComp in the list of sequences.

Each sequence is identified by its "active" AnimComp. There can only be one active AnimComp in each sequence. The sequences are linked together by their active AnimComps; for each of these the NextComp and PrevComp fields link the sequences together to create a list. The first sequence in the list (HeadComp of the AnimOb), has its PrevComp set to NULL. The last sequence in the list has its NextComp set to NULL. None of the inactive AnimComps should have NextComp or PrevComp fields set.

To find the active AnimComp at run time, you can look in the AnimOb's HeadComp field. To find the active AnimComp from any another AnimComp, use the HeadOb field to find the controlling AnimOb first and then look in its HeadComp field to find the active AnimComp.

The figure below shows all the linkages in data structures needed to create the animation GELs.

[[File:LibFig28-6.png|frame|center|Linking of an AnimOb]]

==== Position of an AnimOb ====

To position the object and its component parts, use the AnimOb structure members AnX and AnY. The following figure illustrates how each component has its own offset from the AnimOb's common reference point.

[[File:LibFig28-7.png|frame|center|Specifying an AnimOb Position]]

When you change the animation object's AnX and AnY, all of the component parts will be redrawn relative to it the next time DrawGList() is called.

==== Setting Up Simple Motion Control ====

In this form of animation, you can specify objects that have independently controllable velocities and accelerations in the ''X'' and ''Y'' directions. Components can still sequence.

The variables that control this motion are located in the AnimOb structure and are called:

; YVel, XVel
: the velocities in the ''y'' and ''x'' directions. These values are added to the position values on each call to Animate() (see below).

; YAccel, XAccel
: the accelerations in the ''x'' and ''y'' directions. These values are added to the velocity values on each call to Animate() (see below). The velocity values are updated ''before'' the position values.

==== Setting Up Ring Motion Control ====

To make a given component ''trigger'' a move of the AnimOb you set the RINGTRIGGER bit of that AnimComp's Flags field.

When the system software encounters this flag, it adds the values of RingXTrans and RingYTrans to the AnX and AnY values of the controlling AnimOb. The ''next'' time you execute DrawGList(), the drawing sequence will use the new position.

You usually set RINGTRIGGER in only one of the animation components in a sequence (the last one); however, you can use this flag and the translation variables any way you wish.

==== Using Sequenced Drawing and Motion Control ====

If you are using Ring Motion Control, you will probably set the velocity and acceleration variables to zero. For instance, consider the example of a person walking. With Ring Motion Control, as each foot falls it is positioned on the ground exactly where originally drawn. If you included a velocity value, the person's foot would not be stationary with respect to the ground, and the person would appear to "skate" rather than walk. If you set the velocity and acceleration variables at zero, you avoid this problem.

When the system activates a new AnimComp, it checks the Flags field to see if the RINGTRIGGER bit is set. If so, the system adds RingYTrans and RingXTrans to AnY and AnX respectively.

=== The AnimKey ===

The system uses one pointer, known as the AnimKey, to keep track of all the AnimObs via their PrevOb and NextOb linkage fields. The AnimKey acts as the anchor for the list of AnimObs you are using and is initialized with code such as the following:

<syntaxhighlight lang="C" line>
struct AnimOb *animKey;

IGraphics->InitAnimate(&animKey); /* Only do this once to initialize the AnimOb list */
</syntaxhighlight>

As each new object is added (via AddAnimOb()), it is linked in at the beginning of the list, so AnimKey will always point to the object most recently added to the list. To search forward through the list, start with the AnimKey and move forward on the NextOb link. Continue to move forward until the NextOb is NULL, indicating the end of the list. The PrevOb link will allow you to move back to a previous object.

{{Note|title=Set Up PrevOb and NextOb Correctly|text=It is important that the NextOb link of the last object is NULL, and that the PrevOb of the first object is NULL. In fact, the system expects the animation object lists to be ''exactly'' the way that they are described above. If they are not, the system will produce unexpected results.}}

=== Adding Animation Objects ===

Use the routine AddAnimOb() to add animation objects to the controlled object list. This routine will link the PrevOb and NextOb pointers to chain all the AnimObs that the system is controlling.

<syntaxhighlight lang="C" line>
struct RastPort myRPort;
struct AnimOb myAnimOb;
struct AnimOb *animKey; /* Must be initialized with InitAnimate() */

IGraphics->AddAnimOb(&myAnimOb, &animKey, &myRPort);
</syntaxhighlight>

=== Moving the Objects ===

When you have defined all of the structures and have established all of the links, you can call the Animate() routine to move the objects. Animate() adjusts the positions of the objects as described above, and calls the various subroutines (AnimCRoutines and AnimORoutines) that you have specified.

After the system has completed the Animate() routine, some GELs may have been moved, so the GelsInfo list order may possibly be incorrect. Therefore, the list must be re-sorted with SortGList() before passing it to a system routine.

If you are using collision detection, you then perform DoCollision(). Your collision routines may also have an effect on the relative position of the GELs. Therefore, you should again call SortGList() to assure that the system correctly orders the objects before you call DrawGList().

When you call DrawGList(), the system renders all the GELs it finds in the GelsInfo list and any changes caused by the previous call to Animate() can then be seen.

This is illustrated in the following typical call sequence:

<syntaxhighlight lang="C" line>
struct AnimOb **myAnimKey;
struct RastPort *rp;
struct ViewPort *vp;

/* ... setup of graphics elements and objects */

IGraphics->Animate(myAnimKey, rp); /* "move" objects per instructions */
IGraphics->SortGList(rp); /* put them in order */
IGraphics->DoCollision(rp); /* software collision detect/action */
IGraphics->SortGList(rp); /* put them back into right order */
IGraphics->DrawGList(vp, rp); /* draw into current RastPort */
</syntaxhighlight>

==== Your own Animation Routine Calls ====

The AnimOb and AnimComp structures can include pointers for your own routines that you want the system to call. These pointers are stored in the AnimOb's AnimORoutine field and in the AnimComp's AnimCRoutine field, respectively.

When Animate() is called, the system performs the following steps for every AnimOb in the AnimKey list:

* Updates the AnimOb's location and velocities.
* Calls the AnimOb.AnimORoutine routine if one is supplied.
* Then for each AnimComp of the AnimOb:
** If this sequence times out, switches to the new AnimComp.
** Calls the AnimComp.AnimCRoutine if one is supplied.
** Sets the underlying VSprite's ''x,y'' coordinates.

If you want a routine to be called, you put the address of the routine in either AnimComp.AnimCRoutine or AnimOb.AnimORoutine member as needed. If no routine is to be called, you must set these fields to NULL. Your routines will be passed one parameter, a pointer to the AnimOb or AnimComp it was related to. You can use the user structure extensions discussed earlier to hold the variables you need for your own routines.

For example, if you provide a routine such as this:

<syntaxhighlight lang="C" line>
VOID MyOCode(struct AnimOb *anOb)
{
/* whatever needs to be done */
}
</syntaxhighlight>

Then, if you put the address of the routine in an AnimOb structure:

<syntaxhighlight lang="C" line>
myAnimOb.AnimORoutine = MyOCode;
</syntaxhighlight>

MyOCode() will be called with the address of this AnimOb when Animate() processes this AnimOb.

=== Standard GEL Rules Still Apply ===

Before you use the animation system, you must have called the routine InitGels(). The section called "Bob Priorities" describes how the system maintains the list of GELs to draw on the screen according to their various data fields. The animation system selectively adds GELs to and removes GELs from this list of screen objects during the Animate() routine. On the next call to DrawGList(), the system will draw the GELs in the list into the selected RastPort.

=== Animations Special Numbering System ===

Velocities and accelerations can be either positive or negative. The system treats the velocity, acceleration and Ring values as fixed-point binary fractions, with the decimal point at position 6 in the word. That is: vvvvvvvvvv.ffffff where v stands for actual values that you add to the x or y (AnX, AnY) positions of the object for each call to Animate(), and f stands for the fractional part. By using a fractional part, you can specify the speed of an object in increments as precise as 1/64th of an interval.

If you set the value of XVel at 0x0001, it will take 64 calls to the Animate() routine before the system will modify the object's ''x'' coordinate position by a step of one.

The system constant ANFRACSIZE can be used to shift values correctly. So if you set the value to (1 << ANFRACSIZE), it will be set to 0x0040, the value required to move the object one step per call to Animate().

The system constant ANIMHALF can be used if you want the object to move every other call to Animate().

Each call you make to Animate() simply adds the value of XAccel to the current value of XVel, and YAccel to the current value of YVel, modifying these values accordingly.

=== "animtools.h" and "animtools.c" ===

Here is the listing of the "animtools.h" header file and the "animtools.c" link file used by the examples in this article. The makeSeq() and makeComp() subroutines here demonstrate how to use the GELs animation system.

<pre>
/* animtools.h */
#ifndef GELTOOLS_H
#define GELTOOLS_H

/*
** These data structures are used by the functions in animtools.c to
** allow for an easier interface to the animation system.
*/

/* Data structure to hold information for a new VSprite. */
typedef struct newVSprite {
WORD *nvs_Image; /* image data for the vsprite */
WORD *nvs_ColorSet; /* color array for the vsprite */
SHORT nvs_WordWidth; /* width in words */
SHORT nvs_LineHeight; /* height in lines */
SHORT nvs_ImageDepth; /* depth of the image */
SHORT nvs_X; /* initial x position */
SHORT nvs_Y; /* initial y position */
SHORT nvs_Flags; /* vsprite flags */
USHORT nvs_HitMask; /* Hit mask. */
USHORT nvs_MeMask; /* Me mask. */
} NEWVSPRITE;

/* Data structure to hold information for a new Bob. */
typedef struct newBob {
WORD *nb_Image; /* image data for the bob */
SHORT nb_WordWidth; /* width in words */
SHORT nb_LineHeight; /* height in lines */
SHORT nb_ImageDepth; /* depth of the image */
SHORT nb_PlanePick; /* planes that get image data */
SHORT nb_PlaneOnOff; /* unused planes to turn on */
SHORT nb_BFlags; /* bob flags */
SHORT nb_DBuf; /* 1=double buf, 0=not */
SHORT nb_RasDepth; /* depth of the raster */
SHORT nb_X; /* initial x position */
SHORT nb_Y; /* initial y position */
USHORT nb_HitMask; /* Hit mask. */
USHORT nb_MeMask; /* Me mask. */
} NEWBOB ;

/* Data structure to hold information for a new animation component. */
typedef struct newAnimComp {
WORD (*nac_Routine)(); /* routine called when Comp is displayed. */
SHORT nac_Xt; /* initial delta offset position. */
SHORT nac_Yt; /* initial delta offset position. */
SHORT nac_Time; /* Initial Timer value. */
SHORT nac_CFlags; /* Flags for the Component. */
} NEWANIMCOMP;

/* Data structure to hold information for a new animation sequence. */
typedef struct newAnimSeq {
struct AnimOb *nas_HeadOb; /* common Head of Object. */
WORD *nas_Images; /* array of Comp image data */
SHORT *nas_Xt; /* arrays of initial offsets. */
SHORT *nas_Yt; /* arrays of initial offsets. */
SHORT *nas_Times; /* array of Initial Timer value. */
WORD (**nas_Routines)(); /* Array of fns called when comp drawn */
SHORT nas_CFlags; /* Flags for the Component. */
SHORT nas_Count; /* Num Comps in seq (= arrays size) */
SHORT nas_SingleImage; /* one (or count) images. */
} NEWANIMSEQ;

#define INTUITIONNAME "intuition.library" /* intuitionbase.h does not define a library name. */

#include "animtools_proto.h" /* Include Prototyping. */
#endif

/* animtools_proto.h */
#include <clib/dos_protos.h>
#include <clib/exec_protos.h>
#include <clib/graphics_protos.h>
#include <clib/intuition_protos.h>

struct GelsInfo *setupGelSys(struct RastPort *rPort, BYTE reserved);
VOID cleanupGelSys(struct GelsInfo *gInfo, struct RastPort *rPort);
struct VSprite *makeVSprite(NEWVSPRITE *nVSprite);
struct Bob *makeBob(NEWBOB *nBob);
struct AnimComp *makeComp(NEWBOB *nBob, NEWANIMCOMP *nAnimComp);
struct AnimComp *makeSeq(NEWBOB *nBob, NEWANIMSEQ *nAnimSeq);
VOID freeVSprite(struct VSprite *vsprite);
VOID freeBob(struct Bob *bob, LONG rasdepth);
VOID freeComp(struct AnimComp *myComp, LONG rasdepth);
VOID freeSeq(struct AnimComp *headComp, LONG rasdepth);
VOID freeOb(struct AnimOb *headOb, LONG rasdepth);

/* animtools.c
**
** This file is a collection of tools which are used with the VSprite, Bob and Animation
** system software. It is intended as a useful EXAMPLE, and while it shows what must be
** done, it is not the only way to do it. If Not Enough Memory, or error return, each
** cleans up after itself before returning. NOTE that these routines assume a very specific
** structure to the GEL lists. Make sure that you use the correct pairs together
** (i.e. makeOb()/freeOb(), etc.)
**
** Compile with SAS/C 5.10b: lc -b1 -cfist -v -y -oanimtools.o animtools.c
*/
#include <exec/types.h>
#include <exec/memory.h>
#include <graphics/gfx.h>
#include <graphics/gels.h>
#include <graphics/clip.h>
#include <graphics/rastport.h>
#include <graphics/view.h>
#include <graphics/gfxbase.h>
#include "animtools.h"

/* Setup the GELs system. After this call is made you can use VSprites, Bobs, AnimComps
** and AnimObs. Note that this links the GelsInfo structure into the RastPort, and calls
** InitGels(). It uses information in your RastPort structure to establish boundary collision
** defaults at the outer edges of the raster. This routine sets up for everything - collision
** detection and all. You must already have run LoadView before ReadyGelSys is called.
*/
struct GelsInfo *setupGelSys(struct RastPort *rPort, BYTE reserved)
{
struct GelsInfo *gInfo;
struct VSprite *vsHead;
struct VSprite *vsTail;

if (NULL != (gInfo = (struct GelsInfo *)AllocMem(sizeof(struct GelsInfo), MEMF_CLEAR)))
{
if (NULL != (gInfo->nextLine = (WORD *)AllocMem(sizeof(WORD) * 8, MEMF_CLEAR)))
{
if (NULL != (gInfo->lastColor = (WORD **)AllocMem(sizeof(LONG) * 8, MEMF_CLEAR)))
{
if (NULL != (gInfo->collHandler = (struct collTable *)
AllocMem(sizeof(struct collTable),MEMF_CLEAR)))
{
if (NULL != (vsHead = (struct VSprite *)
AllocMem((LONG)sizeof(struct VSprite), MEMF_CLEAR)))
{
if (NULL != (vsTail = (struct VSprite *)
AllocMem(sizeof(struct VSprite), MEMF_CLEAR)))
{
gInfo->sprRsrvd = reserved;
/* Set left- and top-most to 1 to better keep items */
/* inside the display boundaries. */
gInfo->leftmost = gInfo->topmost = 1;
gInfo->rightmost = (rPort->BitMap->BytesPerRow << 3) - 1;
gInfo->bottommost = rPort->BitMap->Rows - 1;
rPort->GelsInfo = gInfo;
InitGels(vsHead, vsTail, gInfo);
return(gInfo);
}
FreeMem(vsHead, (LONG)sizeof(*vsHead));
}
FreeMem(gInfo->collHandler, (LONG)sizeof(struct collTable));
}
FreeMem(gInfo->lastColor, (LONG)sizeof(LONG) * 8);
}
FreeMem(gInfo->nextLine, (LONG)sizeof(WORD) * 8);
}
FreeMem(gInfo, (LONG)sizeof(*gInfo));
}
return(NULL);
}

/* Free all of the stuff allocated by setupGelSys(). Only call this routine if
** setupGelSys() returned successfully. The GelsInfo structure is the one returned
** by setupGelSys(). It also unlinks the GelsInfo from the RastPort.
*/
VOID cleanupGelSys(struct GelsInfo *gInfo, struct RastPort *rPort)
{
rPort->GelsInfo = NULL;
FreeMem(gInfo->collHandler, (LONG)sizeof(struct collTable));
FreeMem(gInfo->lastColor, (LONG)sizeof(LONG) * 8);
FreeMem(gInfo->nextLine, (LONG)sizeof(WORD) * 8);
FreeMem(gInfo->gelHead, (LONG)sizeof(struct VSprite));
FreeMem(gInfo->gelTail, (LONG)sizeof(struct VSprite));
FreeMem(gInfo, (LONG)sizeof(*gInfo));
}

/* Create a VSprite from the information given in nVSprite. Use freeVSprite()
** to free this GEL.
*/
struct VSprite *makeVSprite(NEWVSPRITE *nVSprite)
{
struct VSprite *vsprite;
LONG line_size;
LONG plane_size;

line_size = sizeof(WORD) * nVSprite->nvs_WordWidth;
plane_size = line_size * nVSprite->nvs_LineHeight;

if (NULL != (vsprite = (struct VSprite *)AllocMem((LONG)sizeof(struct VSprite), MEMF_CLEAR)))
{
if (NULL != (vsprite->BorderLine = (WORD *)AllocMem(line_size, MEMF_CHIP)))
{
if (NULL != (vsprite->CollMask = (WORD *)AllocMem(plane_size, MEMF_CHIP)))
{
vsprite->Y = nVSprite->nvs_Y;
vsprite->X = nVSprite->nvs_X;
vsprite->Flags = nVSprite->nvs_Flags;
vsprite->Width = nVSprite->nvs_WordWidth;
vsprite->Depth = nVSprite->nvs_ImageDepth;
vsprite->Height = nVSprite->nvs_LineHeight;
vsprite->MeMask = nVSprite->nvs_MeMask;
vsprite->HitMask = nVSprite->nvs_HitMask;
vsprite->ImageData = nVSprite->nvs_Image;
vsprite->SprColors = nVSprite->nvs_ColorSet;
vsprite->PlanePick = vsprite->PlaneOnOff = 0x00;
InitMasks(vsprite);
return(vsprite);
}
FreeMem(vsprite->BorderLine, line_size);
}
FreeMem(vsprite, (LONG)sizeof(*vsprite));
}
return(NULL);
}

/* Create a Bob from the information given in nBob. Use freeBob() to free this GEL.
** A VSprite is created for this bob. This routine properly allocates all double
** buffered information if it is required.
*/
struct Bob *makeBob(NEWBOB *nBob)
{
struct Bob *bob;
struct VSprite *vsprite;
NEWVSPRITE nVSprite ;
LONG rassize;

rassize = (LONG)sizeof(UWORD) * nBob->nb_WordWidth * nBob->nb_LineHeight * nBob->nb_RasDepth;

if (NULL != (bob = (struct Bob *)AllocMem((LONG)sizeof(struct Bob), MEMF_CLEAR)))
{
if (NULL != (bob->SaveBuffer = (WORD *)AllocMem(rassize, MEMF_CHIP)))
{
nVSprite.nvs_WordWidth = nBob->nb_WordWidth;
nVSprite.nvs_LineHeight = nBob->nb_LineHeight;
nVSprite.nvs_ImageDepth = nBob->nb_ImageDepth;
nVSprite.nvs_Image = nBob->nb_Image;
nVSprite.nvs_X = nBob->nb_X;
nVSprite.nvs_Y = nBob->nb_Y;
nVSprite.nvs_ColorSet = NULL;
nVSprite.nvs_Flags = nBob->nb_BFlags;
/* Push the values into the NEWVSPRITE structure for use in makeVSprite(). */
nVSprite.nvs_MeMask = nBob->nb_MeMask;
nVSprite.nvs_HitMask = nBob->nb_HitMask;

if ((vsprite = makeVSprite(&nVSprite)) != NULL)
{
vsprite->PlanePick = nBob->nb_PlanePick;
vsprite->PlaneOnOff = nBob->nb_PlaneOnOff;
vsprite->VSBob = bob;
bob->BobVSprite = vsprite;
bob->ImageShadow = vsprite->CollMask;
bob->Flags = 0;
bob->Before = NULL;
bob->After = NULL;
bob->BobComp = NULL;

if (nBob->nb_DBuf)
{
if (NULL != (bob->DBuffer = (struct DBufPacket *)
AllocMem((LONG)sizeof(struct DBufPacket), MEMF_CLEAR)))
{
if (NULL != (bob->DBuffer->BufBuffer = (WORD *)AllocMem(rassize, MEMF_CHIP)))
return(bob);
FreeMem(bob->DBuffer, (LONG)sizeof(struct DBufPacket));
}
}
else
{
bob->DBuffer = NULL;
return(bob);
}
freeVSprite(vsprite);
}
FreeMem(bob->SaveBuffer, rassize);
}
FreeMem(bob, (LONG)sizeof(*bob));
}
return(NULL);
}

/*
** Create a Animation Component from the information given in nAnimComp and nBob. Use
** freeComp() to free this GEL. makeComp() calls makeBob(), and links the Bob into an AnimComp.
*/
struct AnimComp *makeComp(NEWBOB *nBob, NEWANIMCOMP *nAnimComp)
{
struct Bob *compBob;
struct AnimComp *aComp;

if ((aComp = AllocMem((LONG)sizeof(struct AnimComp),MEMF_CLEAR)) != NULL)
{
if ((compBob = makeBob(nBob)) != NULL)
{
compBob->After = compBob->Before = NULL;
compBob->BobComp = aComp; /* Link 'em up. */
aComp->AnimBob = compBob;
aComp->TimeSet = nAnimComp->nac_Time; /* Num ticks active. */
aComp->YTrans = nAnimComp->nac_Yt; /* Offset rel to HeadOb */
aComp->XTrans = nAnimComp->nac_Xt;
aComp->AnimCRoutine = nAnimComp->nac_Routine;
aComp->Flags = nAnimComp->nac_CFlags;
aComp->Timer = 0;
aComp->NextSeq = aComp->PrevSeq = NULL;
aComp->NextComp = aComp->PrevComp = NULL;
aComp->HeadOb = NULL;
return(aComp);
}
FreeMem(aComp, (LONG)sizeof(struct AnimComp));
}
return(NULL);
}

/* Create an Animation Sequence from the information given in nAnimSeq and nBob. Use
** freeSeq() to free this GEL. This routine creates a linked list of animation components
** which make up the animation sequence. It links them all up, making a circular list of
** the PrevSeq and NextSeq pointers. That is to say, the first component of the sequences'
** PrevSeq points to the last component; the last component of * the sequences' NextSeq
** points back to the first component. If dbuf is on, the underlying Bobs will be set up
** for double buffering. If singleImage is non-zero, the pImages pointer is assumed to
** point to an array of only one image, instead of an array of 'count' images, and all
** Bobs will use the same image.
*/
struct AnimComp *makeSeq(NEWBOB *nBob, NEWANIMSEQ *nAnimSeq)
{
int seq;
struct AnimComp *firstCompInSeq = NULL;
struct AnimComp *seqComp = NULL;
struct AnimComp *lastCompMade = NULL;
LONG image_size;
NEWANIMCOMP nAnimComp;

/* get the initial image. this is the only image that is used
** if nAnimSeq->nas_SingleImage is non-zero.
*/
nBob->nb_Image = nAnimSeq->nas_Images;
image_size = nBob->nb_LineHeight * nBob->nb_ImageDepth * nBob->nb_WordWidth;

/* for each comp in the sequence */
for (seq = 0; seq < nAnimSeq->nas_Count; seq++)
{
nAnimComp.nac_Xt = *(nAnimSeq->nas_Xt + seq);
nAnimComp.nac_Yt = *(nAnimSeq->nas_Yt + seq);
nAnimComp.nac_Time = *(nAnimSeq->nas_Times + seq);
nAnimComp.nac_Routine = nAnimSeq->nas_Routines[seq];
nAnimComp.nac_CFlags = nAnimSeq->nas_CFlags;
if ((seqComp = makeComp(nBob, &nAnimComp)) == NULL)
{
if (firstCompInSeq != NULL)
freeSeq(firstCompInSeq, (LONG)nBob->nb_RasDepth);
return(NULL);
}
seqComp->HeadOb = nAnimSeq->nas_HeadOb;
/* Make a note of where the first component is. */
if (firstCompInSeq == NULL) firstCompInSeq = seqComp;
/* link the component into the list */
if (lastCompMade != NULL) lastCompMade->NextSeq = seqComp;
seqComp->NextSeq = NULL;
seqComp->PrevSeq = lastCompMade;
lastCompMade = seqComp;
/* If nAnimSeq->nas_SingleImage is zero, the image array has nAnimSeq->nas_Count images. */
if (!nAnimSeq->nas_SingleImage)
nBob->nb_Image += image_size;
}
/* On The last component in the sequence, set Next/Prev to make */
/* the linked list a loop of components. */
lastCompMade->NextSeq = firstCompInSeq;
firstCompInSeq->PrevSeq = lastCompMade;

return(firstCompInSeq);
}

/* Free the data created by makeVSprite(). Assumes images deallocated elsewhere. */
VOID freeVSprite(struct VSprite *vsprite)
{
LONG line_size;
LONG plane_size;

line_size = (LONG)sizeof(WORD) * vsprite->Width;
plane_size = line_size * vsprite->Height;
FreeMem(vsprite->BorderLine, line_size);
FreeMem(vsprite->CollMask, plane_size);
FreeMem(vsprite, (LONG)sizeof(*vsprite));
}

/* Free the data created by makeBob(). It's important that rasdepth match the depth you */
/* passed to makeBob() when this GEL was made. Assumes images deallocated elsewhere. */
VOID freeBob(struct Bob *bob, LONG rasdepth)
{
LONG rassize = sizeof(UWORD) * bob->BobVSprite->Width * bob->BobVSprite->Height * rasdepth;

if (bob->DBuffer != NULL)
{
FreeMem(bob->DBuffer->BufBuffer, rassize);
FreeMem(bob->DBuffer, (LONG)sizeof(struct DBufPacket));
}
FreeMem(bob->SaveBuffer, rassize);
freeVSprite(bob->BobVSprite);
FreeMem(bob, (LONG)sizeof(*bob));
}

/* Free the data created by makeComp(). It's important that rasdepth match the depth you */
/* passed to makeComp() when this GEL was made. Assumes images deallocated elsewhere. */
VOID freeComp(struct AnimComp *myComp, LONG rasdepth)
{
freeBob(myComp->AnimBob, rasdepth);
FreeMem(myComp, (LONG)sizeof(struct AnimComp));
}

/* Free the data created by makeSeq(). Complimentary to makeSeq(), this routine goes through
** the NextSeq pointers and frees the Components. This routine only goes forward through the
** list, and so it must be passed the first component in the sequence, or the sequence must
** be circular (which is guaranteed if you use makeSeq()). It's important that rasdepth match
** the depth you passed to makeSeq() when this GEL was made. Assumes images deallocated elsewhere!
*/
VOID freeSeq(struct AnimComp *headComp, LONG rasdepth)
{
struct AnimComp *curComp;
struct AnimComp *nextComp;

/* Break the NextSeq loop, so we get a NULL at the end of the list. */
headComp->PrevSeq->NextSeq = NULL;

curComp = headComp; /* get the start of the list */
while (curComp != NULL)
{
nextComp = curComp->NextSeq;
freeComp(curComp, rasdepth);
curComp = nextComp;
}
}

/* Free an animation object (list of sequences). freeOb() goes through the NextComp
** pointers, starting at the AnimObs' HeadComp, and frees every sequence. It only
** goes forward. It then frees the Object itself. Assumes images deallocated elsewhere!
*/
VOID freeOb(struct AnimOb *headOb, LONG rasdepth)
{
struct AnimComp *curSeq;
struct AnimComp *nextSeq;

curSeq = headOb->HeadComp; /* get the start of the list */
while (curSeq != NULL)
{
nextSeq = curSeq->NextComp;
freeSeq(curSeq, rasdepth);
curSeq = nextSeq;
}
FreeMem(headOb, sizeof(struct AnimOb));
}
</pre>

== Function Reference ==

The following are brief descriptions of the Amiga's graphics animation functions. See the SDK for details on each function call.

{| class="wikitable"
! Animation Function
! Description
|-
| AddAnimOb()
| Add an AnimOb to the linked list of AnimObs.
|-
| AddBob()
| Add a Bob to the current GEL list.
|-
| AddVSprite()
| Add a VSprite to the current GEL list.
|-
| Animate()
| Process every AnimOb in the current animation list.
|-
| ChangeSprite()
| Change the sprite image pointer.
|-
| DoCollision()
| Test every GEL in a GEL list for collisions.
|-
| DrawGList()
| Process the GEL list, queueing VSprites, drawing Bobs.
|-
| FreeGBuffers()
| Deallocate memory obtained by GetGBuffers().
|-
| FreeSprite()
| Return sprite for use by others and virtual sprite machine.
|-
| GetGBuffers()
| Attempt to allocate all buffers of an entire AnimOb.
|-
| GetSprite()
| Attempt to get a sprite for the simple sprite manager.
|-
| InitGels()
| Initialize a GEL list; must be called before using GELs.
|-
| InitGMasks()
| Initialize all of the masks of an AnimOb.
|-
| InitMasks()
| Initialize the BorderLine and CollMask masks of a VSprite.
|-
| MoveSprite()
| Move sprite to a point relative to top of ViewPort.
|-
| RemBob()
| Remove a Bob from the GEL list.
|-
| RemIBob()
| Immediately remove a Bob from the GEL list and the RastPort.
|-
| RemVSprite()
| Remove a VSprite from the current GEL list.
|-
| SetCollision()
| Set a pointer to a user collision routine.
|-
| SortGList()
| Sort the current GEL list, ordering its ''x,y'' coordinates.
|}

Cooperative Record Locking

2025-01-26T19:30:20Z

Costel Mincea: Text replacement - "<syntaxhighlight>" to "<syntaxhighlight lang="C" line>"

== Description ==

The Amiga's cooperative record locking scheme allows an application to lock regions of a file rather than locking an entire file. These regions are known as records.

The Amiga thinks of a record in terms of size and offset. The size refers to the length of the record in bytes. The offset refers to
the starting position of the record from the beginning of the file. The size and offset can vary from record to record. The only limit
on a record's size and offset are the limits the file system has on the size of the file.

== File System or DOS? ==

Starting with version 53.x of the DOS Library (dos.library), the record locking feature is handled entirely by AmigaDOS. DOS record locking is independent of the file system and is always available. Prior to this version, record locking was available only if each individual file system implemented the feature. If a file system does not record locking, the record locking functions described below will always fail.

== Record Lock Types ==

There are two basic types of record lock, exclusive and shared. An exclusive lock gives an application exclusive access to a record. While an application holds an exclusive record lock, no other process can obtain a record lock that overlaps the exclusively locked region. The file system can only grant an exclusive record lock on a region that is not part of an existing record lock.

The other type of record lock, the shared lock, gives an application shared access to a record. While an application holds a shared
record lock, other applications can also obtain a shared record lock that overlaps the original shared record lock, but no other process can obtain an exclusive record lock that overlaps the shared record lock.

== Locking and Unlocking Records ==

To lock (or unlock) a record within a file, an application needs a valid file handle on the file. Two DOS Library functions handle
individual record locks:

<syntaxhighlight lang="C" line>
BOOL LockRecord(BPTR myFH, ULONG my_offset, ULONG my_length, ULONG my_mode, ULONG my_timeout);
BOOL UnLockRecord(BPTR myFH, ULONG my_offset, ULONG my_length);
</syntaxhighlight>

In both functions, the myFH field refers to the valid file handle mentioned above, and the my_offset and my_length fields refer to the
record's offset and size.

The LockRecord() function has two additional parameters: my_mode and my_timeout. The my_mode field refers to the type of record. DOS supports four record types:

; REC_EXCLUSIVE
: Create an exclusive record lock. If the record is not immediately available, the file system will make a second record lock attempt when the timeout expires. The timeout (the my_timeout field from the RecordLock() prototype above) is in DOS ticks (1/50 of a second).

; REC_EXCLUSIVE_IMMED
: This record type is like REC_EXCLUSIVE, but the attempt to lock a record will fail if the record is not immediately available. In this case the file system ignores the timeout.

; REC_SHARED
: Create a shared record lock. If the record is not immediately available, the file system will make a second record lock attempt when the timeout expires. The timeout (the my_timeout field from the RecordLock() prototype above) is in DOS ticks (1/50th of a second).

; REC_SHARED_IMMED
: This record type is like REC_SHARED, but the attempt to lock a record will fail if the record is not immediately available. In this case the file system ignores the timeout.

The Amiga record locking scheme is cooperative--the file system does not prevent any process from accessing any part of a data
file. The record locking scheme has nothing to do with other actions of a file system. The file system will let other processes read and write a data file regardless of any existing record locks on the data file.

Also, when an application attempts to create a record lock, the file system's record locking mechanism only makes sure the record won't
conflict with any existing record locks on the same data file. The file system doesn't check the validity of the locked region. This
makes it possible to lock records in an empty data file and also to lock records that are well beyond the end of a data file. This
feature may be useful to an application that needs to lock records that don't exist yet.

When releasing a record lock, an application must provide exactly the same parameters it used when it locked the record. Attempting to
unlock a record using a different offset or length will fail. If the application does not successfully unlock a record, the record lock
will remain in effect. This means further requests to lock that record can fail, depending on the type of record lock. The record
lock will remain in effect until the data file is removed or the system restarted. As with most Amiga resources, an application
should release a record lock as quickly as possible. This helps out other applications that might be waiting to access the locked record.

== Locking Multiple Records ==

DOS Library offers a function to lock an array of record locks:

<syntaxhighlight lang="C" line>
BOOL LockRecords(struct RecordLock *recordarray, ULONG multi_timeout);
</syntaxhighlight>

LockRecords() locks a group of records using one function call. LockRecords() accepts a pointer to an array of RecordLock structures
(as defined in <dos/record.h>):

<syntaxhighlight lang="C" line>
struct RecordLock {
BPTR rec_FH; /* The file handle of the data file */
ULONG rec_Offset; /* The record offset in the data file */
ULONG rec_Length; /* The length of the record */
ULONG rec_Mode; /* The mode of the record lock */
};
</syntaxhighlight>

The fields in each RecordLock structure correspond to the parameters from the LockRecord() function. The records do not have to be in the same file. The array is terminated by a dummy RecordLock with a NULL file handle (rec_FH).

The RecordLock structure does not include a timeout. Instead, LockRecords() applies the same timeout (multi_timeout from the LockRecords() prototype above) to each RecordLock in the array. If LockRecords() fails to lock any of the records in its array, LockRecords() releases any successful record locks from the array, and return DOSFALSE.

To unlock records locked by LockRecords(), use the dos.library function UnLockRecords():

<syntaxhighlight lang="C" line>
BOOL UnLockRecords(struct RecordLock *recordarray);
</syntaxhighlight>

This function accepts the same array used to lock the records with LockRecords().

Note that it is possible to use UnLockRecord() on a record locked by LockRecords(). However, if an application uses UnLockRecord() to
unlock one record in the RecordLock array, it should use UnLockRecord() to unlock all of the records in the array.

== Locking Records Using DOS Packets ==

{{Note|title=Don't use DOS Packets|text=DOS Library now handles record locking as of version 53.?? so that file systems are no longer burdened with implementing this functionality. The information below is being provided for reference and for users of previous versions of the DOS Library.}}

To lock a record using the DOS packet interface, send an ACTION_LOCK_RECORD (2008) packet to the file system. This packet uses the following arguments:

<pre>
ARG1: BTPR The file handle of the data file in which you wish to lock a record.
ARG2: ULONG The offset (in bytes) in the file of the record.
ARG3: ULONG The length (in bytes) of the record.
ARG4: ULONG The mode with which you wish to lock record.
ARG5: ULONG Time (in ticks) you are will to wait for the record to become available.

RES1: BOOL Upon return RES1 will contain the success/failure status:
DOSTRUE if the record lock was successfully locked.
DOSFALSE if the record lock failed.
RES2: CODE Failure code if the record lock failed for a reason other than denied
access (collision for example).
</pre>

To unlock a record using the DOS packet interface, send an ACTION_FREE_RECORD (2009) packet. This packet uses the following arguments:

<pre>
ARG1: BPTR The file handle of the data file in which you locked the record.
ARG2: ULONG The offset (in bytes) in the file of the record with which you locked
the record.
ARG3: ULONG The length (in bytes) of the record with which you locked the record.

RES1: BOOL Upon return RES1 will contain the success/failure status:
DOSTRUE if the record lock was successfully unlocked.
DOSFALSE if there was no lock to unlock.
RES2: CODE Possible failure code if the record lock could not be unlocked.
</pre>

== Examples ==

=== LockRecord.c ===

<syntaxhighlight lang="C" line>
// LockRecord.c
//
// LockRecord()/UnLockRecord() example.

#include <exec/memory.h>
#include <exec/lists.h>
#include <dos/dosextens.h>
#include <dos/rdargs.h>
#include <dos/record.h>
#include <utility/tagitem.h>

#include <proto/dos.h>
#include <proto/exec.h>
#include <proto/utility.h>

void GetCommandLine(BPTR, struct RDArgs *rdargs, UBYTE *cmdbuffer);
void DoLockRecord(BPTR, struct RDArgs *rdargs);
void DoUnLockRecord(BPTR fh, struct RDArgs *rdargs);
void ListRecordLocks(void);
struct LockNode *FindRecordLock(ULONG offset, ULONG length);

/* List and node structures to keep track of record locks */
struct LockNode {
struct LockNode *ln_Succ;
struct LockNode *ln_Pred;
ULONG ln_Counter;
ULONG ln_Offset;
ULONG ln_Length;
ULONG ln_Mode;
};

struct LockList {
struct LockNode *lh_Head;
struct LockNode *lh_Tail;
struct LockNode *lh_TailPred;
ULONG lh_Counter;
};

/* Pseudo data file */
#define TESTFILE "t:locktest"

#define LOCK_TEMPLATE "OFFSET/K/N,LENGTH/K/N,EXCLUSIVE/S,IMMEDIATE/S,TIMEOUT/K/N"
#define UNLOCK_TEMPLATE "OFFSET/K/N,LENGTH/K/N"

#define OFFSET_POS 0
#define LENGTH_POS 1
#define EXCLUSIVE_POS 2
#define IMMEDIATE_POS 3
#define TIMEOUT_POS 4

struct LockList *locklist;

int main()
{
BPTR fh;
struct RDArgs *rdargs;
struct CSource *csource;
UBYTE *cmdbuffer;
struct LockNode *lnode, *nnode;
LONG error = RETURN_OK;

if (locklist = AllocVecTags(sizeof(struct LockList), AVT_ClearWithValue, 0, TAG_END))
{
IExec->NewList((struct List *)locklist);

/* Allocate RDArgs structure to parse command lines */
if (rdargs = IDOS->AllocDosObject(DOS_RDARGS, TAG_END))
{
csource = &rdargs->RDA_Source;

/* Get buffer to read command lines in */
if (csource->CS_Buffer = IExec->AllocVecTags(512, AVT_ClearWithValue, 0, TAG_END))
{
csource->CS_Length = 512;
csource->CS_CurChr = 0;

/* Buffer to isolate command keyword */
if (cmdbuffer = IExec->AllocVecTags(80, AVT_ClearWithValue, 0, TAG_END))
{
/* Open a testfile, create it if necessary */
if (fh = IDOS->Open(TESTFILE, MODE_READWRITE))
{
/* Process command lines */
GetCommandLine(fh, rdargs, cmdbuffer);

/* Try to get rid of outstanding record locks */
lnode = locklist->lh_Head;
while (nnode = lnode->ln_Succ)
{
/* Try to unlock pending locks */
if ((IDOS->UnLockRecord(fh,
lnode->ln_Offset,
lnode->ln_Length)) == DOSFALSE)
{
IDOS->Printf("Error unlocking record %ld with offset %ld length %ld\n",
lnode->ln_Counter,
lnode->ln_Offset,
lnode->ln_Length);
if (IDOS->IoErr())
IDOS->PrintFault(IDOS->IoErr(), NULL);
}
/* Remove node no matter what */
IExec->FreeVec(lnode);
lnode = nnode;
};

IDOS->Close(fh);
}
IExec->FreeVec(cmdbuffer);
} else
IDOS->SetIoErr(ERROR_NO_FREE_STORE);

IExec->FreeVec(csource->CS_Buffer);
} else
IDOS->SetIoErr(ERROR_NO_FREE_STORE);

IDOS->FreeDosObject(DOS_RDARGS, rdargs);
} else
IDOS->SetIoErr(ERROR_NO_FREE_STORE);

IExec->FreeVec(locklist);
} else
IDOS->SetIoErr(ERROR_NO_FREE_STORE);

error = IDOS->IoErr();
if (error)
{
IDOS->PrintFault(IDOS->IoErr(), NULL);
error = RETURN_FAIL;
}

return(error);
}

void GetCommandLine(BPTR fh, struct RDArgs *rdargs, UBYTE *cmdbuffer)
{
struct CSource *csource = &rdargs->RDA_Source;
UBYTE *cmdlinebuffer = csource->CS_Buffer;
LONG error;

/* Prompt for command line */
IDOS->Write(IDOS->Output(), "Cmd> ", 5);

/* Loop forever, waiting for commands */
for (;;)
{
/* Get command line */
if ((IDOS->FGets(IDOS->Input(), cmdlinebuffer, 512)) != NULL)
{
/* Use ReadItem() to isolate actual command */
error = IDOS->ReadItem(cmdbuffer, 80, csource);

/* Break on error */
if (error == ITEM_ERROR)
break;

/* Make sure I've got something */
else if (error != ITEM_NOTHING)
{
/* cmdbuffer now contains the command:
*
* KNOWN COMMANDS:
* QUIT
* LIST
* LOCKRECORD
* UNLOCKRECORD
*/
if ((IUtility->Stricmp("QUIT", cmdbuffer)) == 0)
break;
else if ((IUtility->Stricmp("HELP", cmdbuffer)) == 0)
{
IDOS->Printf("Available commands:\n");
IDOS->Printf("LOCKRECORD %s\n", LOCK_TEMPLATE);
IDOS->Printf("UNLOCKRECORD %s\n", UNLOCK_TEMPLATE);
IDOS->Printf("LIST\n");
IDOS->Printf("QUIT\n");
}
else if ((IUtility->Stricmp("LIST", cmdbuffer)) == 0)
ListRecordLocks(); /* Show all current locks */
else
{
/* Note that I've already isolated the command
* keyword, so I'm using Source->CS_CurChr to point
* after it.
*/
csource->CS_Buffer += csource->CS_CurChr;
csource->CS_CurChr = 0;

if ((IUtility->Stricmp("LOCKRECORD", cmdbuffer)) == 0)
DoLockRecord(fh, rdargs);
else if ((IUtility->Stricmp("UNLOCKRECORD", cmdbuffer)) == 0)
DoUnLockRecord(fh, rdargs);
else
IDOS->PrintFault(ERROR_NOT_IMPLEMENTED, cmdbuffer);

/* Reset CSource */
csource->CS_Buffer = cmdlinebuffer;
}

/* Output new prompt. Make sure csource is OK. */
IDOS->Write(IDOS->Output(), "Cmd> ", 5);
csource->CS_CurChr = 0;
}
} else
break;
}
}

void DoLockRecord(BPTR fh, struct RDArgs *rdargs)
{
struct RDArgs *readargs;
LONG rargs[5];
ULONG offset, length, timeout, mode;
ULONG result;
struct LockNode *lnode;

offset = length = timeout = mode = 0;
rargs[0] = rargs[1] = rargs[2] = rargs[3] = rargs[4] = 0;

if (readargs = IDOS->ReadArgs(LOCK_TEMPLATE, rargs, rdargs))
{
if (rargs[OFFSET_POS])
offset = *((LONG *)rargs[OFFSET_POS]);
if (rargs[LENGTH_POS])
length = *((LONG *)rargs[LENGTH_POS]);
if (rargs[TIMEOUT_POS])
timeout = *((LONG *)rargs[TIMEOUT_POS]);

/* Type of locking */
if (rargs[EXCLUSIVE_POS])
{
if (rargs[IMMEDIATE_POS])
mode = REC_EXCLUSIVE_IMMED;
else
mode = REC_EXCLUSIVE;
}
else
{
if (rargs[IMMEDIATE_POS])
mode = REC_SHARED_IMMED;
else
mode = REC_SHARED;
}

rargs[0] = offset;
rargs[1] = length;
switch (mode)
{
case REC_EXCLUSIVE_IMMED:
rargs[2] = (LONG)"REC_EXCLUSIVE_IMMED";
break;
case REC_EXCLUSIVE:
rargs[2] = (LONG)"REC_EXCLUSIVE";
break;
case REC_SHARED_IMMED:
rargs[2] = (LONG)"REC_SHARED_IMMED";
break;
case REC_SHARED:
rargs[2] = (LONG)"REC_SHARED";
break;
}
rargs[3] = timeout;

/* Show what I'm going to do */
IUtility->VFPrintf(Output(),
"LockRecord: Offset %ld, Length %ld, Mode %s, Timeout %ld...",
rargs);
IDOS->FFlush(IDOS->Output());

/* Lock the record. Parameters are not checked. It is f.e. possible to
* specify an offset larger than the size of the file. Possible since
* Record Locks are not related to the file itself, only the means for
* you to do arbitration.
*
* Note that the timeout value is in ticks...
*/
result = IDOS->LockRecord(fh, offset, length, mode, timeout);

if (result == DOSTRUE)
{
IDOS->Write(IDOS->Output(), "OK\n", 3);

/* Add a node to track this record lock */
if (lnode = IExec->AllocVec(sizeof(struct LockNode), AVT_ClearWithValue, 0, TAG_END))
{
lnode->ln_Counter = locklist->lh_Counter++;
lnode->ln_Offset = offset;
lnode->ln_Length = length;
lnode->ln_Mode = mode;

IExec->AddTail((struct List *)locklist, (struct Node *)lnode);
}
else
{
/* Not enough memory for node. You're on your own... */
IDOS->Write(IDOS->Output(), "Not enough memory to track record lock.\n", 40);
}
}
else
{
IDOS->Write(IDOS->Output(), "FAILED\n", 7);
if (IDOS->IoErr())
IDOS->PrintFault(IDOS->IoErr(), NULL);
}

/* Release memory associated with readargs */
IDOS->FreeArgs(readargs);
} else
IDOS->PrintFault(IDOS->IoErr(), NULL);
}

void DoUnLockRecord(BPTR fh, struct RDArgs *rdargs)
{
struct RDArgs *readargs;
LONG rargs[2];
ULONG offset, length;
ULONG result;
struct LockNode *lnode;

offset = length = 0;
rargs[0] = rargs[1] = 0;

if (readargs = IDOS->ReadArgs(LOCK_TEMPLATE, rargs, rdargs))
{
if (rargs[OFFSET_POS])
offset = *((LONG *)rargs[OFFSET_POS]);
if (rargs[LENGTH_POS])
length = *((LONG *)rargs[LENGTH_POS]);

rargs[0] = offset;
rargs[1] = length;

/* Show what I'm going to do */
IUtility->VFPrintf(Output(), "UnLockRecord: Offset %ld, Length %ld...", rargs);
IDOS->FFlush(IDOS->Output());

/* Unlock indicated record with indicated offset and length.
* If the same record (same offset/length) is locked multiple times,
* only one, the first one in the list , will be unlocked.
*/
result = IDOS->UnLockRecord(fh, offset, length);

if (result == DOSTRUE) {
IDOS->Write(IDOS->Output(), "OK\n", 3);

/* Remove node associated with this lock */
if (lnode = FindRecordLock(offset, length))
{
IExec->Remove((struct Node *)lnode);
FreeVec(lnode);
}
}
else
{
IDOS->Write(IDOS->Output(), "FAILED\n", 7); /* Keep locknode */
if (IDOS->IoErr())
IDOS->PrintFault(IDOS->IoErr(), NULL);
}
/* Release memory associated with readargs */
IDOS->FreeArgs(readargs);
} else
IDOS->PrintFault(IDOS->IoErr(), NULL);
}

void ListRecordLocks(void)
{
struct LockNode *lnode;
LONG rargs[4];

for (lnode = locklist->lh_Head; lnode->ln_Succ; lnode = lnode->ln_Succ)
{
rargs[0] = lnode->ln_Counter;
rargs[1] = lnode->ln_Offset;
rargs[2] = lnode->ln_Length;

switch (lnode->ln_Mode)
{
case REC_EXCLUSIVE_IMMED:
rargs[3] = (LONG)"REC_EXCLUSIVE_IMMED";
break;
case REC_EXCLUSIVE:
rargs[3] = (LONG)"REC_EXCLUSIVE";
break;
case REC_SHARED_IMMED:
rargs[3] = (LONG)"REC_SHARED_IMMED";
break;
case REC_SHARED:
rargs[3] = (LONG)"REC_SHARED";
break;
}

IUtility->VFPrintf(IDOS->Output(), "RecordLock #%ld: Offset %ld Length %ld Mode %s\n", rargs);
}
IDOS->FFlush(IDOS->Output());
}

struct LockNode *FindRecordLock(ULONG offset, ULONG length)
{
struct LockNode *lnode;

for (lnode = locklist->lh_Head; lnode->ln_Succ; lnode = lnode->ln_Succ)
{
if ((lnode->ln_Offset == offset) && lnode->ln_Length == length)
return(lnode);
}
return(NULL);
}
</syntaxhighlight>

=== ExRecLock1.c ===

<syntaxhighlight lang="C" line>
// ExRecLock1.c
//
// This is a simple example of using record locking to create an exclusive record
// lock on a file, and writing to that record. The example ExRecLock2 is almost
// exactly the same as this example, except ExRecLock2 uses the record lock directly
// after ExRecLock1's record. If you try to run ExRecLock1 (or ExRecLock2) while
// another instance of ExRecLock1 (or ExRecLock2) is running, the second record lock
// attempt will fail.

#include <protob/dos.h>

#define RECORDSIZE 12
#define RECORDOFFSET 0

UBYTE *string = "ExRecLock1\n"; /* This string will be the */
/* contents of the record. */
int main()
{
BPTR fh;

if (fh = IDOS->Open("t:testRLock", MODE_READWRITE)) /* Open the file, creating */
{ /* it if necessary. */
if (DOSTRUE == IDOS->LockRecord(fh, /* Lock the record as exclusive, */
RECORDOFFSET, /* and do not wait if it is not */
RECORDSIZE, /* available immediately. */
REC_EXCLUSIVE_IMMED, 0))
{
LONG error = RECORDOFFSET;

/* If the record is beyond the end of the file, */
if (IDOS->Seek(fh, 0, OFFSET_END) < RECORDOFFSET) /* lengthen the file. */
error = IDOS->SetFileSize(fh, RECORDOFFSET, OFFSET_BEGINNING);

if (error == RECORDOFFSET) /* If there was no error with the file */
{ /* file size, continue. */
if (IDOS->Seek(fh, RECORDOFFSET, OFFSET_BEGINNING) < 0)
IDOS->PrintFault(IDOS->IoErr(), "Seek() error");

if (IDOS->Write(fh, string, RECORDSIZE) < 0)
IDOS->PrintFault(IDOS->IoErr(), "Write() error");
else
IDOS->PutStr("Write successful, ");
}
IDOS->PutStr("Waiting 10 seconds...\n");
IDOS->Delay(10 * 50);
IDOS->UnLockRecord(fh, RECORDOFFSET, RECORDSIZE);
}
else IDOS->PrintFault(IDOS->IoErr(), "Record Lock Failed");
IDOS->Close(fh);
}
else IDOS->PrintFault(IDOS->IoErr(), "Open Failed");
}
</syntaxhighlight>

=== ExRecLock2.c ===

<syntaxhighlight lang="C" line>
// ExRecLock2.c
//
// This is a simple example of using record locking to create an exclusive record
// lock on a file, and writing to that record. The example ExRecLock1 is almost
// exactly the same as this example, except ExRecLock1 uses the record lock directly
// before ExRecLock2's record. If you try to run ExRecLock2 (or ExRecLock1) while
// another instance of ExRecLock2 (or ExRecLock1) is running, the second record lock
// attempt will fail.

#include <proto/dos.h>

#define RECORDSIZE 12
#define RECORDOFFSET 12

UBYTE *string = "ExRecLock2\n"; /* This string will be the */
/* contents of the record. */
int main()
{
BPTR fh;

if (fh = IDOS->Open("t:testRLock", MODE_READWRITE)) /* Open the file, creating */
{ /* it if necessary. */
if (DOSTRUE == IDOS->LockRecord(fh, /* Lock the record as exclusive, */
RECORDOFFSET, /* and do not wait if it is not */
RECORDSIZE, /* available immediately. */
REC_EXCLUSIVE_IMMED, 0))
{
LONG error = RECORDOFFSET;

/* If the record is beyond the end of the file, */
if (IDOS->Seek(fh, 0, OFFSET_END) < RECORDOFFSET) /* lengthen the file. */
error = IDOS->SetFileSize(fh, RECORDOFFSET, OFFSET_BEGINNING);

if (error == RECORDOFFSET) /* If there was no error with the file */
{ /* file size, continue. */
if (IDOS->Seek(fh, RECORDOFFSET, OFFSET_BEGINNING) < 0)
IDOS->PrintFault(IDOS->IoErr(), "Seek() error");

if (IDOS->Write(fh, string, RECORDSIZE) < 0)
IDOS->PrintFault(IDOS->IoErr(), "Write() error");
else
IDOS->PutStr("Write successful, ");
}
IDOS->PutStr("Waiting 10 seconds...\n");
IDOS->Delay(10 * 50);
IDOS->UnLockRecord(fh, RECORDOFFSET, RECORDSIZE);
}
else IDOS->PrintFault(IDOS->IoErr(), "Record Lock Failed");
IDOS->Close(fh);
}
else IDOS->PrintFault(IDOS->IoErr(), "Open Failed");
}
</syntaxhighlight>