123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906907908909910911912913914915916917918919920921922923924925926927928929930931932933934935936937938939940941942943944945946947948949950951952953954955956957958959960961962963964965966967968969970971972973974975976977978979980981982983984985986987988989990991992993994995996997998999100010011002100310041005100610071008100910101011101210131014101510161017101810191020102110221023102410251026102710281029103010311032103310341035103610371038103910401041104210431044104510461047104810491050105110521053105410551056105710581059106010611062106310641065106610671068106910701071107210731074107510761077107810791080108110821083108410851086108710881089109010911092109310941095109610971098109911001101110211031104110511061107110811091110111111121113111411151116111711181119112011211122112311241125112611271128112911301131113211331134113511361137113811391140114111421143114411451146114711481149115011511152115311541155115611571158115911601161116211631164116511661167 |
- /*++
- Copyright (c) 2013 Minoca Corp. All Rights Reserved
- Module Name:
- efisup.h
- Abstract:
- This header contains definitions for EFI support in the boot loader.
- Author:
- Evan Green 11-Feb-2014
- --*/
- //
- // ------------------------------------------------------------------- Includes
- //
- //
- // ---------------------------------------------------------------- Definitions
- //
- //
- // ------------------------------------------------------ Data Type Definitions
- //
- //
- // -------------------------------------------------------------------- Globals
- //
- //
- // Store pointers to the main EFI structures.
- //
- extern EFI_HANDLE BoEfiImageHandle;
- extern EFI_SYSTEM_TABLE *BoEfiSystemTable;
- extern EFI_BOOT_SERVICES *BoEfiBootServices;
- extern EFI_RUNTIME_SERVICES *BoEfiRuntimeServices;
- //
- // Define some needed protocol GUIDs.
- //
- extern EFI_GUID BoEfiLoadedImageProtocolGuid;
- extern EFI_GUID BoEfiBlockIoProtocolGuid;
- extern EFI_GUID BoEfiGraphicsOutputProtocolGuid;
- extern EFI_GUID BoEfiDevicePathProtocolGuid;
- extern EFI_GUID BoEfiRamDiskProtocolGuid;
- extern EFI_GUID BoEfiAcpiTableGuid;
- extern EFI_GUID BoEfiAcpi1TableGuid;
- extern EFI_GUID BoEfiSmbiosTableGuid;
- //
- // Store the allocation containing the memory descriptors for the memory map.
- // This is the first allocation to arrive and the last to go, as it contains
- // the list of other allocations to clean up.
- //
- extern EFI_PHYSICAL_ADDRESS BoEfiDescriptorAllocation;
- extern UINTN BoEfiDescriptorAllocationPageCount;
- //
- // -------------------------------------------------------- Function Prototypes
- //
- //
- // Define functions implemented by the application, callable by the boot
- // library.
- //
- EFI_STATUS
- BoEfiApplicationMain (
- EFI_HANDLE ImageHandle,
- EFI_SYSTEM_TABLE *SystemTable,
- PVOID TopOfStack,
- ULONG StackSize
- );
- /*++
- Routine Description:
- This routine is the entry point for the EFI Boot Application.
- Arguments:
- ImageHandle - Supplies a pointer to the image handle.
- SystemTable - Supplies a pointer to the EFI system table.
- TopOfStack - Supplies the top of the stack that has been set up for the
- loader.
- StackSize - Supplies the total size of the stack set up for the loader, in
- bytes.
- Return Value:
- EFI status code.
- --*/
- VOID
- BopEfiArchInitialize (
- PVOID *TopOfStack,
- PULONG StackSize
- );
- /*++
- Routine Description:
- This routine performs early architecture specific initialization of an EFI
- application.
- Arguments:
- TopOfStack - Supplies a pointer where an approximation of the top of the
- stack will be returned.
- StackSize - Supplies a pointer where the stack size will be returned.
- Return Value:
- None.
- --*/
- //
- // Utility functions
- //
- UINTN
- BopEfiGetStackPointer (
- VOID
- );
- /*++
- Routine Description:
- This routine gets the value of the stack register. Note that this can only
- be used as an approximate value, since as soon as this function returns
- the stack pointer changes.
- Arguments:
- None.
- Return Value:
- Returns the current stack pointer.
- --*/
- VOID
- BopEfiSaveInitialState (
- VOID
- );
- /*++
- Routine Description:
- This routine saves the initial CPU state as passed to the application. This
- state is restored when making EFI calls.
- Arguments:
- None.
- Return Value:
- None. The original contents are saved in globals.
- --*/
- VOID
- BopEfiRestoreFirmwareContext (
- VOID
- );
- /*++
- Routine Description:
- This routine restores the processor context set when the EFI application
- was started. This routine is called right before an EFI firmware call is
- made. It is not possible to debug through this function, as the IDT is
- swapped out.
- Arguments:
- None.
- Return Value:
- None. The OS loader context is saved in globals.
- --*/
- VOID
- BopEfiRestoreApplicationContext (
- VOID
- );
- /*++
- Routine Description:
- This routine restores the boot application context. This routine is called
- after an EFI call to restore the processor state set up by the OS loader.
- Arguments:
- None.
- Return Value:
- None.
- --*/
- EFI_STATUS
- BopEfiLocateHandle (
- EFI_LOCATE_SEARCH_TYPE SearchType,
- EFI_GUID *Protocol,
- VOID *SearchKey,
- UINTN *BufferSize,
- EFI_HANDLE *Buffer
- );
- /*++
- Routine Description:
- This routine returns an array of handles that support a specified protocol.
- Arguments:
- SearchType - Supplies which handle(s) are to be returned.
- Protocol - Supplies an optional pointer to the protocols to search by.
- SearchKey - Supplies an optional pointer to the search key.
- BufferSize - Supplies a pointer that on input contains the size of the
- result buffer in bytes. On output, the size of the result array will be
- returned (even if the buffer was too small).
- Buffer - Supplies a pointer where the results will be returned.
- Return Value:
- EFI status code.
- --*/
- EFI_STATUS
- BopEfiLocateHandleBuffer (
- EFI_LOCATE_SEARCH_TYPE SearchType,
- EFI_GUID *Protocol,
- VOID *SearchKey,
- UINTN *HandleCount,
- EFI_HANDLE **Buffer
- );
- /*++
- Routine Description:
- This routine returns an array of handles that support the requested
- protocol in a buffer allocated from pool.
- Arguments:
- SearchType - Supplies the search behavior.
- Protocol - Supplies a pointer to the protocol to search by.
- SearchKey - Supplies a pointer to the search key.
- HandleCount - Supplies a pointer where the number of handles will be
- returned.
- Buffer - Supplies a pointer where an array will be returned containing the
- requested handles.
- Return Value:
- EFI_SUCCESS on success.
- EFI_NOT_FOUND if no handles match the search.
- EFI_INVALID_PARAMETER if the handle count or buffer is NULL.
- EFI_OUT_OF_RESOURCES if an allocation failed.
- --*/
- EFI_STATUS
- BopEfiOpenProtocol (
- EFI_HANDLE Handle,
- EFI_GUID *Protocol,
- VOID **Interface,
- EFI_HANDLE AgentHandle,
- EFI_HANDLE ControllerHandle,
- UINT32 Attributes
- );
- /*++
- Routine Description:
- This routine queries a handle to determine if it supports a specified
- protocol. If the protocol is supported by the handle, it opens the protocol
- on behalf of the calling agent.
- Arguments:
- Handle - Supplies the handle for the protocol interface that is being
- opened.
- Protocol - Supplies the published unique identifier of the protocol.
- Interface - Supplies the address where a pointer to the corresponding
- protocol interface is returned.
- AgentHandle - Supplies the handle of the agent that is opening the protocol
- interface specified by the protocol and interface.
- ControllerHandle - Supplies the controller handle that requires the
- protocl interface if the caller is a driver that follows the UEFI
- driver model. If the caller does not follow the UEFI Driver Model, then
- this parameter is optional.
- Attributes - Supplies the open mode of the protocol interface specified by
- the given handle and protocol.
- Return Value:
- EFI status code.
- --*/
- EFI_STATUS
- BopEfiCloseProtocol (
- EFI_HANDLE Handle,
- EFI_GUID *Protocol,
- EFI_HANDLE AgentHandle,
- EFI_HANDLE ControllerHandle
- );
- /*++
- Routine Description:
- This routine closes a protocol on a handle that was previously opened.
- Arguments:
- Handle - Supplies the handle for the protocol interface was previously
- opened.
- Protocol - Supplies the published unique identifier of the protocol.
- AgentHandle - Supplies the handle of the agent that is closing the
- protocol interface.
- ControllerHandle - Supplies the controller handle that required the
- protocl interface if the caller is a driver that follows the UEFI
- driver model. If the caller does not follow the UEFI Driver Model, then
- this parameter is optional.
- Return Value:
- EFI status code.
- --*/
- EFI_STATUS
- BopEfiHandleProtocol (
- EFI_HANDLE Handle,
- EFI_GUID *Protocol,
- VOID **Interface
- );
- /*++
- Routine Description:
- This routine queries a handle to determine if it supports a specified
- protocol.
- Arguments:
- Handle - Supplies the handle being queried.
- Protocol - Supplies the published unique identifier of the protocol.
- Interface - Supplies the address where a pointer to the corresponding
- protocol interface is returned.
- Return Value:
- EFI_SUCCESS if the interface information was returned.
- EFI_UNSUPPORTED if the device not support the specified protocol.
- EFI_INVALID_PARAMETER if the handle, protocol, or interface is NULL.
- --*/
- EFI_STATUS
- BopEfiFreePool (
- VOID *Buffer
- );
- /*++
- Routine Description:
- This routine frees memory allocated from the EFI firmware heap (not the
- boot environment heap).
- Arguments:
- Buffer - Supplies a pointer to the buffer to free.
- Return Value:
- EFI_SUCCESS on success.
- EFI_INVALID_PARAMETER if the buffer was invalid.
- --*/
- EFI_STATUS
- BopEfiExitBootServices (
- EFI_HANDLE ImageHandle,
- UINTN MapKey
- );
- /*++
- Routine Description:
- This routine terminates all boot services.
- Arguments:
- ImageHandle - Supplies the handle that identifies the exiting image.
- MapKey - Supplies the latest memory map key.
- Return Value:
- EFI_SUCCESS on success.
- EFI_INVALID_PARAMETER if the map key is incorrect.
- --*/
- EFI_STATUS
- BopEfiGetTime (
- EFI_TIME *Time,
- EFI_TIME_CAPABILITIES *Capabilities
- );
- /*++
- Routine Description:
- This routine returns the current time and date information, and
- timekeeping capabilities of the hardware platform.
- Arguments:
- Time - Supplies a pointer where the current time will be returned.
- Capabilities - Supplies an optional pointer where the capabilities will be
- returned on success.
- Return Value:
- EFI_SUCCESS on success.
- EFI_INVALID_PARAMETER if the time parameter was NULL.
- EFI_DEVICE_ERROR if there was a hardware error accessing the device.
- --*/
- EFI_STATUS
- BopEfiStall (
- UINTN Microseconds
- );
- /*++
- Routine Description:
- This routine induces a fine-grained delay.
- Arguments:
- Microseconds - Supplies the number of microseconds to stall execution for.
- Return Value:
- EFI_SUCCESS on success.
- --*/
- VOID
- BopEfiResetSystem (
- EFI_RESET_TYPE ResetType,
- EFI_STATUS ResetStatus,
- UINTN DataSize,
- VOID *ResetData
- );
- /*++
- Routine Description:
- This routine resets the entire platform.
- Arguments:
- ResetType - Supplies the type of reset to perform.
- ResetStatus - Supplies the status code for this reset.
- DataSize - Supplies the size of the reset data.
- ResetData - Supplies an optional pointer for reset types of cold, warm, or
- shutdown to a null-terminated string, optionally followed by additional
- binary data.
- Return Value:
- None. This routine does not return.
- --*/
- VOID
- BopEfiPrintString (
- PWSTR WideString
- );
- /*++
- Routine Description:
- This routine prints a string to the EFI standard out console.
- Arguments:
- WideString - Supplies a pointer to the wide string to print. A wide
- character is two bytes in EFI.
- Return Value:
- None.
- --*/
- KSTATUS
- BopEfiGetSystemConfigurationTable (
- EFI_GUID *Guid,
- VOID **Table
- );
- /*++
- Routine Description:
- This routine attempts to find a configuration table with the given GUID.
- Arguments:
- Guid - Supplies a pointer to the GUID to search for.
- Table - Supplies a pointer where a pointer to the table will be returned on
- success.
- Return Value:
- STATUS_SUCCESS on success.
- STATUS_NOT_FOUND if no table with the given GUID could be found.
- STATUS_NOT_INITIALIZED if the EFI subsystem has not yet started.
- --*/
- KSTATUS
- BopEfiStatusToKStatus (
- EFI_STATUS Status
- );
- /*++
- Routine Description:
- This routine returns a kernel status code similar to the given EFI status
- code.
- Arguments:
- Status - Supplies the EFI status code.
- Return Value:
- Status code.
- --*/
- BOOL
- BopEfiAreGuidsEqual (
- EFI_GUID *FirstGuid,
- EFI_GUID *SecondGuid
- );
- /*++
- Routine Description:
- This routine determines if two GUIDs are equal.
- Arguments:
- FirstGuid - Supplies a pointer to the first GUID to compare.
- SecondGuid - Supplies a pointer to the second GUId to compare.
- Return Value:
- TRUE if the two GUIDs have equal values.
- FALSE if the two GUIDs are not the same.
- --*/
- //
- // Memory functions
- //
- KSTATUS
- BopEfiInitializeMemory (
- VOID
- );
- /*++
- Routine Description:
- This routine initializes memory services for the boot loader.
- Arguments:
- None.
- Return Value:
- Status code.
- --*/
- VOID
- BopEfiDestroyMemory (
- VOID
- );
- /*++
- Routine Description:
- This routine cleans up memory services upon failure.
- Arguments:
- None.
- Return Value:
- None.
- --*/
- KSTATUS
- BopEfiLoaderAllocatePages (
- PULONGLONG Address,
- ULONGLONG Size,
- MEMORY_TYPE MemoryType
- );
- /*++
- Routine Description:
- This routine allocates physical pages for use.
- Arguments:
- Address - Supplies a pointer to where the allocation will be returned.
- Size - Supplies the size of the required space, in bytes.
- MemoryType - Supplies the type of memory to mark the allocation as.
- Return Value:
- STATUS_SUCCESS if the allocation was successful.
- STATUS_INVALID_PARAMETER if a page count of 0 was passed or the address
- parameter was not filled out.
- STATUS_NO_MEMORY if the allocation request could not be filled.
- --*/
- KSTATUS
- BopEfiSynchronizeMemoryMap (
- PUINTN Key
- );
- /*++
- Routine Description:
- This routine synchronizes the EFI memory map with the boot memory map.
- Arguments:
- Key - Supplies a pointer where the latest EFI memory map key will be
- returned.
- Return Value:
- Status code.
- --*/
- KSTATUS
- BopEfiVirtualizeFirmwareServices (
- UINTN MemoryMapSize,
- UINTN DescriptorSize,
- UINT32 DescriptorVersion,
- EFI_MEMORY_DESCRIPTOR *VirtualMap
- );
- /*++
- Routine Description:
- This routine changes the runtime addressing mode of EFI firmware from
- physical to virtual.
- Arguments:
- MemoryMapSize - Supplies the size of the virtual map.
- DescriptorSize - Supplies the size of an entry in the virtual map.
- DescriptorVersion - Supplies the version of the structure entries in the
- virtual map.
- VirtualMap - Supplies the array of memory descriptors which contain the
- new virtual address mappings for all runtime ranges.
- Return Value:
- Status code.
- --*/
- KSTATUS
- BopEfiGetAllocatedMemoryMap (
- UINTN *MemoryMapSize,
- EFI_MEMORY_DESCRIPTOR **MemoryMap,
- UINTN *MapKey,
- UINTN *DescriptorSize,
- UINT32 *DescriptorVersion
- );
- /*++
- Routine Description:
- This routine returns the current memory map.
- Arguments:
- MemoryMapSize - Supplies a pointer where the size in bytes of the map
- buffer will be returned.
- MemoryMap - Supplies a pointer where a pointer to the memory map will be
- returned on success. The caller is responsible for freeing this memory.
- MapKey - Supplies a pointer where the map key will be returned on success.
- DescriptorSize - Supplies a pointer where the firmware returns the size of
- the EFI_MEMORY_DESCRIPTOR structure.
- DescriptorVersion - Supplies a pointer where the firmware returns the
- version number associated with the EFI_MEMORY_DESCRIPTOR structure.
- Return Value:
- Status code.
- --*/
- //
- // Disk functions
- //
- KSTATUS
- BopEfiOpenBootDisk (
- PHANDLE Handle
- );
- /*++
- Routine Description:
- This routine attempts to open the boot disk, the disk from which to load
- the OS.
- Arguments:
- Handle - Supplies a pointer where a handle to the disk will be returned.
- Return Value:
- Status code.
- --*/
- KSTATUS
- BopEfiOpenPartition (
- UCHAR PartitionId[FIRMWARE_PARTITION_ID_SIZE],
- PHANDLE Handle
- );
- /*++
- Routine Description:
- This routine opens a handle to a disk and partition with the given IDs.
- Arguments:
- PartitionId - Supplies the partition identifier to match against.
- Handle - Supplies a pointer where a handle to the opened disk will be
- returned upon success.
- Return Value:
- Status code.
- --*/
- VOID
- BopEfiCloseDisk (
- HANDLE DiskHandle
- );
- /*++
- Routine Description:
- This routine closes an open disk.
- Arguments:
- DiskHandle - Supplies a pointer to the open disk handle.
- Return Value:
- None.
- --*/
- KSTATUS
- BopEfiLoaderBlockIoRead (
- HANDLE DiskHandle,
- ULONGLONG Sector,
- ULONG SectorCount,
- PVOID Buffer
- );
- /*++
- Routine Description:
- This routine uses firmware calls read sectors off of a disk.
- Arguments:
- DiskHandle - Supplies a handle to the disk to read from.
- Sector - Supplies the zero-based sector number to read from.
- SectorCount - Supplies the number of sectors to read. The supplied buffer
- must be at least this large.
- Buffer - Supplies the buffer where the data read from the disk will be
- returned upon success.
- Return Value:
- STATUS_SUCCESS if the operation completed successfully.
- STATUS_FIRMWARE_ERROR if the firmware returned an error.
- Other error codes.
- --*/
- KSTATUS
- BopEfiLoaderBlockIoWrite (
- HANDLE DiskHandle,
- ULONGLONG Sector,
- ULONG SectorCount,
- PVOID Buffer
- );
- /*++
- Routine Description:
- This routine uses firmware calls to write sectors to a disk.
- Arguments:
- DiskHandle - Supplies a handle to the disk to write to.
- Sector - Supplies the zero-based sector number to write to.
- SectorCount - Supplies the number of sectors to write. The supplied buffer
- must be at least this large.
- Buffer - Supplies the buffer containing the data to write to the disk.
- Return Value:
- STATUS_SUCCESS if the operation completed successfully.
- STATUS_FIRMWARE_ERROR if the firmware returned an error.
- Other error codes.
- --*/
- ULONG
- BopEfiGetDiskBlockSize (
- HANDLE DiskHandle
- );
- /*++
- Routine Description:
- This routine determines the number of bytes in a sector on the given disk.
- Arguments:
- DiskHandle - Supplies a handle to the disk to query.
- Return Value:
- Returns the number of bytes in a sector on success.
- 0 on error.
- --*/
- ULONGLONG
- BopEfiGetDiskBlockCount (
- HANDLE DiskHandle
- );
- /*++
- Routine Description:
- This routine determines the number of sectors on the disk.
- Arguments:
- DiskHandle - Supplies a handle to the disk to query.
- Return Value:
- Returns the number of sectors in the disk on success.
- 0 on error.
- --*/
- KSTATUS
- BopEfiGetRamDisks (
- PBOOT_RAM_DISK *RamDisks,
- PULONG RamDiskCount
- );
- /*++
- Routine Description:
- This routine returns an array of the RAM disks known to the firmware.
- Arguments:
- RamDisks - Supplies a pointer where an array of RAM disk structures will
- be allocated and returned. It is the caller's responsibility to free
- this memory.
- RamDiskCount - Supplies a pointer where the count of RAM disks in the
- array will be returned.
- Return Value:
- Status code.
- --*/
- //
- // Video services
- //
- VOID
- BopEfiInitializeVideo (
- VOID
- );
- /*++
- Routine Description:
- This routine initializes UEFI video services. Failure here is not fatal.
- Arguments:
- None.
- Return Value:
- None.
- --*/
- KSTATUS
- BopEfiGetVideoInformation (
- PULONG ResolutionX,
- PULONG ResolutionY,
- PULONG PixelsPerScanLine,
- PULONG BitsPerPixel,
- PULONG RedMask,
- PULONG GreenMask,
- PULONG BlueMask,
- PPHYSICAL_ADDRESS FrameBufferBase,
- PULONGLONG FrameBufferSize
- );
- /*++
- Routine Description:
- This routine returns information about the video frame buffer.
- Arguments:
- ResolutionX - Supplies a pointer where the horizontal resolution in pixels
- will be returned on success.
- ResolutionY - Supplies a pointer where the vertical resolution in pixels
- will be returned on success.
- PixelsPerScanLine - Supplies a pointer where the number of pixels per scan
- line will be returned on success.
- BitsPerPixel - Supplies a pointer where the number of bits per pixel will
- be returned on success.
- RedMask - Supplies a pointer where the mask of bits corresponding to the
- red channel will be returned on success. It is assumed this will be a
- contiguous chunk of bits.
- GreenMask - Supplies a pointer where the mask of bits corresponding to the
- green channel will be returned on success. It is assumed this will be a
- contiguous chunk of bits.
- BlueMask - Supplies a pointer where the mask of bits corresponding to the
- blue channel will be returned on success. It is assumed this will be a
- contiguous chunk of bits.
- FrameBufferBase - Supplies a pointer where the physical base address of the
- frame buffer will be returned on success.
- FrameBufferSize - Supplies a pointer where the size of the frame buffer in
- bytes will be returned on success.
- Return Value:
- STATUS_SUCCESS on success.
- STATUS_NOT_CONFIGURED if video services could not be initialized.
- --*/
- VOID
- BopEfiGetDebugDevice (
- VOID
- );
- /*++
- Routine Description:
- This routine searches for the Serial I/O protocol and enumerates a debug
- devices with it if found.
- Arguments:
- None.
- Return Value:
- None. Failure is not fatal.
- --*/
- //
- // Time services
- //
- KSTATUS
- BopEfiGetCurrentTime (
- PSYSTEM_TIME Time
- );
- /*++
- Routine Description:
- This routine attempts to get the current system time.
- Arguments:
- Time - Supplies a pointer where the current time will be returned.
- Return Value:
- Status code.
- --*/
|