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

[Ferruh Yigit <ferruh.yigit@intel.com>]

On 1/29/2021 7:38 AM, Huang, Wei wrote:
> 
> 
> -----Original Message-----
> From: Ferruh Yigit <ferruh.yigit@intel.com>
> Sent: Thursday, January 28, 2021 21:25
> To: Huang, Wei <wei.huang@intel.com>; dev@dpdk.org; Xu, Rosen <rosen.xu@intel.com>; Zhang, Qi Z <qi.z.zhang@intel.com>
> Cc: stable@dpdk.org; Zhang, Tianfei <tianfei.zhang@intel.com>; Ray Kinsella <mdr@ashroe.eu>; Hemant Agrawal <hemant.agrawal@nxp.com>
> Subject: Re: [dpdk-dev] [PATCH v12 1/4] raw/ifpga: add fpga rsu function
> 
> On 1/26/2021 6:45 AM, Wei Huang wrote:
>> 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 <wei.huang@intel.com>
>> Acked-by: Tianfei Zhang <tianfei.zhang@intel.com>
>> Acked-by: Rosen Xu <rosen.xu@intel.com>
>> ---
>> 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
>> ---
> 
> <...>
> 
>> @@ -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.
>