i386: doxygen and comments related to VESA real mode framebuffer

1 files changed, 21 insertions, 12 deletions

diff --git a/c/src/lib/libbsp/i386/shared/realmode_int/realmode_int.h b/c/src/lib/libbsp/i386/shared/realmode_int/realmode_int.h
index a0216ea0ad..6f77ec92ea 100644
--- a/c/src/lib/libbsp/i386/shared/realmode_int/realmode_int.h
+++ b/c/src/lib/libbsp/i386/shared/realmode_int/realmode_int.h
@@ -4,14 +4,14 @@
  * @ingroup i386_shared
  *
  * @brief Definitioins supporting real mode interrupt calls.
+ *
+ * Interface allows calling given interrupt number with content of the
+ * registers defined. For passing or receiving higher amounts of the data
+ * there is a buffer accessible from real mode available. Real mode pointer
+ * to this buffer is passed to the interrupt in the registers.
  */
 
 /*
- *  Interface allows calling given interrupt number with content of the
- *  registers defined. For passing or receiving higher amounts of the data
- *  there is a buffer accessible from real mode available. Real mode pointer
- *  to this buffer is passed to the interrupt in the registers.
- *
  * Copyright (C) 2014  Jan Doležal (dolezj21@fel.cvut.cz)
  *                     CTU in Prague.
  *
@@ -36,7 +36,11 @@ extern "C" {
 /* number of interrupt servicing video functions */
 #define INTERRUPT_NO_VIDEO_SERVICES 0x10
 
-typedef struct { /* used for passing parameters, fetching results and preserving values */
+/**
+ * @brief Used for passing and retrieving registers content to/from real mode
+ * interrupt call.
+ */
+typedef struct {
     uint32_t reg_eax;
     uint32_t reg_ebx;
     uint32_t reg_ecx;
@@ -50,6 +54,8 @@ typedef struct { /* used for passing parameters, fetching results and preserving
 } RTEMS_COMPILER_PACKED_ATTRIBUTE i386_realmode_interrupt_registers;
 
 /**
+ * @brief Returns buffer and its size usable with real mode interrupt call.
+ *
  * Provides position to real mode buffer. It is buffer
  * accessible from real mode context - it is located below
  * address ~0x100000 in order for it to be accessible
@@ -57,22 +63,25 @@ typedef struct { /* used for passing parameters, fetching results and preserving
  * and through this get bigger portion of an information to/from
  * interrupt service routine than just by using register.
  *
- * @param size pointer to variable, where the size of buffer
- *        will be filled
+ * @param[out] size pointer to variable, where the size of buffer
+ *             will be filled
  * @retval pointer to buffer
  */
 extern void *i386_get_default_rm_buffer(uint16_t *size);
 
 /**
+ * @brief Call to real mode interrupt with specified int NO and processor
+ * registers.
+ *
  * This function allows calling interrupts in real mode and to set processor
  * registers as desired before interrupt call is made and to retrieve the
  * registers content after call was made.
  *
- * @param interruptNumber interrupt number to be called
- * @param ir pointer to structure containing registers to be passed to interrupt
- *        and to retrieve register content after call was made.
+ * @param[in] interrupt_number interrupt number to be called
+ * @param[in] ir pointer to structure containing registers to be passed to
+ *            interrupt and to retrieve register content after call was made.
  * @retval  0 call failed (GDT too small or pagin is on)
- *          1 call successful
+ * @retval  1 call successful
  */
 extern int i386_real_interrupt_call(
     uint8_t interrupt_number,