LXR linux/Documentation/zorro.txt

   1========================================
   2Writing Device Drivers for Zorro Devices
   3========================================
   4
   5:Author: Written by Geert Uytterhoeven <geert@linux-m68k.org>
   6:Last revised: September 5, 2003
   7
   8
   9Introduction
  10------------
  11
  12The Zorro bus is the bus used in the Amiga family of computers. Thanks to
  13AutoConfig(tm), it's 100% Plug-and-Play.
  14
  15There are two types of Zorro buses, Zorro II and Zorro III:
  16
  17  - The Zorro II address space is 24-bit and lies within the first 16 MB of the
  18    Amiga's address map.
  19
  20  - Zorro III is a 32-bit extension of Zorro II, which is backwards compatible
  21    with Zorro II. The Zorro III address space lies outside the first 16 MB.
  22
  23
  24Probing for Zorro Devices
  25-------------------------
  26
  27Zorro devices are found by calling ``zorro_find_device()``, which returns a
  28pointer to the ``next`` Zorro device with the specified Zorro ID. A probe loop
  29for the board with Zorro ID ``ZORRO_PROD_xxx`` looks like::
  30
  31    struct zorro_dev *z = NULL;
  32
  33    while ((z = zorro_find_device(ZORRO_PROD_xxx, z))) {
  34        if (!zorro_request_region(z->resource.start+MY_START, MY_SIZE,
  35                                  "My explanation"))
  36        ...
  37    }
  38
  39``ZORRO_WILDCARD`` acts as a wildcard and finds any Zorro device. If your driver
  40supports 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
  53Zorro Resources
  54---------------
  55
  56Before you can access a Zorro device's registers, you have to make sure it's
  57not yet in use. This is done using the I/O memory space resource management
  58functions::
  59
  60    request_mem_region()
  61    release_mem_region()
  62
  63Shortcuts to claim the whole device's address space are provided as well::
  64
  65    zorro_request_device
  66    zorro_release_device
  67
  68
  69Accessing the Zorro Address Space
  70---------------------------------
  71
  72The address regions in the Zorro device resources are Zorro bus address
  73regions. Due to the identity bus-physical address mapping on the Zorro bus,
  74they are CPU physical addresses as well.
  75
  76The treatment of these regions depends on the type of Zorro space:
  77
  78  - Zorro II address space is always mapped and does not have to be mapped
  79    explicitly using z_ioremap().
  80    
  81    Conversion from bus/physical Zorro II addresses to kernel virtual addresses
  82    and vice versa is done using::
  83
  84        virt_addr = ZTWO_VADDR(bus_addr);
  85        bus_addr = ZTWO_PADDR(virt_addr);
  86
  87  - Zorro III address space must be mapped explicitly using z_ioremap() first
  88    before it can be accessed::
  89 
  90        virt_addr = z_ioremap(bus_addr, size);
  91        ...
  92        z_iounmap(virt_addr);
  93
  94
  95References
  96----------
  97
  98#. linux/include/linux/zorro.h
  99#. linux/include/uapi/linux/zorro.h
 100#. linux/include/uapi/linux/zorro_ids.h
 101#. linux/arch/m68k/include/asm/zorro.h
 102#. linux/drivers/zorro
 103#. /proc/bus/zorro
 104
 105