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