--- 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