share/man/man9/bus_map_resource.9

   1 .\" -*- nroff -*-
   2 .\"
   3 .\" Copyright (c) 2016 John H. Baldwin <jhb@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 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$
  27 .\"
  28 .Dd February 5, 2018
  29 .Dt BUS_MAP_RESOURCE 9
  30 .Os
  31 .Sh NAME
  32 .Nm bus_map_resource , bus_unmap_resource , resource_init_map_request
  33 .Nd map or unmap an active resource
  34 .Sh SYNOPSIS
  35 .In sys/param.h
  36 .In sys/bus.h
  37 .Pp
  38 .In machine/bus.h
  39 .In sys/rman.h
  40 .In machine/resource.h
  41 .Ft int
  42 .Fo bus_map_resource
  43 .Fa "device_t dev" "int type" "struct resource *r"
  44 .Fa "struct resource_map_request *args" "struct resource_map *map"
  45 .Fc
  46 .Ft int
  47 .Fo bus_unmap_resource
  48 .Fa "device_t dev" "int type" "struct resource *r" "struct resource_map *map"
  49 .Fc
  50 .Ft void
  51 .Fn resource_init_map_request "struct resource_map_request *args"
  52 .Sh DESCRIPTION
  53 These functions create or destroy a mapping of a previously activated
  54 resource.
  55 Mappings permit CPU access to the resource via the
  56 .Xr bus_space 9
  57 API.
  58 .Pp
  59 The arguments are as follows:
  60 .Bl -tag -width indent
  61 .It Fa dev
  62 The device that owns the resource.
  63 .It Fa type
  64 The type of resource to map.
  65 It is one of:
  66 .Pp
  67 .Bl -tag -width ".Dv SYS_RES_MEMORY" -compact
  68 .It Dv SYS_RES_IOPORT
  69 for I/O ports
  70 .It Dv SYS_RES_MEMORY
  71 for I/O memory
  72 .El
  73 .It Fa r
  74 A pointer to the
  75 .Vt "struct resource"
  76 returned by
  77 .Xr bus_alloc_resource 9 .
  78 .It Fa args
  79 A set of optional properties to apply when creating a mapping.
  80 This argument can be set to
  81 .Dv NULL
  82 to request a mapping of the entire resource with the default properties.
  83 .It Fa map
  84 The resource mapping to create or destroy.
  85 .El
  86 .Ss Resource Mappings
  87 Resource mappings are described by a
  88 .Vt "struct resource_map"
  89 object.
  90 This structure contains a
  91 .Xr bus_space 9
  92 tag and handle in the
  93 .Va r_bustag
  94 and
  95 .Va r_bushandle
  96 members that can be used for CPU access to the mapping.
  97 The structure also contains a
  98 .Va r_vaddr
  99 member which contains the virtual address of the mapping if one exists.
 100 .Pp
 101 The wrapper API for
 102 .Vt "struct resource"
 103 objects described in
 104 .Xr bus_activate_resource 9
 105 can also be used with
 106 .Vt "struct resource_map" .
 107 For example,
 108 a pointer to a mapping object can be passed as the first argument to
 109 .Fn bus_read_4 .
 110 This wrapper API is preferred over using the
 111 .Va r_bustag
 112 and
 113 .Va r_bushandle
 114 members directly.
 115 .Ss Optional Mapping Properties
 116 The
 117 .Vt "struct resource_map_request"
 118 object passed in
 119 .Fa args
 120 can be used to specify optional properties of a mapping.
 121 The structure must be initialized by invoking
 122 .Fn resource_init_map_request .
 123 Properties are then specified by setting one or more of these members:
 124 .Bl -tag -width indent
 125 .It Va offset , length
 126 These two members specify a region of the resource to map.
 127 By default a mapping is created for the entire resource.
 128 The
 129 .Va offset
 130 is relative to the start of the resource.
 131 .It Va memattr
 132 Specifies a memory attribute to use when mapping the resource.
 133 By default memory mappings use the
 134 .Dv VM_MEMATTR_UNCACHEABLE
 135 attribute.
 136 .El
 137 .Sh RETURN VALUES
 138 Zero is returned on success, otherwise an error is returned.
 139 .Sh EXAMPLES
 140 This maps a PCI memory BAR with the write-combining memory attribute and
 141 reads the first 32-bit word:
 142 .Bd -literal
 143         struct resource *r;
 144         struct resource_map map;
 145         struct resource_map_request req;
 146         uint32_t val;
 147         int rid;
 148
 149         rid = PCIR_BAR(0);
 150         r = bus_alloc_resource_any(dev, SYS_RES_MEMORY, &rid, RF_ACTIVE |
 151             RF_UNMAPPED);
 152         resource_init_map_request(&req);
 153         req.memattr = VM_MEMATTR_WRITE_COMBINING;
 154         bus_map_resource(dev, SYS_RES_MEMORY, r, &req, &map);
 155         val = bus_read_4(&map, 0);
 156 .Ed
 157 .Sh SEE ALSO
 158 .Xr bus_activate_resource 9 ,
 159 .Xr bus_alloc_resource 9 ,
 160 .Xr bus_space 9 ,
 161 .Xr device 9 ,
 162 .Xr driver 9
 163 .Sh AUTHORS
 164 This manual page was written by
 165 .An John Baldwin Aq Mt jhb@FreeBSD.org .