share/man/man9/bus_activate_resource.9

   1 .\" -*- nroff -*-
   2 .\"
   3 .\" Copyright (c) 2003 M. Warner Losh <imp@FreeBSD.org>
   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 DEVELOPERS ``AS IS'' AND ANY EXPRESS OR
  15 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  16 .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
  17 .\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT,
  18 .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  19 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  20 .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  21 .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  22 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
  23 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  24 .\"
  25 .\" $FreeBSD$
  26 .\"
  27 .Dd May 20, 2016
  28 .Dt BUS_ACTIVATE_RESOURCE 9
  29 .Os
  30 .Sh NAME
  31 .Nm bus_activate_resource , bus_deactivate_resource
  32 .Nd activate or deactivate a resource
  33 .Sh SYNOPSIS
  34 .In sys/param.h
  35 .In sys/bus.h
  36 .Pp
  37 .In machine/bus.h
  38 .In sys/rman.h
  39 .In machine/resource.h
  40 .Ft int
  41 .Fo bus_activate_resource
  42 .Fa "device_t dev" "int type" "int rid" "struct resource *r"
  43 .Fc
  44 .Ft int
  45 .Fo bus_deactivate_resource
  46 .Fa "device_t dev" "int type" "int rid" "struct resource *r"
  47 .Fc
  48 .Sh DESCRIPTION
  49 These functions activate or deactivate a previously allocated resource.
  50 In general, resources must be activated before they can be accessed by
  51 the driver.
  52 Bus drivers may perform additional actions to ensure that the resource is
  53 ready to be accessed.
  54 For example,
  55 the PCI bus driver enables memory decoding in a PCI device's command register
  56 when activating a memory resource.
  57 .Pp
  58 The arguments are as follows:
  59 .Bl -tag -width indent
  60 .It Fa dev
  61 The device that requests ownership of the resource.
  62 Before allocation, the resource is owned by the parent bus.
  63 .It Fa type
  64 The type of resource you want to allocate.
  65 It is one of:
  66 .Pp
  67 .Bl -tag -width ".Dv SYS_RES_MEMORY" -compact
  68 .It Dv PCI_RES_BUS
  69 for PCI bus numbers
  70 .It Dv SYS_RES_IRQ
  71 for IRQs
  72 .It Dv SYS_RES_DRQ
  73 for ISA DMA lines
  74 .It Dv SYS_RES_IOPORT
  75 for I/O ports
  76 .It Dv SYS_RES_MEMORY
  77 for I/O memory
  78 .El
  79 .It Fa rid
  80 A pointer to a bus specific handle that identifies the resource being allocated.
  81 .It Fa r
  82 A pointer to the
  83 .Vt "struct resource"
  84 returned by
  85 .Xr bus_alloc_resource 9 .
  86 .El
  87 .Ss Resource Mapping
  88 Resources which can be mapped for CPU access by a
  89 .Xr bus_space 9
  90 tag and handle will create a mapping of the entire resource when activated.
  91 The tag and handle for this mapping are stored in
  92 .Fa r
  93 and can be retrieved via
  94 .Xr rman_get_bustag 9
  95 and
  96 .Xr rman_get_bushandle 9 .
  97 These can be used with the
  98 .Xr bus_space 9
  99 API to access device registers or memory described by
 100 .Fa r .
 101 If the mapping is associated with a virtual address,
 102 the virtual address can be retrieved via
 103 .Xr rman_get_virtual 9 .
 104 .Pp
 105 This implicit mapping can be disabled by passing the
 106 .Dv RF_UNMAPPED
 107 flag to
 108 .Xr bus_alloc_resource 9 .
 109 A driver may use this if it wishes to allocate its own mappings of a resource
 110 using
 111 .Xr bus_map_resource 9 .
 112 .Pp
 113 A wrapper API for
 114 .Xr bus_space 9
 115 is also provided that accepts the associated resource as the first argument
 116 in place of the
 117 .Xr bus_space 9
 118 tag and handle.
 119 The functions in this wrapper API are named similarly to the
 120 .Xr bus_space 9
 121 API except that
 122 .Dq _space
 123 is removed from their name.
 124 For example,
 125 .Fn bus_read_4
 126 can be used in place of
 127 .Fn bus_space_read_4 .
 128 The wrapper API is preferred in new drivers.
 129 .Pp
 130 These two statements both read a 32-bit register at the start of a
 131 resource:
 132 .Bd -literal
 133         bus_space_read_4(rman_get_bustag(res), rman_get_bushandle(res), 0);
 134         bus_read_4(res, 0);
 135 .Ed
 136 .Sh RETURN VALUES
 137 Zero is returned on success, otherwise an error is returned.
 138 .Sh SEE ALSO
 139 .Xr bus_alloc_resource 9 ,
 140 .Xr bus_map_resource 9 ,
 141 .Xr bus_space 9 ,
 142 .Xr device 9 ,
 143 .Xr driver 9
 144 .Sh AUTHORS
 145 This manual page was written by
 146 .An Warner Losh Aq Mt imp@FreeBSD.org .