1.\" -*- nroff -*- 2.\" 3.\" Copyright (c) 2016 John H. Baldwin <jhb@FreeBSD.org> 4.\" All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 15.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 16.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 17.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 18.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 19.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 20.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 21.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 22.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 23.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 24.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 25.\" SUCH DAMAGE. 26.\" 27.\" $FreeBSD$ 28.\" 29.Dd May 20, 2016 30.Dt BUS_MAP_RESOURCE 9 31.Os 32.Sh NAME 33.Nm bus_map_resource , bus_unmap_resource , resource_init_map_request 34.Nd map or unmap an active resource 35.Sh SYNOPSIS 36.In sys/param.h 37.In sys/bus.h 38.Pp 39.In machine/bus.h 40.In sys/rman.h 41.In machine/resource.h 42.Ft int 43.Fo bus_map_resource 44.Fa "device_t dev" "int type" "struct resource *r" 45.Fa "struct resource_map_request *args" "struct resource_map *map" 46.Fc 47.Ft int 48.Fo bus_unmap_resource 49.Fa "device_t dev" "int type" "struct resource *r" "struct resource_map *map" 50.Fc 51.Ft void 52.Fn resource_init_map_request "struct resource_map_request *args" 53.Sh DESCRIPTION 54These functions create or destroy a mapping of a previously activated 55resource. 56Mappings permit CPU access to the resource via the 57.Xr bus_space 9 58API. 59.Pp 60The arguments are as follows: 61.Bl -tag -width indent 62.It Fa dev 63The device that owns the resource. 64.It Fa type 65The type of resource to map. 66It is one of: 67.Pp 68.Bl -tag -width ".Dv SYS_RES_MEMORY" -compact 69.It Dv SYS_RES_IOPORT 70for I/O ports 71.It Dv SYS_RES_MEMORY 72for I/O memory 73.El 74.It Fa r 75A pointer to the 76.Vt "struct resource" 77returned by 78.Xr bus_alloc_resource 9 . 79.It Fa args 80A set of optional properties to apply when creating a mapping. 81This argument can be set to 82.Dv NULL 83to request a mapping of the entire resource with the default properties. 84.It Fa map 85The resource mapping to create or destroy. 86.El 87.Ss Resource Mappings 88Resource mappings are described by a 89.Vt "struct resource_map" 90object. 91This structure contains a 92.Xr bus_space 9 93tag and handle in the 94.Va r_bustag 95and 96.Va r_bushandle 97members that can be used for CPU access to the mapping. 98The structure also contains a 99.Va r_vaddr 100member which contains the virtual address of the mapping if one exists. 101.Pp 102The wrapper API for 103.Vt "struct resource" 104objects described in 105.Xr bus_activate_resource 9 106can also be used with 107.Vt "struct resource_map" . 108For example, 109a pointer to a mapping object can be passed as the first argument to 110.Fn bus_read_4 . 111This wrapper API is preferred over using the 112.Va r_bustag 113and 114.Va r_bushandle 115members directly. 116.Ss Optional Mapping Properties 117The 118.Vt "struct resource_map_request" 119object passed in 120.Fa args 121can be used to specify optional properties of a mapping. 122The structure must be initialized by invoking 123.Fn resource_init_map_request . 124Properties are then specified by setting one or more of these members: 125.Bl -tag -width indent 126.It Va offset , length 127These two members specify a region of the resource to map. 128By default a mapping is created for the entire resource. 129The 130.Va offset 131is relative to the start of the resource. 132.It Va memattr 133Specifies a memory attribute to use when mapping the resource. 134By default memory mappings use the 135.Dv VM_MEMATTR_UNCACHEABLE 136attribute. 137.El 138.Sh EXAMPLES 139This maps a PCI memory BAR with the write-combining memory attribute and 140reads the first 32-bit word: 141.Bd -literal 142 struct resource *r; 143 struct resource_map map; 144 struct resource_map_args args; 145 uint32_t val; 146 int rid; 147 148 rid = PCIR_BAR(0); 149 r = bus_alloc_resource_any(dev, SYS_RES_MEMORY, &rid, RF_ACTIVE | 150 RF_UNMAPPED); 151 resource_init_map_request(&args); 152 args.memattr = VM_MEMATTR_WRITE_COMBINING; 153 bus_map_resource(dev, SYS_RES_MEMORY, r, &args, &map); 154 val = bus_read_4(&map, 0); 155.Ed 156.Pp 157.Sh RETURN VALUES 158Zero is returned on success, otherwise an error is returned. 159.Sh SEE ALSO 160.Xr bus_activate_resource 9 , 161.Xr bus_alloc_resource 9 , 162.Xr bus_space 9 , 163.Xr device 9 , 164.Xr driver 9 165.Sh AUTHORS 166This manual page was written by 167.An John Baldwin Aq Mt jhb@FreeBSD.org . 168