[deliverable/linux.git] / Documentation / zorro.txt

		Writing Device Drivers for Zorro Devices
		----------------------------------------

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


1. 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 busses, 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.


2. 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"))
	...
    }


3. 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


4. 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);


5. References
-------------

linux/include/linux/zorro.h
linux/include/asm-{m68k,ppc}/zorro.h
linux/include/linux/zorro_ids.h
linux/drivers/zorro
/proc/bus/zorro
Commit	Line	Data
1da177e4 LT	1	Writing Device Drivers for Zorro Devices
	2	----------------------------------------
	3
	4	Written by Geert Uytterhoeven <geert@linux-m68k.org>
	5	Last revised: September 5, 2003
	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 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	...
	36	}
	37
	38	`ZORRO_WILDCARD' acts as a wildcard and finds any Zorro device. If your driver
	39	supports different types of boards, you can use a construct like:
	40
	41	struct zorro_dev *z = NULL;
	42
	43	while ((z = zorro_find_device(ZORRO_WILDCARD, z))) {
	44	if (z->id != ZORRO_PROD_xxx1 && z->id != ZORRO_PROD_xxx2 && ...)
	45	continue;
	46	if (!zorro_request_region(z->resource.start+MY_START, MY_SIZE,
	47	"My explanation"))
	48	...
	49	}
	50
	51
	52	3. Zorro Resources
	53	------------------
	54
	55	Before you can access a Zorro device's registers, you have to make sure it's
	56	not yet in use. This is done using the I/O memory space resource management
	57	functions:
	58
	59	request_mem_region()
	60	release_mem_region()
	61
	62	Shortcuts to claim the whole device's address space are provided as well:
	63
	64	zorro_request_device
65	zorro_release_device
66
67
68	4. Accessing the Zorro Address Space
69	------------------------------------
70
71	The address regions in the Zorro device resources are Zorro bus address
72	regions. Due to the identity bus-physical address mapping on the Zorro bus,
73	they are CPU physical addresses as well.
74
75	The treatment of these regions depends on the type of Zorro space:
76
77	- Zorro II address space is always mapped and does not have to be mapped
78	explicitly using z_ioremap().
79
80	Conversion from bus/physical Zorro II addresses to kernel virtual addresses
81	and vice versa is done using:
82
83	virt_addr = ZTWO_VADDR(bus_addr);
84	bus_addr = ZTWO_PADDR(virt_addr);
85
86	- Zorro III address space must be mapped explicitly using z_ioremap() first
87	before it can be accessed:
88
89	virt_addr = z_ioremap(bus_addr, size);
90	...
91	z_iounmap(virt_addr);
92
93
94	5. References
95	-------------
96
97	linux/include/linux/zorro.h
98	linux/include/asm-{m68k,ppc}/zorro.h
99	linux/include/linux/zorro_ids.h
100	linux/drivers/zorro
101	/proc/bus/zorro
102