[PATCH 2/2] i386: doxygen and comments related to VESA real mode framebuffer
Gedare Bloom
gedare at rtems.org
Wed Dec 3 16:56:53 UTC 2014
On Wed, Dec 3, 2014 at 11:29 AM, Jan Dolezal <dolezj21 at fel.cvut.cz> wrote:
> 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?
>
I prefer #2.
-Gedare
>
>>
>> -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