From owner-svn-src-all@freebsd.org Mon Sep 14 06:26:37 2020 Return-Path: Delivered-To: svn-src-all@mailman.nyi.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2610:1c1:1:606c::19:1]) by mailman.nyi.freebsd.org (Postfix) with ESMTP id 6EF393F44D3; Mon, 14 Sep 2020 06:26:37 +0000 (UTC) (envelope-from scottl@FreeBSD.org) Received: from mxrelay.nyi.freebsd.org (mxrelay.nyi.freebsd.org [IPv6:2610:1c1:1:606c::19:3]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256 client-signature RSA-PSS (4096 bits) client-digest SHA256) (Client CN "mxrelay.nyi.freebsd.org", Issuer "Let's Encrypt Authority X3" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id 4Bqbws2P85z4Hr4; Mon, 14 Sep 2020 06:26:37 +0000 (UTC) (envelope-from scottl@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 mxrelay.nyi.freebsd.org (Postfix) with ESMTPS id 359DE125E6; Mon, 14 Sep 2020 06:26:37 +0000 (UTC) (envelope-from scottl@FreeBSD.org) Received: from repo.freebsd.org ([127.0.1.37]) by repo.freebsd.org (8.15.2/8.15.2) with ESMTP id 08E6QahU084922; Mon, 14 Sep 2020 06:26:36 GMT (envelope-from scottl@FreeBSD.org) Received: (from scottl@localhost) by repo.freebsd.org (8.15.2/8.15.2/Submit) id 08E6Qam0084921; Mon, 14 Sep 2020 06:26:36 GMT (envelope-from scottl@FreeBSD.org) Message-Id: <202009140626.08E6Qam0084921@repo.freebsd.org> X-Authentication-Warning: repo.freebsd.org: scottl set sender to scottl@FreeBSD.org using -f From: Scott Long Date: Mon, 14 Sep 2020 06:26:36 +0000 (UTC) To: src-committers@freebsd.org, svn-src-all@freebsd.org, svn-src-head@freebsd.org Subject: svn commit: r365707 - head/share/man/man9 X-SVN-Group: head X-SVN-Commit-Author: scottl X-SVN-Commit-Paths: head/share/man/man9 X-SVN-Commit-Revision: 365707 X-SVN-Commit-Repository: base 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.33 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: Mon, 14 Sep 2020 06:26:37 -0000 Author: scottl Date: Mon Sep 14 06:26:36 2020 New Revision: 365707 URL: https://svnweb.freebsd.org/changeset/base/365707 Log: Update bus_dma.9 for the expanded template API. Add some clarifying language about the operation of parent tags in templates. Modified: head/share/man/man9/bus_dma.9 Modified: head/share/man/man9/bus_dma.9 ============================================================================== --- head/share/man/man9/bus_dma.9 Mon Sep 14 05:58:12 2020 (r365706) +++ head/share/man/man9/bus_dma.9 Mon Sep 14 06:26:36 2020 (r365707) @@ -63,6 +63,8 @@ .Nm bus_dma_template_init , .Nm bus_dma_template_tag , .Nm bus_dma_template_clone , +.Nm bus_dma_template_fill, +.Nm BUS_DMA_TEMPLATE_FILL, .Nm bus_dmamap_create , .Nm bus_dmamap_destroy , .Nm bus_dmamap_load , @@ -90,19 +92,29 @@ .Fn bus_dma_tag_destroy "bus_dma_tag_t dmat" .Ft void .Fo bus_dma_template_init -.Fa "bus_dma_template_t template" +.Fa "bus_dma_template_t *template" .Fa "bus_dma_tag_t parent" .Fc .Ft int .Fo bus_dma_template_tag -.Fa "bus_dma_template_t template" +.Fa "bus_dma_template_t *template" .Fa "bus_dma_tag_t *dmat" .Fc .Ft void .Fo bus_dma_template_clone -.Fa "bus_dma_template_t template" +.Fa "bus_dma_template_t *template" .Fa "bus_dma_tag_t dmat" .Fc +.Ft void +.Fo bus_dma_template_fill +.Fa "bus_dma_template_t *template" +.Fa "bus_dma_param_t params[]" +.Fa "u_int count" +.Fc +.Fo BUS_DMA_TEMPLATE_FILL +.Fa "bus_dma_template_t *template" +.Fa "bus_dma_param_t param ..." +.Fc .Ft int .Fn bus_dmamap_create "bus_dma_tag_t dmat" "int flags" "bus_dmamap_t *mapp" .Ft int @@ -697,8 +709,12 @@ Initializes a .Fa bus_dma_template_t structure. If the .Fa parent -argument is non-NULL, values from this tag will be copied into the template, -replacing any defaults. +argument is non-NULL, this parent tag is associated with the template and +will be compiled into the dma tag that is later created. The values +of the parent are not copied into the template. During tag creation in +.Fn bus_dma_tag_template , +any parameters from the parent tag that are more restrictive than what is +in the provided template will overwrite what goes into the new tag. .It Fn bus_dma_template_tag "*template" "*dmat" Unpacks a template into a tag, and returns the tag via the .Fa dmat . @@ -712,6 +728,31 @@ The template does not need to be initialized first. A be overwritten by the values contained in the tag. When paired with .Fn bus_dma_template_tag , this function is useful for creating copies of tags. +.It Fn bus_dma_template_fill "*template" "params[]" "count" +Fills in the selected fields of the template with the keyed values from the +.Fa params +array. This is not meant to be called directly, use +.Fn BUS_DMA_TEMPLATE_FILL +instead. +.It Fn BUS_DMA_TEMPLATE_FILL "*template" "param ..." +Fills in the selected fields of the template with a variable number of +key-value parameters. The macros listed below take an argument of the +specified type and encapsulate it into a key-value structure that is directly +usable as a parameter argument. Muliple parameters may be provided at once. +.Bd -literal + BD_PARENT() void * + BD_ALIGNMENT() uintmax_t + BD_BOUNDARY() uintmax_t + BD_LOWADDR() vm_paddr_t + BD_HIGHADDR() vm_paddr_t + BD_MAXSIZE() uintmax_t + BD_NSEGMENTS() uintmax_t + BD_MAXSEGSIZE() uintmax_t + BD_FLAGS() uintmax_t + BD_LOCKFUNC() void * + BD_LOCKFUNCARG() void * +.Ed +.Pp .It Fn bus_dmamap_create "dmat" "flags" "*mapp" Allocates and initializes a DMA map. Arguments are as follows: