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