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 March 13, 2024 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" "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" "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 r 62A pointer to the 63.Vt "struct resource" 64returned by 65.Xr bus_alloc_resource 9 . 66.It Fa args 67A set of optional properties to apply when creating a mapping. 68This argument can be set to 69.Dv NULL 70to request a mapping of the entire resource with the default properties. 71.It Fa map 72The resource mapping to create or destroy. 73.El 74.Ss Resource Mappings 75Resource mappings are described by a 76.Vt "struct resource_map" 77object. 78This structure contains a 79.Xr bus_space 9 80tag and handle in the 81.Va r_bustag 82and 83.Va r_bushandle 84members that can be used for CPU access to the mapping. 85The structure also contains a 86.Va r_vaddr 87member which contains the virtual address of the mapping if one exists. 88.Pp 89The wrapper API for 90.Vt "struct resource" 91objects described in 92.Xr bus_activate_resource 9 93can also be used with 94.Vt "struct resource_map" . 95For example, 96a pointer to a mapping object can be passed as the first argument to 97.Fn bus_read_4 . 98This wrapper API is preferred over using the 99.Va r_bustag 100and 101.Va r_bushandle 102members directly. 103.Ss Optional Mapping Properties 104The 105.Vt "struct resource_map_request" 106object passed in 107.Fa args 108can be used to specify optional properties of a mapping. 109The structure must be initialized by invoking 110.Fn resource_init_map_request . 111Properties are then specified by setting one or more of these members: 112.Bl -tag -width indent 113.It Va offset , length 114These two members specify a region of the resource to map. 115By default a mapping is created for the entire resource. 116The 117.Va offset 118is relative to the start of the resource. 119.It Va memattr 120Specifies a memory attribute to use when mapping the resource. 121By default memory mappings use the 122.Dv VM_MEMATTR_UNCACHEABLE 123attribute. 124.El 125.Sh RETURN VALUES 126Zero is returned on success, otherwise an error is returned. 127.Sh EXAMPLES 128This maps a PCI memory BAR with the write-combining memory attribute and 129reads the first 32-bit word: 130.Bd -literal 131 struct resource *r; 132 struct resource_map map; 133 struct resource_map_request req; 134 uint32_t val; 135 int rid; 136 137 rid = PCIR_BAR(0); 138 r = bus_alloc_resource_any(dev, SYS_RES_MEMORY, &rid, RF_ACTIVE | 139 RF_UNMAPPED); 140 resource_init_map_request(&req); 141 req.memattr = VM_MEMATTR_WRITE_COMBINING; 142 bus_map_resource(dev, SYS_RES_MEMORY, r, &req, &map); 143 val = bus_read_4(&map, 0); 144.Ed 145.Sh SEE ALSO 146.Xr bus_activate_resource 9 , 147.Xr bus_alloc_resource 9 , 148.Xr bus_space 9 , 149.Xr device 9 , 150.Xr driver 9 151.Sh AUTHORS 152This manual page was written by 153.An John Baldwin Aq Mt jhb@FreeBSD.org . 154