From da9a9b3de6e08c3dea95779c10c6fcb96bc43f95 Mon Sep 17 00:00:00 2001
From: "adrian.spycher" <adrian.spycher@etu.hesge.ch>
Date: Tue, 5 Nov 2024 18:36:07 +0100
Subject: [PATCH] docs: comment header function
---
guest/console/console.h | 8 +++++
guest/gfx/gfx.h | 18 ++++++++++
guest/ide/ide.h | 24 +++++++++----
guest/timer/timer.h | 16 +++++++++
vmm/handler.c | 77 +++++++++++++++++++++++++++++++++++++++--
vmm/operation.h | 35 +++++++++++++++++++
6 files changed, 169 insertions(+), 9 deletions(-)
diff --git a/guest/console/console.h b/guest/console/console.h
index d8d494e..b0f77ac 100644
--- a/guest/console/console.h
+++ b/guest/console/console.h
@@ -7,6 +7,14 @@
// --- FUNCTION ---
+/**
+ * @brief Sends a message to the virtual console using paravirtualization.
+ *
+ * Transfers a string message to the VMM console via a paravirtualized hypercall,
+ * allowing the guest to output text to the VMM console.
+ *
+ * @param str Pointer to a null-terminated string containing the message to be sent.
+ */
void console_pv_send(char *str);
#endif // _CONSOLE_H_
diff --git a/guest/gfx/gfx.h b/guest/gfx/gfx.h
index 6aed69c..5886f31 100644
--- a/guest/gfx/gfx.h
+++ b/guest/gfx/gfx.h
@@ -9,8 +9,26 @@
// --- FUNCTION ---
+/**
+ * @brief Initializes the virtual graphics system with specified width and height using paravirtualization.
+ *
+ * Sets up the virtual graphics display with the desired dimensions through a paravirtualized hypercall,
+ * allowing for efficient graphics setup in the guest environment.
+ *
+ * @param width Width of the display in pixels.
+ * @param height Height of the display in pixels.
+ */
void gfx_pv_init(uint32_t width, uint32_t height);
+/**
+ * @brief Initializes the virtual graphics system with specified width and height in emulated mode.
+ *
+ * Configures the graphics display with the provided dimensions through an emulated hypercall,
+ * simulating a hardware-based initialization process.
+ *
+ * @param width Width of the display in pixels.
+ * @param height Height of the display in pixels.
+ */
void gfx_phys_init(uint32_t width, uint32_t height);
#endif // !_TIMER_H_
diff --git a/guest/ide/ide.h b/guest/ide/ide.h
index 8186e2b..6251891 100644
--- a/guest/ide/ide.h
+++ b/guest/ide/ide.h
@@ -10,13 +10,25 @@
// --- FUNCTION ---
/**
- * Read a sector from the first disk.
- * @param first sector to read (0-indexed)
- * @param dst address to store to read data
- * Based on the assembly code at http://wiki.osdev.org/ATA_read/write_sectors
+ * @brief Writes data to a specified sector on the IDE device using paravirtualization.
+ *
+ * Transmits a data block to a specified IDE sector in a paravirtualized manner,
+ * allowing the guest to write data more efficiently.
+ *
+ * @param sector_idx Index of the target sector on the IDE device.
+ * @param data Pointer to the data buffer to be written.
*/
-void ide_phys_write_sector(uint32_t sector_idx, void *data);
-
void ide_pv_write_sector(uint32_t sector_idx, void *data);
+/**
+ * @brief Writes data to a specified sector on the IDE device using emulation.
+ *
+ * Transfers a data block to a specific sector of the emulated IDE device,
+ * simulating a hardware IDE write operation.
+ *
+ * @param sector_idx Index of the target sector on the IDE device.
+ * @param data Pointer to the data buffer to be written.
+ */
+void ide_phys_write_sector(uint32_t sector_idx, void *data);
+
#endif // _IDE_H_
diff --git a/guest/timer/timer.h b/guest/timer/timer.h
index 9e44db0..1986647 100644
--- a/guest/timer/timer.h
+++ b/guest/timer/timer.h
@@ -9,8 +9,24 @@
// --- FUNCTION ---
+/**
+ * @brief Waits for a specified duration using a paravirtualized timer.
+ *
+ * Pauses execution within the guest for a set time in microseconds,
+ * leveraging a paravirtualized hypercall for efficient timing.
+ *
+ * @param us Duration of the wait in microseconds.
+ */
void timer_pv_wait(uint32_t us);
+/**
+ * @brief Waits for a specified duration using an emulated timer.
+ *
+ * Delays execution within the guest for the specified time in microseconds,
+ * simulating a hardware-based timing wait.
+ *
+ * @param us Duration of the wait in microseconds.
+ */
void timer_phys_wait(uint32_t us);
#endif // !_TIMER_H_
diff --git a/vmm/handler.c b/vmm/handler.c
index 2c52eff..a67e00f 100644
--- a/vmm/handler.c
+++ b/vmm/handler.c
@@ -25,6 +25,17 @@ static state_t *current_state = NULL;
// - UTILS -
+/**
+ * @brief Retrieves data from a specified address with a given size.
+ *
+ * This function extracts a value from the address provided, interpreting the data based
+ * on the specified size (1, 2, or 4 bytes). If an unsupported size is given, the function
+ * will terminate the program with an error.
+ *
+ * @param addr Address to retrieve data from.
+ * @param size Size of the data to retrieve (in bytes).
+ * @return Extracted 32-bit value from the specified address.
+ */
static uint32_t retrieve_data(uint8_t *addr, uint8_t size) {
uint32_t value;
@@ -51,6 +62,17 @@ static uint32_t retrieve_data(uint8_t *addr, uint8_t size) {
return value;
}
+/**
+ * @brief Injects data into a specified address with a given size.
+ *
+ * This function writes a value to the address provided, interpreting the data based
+ * on the specified size (1, 2, or 4 bytes). If an unsupported size is provided, the function
+ * will terminate the program with an error.
+ *
+ * @param addr Address to inject data into.
+ * @param size Size of the data to inject (in bytes).
+ * @param value The 32-bit value to inject at the specified address.
+ */
static void injecte_data(uint8_t *addr, uint8_t size, uint32_t value) {
switch (size) {
@@ -73,6 +95,17 @@ static void injecte_data(uint8_t *addr, uint8_t size, uint32_t value) {
}
}
+/**
+ * @brief Checks if a state transition is possible based on the provided address, size, and value.
+ *
+ * Iterates over available state machine configurations to find a matching state
+ * that meets the specified conditions, returning it if found.
+ *
+ * @param addr Memory address of the operation.
+ * @param size Size of the operation (in bytes).
+ * @param value Value to compare or store based on the state's operation.
+ * @return Pointer to the matching state, or NULL if no match is found.
+ */
static state_t *state_check(uint64_t addr, uint8_t size, uint32_t value) {
for (uint32_t i = 0; i < STATE_MACHINE_NUM + 1; i++) {
@@ -114,6 +147,17 @@ static state_t *state_check(uint64_t addr, uint8_t size, uint32_t value) {
return NULL;
}
+/**
+ * @brief Executes operations for the current state and determines if the next state should be entered.
+ *
+ * Performs any necessary computations or callback invocations for the current state.
+ * Determines whether to advance to the next state based on the state's configuration and
+ * modifies `current_state` accordingly.
+ *
+ * @param state Pointer to the current state.
+ * @param value Value for the operation (e.g., value written to a register).
+ * @param addr Address associated with the operation.
+ */
static void state_compute(state_t *state, uint32_t value, uint8_t *addr) {
bool go_next = true;
@@ -134,6 +178,7 @@ static void state_compute(state_t *state, uint32_t value, uint8_t *addr) {
case OP_WRITE_STORE_LOOP:
+ // - prevent advancing to the next state if loop is ongoing -
if (flag_stop_loop == false)
go_next = false;
break;
@@ -145,20 +190,27 @@ static void state_compute(state_t *state, uint32_t value, uint8_t *addr) {
break;
}
- // - check and compute last operation -
+ // - move to the next state if applicable (not in loop) -
if (go_next) current_state = state + 1;
+ // - check to end and compute the last operation -
if (current_state->op == OP_EMUL_END) {
if (current_state->callback != NULL)
current_state->callback(NULL);
- current_state = NULL;
+ current_state = NULL;
}
}
-// - OPERATION WRAPPER -
+// - OPERATION WRAPPERS -
+/**
+ * @brief Handles console hypercall by adjusting buffer pointers and invoking callback.
+ *
+ * @param shared_buf Buffer shared between guest and host.
+ * @param mem Pointer to guest memory, used to calculate buffer offsets.
+ */
static void wrapper_op_console(uint8_t *shared_buf, uint8_t *mem) {
hyper_virtual_console_params_t *p_consol = (hyper_virtual_console_params_t *)shared_buf;
@@ -167,18 +219,37 @@ static void wrapper_op_console(uint8_t *shared_buf, uint8_t *mem) {
op_callback_console_conclude(p_consol);
}
+/**
+ * @brief Handles timer hypercall by invoking the timer conclusion callback.
+ *
+ * @param shared_buf Buffer holding timer parameters for the hypercall.
+ */
static void wrapper_op_timer(uint8_t *shared_buf) {
hyper_timer_sleep_params_t *p_timer = (hyper_timer_sleep_params_t *)shared_buf;
op_callback_timer_conclude(p_timer);
}
+/**
+ * @brief Handles graphics initialization hypercall and invokes conclusion callback.
+ *
+ * @param shared_buf Buffer holding graphics initialization parameters.
+ */
static void wrapper_op_gfx_init(uint8_t *shared_buf) {
hyper_init_gfx_params_t *p_init_gfx = (hyper_init_gfx_params_t *)shared_buf;
op_callback_gfx_init_conclude(p_init_gfx);
}
+/**
+ * @brief Handles IDE (Integrated Drive Electronics) hypercall and invokes the conclusion callback.
+ *
+ * Adjusts the data pointer to account for the guest memory base, ensuring the callback
+ * receives a valid address for the data transfer.
+ *
+ * @param shared_buf Buffer holding IDE parameters for the hypercall.
+ * @param mem Pointer to guest memory, used to calculate data buffer offsets.
+ */
static void wrapper_op_ide(uint8_t *shared_buf, uint8_t *mem) {
hyper_ide_params_t *p_ide = (hyper_ide_params_t *)shared_buf;
diff --git a/vmm/operation.h b/vmm/operation.h
index f37e0ac..b9e009c 100644
--- a/vmm/operation.h
+++ b/vmm/operation.h
@@ -90,18 +90,53 @@ void op_callback_gfx_init_store_h(void *addr);
*/
void op_callback_gfx_init_conclude(void *addr);
+/**
+ * @brief Prepares for an IDE operation by setting up necessary parameters.
+ *
+ * @param addr Address of the IDE parameters or `NULL` if using previously configured parameters.
+ */
void op_callback_ide_prepare(void *addr);
+/**
+ * @brief Stores data in the first sector for an IDE operation.
+ *
+ * @param addr Address containing the data to be stored in sector 1, or `NULL` to use pre-existing data.
+ */
void op_callback_ide_store_sector_1(void *addr);
+/**
+ * @brief Stores data in the second sector for an IDE operation.
+ *
+ * @param addr Address containing the data to be stored in sector 2, or `NULL` to use pre-existing data.
+ */
void op_callback_ide_store_sector_2(void *addr);
+/**
+ * @brief Stores data in the third sector for an IDE operation.
+ *
+ * @param addr Address containing the data to be stored in sector 3, or `NULL` to use pre-existing data.
+ */
void op_callback_ide_store_sector_3(void *addr);
+/**
+ * @brief Stores data in the fourth sector for an IDE operation.
+ *
+ * @param addr Address containing the data to be stored in sector 4, or `NULL` to use pre-existing data.
+ */
void op_callback_ide_store_sector_4(void *addr);
+/**
+ * @brief Stores the entire data payload for an IDE operation.
+ *
+ * @param addr Address containing the complete IDE data payload, or `NULL` if previously stored data is to be used.
+ */
void op_callback_ide_store_data(void *addr);
+/**
+ * @brief Concludes the IDE operation by finalizing data transfer or processing steps.
+ *
+ * @param addr Address of the concluding parameters for the IDE operation, or `NULL` to use previously set parameters.
+ */
void op_callback_ide_conclude(void *addr);
#endif // _OPERATION_H_
--
GitLab