[PATCH 2/2] i386: doxygen and comments related to VESA real mode framebuffer

Jan Dolezal dolezj21 at fel.cvut.cz
Wed Dec 3 16:29:29 UTC 2014


Hello Gedare,

thank you very much for your comments. I really appreciate them.

On 3.12.2014 00:59, Gedare Bloom wrote:
> Sometimes params are identified as in our out, sometimes they are not.
> Please be consistent. Generally patch looks OK, does the doxygen look
> right when applied? [1] can help
There is a problem caused by redefinition of macro 
RTEMS_COMPILER_PACKED_ATTRIBUTE for edid.h (to EDID_PACKED_ATTRIBUTE) 
and vbe3.h (to VBE3_PACKED_ATTRIBUTE).

Currently doxygen sets names of typedefed structs using these macros 
([EDID,VBE3]_PACKED_ATTRIBUTE) to these macros names - so I ended up 
with several structs named after macro.

I already added RTEMS_COMPILER_PACKED_ATTRIBUTE= into PREDEFINED tag 
under cpukit/Doxyfile.in, so when doxygen preprocessor encounters this 
macro it replaces it with 'nothing'.

Now I think there are two reasonable approaches to make things work
1) set MACRO_EXPANSION to YES in Doxyfile.in
    This way macros [EDID,VBE3]_PACKED... are replaced by
    RTEMS_COMPILER_PACKED... one, that is empty.
    Nevertheless I'm not sure if this way could harm something else.
2) drop usage of macros [EDID,VBE3]_PACKED_ATTRIBUTEs and use
    RTEMS_COMPILER_PACKED_ATTRIBUTE instead

3) I could add macros [EDID,VBE3]_PACKED_ATTRIBUTE to PREDEFINED tag
    under cpukit/Doxyfile.in, but it seems to me that is way too much
    global place for small amount of things it influences in the end

Which way would you prefer?

