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