[thirdparty/kernel/stable.git] / Documentation / zorro.txt

========================================
Writing Device Drivers for Zorro Devices
========================================

:Author: Written by Geert Uytterhoeven <geert@linux-m68k.org>
:Last revised: September 5, 2003


Introduction
------------

The Zorro bus is the bus used in the Amiga family of computers. Thanks to
AutoConfig(tm), it's 100% Plug-and-Play.

There are two types of Zorro buses, Zorro II and Zorro III:

  - The Zorro II address space is 24-bit and lies within the first 16 MB of the
    Amiga's address map.

  - Zorro III is a 32-bit extension of Zorro II, which is backwards compatible
    with Zorro II. The Zorro III address space lies outside the first 16 MB.


Probing for Zorro Devices
-------------------------

Zorro devices are found by calling ``zorro_find_device()``, which returns a
pointer to the ``next`` Zorro device with the specified Zorro ID. A probe loop
for the board with Zorro ID ``ZORRO_PROD_xxx`` looks like::

    struct zorro_dev *z = NULL;

    while ((z = zorro_find_device(ZORRO_PROD_xxx, z))) {
	if (!zorro_request_region(z->resource.start+MY_START, MY_SIZE,
				  "My explanation"))
	...
    }

``ZORRO_WILDCARD`` acts as a wildcard and finds any Zorro device. If your driver
supports different types of boards, you can use a construct like::

    struct zorro_dev *z = NULL;

    while ((z = zorro_find_device(ZORRO_WILDCARD, z))) {
	if (z->id != ZORRO_PROD_xxx1 && z->id != ZORRO_PROD_xxx2 && ...)
	    continue;
	if (!zorro_request_region(z->resource.start+MY_START, MY_SIZE,
				  "My explanation"))
	...
    }


Zorro Resources
---------------

Before you can access a Zorro device's registers, you have to make sure it's
not yet in use. This is done using the I/O memory space resource management
functions::

    request_mem_region()
    release_mem_region()

Shortcuts to claim the whole device's address space are provided as well::

    zorro_request_device
    zorro_release_device


Accessing the Zorro Address Space
---------------------------------

The address regions in the Zorro device resources are Zorro bus address
regions. Due to the identity bus-physical address mapping on the Zorro bus,
they are CPU physical addresses as well.

The treatment of these regions depends on the type of Zorro space:

  - Zorro II address space is always mapped and does not have to be mapped
    explicitly using z_ioremap().
    
    Conversion from bus/physical Zorro II addresses to kernel virtual addresses
    and vice versa is done using::

	virt_addr = ZTWO_VADDR(bus_addr);
	bus_addr = ZTWO_PADDR(virt_addr);

  - Zorro III address space must be mapped explicitly using z_ioremap() first
    before it can be accessed::
 
	virt_addr = z_ioremap(bus_addr, size);
	...
	z_iounmap(virt_addr);


References
----------

#. linux/include/linux/zorro.h
#. linux/include/uapi/linux/zorro.h
#. linux/include/uapi/linux/zorro_ids.h
#. linux/arch/m68k/include/asm/zorro.h
#. linux/drivers/zorro
#. /proc/bus/zorro
Commit	Line	Data
998ff0b5 MCC	1	========================================
	2	Writing Device Drivers for Zorro Devices
	3	========================================
1da177e4	4
998ff0b5 MCC	5	:Author: Written by Geert Uytterhoeven <geert@linux-m68k.org>
998ff0b5 MCC	6	:Last revised: September 5, 2003
1da177e4 LT	7
1da177e4 LT	8
998ff0b5 MCC	9	Introduction
998ff0b5 MCC	10	------------
1da177e4 LT	11
	12	The Zorro bus is the bus used in the Amiga family of computers. Thanks to
	13	AutoConfig(tm), it's 100% Plug-and-Play.
	14
9bb0e9cb	15	There are two types of Zorro buses, Zorro II and Zorro III:
1da177e4 LT	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
998ff0b5 MCC	24	Probing for Zorro Devices
998ff0b5 MCC	25	-------------------------
1da177e4	26
998ff0b5 MCC	27	Zorro devices are found by calling ``zorro_find_device()``, which returns a
	28	pointer to the ``next`` Zorro device with the specified Zorro ID. A probe loop
	29	for the board with Zorro ID ``ZORRO_PROD_xxx`` looks like::
1da177e4 LT	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
998ff0b5 MCC	39	``ZORRO_WILDCARD`` acts as a wildcard and finds any Zorro device. If your driver
998ff0b5 MCC	40	supports different types of boards, you can use a construct like::
1da177e4 LT	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
998ff0b5 MCC	53	Zorro Resources
998ff0b5 MCC	54	---------------
1da177e4 LT	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
998ff0b5	58	functions::
1da177e4 LT	59
	60	request_mem_region()
	61	release_mem_region()
	62
998ff0b5	63	Shortcuts to claim the whole device's address space are provided as well::
1da177e4 LT	64
	65	zorro_request_device
	66	zorro_release_device
	67
	68
998ff0b5 MCC	69	Accessing the Zorro Address Space
998ff0b5 MCC	70	---------------------------------
1da177e4 LT	71
	72	The address regions in the Zorro device resources are Zorro bus address
	73	regions. Due to the identity bus-physical address mapping on the Zorro bus,
	74	they are CPU physical addresses as well.
	75
	76	The 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
998ff0b5	82	and vice versa is done using::
1da177e4 LT	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
998ff0b5	88	before it can be accessed::
1da177e4 LT	89
	90	virt_addr = z_ioremap(bus_addr, size);
	91	...
	92	z_iounmap(virt_addr);
	93
	94
998ff0b5 MCC	95	References
998ff0b5 MCC	96	----------
1da177e4	97
998ff0b5 MCC	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
1da177e4	104