1# 2# Copyright (c) 1998 Doug Rabson 3# All rights reserved. 4# 5# Redistribution and use in source and binary forms, with or without 6# modification, are permitted provided that the following conditions 7# are met: 8# 1. Redistributions of source code must retain the above copyright 9# notice, this list of conditions and the following disclaimer. 10# 2. Redistributions in binary form must reproduce the above copyright 11# notice, this list of conditions and the following disclaimer in the 12# documentation and/or other materials provided with the distribution. 13# 14# THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 15# ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 16# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 17# ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 18# FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 19# DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 20# OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 21# HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 22# LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 23# OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 24# SUCH DAMAGE. 25# 26# $FreeBSD: src/sys/kern/bus_if.m,v 1.16 1999/10/12 21:35:50 dfr Exp $ 27# $DragonFly: src/sys/kern/bus_if.m,v 1.11 2006/10/25 20:56:02 dillon Exp $ 28# 29 30#include <sys/bus.h> 31 32INTERFACE bus; 33 34# 35# Default implementations of some methods. 36# 37CODE { 38 static struct resource * 39 null_alloc_resource(device_t dev, device_t child, 40 int type, int *rid, 41 u_long start, u_long end, 42 u_long count, u_int flags) 43 { 44 return 0; 45 } 46}; 47 48# 49# This is called from system code which prints out a description of a 50# device. It should describe the attachment that the child has with 51# the parent. See bus_generic_print_child.9 for more information. 52# This method returns the number of characters output. 53# 54METHOD int print_child { 55 device_t dev; 56 device_t child; 57} DEFAULT bus_generic_print_child; 58 59# 60# Called for each child device that 61# did not succeed in probing for a 62# driver. 63# 64METHOD void probe_nomatch { 65 device_t dev; 66 device_t child; 67}; 68 69# 70# These two methods manage a bus specific set of instance variables of 71# a child device. The intention is that each different type of bus 72# defines a set of appropriate instance variables (such as ports and 73# irqs for ISA bus etc.) 74# 75# This information could be given to the child device as a struct but 76# that makes it hard for a bus to add or remove variables without 77# forcing an edit and recompile for all drivers which may not be 78# possible for vendor supplied binary drivers. 79 80# 81# Read an instance variable. Return 0 on success. 82# 83METHOD int read_ivar { 84 device_t dev; 85 device_t child; 86 int index; 87 uintptr_t *result; 88}; 89 90# 91# Write an instance variable. Return 0 on success. 92# 93METHOD int write_ivar { 94 device_t dev; 95 device_t child; 96 int index; 97 uintptr_t value; 98}; 99 100# 101# Called after the child's DEVICE_DETACH method to allow the parent 102# to reclaim any resources allocated on behalf of the child. 103# 104METHOD void child_detached { 105 device_t dev; 106 device_t child; 107}; 108 109# 110# Called when a new driver is added to the devclass which owns this 111# bus. The generic implementation of this method attempts to probe and 112# attach any un-matched children of the bus. 113# 114METHOD void driver_added { 115 device_t dev; 116 driver_t *driver; 117} DEFAULT bus_generic_driver_added; 118 119# 120# For busses which use drivers supporting DEVICE_IDENTIFY to 121# enumerate their devices, these methods are used to create new 122# device instances. If place is non-NULL, the new device will be 123# added after the last existing child with the same order. 124# 125# bus is an entity which may iterate up through the bus heirarchy 126# while parent is the parent device under which the child should be 127# added. 128# 129METHOD device_t add_child { 130 device_t bus; 131 device_t parent; 132 int order; 133 const char *name; 134 int unit; 135}; 136 137# 138# Allocate a system resource attached to `dev' on behalf of `child'. 139# The types are defined in <sys/bus_resource.h>; the meaning of the 140# resource-ID field varies from bus to bus (but *rid == 0 is always 141# valid if the resource type is). start and end reflect the allowable 142# range, and should be passed as `0UL' and `~0UL', respectively, if 143# the client has no range restriction. count is the number of consecutive 144# indices in the resource required. flags is a set of sharing flags 145# as defined in <sys/rman.h>. 146# 147# Returns a resource or a null pointer on failure. The caller is 148# responsible for calling rman_activate_resource() when it actually 149# uses the resource. 150# 151METHOD struct resource * alloc_resource { 152 device_t dev; 153 device_t child; 154 int type; 155 int *rid; 156 u_long start; 157 u_long end; 158 u_long count; 159 u_int flags; 160} DEFAULT null_alloc_resource; 161 162METHOD int activate_resource { 163 device_t dev; 164 device_t child; 165 int type; 166 int rid; 167 struct resource *r; 168}; 169 170METHOD int deactivate_resource { 171 device_t dev; 172 device_t child; 173 int type; 174 int rid; 175 struct resource *r; 176}; 177 178# 179# Free a resource allocated by the preceding method. The `rid' value 180# must be the same as the one returned by BUS_ALLOC_RESOURCE (which 181# is not necessarily the same as the one the client passed). 182# 183METHOD int release_resource { 184 device_t dev; 185 device_t child; 186 int type; 187 int rid; 188 struct resource *res; 189}; 190 191METHOD int setup_intr { 192 device_t dev; 193 device_t child; 194 struct resource *irq; 195 int flags; 196 driver_intr_t *intr; 197 void *arg; 198 void **cookiep; 199 lwkt_serialize_t serializer; 200}; 201 202METHOD int teardown_intr { 203 device_t dev; 204 device_t child; 205 struct resource *irq; 206 void *cookie; 207}; 208 209# Enable or disable an interrupt. The device is generally expected to do 210# the physical enablement and disablement. The bus code must flag the 211# condition so it does not call the handler from a scheduled interrupt thread, 212# since the hard interrupt might be disabled after the interrupt thread 213# has been scheduled but before it runs. 214# 215# The disable function returns an indication as to whether the handler 216# is currently running (i.e. the disablement is racing the execution of 217# the interrupt handler). 0 is returned if it isn't, non-zero if it is. 218# 219# The disablement function does NOT interlock against a running handler, it 220# simply prevents future handler calls from being made. 221# 222METHOD void enable_intr { 223 device_t dev; 224 device_t child; 225 void *cookie; 226} DEFAULT bus_generic_enable_intr; 227 228METHOD int disable_intr { 229 device_t dev; 230 device_t child; 231 void *cookie; 232} DEFAULT bus_generic_disable_intr; 233 234# 235# Set the range used for a particular resource. Return EINVAL if 236# the type or rid are out of range. 237# 238METHOD int set_resource { 239 device_t dev; 240 device_t child; 241 int type; 242 int rid; 243 u_long start; 244 u_long count; 245}; 246 247# 248# Get the range for a resource. Return ENOENT if the type or rid are 249# out of range or have not been set. 250# 251METHOD int get_resource { 252 device_t dev; 253 device_t child; 254 int type; 255 int rid; 256 u_long *startp; 257 u_long *countp; 258}; 259 260# 261# Delete a resource. 262# 263METHOD void delete_resource { 264 device_t dev; 265 device_t child; 266 int type; 267 int rid; 268}; 269 270# 271# Return a struct resource_list. 272# 273METHOD struct resource_list * get_resource_list { 274 device_t _dev; 275 device_t _child; 276} DEFAULT bus_generic_get_resource_list; 277 278# 279# Is the hardware described by _child still attached to the system? 280# 281# This method should return 0 if the device is not present. It should 282# return -1 if it is present. Any errors in determining should be 283# returned as a normal errno value. Client drivers are to assume that 284# the device is present, even if there is an error determining if it is 285# there. Busses are to try to avoid returning errors, but newcard will return 286# an error if the device fails to implement this method. 287# 288METHOD int child_present { 289 device_t _dev; 290 device_t _child; 291} DEFAULT bus_generic_child_present; 292 293# 294# Returns the pnp info for this device. Return it as a string. If the 295# string is insufficient for the storage, then return EOVERFLOW. 296# 297METHOD int child_pnpinfo_str { 298 device_t _dev; 299 device_t _child; 300 char *_buf; 301 size_t _buflen; 302}; 303 304# 305# Returns the location for this device. Return it as a string. If the 306# string is insufficient for the storage, then return EOVERFLOW. 307# 308METHOD int child_location_str { 309 device_t _dev; 310 device_t _child; 311 char *_buf; 312 size_t _buflen; 313}; 314 315# 316# Allow (bus) drivers to specify the trigger mode and polarity of the 317# specified interrupt. 318# 319METHOD int config_intr { 320 device_t _dev; 321 int _irq; 322 enum intr_trigger _trig; 323 enum intr_polarity _pol; 324} DEFAULT bus_generic_config_intr; 325 326