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 53These functions create or destroy a mapping of a previously activated 54resource. 55Mappings permit CPU access to the resource via the 56.Xr bus_space 9 57API. 58.Pp 59The arguments are as follows: 60.Bl -tag -width indent 61.It Fa dev 62The device that owns the resource. 63.It Fa type 64The type of resource to map. 65It is one of: 66.Pp 67.Bl -tag -width ".Dv SYS_RES_MEMORY" -compact 68.It Dv SYS_RES_IOPORT 69for I/O ports 70.It Dv SYS_RES_MEMORY 71for I/O memory 72.El 73.It Fa r 74A pointer to the 75.Vt "struct resource" 76returned by 77.Xr bus_alloc_resource 9 . 78.It Fa args 79A set of optional properties to apply when creating a mapping. 80This argument can be set to 81.Dv NULL 82to request a mapping of the entire resource with the default properties. 83.It Fa map 84The resource mapping to create or destroy. 85.El 86.Ss Resource Mappings 87Resource mappings are described by a 88.Vt "struct resource_map" 89object. 90This structure contains a 91.Xr bus_space 9 92tag and handle in the 93.Va r_bustag 94and 95.Va r_bushandle 96members that can be used for CPU access to the mapping. 97The structure also contains a 98.Va r_vaddr 99member which contains the virtual address of the mapping if one exists. 100.Pp 101The wrapper API for 102.Vt "struct resource" 103objects described in 104.Xr bus_activate_resource 9 105can also be used with 106.Vt "struct resource_map" . 107For example, 108a pointer to a mapping object can be passed as the first argument to 109.Fn bus_read_4 . 110This wrapper API is preferred over using the 111.Va r_bustag 112and 113.Va r_bushandle 114members directly. 115.Ss Optional Mapping Properties 116The 117.Vt "struct resource_map_request" 118object passed in 119.Fa args 120can be used to specify optional properties of a mapping. 121The structure must be initialized by invoking 122.Fn resource_init_map_request . 123Properties are then specified by setting one or more of these members: 124.Bl -tag -width indent 125.It Va offset , length 126These two members specify a region of the resource to map. 127By default a mapping is created for the entire resource. 128The 129.Va offset 130is relative to the start of the resource. 131.It Va memattr 132Specifies a memory attribute to use when mapping the resource. 133By default memory mappings use the 134.Dv VM_MEMATTR_UNCACHEABLE 135attribute. 136.El 137.Sh RETURN VALUES 138Zero is returned on success, otherwise an error is returned. 139.Sh EXAMPLES 140This maps a PCI memory BAR with the write-combining memory attribute and 141reads 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 164This manual page was written by 165.An John Baldwin Aq Mt jhb@FreeBSD.org . 166