On Wed, Dec 3, 2014 at 11:29 AM, Jan Dolezal <dolez...@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 <dolez...@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 ( dolez...@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.seve...@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 ( dolez...@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.seve...@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 (dolez...@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 (dolez...@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 (dolez...@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 (dolez...@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 (vale...@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 ( dolez...@fel.cvut.cz ) >>> + * @brief Real mode interrupt call implementation >>> + */ >>> + >>> +/* >>> + * Copyright (c) 2014 - CTU in Prague >>> + * Jan Doležal ( dolez...@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 (dolez...@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@rtems.org >>> http://lists.rtems.org/mailman/listinfo/devel _______________________________________________ devel mailing list devel@rtems.org http://lists.rtems.org/mailman/listinfo/devel
