--- 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 | 77 +-- c/src/lib/libbsp/i386/pc386/include/tblsizes.h | 1 - c/src/lib/libbsp/i386/pc386/include/vbe3.h | 694 +++++++++++++-------- .../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 | 65 +- cpukit/score/cpu/i386/cpu_asm.S | 4 +- cpukit/score/cpu/i386/rtems/score/i386.h | 39 +- 10 files changed, 685 insertions(+), 416 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 e5acbd5..d6fd174 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 @@ 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[in,out] searched_resolution element filled with searched resolution + * or/and bpp; mode_number is filled in if appropriate mode found + * @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 fe6d7da..1120296 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 b82d3e7..d8bfd1b 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[out] info_block pointer to the struct to be filled with + * controller information + * @param[in] 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_vbe_info_block *info_block, @@ -51,13 +50,14 @@ 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[out] info_block pointer to the struct to be filled with + * mode information + * @param[in] 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_mode_info_block *info_block, @@ -65,13 +65,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[in] mode_number number of mode to be set + * @param[in] 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 +79,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[out] 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[in] controller_unit_number + * @param[out] seconds_to_transfer_EDID_block approximate time to transfer one + * EDID block rounded up to seconds + * @param[out] DDC_level_supported 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 +108,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 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 + * @param[in] controller_unit_number + * @param[in] EDID_block_number block no. to be read from the display + * @param[out] buffer place to store block fetched from the display + * @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 811fc3d..06f614f 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. * @@ -37,343 +37,484 @@ extern "C" { /* VESA BIOS EXTENSION (VBE) Core functions Standard Version: 3.0 Date: September 16, 1998 */ -/* VBE RETURN STATUS */ -/* AL == 4Fh: Function is supported */ -/* AL != 4Fh: Function is not supported */ +/** AL == 4Fh: Function is supported \n + * AL != 4Fh: Function is not supported */ #define VBE_functionSupported 0x4F -/* AH == 00h: Function call successful */ +/** AH == 00h: Function call successful */ #define VBE_callSuccessful 0x00 -/* AH == 01h: Function call failed */ +/** AH == 01h: Function call failed */ #define VBE_callFailed 0x01 -/* AH == 02h: Function is not supported in the current hardware configuration */ +/** AH == 02h: Function is not supported in the current hardware configuration*/ #define VBE_notSupportedInCurHWConf 0x02 -/* AH == 03h: Function call invalid in current video mode */ +/** AH == 03h: Function call invalid in current video mode */ #define VBE_callInvalid 0x03 /* VBE Mode Numbers */ -/* D0-D8 = Mode number */ +/** D0-D8 = Mode number */ #define VBE_modeNumberMask 0x01FF #define VBE_modeNumberShift 0x00 -/* If D8 == 0, this is not a VESA defined VBE mode */ +/** If D8 == 0, this is not a VESA defined VBE mode \n + If D8 == 1, this is a VESA defined VBE mode */ #define VBE_VESAmodeMask 0x0100 -/* If D8 == 1, this is a VESA defined VBE mode */ -/* D9-D12 = Reserved by VESA for future expansion (= 0) */ #define VBE_VESAmodeShift 0x08 -/* If D11 == 0, Use current BIOS default refresh rate */ +/* D9-D10 = Reserved by VESA for future expansion (= 0) */ +/** If D11 == 0, Use current BIOS default refresh rate \n + If D11 == 1, Use user specified CRTC values for refresh rate */ #define VBE_refreshRateCtrlMask 0x0800 -/* If D11 == 1, Use user specified CRTC values for refresh rate */ -/* D12-13 = Reserved for VBE/AF (must be 0) */ #define VBE_refreshRateCtrlShift 0x0B -/* If D14 == 0, Use Banked/Windowed Frame Buffer */ +/* D12-13 = Reserved for VBE/AF (must be 0) */ +/** If D14 == 0, Use Banked/Windowed Frame Buffer \n + If D14 == 1, Use Linear/Flat Frame Buffer */ #define VBE_linearFlatFrameBufMask 0x4000 -/* If D14 == 1, Use Linear/Flat Frame Buffer */ #define VBE_linearFlatFrameBufShift 0x0E -/* If D15 == 0, Clear display memory */ +/** If D15 == 0, Clear display memory \n + If D15 == 1, Preserve display memory */ #define VBE_preserveDispMemMask 0x8000 -/* If D15 == 1, Preserve display memory */ #define VBE_preserveDispMemShift 0x0F /* Graphics modes */ -/* 15-bit mode, Resolution: 640x400, Colors: 256 */ +/** 15-bit mode, Resolution: 640x400, Colors: 256 */ #define VBE_R640x400C256 0x100 -/* 15-bit mode, Resolution: 640x480, Colors: 256 */ +/** 15-bit mode, Resolution: 640x480, Colors: 256 */ #define VBE_R640x480C256 0x101 -/* 15-bit mode, Resolution: 800x600, Colors: 16 */ +/** 15-bit mode, Resolution: 800x600, Colors: 16 */ #define VBE_R800x600C16 0x102 -/* 7-bit mode, Resolution: 800x600, Colors: 16 */ +/** 7-bit mode, Resolution: 800x600, Colors: 16 */ #define VBE_b7R800x600C16 0x6A -/* 15-bit mode, Resolution: 800x600, Colors: 256 */ +/** 15-bit mode, Resolution: 800x600, Colors: 256 */ #define VBE_R800x600C256 0x103 -/* 15-bit mode, Resolution: 1024x768, Colors: 16 */ +/** 15-bit mode, Resolution: 1024x768, Colors: 16 */ #define VBE_R1024x768C16 0x104 -/* 15-bit mode, Resolution: 1024x768, Colors: 256 */ +/** 15-bit mode, Resolution: 1024x768, Colors: 256 */ #define VBE_R1024x768C256 0x105 -/* 15-bit mode, Resolution: 1280x1024, Colors: 16 */ +/** 15-bit mode, Resolution: 1280x1024, Colors: 16 */ #define VBE_R1280x1024C16 0x106 -/* 15-bit mode, Resolution: 1280x1024, Colors: 256 */ +/** 15-bit mode, Resolution: 1280x1024, Colors: 256 */ #define VBE_R1280x1024C256 0x107 -/* 15-bit mode, Resolution: 320x200, Colors: 32K (1:5:5:5) */ +/** 15-bit mode, Resolution: 320x200, Colors: 32K (1:5:5:5) */ #define VBE_R320x200C32K 0x10D -/* 15-bit mode, Resolution: 320x200, Colors: 64K (5:6:5) */ +/** 15-bit mode, Resolution: 320x200, Colors: 64K (5:6:5) */ #define VBE_R320x200C64K 0x10E -/* 15-bit mode, Resolution: 320x200, Colors: 16.8M (8:8:8) */ +/** 15-bit mode, Resolution: 320x200, Colors: 16.8M (8:8:8) */ #define VBE_R320x200C17M 0x10F -/* 15-bit mode, Resolution: 640x480, Colors: 32K (1:5:5:5) */ +/** 15-bit mode, Resolution: 640x480, Colors: 32K (1:5:5:5) */ #define VBE_R640x480C32K 0x110 -/* 15-bit mode, Resolution: 640x480, Colors: 64K (5:6:5) */ +/** 15-bit mode, Resolution: 640x480, Colors: 64K (5:6:5) */ #define VBE_R640x480C64K 0x111 -/* 15-bit mode, Resolution: 640x480, Colors: 16.8M (8:8:8) */ +/** 15-bit mode, Resolution: 640x480, Colors: 16.8M (8:8:8) */ #define VBE_R640x480C17M 0x112 -/* 15-bit mode, Resolution: 800x600, Colors: 32K (1:5:5:5) */ +/** 15-bit mode, Resolution: 800x600, Colors: 32K (1:5:5:5) */ #define VBE_R800x600C32K 0x113 -/* 15-bit mode, Resolution: 800x600, Colors: 64K (5:6:5) */ +/** 15-bit mode, Resolution: 800x600, Colors: 64K (5:6:5) */ #define VBE_R800x600C64K 0x114 -/* 15-bit mode, Resolution: 800x600, Colors: 16.8M (8:8:8) */ +/** 15-bit mode, Resolution: 800x600, Colors: 16.8M (8:8:8) */ #define VBE_R800x600C17M 0x115 -/* 15-bit mode, Resolution: 1024x768, Colors: 32K (1:5:5:5) */ +/** 15-bit mode, Resolution: 1024x768, Colors: 32K (1:5:5:5) */ #define VBE_R1024x768C32K 0x116 -/* 15-bit mode, Resolution: 1024x768, Colors: 64K (5:6:5) */ +/** 15-bit mode, Resolution: 1024x768, Colors: 64K (5:6:5) */ #define VBE_R1024x768C64K 0x117 -/* 15-bit mode, Resolution: 1024x768, Colors: 16.8M (8:8:8) */ +/** 15-bit mode, Resolution: 1024x768, Colors: 16.8M (8:8:8) */ #define VBE_R1024x768C17M 0x118 -/* 15-bit mode, Resolution: 1280x1024, Colors: 32K (1:5:5:5) */ +/** 15-bit mode, Resolution: 1280x1024, Colors: 32K (1:5:5:5) */ #define VBE_R1280x1024C32K 0x119 -/* 15-bit mode, Resolution: 1280x1024, Colors: 64K (5:6:5) */ +/** 15-bit mode, Resolution: 1280x1024, Colors: 64K (5:6:5) */ #define VBE_R1280x1024C64K 0x11A -/* 15-bit mode, Resolution: 1280x1024, Colors: 16.8M (8:8:8) */ +/** 15-bit mode, Resolution: 1280x1024, Colors: 16.8M (8:8:8) */ #define VBE_R1280x1024C17M 0x11B #define VBE_SpecialMode 0x81FF /* Text modes */ -#define VBE_C80R60 0x108 /* 15-bit mode, Columns: 80, Rows: 60 */ -#define VBE_C132R25 0x109 /* 15-bit mode, Columns: 132, Rows: 25 */ -#define VBE_C132R43 0x10A /* 15-bit mode, Columns: 132, Rows: 43 */ -#define VBE_C132R50 0x10B /* 15-bit mode, Columns: 132, Rows: 50 */ -#define VBE_C132R60 0x10C /* 15-bit mode, Columns: 132, Rows: 60 */ +#define VBE_C80R60 0x108 /**< 15-bit mode, Columns: 80, Rows: 60 */ +#define VBE_C132R25 0x109 /**< 15-bit mode, Columns: 132, Rows: 25 */ +#define VBE_C132R43 0x10A /**< 15-bit mode, Columns: 132, Rows: 43 */ +#define VBE_C132R50 0x10B /**< 15-bit mode, Columns: 132, Rows: 50 */ +#define VBE_C132R60 0x10C /**< 15-bit mode, Columns: 132, Rows: 60 */ /* VBE function numbers - passed in AX register */ -#define VBE_RetVBEConInf 0x4F00 /* Return VBE Controller Information */ -#define VBE_RetVBEModInf 0x4F01 /* Return VBE Mode Information */ -#define VBE_SetVBEMod 0x4F02 /* Set VBE Mode */ -#define VBE_RetCurVBEMod 0x4F03 /* Return Current VBE Mode */ -#define VBE_SavResSta 0x4F04 /* Save/Restore State */ -#define VBE_DisWinCon 0x4F05 /* Display Window Control */ -#define VBE_SetGetLogScaLinLen 0x4F06 /* Set/Get Logical Scan Line Length */ -#define VBE_SetGetDisSta 0x4F07 /* Set/Get Display Start */ -#define VBE_SetGetDACPalFor 0x4F08 /* Set/Get DAC Palette Format */ -#define VBE_SetGetPalDat 0x4F09 /* Set/Get Palette Data */ -#define VBE_RetVBEProModInt 0x4F0A /* Return VBE Protected Mode Interface */ -#define VBE_GetSetpixclo 0x4F0B /* Get/Set pixel clock */ -#define VBE_PowManExt 0x4F10 /* Power Management Extensions (PM) */ -#define VBE_FlaPanIntExt 0x4F11 /* Flat Panel Interface Extensions (FP) */ -#define VBE_AudIntExt 0x4F13 /* Audio Interface Extensions (AI) */ -#define VBE_OEMExt 0x4F14 /* OEM Extensions */ -#define VBE_DisDatCha 0x4F15 /* Display Data Channel (DDC), - Serial Control Interface (SCI) */ +/** VBE function - Return VBE Controller Information */ +#define VBE_RetVBEConInf 0x4F00 +/** VBE function - Return VBE Mode Information */ +#define VBE_RetVBEModInf 0x4F01 +/** VBE function - Set VBE Mode */ +#define VBE_SetVBEMod 0x4F02 +/** VBE function - Return Current VBE Mode */ +#define VBE_RetCurVBEMod 0x4F03 +/** VBE function - Save/Restore State */ +#define VBE_SavResSta 0x4F04 +/** VBE function - Display Window Control */ +#define VBE_DisWinCon 0x4F05 +/** VBE function - Set/Get Logical Scan Line Length */ +#define VBE_SetGetLogScaLinLen 0x4F06 +/** VBE function - Set/Get Display Start */ +#define VBE_SetGetDisSta 0x4F07 +/** VBE function - Set/Get DAC Palette Format */ +#define VBE_SetGetDACPalFor 0x4F08 +/** VBE function - Set/Get Palette Data */ +#define VBE_SetGetPalDat 0x4F09 +/** VBE function - Return VBE Protected Mode Interface */ +#define VBE_RetVBEProModInt 0x4F0A +/** VBE function - Get/Set pixel clock */ +#define VBE_GetSetpixclo 0x4F0B +/** VBE function - Power Management Extensions (PM) */ +#define VBE_PowManExt 0x4F10 +/** VBE function - Flat Panel Interface Extensions (FP) */ +#define VBE_FlaPanIntExt 0x4F11 +/** VBE function - Audio Interface Extensions (AI) */ +#define VBE_AudIntExt 0x4F13 +/** VBE function - OEM Extensions */ +#define VBE_OEMExt 0x4F14 +/** VBE function - Display Data Channel (DDC), Serial Control Interface (SCI) */ +#define VBE_DisDatCha 0x4F15 /* VBE subfunction numbers - passed in BL register */ -#define VBE_RetVBESupSpeInf 0x00 /* Return VBE Supplemental - Specification Information */ +#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; } RTEMS_COMPILER_PACKED_ATTRIBUTE VBE_far_pointer; +/** + * @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. Sum over all structure bytes gives 0. */ + uint8_t Checksum; } RTEMS_COMPILER_PACKED_ATTRIBUTE VBE_protected_mode_info_block; -/* General VBE signature */ +/** General VBE signature */ #define VBE_SIGNATURE "VESA" -/* Signature for VBE 2.0 and higher */ +/** Signature for VBE 2.0 and higher */ #define VBE20plus_SIGNATURE "VBE2" -/* for STUB see VBE CORE FUNCTIONS VERSION 3.0 - Appendix 1 */ -#define VBE_END_OF_VideoModeList 0xFFFF +/** for STUB see VBE CORE FUNCTIONS VERSION 3.0 - Appendix 1 */ #define VBE_STUB_VideoModeList 0xFFFF +#define VBE_END_OF_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; + /** VBE_far_pointer to OEM String */ + uint8_t *OemStringPtr; + /** Capabilities of graphics controller */ + uint8_t Capabilities[4]; + /** VBE_far_pointer 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; + /** VBE_far_pointer to Vendor Name String */ + uint8_t *OemVendorNamePtr; + /** VBE_far_pointer to Product Name String */ + uint8_t *OemProductNamePtr; + /** VBE_far_pointer 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]; } RTEMS_COMPILER_PACKED_ATTRIBUTE VBE_vbe_info_block; +/** + * @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 VBE_mode_info_block */ + uint8_t Reserved3[189]; } RTEMS_COMPILER_PACKED_ATTRIBUTE VBE_mode_info_block; +/** + * @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 VBE_mode_info_block */ + uint8_t Reserved[40]; } RTEMS_COMPILER_PACKED_ATTRIBUTE VBE_CRTC_info_block; +/** + * @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; } RTEMS_COMPILER_PACKED_ATTRIBUTE VBE_palette_entry; +/** + * @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; + /** VBE_far_pointer to Vendor Name String */ + uint8_t *OemVendorNamePtr; + /** VBE_far_pointer to Product Name String */ + uint8_t *OemProductNamePtr; + /** VBE_far_pointer to Product Revision String */ + uint8_t *OemProductRevPtr; + /** VBE_far_pointer to OEM String */ + uint8_t *OemStringPtr; + /** Reserved for description strings and future expansion */ + uint8_t Reserved[221]; } RTEMS_COMPILER_PACKED_ATTRIBUTE VBE_supplemental_vbe_info_block; -/* VbeInfoBlock Capabilities */ -/* D0 = 0 DAC is fixed width, with 6 bits per primary color */ -/* = 1 DAC width is switchable to 8 bits per primary color */ +/* VBE_vbe_info_block Capabilities */ +/** VBE Info Block - Capabilities\n + D0 = 0 DAC is fixed width, with 6 bits per primary color \n + D0 = 1 DAC width is switchable to 8 bits per primary color */ #define VBE_DACswitchableMask 0x0001 -/* D1 = 0 Controller is VGA compatible */ -/* = 1 Controller is not VGA compatible */ +/** VBE Info Block - Capabilities\n + D1 = 0 Controller is VGA compatible \n + D1 = 1 Controller is not VGA compatible */ #define VBE_notVGAcompatibleMask 0x0002 -/* D2 = 0 Normal RAMDAC operation */ -/* = 1 When programming large blocks of information to the RAMDAC, +/** VBE Info Block - Capabilities\n + D2 = 0 Normal RAMDAC operation \n + D2 = 1 When programming large blocks of information to the RAMDAC, use the blank bit in Function 09h. */ #define VBE_specialRAMDACopMask 0x0004 -/* D3 = 0 No hardware stereoscopic signaling support */ -/* = 1 Hardware stereoscopic signaling supported by controller */ +/** VBE Info Block - Capabilities\n + D3 = 0 No hardware stereoscopic signaling support \n + D3 = 1 Hardware stereoscopic signaling supported by controller */ #define VBE_hwStereoscopicMask 0x0008 -/* D4 = 0 Stereo signaling supported via external VESA stereo connector */ -/* = 1 Stereo signaling supported via VESA EVC connector */ +/** VBE Info Block - Capabilities\n + D4 = 0 Stereo signaling supported via external VESA stereo connector \n + D4 = 1 Stereo signaling supported via VESA EVC connector */ #define VBE_supportEVCconnMask 0x0010 /* D5-31 = Reserved */ -/* ModeInfoBlock ModeAttributes */ -/* D0 = Mode supported by hardware configuration */ -/* 0 = Mode not supported in hardware */ -/* 1 = Mode supported in hardware */ +/* VBE_mode_info_block ModeAttributes */ +/** Mode Info Block - Mode Attributes\n + D0 = Mode supported by hardware configuration. + 0 = Mode not supported in hardware\n + 1 = Mode supported in hardware */ #define VBE_modSupInHWMask 0x0001 /* D1 = 1 (Reserved) */ -/* D2 = TTY Output functions supported by BIOS */ -/* 0 = TTY Output functions not supported by BIOS */ -/* 1 = TTY Output functions supported by BIOS */ +/** Mode Info Block - Mode Attributes\n + D2 = TTY Output functions supported by BIOS. + 0 = TTY Output functions not supported by BIOS\n + 1 = TTY Output functions supported by BIOS */ #define VBE_TTYOutSupByBIOSMask 0x0004 -/* D3 = Monochrome/color mode (see note below) */ -/* 0 = Monochrome mode */ -/* 1 = Color mode */ +/** Mode Info Block - Mode Attributes\n + D3 = Monochrome/color mode (see note below). + 0 = Monochrome mode\n + 1 = Color mode */ #define VBE_ColorModeMask 0x0008 -/* D4 = Mode type */ -/* 0 = Text mode */ -/* 1 = Graphics mode */ +/** Mode Info Block - Mode Attributes\n + D4 = Mode type. + 0 = Text mode\n + 1 = Graphics mode */ #define VBE_GraphicsModeMask 0x0010 -/* D5 = VGA compatible mode */ -/* 0 = Yes */ -/* 1 = No */ +/** Mode Info Block - Mode Attributes\n + D5 = VGA compatible mode. + 0 = Yes\n + 1 = No */ #define VBE_VGACompModeMask 0x0020 -/* D6 = VGA compatible windowed memory mode is available */ -/* 0 = Yes */ -/* 1 = No */ +/** Mode Info Block - Mode Attributes\n + D6 = VGA compatible windowed memory mode is available. + 0 = Yes\n + 1 = No */ #define VBE_VGACompWinMemModeMask 0x0040 -/* D7 = Linear frame buffer mode is available */ -/* 0 = No */ -/* 1 = Yes */ +/** Mode Info Block - Mode Attributes\n + D7 = Linear frame buffer mode is available. + 0 = No\n + 1 = Yes */ #define VBE_LinFraBufModeAvaiMask 0x0080 -/* D8 = Double scan mode is available */ -/* 0 = No */ -/* 1 = Yes */ +/** Mode Info Block - Mode Attributes\n + D8 = Double scan mode is available. + 0 = No\n + 1 = Yes */ #define VBE_DblScnModeAvaiMask 0x0100 -/* D9 = Interlaced mode is available */ -/* 0 = No */ -/* 1 = Yes */ +/** Mode Info Block - Mode Attributes\n + D9 = Interlaced mode is available. + 0 = No\n + 1 = Yes */ #define VBE_InterlModeAvaiMask 0x0200 -/* D10 = Hardware triple buffering support */ -/* 0 = No */ -/* 1 = Yes */ +/** Mode Info Block - Mode Attributes\n + D10 = Hardware triple buffering support. + 0 = No\n + 1 = Yes */ #define VBE_HWTripBufSupMask 0x0400 -/* D11 = Hardware stereoscopic display support */ -/* 0 = No */ -/* 1 = Yes */ +/** Mode Info Block - Mode Attributes\n + D11 = Hardware stereoscopic display support. + 0 = No\n + 1 = Yes */ #define VBE_HWSterDispSupMask 0x0800 -/* D12 = Dual display start address support */ -/* 0 = No */ -/* 1 = Yes */ +/** Mode Info Block - Mode Attributes\n + D12 = Dual display start address support. + 0 = No\n + 1 = Yes */ #define VBE_DualDispStAdrSupMask 0x1000 /* D13-D15 = Reserved */ -/* ModeInfoBlock WinXAttributes */ -/* D0 = Relocatable window(s) supported */ -/* 0 = Single non-relocatable window only */ -/* 1 = Relocatable window(s) are supported */ +/* VBE_mode_info_block WinXAttributes */ +/** D0 = Relocatable window(s) supported. + 0 = Single non-relocatable window only\n + 1 = Relocatable window(s) are supported */ #define VBE_RelocWinSupMask 0x01 -/* D1 = Window readable */ -/* 0 = Window is not readable */ -/* 1 = Window is readable */ +/** D1 = Window readable. + 0 = Window is not readable\n + 1 = Window is readable */ #define VBE_WinReadableMask 0x02 -/* D2 = Window writeable */ -/* 0 = Window is not writeable */ -/* 1 = Window is writeable */ +/** D2 = Window writeable. + 0 = Window is not writeable\n + 1 = Window is writeable */ #define VBE_WinWritableMask 0x04 /* D3-D7 = Reserved */ -/* ModeInfoBlock MemoryModel */ +/* VBE_mode_info_block MemoryModel */ #define VBE_TextMode 0x00 #define VBE_CGAGraphics 0x01 #define VBE_HerculesGraphics 0x02 @@ -385,32 +526,36 @@ typedef struct { /* 0x08-0x0F Reserved, to be defined by VESA */ /* 0x10-0xFF To be defined by OEM */ -/* ModeInfoBlock DirectColorModeInfo */ -/* D0 = Color ramp is fixed/programmable */ -/* 0 = Color ramp is fixed */ -/* 1 = Color ramp is programmable */ +/* VBE_mode_info_block DirectColorModeInfo */ +/** D0 = Color ramp is fixed/programmable. + 0 = Color ramp is fixed\n + 1 = Color ramp is programmable */ #define VBE_ColRampProgMask 0x01 -/* D1 = Bits in Rsvd field are usable/reserved */ -/* 0 = Bits in Rsvd field are reserved */ -/* 1 = Bits in Rsvd field are usable by the application */ +/** D1 = Bits in Rsvd field are usable/reserved. + 0 = Bits in Rsvd field are reserved\n + 1 = Bits in Rsvd field are usable by the application */ #define VBE_RsvdBitsUsableMask 0x02 -/* CRTCInfoBlock Flags */ -/* D0 = Double Scan Mode Enable */ -/* 0 = Graphics mode is not double scanned */ -/* 1 = Graphics mode is double scanned */ +/* VBE_CRTC_info_block Flags */ +/** CRTC Info Block - Flags\n + D0 = Double Scan Mode Enable. + 0 = Graphics mode is not double scanned\n + 1 = Graphics mode is double scanned */ #define VBE_GrModeDblScanMask 0x01 -/* D1 = Interlaced Mode Enable */ -/* 0 = Graphics mode is non-interlaced */ -/* 1 = Graphics mode is interlaced */ +/** CRTC Info Block - Flags\n + D1 = Interlaced Mode Enable. + 0 = Graphics mode is non-interlaced\n + 1 = Graphics mode is interlaced */ #define VBE_GrModeInterlMask 0x02 -/* D2 = Horizontal sync polarity */ -/* 0 = Horizontal sync polarity is positive (+) */ -/* 1 = Horizontal sync polarity is negative (-) */ +/** CRTC Info Block - Flags\n + D2 = Horizontal sync polarity. + 0 = Horizontal sync polarity is positive (+)\n + 1 = Horizontal sync polarity is negative (-) */ #define VBE_HorSncPolNegMask 0x04 -/* D3 = Vertical sync polarity */ -/* 0 = Vertical sync polarity is positive (+) */ -/* 1 = Vertical sync polarity is negative (-) */ +/** CRTC Info Block - Flags\n + D3 = Vertical sync polarity. + 0 = Vertical sync polarity is positive (+)\n + 1 = Vertical sync polarity is negative (-) */ #define VBE_VerSncPolNegMask 0x08 @@ -418,17 +563,19 @@ typedef struct { Version: 1.1 November 18, 1999 */ /* VBE/DDC subfunction numbers - passed in BL register */ -#define VBEDDC_Capabilities 0x0 /* Report VBE/DDC Capabilities */ -#define VBEDDC_ReadEDID 0x1 /* Read EDID */ +/** VBE/DDC subfunction - Report VBE/DDC Capabilities */ +#define VBEDDC_Capabilities 0x0 +/** VBE/DDC subfunction - Read EDID */ +#define VBEDDC_ReadEDID 0x1 /* DDC Capabilities */ /* DDC level supported - returned in BL register */ -/* 0 - DDC1 not supported; 1 - DDC1 supported */ +/** 0 - DDC1 not supported; 1 - DDC1 supported */ #define VBEDDC_1SupportedMask 0x1 -/* 0 - DDC2 not supported; 1 - DDC2 supported */ +/** 0 - DDC2 not supported; 1 - DDC2 supported */ #define VBEDDC_2SupportedMask 0x2 -/* 0 - Screen not blanked during data transfer; - 1 - Screen blanked during data transfer */ +/** 0 - Screen not blanked during data transfer\n + 1 - Screen blanked during data transfer */ #define VBEDDC_scrBlnkDatTrMs 0x4 @@ -436,20 +583,31 @@ typedef struct { Version: 1.0 Revision: 2 Date: July 2, 1997 */ /* VBE/SCI subfunction numbers - passed in BL register */ -#define VBESCI_ReportCapabil 0x10 /* Report VBE/SCI Capabilities */ -#define VBESCI_BegSCLSDACtrl 0x11 /* Begin SCL/SDA control */ -#define VBESCI_EndSCLSDACtrl 0x12 /* End SCL/SDA control */ -#define VBESCI_WrtSCLClkLine 0x13 /* Write SCL clock line */ -#define VBESCI_WrtSDADatLine 0x14 /* Write SDA data line */ -#define VBESCI_RdySCLClkLine 0x15 /* Read SCL clock line */ -#define VBESCI_RdySDADatLine 0x16 /* Read SDA data line */ +/** VBE/SCI subfunction - Report VBE/SCI Capabilities */ +#define VBESCI_ReportCapabil 0x10 +/** VBE/SCI subfunction - Begin SCL/SDA control */ +#define VBESCI_BegSCLSDACtrl 0x11 +/** VBE/SCI subfunction - End SCL/SDA control */ +#define VBESCI_EndSCLSDACtrl 0x12 +/** VBE/SCI subfunction - Write SCL clock line */ +#define VBESCI_WrtSCLClkLine 0x13 +/** VBE/SCI subfunction - Write SDA data line */ +#define VBESCI_WrtSDADatLine 0x14 +/** VBE/SCI subfunction - Read SCL clock line */ +#define VBESCI_RdySCLClkLine 0x15 +/** VBE/SCI subfunction - Read SDA data line */ +#define VBESCI_RdySDADatLine 0x16 /* SCI Capabilities */ /* I2C level supported - returned in BL register */ -#define VBESCI_capSCLwrtMask 0x1 /* Can write to SCL clock line */ -#define VBESCI_capSDAwrtMask 0x2 /* Can write to SDA data line */ -#define VBESCI_capSCLrdyMask 0x4 /* Can read from SCL clock line */ -#define VBESCI_capSDArdyMask 0x8 /* Can read from SDA data line */ +/** Can write to SCL clock line */ +#define VBESCI_capSCLwrtMask 0x1 +/** Can write to SDA data line */ +#define VBESCI_capSDAwrtMask 0x2 +/** Can read from SCL clock line */ +#define VBESCI_capSCLrdyMask 0x4 +/** Can read from SDA data line */ +#define VBESCI_capSDArdyMask 0x8 #ifdef __cplusplus 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..6836af3 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..0242e27 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 describes one entry of Global/Local 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[in] base 32-bit address to be set as descriptor's base + * @param[out] 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[in] limit 32-bit value representing number of limit bytes + * @param[out] sd descriptor being filled with \p limit */ extern void i386_fill_segment_desc_limit (uint32_t limit, segment_descriptors* sd); @@ -312,37 +318,40 @@ 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. + * + * Number of descriptors that can be returned depends on \a GDT_SIZE * * @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[in] segment_selector index to GDT table specifying descriptor to copy + * @param[out] struct_to_fill pointer to memory where will 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[in] 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 + * @param[in] gdt_entry pointer to entry from which base should be retrieved * @retval base address from GDT entry */ RTEMS_INLINE_ROUTINE void* i386_base_gdt_entry (segment_descriptors* gdt_entry) @@ -353,9 +362,9 @@ 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 + * @param[in] gdt_entry pointer to entry from which limit should be retrieved * @retval limit value in bytes from GDT entry */ extern uint32_t i386_limit_gdt_entry (segment_descriptors* 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
