March 2023 - Openamp-system-reference - lists.openampproject.org

2023-03-22 OpenAMP System Reference notes and action items

by Chan King Choy, Nathalie

Hi all, The notes from today's call can be found at: https://github.com/OpenAMP/openamp-system-reference/wiki/OpenAMP-System-Ref… When I tried to add the notes to the usual page, it wouldn't render, so I think that page got too long. So, I split out a 2023 page & can clean up the rest later to split into their own year pages. Action items: * Bill will publish the notes & share the recording from the Virtio spin-off call * Bill to discuss w/ Mathieu about joining the AMP BOF * Bill & Arnaud to reply on doc data structures thread from Tammy * Arnaud will look at Zephyr for what could be leveraged for automatic checking of pull requests for Doxygen-compatible comments * [DONE] Nathalie: Make a copy of Dec deck & share to rest of group as editors * Here is the BOF deck working document: https://docs.google.com/presentation/d/1dKGGgLGFWYTeS_pJ4HBqPB1fwq2070-KzoS… * Nathalie: Find out call-in capability for Session Room 1 * Tammy will submit a pull request for the input parameters mods (Separate commits for libs & apps & tests. OK to submit in same pull request) @hnagalla@ti.com<mailto:hnagalla@ti.com> and @Nishanth Menon<mailto:nm@ti.com>: Please email me directly with the google account that you use for work & I can add you to the Google Drive folder where we store the System Reference work-in-progress documents. Thanks & regards, Nathalie

2 months

2
2
0 0

Proposal for Updating Doxygen Comments within OpenAMP for Consistent Documentation of Data Structures

by Leino, Tammy

Hello All, As per the discussion last week in the OpenAMP System Reference call, here is my proposal for updating the Doxygen comments for data structures. I would like to target these changes for the April 2023 release. Existing problems with data structure documentation formatting: ------------------------------------------------------------------------------------ 1 - Data structure member descriptions are not being generated in documentation 2 - In place where description should be, there is only a line number and file reference Proposed changes for structure updates: ----------------------------------------------------- 1- Update OpenAMP code to add Doxygen comments for member descriptions to display properly. Current definition of rpmsg_endpoint: ++++++++++++++++++++++++++++ /** * struct rpmsg_endpoint - binds a local rpmsg address to its user * @name: name of the service supported * @rdev: pointer to the rpmsg device * @addr: local address of the endpoint * @dest_addr: address of the default remote endpoint binded. * @cb: user rx callback, return value of this callback is reserved * for future use, for now, only allow RPMSG_SUCCESS as return value. * @ns_unbind_cb: end point service unbind callback, called when remote * ept is destroyed. * @node: end point node. * @priv: private data for the driver's use * * In essence, an rpmsg endpoint represents a listener on the rpmsg bus, as * it binds an rpmsg address with an rx callback handler. */ struct rpmsg_endpoint { char name[RPMSG_NAME_SIZE]; struct rpmsg_device *rdev; uint32_t addr; uint32_t dest_addr; rpmsg_ept_cb cb; rpmsg_ns_unbind_cb ns_unbind_cb; struct metal_list node; void *priv; }; Proposed updates to rpmsg_endpoint: +++++++++++++++++++++++++++++ Comment descriptions should be column-aligned. Copy/paste caused problems. /** * struct rpmsg_endpoint - binds a local rpmsg address to its user * * In essence, an rpmsg endpoint represents a listener on the rpmsg bus, as * it binds an rpmsg address with an rx callback handler. */ struct rpmsg_endpoint { char name[RPMSG_NAME_SIZE]; /** Name of the service supported */ struct rpmsg_device *rdev; /** Pointer to the rpmsg device */ uint32_t addr; /** Local address of the endpoint */ uint32_t dest_addr; /** Address of the default remote endpoint binded */ rpmsg_ept_cb cb; /** User rx callback, return value of this callback is reserved for future use, for now, only allow RPMSG_SUCCESS as return value */ rpmsg_ns_unbind_cb ns_unbind_cb; /** Endpoint service unbind callback, called when remote ept is destroyed */ struct metal_list node; /** Endpoint node */ void *priv; /** Private data for the driver's use */ }; 2 - Update Doxyfile to remove line number / file from description ------------------------------------------------------------------------------------- Updates to Doxyfile to remove line number reference from data structure parameters: +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ # If the SOURCE_BROWSER tag is set to YES then a list of source files will be # generated. Documented entities will be cross-referenced with these sources. # # Note: To get rid of all source code in the generated output, make sure that # also VERBATIM_HEADERS is set to NO. # The default value is: NO. SOURCE_BROWSER = NO

2 months, 1 week

2
1
0 0

Calling for agenda: 2023-03-22 OpenAMP System Reference call

by Chan King Choy, Nathalie

Hi all, Please let us know if you have any agenda topics. Here is what I have so far: * Bill, Arnaud, Dan: Quick summary of last week's Virtio spin-off call * All: Starting on slide deck for OpenAMP BOF presentation (making something short is always harder than making it long...) * Tammy & Arnaud: Update on docs for 2023.04 release * Nathalie: Should we update OpenAMP governance page to reflect what we've established by the work the System Reference group has done (e.g. docs, CI) * https://www.openampproject.org/governance/ * Nathalie: Are there any tasks we want to track as a group (e.g. where there are interdependencies between devs) for Q2 work? Any work from our webinar tracking sheet<https://docs.google.com/spreadsheets/d/1SkQvq34NJBjJM56T6nm9fknJGTHutfV-LJd…> that we should continue tracking? * Individual updates Thanks & regards, Nathalie

2 months, 1 week

1
0
0 0