>
> -Gedare
>
> [1] https://github.com/joelsherrill/gci_tasks/blob/master/2013/doxygen_c_header_tasks/validate/do_doxygen
>
> On Tue, Dec 2, 2014 at 11:49 AM, Jan Dolezal <dolezj21 at fel.cvut.cz> wrote:
>> ---
>>   c/src/lib/libbsp/i386/pc386/console/fb_vesa_rm.c   | 105 ++++---
>>   c/src/lib/libbsp/i386/pc386/include/edid.h         |  14 +-
>>   c/src/lib/libbsp/i386/pc386/include/fb_vesa.h      |  74 ++---
>>   c/src/lib/libbsp/i386/pc386/include/tblsizes.h     |   1 -
>>   c/src/lib/libbsp/i386/pc386/include/vbe3.h         | 311 ++++++++++++++-------
>>   c/src/lib/libbsp/i386/pc386/startup/ldsegs.S       |   6 +-
>>   c/src/lib/libbsp/i386/shared/irq/idt.c             |  10 +-
>>   .../libbsp/i386/shared/realmode_int/realmode_int.c |  69 ++++-
>>   .../libbsp/i386/shared/realmode_int/realmode_int.h |  33 ++-
>>   c/src/lib/libcpu/i386/cpu.h                        |  53 ++--
>>   cpukit/score/cpu/i386/cpu_asm.S                    |   4 +-
>>   cpukit/score/cpu/i386/rtems/score/i386.h           |  39 ++-
>>   12 files changed, 468 insertions(+), 251 deletions(-)
>>
>> diff --git a/c/src/lib/libbsp/i386/pc386/console/fb_vesa_rm.c b/c/src/lib/libbsp/i386/pc386/console/fb_vesa_rm.c
>> index b7b27b6..fb9d575 100644
>> --- a/c/src/lib/libbsp/i386/pc386/console/fb_vesa_rm.c
>> +++ b/c/src/lib/libbsp/i386/pc386/console/fb_vesa_rm.c
>> @@ -1,35 +1,39 @@
>> -/*
>> - *  FB driver for graphic hardware compatible with VESA Bios Extension
>> - *  Real mode interface utilized
>> - *  Tested on real HW.
>> +/**
>> + * @file fb_vesa_rm.c
>> + *
>> + * @ingroup i386_pc386
>> + *
>> + * @brief FB driver for graphic hardware compatible with VESA Bios Extension
>> + *     Real mode interface utilized
>> + *     Tested on real HW.
>>    *
>> - *  Copyright (c) 2014 - CTU in Prague
>> - *                       Jan Doležal ( dolezj21 at fel.cvut.cz )
>> + * Public sources related:
>> + *   - VESA BIOS EXTENSION (VBE) Core Function Standard, Ver: 3.0, Sep 16, 1998
>> + *   - VESA Enhanced Extended Display Identification Data (E-EDID) Standard
>> + *     Release A, Revision 2, September 25, 2006
>>    *
>> - *  The license and distribution terms for this file may be
>> - *  found in the file LICENSE in this distribution or at
>> - *  http://www.rtems.org/license/LICENSE.
>> + * Hardware is completely initialized upon boot of the system.
>> + * Therefore there is no way to change graphics mode later.
>>    *
>> - *  The code for rtems_buffer_* functions were greatly
>> - *  inspired or coppied from:
>> - *    - RTEMS fb_cirrus.c - Alexandru-Sever Horin (alex.sever.h at gmail.com)
>> + * Interrupt 0x10 is used for entering graphics BIOS.
>>    *
>> - *  Public sources related:
>> - *    - VESA BIOS EXTENSION (VBE) Core Function Standard, Ver: 3.0, Sep 16, 1998
>> - *    - VESA Enhanced Extended Display Identification Data (E-EDID) Standard
>> - *      Release A, Revision 2, September 25, 2006
>> + * Driver reads parameter from multiboot command line to setup video:
>> + * "--video=<resX>x<resY>[-<bpp>]"
>> + * If cmdline parameter is not specified an attempt for obtaining
>> + * resolution from display attached is made.
>>    */
>>
>>   /*
>> - *  Hardware is completely initialized upon boot of the system.
>> - *  Therefore there is no way to change graphics mode later.
>> + * Copyright (c) 2014 - CTU in Prague
>> + *                      Jan Doležal ( dolezj21 at fel.cvut.cz )
>>    *
>> - *  Interrupt 0x10 is used for entering graphics BIOS.
>> + * The license and distribution terms for this file may be
>> + * found in the file LICENSE in this distribution or at
>> + * http://www.rtems.org/license/LICENSE.
>>    *
>> - *  Driver reads parameter from multiboot command line to setup video:
>> - *  "--video=<resX>x<resY>[-<bpp>]"
>> - *  If cmdline parameter is not specified an attempt for obtaining
>> - *  resolution from display attached is made.
>> + * The code for rtems_buffer_* functions were greatly
>> + * inspired or coppied from:
>> + *   - RTEMS fb_cirrus.c - Alexandru-Sever Horin (alex.sever.h at gmail.com)
>>    */
>>
>>   #include <bsp.h>
>> @@ -48,6 +52,13 @@
>>
>>   #define FB_VESA_NAME    "FB_VESA_RM"
>>
>> +/**
>> + * @brief Initializes VBE framebuffer during bootup.
>> + *
>> + * utilizes switches to real mode interrupts and therefore must be
>> + * called during bootup before tick is set up and real-time
>> + * interrupt vectors utilized
>> + */
>>   void vesa_realmode_bootup_init(void);
>>
>>   /* mutex for protection against multiple opens, when called frame_buffer_open */
>> @@ -187,19 +198,37 @@ inline uint32_t VBE_read_EDID(uint16_t controller_unit_number,
>>       return (parret.reg_eax & 0xFFFF);
>>   }
>>
>> +/**
>> + * @brief Basic graphic's mode parameters
>> + */
>>   typedef struct {
>> +    /** number of the graphic's mode */
>>       uint16_t mode_number;
>> +    /** number of pixels in one line */
>>       uint16_t resX;
>> +    /** number of lines */
>>       uint16_t resY;
>> +    /** bits per pixel */
>>       uint8_t bpp;
>>   } Mode_params;
>>
>> -/* finds mode in 'modeList' of 'listLength' length according to resolution
>> -    given in 'searchedResolution'. If bpp is given in that struct as well
>> -    mode with such color depth and resolution is searched for. Otherwise bpp
>> -    has to be zero. Mode number found is returned and also filled into
>> -    'searchedResolution'. bpp is also filled into 'searchedResolution' if it
>> -    was 0 before call. */
>> +/**
>> + * @brief Find mode by resolution in the given list of modes
>> + *
>> + * finds mode in \p mode_list of \p list_length length according to resolution
>> + * given in \p searched_resolution . If bpp is given in that struct as well
>> + * mode with such color depth and resolution is searched for. Otherwise bpp
>> + * has to be zero. Mode number found is returned and also filled into
>> + * \p searched_resolution . bpp is also filled into \p searchedResolution if it
>> + * was 0 before call.
>> + *
>> + * @param[in] mode_list list of modes to be searched
>> + * @param[in] list_length number of modes in the list
>> + * @param searched_resolution element filled with searched resolution or/and
>> + *            bpp
>> + * @retval mode number satisfying given parameters
>> + * @retval -1 no suitable mode found
>> + */
>>   static uint16_t find_mode_by_resolution(   Mode_params *mode_list,
>>                                           uint8_t list_length,
>>                                           Mode_params *searched_resolution)
>> @@ -223,14 +252,18 @@ static uint16_t find_mode_by_resolution(   Mode_params *mode_list,
>>       return -1;
>>   }
>>
>> -/*
>> - * Parse comandline option "--video=" if available.
>> +/**
>> + * @brief Find mode given within command line.
>> + *
>> + * Parse command line option "--video=" if available.
>>    *  expected format
>>    *  --video=<resX>x<resY>[-<bpp>]
>>    *  numbers <resX>, <resY> and <bpp> are decadic
>>    *
>> + * @param[in] mode_list list of modes to be searched
>> + * @param[in] list_length number of modes in the list
>>    * @retval video mode number to be set
>> - *         -1 on parsing error or when no suitable mode found
>> + * @retval -1 on parsing error or when no suitable mode found
>>    */
>>   static uint16_t find_mode_using_cmdline(Mode_params *mode_list,
>>                                           uint8_t list_length)
>> @@ -278,11 +311,13 @@ static uint16_t find_mode_using_cmdline(Mode_params *mode_list,
>>       return -1;
>>   }
>>
>> -/*
>> - * returns mode number best fitting to monitor attached
>> +/**
>> + * @brief Find mode number best fitting to monitor attached
>>    *
>> + * @param[in] mode_list list of modes to be searched
>> + * @param[in] list_length number of modes in the list
>>    * @retval video mode number to be set
>> - *         -1 on parsing error or when no suitable mode found
>> + * @retval -1 on parsing error or when no suitable mode found
>>    */
>>   static uint16_t find_mode_using_EDID( Mode_params *mode_list,
>>                                         uint8_t list_length)
>> diff --git a/c/src/lib/libbsp/i386/pc386/include/edid.h b/c/src/lib/libbsp/i386/pc386/include/edid.h
>> index 41bf1ca..16be6f6 100644
>> --- a/c/src/lib/libbsp/i386/pc386/include/edid.h
>> +++ b/c/src/lib/libbsp/i386/pc386/include/edid.h
>> @@ -4,16 +4,16 @@
>>    * @ingroup i386_pc386
>>    *
>>    * @brief VESA EDID definitions.
>> + *
>> + * This file contains definitions for constants related to
>> + * VESA Extended Display Identification Data.
>> + *         More information can be found at
>> + *     <http://www.vesa.org/vesa-standards/free-standards/>
>> + *         VESA public standards may be found at
>> + *     <http://www.vesa.org/wp-content/uploads/2010/12/thankspublic.htm>
>>    */
>>
>>   /*
>> - * edid.h  - This file contains definitions for constants related to
>> - *           VESA Extended Display Identification Data.
>> - *          More information can be found at
>> - *      <http://www.vesa.org/vesa-standards/free-standards/>
>> - *          VESA public standards may be found at
>> - *      <http://www.vesa.org/wp-content/uploads/2010/12/thankspublic.htm>
>> - *
>>    * Copyright (C) 2014  Jan Doležal (dolezj21 at fel.cvut.cz)
>>    *                     CTU in Prague.
>>    *
>> diff --git a/c/src/lib/libbsp/i386/pc386/include/fb_vesa.h b/c/src/lib/libbsp/i386/pc386/include/fb_vesa.h
>> index 88e7dd8..d03b070 100644
>> --- a/c/src/lib/libbsp/i386/pc386/include/fb_vesa.h
>> +++ b/c/src/lib/libbsp/i386/pc386/include/fb_vesa.h
>> @@ -3,12 +3,10 @@
>>    *
>>    * @ingroup i386_pc386
>>    *
>> - * @brief Definitioins for vesa based framebuffer drivers.
>> + * @brief Headers specific for framebuffer drivers utilizing VESA VBE.
>>    */
>>
>>   /*
>> - * Headers specific for framebuffer drivers utilizing VESA VBE.
>> - *
>>    * Copyright (C) 2014  Jan Doležal (dolezj21 at fel.cvut.cz)
>>    *                     CTU in Prague.
>>    *
>> @@ -35,15 +33,16 @@ extern "C" {
>>   /* ----- Prototypes ----- */
>>
>>   /**
>> - * Returns information about graphic's controller in the infoBlock structure.
>> + * @brief Returns information about graphic's controller in the \p info_block
>> + * structure.
>>    *
>> - * @param infoBlock pointer to the struct to be filled with
>> -                    controller information
>> - * @param queriedVBEVersion if >0x200 then video bios is asked to fill in
>> + * @param info_block pointer to the struct to be filled with
>> + *                  controller information
>> + * @param queried_VBE_Version if >0x200 then video bios is asked to fill in
>>    *                          parameters which appeared with second version
>>    *                          of VBE.
>> - * @retval  register ax content as defined in VBE RETURN STATUS paragraph
>> - *          -1 error calling graphical bios
>> + * @retval  ax register content as defined in VBE RETURN STATUS paragraph
>> + * @retval  -1 error calling graphical bios
>>    */
>>   uint32_t VBE_controller_information (
>>       VBE_VbeInfoBlock *info_block,
>> @@ -51,13 +50,13 @@ uint32_t VBE_controller_information (
>>   );
>>
>>   /**
>> - * Fills structure infoBlock with informations about selected mode in
>> - * modeNumber variable.
>> + * @brief Fills structure \p info_block with informations about selected mode in
>> + * \p mode_number variable.
>>    *
>> - * @param infoBlock pointer to the struct to be filled with mode information
>> - * @param modeNumber detailes of this mode to be filled
>> - * @retval  register ax content as defined in VBE RETURN STATUS paragraph
>> - *          -1 error calling graphical bios
>> + * @param info_block pointer to the struct to be filled with mode information
>> + * @param mode_number detailes of this mode to be filled
>> + * @retval  ax register content as defined in VBE RETURN STATUS paragraph
>> + * @retval  -1 error calling graphical bios
>>    */
>>   uint32_t VBE_mode_information (
>>       VBE_ModeInfoBlock *info_block,
>> @@ -65,13 +64,13 @@ uint32_t VBE_mode_information (
>>   );
>>
>>   /**
>> - * Sets graphics mode selected. If mode has refreshRateCtrl bit set, than the
>> - * infoBlock must be filled accordingly.
>> + * @brief Sets graphics mode selected. If mode has refreshRateCtrl bit set, than
>> + * the \p info_block must be filled accordingly.
>>    *
>> - * @param modeNumber number of mode to be set
>> - * @param infoBlock pointer to struct containing refresh rate control info
>> - * @retval  register ax content as defined in VBE RETURN STATUS paragraph
>> - *          -1 error calling graphical bios
>> + * @param mode_number number of mode to be set
>> + * @param info_block pointer to struct containing refresh rate control info
>> + * @retval  ax register content as defined in VBE RETURN STATUS paragraph
>> + * @retval  -1 error calling graphical bios
>>    */
>>   uint32_t VBE_set_mode (
>>       uint16_t mode_number,
>> @@ -79,27 +78,27 @@ uint32_t VBE_set_mode (
>>   );
>>
>>   /**
>> - * Get currently set mode number.
>> + * @brief Get currently set mode number.
>>    *
>> - * @param modeNumber variable to be filled with current mode number
>> - * @retval  register ax content as defined in VBE RETURN STATUS paragraph
>> - *          -1 error calling graphical bios
>> + * @param mode_number variable to be filled with current mode number
>> + * @retval  ax register content as defined in VBE RETURN STATUS paragraph
>> + * @retval  -1 error calling graphical bios
>>    */
>>   uint32_t VBE_current_mode (
>>       uint16_t *mode_number
>>   );
>>
>>   /**
>> - * Gets information about display data channel implemented in the
>> + * @brief Gets information about display data channel implemented in the
>>    * graphic's controller.
>>    *
>> - * @param controllerUnitNumber
>> - * @param secondsToTransferEDIDBlock approximate time to transfer one EDID block
>> - *                                   rounded up to seconds
>> - * @param DDCLevelSupported after call contains DDC version supported and
>> + * @param controller_unit_number
>> + * @param seconds_to_transfer_EDID_block approximate time to transfer one EDID
>> + *                                       block rounded up to seconds
>> + * @param DDC_level_supported after call contains DDC version supported and
>>    *                          screen blanking state during transfer
>> - * @retval  register ax content as defined in VBE RETURN STATUS paragraph
>> - *          -1 error calling graphical bios
>> + * @retval  ax register content as defined in VBE RETURN STATUS paragraph
>> + * @retval  -1 error calling graphical bios
>>    */
>>   uint32_t VBE_report_DDC_capabilities (
>>       uint16_t controller_unit_number,
>> @@ -108,13 +107,14 @@ uint32_t VBE_report_DDC_capabilities (
>>   );
>>
>>   /**
>> - * Reads selected EDID block from display attached to controller's interface.
>> + * @brief Reads selected EDID block from display attached to controller's
>> + * interface.
>>    *
>> - * @param controllerUnitNumber
>> - * @param EDIDBlockNumber block no. to be read from the display
>> + * @param controller_unit_number
>> + * @param EDID_block_number block no. to be read from the display
>>    * @param buffer place to store block fetched from the display
>> - * @retval  register ax content as defined in VBE RETURN STATUS paragraph
>> - *          -1 error calling graphical bios
>> + * @retval  ax register content as defined in VBE RETURN STATUS paragraph
>> + * @retval  -1 error calling graphical bios
>>    */
>>   uint32_t VBE_read_EDID (
>>       uint16_t controller_unit_number,
>> diff --git a/c/src/lib/libbsp/i386/pc386/include/tblsizes.h b/c/src/lib/libbsp/i386/pc386/include/tblsizes.h
>> index 6128d87..bd4e989 100644
>> --- a/c/src/lib/libbsp/i386/pc386/include/tblsizes.h
>> +++ b/c/src/lib/libbsp/i386/pc386/include/tblsizes.h
>> @@ -7,7 +7,6 @@
>>    */
>>
>>   /*
>> - * Definitions related to the PC386 BSP.
>>    * This header file is also used in assembler modules.
>>    *
>>    * Copyright (C) 2014  Jan Doležal (dolezj21 at fel.cvut.cz)
>> diff --git a/c/src/lib/libbsp/i386/pc386/include/vbe3.h b/c/src/lib/libbsp/i386/pc386/include/vbe3.h
>> index ba0ae3f..5aaa461 100644
>> --- a/c/src/lib/libbsp/i386/pc386/include/vbe3.h
>> +++ b/c/src/lib/libbsp/i386/pc386/include/vbe3.h
>> @@ -4,15 +4,15 @@
>>    * @ingroup i386_pc386
>>    *
>>    * @brief VESA Bios Extension definitions.
>> + *
>> + * This file contains definitions for constants related to VBE.
>> + *         More information can be found at
>> + *     <http://www.vesa.org/vesa-standards/free-standards/>
>> + *         VESA public standards may be found at
>> + *     <http://www.vesa.org/wp-content/uploads/2010/12/thankspublic.htm>
>>    */
>>
>>   /*
>> - * vbe3.h  - This file contains definitions for constants related to VBE.
>> - *          More information can be found at
>> - *      <http://www.vesa.org/vesa-standards/free-standards/>
>> - *          VESA public standards may be found at
>> - *      <http://www.vesa.org/wp-content/uploads/2010/12/thankspublic.htm>
>> - *
>>    * Copyright (C) 2014  Jan Doležal (dolezj21 at fel.cvut.cz)
>>    *                     CTU in Prague.
>>    *
>> @@ -156,22 +156,41 @@ extern "C" {
>>   #define VBE_RetVBESupSpeInf    0x00  /* Return VBE Supplemental
>>                                           Specification Information */
>>   /* *** Structures *** */
>> +/**
>> + * @brief Far pointer as defined by VBE standard.
>> + */
>>   typedef struct {
>> +    /** @brief Offset to segment described by \a selector. */
>>       uint16_t offset;
>> +    /** @brief Selector or Segment depending on whether this is used from 16bit
>> +        protected mode or from real mode. */
>>       uint16_t selector;
>>   } VBE3_PACKED_ATTRIBUTE VBE_FarPtr;
>>
>> +/**
>> + * @brief Protected mode info block as defined by VBE standard.
>> + */
>>   typedef struct {
>> -    uint8_t   Signature[4];    /*  PM Info Block Signature */
>> -    uint16_t  EntryPoint;      /*  Offset of PM entry point within BIOS */
>> -    uint16_t  PMInitialize;    /*  Offset of PM initialization entry point */
>> -    uint16_t  BIOSDataSel;     /*  Selector to BIOS data area emulation block */
>> -    uint16_t  A0000Sel;        /*  Selector to access A0000h physical mem */
>> -    uint16_t  B0000Sel;        /*  Selector to access B0000h physical mem */
>> -    uint16_t  B8000Sel;        /*  Selector to access B8000h physical mem */
>> -    uint16_t  CodeSegSel;      /*  Selector to access code segment as data */
>> -    uint8_t   InProtectMode;   /*  Set to 1 when in protected mode */
>> -    uint8_t   Checksum;        /*  Checksum byte for structure */
>> +    /** PM Info Block Signature */
>> +    uint8_t   Signature[4];
>> +    /** Offset of PM entry point within BIOS */
>> +    uint16_t  EntryPoint;
>> +    /** Offset of PM initialization entry point */
>> +    uint16_t  PMInitialize;
>> +    /** Selector to BIOS data area emulation block */
>> +    uint16_t  BIOSDataSel;
>> +    /** Selector to access A0000h physical memmory */
>> +    uint16_t  A0000Sel;
>> +    /** Selector to access B0000h physical memmory */
>> +    uint16_t  B0000Sel;
>> +    /** Selector to access B8000h physical memmory */
>> +    uint16_t  B8000Sel;
>> +    /** Selector to access code segment as data */
>> +    uint16_t  CodeSegSel;
>> +    /** Set to 1 when in protected mode */
>> +    uint8_t   InProtectMode;
>> +    /** Checksum byte for structure */
>> +    uint8_t   Checksum;
>>   } VBE3_PACKED_ATTRIBUTE VBE_PMInfoBlock;
>>
>>   /* General VBE signature */
>> @@ -181,111 +200,201 @@ typedef struct {
>>   /* for STUB see VBE CORE FUNCTIONS VERSION 3.0 - Appendix 1 */
>>   #define VBE_END_OF_VideoModeList 0xFFFF
>>   #define VBE_STUB_VideoModeList 0xFFFF
>> +/**
>> + * @brief Information about VBE implementation.
>> + */
>>   typedef struct {
>> -    uint8_t   VbeSignature[4];   /*  VBE Signature */
>> -    uint16_t  VbeVersion;        /*  VBE Version */
>> -    uint8_t  *OemStringPtr;      /*  VbeFarPtr to OEM String */
>> -    uint8_t   Capabilities[4];   /*  Capabilities of graphics controller */
>> -    uint32_t *VideoModePtr;      /*  VbeFarPtr to VideoModeList */
>> -    uint16_t  TotalMemory;       /*  Number of 64kb memory blocks    */
>> +    /** VBE Signature */
>> +    uint8_t   VbeSignature[4];
>> +    /** VBE Version */
>> +    uint16_t  VbeVersion;
>> +    /** VbeFarPtr to OEM String */
>> +    uint8_t  *OemStringPtr;
>> +    /** Capabilities of graphics controller */
>> +    uint8_t   Capabilities[4];
>> +    /** VbeFarPtr to VideoModeList */
>> +    uint32_t *VideoModePtr;
>> +    /** Number of 64kb memory blocks    */
>> +    uint16_t  TotalMemory;
>>       /*  Added for VBE 2.0+ */
>> -    uint16_t  OemSoftwareRev;    /*  VBE implementation Software revision */
>> -    uint8_t  *OemVendorNamePtr;  /*  VbeFarPtr to Vendor Name String */
>> -    uint8_t  *OemProductNamePtr; /*  VbeFarPtr to Product Name String */
>> -    uint8_t  *OemProductRevPtr;  /*  VbeFarPtr to Product Revision String */
>> -    uint8_t   Reserved[222];     /*  Reserved for VBE implementation scratch */
>> -    /*    area */
>> -    uint8_t   OemData[256];      /*  Data Area for OEM Strings */
>> +    /** VBE implementation Software revision */
>> +    uint16_t  OemSoftwareRev;
>> +    /** VbeFarPtr to Vendor Name String */
>> +    uint8_t  *OemVendorNamePtr;
>> +    /** VbeFarPtr to Product Name String */
>> +    uint8_t  *OemProductNamePtr;
>> +    /** VbeFarPtr to Product Revision String */
>> +    uint8_t  *OemProductRevPtr;
>> +    /** Reserved for VBE implementation scratch */
>> +    uint8_t   Reserved[222];
>> +    /** Data Area for OEM Strings */
>> +    uint8_t   OemData[256];
>>   } VBE3_PACKED_ATTRIBUTE VBE_VbeInfoBlock;
>>
>> +/**
>> + * @brief Describes graphic's mode parameter.
>> + */
>>   typedef struct {
>>       /*  Mandatory information for all VBE revisions */
>> -    uint16_t  ModeAttributes;        /* mode attributes */
>> -    uint8_t   WinAAttributes;        /* window A attributes */
>> -    uint8_t   WinBAttributes;        /* window B attributes */
>> -    uint16_t  WinGranularity;        /* window granularity */
>> -    uint16_t  WinSize;               /* window size */
>> -    uint16_t  WinASegment;           /* window A start segment */
>> -    uint16_t  WinBSegment;           /* window B start segment */
>> -    uint32_t *WinFuncPtr;            /* real mode pointer to window function */
>> -    uint16_t  BytesPerScanLine;      /* bytes per scan line */
>> +    /** mode attributes */
>> +    uint16_t  ModeAttributes;
>> +    /** window A attributes */
>> +    uint8_t   WinAAttributes;
>> +    /** window B attributes */
>> +    uint8_t   WinBAttributes;
>> +    /** window granularity */
>> +    uint16_t  WinGranularity;
>> +    /** window size */
>> +    uint16_t  WinSize;
>> +    /** window A start segment */
>> +    uint16_t  WinASegment;
>> +    /** window B start segment */
>> +    uint16_t  WinBSegment;
>> +    /** real mode pointer to window function */
>> +    uint32_t *WinFuncPtr;
>> +    /** bytes per scan line */
>> +    uint16_t  BytesPerScanLine;
>>       /*  Mandatory information for VBE 1.2 and above */
>> -    uint16_t  XResolution;           /* horizontal resolution in px or chars */
>> -    uint16_t  YResolution;           /* vertical resolution in px or chars */
>> -    uint8_t   XCharSize;             /* character cell width in pixels */
>> -    uint8_t   YCharSize;             /* character cell height in pixels */
>> -    uint8_t   NumberOfPlanes;        /* number of memory planes */
>> -    uint8_t   BitsPerPixel;          /* bits per pixel */
>> -    uint8_t   NumberOfBanks;         /* number of banks */
>> -    uint8_t   MemoryModel;           /* memory model type */
>> -    uint8_t   BankSize;              /* bank size in KB */
>> -    uint8_t   NumberOfImagePages;    /* number of images */
>> -    uint8_t   Reserved0;             /* reserved for page function */
>> +    /** horizontal resolution in px or chars */
>> +    uint16_t  XResolution;
>> +    /** vertical resolution in px or chars */
>> +    uint16_t  YResolution;
>> +    /** character cell width in pixels */
>> +    uint8_t   XCharSize;
>> +    /** character cell height in pixels */
>> +    uint8_t   YCharSize;
>> +    /** number of memory planes */
>> +    uint8_t   NumberOfPlanes;
>> +    /** bits per pixel */
>> +    uint8_t   BitsPerPixel;
>> +    /** number of banks */
>> +    uint8_t   NumberOfBanks;
>> +    /** memory model type */
>> +    uint8_t   MemoryModel;
>> +    /** bank size in KB */
>> +    uint8_t   BankSize;
>> +    /** number of images */
>> +    uint8_t   NumberOfImagePages;
>> +    /** reserved for page function */
>> +    uint8_t   Reserved0;
>>       /*  Direct Color fields (required for direct/6 and YUV/7 memory models) */
>> -    uint8_t   RedMaskSize;           /* size of direct color red mask in bits */
>> -    uint8_t   RedFieldPosition;      /* bit position of lsb of red mask */
>> -    uint8_t   GreenMaskSize;         /* size of direct color green mask in b */
>> -    uint8_t   GreenFieldPosition;    /* bit position of lsb of green mask */
>> -    uint8_t   BlueMaskSize;          /* size of direct color blue mask in b */
>> -    uint8_t   BlueFieldPosition;     /* bit position of lsb of blue mask */
>> -    uint8_t   RsvdMaskSize;          /* size of direct color reserved mask */
>> -    uint8_t   RsvdFieldPosition;     /* bit position of lsb of reserved mask */
>> -    uint8_t   DirectColorModeInfo;   /* direct color mode attributes */
>> +    /** size of direct color red mask in bits */
>> +    uint8_t   RedMaskSize;
>> +    /** bit position of lsb of red mask */
>> +    uint8_t   RedFieldPosition;
>> +    /** size of direct color green mask in b */
>> +    uint8_t   GreenMaskSize;
>> +    /** bit position of lsb of green mask */
>> +    uint8_t   GreenFieldPosition;
>> +    /** size of direct color blue mask in b */
>> +    uint8_t   BlueMaskSize;
>> +    /** bit position of lsb of blue mask */
>> +    uint8_t   BlueFieldPosition;
>> +    /** size of direct color reserved mask */
>> +    uint8_t   RsvdMaskSize;
>> +    /** bit position of lsb of reserved mask */
>> +    uint8_t   RsvdFieldPosition;
>> +    /** direct color mode attributes */
>> +    uint8_t   DirectColorModeInfo;
>>       /*  Mandatory information for VBE 2.0 and above */
>> -    uint32_t *PhysBasePtr;           /* physical address for
>> -                                        flat memory frame buffer */
>> -    uint32_t  Reserved1;             /* Reserved - always set to 0 */
>> -    uint16_t  Reserved2;             /* Reserved - always set to 0 */
>> +    /** physical address for flat memory frame buffer */
>> +    uint32_t *PhysBasePtr;
>> +    /** Reserved - always set to 0 */
>> +    uint32_t  Reserved1;
>> +    /** Reserved - always set to 0 */
>> +    uint16_t  Reserved2;
>>       /*  Mandatory information for VBE 3.0 and above */
>> -    uint16_t  LinBytesPerScanLine;   /* bytes per scan line for linear modes */
>> -    uint8_t   BnkNumberOfImagePages; /* number of images for banked modes */
>> -    uint8_t   LinNumberOfImagePages; /* number of images for linear modes */
>> +    /** bytes per scan line for linear modes */
>> +    uint16_t  LinBytesPerScanLine;
>> +    /** number of images for banked modes */
>> +    uint8_t   BnkNumberOfImagePages;
>> +    /** number of images for linear modes */
>> +    uint8_t   LinNumberOfImagePages;
>>           /* linear modes */
>> -    uint8_t   LinRedMaskSize;        /* size of direct color red mask */
>> -    uint8_t   LinRedFieldPosition;   /* bit position of lsb of red mask */
>> -    uint8_t   LinGreenMaskSize;      /* size of direct color green mask  */
>> -    uint8_t   LinGreenFieldPosition; /* bit position of lsb of green mask */
>> -    uint8_t   LinBlueMaskSize;       /* size of direct color blue mask  */
>> -    uint8_t   LinBlueFieldPosition;  /* bit position of lsb of blue mask */
>> -    uint8_t   LinRsvdMaskSize;       /* size of direct color reserved mask */
>> -    uint8_t   LinRsvdFieldPosition;  /* bit position of lsb of reserved mask */
>> -    uint32_t  MaxPixelClock;         /* maximum pixel clock
>> -                                        (in Hz) for graphics mode */
>> -    uint8_t   Reserved3[189];        /* remainder of ModeInfoBlock */
>> +    /** size of direct color red mask */
>> +    uint8_t   LinRedMaskSize;
>> +    /** bit position of lsb of red mask */
>> +    uint8_t   LinRedFieldPosition;
>> +    /** size of direct color green mask  */
>> +    uint8_t   LinGreenMaskSize;
>> +    /** bit position of lsb of green mask */
>> +    uint8_t   LinGreenFieldPosition;
>> +    /** size of direct color blue mask  */
>> +    uint8_t   LinBlueMaskSize;
>> +    /** bit position of lsb of blue mask */
>> +    uint8_t   LinBlueFieldPosition;
>> +    /** size of direct color reserved mask */
>> +    uint8_t   LinRsvdMaskSize;
>> +    /** bit position of lsb of reserved mask */
>> +    uint8_t   LinRsvdFieldPosition;
>> +    /** maximum pixel clock (in Hz) for graphics mode */
>> +    uint32_t  MaxPixelClock;
>> +    /** remainder of ModeInfoBlock */
>> +    uint8_t   Reserved3[189];
>>   } VBE3_PACKED_ATTRIBUTE VBE_ModeInfoBlock;
>>
>> +/**
>> + * @brief Describes monitor synchronization.
>> + */
>>   typedef struct {
>> -    uint16_t  HorizontalTotal;       /* Horizontal total in pixels */
>> -    uint16_t  HorizontalSyncStart;   /* Horizontal sync start in pixels */
>> -    uint16_t  HorizontalSyncEnd;     /* Horizontal sync end in pixels */
>> -    uint16_t  VerticalTotal;         /* Vertical total in lines */
>> -    uint16_t  VerticalSyncStart;     /* Vertical sync start in lines */
>> -    uint16_t  VerticalSyncEnd;       /* Vertical sync end in lines */
>> -    uint8_t   Flags;                 /* Flags (Interlaced, Double Scan etc) */
>> -    uint32_t  PixelClock;            /* Pixel clock in units of Hz */
>> -    uint16_t  RefreshRate;           /* Refresh rate in units of 0.01 Hz */
>> -    uint8_t   Reserved[40];          /* remainder of ModeInfoBlock */
>> +    /** Horizontal total in pixels */
>> +    uint16_t  HorizontalTotal;
>> +    /** Horizontal sync start in pixels */
>> +    uint16_t  HorizontalSyncStart;
>> +    /** Horizontal sync end in pixels */
>> +    uint16_t  HorizontalSyncEnd;
>> +    /** Vertical total in lines */
>> +    uint16_t  VerticalTotal;
>> +    /** Vertical sync start in lines */
>> +    uint16_t  VerticalSyncStart;
>> +    /** Vertical sync end in lines */
>> +    uint16_t  VerticalSyncEnd;
>> +    /** Flags (Interlaced, Double Scan etc) */
>> +    uint8_t   Flags;
>> +    /** Pixel clock in units of Hz */
>> +    uint32_t  PixelClock;
>> +    /** Refresh rate in units of 0.01 Hz */
>> +    uint16_t  RefreshRate;
>> +    /** remainder of ModeInfoBlock */
>> +    uint8_t   Reserved[40];
>>   } VBE3_PACKED_ATTRIBUTE VBE_CRTCInfoBlock;
>>
>> +/**
>> + * @brief Describes palette entry.
>> + */
>>   typedef struct {
>> -    uint8_t   Blue;                  /* Blue channel value (6 or 8 bits) */
>> -    uint8_t   Green;                 /* Green channel value (6 or 8 bits) */
>> -    uint8_t   Red;                   /* Red channel value(6 or 8 bits) */
>> -    uint8_t   Alignment;             /* DWORD alignment byte (unused) */
>> +    /** Blue channel value (6 or 8 bits) */
>> +    uint8_t   Blue;
>> +    /** Green channel value (6 or 8 bits) */
>> +    uint8_t   Green;
>> +    /** Red channel value(6 or 8 bits) */
>> +    uint8_t   Red;
>> +    /** DWORD alignment byte (unused) */
>> +    uint8_t   Alignment;
>>   } VBE3_PACKED_ATTRIBUTE VBE_PaletteEntry;
>>
>> +/**
>> + * @brief Supplemental VBE info block.
>> + */
>>   typedef struct {
>> -    uint8_t   SupVbeSignature[7];    /* Supplemental VBE Signature */
>> -    uint16_t  SupVbeVersion;         /* Supplemental VBE Version */
>> -    uint8_t   SupVbeSubFunc[8];      /* Bitfield of supported subfunctions */
>> -    uint16_t  OemSoftwareRev;        /* OEM Software revision */
>> -    uint8_t  *OemVendorNamePtr;      /* VbeFarPtr to Vendor Name String */
>> -    uint8_t  *OemProductNamePtr;     /* VbeFarPtr to Product Name String */
>> -    uint8_t  *OemProductRevPtr;      /* VbeFarPtr to Product Revision String */
>> -    uint8_t  *OemStringPtr;          /* VbeFarPtr to OEM String */
>> -    uint8_t   Reserved[221];         /* Reserved for description
>> -                                        strings and future */
>> -    /*  expansion */
>> +    /** Supplemental VBE Signature */
>> +    uint8_t   SupVbeSignature[7];
>> +    /** Supplemental VBE Version */
>> +    uint16_t  SupVbeVersion;
>> +    /** Bitfield of supported subfunctions */
>> +    uint8_t   SupVbeSubFunc[8];
>> +    /** OEM Software revision */
>> +    uint16_t  OemSoftwareRev;
>> +    /** VbeFarPtr to Vendor Name String */
>> +    uint8_t  *OemVendorNamePtr;
>> +    /** VbeFarPtr to Product Name String */
>> +    uint8_t  *OemProductNamePtr;
>> +    /** VbeFarPtr to Product Revision String */
>> +    uint8_t  *OemProductRevPtr;
>> +    /** VbeFarPtr to OEM String */
>> +    uint8_t  *OemStringPtr;
>> +    /** Reserved for description strings and future expansion */
>> +    uint8_t   Reserved[221];
>>   } VBE3_PACKED_ATTRIBUTE VBE_SupVbeInfoBlock;
>>
>>   /* VbeInfoBlock Capabilities */
>> diff --git a/c/src/lib/libbsp/i386/pc386/startup/ldsegs.S b/c/src/lib/libbsp/i386/pc386/startup/ldsegs.S
>> index 14cbb95..9d61caf 100644
>> --- a/c/src/lib/libbsp/i386/pc386/startup/ldsegs.S
>> +++ b/c/src/lib/libbsp/i386/pc386/startup/ldsegs.S
>> @@ -200,7 +200,7 @@ SYM (_Global_descriptor_table):
>>   +--------------------------------------------------------------------------*/
>>           PUBLIC(gdtdesc)
>>   SYM(gdtdesc):
>> -       .word (GDT_SIZE*8 - 1)
>> +        .word (GDT_SIZE*8 - 1)
>>          .long SYM (_Global_descriptor_table)
>>
>>   /*---------------------------------------------------------------------------+
>> @@ -210,7 +210,7 @@ SYM(gdtdesc):
>>
>>          PUBLIC(Interrupt_descriptor_table)
>>   SYM(Interrupt_descriptor_table):
>> -       .rept IDT_SIZE
>> +        .rept IDT_SIZE
>>          .word 0,0,0,0
>>          .endr
>>
>> @@ -221,7 +221,7 @@ SYM(Interrupt_descriptor_table):
>>          .p2align 4
>>          PUBLIC(IDT_Descriptor)
>>   SYM(IDT_Descriptor):
>> -       .word  (IDT_SIZE*8 - 1)
>> +        .word  (IDT_SIZE*8 - 1)
>>          .long  SYM (Interrupt_descriptor_table)
>>
>>   END_DATA
>> diff --git a/c/src/lib/libbsp/i386/shared/irq/idt.c b/c/src/lib/libbsp/i386/shared/irq/idt.c
>> index fc9364e..ff7db36 100644
>> --- a/c/src/lib/libbsp/i386/shared/irq/idt.c
>> +++ b/c/src/lib/libbsp/i386/shared/irq/idt.c
>> @@ -1,12 +1,12 @@
>>   /*
>> - * cpu.c  - This file contains implementation of C function to
>> + * idt.c  - This file contains implementation of C function to
>>    *          instantiate IDT entries. More detailled information can be found
>> - *         on Intel site and more precisely in the following book :
>> + *          on Intel site and more precisely in the following book :
>>    *
>> - *             Pentium Processor family
>> - *             Developper's Manual
>> + *              Pentium Processor family
>> + *              Developper's Manual
>>    *
>> - *             Volume 3 : Architecture and Programming Manual
>> + *              Volume 3 : Architecture and Programming Manual
>>    *
>>    * Copyright (C) 1998  Eric Valette (valette at crf.canon.fr)
>>    *                     Canon Centre Recherche France.
>> diff --git a/c/src/lib/libbsp/i386/shared/realmode_int/realmode_int.c b/c/src/lib/libbsp/i386/shared/realmode_int/realmode_int.c
>> index af5cf1e..8e9a83d 100644
>> --- a/c/src/lib/libbsp/i386/shared/realmode_int/realmode_int.c
>> +++ b/c/src/lib/libbsp/i386/shared/realmode_int/realmode_int.c
>> @@ -1,20 +1,28 @@
>> -/*
>> - *  Realmode interrupt call implementation.
>> +/**
>> + * @file realmode_int.c
>>    *
>> + * @ingroup i386_shared
>>    *
>> - *  Copyright (c) 2014 - CTU in Prague
>> - *                       Jan Doležal ( dolezj21 at fel.cvut.cz )
>> + * @brief Real mode interrupt call implementation
>> + */
>> +
>> +/*
>> + * Copyright (c) 2014 - CTU in Prague
>> + *                      Jan Doležal ( dolezj21 at fel.cvut.cz )
>>    *
>>    *  The license and distribution terms for this file may be
>>    *  found in the file LICENSE in this distribution or at
>>    *  http://www.rtems.org/license/LICENSE.
>> - *
>>    */
>>
>>   #include <bsp/realmode_int.h>
>>   #include <string.h>
>>   #include <rtems/score/cpu.h>
>>
>> +/*
>> + * offsets to \a i386_realmode_interrupt_registers declared in realmode_int.h
>> + * used in inline assmbler for better readability
>> + */
>>   #define IR_EAX_OFF      "0x00"
>>   #define IR_EBX_OFF      "0x04"
>>   #define IR_ECX_OFF      "0x08"
>> @@ -26,25 +34,45 @@
>>   #define IR_FS_OFF       "0x1C"
>>   #define IR_GS_OFF       "0x1E"
>>
>> +/*
>> + * offsets to \a rm_int_regs_bkp_param
>> + */
>>   #define BKP_ESP_OFF     "0x20"
>>   #define BKP_SS_OFF      "0x24"
>>   #define BKP_DS_OFF      "0x26"
>>   #define RM_ENTRY        "0x28"
>>   #define PM_ENTRY        "0x2C"
>>
>> -/* parameters, results, backup values accessible in real mode */
>> +/**
>> + * @brief parameters, results, backup values accessible in real mode
>> + *
>> + * @note Struct members not necessarily used in C. This serves also as
>> + *       layout of memory and it is used within inline assembler.
>> + */
>>   typedef struct {
>>       i386_realmode_interrupt_registers inoutregs;
>> +    /** spot for back up of protected mode stack pointer */
>>       uint32_t pm_esp_bkp;
>> +    /** spot for back up of protected mode stack selector */
>>       uint16_t pm_ss_bkp;
>> +    /** spot for back up of protected mode data selector */
>>       uint16_t ds_bkp;
>> +    /** spot for setting up long indirect jump offset
>> +        to real mode from 16bit protected mode */
>>       uint16_t rm_entry;
>> +    /** spot for setting up long indirect jump segment
>> +        to real mode from 16bit protected mode */
>>       uint16_t rm_code_segment;
>> +    /** returning offset for long indirect jump back
>> +        to 32bit protected mode */
>>       uint32_t pm_entry;
>> +    /** returning selector for long indirect jump back
>> +        to 32bit protected mode */
>>       uint16_t pm_code_selector;
>> -    /* if modifying update offset definitions as well */
>> +    /* if this struct is to be modified update offset definitions as well */
>>   } RTEMS_COMPILER_PACKED_ATTRIBUTE rm_int_regs_bkp_param;
>>
>> +/* offsets to \a pm_bkp_and_param */
>>   #define BKP_IDTR_LIM    "0x00"
>>   #define BKP_IDTR_BASE   "0x02"
>>   #define BKP_ES_OFF      "0x06"
>> @@ -55,18 +83,35 @@ typedef struct {
>>   #define RM_SS           "0x14"
>>   #define RM_SP           "0x16"
>>   #define RM_DS           "0x18"
>> -/* backup values, pointers/parameters accessible in protected mode */
>> +
>> +/**
>> + * @brief backup values, pointers/parameters accessible in protected mode
>> + *
>> + * @note Struct members not necessarily used in C. This serves also as
>> + *       layout of memory and it is used within inline assembler.
>> + */
>>   typedef struct {
>> +    /** spot for backup protected mode interrupt descriptor table register */
>>       uint16_t idtr_lim_bkp;
>> +    /** @see idtr_lim_bkp */
>>       uint32_t idtr_base_bkp;
>> +    /** spot to backup of ES register value in 32bit protected mode */
>>       uint16_t es_bkp;
>> +    /** spot to backup of FS register value in 32bit protected mode */
>>       uint16_t fs_bkp;
>> +    /** spot to backup of GS register value in 32bit protected mode */
>>       uint16_t gs_bkp;
>> +    /** values for indirect jump to 16bit protected mode */
>>       uint32_t rml_entry;
>> +    /** @see rml_entry */
>>       uint16_t rml_code_selector;
>> +    /** data selector for 16bit protected mode */
>>       uint16_t rml_data_selector;
>> +    /** values determinig location of real mode stack */
>>       uint16_t rm_stack_segment;
>> +    /** @see rm_stack_segment */
>>       uint16_t rm_stack_pointer;
>> +    /** data segment for real mode */
>>       uint16_t rm_data_segment;
>>   } RTEMS_COMPILER_PACKED_ATTRIBUTE pm_bkp_and_param;
>>
>> @@ -112,10 +157,14 @@ static __DP_TYPE descsPrepared = __DP_NO;
>>   static uint16_t rml_code_dsc_index = 0;
>>   static uint16_t rml_data_dsc_index = 0;
>>
>> -/*
>> - * Prepares real-mode like descriptors to be used for switching
>> +/**
>> + * @brief Prepares real-mode like descriptors to be used for switching
>>    * to real mode.
>>    *
>> + * Descriptors will be placed to the GDT.
>> + *
>> + * @param[in] base32 32-bit physical address to be used as base for 16-bit
>> + *               protected mode descriptors
>>    * @retval __DP_YES descriptors are prepared
>>    * @retval __DP_FAIL descriptors allocation failed (GDT too small)
>>    */
>> 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 a0216ea..6f77ec9 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 at 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,
>> diff --git a/c/src/lib/libcpu/i386/cpu.h b/c/src/lib/libcpu/i386/cpu.h
>> index 23a82de..50234a6 100644
>> --- a/c/src/lib/libcpu/i386/cpu.h
>> +++ b/c/src/lib/libcpu/i386/cpu.h
>> @@ -1,5 +1,7 @@
>>   /*
>> - * cpu.h  - This file contains definitions for data structure related
>> + * @file cpu.h
>> + *
>> + *          This file contains definitions for data structure related
>>    *          to Intel system programming. More information can be found
>>    *         on Intel site and more precisely in the following book :
>>    *
>> @@ -241,7 +243,9 @@ extern int i386_get_idt_config (rtems_raw_irq_global_settings** config);
>>    * See page 11.12 Figure 11-8.
>>    *
>>    */
>> -
>> +/**
>> + * @brief segment_descriptors sturcture describes one entry of Descriptor Table
>> + */
>>   typedef struct {
>>     unsigned int limit_15_0              : 16;
>>     unsigned int base_address_15_0       : 16;
>> @@ -272,34 +276,36 @@ extern void i386_set_GDTR (segment_descriptors*,
>>                              uint16_t limit);
>>
>>   /**
>> - * C callable function:
>> - * Puts global descriptor @sd to the global descriptor table on index
>> - * @segment_selector_index
>> + * @brief Allows to set a GDT entry.
>> + *
>> + * Puts global descriptor \p sd to the global descriptor table on index
>> + * \p segment_selector_index
>>    *
>> + * @param[in] segment_selector_index index to GDT entry
>> + * @param[in] sd structure to be coppied to given \p segment_selector in GDT
>>    * @retval  0 FAILED out of GDT range or index is 0, which is not valid
>>    *                   index in GDT
>> - *          1 SUCCESS
>> + * @retval  1 SUCCESS
>>    */
>>   extern uint32_t i386_raw_gdt_entry (uint16_t segment_selector_index,
>>                                  segment_descriptors* sd);
>>
>>   /**
>> - * C callable function
>> - * fills @sd with provided @base in appropriate fields of @sd
>> + * @brief fills \p sd with provided \p base in appropriate fields of \p sd
>>    *
>>    * @param base 32-bit address to be set as descriptor's base
>> - * @param sd descriptor being filled with @base
>> + * @param sd descriptor being filled with \p base
>>    */
>>   extern void i386_fill_segment_desc_base (uint32_t base,
>>                                            segment_descriptors* sd);
>>
>>   /**
>> - * C callable function
>> - * fills @sd with provided @limit in appropriate fields of @sd
>> - * also influences granularity bit
>> + * @brief fills \p sd with provided \p limit in appropriate fields of \p sd
>> + *
>> + * sets granularity bit if necessary
>>    *
>>    * @param limit 32-bit value representing number of limit bytes
>> - * @param sd descriptor being filled with @limit
>> + * @param sd descriptor being filled with \p limit
>>    */
>>   extern void i386_fill_segment_desc_limit (uint32_t limit,
>>                                             segment_descriptors* sd);
>> @@ -312,35 +318,36 @@ extern uint32_t i386_set_gdt_entry (uint16_t segment_selector,
>>                                       uint32_t limit);
>>
>>   /**
>> - * C callable function returns next empty descriptor in GDT.
>> + * @brief Returns next empty descriptor in GDT.
>>    *
>>    * @retval  0 FAILED GDT is full
>> - *          <1;65535> segment_selector number as index to GDT
>> + * @retval  <1;65535> segment_selector number as index to GDT
>>    */
>>   extern uint16_t i386_next_empty_gdt_entry (void);
>>
>>   /**
>> - * Copies GDT entry at index @segment_selector to structure
>> - * pointed to by @struct_to_fill
>> + * @brief Copies GDT entry at index \p segment_selector to structure
>> + * pointed to by \p struct_to_fill
>>    *
>>    * @param  segment_selector index to GDT table for specifying descriptor to copy
>> + * @param  struct_to_fill pointer to memory where should be descriptor coppied
>>    * @retval  0 FAILED segment_selector out of GDT range
>> - *          <1;65535> retrieved segment_selector
>> + * @retval  <1;65535> retrieved segment_selector
>>    */
>>   extern uint16_t i386_cpy_gdt_entry (uint16_t segment_selector,
>>                                       segment_descriptors* struct_to_fill);
>>
>>   /**
>> - * Returns pointer to GDT table at index given by @segment_selector
>> + * @brief Returns pointer to GDT table at index given by \p segment_selector
>>    *
>> - * @param   segment_selector index to GDT table for specifying descriptor to get
>> + * @param   sgmnt_selector index to GDT table for specifying descriptor to get
>>    * @retval  NULL FAILED segment_selector out of GDT range
>> - *          pointer to GDT table at @segment_selector
>> + * @retval  pointer to GDT table at \p segment_selector
>>    */
>>   extern segment_descriptors* i386_get_gdt_entry (uint16_t sgmnt_selector);
>>
>>   /**
>> - * Extracts base address from GDT entry pointed to by @gdt_entry
>> + * @brief Extracts base address from GDT entry pointed to by \p gdt_entry
>>    *
>>    * @param  gdt_entry pointer to entry from which base should be retrieved
>>    * @retval base address from GDT entry
>> @@ -353,7 +360,7 @@ RTEMS_INLINE_ROUTINE void* i386_base_gdt_entry (segment_descriptors* gdt_entry)
>>   }
>>
>>   /**
>> - * Extracts limit in bytes from GDT entry pointed to by @gdt_entry
>> + * @brief Extracts limit in bytes from GDT entry pointed to by \p gdt_entry
>>    *
>>    * @param  gdt_entry pointer to entry from which limit should be retrieved
>>    * @retval limit value in bytes from GDT entry
>> diff --git a/cpukit/score/cpu/i386/cpu_asm.S b/cpukit/score/cpu/i386/cpu_asm.S
>> index f3ef4e2..45079a6 100644
>> --- a/cpukit/score/cpu/i386/cpu_asm.S
>> +++ b/cpukit/score/cpu/i386/cpu_asm.S
>> @@ -334,9 +334,9 @@ SYM (i386_Physical_to_logical):
>>    *     uint16_t *offset
>>    *  );
>>    *
>> - *  Fills segment:offest realmode pointer counted from thirty-two bit physical
>> + *  Fills segment:offest real mode pointer counted from thirty-two bit physical
>>    *  address.
>> - *  Returns 0 if unconvertible, 1 if successfuly converted.
>> + *  Returns 0 if inconvertible, 1 if successfuly converted.
>>    */
>>
>>   .set PHYS_PTR_ARG,   4
>> diff --git a/cpukit/score/cpu/i386/rtems/score/i386.h b/cpukit/score/cpu/i386/rtems/score/i386.h
>> index 926627d..875526a 100644
>> --- a/cpukit/score/cpu/i386/rtems/score/i386.h
>> +++ b/cpukit/score/cpu/i386/rtems/score/i386.h
>> @@ -185,10 +185,14 @@ void *i386_Physical_to_logical(
>>     void           *address
>>   );
>>
>> -/*
>> - *  i386_Real_to_physical
>> +/**
>> + * @brief Converts real mode pointer {segment, offset} to physical address.
>> + *
>> + * i386_Real_to_physical
>>    *
>> - *  Converts real mode pointer {segment, offset} to physical address.
>> + * @param[in] segment used with \p offset to compute physical address
>> + * @param[in] offset used with \p segment to compute physical address
>> + * @retval    physical address
>>    */
>>   RTEMS_INLINE_ROUTINE void *i386_Real_to_physical(
>>       uint16_t segment,
>> @@ -197,19 +201,24 @@ RTEMS_INLINE_ROUTINE void *i386_Real_to_physical(
>>       return (void *)(((uint32_t)segment<<4)+offset);
>>   }
>>
>> -/*
>> - *  i386_Physical_to_real
>> - *  Retreives real mode pointer elements {segmnet, offset} from physical address
>> - *  Function returns the highest segment (base) address possible.
>> - *  Example:    input   address - 0x4B3A2
>> - *              output  segment - 0x4B3A
>> - *                      offset  - 0x2
>> - *              input   address - 0x10F12E
>> - *              output  segment - 0xFFFF
>> - *                      offset  - 0xF13E
>> +/**
>> + * @brief Retreives real mode pointer elements {segmnet, offset} from
>> + * physical address.
>> + *
>> + * i386_Physical_to_real
>> + * Function returns the highest segment (base) address possible.
>> + * Example:    input   address - 0x4B3A2
>> + *             output  segment - 0x4B3A
>> + *                     offset  - 0x2
>> + *             input   address - 0x10F12E
>> + *             output  segment - 0xFFFF
>> + *                     offset  - 0xF13E
>>    *
>> - *  return  0 address not convertible, must be less than 0x10FFEF
>> - *          1 segment and offset extracted
>> + * @param[in]  address address to be converted, must be less than 0x10FFEF
>> + * @param[out] segment segment computed from \p address
>> + * @param[out] offset offset computed from \p address
>> + * @retval  0 address not convertible
>> + * @retval  1 segment and offset extracted
>>    */
>>   int i386_Physical_to_real(
>>     void *address,
>> --
>> 1.9.1
>>
>>
>> _______________________________________________
>> devel mailing list
>> devel at rtems.org
>> http://lists.rtems.org/mailman/listinfo/devel



More information about the devel mailing list