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.7 2005/05/24 20:58:41 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. For instance the TurboLaser bus prints which node the 52# device is attached to. See bus_generic_print_child.9 for more 53# information. 54# This method returns the number of characters output. 55# 56METHOD int print_child { 57 device_t dev; 58 device_t child; 59} DEFAULT bus_generic_print_child; 60 61# 62# Called for each child device that 63# did not succeed in probing for a 64# driver. 65# 66METHOD void probe_nomatch { 67 device_t dev; 68 device_t child; 69}; 70 71# 72# These two methods manage a bus specific set of instance variables of 73# a child device. The intention is that each different type of bus 74# defines a set of appropriate instance variables (such as ports and 75# irqs for ISA bus etc.) 76# 77# This information could be given to the child device as a struct but 78# that makes it hard for a bus to add or remove variables without 79# forcing an edit and recompile for all drivers which may not be 80# possible for vendor supplied binary drivers. 81 82# 83# Read an instance variable. Return 0 on success. 84# 85METHOD int read_ivar { 86 device_t dev; 87 device_t child; 88 int index; 89 uintptr_t *result; 90}; 91 92# 93# Write an instance variable. Return 0 on success. 94# 95METHOD int write_ivar { 96 device_t dev; 97 device_t child; 98 int index; 99 uintptr_t value; 100}; 101 102# 103# Called after the child's DEVICE_DETACH method to allow the parent 104# to reclaim any resources allocated on behalf of the child. 105# 106METHOD void child_detached { 107 device_t dev; 108 device_t child; 109}; 110 111# 112# Called when a new driver is added to the devclass which owns this 113# bus. The generic implementation of this method attempts to probe and 114# attach any un-matched children of the bus. 115# 116METHOD void driver_added { 117 device_t dev; 118 driver_t *driver; 119} DEFAULT bus_generic_driver_added; 120 121# 122# For busses which use use drivers supporting DEVICE_IDENTIFY to 123# enumerate their devices, these methods are used to create new 124# device instances. If place is non-NULL, the new device will be 125# added after the last existing child with the same order. 126# 127METHOD device_t add_child { 128 device_t dev; 129 int order; 130 const char *name; 131 int unit; 132}; 133 134# 135# Allocate a system resource attached to `dev' on behalf of `child'. 136# The types are defined in <machine/resource.h>; the meaning of the 137# resource-ID field varies from bus to bus (but *rid == 0 is always 138# valid if the resource type is). start and end reflect the allowable 139# range, and should be passed as `0UL' and `~0UL', respectively, if 140# the client has no range restriction. count is the number of consecutive 141# indices in the resource required. flags is a set of sharing flags 142# as defined in <sys/rman.h>. 143# 144# Returns a resource or a null pointer on failure. The caller is 145# responsible for calling rman_activate_resource() when it actually 146# uses the resource. 147# 148METHOD struct resource * alloc_resource { 149 device_t dev; 150 device_t child; 151 int type; 152 int *rid; 153 u_long start; 154 u_long end; 155 u_long count; 156 u_int flags; 157} DEFAULT null_alloc_resource; 158 159METHOD int activate_resource { 160 device_t dev; 161 device_t child; 162 int type; 163 int rid; 164 struct resource *r; 165}; 166 167METHOD int deactivate_resource { 168 device_t dev; 169 device_t child; 170 int type; 171 int rid; 172 struct resource *r; 173}; 174 175# 176# Free a resource allocated by the preceding method. The `rid' value 177# must be the same as the one returned by BUS_ALLOC_RESOURCE (which 178# is not necessarily the same as the one the client passed). 179# 180METHOD int release_resource { 181 device_t dev; 182 device_t child; 183 int type; 184 int rid; 185 struct resource *res; 186}; 187 188METHOD int setup_intr { 189 device_t dev; 190 device_t child; 191 struct resource *irq; 192 int flags; 193 driver_intr_t *intr; 194 void *arg; 195 void **cookiep; 196 lwkt_serialize_t serializer; 197}; 198 199METHOD int teardown_intr { 200 device_t dev; 201 device_t child; 202 struct resource *irq; 203 void *cookie; 204}; 205 206# Enable or disable an interrupt. The device is generally expected to do 207# the physical enablement and disablement. The bus code must flag the 208# condition so it does not call the handler from a scheduled interrupt thread, 209# since the hard interrupt might be disabled after the interrupt thread 210# has been scheduled but before it runs. 211# 212# The disable function returns an indication as to whether the handler 213# is currently running (i.e. the disablement is racing the execution of 214# the interrupt handler). 0 is returned if it isn't, non-zero if it is. 215# 216# The disablement function does NOT interlock against a running handler, it 217# simply prevents future handler calls from being made. 218# 219METHOD void enable_intr { 220 device_t dev; 221 device_t child; 222 void *cookie; 223} DEFAULT bus_generic_enable_intr; 224 225METHOD int disable_intr { 226 device_t dev; 227 device_t child; 228 void *cookie; 229} DEFAULT bus_generic_disable_intr; 230 231# 232# Set the range used for a particular resource. Return EINVAL if 233# the type or rid are out of range. 234# 235METHOD int set_resource { 236 device_t dev; 237 device_t child; 238 int type; 239 int rid; 240 u_long start; 241 u_long count; 242}; 243 244# 245# Get the range for a resource. Return ENOENT if the type or rid are 246# out of range or have not been set. 247# 248METHOD int get_resource { 249 device_t dev; 250 device_t child; 251 int type; 252 int rid; 253 u_long *startp; 254 u_long *countp; 255}; 256 257# 258# Delete a resource. 259# 260METHOD void delete_resource { 261 device_t dev; 262 device_t child; 263 int type; 264 int rid; 265}; 266 267# 268# Return a struct resource_list. 269# 270METHOD struct resource_list * get_resource_list { 271 device_t _dev; 272 device_t _child; 273} DEFAULT bus_generic_get_resource_list; 274 275# 276# Is the hardware described by _child still attached to the system? 277# 278# This method should return 0 if the device is not present. It should 279# return -1 if it is present. Any errors in determining should be 280# returned as a normal errno value. Client drivers are to assume that 281# the device is present, even if there is an error determining if it is 282# there. Busses are to try to avoid returning errors, but newcard will return 283# an error if the device fails to implement this method. 284# 285METHOD int child_present { 286 device_t _dev; 287 device_t _child; 288} DEFAULT bus_generic_child_present; 289 290# 291# Returns the pnp info for this device. Return it as a string. If the 292# string is insufficient for the storage, then return EOVERFLOW. 293# 294METHOD int child_pnpinfo_str { 295 device_t _dev; 296 device_t _child; 297 char *_buf; 298 size_t _buflen; 299}; 300 301# 302# Returns the location for this device. Return it as a string. If the 303# string is insufficient for the storage, then return EOVERFLOW. 304# 305METHOD int child_location_str { 306 device_t _dev; 307 device_t _child; 308 char *_buf; 309 size_t _buflen; 310}; 311 312# 313# Allow (bus) drivers to specify the trigger mode and polarity of the 314# specified interrupt. 315# 316METHOD int config_intr { 317 device_t _dev; 318 int _irq; 319 enum intr_trigger _trig; 320 enum intr_polarity _pol; 321} DEFAULT bus_generic_config_intr; 322 323