Proposal for Updating Doxygen Comments within OpenAMP for Consistent Documentation of Input Parameters

by Leino, Tammy

Hello All, As per the discussion last week in the OpenAMP System Reference call, here is my proposal for updating the Doxygen comments for consistent documentation of input parameters. I would like to target these changes for the April 2023 release. I will be sending out another email with proposed changes for documenting data structures also targeting the April 2023 release. There are other changes I will be proposing for future releases, but these two proposals are what seem doable for April. Overview: ------------- 1 - Isolate all Doxygen comments to header files. Doxygen comments are currently sporadically located between source and header files. Some routines have Doxygen comments in both places. Zephyr has Doxygen comments for all functions/data structures in header files (except for static/externed functions), so the proposal is to follow their example. 2 - Update Doxygen comment formatting to be consistent. 3 - Ensure all i/o parameters for APIs are documented. Examples: -------------- Following shows just one example of each suggestion. #1 - Isolate all Doxygen comments to header files. ++++++++++++++++++++++++++++++++++++++ rpmsg_send_offchannel_raw() The Doxygen comments are found in both the header file and the source file. The formatting in the source file is proper, and is given priority when the code is built, so it is used and displayed properly in the html. Recommend to move the formatting to the header file. #2 - Update formatting to be consistent. ++++++++++++++++++++++++++++++ rpmsg_get_tx_payload_buffer() The Doxygen formatting is not proper for the input parameters and therefore does not display correctly. html output for input parameters is as follows: @ept: Pointer to rpmsg endpoint @len: Pointer to store tx buffer size @wait: Boolean, wait or not for buffer to become available This should instead be formatted as: Parameters ept Pointer to rpmsg endpoint len Pointer to store tx buffer size wait Boolean, wait or not for buffer to become available The changes to support this requirement are as follows: Current formatting: /** * @brief Gets the tx buffer for message payload. * * This API can only be called at process context to get the tx buffer in vring. * By this way, the application can directly put its message into the vring tx * buffer without copy from an application buffer. * It is the application responsibility to correctly fill the allocated tx * buffer by data and passing correct parameters to the rpmsg_send_nocopy() or * rpmsg_sendto_nocopy() function to perform data no-copy-send mechanism. * * @ept: Pointer to rpmsg endpoint * @len: Pointer to store tx buffer size * @wait: Boolean, wait or not for buffer to become available * * @return The tx buffer address on success and NULL on failure * * @see rpmsg_send_offchannel_nocopy * @see rpmsg_sendto_nocopy * @see rpmsg_send_nocopy */ void *rpmsg_get_tx_payload_buffer(struct rpmsg_endpoint *ept, uint32_t *len, int wait); Proposed updated formatting highlighted by ==>: /** * @brief Gets the tx buffer for message payload. * * This API can only be called at process context to get the tx buffer in vring. * By this way, the application can directly put its message into the vring tx * buffer without copy from an application buffer. * It is the application responsibility to correctly fill the allocated tx * buffer by data and passing correct parameters to the rpmsg_send_nocopy() or * rpmsg_sendto_nocopy() function to perform data no-copy-send mechanism. * ==> * @param ept Pointer to rpmsg endpoint ==> * @param len Pointer to store tx buffer size ==> * @param wait Boolean, wait or not for buffer to become available * * @return The tx buffer address on success and NULL on failure * * @see rpmsg_send_offchannel_nocopy * @see rpmsg_sendto_nocopy * @see rpmsg_send_nocopy */ void *rpmsg_get_tx_payload_buffer(struct rpmsg_endpoint *ept, uint32_t *len, int wait); #3 - Ensure all parameters are documented. ++++++++++++++++++++++++++++++++++ rpmsg_send_offchannel_raw() The Doxygen comments in the source file are complete, but the header file is missing some parameters. All routines should be checked for completeness. Comments respectfully appreciated. Thanks, Tammy

2 months, 2 weeks

2
1
0 0

2023-03-08 OpenAMP System Reference notes and action items

by Chan King Choy, Nathalie

Hi all, Notes are posted at https://github.com/OpenAMP/openamp-system-reference/wiki/OpenAMP-System-Ref… Let us know if you spot any errors or important omissions. Action items: * Hari to check with Nishanth if TI is approved for Linaro Connect * Nathalie: Start thread on email regarding OpenAMP F2F at Linaro Connect * Nathalie: Reach out to NXP OpenAMP folks to see if they are attending Linaro Connect Thanks & regards, Nathalie

2 months, 3 weeks

1
0
0 0

Calling for Agenda: 2023-03-08 OpenAMP System Reference

by Chan King Choy, Nathalie

Hi all, Please let us know your topics for this week's System Reference call. Here is what I have so far: * Linaro Connect: * Who submitted for the CFP & what topics? * Bill: OpenAMP BOF (Birds Of a Feather) * Arnaud: management of the coprocessor firmware in OP-TEE * Any updates on who is able to attend Connect? * Individual updates on OpenAMP System Reference-related work Thanks & regards, Nathalie

2 months, 3 weeks

1
0
0 0

2022-02-22 OpenAMP System Reference notes and action items

by Chan King Choy, Nathalie

Hi all, Sorry for the delay. Been tied up with a release in another project. Notes from last call are posted at: https://github.com/OpenAMP/openamp-system-reference/wiki/OpenAMP-System-Ref… Action items: * Bill to put on agenda for RP call in 2 weeks to discuss fixing up of API reference guide (requires touching a lot of files) * Nathalie to reach out to NXP to figure out which calls they want to participate in * Nathalie: Put in calendar reminders for Google Summer of Code consideration Best regards, Nathalie

2 months, 3 weeks

1
0
0 0

2023

2022

2021

Openamp-system-reference March 2023