Documentation/zorro.txt

   1                 Writing Device Drivers for Zorro Devices
   2                 ----------------------------------------
   3
   4 Written by Geert Uytterhoeven <geert@linux-m68k.org>
   5 Last revised: February 27, 2000
   6
   7
   8 1. Introduction
   9 ---------------
  10
  11 The Zorro bus is the bus used in the Amiga family of computers. Thanks to
  12 AutoConfig(tm), it's is 100% Plug-and-Play.
  13
  14 There are two types of Zorro busses, Zorro II and Zorro III:
  15
  16   - The Zorro II address space is 24-bit and lies within the first 16 MB of the
  17     Amiga's address map.
  18
  19   - Zorro III is a 32-bit extension of Zorro II, which is backwards compatible
  20     with Zorro II. The Zorro III address space lies outside the first 16 MB.
  21
  22
  23 2. Probing for Zorro Devices
  24 ----------------------------
  25
  26 Zorro devices are found by calling `zorro_find_device()', which returns a
  27 pointer to the `next' Zorro device with the specified Zorro ID. A probe loop
  28 for the board with Zorro ID `ZORRO_PROD_xxx' looks like:
  29
  30     struct zorro_dev *z = NULL;
  31
  32     while ((z = zorro_find_device(ZORRO_PROD_xxx, z))) {
  33         if (!zorro_request_region(z->resource.start+MY_START, MY_SIZE,
  34                                   "My explanation"))
  35         strcpy(z->name, "My board name");
  36         ...
  37     }
  38
  39 `ZORRO_WILDCARD' acts as a wildcard and finds any Zorro device. If your driver
  40 supports different types of boards, you can use a construct like:
  41
  42     struct zorro_dev *z = NULL;
  43
  44     while ((z = zorro_find_device(ZORRO_WILDCARD, z))) {
  45         if (z->id != ZORRO_PROD_xxx1 && z->id != ZORRO_PROD_xxx2 && ...)
  46             continue;
  47         if (!zorro_request_region(z->resource.start+MY_START, MY_SIZE,
  48                                   "My explanation"))
  49         ...
  50     }
  51
  52
  53 3. Zorro Resources
  54 ------------------
  55
  56 Before you can access a Zorro device's registers, you have to make sure it's
  57 not yet in use. This is done using the I/O memory space resource management
  58 functions:
  59
  60     request_mem_region()
  61     check_mem_region()          (deprecated)
  62     release_mem_region()
  63
  64 Shortcuts to claim the whole device's address space are provided as well:
  65
  66     zorro_request_device
  67     zorro_check_device          (deprecated)
  68     zorro_release_device
  69
  70
  71 4. Accessing the Zorro Address Space
  72 ------------------------------------
  73
  74 The address regions in the Zorro device resources are Zorro bus address
  75 regions. Due to the identity bus-physical address mapping on the Zorro bus,
  76 they are CPU physical addresses as well.
  77
  78 The treatment of these regions depends on the type of Zorro space:
  79
  80   - Zorro II address space is always mapped and does not have to be mapped
  81     explicitly using ioremap().
  82
  83     Conversion from bus/physical Zorro II addresses to kernel virtual addresses
  84     and vice versa is done using:
  85
  86         virt_addr = ZTWO_VADDR(bus_addr);
  87         bus_addr = ZTWO_PADDR(virt_addr);
  88
  89   - Zorro III address space must be mapped explicitly using ioremap() first
  90     before it can be accessed:
  91
  92         virt_addr = ioremap(bus_addr, size);
  93         ...
  94         iounmap(virt_addr);
  95
  96
  97 5. Zorro Device Naming
  98 ----------------------
  99
 100 Since we think generic device naming is something for userspace (zorroutils),
 101 we don't keep a Zorro device name database in the kernel.
 102 However, device drivers are allowed to store the expansion board name in struct
 103 zorro_dev.
 104
 105
 106 6. References
 107 -------------
 108
 109 linux/include/linux/zorro.h
 110 linux/include/linux/ioport.h
 111 linux/include/asm-m68k/io.h
 112 linux/include/asm-m68k/amigahw.h
 113 linux/include/asm-ppc/io.h
 114 linux/driver/zorro
 115 /proc/bus/zorro
 116