From owner-svn-src-all@freebsd.org Thu Apr 28 18:23:19 2016 Return-Path: Delivered-To: svn-src-all@mailman.ysv.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:1900:2254:206a::19:1]) by mailman.ysv.freebsd.org (Postfix) with ESMTP id E2D53B1F802; Thu, 28 Apr 2016 18:23:19 +0000 (UTC) (envelope-from jhb@FreeBSD.org) Received: from repo.freebsd.org (repo.freebsd.org [IPv6:2610:1c1:1:6068::e6a:0]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (Client did not present a certificate) by mx1.freebsd.org (Postfix) with ESMTPS id 9AC23187B; Thu, 28 Apr 2016 18:23:19 +0000 (UTC) (envelope-from jhb@FreeBSD.org) Received: from repo.freebsd.org ([127.0.1.37]) by repo.freebsd.org (8.15.2/8.15.2) with ESMTP id u3SINI9a027505; Thu, 28 Apr 2016 18:23:18 GMT (envelope-from jhb@FreeBSD.org) Received: (from jhb@localhost) by repo.freebsd.org (8.15.2/8.15.2/Submit) id u3SINIE2027504; Thu, 28 Apr 2016 18:23:18 GMT (envelope-from jhb@FreeBSD.org) Message-Id: <201604281823.u3SINIE2027504@repo.freebsd.org> X-Authentication-Warning: repo.freebsd.org: jhb set sender to jhb@FreeBSD.org using -f From: John Baldwin Date: Thu, 28 Apr 2016 18:23:18 +0000 (UTC) To: src-committers@freebsd.org, svn-src-all@freebsd.org, svn-src-head@freebsd.org Subject: svn commit: r298752 - head/share/man/man9 X-SVN-Group: head MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-BeenThere: svn-src-all@freebsd.org X-Mailman-Version: 2.1.21 Precedence: list List-Id: "SVN commit messages for the entire src tree \(except for " user" and " projects" \)" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Thu, 28 Apr 2016 18:23:20 -0000 Author: jhb Date: Thu Apr 28 18:23:18 2016 New Revision: 298752 URL: https://svnweb.freebsd.org/changeset/base/298752 Log: Add some notes about the implicit resource mapping for activated resources. Specifically, mention that rman_get_bustag/handle/virtual are valid after a resource is activated. Also, mention the wrapper API that accepts a struct resource instead of a bus tag and handle. Modified: head/share/man/man9/bus_activate_resource.9 Modified: head/share/man/man9/bus_activate_resource.9 ============================================================================== --- head/share/man/man9/bus_activate_resource.9 Thu Apr 28 18:01:25 2016 (r298751) +++ head/share/man/man9/bus_activate_resource.9 Thu Apr 28 18:23:18 2016 (r298752) @@ -52,8 +52,12 @@ .Sh DESCRIPTION These functions activate or deactivate a previously allocated resource. In general, resources must be activated before they can be accessed by -the driver so that the bus driver can map the resource into the -devices space. +the driver. +Bus drivers may perform additional actions to ensure that the resource is +ready to be accessed. +For example, +the PCI bus driver enables memory decoding in a PCI device's command register +when activating a memory resource. .Pp The arguments are as follows: .Bl -tag -width indent @@ -84,6 +88,47 @@ A pointer to the returned by .Xr bus_alloc_resource 9 . .El +.Ss Resource Mapping +Resources which can be mapped for CPU access by a +.Xr bus_space +tag and handle will create a mapping of the entire resource when activated. +The tag and handle for this mapping are stored in +.Fa r +and can be retrieved via +.Xr rman_get_bustag 9 +and +.Xr rman_get_bushandle 9 . +These can be used with the +.Xr bus_space 9 +API to access device registers or memory described by +.Fa r . +If the mapping is associated with a virtual address, +the virtual address can be retrieved via +.Xr rman_get_virtual 9 . +.Pp +A wrapper API for +.Xr bus_space 9 +is also provided that accepts the associated resource as the first argument +in place of the +.Xr bus_space 9 +tag and handle. +The functions in this wrapper API are named similarly to the +.Xr bus_space 9 +API except that +.Dq _space +is removed from their name. +For example, +.Fn bus_read_4 +can be used in place of +.Fn bus_space_read_4 . +The wrapper API is preferred in new drivers. +.Pp +These two statements both read a 32-bit register at the start of a +resource: +.Bd -literal + bus_space_read_4(rman_get_bustag(res), rman_get_bushandle(res), 0); + bus_read_4(res, 0); +.Ed .Sh RETURN VALUES Zero is returned on success, otherwise an error is returned. .Sh SEE ALSO