Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Document domctl.h #98

Merged
merged 3 commits into from
May 2, 2024
Merged

Document domctl.h #98

merged 3 commits into from
May 2, 2024

Conversation

Deedone
Copy link

@Deedone Deedone commented Apr 29, 2024

Document all of the public functions in the domctl API with oxygen
Document all of the public functions in the sysctl API with doxygen
Fixes #97

@Deedone Deedone force-pushed the docs branch 2 times, most recently from d629e29 to 6b5fa4f Compare April 29, 2024 11:06
@@ -12,27 +12,190 @@

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You probably wanna add

  • file header, like
/**
 * @file
 *
 * @brief Public APIs for the I2C drivers.
 */
  • interface header, like
/**
 * @brief I2C Interface
 * @defgroup i2c_interface I2C Interface
 * @ingroup io_interfaces
 * @{
 */
  • interface footer
/**
 * @}
 */

* @brief Perform a scheduler operation on a specified domain.
*
* @param domid The ID of the domain on which the scheduler operation is to be performed.
* @param[in,out] sched_op A pointer to a `struct xen_domctl_scheduler_op` object that defines

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Have you tried '@ref xen_domctl_scheduler_op' here?

Actually refs might be used in all APIs docs to reference Xen structures.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Xen public headers do not use doxygen so there is nothing to ref to.

int xen_domctl_scheduler_op(int domid, struct xen_domctl_scheduler_op *sched_op);
/**

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Add blank lines before each API

* @param domid The domain ID of the domain to set the maximum memory for.
* @param max_memkb The maximum memory (in kilobytes) to set for the domain.
* @return 0 on success, or a negative error code on failure.
*/
int xen_domctl_max_mem(int domid, uint64_t max_memkb);

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

TODO: this api doesn't follow set/get naming convention

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Function names are chosen based on defines from Xen headers.

@Deedone Deedone force-pushed the docs branch 2 times, most recently from 7946325 to 6fdc816 Compare April 29, 2024 13:19
*
* @brief Xen Domain Control Interface
*/

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

if you check other generic headers - "file header" is added as first block in the file or right after copyright block, can we follow the same, pls.

@GrygiriiS
Copy link

It seems to finish this task properly - the xen_xx.rst file need to be added in doc folder.

It has to be similar to doc/hardware/peripherals/spi.rst (this one very simple) or doc/hardware/peripherals/i2c.rst (or any other interface doc).

Question where to add these Xen doc files, with assumption that more docs will be added (event, ranges, gnt) - is "doc/hardware/peripherals" proper path? or need Xen specific folder somewhere?

@Deedone
Copy link
Author

Deedone commented Apr 30, 2024

Let's try to keep PRs small and finally merge something because we keep getting interrelated changes piling up, and this is getting out of hand.

Copy link
Collaborator

@firscity firscity left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Acked-by: Dmytro Firsov <[email protected]>

Deedone added 3 commits April 30, 2024 13:18
The size is passed in bytes, not in megabytes. So rename the parameter
to avoid confusion.

Signed-off-by: Mykyta Poturai <[email protected]>
Acked-by: Dmytro Firsov <[email protected]>
Document all of the public functions in the domctl API with doxygen

Signed-off-by: Mykyta Poturai <[email protected]>
Acked-by: Dmytro Firsov <[email protected]>
Document all of the public functions in the sysctl API with doxygen

Signed-off-by: Mykyta Poturai <[email protected]>
Acked-by: Dmytro Firsov <[email protected]>
@GrygiriiS
Copy link

GrygiriiS commented May 1, 2024

LGTM. Thank you very much.

@firscity firscity merged commit bbdc9a3 into xen-troops:zephyr-v3.6.0-xt May 2, 2024
9 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants