github/acrn-hypervisor
1
0
Fork 0
mirror of https://github.com/projectacrn/acrn-hypervisor.git synced 2025-08-01 07:49:39 +00:00
Code Issues Projects Releases Wiki Activity

doc: replace return with retval

Browse Source 
`@return` is dedicated for brief description of return values, not for comments
stating actual return values. In addition, sphinx + breathe does not join
multiple adjacent `@return`. This results in multiple `Return` sections in the
generated document, which is confusing.

This patch replaces `@return` with `@retval` for the lists of return
values. Adjacent `@retval` can be joined into one list by breathe.

v1 -> v2:

* Replace return value descriptions like `negative` and `positive` with
  expressions like `<0` and `>0` in `@retval`.
* Keep the list of `@retval` comprehensive, even when there is a `@return` to
  generally describe what the return value means.
* Drop duplicated `@return` when it does not give more information than the
  `@retval` list.

Tracked-On: #1595
Signed-off-by: Junjie Mao <junjie.mao@intel.com>
This commit is contained in:
Junjie Mao 2018-11-21 17:28:28 +08:00 committed by Eddie Dong
parent 97eb72a4a0
commit 584f6b7255
14 changed files with 82 additions and 78 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

16
devicemodel/include/dm_string.h
View File

@ -16,8 +16,8 @@
* @param base Base: 8, 10, 16...
* @param val Long integer convert from string.
*
* @return -1 error.
* @return 0 no error.
* @retval -1 error.
* @retval 0 no error.
*/
int dm_strtol(const char *s, char **end, unsigned int base, long *val);
@ -30,8 +30,8 @@ int dm_strtol(const char *s, char **end, unsigned int base, long *val);
* @param base Base: 8, 10, 16...
* @param val Integer convert from string.
*
* @return -1 error.
* @return 0 no error.
* @retval -1 error.
* @retval 0 no error.
*/
int dm_strtoi(const char *s, char **end, unsigned int base, int *val);
@ -44,8 +44,8 @@ int dm_strtoi(const char *s, char **end, unsigned int base, int *val);
* @param base Base: 8, 10, 16...
* @param val Unsigned long integer convert from string.
*
* @return -1 error.
* @return 0 no error.
* @retval -1 error.
* @retval 0 no error.
*/
int dm_strtoul(const char *s, char **end, unsigned int base, unsigned long *val);
@ -58,8 +58,8 @@ int dm_strtoul(const char *s, char **end, unsigned int base, unsigned long *val)
* @param base Base: 8, 10, 16...
* @param val Unsigned integer convert from string.
*
* @return -1 error.
* @return 0 no error.
* @retval -1 error.
* @retval 0 no error.
*/
int dm_strtoui(const char *s, char **end, unsigned int base, unsigned int *val);

2
hypervisor/arch/x86/guest/guest.c
View File

@ -601,7 +601,7 @@ static void rebuild_vm0_e820(void)
/**
* @param[inout] vm pointer to a vm descriptor
*
* @return 0 - on success
* @retval 0 on success
*
* @pre vm != NULL
* @pre is_vm0(vm) == true

12
hypervisor/arch/x86/guest/vlapic.c
View File

@ -1312,8 +1312,8 @@ vlapic_icrlo_write_handler(struct acrn_vlapic *vlapic)
* @param[inout] vecptr Pointer to vector buffer and will be filled
* with eligible vector if any.
*
* @return 0 - There is no eligible pending vector.
* @return 1 - There is pending vector.
* @retval 0 There is no eligible pending vector.
* @retval 1 There is pending vector.
*
* @remark The vector does not automatically transition to the ISR as a
* result of calling this function.
@ -1951,8 +1951,8 @@ vlapic_set_intr(struct acrn_vcpu *vcpu, uint32_t vector, bool level)
* interrupt to all vCPUs.
* @param[in] vector Vector to be fired.
*
* @return 0 on success.
* @return -EINVAL on error that vcpu_id_arg or vector is invalid.
* @retval 0 on success.
* @retval -EINVAL on error that vcpu_id_arg or vector is invalid.
*
* @pre vm != NULL
*/
@ -1994,8 +1994,8 @@ vlapic_set_local_intr(struct acrn_vm *vm, uint16_t vcpu_id_arg, uint32_t vector)
* @param[in] addr MSI address.
* @param[in] msg MSI data.
*
* @return 0 on success.
* @return non-zero on error that addr is invalid.
* @retval 0 on success.
* @retval -1 on error that addr is invalid.
*
* @pre vm != NULL
*/

