Re: [dpdk-dev] [PATCH v12 1/4] raw/ifpga: add fpga rsu function

On 1/29/2021 7:38 AM, Huang, Wei wrote:

-----Original Message-----
From: Ferruh Yigit <redacted>
Sent: Thursday, January 28, 2021 21:25
To: Huang, Wei <redacted>; dev@dpdk.org; Xu, Rosen <redacted>; Zhang, Qi Z <redacted>
Cc: stable@dpdk.org; Zhang, Tianfei <redacted>; Ray Kinsella <redacted>; Hemant Agrawal <redacted>
Subject: Re: [dpdk-dev] [PATCH v12 1/4] raw/ifpga: add fpga rsu function

On 1/26/2021 6:45 AM, Wei Huang wrote:

quoted

RSU (Remote System Update) depends on secure manager which may be
different on various implementations, so a new secure manager device
is implemented for adapting such difference.
There are three major functions added:
1. ifpga_rawdev_update_flash() updates flash with specific image file.
2. ifpga_rawdev_stop_flash_update() aborts flash update process.
3. ifpga_rawdev_reload() reloads FPGA from updated flash.

Signed-off-by: Wei Huang <redacted>
Acked-by: Tianfei Zhang <redacted>
Acked-by: Rosen Xu <redacted>
---
v2: fix coding style issue in ifpga_fme_rsu.c and ifpga_sec_mgr.c
---
v3: fix compilation issues in ifpga_fme_rsu.c
---
v4: fix compilation issues in opae_intel_max10.c
---

<...>

quoted

@@ -43,7 +43,7 @@ enum ifpga_rawdev_device_state {
   static inline struct opae_adapter *
   ifpga_rawdev_get_priv(const struct rte_rawdev *rawdev)
   {
-return rawdev->dev_private;
+return (struct opae_adapter *)rawdev->dev_private;
   }

   #define IFPGA_RAWDEV_MSIX_IRQ_NUM 7

@@ -76,4 +76,9 @@ int
   ifpga_unregister_msix_irq(enum ifpga_irq_type type,
   int vec_start, rte_intr_callback_fn handler, void *arg);

+int ifpga_rawdev_update_flash(struct rte_rawdev *dev, const char *image,
+uint64_t *status);
+int ifpga_rawdev_stop_flash_update(struct rte_rawdev *dev, int
+force); int ifpga_rawdev_reload(struct rte_rawdev *dev, int type, int
+page);
+
   #endif /* _IFPGA_RAWDEV_H_ */

Hi Wei, Rosen,

This patch introduces three new PMD specific APIs, adding new API has some requirements.

1)
There must be a header file for user application to include, that has the definitions of the APIs.

This header file should be installed in meson via "headers = ..." syntax.

Indeed for rawdev a header always should be installed, because of the rawdev design, the user application should know about the some driver structures, to share those structures PMD should provide a header. This header seems missing.

You can start for providing the missing header, even before this patch.

Header file should be named as 'rte_pmd_.....', and since it is a public header now it should be fully documented via doxygen comments.

This header file should be added to 'doc/api/doxy-api-index.md' for API documentathion.
OK, I will add rte_pmd_ifpga.h.
2)
All APIs should start with 'rte_pmd_' prefix.
OK, I will use 'rte_pmd_' prefix before driver APIs.
3)
All APIs should be in the .map file
OK, I will add them into .map file.

Btw, in the .map, it needs a special block for the experimental APIs, and since 
all your APIs will be experimental at this stage, they will all go in that 
block, it is like:

EXPERIMENTAL {
	global:

	# added in <dpdk release version>
	<list of APIs>
};

4)
Since these are new APIs, they should be marked as experimental. This is done both documenting this in the doxygen comments and marking the function decleration via '__rte_experimental' tag
How to document it in doxygen comments ? Could you give an example ?

Sample:
https://git.dpdk.org/dpdk/tree/lib/librte_ethdev/rte_ethdev.h?h=v20.11#n2105

It is simply adding a note/warning that is saying API is experimental.

5)
Please don't use "struct rte_rawdev *dev" as a argument in the APIs, since that structure is rawdev internal structures, applications (that will call your API) should not know or access to this struct.
Instead you can you 'dev_id' (ethdev 'port_id' equivalent) in the API, as done in the rawdev APIs. Driver can easily get the rawdevice from 'dev_id'.
OK, I will use dev_id in driver APIs' argument.
cc'ed Ray & Hemant in case I missed something related to rawdev and API/ABIs.


And for the ifpga implementation, it is hard for me to review it, I trust Rosen for it.