1.\" $NetBSD: isa.9,v 1.7 2002/10/14 13:43:24 wiz Exp $ 2.\" 3.\" Copyright (c) 2001 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" This code is derived from software contributed to The NetBSD Foundation 7.\" by Gregory McGarry. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 3. All advertising materials mentioning features or use of this software 18.\" must display the following acknowledgement: 19.\" This product includes software developed by the NetBSD 20.\" Foundation, Inc. and its contributors. 21.\" 4. Neither the name of The NetBSD Foundation nor the names of its 22.\" contributors may be used to endorse or promote products derived 23.\" from this software without specific prior written permission. 24.\" 25.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 26.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 27.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 28.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 29.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 30.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 31.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 32.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 33.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 34.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 35.\" POSSIBILITY OF SUCH DAMAGE. 36.\" 37.Dd June 19, 2001 38.Dt ISA 9 39.Os 40.Sh NAME 41.Nm ISA , 42.Nm isa_intr_alloc , 43.Nm isa_intr_establish , 44.Nm isa_intr_disestablish , 45.Nm isa_intr_evcnt , 46.Nm isa_dmamap_create , 47.Nm isa_dmamap_destroy , 48.Nm isa_dmamem_alloc , 49.Nm isa_dmamem_free , 50.Nm isa_dmamem_map , 51.Nm isa_dmamem_unmap , 52.Nm isa_malloc , 53.Nm isa_free , 54.Nm isa_dmastart , 55.Nm isa_dmaabort , 56.Nm isa_dmacount , 57.Nm isa_dmadone , 58.Nm isa_dmamaxsize , 59.Nm isa_drq_isfree , 60.Nm isa_dmacascade , 61.Nm isa_mappage 62.Nd Industry-standard Architecture 63.Sh SYNOPSIS 64.Fd #include \*[Lt]machine/bus.h\*[Gt] 65.Fd #include \*[Lt]dev/isa/isareg.h\*[Gt] 66.Fd #include \*[Lt]dev/isa/isavar.h\*[Gt] 67.Ft int 68.Fn isa_intr_alloc "isa_chipset_tag_t ic" "int mask" "int type" \ 69"int *irq" 70.Ft const struct evcnt * 71.Fn isa_intr_evcnt "isa_chipset_tag_t ic" "int irq" 72.Ft void * 73.Fn isa_intr_establish "isa_chipset_tag_t ic" "int irq" "int type" \ 74"int level" "int (*handler)(void *)" "void *arg" 75.Ft void 76.Fn isa_intr_disestablish "isa_chipset_tag_t ic" "void *ih" 77.Fd #include \*[Lt]dev/isa/isadmareg.h\*[Gt] 78.Fd #include \*[Lt]dev/isa/isadmavar.h\*[Gt] 79.Ft int 80.Fn isa_dmamap_create "isa_chipset_tag_t ic" "int chan" "bus_size_t size" \ 81"int flags" 82.Ft void 83.Fn isa_dmamap_destroy "isa_chipset_tag_t ic" "int chan" 84.Ft int 85.Fn isa_dmamem_alloc "isa_chipset_tag_t ic" "int chan" "bus_size_t size" \ 86"bus_addr_t *addrp" "int flags" 87.Ft void 88.Fn isa_dmamem_free "isa_chipset_tag_t ic" "int chan" "bus_addr_t addr" \ 89"bus_size_t size" 90.Ft int 91.Fn isa_dmamem_map "isa_chipset_tag_t ic" "int chan" "bus_addr_t addr" \ 92"bus_size_t size" "caddr_t *kvap" "int flags" 93.Ft void 94.Fn isa_dmamem_unmap "isa_chipset_tag_t ic" "int chan" "caddr_t kva" \ 95"size_t size" 96.Ft void * 97.Fn isa_malloc "isa_chipset_tag_t ic" "int chan" "size_t size" \ 98"int pool" "int flags" 99.Ft void 100.Fn isa_free "void *addrp" "int pool" 101.Ft int 102.Fn isa_dmastart "isa_chipset_tag_t ic" "int chan" "bus_addr_t addr" \ 103"bus_size_t size" "struct proc *proc" "int flags" "int bf" 104.Ft void 105.Fn isa_dmaabort "isa_chipset_tag_t ic" "int chan" 106.Ft bus_size_t 107.Fn isa_dmacount "isa_chipset_tag_t ic" "int chan" 108.Ft void 109.Fn isa_dmadone "isa_chipset_tag_t ic" "int chan" 110.Ft bus_size_t 111.Fn isa_dmamaxsize "isa_chipset_tag_t ic" "int chan" 112.Ft int 113.Fn isa_drq_isfree "isa_chipset_tag_t ic" "int chan" 114.Ft int 115.Fn isa_dmacascade "isa_chipset_tag_t ic" "int chan" 116.Ft paddr_t 117.Fn isa_mappage "void *mem" "off_t offset" "int prot" 118.Sh DESCRIPTION 119The machine-independent 120.Nm 121subsystem provides support for the ISA bus. 122.Pp 123The ISA bus was introduced on the IBM PC/AT. 124It is an extension to the original bus found on the original IBM PC. 125The ISA bus is essentially the host bus of the Intel 80286 processor, 126however the widespread acceptance of the bus as a defacto standard has 127seen it appear on systems without Intel processors. 128.Pp 129The ISA bus has a 16-bit data bus, a 24-bit memory address bus, a 13016-bit I/O address bus, and operates at 8MHz. 131It provides 15 interrupt lines and 8 DMA channels supporting DMA transfers 132of 64KB or 128KB transfers depending on the width of the channel being used. 133Historically, some devices only decoded the 10 lowest bits of 134the I/O address bus, preventing use of the full 16-bit address space. 135.Pp 136On newer machines, the ISA bus is no longer connected directly to the 137host bus, and is usually connected via a PCI-ISA bridge. 138Either way, the bus looks the same to the device driver. 139.Sh DATA TYPES 140Drivers for devices attached to the 141.Nm 142bus will make use of the following data types: 143.Bl -tag -width compact 144.It Fa isa_chipset_tag_t 145Chipset tag for the ISA bus. 146.It Fa struct isa_attach_args 147Location hints for devices are recorded in this structure. 148It contains the following members: 149.Bd -literal 150 bus_space_tag_t ia_iot; /* isa i/o space tag */ 151 bus_space_tag_t ia_memt; /* isa mem space tag */ 152 bus_dma_tag_t ia_dmat; /* DMA tag */ 153 isa_chipset_tag_t ia_ic; 154 int ia_iobase; /* base i/o address */ 155 int ia_iosize; /* span of ports used */ 156 int ia_maddr; /* physical mem addr */ 157 u_int ia_msize; /* size of memory */ 158 int ia_irq; /* interrupt request */ 159 int ia_drq; /* DMA request */ 160 int ia_drq2; /* second DMA request */ 161 void *ia_aux; /* driver specific */ 162.Ed 163.El 164.Sh FUNCTIONS 165.Bl -tag -width compact 166.It Fn isa_intr_alloc "ic" "mask" "type" "irq" 167This function is generally not required by device drivers. 168It is used by bridges attaching other busses to the ISA bus. 169.It Fn isa_intr_evcnt "ic" "irq" 170Returns the event counter associated with interrupt line 171.Fa irq . 172.It Fn isa_intr_establish "ic" "irq" "type" "level" "handler" "arg" 173To establish an ISA interrupt handler, a driver calls 174.Fn isa_intr_establish 175with the interrupt number 176.Fa irq , 177type 178.Fa type , 179and level 180.Fa level . 181When the interrupt occurs the function 182.Fa handler 183is called with argument 184.Fa arg . 185Valid values for 186.Fa type 187are: 188.Bl -tag -width compact 189.It IST_NONE 190Reserve interrupt, but don't actually establish. 191.It IST_EDGE 192Edge-triggered interrupt. 193.It IST_LEVEL 194Level-triggered interrupt. 195.It IST_PULSE 196Pulse-triggered interrupt. 197.El 198.sp 199.Fn isa_intr_establish 200returns an opaque handle to an event descriptor if it succeeds, and 201returns NULL on failure. 202.Pp 203.It Fn isa_intr_disestablish "ic" "ih" 204Dis-establish the interrupt handler with handle 205.Fa ih . 206The handle was returned from 207.Fn isa_intr_establish . 208.It Fn isa_dmamap_create "ic" "chan" "size" "flags" 209Creates a DMA map for channel 210.Fa chan . 211It is initialised to accept maximum DMA transfers of size 212.Fa size . 213Valid values for the 214.Fa flags 215argument are the same as for 216.Fn bus_dmamap_create 217(see 218.Xr bus_dma 9 ) . 219This function returns zero on success or an error value on failure. 220.It Fn isa_dmamap_destroy "ic" "chan" 221Destroy the DMA map for DMA channel 222.Fa chan . 223.It Fn isa_dmamem_alloc "ic" "chan" "size" "addrp" "flags" 224Allocate DMA-safe memory of size 225.Fa size 226for channel 227.Fa chan . 228Valid values for the 229.Fa flags 230argument are the same as for 231.Fn bus_dmamem_alloc 232(see 233.Xr bus_dma 9 ) . 234The bus-address of the memory is returned in 235.Fa addrp . 236This function returns zero on success or an error value on failure. 237.It Fn isa_dmamem_free "ic" "chan" "addr" "size" 238Frees memory previously allocated by 239.Fn isa_dmamem_alloc 240for channel 241.Fa chan . 242The bus-address and size of the memory are specified by 243.Fa addr 244and 245.Fa size 246respectively. 247.It Fn isa_dmamem_map "ic" "chan" "addr" "size" "kvap" "flags" 248Maps DMA-safe memory (allocated with 249.Fn isa_dmamem_alloc ) 250specified by bus-address 251.Fa addr 252and of size 253.Fa size 254into kernel virtual address space for DMA channel 255.Fa chan . 256Valid values for the 257.Fa flags 258argument are the same as for 259.Fn bus_dmamem_map 260(see 261.Xr bus_dma 9 ) . 262The kernel virtual address is returned in 263.Fa kvap . 264This function returns zero on success or an error value on failure. 265.It Fn isa_dmamem_unmap "ic" "chan" "kva" "size" 266Unmaps memory (previously mapped with 267.Fn isa_dmamem_map ) 268of size 269.Fa size 270for channel 271.Fa chan . 272The kernel virtual address space used by the mapping is freed. 273.It Fn isa_malloc "ic" "chan" "size" "pool" "flags" 274This function is a shortcut for allocating and mapping DMA-safe memory 275in a single step. 276The arguments correspond with the arguments to 277.Fn isa_dmamem_alloc 278and 279.Fn isa_dmamem_map . 280The argument 281.Fa pool 282is a pool to record the memory allocation. 283This function returns a pointer to the DMA-safe memory. 284.It Fn isa_free "addrp" "pool" 285This function is a shortcut for unmapping and deallocating DMA-safe 286memory in a single step. 287It replaces 288.Fn isa_dmamem_unmap 289and 290.Fn isa_dmamem_free . 291The argument 292.Fa addrp 293is the pointer to the DMA-safe memory returned by 294.Fn isa_malloc . 295The argument 296.Fa pool 297is the same as the value passed to 298.Fn isa_malloc . 299.It Fn isa_dmastart "ic" "chan" "addr" "size" "proc" "flags" "bf" 300Load DMA memory specified by address 301.Fa addr 302of size 303.Fa size 304into the DMA controller at channel 305.Fa chan 306and set it in motion. 307The argument 308.Fa proc 309is used to indicate the address space in which the buffer is located. 310If NULL, the buffer is assumed to be in kernel space. 311Otherwise, the buffer is assumed to be in process 312.Fa proc 's 313address space. 314The argument 315.Fa flags 316describes the type of ISA DMA. 317Valid values are: 318.Bl -tag -width compact 319.It DMAMODE_WRITE 320DMA transfer from host to device. 321.It DMAMODE_READ 322DMA transfer to host from device. 323.It DMAMODE_SINGLE 324Transfer buffer once and stop. 325.It DMAMODE_DEMAND 326Demand mode. 327.It DMAMODE_LOOP 328Transfer buffer continuously in loop until notified to stop. 329.It DMAMODE_LOOPDEMAND 330Transfer buffer continuously in loop and demand mode. 331.El 332.sp 333The argument 334.Fa bf 335is the bus-space flags. 336Valid values are the same as for 337.Fn bus_dmamap_load 338(see 339.Xr bus_dma 9 ) . 340.It Fn isa_dmaabort "ic" "chan" 341Abort a DMA transfer on channel 342.Fa chan . 343.It Fn isa_dmacount "ic" "chan" 344Returns the offset in the DMA memory of the current DMA transfer on 345channel 346.Fa chan . 347.It Fn isa_dmadone "ic" "chan" 348Unloads the DMA memory 349on channel 350.Fa chan 351after a DMA transfer has completed. 352.It Fn isa_dmamaxsize "ic" "chan" 353Returns the maximum allowable DMA transfer size for channel 354.Fa chan . 355.It Fn isa_drq_isfree "ic" "chan" 356If the 357.Fa ia_drq 358or 359.Fa ia_drq2 360members of 361.Fa struct isa_attach_args 362are wildcarded, then the driver is expected to probe the hardware for 363valid DMA channels. 364In this case, the driver can check to see if the hardware-supported 365DMA channel 366.Fa chan 367is available for use. 368.It Fn isa_dmacascade "ic" "chan" 369Programs the 8237 DMA controller channel 370.Fa chan 371to accept external DMA control by the device hardware. 372.It Fn isa_mappage "mem" "offset" "prot" 373Provides support for user 374.Xr mmap 2 'ing 375of DMA-safe memory. 376.El 377.Sh AUTOCONFIGURATION 378The ISA bus is an indirect-connection bus. 379During autoconfiguration each driver is required to probe the bus 380for the presence of a device. 381An ISA driver will receive a pointer to 382.Fa struct isa_attach_args 383hinting at "locations" on the ISA bus where the device may be located. 384They should use the 385.Em ia_iobase , 386.Em ia_iosize , 387.Em ia_maddr , 388and 389.Em ia_msize 390members. 391Not all of these hints will be necessary; locators may be wildcarded 392with IOBASEUNK and MADDRUNK for 393.Em ia_iobase 394and 395.Em ia_maddr 396respectively. 397If a driver can probe the device for configuration information at default 398locations, it may update the members of 399.Fa struct isa_attach_args . 400The IRQ and DMA locators can also be wildcarded with IRQUNK and DRQUNK 401respectively. 402.Pp 403During the driver attach step, the I/O and memory address spaces 404should be mapped (see 405.Xr bus_space 9 ) . 406.Sh DMA SUPPORT 407Extensive DMA facilities are provided for the ISA bus. 408A driver can use up to two DMA channels simultaneously. 409The DMA channels allocated during autoconfiguration are passed to the 410driver during the driver attach using the 411.Fa ia_drq 412and 413.Fa ia_drq2 414members of 415.Fa struct isa_attach_args . 416.Pp 417Before allocating resources for DMA transfers on the ISA bus, a driver 418should check the maximum allowable DMA transfer size for the DMA 419channel using 420.Fn isa_dmamaxsize . 421.Pp 422A DMA map should be created first using 423.Fn isa_dmamap_create . 424A DMA map describes how DMA memory is loaded into the DMA controllers. 425Only DMA-safe memory can be used for DMA transfers. 426DMA-safe memory is allocated using 427.Fn isa_dmamem_alloc . 428The memory allocated by 429.Fn isa_dmamem_alloc 430must now be mapped into kernel virtual address space by 431.Fn isa_dmamem_map 432so that it can be accessed by the driver. 433.Pp 434For a DMA transfer from the host to the device, the driver will fill 435the DMA memory with the data to be transferred. 436The DMA-transfer of the memory is started using 437.Fn isa_dmastart 438with 439.Fa flags 440containing DMAMODE_WRITE. 441When the DMA transfer is completed, a call to 442.Fn isa_dmadone 443cleans up the DMA transfer by unloading the memory from the 444controller. 445.Pp 446For a DMA transfer from the device to the host, the DMA-transfer is 447started using 448.Fn isa_dmastart 449with 450.Fa flags 451containing DMAMODE_READ. 452When the DMA transfer is completed, a call to 453.Fn isa_dmadone 454cleans up the DMA transfer by unloading the memory from the 455controller. 456The memory can now be access by the driver. 457.Pp 458When the DMA resources are no longer required they should be released 459using 460.Fn isa_dmamem_unmap , 461.Fn isa_dmamem_free 462and 463.Fn isa_dmamap_destroy . 464.Sh CODE REFERENCES 465This section describes places within the 466.Nx 467source tree where actual code implementing or utilising the 468machine-independent ISA subsystem can be found. 469All pathnames are relative to 470.Pa /usr/src . 471.Pp 472The ISA subsystem itself is implemented within the files 473.Pa sys/dev/isa/isa.c 474and 475.Pa sys/dev/isa/isadma.c . 476.Sh SEE ALSO 477.Xr isa 4 , 478.Xr autoconf 9 , 479.Xr bus_dma 9 , 480.Xr bus_space 9 , 481.Xr driver 9 , 482.Xr isapnp 9 483.Sh HISTORY 484The machine-independent 485.Nm 486subsystem appeared in 487.Nx 1.2 . 488.Sh BUGS 489The previous behaviour of 490.Fn isa_intr_establish 491was to invoke 492.Fn panic 493on failure. 494.Fn isa_intr_establish 495now returns NULL on failure. 496Some old drivers written for the former behaviour discard the return value. 497