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