26
hypervisor/arch/x86/io.c
View File

@ -184,9 +184,9 @@ void emulate_io_post(struct acrn_vcpu *vcpu)
*
* @pre io_req->type == REQ_PORTIO
*
* @return 0 - Successfully emulated by registered handlers.
* @return -ENODEV - No proper handler found.
* @return -EIO - The request spans multiple devices and cannot be emulated.
* @retval 0 Successfully emulated by registered handlers.
* @retval -ENODEV No proper handler found.
* @retval -EIO The request spans multiple devices and cannot be emulated.
*/
int32_t
hv_emulate_pio(const struct acrn_vcpu *vcpu, struct io_request *io_req)
@ -234,9 +234,9 @@ hv_emulate_pio(const struct acrn_vcpu *vcpu, struct io_request *io_req)
*
* @pre io_req->type == REQ_MMIO
*
* @return 0 - Successfully emulated by registered handlers.
* @return -ENODEV - No proper handler found.
* @return -EIO - The request spans multiple devices and cannot be emulated.
* @retval 0 Successfully emulated by registered handlers.
* @retval -ENODEV No proper handler found.
* @retval -EIO The request spans multiple devices and cannot be emulated.
*/
static int32_t
hv_emulate_mmio(struct acrn_vcpu *vcpu, struct io_request *io_req)
@ -283,11 +283,11 @@ hv_emulate_mmio(struct acrn_vcpu *vcpu, struct io_request *io_req)
* @param vcpu The virtual CPU that triggers the MMIO access
* @param io_req The I/O request holding the details of the MMIO access
*
* @return 0 - Successfully emulated by registered handlers.
* @return IOREQ_PENDING - The I/O request is delivered to VHM.
* @return -EIO - The request spans multiple devices and cannot be emulated.
* @return -EINVAL - \p io_req has an invalid type.
* @return Negative on other errors during emulation.
* @retval 0 Successfully emulated by registered handlers.
* @retval IOREQ_PENDING The I/O request is delivered to VHM.
* @retval -EIO The request spans multiple devices and cannot be emulated.
* @retval -EINVAL \p io_req has an invalid type.
* @retval <0 on other errors during emulation.
*/
int32_t
emulate_io(struct acrn_vcpu *vcpu, struct io_request *io_req)
@ -472,8 +472,8 @@ void register_io_emulation_handler(struct acrn_vm *vm, uint32_t pio_idx,
* @param end The end of the range (exclusive) \p read_write can emulate
* @param handler_private_data Handler-specific data which will be passed to \p read_write when called
*
* @return 0 - Registration succeeds
* @return -EINVAL - \p read_write is NULL, \p end is not larger than \p start or \p vm has been launched
* @retval 0 Registration succeeds
* @retval -EINVAL \p read_write is NULL, \p end is not larger than \p start or \p vm has been launched
*/
int register_mmio_emulation_handler(struct acrn_vm *vm,
hv_mem_io_handler_t read_write, uint64_t start,

4
hypervisor/boot/sbl/multiboot.c
View File

@ -158,8 +158,8 @@ static void *get_kernel_load_addr(void *kernel_src_addr)
/**
* @param[inout] vm pointer to a vm descriptor
*
* @return 0 - on success
* @return -EINVAL - on invalid parameters
* @retval 0 on success
* @retval -EINVAL on invalid parameters
*
* @pre vm != NULL
* @pre is_vm0(vm) == true

6
hypervisor/include/arch/x86/guest/vcpu.h
View File

@ -520,7 +520,7 @@ struct acrn_vcpu* get_ever_run_vcpu(uint16_t pcpu_id);
* @param[in] vm pointer to vm data structure, this vcpu will owned by this vm.
* @param[out] rtn_vcpu_handle pointer to the created vcpu
*
* @return 0: vcpu created successfully, other values failed.
* @retval 0 vcpu created successfully, other values failed.
*/
int create_vcpu(uint16_t pcpu_id, struct acrn_vm *vm, struct acrn_vcpu **rtn_vcpu_handle);
@ -533,7 +533,7 @@ int create_vcpu(uint16_t pcpu_id, struct acrn_vm *vm, struct acrn_vcpu **rtn_vcp
* @param[inout] vcpu pointer to vcpu data structure
* @pre vcpu != NULL
*
* @return 0: vcpu run successfully, other values failed.
* @retval 0 vcpu run successfully, other values failed.
*/
int run_vcpu(struct acrn_vcpu *vcpu);
@ -592,7 +592,7 @@ void schedule_vcpu(struct acrn_vcpu *vcpu);
* Create a vcpu for the vm, and mapped to the pcpu.
*
* @param[inout] vm pointer to vm data structure
* @param[in] pcpu_id which the vcpu will be mapped
* @param[in] pcpu_id which the vcpu will be mapped
*/
int prepare_vcpu(struct acrn_vm *vm, uint16_t pcpu_id);

12
hypervisor/include/arch/x86/guest/vlapic.h
View File

@ -126,8 +126,8 @@ uint64_t vlapic_get_cr8(const struct acrn_vlapic *vlapic);
* @param[inout] vecptr Pointer to vector buffer and will be filled
* with eligible vector if any.
*
* @return 0 - There is no eligible pending vector.
* @return 1 - There is pending vector.
* @retval 0 There is no eligible pending vector.
* @retval 1 There is pending vector.
*
* @remark The vector does not automatically transition to the ISR as a
* result of calling this function.
@ -226,8 +226,8 @@ vlapic_intr_edge(struct acrn_vcpu *vcpu, uint32_t vector)
* interrupt to all vCPUs.
* @param[in] vector Vector to be fired.
*
* @return 0 on success.
* @return -EINVAL on error that vcpu_id_arg or vector is invalid.
* @retval 0 on success.
* @retval -EINVAL on error that vcpu_id_arg or vector is invalid.
*
* @pre vm != NULL
*/
@ -240,8 +240,8 @@ int32_t vlapic_set_local_intr(struct acrn_vm *vm, uint16_t vcpu_id_arg, uint32_t
* @param[in] addr MSI address.
* @param[in] msg MSI data.
*
* @return 0 on success.
* @return non-zero on error that addr is invalid.
* @retval 0 on success.
* @retval -1 on error that addr is invalid.
*
* @pre vm != NULL
*/

14
hypervisor/include/arch/x86/ioreq.h
View File

@ -220,8 +220,8 @@ void register_io_emulation_handler(struct acrn_vm *vm, uint32_t pio_idx,
* @param end The end of the range (exclusive) \p read_write can emulate
* @param handler_private_data Handler-specific data which will be passed to \p read_write when called
*
* @return 0 - Registration succeeds
* @return -EINVAL - \p read_write is NULL, \p end is not larger than \p start or \p vm has been launched
* @retval 0 Registration succeeds
* @retval -EINVAL \p read_write is NULL, \p end is not larger than \p start or \p vm has been launched
*/
int register_mmio_emulation_handler(struct acrn_vm *vm,
hv_mem_io_handler_t read_write, uint64_t start,
@ -262,11 +262,11 @@ void dm_emulate_mmio_post(struct acrn_vcpu *vcpu);
* @param vcpu The virtual CPU that triggers the MMIO access
* @param io_req The I/O request holding the details of the MMIO access
*
* @return 0 - Successfully emulated by registered handlers.
* @return IOREQ_PENDING - The I/O request is delivered to VHM.
* @return -EIO - The request spans multiple devices and cannot be emulated.
* @return -EINVAL - \p io_req has an invalid type.
* @return Negative on other errors during emulation.
* @retval 0 Successfully emulated by registered handlers.
* @retval IOREQ_PENDING The I/O request is delivered to VHM.
* @retval -EIO The request spans multiple devices and cannot be emulated.
* @retval -EINVAL \p io_req has an invalid type.
* @retval <0 on other errors during emulation.
*/
int32_t emulate_io(struct acrn_vcpu *vcpu, struct io_request *io_req);

4
hypervisor/include/arch/x86/irq.h
View File

@ -138,8 +138,8 @@ uint32_t irq_to_vector(uint32_t irq);
* @param[in] vector Vector of the exeception.
* @param[in] err_code Error Code to be injected.
*
* @return 0 on success
* @return -EINVAL on error that vector is invalid.
* @retval 0 on success
* @retval -EINVAL on error that vector is invalid.
*
* @pre vcpu != NULL
*/

28
hypervisor/include/arch/x86/mmu.h
View File

@ -117,15 +117,15 @@ void mmu_modify_or_del(uint64_t *pml4_page, uint64_t vaddr_base, uint64_t size,
/**
* @brief EPT and VPID capability checking
*
* @return 0 - on success
* @return -ENODEV - Don't support EPT or VPID capability
* @retval 0 on success
* @retval -ENODEV Don't support EPT or VPID capability
*/
int check_vmx_mmu_cap(void);
/**
* @brief VPID allocation
*
* @return 0 - VPID overflow
* @return more than 0 - the valid VPID
* @retval 0 VPID overflow
* @retval >0 the valid VPID
*/
uint16_t allocate_vpid(void);
/**
@ -157,8 +157,8 @@ void invept(const struct acrn_vcpu *vcpu);
* @param[in] gpa_arg the start GPA address of the guest memory region
* @param[in] size_arg the size of the guest memory region
*
* @return true - The HPA of the guest memory region is continuous
* @return false - The HPA of the guest memory region is non-continuous
* @retval true The HPA of the guest memory region is continuous
* @retval false The HPA of the guest memory region is non-continuous
*/
bool check_continuous_hpa(struct acrn_vm *vm, uint64_t gpa_arg, uint64_t size_arg);
/**
@ -221,8 +221,8 @@ void destroy_ept(struct acrn_vm *vm);
* @param[in] vm the pointer that points to VM data structure
* @param[in] gpa the specified guest-physical address
*
* @return INVALID_HPA - the HPA of parameter gpa is unmapping
* @return hpa - the HPA of parameter gpa is hpa
* @retval hpa the host physical address mapping to the \p gpa
* @retval INVALID_HPA the HPA of parameter gpa is unmapping
*/
uint64_t gpa2hpa(struct acrn_vm *vm, uint64_t gpa);
/**
@ -233,8 +233,8 @@ uint64_t gpa2hpa(struct acrn_vm *vm, uint64_t gpa);
* @param[out] size the pointer that returns the page size of
* the page in which the gpa is
*
* @return INVALID_HPA - the HPA of parameter gpa is unmapping
* @return hpa - the HPA of parameter gpa is hpa
* @retval hpa the host physical address mapping to the \p gpa
* @retval INVALID_HPA the HPA of parameter gpa is unmapping
*/
uint64_t local_gpa2hpa(struct acrn_vm *vm, uint64_t gpa, uint32_t *size);
/**
@ -299,8 +299,8 @@ void ept_mr_del(struct acrn_vm *vm, uint64_t *pml4_page, uint64_t gpa,
*
* @param[in] vcpu the pointer that points to vcpu data structure
*
* @return -EINVAL - fail to handle the EPT violation
* @return 0 - Success to handle the EPT violation
* @retval -EINVAL fail to handle the EPT violation
* @retval 0 Success to handle the EPT violation
*/
int ept_violation_vmexit_handler(struct acrn_vcpu *vcpu);
/**
@ -308,8 +308,8 @@ int ept_violation_vmexit_handler(struct acrn_vcpu *vcpu);
*
* @param[in] vcpu the pointer that points to vcpu data structure
*
* @return -EINVAL - fail to handle the EPT misconfig
* @return 0 - Success to handle the EPT misconfig
* @retval -EINVAL fail to handle the EPT misconfig
* @retval 0 Success to handle the EPT misconfig
*/
int ept_misconfig_vmexit_handler(__unused struct acrn_vcpu *vcpu);

2
hypervisor/include/arch/x86/mtrr.h
View File

@ -69,7 +69,7 @@ void mtrr_wrmsr(struct acrn_vcpu *vcpu, uint32_t msr, uint64_t value);
* @param[in] vcpu The pointer that points VCPU data structure
* @param[in] msr Virtual MTRR MSR Address
*
* @return unsigned long integer - The specified virtual MTRR MSR value
* @return The specified virtual MTRR MSR value
*/
uint64_t mtrr_rdmsr(const struct acrn_vcpu *vcpu, uint32_t msr);
/**

4
hypervisor/include/arch/x86/pgtable.h
View File

@ -82,7 +82,7 @@
*
* @param[in] x The specified host-physical address
*
* @return void pointer - The host-virtual address
* @return The translated host-virtual address
*/
static inline void *hpa2hva(uint64_t x)
{
@ -93,7 +93,7 @@ static inline void *hpa2hva(uint64_t x)
*
* @param[in] x The specified host-virtual address
*
* @return unsigned long integer - The host-physical address
* @return The translated host-physical address
*/
static inline uint64_t hva2hpa(void *x)
{

26
hypervisor/include/arch/x86/vtd.h
View File

@ -496,8 +496,8 @@ struct iommu_domain;
* @param[in] bus the 8-bit bus number of the device
* @param[in] devfun the 8-bit device(5-bit):function(3-bit) of the device
*
* @return 0 - on success.
* @return 1 - fail to unassign the device
* @retval 0 on success.
* @retval 1 fail to unassign the device
*
* @pre domain != NULL
*
@ -513,8 +513,8 @@ int assign_iommu_device(struct iommu_domain *domain, uint8_t bus, uint8_t devfun
* @param[in] bus the 8-bit bus number of the device
* @param[in] devfun the 8-bit device(5-bit):function(3-bit) of the device
*
* @return 0 - on success.
* @return 1 - fail to unassign the device
* @retval 0 on success.
* @retval 1 fail to unassign the device
*
* @pre domain != NULL
*
@ -530,8 +530,10 @@ int unassign_iommu_device(const struct iommu_domain *domain, uint8_t bus, uint8_
* @param[in] translation_table the physcial address of EPT table of the VM specified by the vm_id
* @param[in] addr_width address width of the VM
*
* @return Pointer pointer to iommu_domain
* @return NULL if translation_table is 0
* @return Pointer to the created iommu_domain
*
* @retval NULL when \p translation_table is 0
* @retval !NULL when \p translation_table is not 0
*
* @pre vm_id is valid
* @pre translation_table != 0
@ -586,10 +588,12 @@ void resume_iommu(void);
/**
* @brief Init IOMMUs.
*
* Register DMAR units on the platform according to the pre-parsed information or DMAR table.
* Register DMAR units on the platform according to the pre-parsed information
* or DMAR table. IOMMU is a must have feature, if init_iommu failed, the system
* should not continue booting.
*
* @return 0 - on success
* @return non-zero - iommu is a must have feature, if init_iommu failed, the system should not continue booting
* @retval 0 on success
* @retval <0 on failure
*
*/
int init_iommu(void);
@ -614,8 +618,8 @@ void init_iommu_vm0_domain(struct acrn_vm *vm0);
*
* @param[in] vm pointer to VM to check
*
* @return true - support
* @return false - not support
* @retval true support
* @retval false not support
*
*/
bool iommu_snoop_supported(struct acrn_vm *vm);

4
hypervisor/include/common/irq.h
View File

@ -50,8 +50,8 @@ struct irq_desc {
* IRQF_LEVEL - 1: level trigger; 0: edge trigger;
* IRQF_PT - 1: for passthrough dev
*
* @return valid irq num - on success
* @return IRQ_INVALID - on failure
* @retval >=0 on success
* @retval IRQ_INVALID on failure
*/
int32_t request_irq(uint32_t req_irq, irq_action_t action_fn, void *priv_data,
uint32_t flags);