fpl011.md

# FPL011 驱动程序

## 1. 概述

- 通用异步收发传输器（Universal Asynchronous Receiver/Transmitter)，通常称作UART。它将要传输的资料在串行通信与并行通信之间加以转换。作为把并行输入信号转成串行输出信号的芯片，UART通常被集成于其他通讯接口的连结上。

- 本模块目前支持FT2000-4/D2000/E2000

- 本模块可使用MIO的uart功能
## 2. 功能

- 1. 支持轮询接收发送数据 
  2. 中断接收发送数据
  3. 接收发送有独立fifo
  4. 支持回传测试模式

相关源文件为：
```
fpl011
    ├── fpl011.c
    ├── fpl011.h
    ├── fpl011_g.c
    ├── fpl011_hw.c
    ├── fpl011_hw.h
    ├── fpl011_intr.c
    ├── fpl011_options.c
    └── fpl011_sinit.c
```


## 3. 配置方法

### 参数配置

#### 通信参数配置

FPl011SetDataFormat()并将一个FPl011Format结构传递给它。FPl011Format结构应该包含所有必需的参数。参见下面的示例。

```
FPl011Format format = 
{
    u32 baudrate  = 115200;      /* In bps, ie 1200 */
    u32 data_bits = FPL011_FORMAT_WORDLENGTH_8BIT ;     /* Number of data bits */
    u32 parity    = FPL011_FORMAT_NO_PARITY ;        /* Parity */
    u8  stopbits  = FPL011_FORMAT_1_STOP_BIT ;      /* Number of stop bits */
};

FPl011SetDataFormat(&uart,&format);

```

#### Running UART Communication

- Transmitting ,此接口兼容轮询与中断模式,用户传入特定buffer，函数外通过判断标志位确认发送是否完成。

```
u8 buffer_p[10] ;
u32 len = 0 ;
len = FPl011Send(&uart,buffer_p,sizeof(buffer_p)) ;
```

- Receiving ,此接口兼容轮询与中断模式,用户传入特定buffer，函数外通过判断标志位确认发送是否完成。

```
u8 buffer_p[10] ;
u32 len = 0 ;
len = FPl011Receive(&uart,buffer_p,sizeof(buffer_p)) ;
```

## 4 应用示例

baremetal/example/uart_test

## 4. API参考

## FPl011Config *FPl011LookupConfig(u32 instance_id)

初始化特定的FPl011实例，以便它可以被使用。  
Initializes a specific FPl011 instance such that it is ready to be used.

- 参数
instance_id 是对应驱动的编号


- Parameters

instance_id  contains the ID of the device

- 返回

FPl011Config *指向配置结构的指针，如果指定的设备不在系统中，则为NULL。 


- Return

FPl011Config *A pointer to the configuration structure or NULL if the specified device is not in the system.


## u32 FPl011Send(FPl011 *uart_p, u8 *byte_p, u32 length)

这个函数使用设备发送指定的缓冲区，采用轮询或中断驱动模式。  

This functions sends the specified buffer using the device in either
 polled or interrupt driven mode.


- 参数

uart_p 是指向FPl011实例的指针。
byte_p 是指向要发送的数据缓冲区的指针。 
length 表示发送的字节数。任何已经放入传输FIFO的数据将被发送。  

- Parameters 
uart_p  is a pointer to the FPl011 instance.
byte_p  is pointer to a buffer of data to be sent.
length  contains the number of bytes to be sent. Any data that was already put into the transmit FIFO will be sent.

- 返回

实际发送的字节数。


- Return

The number of bytes actually sent.

## u32 FPl011Receive(FPl011 *uart_p, u8 *byte_p, u32 length)

此函数尝试从设备接收指定字节数的数据，并将其存储到指定的缓冲区中。

This function attempts to receive a specified number of bytes of data from the device and store it into the specified buffer.

- 参数

uart_p 是指向FPl011实例的指针  
byte_p 是用于接收数据的缓冲区指针  
length 表示接收的字节数。  

- Parameters 

uart_p is a pointer to the FPl011 instance
byte_p is pointer to buffer for data to be received into
length is the number of bytes to be received. 

- 返回

接收的字节数。

- Return

The number of bytes received.


## void FPl011ProgramCtlReg(FPl011 *uart_p,u32 ctrl_reg)

 This function reprograms the control register according to the following
 sequence mentioned in the TRM

- 参数
uart_p 是指向FPl011实例的指针  
ctrl_reg 想要被写入的控制寄存器的参数

 - Parameters 

uart_p is a pointer to the FPl011 instance
ctrl_reg value to be written



## void FPl011SetOperMode(FPl011 *uart_p,u8 operation_mode)

该函数设置UART的操作模式。 UART可以操作  两种模式之一:正常模式、本地环回模式。 

This function sets the operational mode of the UART. The UART can operate
 in one of four modes: Normal, Local Loopback.

- 参数

uart_p是指向FPl011实例的指针。

operation mode为UART模式。

- Parameters 

 uart_p is a pointer to the FPl011 instance.

 operation_mode is the mode of the UART.

