/**@file\r
- Serial driver for standard UARTS on an ISA bus.\r
+ Serial driver for standard UARTS on an ISA bus.\r
\r
Copyright (c) 2006 - 2007, Intel Corporation<BR>\r
All rights reserved. This program and the accompanying materials\r
return Status;\r
}\r
\r
+/**\r
+ Check to see if this driver supports the given controller\r
+\r
+ @param This - A pointer to the EFI_DRIVER_BINDING_PROTOCOL instance.\r
+ @param Controller - The handle of the controller to test.\r
+ @param RemainingDevicePath - A pointer to the remaining portion of a device path.\r
\r
+ @return EFI_SUCCESS - This driver can support the given controller\r
+\r
+**/\r
EFI_STATUS\r
EFIAPI\r
SerialControllerDriverSupported (\r
IN EFI_HANDLE Controller,\r
IN EFI_DEVICE_PATH_PROTOCOL *RemainingDevicePath\r
)\r
-/*++\r
-\r
- Routine Description:\r
-\r
- Check to see if this driver supports the given controller\r
-\r
- Arguments:\r
\r
- This - A pointer to the EFI_DRIVER_BINDING_PROTOCOL instance.\r
- Controller - The handle of the controller to test.\r
- RemainingDevicePath - A pointer to the remaining portion of a device path.\r
-\r
- Returns:\r
-\r
- EFI_SUCCESS - This driver can support the given controller\r
-\r
---*/\r
{\r
EFI_STATUS Status;\r
EFI_DEVICE_PATH_PROTOCOL *ParentDevicePath;\r
return Status;\r
}\r
\r
+/**\r
+ Start to management the controller passed in\r
+\r
+ @param This - A pointer to the EFI_DRIVER_BINDING_PROTOCOL instance.\r
+ @param Controller - The handle of the controller to test.\r
+ @param RemainingDevicePath - A pointer to the remaining portion of a device path.\r
+\r
+ @return EFI_SUCCESS - Driver is started successfully\r
+\r
+**/\r
EFI_STATUS\r
EFIAPI\r
SerialControllerDriverStart (\r
IN EFI_HANDLE Controller,\r
IN EFI_DEVICE_PATH_PROTOCOL *RemainingDevicePath\r
)\r
-/*++\r
-\r
- Routine Description:\r
-\r
- Start to management the controller passed in\r
-\r
- Arguments:\r
-\r
- This - A pointer to the EFI_DRIVER_BINDING_PROTOCOL instance.\r
- Controller - The handle of the controller to test.\r
- RemainingDevicePath - A pointer to the remaining portion of a device path.\r
\r
- Returns:\r
-\r
- EFI_SUCCESS - Driver is started successfully\r
-\r
---*/\r
{\r
EFI_STATUS Status;\r
EFI_ISA_IO_PROTOCOL *IsaIo;\r
return Status;\r
}\r
\r
+/**\r
+ Disconnect this driver with the controller, uninstall related protocol instance\r
+\r
+ @param This - A pointer to the EFI_DRIVER_BINDING_PROTOCOL instance.\r
+ @param Controller - The handle of the controller to test.\r
+ @param NumberOfChildren - Number of child device.\r
+ @param RemainingDevicePath - A pointer to the remaining portion of a device path.\r
+\r
+ @retval EFI_SUCCESS - Operation successfully\r
+ @retval EFI_DEVICE_ERROR - Cannot stop the driver successfully\r
+\r
+**/\r
EFI_STATUS\r
EFIAPI\r
SerialControllerDriverStop (\r
IN UINTN NumberOfChildren,\r
IN EFI_HANDLE *ChildHandleBuffer\r
)\r
-/*++\r
-\r
- Routine Description:\r
-\r
- Disconnect this driver with the controller, uninstall related protocol instance\r
-\r
- Arguments:\r
-\r
- This - A pointer to the EFI_DRIVER_BINDING_PROTOCOL instance.\r
- Controller - The handle of the controller to test.\r
- NumberOfChildren - Number of child device.\r
- RemainingDevicePath - A pointer to the remaining portion of a device path.\r
-\r
- Returns:\r
\r
- EFI_SUCCESS - Operation successfully\r
- EFI_DEVICE_ERROR - Cannot stop the driver successfully\r
-\r
---*/\r
{\r
EFI_STATUS Status;\r
UINTN Index;\r
return EFI_SUCCESS;\r
}\r
\r
+/**\r
+ Detect whether specific FIFO is full or not\r
+\r
+ @param Fifo - A pointer to the Data Structure SERIAL_DEV_FIFO\r
+\r
+ @return whether specific FIFO is full or not\r
+\r
+**/\r
BOOLEAN\r
IsaSerialFifoFull (\r
IN SERIAL_DEV_FIFO *Fifo\r
)\r
-/*++\r
\r
- Routine Description:\r
-\r
- Detect whether specific FIFO is full or not\r
-\r
- Arguments:\r
-\r
- Fifo - A pointer to the Data Structure SERIAL_DEV_FIFO\r
-\r
- Returns:\r
-\r
- TRUE - the FIFO is full\r
- FALSE - the FIFO is not full\r
-\r
---*/\r
{\r
if (Fifo->Surplus == 0) {\r
return TRUE;\r
return FALSE;\r
}\r
\r
+/**\r
+ Detect whether specific FIFO is empty or not\r
+\r
+ \r
+ @param Fifo - A pointer to the Data Structure SERIAL_DEV_FIFO\r
+\r
+ @return whether specific FIFO is empty or not\r
+\r
+**/\r
BOOLEAN\r
IsaSerialFifoEmpty (\r
IN SERIAL_DEV_FIFO *Fifo\r
)\r
-/*++\r
-\r
- Routine Description:\r
\r
- Detect whether specific FIFO is empty or not\r
-\r
- Arguments:\r
-\r
- Fifo - A pointer to the Data Structure SERIAL_DEV_FIFO\r
-\r
- Returns:\r
-\r
- TRUE - the FIFO is empty\r
- FALSE - the FIFO is not empty\r
-\r
---*/\r
{\r
if (Fifo->Surplus == SERIAL_MAX_BUFFER_SIZE) {\r
return TRUE;\r
return FALSE;\r
}\r
\r
+/**\r
+ Add data to specific FIFO\r
+\r
+ @param Fifo - A pointer to the Data Structure SERIAL_DEV_FIFO\r
+ @param Data - the data added to FIFO\r
+\r
+ @retval EFI_SUCCESS - Add data to specific FIFO successfully\r
+ @retval EFI_OUT_OF_RESOURCE - Failed to add data because FIFO is already full\r
+\r
+**/\r
EFI_STATUS\r
IsaSerialFifoAdd (\r
IN SERIAL_DEV_FIFO *Fifo,\r
IN UINT8 Data\r
)\r
-/*++\r
-\r
- Routine Description:\r
-\r
- Add data to specific FIFO\r
-\r
- Arguments:\r
\r
- Fifo - A pointer to the Data Structure SERIAL_DEV_FIFO\r
- Data - the data added to FIFO\r
-\r
- Returns:\r
-\r
- EFI_SUCCESS - Add data to specific FIFO successfully\r
- EFI_OUT_OF_RESOURCE - Failed to add data because FIFO is already full\r
-\r
---*/\r
{\r
//\r
// if FIFO full can not add data\r
return EFI_SUCCESS;\r
}\r
\r
+/**\r
+ Remove data from specific FIFO\r
+\r
+ @param Fifo - A pointer to the Data Structure SERIAL_DEV_FIFO\r
+ @param Data - the data removed from FIFO\r
+\r
+ @retval EFI_SUCCESS - Remove data from specific FIFO successfully\r
+ @retval EFI_OUT_OF_RESOURCE - Failed to remove data because FIFO is empty\r
+\r
+**/\r
EFI_STATUS\r
IsaSerialFifoRemove (\r
IN SERIAL_DEV_FIFO *Fifo,\r
OUT UINT8 *Data\r
)\r
-/*++\r
-\r
- Routine Description:\r
-\r
- Remove data from specific FIFO\r
-\r
- Arguments:\r
-\r
- Fifo - A pointer to the Data Structure SERIAL_DEV_FIFO\r
- Data - the data removed from FIFO\r
\r
- Returns:\r
- EFI_SUCCESS - Remove data from specific FIFO successfully\r
- EFI_OUT_OF_RESOURCE - Failed to remove data because FIFO is empty\r
-\r
---*/\r
{\r
//\r
// if FIFO is empty, no data can remove\r
return EFI_SUCCESS;\r
}\r
\r
+/**\r
+ Reads and writes all avaliable data.\r
+\r
+ @param SerialDevice - The device to flush\r
+\r
+ @retval EFI_SUCCESS - Data was read/written successfully.\r
+ @retval EFI_OUT_OF_RESOURCE - Failed because software receive FIFO is full. Note, when\r
+ this happens, pending writes are not done.\r
+\r
+**/\r
EFI_STATUS\r
IsaSerialReceiveTransmit (\r
IN SERIAL_DEV *SerialDevice\r
)\r
-/*++\r
-\r
- Routine Description:\r
-\r
- Reads and writes all avaliable data.\r
-\r
- Arguments:\r
-\r
- SerialDevice - The device to flush\r
-\r
- Returns:\r
-\r
- EFI_SUCCESS - Data was read/written successfully.\r
- EFI_OUT_OF_RESOURCE - Failed because software receive FIFO is full. Note, when\r
- this happens, pending writes are not done.\r
\r
---*/\r
{\r
SERIAL_PORT_LSR Lsr;\r
UINT8 Data;\r
\r
return EFI_SUCCESS;\r
}\r
+\r
//\r
// Interface Functions\r
//\r
+/**\r
+ Reset serial device\r
+\r
+ @param This - Pointer to EFI_SERIAL_IO_PROTOCOL\r
+\r
+ @retval EFI_SUCCESS - Reset successfully\r
+ @retval EFI_DEVICE_ERROR - Failed to reset\r
+\r
+**/\r
EFI_STATUS\r
EFIAPI\r
IsaSerialReset (\r
IN EFI_SERIAL_IO_PROTOCOL *This\r
)\r
-/*++\r
-\r
- Routine Description:\r
-\r
- Reset serial device\r
-\r
- Arguments:\r
-\r
- This - Pointer to EFI_SERIAL_IO_PROTOCOL\r
-\r
- Returns:\r
-\r
- EFI_SUCCESS - Reset successfully\r
- EFI_DEVICE_ERROR - Failed to reset\r
-\r
---*/\r
{\r
EFI_STATUS Status;\r
SERIAL_DEV *SerialDevice;\r
return EFI_SUCCESS;\r
}\r
\r
+/**\r
+ Set new attributes to a serial device\r
+\r
+ @param This - Pointer to EFI_SERIAL_IO_PROTOCOL\r
+ @param BaudRate - The baudrate of the serial device\r
+ @param ReceiveFifoDepth - The depth of receive FIFO buffer\r
+ @param Timeout - The request timeout for a single char\r
+ @param Parity - The type of parity used in serial device\r
+ @param DataBits - Number of databits used in serial device\r
+ @param StopBits - Number of stopbits used in serial device\r
+\r
+ @retval EFI_SUCCESS - The new attributes were set\r
+ @retval EFI_INVALID_PARAMETERS - One or more attributes have an unsupported value\r
+ @retval EFI_UNSUPPORTED - Data Bits can not set to 5 or 6\r
+ @retval EFI_DEVICE_ERROR - The serial device is not functioning correctly (no return)\r
+\r
+**/\r
EFI_STATUS\r
EFIAPI\r
IsaSerialSetAttributes (\r
IN UINT8 DataBits,\r
IN EFI_STOP_BITS_TYPE StopBits\r
)\r
-/*++\r
-\r
- Routine Description:\r
-\r
- Set new attributes to a serial device\r
-\r
- Arguments:\r
-\r
- This - Pointer to EFI_SERIAL_IO_PROTOCOL\r
- BaudRate - The baudrate of the serial device\r
- ReceiveFifoDepth - The depth of receive FIFO buffer\r
- Timeout - The request timeout for a single char\r
- Parity - The type of parity used in serial device\r
- DataBits - Number of databits used in serial device\r
- StopBits - Number of stopbits used in serial device\r
-\r
- Returns:\r
-\r
- EFI_SUCCESS - The new attributes were set\r
- EFI_INVALID_PARAMETERS - One or more attributes have an unsupported value\r
- EFI_UNSUPPORTED - Data Bits can not set to 5 or 6\r
- EFI_DEVICE_ERROR - The serial device is not functioning correctly (no return)\r
-\r
---*/\r
{\r
EFI_STATUS Status;\r
SERIAL_DEV *SerialDevice;\r
return EFI_SUCCESS;\r
}\r
\r
+/**\r
+ Set Control Bits\r
+\r
+ @param This - Pointer to EFI_SERIAL_IO_PROTOCOL\r
+ @param Control - Control bits that can be settable\r
+\r
+ @retval EFI_SUCCESS - New Control bits were set successfully\r
+ @retval EFI_UNSUPPORTED - The Control bits wanted to set are not supported\r
+\r
+**/\r
EFI_STATUS\r
EFIAPI\r
IsaSerialSetControl (\r
IN EFI_SERIAL_IO_PROTOCOL *This,\r
IN UINT32 Control\r
)\r
-/*++\r
-\r
- Routine Description:\r
-\r
- Set Control Bits\r
-\r
- Arguments:\r
-\r
- This - Pointer to EFI_SERIAL_IO_PROTOCOL\r
- Control - Control bits that can be settable\r
-\r
- Returns:\r
-\r
- EFI_SUCCESS - New Control bits were set successfully\r
- EFI_UNSUPPORTED - The Control bits wanted to set are not supported\r
-\r
---*/\r
{\r
SERIAL_DEV *SerialDevice;\r
SERIAL_PORT_MCR Mcr;\r
return EFI_SUCCESS;\r
}\r
\r
+/**\r
+ Get ControlBits\r
+\r
+ @param This - Pointer to EFI_SERIAL_IO_PROTOCOL\r
+ @param Control - Control signals of the serial device\r
+\r
+ @retval EFI_SUCCESS - Get Control signals successfully\r
+\r
+**/\r
EFI_STATUS\r
EFIAPI\r
IsaSerialGetControl (\r
IN EFI_SERIAL_IO_PROTOCOL *This,\r
OUT UINT32 *Control\r
)\r
-/*++\r
-\r
- Routine Description:\r
-\r
- Get ControlBits\r
-\r
- Arguments:\r
-\r
- This - Pointer to EFI_SERIAL_IO_PROTOCOL\r
- Control - Control signals of the serial device\r
-\r
- Returns:\r
-\r
- EFI_SUCCESS - Get Control signals successfully\r
-\r
---*/\r
{\r
SERIAL_DEV *SerialDevice;\r
SERIAL_PORT_MSR Msr;\r
return EFI_SUCCESS;\r
}\r
\r
+/**\r
+ Write the specified number of bytes to serial device\r
+\r
+ @param This - Pointer to EFI_SERIAL_IO_PROTOCOL\r
+ @param BufferSize - On input the size of Buffer, on output the amount of\r
+ data actually written\r
+ @param Buffer - The buffer of data to write\r
+\r
+ @retval EFI_SUCCESS - The data were written successfully\r
+ @retval EFI_DEVICE_ERROR - The device reported an error\r
+ @retval EFI_TIMEOUT - The write operation was stopped due to timeout\r
+\r
+**/\r
EFI_STATUS\r
EFIAPI\r
IsaSerialWrite (\r
IN OUT UINTN *BufferSize,\r
IN VOID *Buffer\r
)\r
-/*++\r
-\r
- Routine Description:\r
-\r
- Write the specified number of bytes to serial device\r
-\r
- Arguments:\r
-\r
- This - Pointer to EFI_SERIAL_IO_PROTOCOL\r
- BufferSize - On input the size of Buffer, on output the amount of\r
- data actually written\r
- Buffer - The buffer of data to write\r
-\r
- Returns:\r
-\r
- EFI_SUCCESS - The data were written successfully\r
- EFI_DEVICE_ERROR - The device reported an error\r
- EFI_TIMEOUT - The write operation was stopped due to timeout\r
-\r
---*/\r
{\r
SERIAL_DEV *SerialDevice;\r
UINT8 *CharBuffer;\r
return EFI_SUCCESS;\r
}\r
\r
+/**\r
+ Read the specified number of bytes from serial device\r
+\r
+ @param This - Pointer to EFI_SERIAL_IO_PROTOCOL\r
+ @param BufferSize - On input the size of Buffer, on output the amount of\r
+ data returned in buffer\r
+ @param Buffer - The buffer to return the data into\r
+\r
+ @retval EFI_SUCCESS - The data were read successfully\r
+ @retval EFI_DEVICE_ERROR - The device reported an error\r
+ @retval EFI_TIMEOUT - The read operation was stopped due to timeout\r
+\r
+**/\r
EFI_STATUS\r
EFIAPI\r
IsaSerialRead (\r
IN OUT UINTN *BufferSize,\r
OUT VOID *Buffer\r
)\r
-/*++\r
-\r
- Routine Description:\r
-\r
- Read the specified number of bytes from serial device\r
-\r
- Arguments:\r
-\r
- This - Pointer to EFI_SERIAL_IO_PROTOCOL\r
- BufferSize - On input the size of Buffer, on output the amount of\r
- data returned in buffer\r
- Buffer - The buffer to return the data into\r
-\r
- Returns:\r
-\r
- EFI_SUCCESS - The data were read successfully\r
- EFI_DEVICE_ERROR - The device reported an error\r
- EFI_TIMEOUT - The read operation was stopped due to timeout\r
-\r
---*/\r
{\r
SERIAL_DEV *SerialDevice;\r
UINT32 Index;\r
return EFI_SUCCESS;\r
}\r
\r
+/**\r
+ Use scratchpad register to test if this serial port is present\r
+\r
+ @param SerialDevice - Pointer to serial device structure\r
+\r
+ @return if this serial port is present\r
+**/\r
BOOLEAN\r
IsaSerialPortPresent (\r
IN SERIAL_DEV *SerialDevice\r
)\r
-/*++\r
-\r
- Routine Description:\r
-\r
- Use scratchpad register to test if this serial port is present\r
-\r
- Arguments:\r
-\r
- SerialDevice - Pointer to serial device structure\r
-\r
- Returns:\r
\r
- TRUE - The serial port is present\r
- FALSE - The serial port is NOT present\r
-\r
---*/\r
{\r
UINT8 Temp;\r
BOOLEAN Status;\r
return Status;\r
}\r
\r
+/**\r
+ Use IsaIo protocol to read serial port\r
+\r
+ @param IsaIo - Pointer to EFI_ISA_IO_PROTOCOL instance\r
+ @param BaseAddress - Serial port register group base address\r
+ @param Offset - Offset in register group\r
+\r
+ @return Data read from serial port\r
+\r
+**/\r
UINT8\r
IsaSerialReadPort (\r
IN EFI_ISA_IO_PROTOCOL *IsaIo,\r
IN UINT16 BaseAddress,\r
IN UINT32 Offset\r
)\r
-/*++\r
-\r
- Routine Description:\r
-\r
- Use IsaIo protocol to read serial port\r
-\r
- Arguments:\r
-\r
- IsaIo - Pointer to EFI_ISA_IO_PROTOCOL instance\r
- BaseAddress - Serial port register group base address\r
- Offset - Offset in register group\r
-\r
- Returns:\r
-\r
- Data read from serial port\r
-\r
---*/\r
{\r
UINT8 Data;\r
\r
return Data;\r
}\r
\r
+/**\r
+ Use IsaIo protocol to write serial port\r
+\r
+ @param IsaIo - Pointer to EFI_ISA_IO_PROTOCOL instance\r
+ @param BaseAddress - Serial port register group base address\r
+ @param Offset - Offset in register group\r
+ @param Data - data which is to be written to some serial port register\r
+\r
+**/\r
VOID\r
IsaSerialWritePort (\r
IN EFI_ISA_IO_PROTOCOL *IsaIo,\r
IN UINT32 Offset,\r
IN UINT8 Data\r
)\r
-/*++\r
-\r
- Routine Description:\r
-\r
- Use IsaIo protocol to write serial port\r
-\r
- Arguments:\r
-\r
- IsaIo - Pointer to EFI_ISA_IO_PROTOCOL instance\r
- BaseAddress - Serial port register group base address\r
- Offset - Offset in register group\r
- Data - data which is to be written to some serial port register\r
-\r
- Returns:\r
-\r
- None\r
-\r
---*/\r
{\r
//\r
// Use IsaIo to access IO\r
projects / mirror_edk2.git / blobdiff