HV: add missing @pre for some functions

donsheng · acrnsi · commit 0018da4114dd · 2019-05-20T10:37:13.000+08:00
Add @pre for some functions, and fix outdated @pre statements Tracked-On: #3056 Signed-off-by: dongshen <dongsheng.x.zhang@intel.com> Acked-by: Eddie Dong <eddie.dong@intel.com>
diff --git a/hypervisor/dm/vpci/vdev.c b/hypervisor/dm/vpci/vdev.c
@@ -30,6 +30,9 @@
 #include <vm.h>
 #include "vpci_priv.h"
 
+/**
+ * @pre vdev != NULL
+ */
 uint32_t pci_vdev_read_cfg(const struct pci_vdev *vdev, uint32_t offset, uint32_t bytes)
 {
 	uint32_t val;
@@ -49,6 +52,9 @@ uint32_t pci_vdev_read_cfg(const struct pci_vdev *vdev, uint32_t offset, uint32_
 	return val;
 }
 
+/**
+ * @pre vdev != NULL
+ */
 void pci_vdev_write_cfg(struct pci_vdev *vdev, uint32_t offset, uint32_t bytes, uint32_t val)
 {
 	switch (bytes) {
diff --git a/hypervisor/dm/vpci/vmsi.c b/hypervisor/dm/vpci/vmsi.c
@@ -57,6 +57,12 @@ static inline bool msicap_access(const struct pci_vdev *vdev, uint32_t offset)
 	return ret;
 }
 
+/**
+ * @pre vdev != NULL
+ * @pre vdev->vpci != NULL
+ * @pre vdev->vpci->vm != NULL
+ * @pre vdev->pdev != NULL
+ */
 static int32_t vmsi_remap(const struct pci_vdev *vdev, bool enable)
 {
 	struct ptirq_msi_info info;
@@ -172,6 +178,11 @@ int32_t vmsi_write_cfg(struct pci_vdev *vdev, uint32_t offset, uint32_t bytes, u
 	return ret;
 }
 
+/**
+ * @pre vdev != NULL
+ * @pre vdev->vpci != NULL
+ * @pre vdev->vpci->vm != NULL
+ */
 void deinit_vmsi(const struct pci_vdev *vdev)
 {
 	if (has_msi_cap(vdev)) {
@@ -194,6 +205,10 @@ static void buf_write32(uint8_t buf[], uint32_t val)
 	buf[3] = (uint8_t)((val >> 24U) & 0xFFU);
 }
 
+/**
+ * @pre vdev != NULL
+ * @pre vdev->pdev != NULL
+ */
 void init_vmsi(struct pci_vdev *vdev)
 {
 	struct pci_pdev *pdev = vdev->pdev;
diff --git a/hypervisor/dm/vpci/vmsix.c b/hypervisor/dm/vpci/vmsix.c
@@ -53,11 +53,20 @@ static inline bool msixcap_access(const struct pci_vdev *vdev, uint32_t offset)
 	return ret;
 }
 
+/**
+ * @pre vdev != NULL
+ */
 static inline bool msixtable_access(const struct pci_vdev *vdev, uint32_t offset)
 {
 	return in_range(offset, vdev->msix.table_offset, vdev->msix.table_count * MSIX_TABLE_ENTRY_SIZE);
 }
 
+/**
+ * @pre vdev != NULL
+ * @pre vdev->vpci != NULL
+ * @pre vdev->vpci->vm != NULL
+ * @pre vdev->pdev != NULL
+ */
 static int32_t vmsix_remap_entry(const struct pci_vdev *vdev, uint32_t index, bool enable)
 {
 	struct msix_table_entry *pentry;
@@ -92,6 +101,10 @@ static int32_t vmsix_remap_entry(const struct pci_vdev *vdev, uint32_t index, bo
 	return ret;
 }
 
+/**
+ * @pre vdev != NULL
+ * @pre vdev->pdev != NULL
+ */
 static inline void enable_disable_msix(const struct pci_vdev *vdev, bool enable)
 {
 	uint32_t msgctrl;
@@ -105,7 +118,11 @@ static inline void enable_disable_msix(const struct pci_vdev *vdev, bool enable)
 	pci_pdev_write_cfg(vdev->pdev->bdf, vdev->msix.capoff + PCIR_MSIX_CTRL, 2U, msgctrl);
 }
 
-/* Do MSI-X remap for all MSI-X table entries in the target device */
+/**
+ * Do MSI-X remap for all MSI-X table entries in the target device
+ * @pre vdev != NULL
+ * @pre vdev->pdev != NULL
+ */
 static int32_t vmsix_remap(const struct pci_vdev *vdev, bool enable)
 {
 	uint32_t index;
@@ -132,7 +149,11 @@ static int32_t vmsix_remap(const struct pci_vdev *vdev, bool enable)
 	return ret;
 }
 
-/* Do MSI-X remap for one MSI-X table entry only */
+/**
+ * Do MSI-X remap for one MSI-X table entry only
+ * @pre vdev != NULL
+ * @pre vdev->pdev != NULL
+ */
 static int32_t vmsix_remap_one_entry(const struct pci_vdev *vdev, uint32_t index, bool enable)
 {
 	uint32_t msgctrl;
@@ -336,6 +357,7 @@ int32_t vmsix_table_mmio_access_handler(struct io_request *io_req, void *handler
 
 /**
  * @pre vdev != NULL
+ * @pre vdev->pdev != NULL
  */
 void init_vmsix(struct pci_vdev *vdev)
 {
diff --git a/hypervisor/dm/vpci/vpci.c b/hypervisor/dm/vpci/vpci.c
@@ -51,7 +51,8 @@ static void pci_cfg_clear_cache(struct pci_addr_info *pi)
 }
 
 /**
- * @pre vm != NULL && vcpu != NULL
+ * @pre vm != NULL
+ * @pre vcpu != NULL
  */
 static bool pci_cfgaddr_io_read(struct acrn_vm *vm, struct acrn_vcpu *vcpu, uint16_t addr, size_t bytes)
 {
@@ -147,7 +148,7 @@ static bool pci_cfgdata_io_read(struct acrn_vm *vm, struct acrn_vcpu *vcpu, uint
 /**
  * @pre vm != NULL
  * @pre vm->vm_id < CONFIG_MAX_VM_NUM
- * @pre (get_vm_config(vm->vm_id)->type == PRE_LAUNCHED_VM) || (get_vm_config(vm->vm_id)->type == SOS_VM)
+ * @pre (get_vm_config(vm->vm_id)->load_order == PRE_LAUNCHED_VM) || (get_vm_config(vm->vm_id)->load_order == SOS_VM)
  */
 static bool pci_cfgdata_io_write(struct acrn_vm *vm, uint16_t addr, size_t bytes, uint32_t val)
 {
diff --git a/hypervisor/dm/vpci/vpci_priv.h b/hypervisor/dm/vpci/vpci_priv.h
@@ -37,31 +37,49 @@ static inline bool in_range(uint32_t value, uint32_t lower, uint32_t len)
 	return ((value >= lower) && (value < (lower + len)));
 }
 
+/**
+ * @pre vdev != NULL
+ */
 static inline uint8_t pci_vdev_read_cfg_u8(const struct pci_vdev *vdev, uint32_t offset)
 {
 	return vdev->cfgdata.data_8[offset];
 }
 
+/**
+ * @pre vdev != NULL
+ */
 static inline uint16_t pci_vdev_read_cfg_u16(const struct pci_vdev *vdev, uint32_t offset)
 {
 	return vdev->cfgdata.data_16[offset >> 1U];
 }
 
+/**
+ * @pre vdev != NULL
+ */
 static inline uint32_t pci_vdev_read_cfg_u32(const struct pci_vdev *vdev, uint32_t offset)
 {
 	return vdev->cfgdata.data_32[offset >> 2U];
 }
 
+/**
+ * @pre vdev != NULL
+ */
 static inline void pci_vdev_write_cfg_u8(struct pci_vdev *vdev, uint32_t offset, uint8_t val)
 {
 	vdev->cfgdata.data_8[offset] = val;
 }
 
+/**
+ * @pre vdev != NULL
+ */
 static inline void pci_vdev_write_cfg_u16(struct pci_vdev *vdev, uint32_t offset, uint16_t val)
 {
 	vdev->cfgdata.data_16[offset >> 1U] = val;
 }
 
+/**
+ * @pre vdev != NULL
+ */
 static inline void pci_vdev_write_cfg_u32(struct pci_vdev *vdev, uint32_t offset, uint32_t val)
 {
 	vdev->cfgdata.data_32[offset >> 2U] = val;

Original file line number	Diff line number	Diff line change
`@@ -30,6 +30,9 @@`
`30`	`30`	`#include <vm.h>`
`31`	`31`	`#include "vpci_priv.h"`
`32`	`32`
	`33`	`+/**`
	`34`	`+ * @pre vdev != NULL`
	`35`	`+ */`
`33`	`36`	`uint32_t pci_vdev_read_cfg(const struct pci_vdev *vdev, uint32_t offset, uint32_t bytes)`
`34`	`37`	`{`
`35`	`38`	`uint32_t val;`
`@@ -49,6 +52,9 @@ uint32_t pci_vdev_read_cfg(const struct pci_vdev *vdev, uint32_t offset, uint32_`
`49`	`52`	`return val;`
`50`	`53`	`}`
`51`	`54`
	`55`	`+/**`
	`56`	`+ * @pre vdev != NULL`
	`57`	`+ */`
`52`	`58`	`void pci_vdev_write_cfg(struct pci_vdev *vdev, uint32_t offset, uint32_t bytes, uint32_t val)`
`53`	`59`	`{`
`54`	`60`	`switch (bytes) {`
Original file line number	Diff line number	Diff line change
`@@ -57,6 +57,12 @@ static inline bool msicap_access(const struct pci_vdev *vdev, uint32_t offset)`
`57`	`57`	`return ret;`
`58`	`58`	`}`
`59`	`59`
	`60`	`+/**`
	`61`	`+ * @pre vdev != NULL`
	`62`	`+ * @pre vdev->vpci != NULL`
	`63`	`+ * @pre vdev->vpci->vm != NULL`
	`64`	`+ * @pre vdev->pdev != NULL`
	`65`	`+ */`
`60`	`66`	`static int32_t vmsi_remap(const struct pci_vdev *vdev, bool enable)`
`61`	`67`	`{`
`62`	`68`	`struct ptirq_msi_info info;`
`@@ -172,6 +178,11 @@ int32_t vmsi_write_cfg(struct pci_vdev *vdev, uint32_t offset, uint32_t bytes, u`
`172`	`178`	`return ret;`
`173`	`179`	`}`
`174`	`180`
	`181`	`+/**`
	`182`	`+ * @pre vdev != NULL`
	`183`	`+ * @pre vdev->vpci != NULL`
	`184`	`+ * @pre vdev->vpci->vm != NULL`
	`185`	`+ */`
`175`	`186`	`void deinit_vmsi(const struct pci_vdev *vdev)`
`176`	`187`	`{`
`177`	`188`	`if (has_msi_cap(vdev)) {`
`@@ -194,6 +205,10 @@ static void buf_write32(uint8_t buf[], uint32_t val)`
`194`	`205`	`buf[3] = (uint8_t)((val >> 24U) & 0xFFU);`
`195`	`206`	`}`
`196`	`207`
	`208`	`+/**`
	`209`	`+ * @pre vdev != NULL`
	`210`	`+ * @pre vdev->pdev != NULL`
	`211`	`+ */`
`197`	`212`	`void init_vmsi(struct pci_vdev *vdev)`
`198`	`213`	`{`
`199`	`214`	`struct pci_pdev *pdev = vdev->pdev;`
Original file line number	Diff line number	Diff line change
`@@ -53,11 +53,20 @@ static inline bool msixcap_access(const struct pci_vdev *vdev, uint32_t offset)`
`53`	`53`	`return ret;`
`54`	`54`	`}`
`55`	`55`
	`56`	`+/**`
	`57`	`+ * @pre vdev != NULL`
	`58`	`+ */`
`56`	`59`	`static inline bool msixtable_access(const struct pci_vdev *vdev, uint32_t offset)`
`57`	`60`	`{`
`58`	`61`	`return in_range(offset, vdev->msix.table_offset, vdev->msix.table_count * MSIX_TABLE_ENTRY_SIZE);`
`59`	`62`	`}`
`60`	`63`
	`64`	`+/**`
	`65`	`+ * @pre vdev != NULL`
	`66`	`+ * @pre vdev->vpci != NULL`
	`67`	`+ * @pre vdev->vpci->vm != NULL`
	`68`	`+ * @pre vdev->pdev != NULL`
	`69`	`+ */`
`61`	`70`	`static int32_t vmsix_remap_entry(const struct pci_vdev *vdev, uint32_t index, bool enable)`
`62`	`71`	`{`
`63`	`72`	`struct msix_table_entry *pentry;`
`@@ -92,6 +101,10 @@ static int32_t vmsix_remap_entry(const struct pci_vdev *vdev, uint32_t index, bo`
`92`	`101`	`return ret;`
`93`	`102`	`}`
`94`	`103`
	`104`	`+/**`
	`105`	`+ * @pre vdev != NULL`
	`106`	`+ * @pre vdev->pdev != NULL`
	`107`	`+ */`
`95`	`108`	`static inline void enable_disable_msix(const struct pci_vdev *vdev, bool enable)`
`96`	`109`	`{`
`97`	`110`	`uint32_t msgctrl;`
`@@ -105,7 +118,11 @@ static inline void enable_disable_msix(const struct pci_vdev *vdev, bool enable)`
`105`	`118`	`pci_pdev_write_cfg(vdev->pdev->bdf, vdev->msix.capoff + PCIR_MSIX_CTRL, 2U, msgctrl);`
`106`	`119`	`}`
`107`	`120`
`108`		`-/* Do MSI-X remap for all MSI-X table entries in the target device */`
	`121`	`+/**`
	`122`	`+ * Do MSI-X remap for all MSI-X table entries in the target device`
	`123`	`+ * @pre vdev != NULL`
	`124`	`+ * @pre vdev->pdev != NULL`
	`125`	`+ */`
`109`	`126`	`static int32_t vmsix_remap(const struct pci_vdev *vdev, bool enable)`
`110`	`127`	`{`
`111`	`128`	`uint32_t index;`
`@@ -132,7 +149,11 @@ static int32_t vmsix_remap(const struct pci_vdev *vdev, bool enable)`
`132`	`149`	`return ret;`
`133`	`150`	`}`
`134`	`151`
`135`		`-/* Do MSI-X remap for one MSI-X table entry only */`
	`152`	`+/**`
	`153`	`+ * Do MSI-X remap for one MSI-X table entry only`
	`154`	`+ * @pre vdev != NULL`
	`155`	`+ * @pre vdev->pdev != NULL`
	`156`	`+ */`
`136`	`157`	`static int32_t vmsix_remap_one_entry(const struct pci_vdev *vdev, uint32_t index, bool enable)`
`137`	`158`	`{`
`138`	`159`	`uint32_t msgctrl;`
`@@ -336,6 +357,7 @@ int32_t vmsix_table_mmio_access_handler(struct io_request io_req, void handler`
`336`	`357`
`337`	`358`	`/**`
`338`	`359`	`* @pre vdev != NULL`
	`360`	`+ * @pre vdev->pdev != NULL`
`339`	`361`	`*/`
`340`	`362`	`void init_vmsix(struct pci_vdev *vdev)`
`341`	`363`	`{`
Original file line number	Diff line number	Diff line change
`@@ -51,7 +51,8 @@ static void pci_cfg_clear_cache(struct pci_addr_info *pi)`
`51`	`51`	`}`
`52`	`52`
`53`	`53`	`/**`
`54`		`- * @pre vm != NULL && vcpu != NULL`
	`54`	`+ * @pre vm != NULL`
	`55`	`+ * @pre vcpu != NULL`
`55`	`56`	`*/`
`56`	`57`	`static bool pci_cfgaddr_io_read(struct acrn_vm vm, struct acrn_vcpu vcpu, uint16_t addr, size_t bytes)`
`57`	`58`	`{`
`@@ -147,7 +148,7 @@ static bool pci_cfgdata_io_read(struct acrn_vm vm, struct acrn_vcpu vcpu, uint`
`147`	`148`	`/**`
`148`	`149`	`* @pre vm != NULL`
`149`	`150`	`* @pre vm->vm_id < CONFIG_MAX_VM_NUM`
`150`		`- * @pre (get_vm_config(vm->vm_id)->type == PRE_LAUNCHED_VM) \|\| (get_vm_config(vm->vm_id)->type == SOS_VM)`
	`151`	`+ * @pre (get_vm_config(vm->vm_id)->load_order == PRE_LAUNCHED_VM) \|\| (get_vm_config(vm->vm_id)->load_order == SOS_VM)`
`151`	`152`	`*/`
`152`	`153`	`static bool pci_cfgdata_io_write(struct acrn_vm *vm, uint16_t addr, size_t bytes, uint32_t val)`
`153`	`154`	`{`
Original file line number	Diff line number	Diff line change
`@@ -37,31 +37,49 @@ static inline bool in_range(uint32_t value, uint32_t lower, uint32_t len)`
`37`	`37`	`return ((value >= lower) && (value < (lower + len)));`
`38`	`38`	`}`
`39`	`39`
	`40`	`+/**`
	`41`	`+ * @pre vdev != NULL`
	`42`	`+ */`
`40`	`43`	`static inline uint8_t pci_vdev_read_cfg_u8(const struct pci_vdev *vdev, uint32_t offset)`
`41`	`44`	`{`
`42`	`45`	`return vdev->cfgdata.data_8[offset];`
`43`	`46`	`}`
`44`	`47`
	`48`	`+/**`
	`49`	`+ * @pre vdev != NULL`
	`50`	`+ */`
`45`	`51`	`static inline uint16_t pci_vdev_read_cfg_u16(const struct pci_vdev *vdev, uint32_t offset)`
`46`	`52`	`{`
`47`	`53`	`return vdev->cfgdata.data_16[offset >> 1U];`
`48`	`54`	`}`
`49`	`55`
	`56`	`+/**`
	`57`	`+ * @pre vdev != NULL`
	`58`	`+ */`
`50`	`59`	`static inline uint32_t pci_vdev_read_cfg_u32(const struct pci_vdev *vdev, uint32_t offset)`
`51`	`60`	`{`
`52`	`61`	`return vdev->cfgdata.data_32[offset >> 2U];`
`53`	`62`	`}`
`54`	`63`
	`64`	`+/**`
	`65`	`+ * @pre vdev != NULL`
	`66`	`+ */`
`55`	`67`	`static inline void pci_vdev_write_cfg_u8(struct pci_vdev *vdev, uint32_t offset, uint8_t val)`
`56`	`68`	`{`
`57`	`69`	`vdev->cfgdata.data_8[offset] = val;`
`58`	`70`	`}`
`59`	`71`
	`72`	`+/**`
	`73`	`+ * @pre vdev != NULL`
	`74`	`+ */`
`60`	`75`	`static inline void pci_vdev_write_cfg_u16(struct pci_vdev *vdev, uint32_t offset, uint16_t val)`
`61`	`76`	`{`
`62`	`77`	`vdev->cfgdata.data_16[offset >> 1U] = val;`
`63`	`78`	`}`
`64`	`79`
	`80`	`+/**`
	`81`	`+ * @pre vdev != NULL`
	`82`	`+ */`
`65`	`83`	`static inline void pci_vdev_write_cfg_u32(struct pci_vdev *vdev, uint32_t offset, uint32_t val)`
`66`	`84`	`{`
`67`	`85`	`vdev->cfgdata.data_32[offset >> 2U] = val;`