Document newly introduced fpga_manager_ops callback parse_header() along
with header_size and data_size fields of struct fpga_image_info.
Signed-off-by: Ivan Bornyakov <[email protected]>
---
Documentation/driver-api/fpga/fpga-mgr.rst | 31 ++++++++++++++++------
1 file changed, 23 insertions(+), 8 deletions(-)
diff --git a/Documentation/driver-api/fpga/fpga-mgr.rst b/Documentation/driver-api/fpga/fpga-mgr.rst
index 42c01f396dce..db0852bd3ddc 100644
--- a/Documentation/driver-api/fpga/fpga-mgr.rst
+++ b/Documentation/driver-api/fpga/fpga-mgr.rst
@@ -79,14 +79,29 @@ 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;
-if the whole bitstream is not immediately available then the core code will
-buffer up at least this much before starting.
+ 1. .parse_header
+ 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. If header_size is set, .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 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 it's defined, otherwise .initial_header_size; if the whole bitstream is not
+immediately available then the core code will buffer up at least this much
+before starting.
The .write function writes a buffer to the FPGA. The buffer may be contain the
whole FPGA image or may be a smaller chunk of an FPGA image. In the latter
--
2.35.1
On Thu, Jun 09, 2022 at 06:47:50PM +0300, Ivan Bornyakov wrote:
> Document newly introduced fpga_manager_ops callback parse_header() along
> with header_size and data_size fields of struct fpga_image_info.
>
> Signed-off-by: Ivan Bornyakov <[email protected]>
> ---
> Documentation/driver-api/fpga/fpga-mgr.rst | 31 ++++++++++++++++------
> 1 file changed, 23 insertions(+), 8 deletions(-)
>
> diff --git a/Documentation/driver-api/fpga/fpga-mgr.rst b/Documentation/driver-api/fpga/fpga-mgr.rst
> index 42c01f396dce..db0852bd3ddc 100644
> --- a/Documentation/driver-api/fpga/fpga-mgr.rst
> +++ b/Documentation/driver-api/fpga/fpga-mgr.rst
> @@ -79,14 +79,29 @@ 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;
> -if the whole bitstream is not immediately available then the core code will
> -buffer up at least this much before starting.
> + 1. .parse_header
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. If header_size is set, .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 a
If FPGA image is already mapped as a
Others look good to me.
Thanks,
Yilun
> +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 it's defined, otherwise .initial_header_size; if the whole bitstream is not
> +immediately available then the core code will buffer up at least this much
> +before starting.
>
> The .write function writes a buffer to the FPGA. The buffer may be contain the
> whole FPGA image or may be a smaller chunk of an FPGA image. In the latter
> --
> 2.35.1
>