| /** @file | |
| Header file for USB Serial Driver's Data Structures. | |
| Copyright (c) 2004 - 2013, Intel Corporation. All rights reserved. | |
| Portions Copyright 2012 Ashley DeSimone | |
| This program and the accompanying materials | |
| are licensed and made available under the terms and conditions of the BSD | |
| License which accompanies this distribution. The full text of the license may | |
| be found at 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. | |
| **/ | |
| #ifndef _FTDI_USB_SERIAL_DRIVER_H_ | |
| #define _FTDI_USB_SERIAL_DRIVER_H_ | |
| #include <Library/BaseMemoryLib.h> | |
| #include <Library/DebugLib.h> | |
| #include <Library/MemoryAllocationLib.h> | |
| #include <Library/UefiBootServicesTableLib.h> | |
| #include <Library/UefiLib.h> | |
| #include <Library/DevicePathLib.h> | |
| #include <Protocol/DevicePath.h> | |
| #include <Protocol/UsbIo.h> | |
| #include <Protocol/SerialIo.h> | |
| // | |
| // US English LangID | |
| // | |
| #define USB_US_LANG_ID 0x0409 | |
| // | |
| // Supported Vendor Ids | |
| // | |
| #define VID_FTDI 0x0403 | |
| // | |
| // Supported product ids | |
| // | |
| #define DID_FTDI_FT232 0x6001 | |
| // | |
| // FTDI Commands | |
| // | |
| #define FTDI_COMMAND_RESET_PORT 0 | |
| #define FTDI_COMMAND_MODEM_CTRL 1 | |
| #define FTDI_COMMAND_SET_FLOW_CTRL 2 | |
| #define FTDI_COMMAND_SET_BAUDRATE 3 | |
| #define FTDI_COMMAND_SET_DATA 4 | |
| #define FTDI_COMMAND_GET_MODEM_STATUS 5 | |
| #define FTDI_COMMAND_SET_EVENT_CHAR 6 | |
| #define FTDI_COMMAND_SET_ERROR_CHAR 7 | |
| #define FTDI_COMMAND_SET_LATENCY_TIMER 9 | |
| #define FTDI_COMMAND_GET_LATENCY_TIMER 10 | |
| // | |
| // FTDI_PORT_IDENTIFIER | |
| // Used in the usb control transfers that issue FTDI commands as the index value. | |
| // | |
| #define FTDI_PORT_IDENTIFIER 0x1 // For FTDI USB serial adapter the port | |
| // identifier is always 1. | |
| // | |
| // RESET_PORT | |
| // | |
| #define RESET_PORT_RESET 0x0 // Purges RX and TX, clears DTR and RTS sets | |
| // flow control to none, disables event | |
| // trigger, sets the event char to 0x0d and | |
| // does nothing to baudrate or data settings | |
| #define RESET_PORT_PURGE_RX 0x1 | |
| #define RESET_PORT_PURGE_TX 0x2 | |
| // | |
| // SET_FLOW_CONTROL | |
| // | |
| #define NO_FLOW_CTRL 0x0 | |
| #define XON_XOFF_CTRL 0x4 | |
| // | |
| // SET_BAUD_RATE | |
| // To set baud rate, one must calculate an encoding of the baud rate from | |
| // UINT32 to UINT16.See EncodeBaudRateForFtdi() for details | |
| // | |
| #define FTDI_UART_FREQUENCY 3000000 | |
| #define FTDI_MIN_DIVISOR 0x20 | |
| #define FTDI_MAX_DIVISOR 0x3FFF8 | |
| // | |
| // Special case baudrate values | |
| // 300,000 and 200,000 are special cases for calculating the encoded baudrate | |
| // | |
| #define FTDI_SPECIAL_CASE_300_MIN (3000000 * 100) / 103 // minimum adjusted | |
| // value for 300,000 | |
| #define FTDI_SPECIAL_CASE_300_MAX (3000000 * 100) / 97 // maximum adjusted | |
| // value for 300,000 | |
| #define FTDI_SPECIAL_CASE_200_MIN (2000000 * 100) / 103 // minimum adjusted | |
| // value for 200,000 | |
| #define FTDI_SPECIAL_CASE_200_MAX (2000000 * 100) / 97 // maximum adjusted | |
| // value for 200,000 | |
| // | |
| // Min and max frequency values that the FTDI chip can attain | |
| //.all generated frequencies must be between these values | |
| // | |
| #define FTDI_MIN_FREQUENCY 46601941 // (3MHz * 1600) / 103 = 46601941 | |
| #define FTDI_MAX_FREQUENCY 49484536 // (3MHz * 1600) / 97 = 49484536 | |
| // | |
| // SET_DATA_BITS | |
| // | |
| #define SET_DATA_BITS(n) (n) | |
| // | |
| // SET_PARITY | |
| // | |
| #define SET_PARITY_NONE 0x0 | |
| #define SET_PARITY_ODD BIT8 // (0x1 << 8) | |
| #define SET_PARITY_EVEN BIT9 // (0x2 << 8) | |
| #define SET_PARITY_MARK BIT9 | BIT8 // (0x3 << 8) | |
| #define SET_PARITY_SPACE BIT10 // (0x4 << 8) | |
| // | |
| // SET_STOP_BITS | |
| // | |
| #define SET_STOP_BITS_1 0x0 | |
| #define SET_STOP_BITS_15 BIT11 // (0x1 << 11) | |
| #define SET_STOP_BITS_2 BIT12 // (0x2 << 11) | |
| // | |
| // SET_MODEM_CTRL | |
| // SET_DTR_HIGH = (1 | (1 << 8)), SET_DTR_LOW = (0 | (1 << 8) | |
| // SET_RTS_HIGH = (2 | (2 << 8)), SET_RTS_LOW = (0 | (2 << 8) | |
| // | |
| #define SET_DTR_HIGH (BIT8 | BIT0) | |
| #define SET_DTR_LOW (BIT8) | |
| #define SET_RTS_HIGH (BIT9 | BIT1) | |
| #define SET_RTS_LOW (BIT9) | |
| // | |
| // MODEM_STATUS | |
| // | |
| #define CTS_MASK BIT4 | |
| #define DSR_MASK BIT5 | |
| #define RI_MASK BIT6 | |
| #define SD_MASK BIT7 | |
| #define MSR_MASK (CTS_MASK | DSR_MASK | RI_MASK | SD_MASK) | |
| // | |
| // Macro used to check for USB transfer errors | |
| // | |
| #define USB_IS_ERROR(Result, Error) (((Result) & (Error)) != 0) | |
| // | |
| // USB request timeouts | |
| // | |
| #define WDR_TIMEOUT 5000 // default urb timeout in ms | |
| #define WDR_SHORT_TIMEOUT 1000 // shorter urb timeout in ms | |
| // | |
| // FTDI timeout | |
| // | |
| #define FTDI_TIMEOUT 16 | |
| // | |
| // FTDI FIFO depth | |
| // | |
| #define FTDI_MAX_RECEIVE_FIFO_DEPTH 384 | |
| // | |
| // FTDI Endpoint Descriptors | |
| // | |
| #define FTDI_ENDPOINT_ADDRESS_IN 0x81 //the endpoint address for the in enpoint generated by the device | |
| #define FTDI_ENDPOINT_ADDRESS_OUT 0x02 //the endpoint address for the out endpoint generated by the device | |
| // | |
| // Max buffer size for USB transfers | |
| // | |
| #define SW_FIFO_DEPTH 1024 | |
| // | |
| // struct to define a usb device as a vendor and product id pair | |
| // | |
| typedef struct { | |
| UINTN VendorId; | |
| UINTN DeviceId; | |
| } USB_DEVICE; | |
| // | |
| //struct to describe the control bits of the device | |
| //true indicates enabled | |
| //false indicates disabled | |
| // | |
| typedef struct { | |
| BOOLEAN HardwareFlowControl; | |
| BOOLEAN DtrState; | |
| BOOLEAN RtsState; | |
| BOOLEAN HardwareLoopBack; | |
| BOOLEAN SoftwareLoopBack; | |
| } CONTROL_BITS; | |
| // | |
| //struct to describe the status bits of the device | |
| //true indicates enabled | |
| //false indicated disabled | |
| // | |
| typedef struct { | |
| BOOLEAN CtsState; | |
| BOOLEAN DsrState; | |
| BOOLEAN RiState; | |
| BOOLEAN SdState; | |
| } STATUS_BITS; | |
| // | |
| // Structure to describe the last attributes of the Usb Serial device | |
| // | |
| typedef struct { | |
| UINT64 BaudRate; | |
| UINT32 ReceiveFifoDepth; | |
| UINT32 Timeout; | |
| EFI_PARITY_TYPE Parity; | |
| UINT8 DataBits; | |
| EFI_STOP_BITS_TYPE StopBits; | |
| } PREVIOUS_ATTRIBUTES; | |
| // | |
| // Structure to describe USB serial device | |
| // | |
| #define USB_SER_DEV_SIGNATURE SIGNATURE_32 ('u', 's', 'b', 's') | |
| typedef struct { | |
| UINTN Signature; | |
| EFI_HANDLE ControllerHandle; | |
| EFI_DEVICE_PATH_PROTOCOL *DevicePath; | |
| EFI_DEVICE_PATH_PROTOCOL *ParentDevicePath; | |
| UART_DEVICE_PATH UartDevicePath; | |
| UART_FLOW_CONTROL_DEVICE_PATH FlowControlDevicePath; | |
| EFI_USB_IO_PROTOCOL *UsbIo; | |
| EFI_USB_INTERFACE_DESCRIPTOR InterfaceDescriptor; | |
| EFI_USB_ENDPOINT_DESCRIPTOR InEndpointDescriptor; | |
| EFI_USB_ENDPOINT_DESCRIPTOR OutEndpointDescriptor; | |
| EFI_UNICODE_STRING_TABLE *ControllerNameTable; | |
| UINT32 DataBufferHead; | |
| UINT32 DataBufferTail; | |
| UINT8 *DataBuffer; | |
| EFI_SERIAL_IO_PROTOCOL SerialIo; | |
| BOOLEAN Shutdown; | |
| EFI_EVENT PollingLoop; | |
| UINT32 ControlBits; | |
| PREVIOUS_ATTRIBUTES LastSettings; | |
| CONTROL_BITS ControlValues; | |
| STATUS_BITS StatusValues; | |
| UINT8 ReadBuffer[512]; | |
| } USB_SER_DEV; | |
| #define USB_SER_DEV_FROM_THIS(a) \ | |
| CR(a, USB_SER_DEV, SerialIo, USB_SER_DEV_SIGNATURE) | |
| // | |
| // Global Variables | |
| // | |
| extern EFI_DRIVER_BINDING_PROTOCOL gUsbSerialDriverBinding; | |
| extern EFI_COMPONENT_NAME_PROTOCOL gUsbSerialComponentName; | |
| extern EFI_COMPONENT_NAME2_PROTOCOL gUsbSerialComponentName2; | |
| // | |
| // Functions of Driver Binding Protocol | |
| // | |
| /** | |
| Check whether USB Serial driver supports this device. | |
| @param This[in] The USB Serial driver binding protocol. | |
| @param Controller[in] The controller handle to check. | |
| @param RemainingDevicePath[in] The remaining device path. | |
| @retval EFI_SUCCESS The driver supports this controller. | |
| @retval other This device isn't supported. | |
| **/ | |
| EFI_STATUS | |
| EFIAPI | |
| UsbSerialDriverBindingSupported ( | |
| IN EFI_DRIVER_BINDING_PROTOCOL *This, | |
| IN EFI_HANDLE Controller, | |
| IN EFI_DEVICE_PATH_PROTOCOL *RemainingDevicePath | |
| ); | |
| /** | |
| Starts the Serial device with this driver. | |
| This function produces Serial IO Protocol and initializes the USB | |
| Serial device to manage this USB Serial device. | |
| @param This[in] The USB Serial driver binding instance. | |
| @param Controller[in] Handle of device to bind driver to. | |
| @param RemainingDevicePath[in] Optional parameter use to pick a specific | |
| child device to start. | |
| @retval EFI_SUCCESS The controller is controlled by the USB | |
| Serial driver. | |
| @retval EFI_UNSUPPORTED No interrupt endpoint can be found. | |
| @retval Other This controller cannot be started. | |
| **/ | |
| EFI_STATUS | |
| EFIAPI | |
| UsbSerialDriverBindingStart ( | |
| IN EFI_DRIVER_BINDING_PROTOCOL *This, | |
| IN EFI_HANDLE Controller, | |
| IN EFI_DEVICE_PATH_PROTOCOL *RemainingDevicePath | |
| ); | |
| /** | |
| Stop the USB Serial device handled by this driver. | |
| @param This[in] The USB Serial driver binding protocol. | |
| @param Controller[in] The controller to release. | |
| @param NumberOfChildren[in] The number of handles in ChildHandleBuffer. | |
| @param ChildHandleBuffer[in] The array of child handle. | |
| @retval EFI_SUCCESS The device was stopped. | |
| @retval EFI_UNSUPPORTED Simple Text In Protocol or Simple Text In Ex | |
| Protocol is not installed on Controller. | |
| @retval EFI_DEVICE_ERROR The device could not be stopped due to a | |
| device error. | |
| @retval Others Fail to uninstall protocols attached on the | |
| device. | |
| **/ | |
| EFI_STATUS | |
| EFIAPI | |
| UsbSerialDriverBindingStop ( | |
| IN EFI_DRIVER_BINDING_PROTOCOL *This, | |
| IN EFI_HANDLE Controller, | |
| IN UINTN NumberOfChildren, | |
| IN EFI_HANDLE *ChildHandleBuffer | |
| ); | |
| // | |
| // Serial IO Member Functions | |
| // | |
| /** | |
| Writes data to a serial device. | |
| @param This[in] Protocol instance pointer. | |
| @param BufferSize[in, out] On input, the size of the Buffer. On output, | |
| the amount of data actually written. | |
| @param Buffer[in] The buffer of data to write | |
| @retval EFI_SUCCESS The data was written. | |
| @retval EFI_DEVICE_ERROR The device reported an error. | |
| @retval EFI_TIMEOUT The data write was stopped due to a timeout. | |
| **/ | |
| EFI_STATUS | |
| EFIAPI | |
| WriteSerialIo ( | |
| IN EFI_SERIAL_IO_PROTOCOL *This, | |
| IN OUT UINTN *BufferSize, | |
| IN VOID *Buffer | |
| ); | |
| /** | |
| Reads data from a serial device. | |
| @param This[in] Protocol instance pointer. | |
| @param BufferSize[in, out] On input, the size of the Buffer. On output, | |
| the amount of data returned in Buffer. | |
| @param Buffer[out] The buffer to return the data into. | |
| @retval EFI_SUCCESS The data was read. | |
| @retval EFI_DEVICE_ERROR The device reported an error. | |
| @retval EFI_TIMEOUT The data write was stopped due to a timeout. | |
| **/ | |
| EFI_STATUS | |
| EFIAPI | |
| ReadSerialIo ( | |
| IN EFI_SERIAL_IO_PROTOCOL *This, | |
| IN OUT UINTN *BufferSize, | |
| OUT VOID *Buffer | |
| ); | |
| /** | |
| Retrieves the status of the control bits on a serial device. | |
| @param This[in] Protocol instance pointer. | |
| @param Control[out] A pointer to return the current Control signals | |
| from the serial device. | |
| @retval EFI_SUCCESS The control bits were read from the serial | |
| device. | |
| @retval EFI_DEVICE_ERROR The serial device is not functioning correctly. | |
| **/ | |
| EFI_STATUS | |
| EFIAPI | |
| GetControlBits ( | |
| IN EFI_SERIAL_IO_PROTOCOL *This, | |
| OUT UINT32 *Control | |
| ); | |
| /** | |
| Set the control bits on a serial device. | |
| @param This[in] Protocol instance pointer. | |
| @param Control[in] Set the bits of Control that are settable. | |
| @retval EFI_SUCCESS The new control bits were set on the serial device. | |
| @retval EFI_UNSUPPORTED The serial device does not support this operation. | |
| @retval EFI_DEVICE_ERROR The serial device is not functioning correctly. | |
| **/ | |
| EFI_STATUS | |
| EFIAPI | |
| SetControlBits ( | |
| IN EFI_SERIAL_IO_PROTOCOL *This, | |
| IN UINT32 Control | |
| ); | |
| /** | |
| Calls SetAttributesInternal() to set the baud rate, receive FIFO depth, | |
| transmit/receice time out, parity, data buts, and stop bits on a serial device. | |
| @param This[in] Protocol instance pointer. | |
| @param BaudRate[in] The requested baud rate. A BaudRate value of 0 | |
| will use the device's default interface speed. | |
| @param ReveiveFifoDepth[in] The requested depth of the FIFO on the receive | |
| side of the serial interface. A ReceiveFifoDepth | |
| value of 0 will use the device's default FIFO | |
| depth. | |
| @param Timeout[in] The requested time out for a single character in | |
| microseconds.This timeout applies to both the | |
| transmit and receive side of the interface.A | |
| Timeout value of 0 will use the device's default | |
| time out value. | |
| @param Parity[in] The type of parity to use on this serial device.A | |
| Parity value of DefaultParity will use the | |
| device's default parity value. | |
| @param DataBits[in] The number of data bits to use on the serial | |
| device. A DataBits value of 0 will use the | |
| device's default data bit setting. | |
| @param StopBits[in] The number of stop bits to use on this serial | |
| device. A StopBits value of DefaultStopBits will | |
| use the device's default number of stop bits. | |
| @retval EFI_SUCCESS The attributes were set | |
| @retval EFI_DEVICE_ERROR The attributes were not able to be | |
| **/ | |
| EFI_STATUS | |
| EFIAPI | |
| SetAttributes ( | |
| IN EFI_SERIAL_IO_PROTOCOL *This, | |
| IN UINT64 BaudRate, | |
| IN UINT32 ReceiveFifoDepth, | |
| IN UINT32 Timeout, | |
| IN EFI_PARITY_TYPE Parity, | |
| IN UINT8 DataBits, | |
| IN EFI_STOP_BITS_TYPE StopBits | |
| ); | |
| /** | |
| Reset the serial device. | |
| @param This Protocol instance pointer. | |
| @retval EFI_SUCCESS The device was reset. | |
| @retval EFI_DEVICE_ERROR The serial device could not be reset. | |
| **/ | |
| EFI_STATUS | |
| EFIAPI | |
| SerialReset ( | |
| IN EFI_SERIAL_IO_PROTOCOL *This | |
| ); | |
| // | |
| // EFI Component Name Functions | |
| // | |
| /** | |
| Retrieves a Unicode string that is the user readable name of the driver. | |
| This function retrieves the user readable name of a driver in the form of a | |
| Unicode string. If the driver specified by This has a user readable name in | |
| the language specified by Language, then a pointer to the driver name is | |
| returned in DriverName, and EFI_SUCCESS is returned. If the driver specified | |
| by This does not support the language specified by Language, | |
| then EFI_UNSUPPORTED is returned. | |
| @param This[in] A pointer to the EFI_COMPONENT_NAME2_PROTOCOL | |
| or EFI_COMPONENT_NAME_PROTOCOL instance. | |
| @param Language[in] A pointer to a Null-terminated ASCII string | |
| array indicating the language. This is the | |
| language of the driver name that the caller | |
| is requesting, and it must match one of the | |
| languages specified in SupportedLanguages. | |
| The number of languages supported by a | |
| driver is up to the driver writer. Language | |
| is specified in RFC 4646 or ISO 639-2 | |
| language code format. | |
| @param DriverName[out] A pointer to the Unicode string to return. | |
| This Unicode string is the name of the | |
| driver specified by This in the language | |
| specified by Language. | |
| @retval EFI_SUCCESS The Unicode string for the Driver specified | |
| by This and the language specified by | |
| Language was returned in DriverName. | |
| @retval EFI_INVALID_PARAMETER Language is NULL. | |
| @retval EFI_INVALID_PARAMETER DriverName is NULL. | |
| @retval EFI_UNSUPPORTED The driver specified by This does not | |
| support the language specified by Language. | |
| **/ | |
| EFI_STATUS | |
| EFIAPI | |
| UsbSerialComponentNameGetDriverName ( | |
| IN EFI_COMPONENT_NAME2_PROTOCOL *This, | |
| IN CHAR8 *Language, | |
| OUT CHAR16 **DriverName | |
| ); | |
| /** | |
| Retrieves a Unicode string that is the user readable name of the controller | |
| that is being managed by a driver. | |
| This function retrieves the user readable name of the controller specified by | |
| ControllerHandle and ChildHandle in the form of a Unicode string. If the | |
| driver specified by This has a user readable name in the language specified by | |
| Language, then a pointer to the controller name is returned in ControllerName, | |
| and EFI_SUCCESS is returned. If the driver specified by This is not currently | |
| managing the controller specified by ControllerHandle and ChildHandle, | |
| then EFI_UNSUPPORTED is returned. If the driver specified by This does not | |
| support the language specified by Language, then EFI_UNSUPPORTED is returned. | |
| @param This[in] A pointer to the EFI_COMPONENT_NAME2_PROTOCOL | |
| or EFI_COMPONENT_NAME_PROTOCOL instance. | |
| @param ControllerHandle[in] The handle of a controller that the driver | |
| specified by This is managing. This handle | |
| specifies the controller whose name is to | |
| be returned. | |
| @param ChildHandle[in] The handle of the child controller to | |
| retrieve the name of. This is an optional | |
| parameter that may be NULL. It will be NULL | |
| for device drivers. It will also be NULL | |
| for a bus drivers that wish to retrieve the | |
| name of the bus controller. It will not be | |
| NULL for a bus driver that wishes to | |
| retrieve the name of a child controller. | |
| @param Language[in] A pointer to a Null-terminated ASCII string | |
| array indicating the language. This is the | |
| language of the driver name that the caller | |
| is requesting, and it must match one of the | |
| languages specified in SupportedLanguages. | |
| The number of languages supported by a | |
| driver is up to the driver writer. Language | |
| is specified in RFC 4646 or ISO 639-2 | |
| language code format. | |
| @param ControllerName[out] A pointer to the Unicode string to return. | |
| This Unicode string is the name of the | |
| controller specified by ControllerHandle | |
| and ChildHandle in the language specified | |
| by Language from the point of view of the | |
| driver specified by This. | |
| @retval EFI_SUCCESS The Unicode string for the user readable | |
| name in the language specified by Language | |
| for the driver specified by This was | |
| returned in DriverName. | |
| @retval EFI_INVALID_PARAMETER ControllerHandle is not a valid EFI_HANDLE. | |
| @retval EFI_INVALID_PARAMETER ChildHandle is not NULL and it is not a | |
| valid EFI_HANDLE. | |
| @retval EFI_INVALID_PARAMETER Language is NULL. | |
| @retval EFI_INVALID_PARAMETER ControllerName is NULL. | |
| @retval EFI_UNSUPPORTED The driver specified by This is not | |
| currently managing the controller specified | |
| by ControllerHandle and ChildHandle. | |
| @retval EFI_UNSUPPORTED The driver specified by This does not | |
| support the language specified by Language. | |
| **/ | |
| EFI_STATUS | |
| EFIAPI | |
| UsbSerialComponentNameGetControllerName ( | |
| IN EFI_COMPONENT_NAME2_PROTOCOL *This, | |
| IN EFI_HANDLE ControllerHandle, | |
| IN EFI_HANDLE ChildHandle OPTIONAL, | |
| IN CHAR8 *Language, | |
| OUT CHAR16 **ControllerName | |
| ); | |
| #endif |