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