Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) client-ip=2620:137:e000::1:20;
Date:   Tue, 21 Jun 2022 18:36:57 +0800
From:   Xu Yilun <yilun.xu@intel.com>
To:     Ivan Bornyakov <i.bornyakov@metrotek.ru>
Cc:     mdf@kernel.org, hao.wu@intel.com, trix@redhat.com, corbet@lwn.net,
        Conor.Dooley@microchip.com, robh+dt@kernel.org,
        krzysztof.kozlowski+dt@linaro.org, linux-fpga@vger.kernel.org,
        devicetree@vger.kernel.org, linux-doc@vger.kernel.org,
        linux-kernel@vger.kernel.org, system@metrotek.ru
Subject: Re: [PATCH v20 2/4] docs: fpga: mgr: document parse_header() callback
Message-ID: <20220621103657.GB1530041@yilunxu-OptiPlex-7050>
References: <20220617134846.19859-1-i.bornyakov@metrotek.ru>
 <20220617134846.19859-3-i.bornyakov@metrotek.ru>
MIME-Version: 1.0
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
In-Reply-To: <20220617134846.19859-3-i.bornyakov@metrotek.ru>
Precedence: bulk

On Fri, Jun 17, 2022 at 04:48:44PM +0300, Ivan Bornyakov wrote:
> Document newly introduced fpga_manager_ops callback parse_header() and
> flag skip_header along with header_size and data_size fields of struct
> fpga_image_info.
> 
> Signed-off-by: Ivan Bornyakov <i.bornyakov@metrotek.ru>

Acked-by: Xu Yilun <yilun.xu@intel.com>

> ---
>  Documentation/driver-api/fpga/fpga-mgr.rst | 27 +++++++++++++++++-----
>  1 file changed, 21 insertions(+), 6 deletions(-)
> 
> diff --git a/Documentation/driver-api/fpga/fpga-mgr.rst b/Documentation/driver-api/fpga/fpga-mgr.rst
> index 42c01f396dce..49c0a9512653 100644
> --- a/Documentation/driver-api/fpga/fpga-mgr.rst
> +++ b/Documentation/driver-api/fpga/fpga-mgr.rst
> @@ -79,12 +79,27 @@ do the programming sequence for this particular FPGA.  These ops return 0 for
>  success or negative error codes otherwise.
>  
>  The programming sequence is::
> - 1. .write_init
> - 2. .write or .write_sg (may be called once or multiple times)
> - 3. .write_complete
> -
> -The .write_init function will prepare the FPGA to receive the image data.  The
> -buffer passed into .write_init will be at most .initial_header_size bytes long;
> + 1. .parse_header (optional, may be called once or multiple times)
> + 2. .write_init
> + 3. .write or .write_sg (may be called once or multiple times)
> + 4. .write_complete
> +
> +The .parse_header function will set header_size and data_size to
> +struct fpga_image_info. Before parse_header call, header_size is initialized
> +with initial_header_size. If flag skip_header of fpga_manager_ops is true,
> +.write function will get image buffer starting at header_size offset from the
> +beginning. If data_size is set, .write function will get data_size bytes of
> +the image buffer, otherwise .write will get data up to the end of image buffer.
> +This will not affect .write_sg, .write_sg will still get whole image in
> +sg_table form. If FPGA image is already mapped as a single contiguous buffer,
> +whole buffer will be passed into .parse_header. If image is in scatter-gather
> +form, core code will buffer up at least .initial_header_size before the first
> +call of .parse_header, if it is not enough, .parse_header should set desired
> +size into info->header_size and return -EAGAIN, then it will be called again
> +with greater part of image buffer on the input.
> +
> +The .write_init function will prepare the FPGA to receive the image data. The
> +buffer passed into .write_init will be at least info->header_size bytes long;
>  if the whole bitstream is not immediately available then the core code will
>  buffer up at least this much before starting.
>  
> -- 
> 2.25.1
>