From f1294e4a56b71a58c4f054fee14e537d7aca2d52 Mon Sep 17 00:00:00 2001 From: klu2 Date: Sun, 1 Mar 2009 07:12:53 +0000 Subject: Refine the comments for BiosVideo thunk driver. git-svn-id: https://edk2.svn.sourceforge.net/svnroot/edk2/trunk/edk2@7738 6f19259b-4bc3-4df7-8a09-765794883524 --- DuetPkg/BiosVideoThunkDxe/BiosVideo.h | 396 ++++++++++++++-------------------- 1 file changed, 166 insertions(+), 230 deletions(-) (limited to 'DuetPkg/BiosVideoThunkDxe/BiosVideo.h') diff --git a/DuetPkg/BiosVideoThunkDxe/BiosVideo.h b/DuetPkg/BiosVideoThunkDxe/BiosVideo.h index c8a3f3c92d..08053478f8 100644 --- a/DuetPkg/BiosVideoThunkDxe/BiosVideo.h +++ b/DuetPkg/BiosVideoThunkDxe/BiosVideo.h @@ -1,4 +1,4 @@ -/*++ +/** @file Copyright (c) 2006 - 2007, Intel Corporation All rights reserved. This program and the accompanying materials @@ -9,14 +9,7 @@ http://opensource.org/licenses/bsd-license.php THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. -Module Name: - - UefiBiosVideo.h - -Abstract: - -Revision History ---*/ +**/ #ifndef _BIOS_GRAPHICS_OUTPUT_H #define _BIOS_GRAPHICS_OUTPUT_H @@ -88,11 +81,12 @@ typedef struct { EFI_HANDLE Handle; // - // Consumed Protocols + // Consumed Protocols inherited from parent controller. // EFI_PCI_IO_PROTOCOL *PciIo; EFI_LEGACY_8259_PROTOCOL *Legacy8259; - + THUNK_CONTEXT *ThunkContext; + // // Produced Protocols // @@ -106,7 +100,6 @@ typedef struct { // BOOLEAN VgaCompatible; BOOLEAN ProduceGraphicsOutput; - EFI_EVENT ExitBootServicesEvent; // // Graphics Output Protocol related fields @@ -150,6 +143,17 @@ extern EFI_COMPONENT_NAME2_PROTOCOL gBiosVideoComponentName2; // // Driver Binding Protocol functions // +/** + Test to see if Bios Video could be supported on the Controller. + + @param This Pointer to driver binding protocol + @param Controller Controller handle to connect + @param RemainingDevicePath A pointer to the remaining portion of a device path + + @retval EFI_SUCCESS This driver supports this device. + @retval other This driver does not support this device. + +**/ EFI_STATUS EFIAPI BiosVideoDriverBindingSupported ( @@ -157,25 +161,18 @@ BiosVideoDriverBindingSupported ( IN EFI_HANDLE Controller, IN EFI_DEVICE_PATH_PROTOCOL *RemainingDevicePath ) -/*++ - -Routine Description: - - GC_TODO: Add function description - -Arguments: - - This - GC_TODO: add argument description - Controller - GC_TODO: add argument description - RemainingDevicePath - GC_TODO: add argument description +; -Returns: +/** + Install Graphics Output Protocol onto VGA device handles - GC_TODO: add return values + @param This Pointer to driver binding protocol + @param Controller Controller handle to connect + @param RemainingDevicePath A pointer to the remaining portion of a device path ---*/ -; + @return EFI_STATUS +**/ EFI_STATUS EFIAPI BiosVideoDriverBindingStart ( @@ -183,25 +180,21 @@ BiosVideoDriverBindingStart ( IN EFI_HANDLE Controller, IN EFI_DEVICE_PATH_PROTOCOL *RemainingDevicePath ) -/*++ - -Routine Description: - - GC_TODO: Add function description - -Arguments: - - This - GC_TODO: add argument description - Controller - GC_TODO: add argument description - RemainingDevicePath - GC_TODO: add argument description +; -Returns: +/** + Stop this driver on Controller - GC_TODO: add return values + @param This Protocol instance pointer. + @param Controller Handle of device to stop driver on + @param NumberOfChildren Number of Handles in ChildHandleBuffer. If number of + children is zero stop the entire bus driver. + @param ChildHandleBuffer List of Child Handles to Stop. ---*/ -; + @retval EFI_SUCCESS This driver is removed Controller. + @retval other This driver was not removed from this device. +**/ EFI_STATUS EFIAPI BiosVideoDriverBindingStop ( @@ -210,120 +203,70 @@ BiosVideoDriverBindingStop ( IN UINTN NumberOfChildren, IN EFI_HANDLE *ChildHandleBuffer ) -/*++ - -Routine Description: - - GC_TODO: Add function description - -Arguments: - - This - GC_TODO: add argument description - Controller - GC_TODO: add argument description - NumberOfChildren - GC_TODO: add argument description - ChildHandleBuffer - GC_TODO: add argument description - -Returns: - - GC_TODO: add return values - ---*/ ; // // Private worker functions // +/** + Check for VBE device + + @param BiosVideoPrivate - Pointer to BIOS_VIDEO_DEV structure + + @retval EFI_SUCCESS VBE device found + +**/ EFI_STATUS BiosVideoCheckForVbe ( BIOS_VIDEO_DEV *BiosVideoPrivate ) -/*++ - -Routine Description: - - GC_TODO: Add function description - -Arguments: - - BiosVideoPrivate - GC_TODO: add argument description +; -Returns: +/** + Check for VGA device - GC_TODO: add return values + @param BiosVideoPrivate - Pointer to BIOS_VIDEO_DEV structure ---*/ -; + @retval EFI_SUCCESS Standard VGA device found +**/ EFI_STATUS BiosVideoCheckForVga ( BIOS_VIDEO_DEV *BiosVideoPrivate ) -/*++ - -Routine Description: - - GC_TODO: Add function description - -Arguments: - - BiosVideoPrivate - GC_TODO: add argument description - -Returns: - - GC_TODO: add return values - ---*/ ; -STATIC -EFI_STATUS -DeRegisterVideoChildHandle ( - EFI_DRIVER_BINDING_PROTOCOL *This, - EFI_HANDLE Controller, - EFI_HANDLE Handle - ) -/*++ - -Routine Description: - - Deregister an video child handle and free resources +/** + Collect the resource from destroyed bios video device. -Arguments: - - This - Protocol instance pointer. - Controller - Video controller handle - Handle - Video child handle - -Returns: - - EFI_STATUS - ---*/ -; + @param BiosVideoPrivate Video child device private data structure +**/ VOID BiosVideoDeviceReleaseResource ( BIOS_VIDEO_DEV *BiosVideoChildPrivate ) -/*++ -Routing Description: +; - Release resources of a video child device before stopping it. +// +// BIOS Graphics Output Protocol functions +// +/** -Arguments: + Graphics Output protocol interface to get video mode - BiosVideoChildPrivate - Video child device private data structure -Returns: + @param This - Protocol instance pointer. + @param ModeNumber - The mode number to return information on. + @param SizeOfInfo - A pointer to the size, in bytes, of the Info buffer. + @param Info - Caller allocated buffer that returns information about ModeNumber. - NONE - ----*/ -; + @return EFI_SUCCESS - Mode information returned. + EFI_DEVICE_ERROR - A hardware error occurred trying to retrieve the video mode. + EFI_NOT_STARTED - Video display is not initialized. Call SetMode () + EFI_INVALID_PARAMETER - One of the input args was NULL. -// -// BIOS Graphics Output Protocol functions -// +**/ EFI_STATUS EFIAPI BiosVideoGraphicsOutputQueryMode ( @@ -332,52 +275,52 @@ BiosVideoGraphicsOutputQueryMode ( OUT UINTN *SizeOfInfo, OUT EFI_GRAPHICS_OUTPUT_MODE_INFORMATION **Info ) -/*++ +; -Routine Description: +/** - Graphics Output protocol interface to get video mode + Graphics Output protocol interface to set video mode - Arguments: - This - Protocol instance pointer. - ModeNumber - The mode number to return information on. - Info - Caller allocated buffer that returns information about ModeNumber. - SizeOfInfo - A pointer to the size, in bytes, of the Info buffer. - Returns: - EFI_SUCCESS - Mode information returned. - EFI_BUFFER_TOO_SMALL - The Info buffer was too small. - EFI_DEVICE_ERROR - A hardware error occurred trying to retrieve the video mode. - EFI_NOT_STARTED - Video display is not initialized. Call SetMode () - EFI_INVALID_PARAMETER - One of the input args was NULL. + @param This - Protocol instance pointer. + @param ModeNumber - The mode number to be set. ---*/ -; + @return EFI_SUCCESS - Graphics mode was changed. + EFI_DEVICE_ERROR - The device had an error and could not complete the request. + EFI_UNSUPPORTED - ModeNumber is not supported by this device. +**/ EFI_STATUS EFIAPI BiosVideoGraphicsOutputSetMode ( IN EFI_GRAPHICS_OUTPUT_PROTOCOL * This, IN UINT32 ModeNumber ) -/*++ - -Routine Description: +; - Graphics Output protocol interface to set video mode +/** - Arguments: - This - Protocol instance pointer. - ModeNumber - The mode number to be set. + Graphics Output protocol instance to block transfer for VBE device - Returns: - EFI_SUCCESS - Graphics mode was changed. - EFI_DEVICE_ERROR - The device had an error and could not complete the request. - EFI_UNSUPPORTED - ModeNumber is not supported by this device. - ---*/ -; + @param This - Pointer to Graphics Output protocol instance + @param BltBuffer - The data to transfer to screen + @param BltOperation - The operation to perform + @param SourceX - The X coordinate of the source for BltOperation + @param SourceY - The Y coordinate of the source for BltOperation + @param DestinationX - The X coordinate of the destination for BltOperation + @param DestinationY - The Y coordinate of the destination for BltOperation + @param Width - The width of a rectangle in the blt rectangle in pixels + @param Height - The height of a rectangle in the blt rectangle in pixels + @param Delta - Not used for EfiBltVideoFill and EfiBltVideoToVideo operation. + If a Delta of 0 is used, the entire BltBuffer will be operated on. + If a subrectangle of the BltBuffer is used, then Delta represents + the number of bytes in a row of the BltBuffer. + + @return EFI_INVALID_PARAMETER - Invalid parameter passed in + EFI_SUCCESS - Blt operation success + +**/ EFI_STATUS EFIAPI BiosVideoGraphicsOutputVbeBlt ( @@ -392,36 +335,29 @@ BiosVideoGraphicsOutputVbeBlt ( IN UINTN Height, IN UINTN Delta ) -/*++ - -Routine Description: - - Graphics Output protocol instance to block transfer for VBE device - -Arguments: - - This - Pointer to Graphics Output protocol instance - BltBuffer - The data to transfer to screen - BltOperation - The operation to perform - SourceX - The X coordinate of the source for BltOperation - SourceY - The Y coordinate of the source for BltOperation - DestinationX - The X coordinate of the destination for BltOperation - DestinationY - The Y coordinate of the destination for BltOperation - Width - The width of a rectangle in the blt rectangle in pixels - Height - The height of a rectangle in the blt rectangle in pixels - Delta - Not used for EfiBltVideoFill and EfiBltVideoToVideo operation. - If a Delta of 0 is used, the entire BltBuffer will be operated on. - If a subrectangle of the BltBuffer is used, then Delta represents - the number of bytes in a row of the BltBuffer. - -Returns: - - EFI_INVALID_PARAMETER - Invalid parameter passed in - EFI_SUCCESS - Blt operation success - ---*/ ; +/** + Grahpics Output protocol instance to block transfer for VGA device + + @param This Pointer to Grahpics Output protocol instance + @param BltBuffer The data to transfer to screen + @param BltOperation The operation to perform + @param SourceX The X coordinate of the source for BltOperation + @param SourceY The Y coordinate of the source for BltOperation + @param DestinationX The X coordinate of the destination for BltOperation + @param DestinationY The Y coordinate of the destination for BltOperation + @param Width The width of a rectangle in the blt rectangle in pixels + @param Height The height of a rectangle in the blt rectangle in pixels + @param Delta Not used for EfiBltVideoFill and EfiBltVideoToVideo operation. + If a Delta of 0 is used, the entire BltBuffer will be operated on. + If a subrectangle of the BltBuffer is used, then Delta represents + the number of bytes in a row of the BltBuffer. + + @retval EFI_INVALID_PARAMETER Invalid parameter passed in + @retval EFI_SUCCESS Blt operation success + +**/ EFI_STATUS EFIAPI BiosVideoGraphicsOutputVgaBlt ( @@ -436,65 +372,37 @@ BiosVideoGraphicsOutputVgaBlt ( IN UINTN Height, IN UINTN Delta ) -/*++ - -Routine Description: - - Grahpics Output protocol instance to block transfer for VGA device - -Arguments: - - This - Pointer to Grahpics Output protocol instance - BltBuffer - The data to transfer to screen - BltOperation - The operation to perform - SourceX - The X coordinate of the source for BltOperation - SourceY - The Y coordinate of the source for BltOperation - DestinationX - The X coordinate of the destination for BltOperation - DestinationY - The Y coordinate of the destination for BltOperation - Width - The width of a rectangle in the blt rectangle in pixels - Height - The height of a rectangle in the blt rectangle in pixels - Delta - Not used for EfiBltVideoFill and EfiBltVideoToVideo operation. - If a Delta of 0 is used, the entire BltBuffer will be operated on. - If a subrectangle of the BltBuffer is used, then Delta represents - the number of bytes in a row of the BltBuffer. - -Returns: - - EFI_INVALID_PARAMETER - Invalid parameter passed in - EFI_SUCCESS - Blt operation success - ---*/ ; // // BIOS VGA Mini Port Protocol functions // +/** + VgaMiniPort protocol interface to set mode + + @param This Pointer to VgaMiniPort protocol instance + @param ModeNumber The index of the mode + + @retval EFI_UNSUPPORTED The requested mode is not supported + @retval EFI_SUCCESS The requested mode is set successfully + +**/ EFI_STATUS EFIAPI BiosVideoVgaMiniPortSetMode ( IN EFI_VGA_MINI_PORT_PROTOCOL *This, IN UINTN ModeNumber ) -/*++ - -Routine Description: - - VgaMiniPort protocol interface to set mode - -Arguments: - - This - Pointer to VgaMiniPort protocol instance - ModeNumber - The index of the mode - -Returns: - - EFI_UNSUPPORTED - The requested mode is not supported - EFI_SUCCESS - The requested mode is set successfully - ---*/ ; +/** + Judge whether this device is VGA device. + + @param PciIo Parent PciIo protocol instance pointer + @retval TRUE Is vga device + @retval FALSE Is no vga device +**/ BOOLEAN BiosVideoIsVga ( IN EFI_PCI_IO_PROTOCOL *PciIo @@ -543,16 +451,44 @@ BiosVideoIsVga ( #define VGA_GRAPHICS_CONTROLLER_BIT_MASK_REGISTER 0x08 +/** + Initialize legacy environment for BIOS INI caller. + + @param ThunkContext the instance pointer of THUNK_CONTEXT +**/ VOID InitializeBiosIntCaller ( - IN BIOS_VIDEO_DEV *BiosDev + THUNK_CONTEXT *ThunkContext ); +/** + Initialize interrupt redirection code and entries, because + IDT Vectors 0x68-0x6f must be redirected to IDT Vectors 0x08-0x0f. + Or the interrupt will lost when we do thunk. + NOTE: We do not reset 8259 vector base, because it will cause pending + interrupt lost. + + @param Legacy8259 Instance pointer for EFI_LEGACY_8259_PROTOCOL. + +**/ VOID InitializeInterruptRedirection ( - IN BIOS_VIDEO_DEV *BiosDev + IN EFI_LEGACY_8259_PROTOCOL *Legacy8259 ); +/** + Thunk to 16-bit real mode and execute a software interrupt with a vector + of BiosInt. Regs will contain the 16-bit register context on entry and + exit. + + @param This Protocol instance pointer. + @param BiosInt Processor interrupt vector to invoke + @param Reg Register contexted passed into (and returned) from thunk to 16-bit mode + + @retval TRUE Thunk completed, and there were no BIOS errors in the target code. + See Regs for status. + @retval FALSE There was a BIOS erro in the target code. +**/ BOOLEAN EFIAPI LegacyBiosInt86 ( -- cgit v1.2.3