## void FPl011SetSpecificOptions(FPl011 *uart_p, u32 options)

为指定的驱动程序实例设置选项。  

Sets the options for the specified driver instance. 

- Parameters 

uart_p是指向FPl011实例的指针。

uart_p is a pointer to the FPl011 instance.

options contains the options to be set which are bit masks contained in the file FPl011_uart.h and named FUART_OPTION_*.


## void FPl011ClearSpecificOptions(FPl011 *uart_p, u32 options)


清除指定驱动程序实例的选项。  

Clear the options for the specified driver instance. 

- 参数

uart_p是指向fpl011实例的指针。

options 包含要设置的选项，这些选项是包含在文件FPl011_uart.h和名为FUART_OPTION_*的位掩码。  

- Parameters

uart_p is a pointer to the fpl011 instance.

options contains the options to be set which are bit masks contained in the file FPl011_uart.h and named FUART_OPTION_*.

## FError FPl011SetBaudRate(FPl011 *uart_p, u32 baudrate)

设置设备波特率。

Sets the baud rate for the device.

- 参数

uart p是指向FPl011实例的指针

BaudRate 所要设置波特率

- Parameters

uart_p is a pointer to the FPl011 instance

BaudRate to be set

- 返回

如果一切都按照预期配置，则返回FT_SUCCESS  

如果请求的速率不可用，则返回FPL011_ERROR_PARAM

- Return

  FT_SUCCESS if everything configured as expected

  FPL011_ERROR_PARAM if the requested rate is not available
  because there was too much error

## void FPl011GetDataFormat(FPl011 *uart_p,FPl011Format *format_p) 

获取指定UART的数据格式。

Gets the data format for the specified UART. 

- 参数

uart_p 是指向fpl011实例的指针。

format_p 是一个指向格式结构的指针，该结构将在调用完成后包含数据格式。

- Parameters

uart_p    is a pointer to the fpl011 instance.

format_p  is a pointer to a format structure that will contain the data format after this call completes.

## FError FPl011SetDataFormat(FPl011 *uart_p,FPl011Format *format_p)

将需要的参数格式，设置至特定的串口驱动中

Sets the data format for the specified UART. 

- 参数

Uart_p 是指向fpl011实例的指针。

format_p 是一个指向格式结构的指针，该结构将在调用完成后包含数据格式。 

- Parameters

uart_p    is a pointer to the fpl011 instance.

format_p  is a pointer to a format structure that will contain the data format after this call completes.

- 返回

  如果一切都按照预期配置，则使用FT_SUCCESS  
  如果其中一个参数无效，则返回FPL011_ERROR_PARAM

- Return

  FT_SUCCESS if everything configured as expected
  FPL011_ERROR_PARAM if one of the parameters was not valid.


## void FPl011SetTxFifoThreadHold(FPl011 *uart_p, u8 trigger_level)

这个函数设置Tx FIFO触发器级别为'TriggerLevel'参数。

This functions sets the Tx FIFO trigger level to the 'TriggerLevel' argument.

- 参数

uart_p 是指向fpl011实例的指针。
Trigger_level包含要设置的触发器级别。 这个值从0-32 (FPL011IFLS_TXIFLSEL_1_8 - FPL011IFLS_TXIFLSEL_7_8)  


- Parameters

uart_p is a pointer to the fpl011 instance.

trigger_level contains the trigger level to set. This is a value from 0-32  (FPL011IFLS_TXIFLSEL_1_8 - FPL011IFLS_TXIFLSEL_7_8)


## void FPl011SetRxFifoThreadhold(FPl011 *uart_p, u8 trigger_level)

这个函数将Rx FIFO触发器级别设置为'TriggerLevel'参数。  

This functions sets the Rx FIFO trigger level to the 'TriggerLevel' argument.

- 参数

uart_p 是指向fpl011实例的指针。
Trigger_level包含要设置的触发器级别。 这个值从0-32 (FPL011IFLS_RXIFLSEL_1_8 - FPL011IFLS_RXIFLSEL_7_8)  

- Parameters

uart_p is a pointer to the fpl011 instance.

trigger_level contains the trigger level to set. This is a value from 0-32  (FPL011IFLS_RXIFLSEL_1_8 - FPL011IFLS_RXIFLSEL_7_8)

## u32 FPl011GetInterruptMask(FPl011 *uart_p)

这个函数获取中断掩码。

This function gets the interrupt mask.

- 参数

uart_p是指向PFl011实例的指针

- Parameters

uart_p is a pointer to the PFl011 instance


## void FPl011SetInterruptMask(FPl011 *uart_p, u32 mask)

这个函数设置中断掩码。

This function sets the interrupt mask.

- 参数

uart_p是指向PFl011实例的指针

mask包含要启用或禁用的中断。 '1'启用中断，'0'禁用中断。  

- Parameters

uart_p is a pointer to the PFl011 instance

mask contains the interrupts to be enabled or disabled. A '1' enables an interrupt, and a '0' disables.