.. _tools-lec:

tools lec 工具
======================

.. toctree::
   :maxdepth: 1

lec 工具概述
::::::::::::::::

tools lec 工具用于判断两个输入的 verilog 文件或项目是否逻辑等价. 这两个输入文件或项目被称作 REVISED 和 GODLEN.
此外, tools 工具还支持指定 file_list 文件, 以满足特殊的 src 可能会指定 file 的情况. 若未指定 file_list 文件时,
若 GOLDEN 或 REVISED 输入是目录, 则尝试在输入目录下寻找默认的 file_list 文件 "file_list.txt"

lec 工具基础使用教程
:::::::::::::::::::::::::

tools lec 工具最简单的用法是直接提供 REVISED 和 GOLDEN 文件(或目录), lec 工具将其上传到 rpc 服务主机并返回
一个 lec 脚本和一个 lec report 文件, 并在命令行中回显此次 lec 检查结果. 其示例如下:

.. code:: 

   # 存在一个放有 Verilog 文件的目录, 该文件(或目录)作为 golden
   ls golden
   # golden_file.v

   # 存在一个放有 verilog 文件的目录, 该文件(或目录)作为 revised
   ls revised
   # revised_file.v

   # 调用 lec 工具
   tools lec golden/golden_file.v revised/revised_file.v

   # 当输入是 dir 时, 会读入该目录下所有 verilog 文件, 当存在 file_list 时, 按 file_list 读入.
   tools lec golden revised
   tools lec golden/golden_file.v revised
   tools lec golden revised/revised_file.v

效果图如下:

.. image:: ../images/tools_lec.png

lec 工具进阶使用教程
:::::::::::::::::::::::::

tools lec 工具的 help 文档如下:

.. code:: bash

   [root@dev02 Thor]$ tools lec --help
   Usage: tools lec [OPTIONS] REVISED GOLDEN

   call lec check by RPC

   Options:
   --platform TEXT           specify the platform for lec
   --revised_file_list TEXT  specify the file_list for revised
   --golden_file_list TEXT   specify the file_list for golden
   --record                  Keep case file and lec info in server
   --script TEXT             specify the script for lec.
   --help                    Show this message and exit.

-\-platform 参数
------------------------------

用于指定此次 lec 校验使用的 lib 库, 默认为 nangate45, 当输入中存在网表时, 一般需要指定为该网表对应的 lib 库.

.. code:: 

   # eg: 使用 tsmc65 的 lib 库
   tools lec src netlist.v --platform tsmc65

-\-revised_file_list 参数
------------------------------

revised_file_list 参数用于指定 revised 使用的 file_list 文件, 一般用于用户调试 Thor 代码时需要使用自己编写
的 file_list 文件. 当不使用该参数时, 若 REVISED 输入是 dir, 则默认尝试在 REVISED 下寻找 file_list.txt 文件.

-\-golden_file_list 参数
------------------------------

golden_file_list 参数用于指定 golden 使用的 file_list 文件, 一般用于用户调试 Thor 代码时需要使用自己编写
的 file_list 文件. 当不使用该参数时, 若 GODLEN 输入是 dir, 则默认尝试在 GOLDEN 下寻找 file_list.txt 文件.

-\-record 参数
------------------------------

指定服务器是否保存本次 lec rpc 调用的相关数据, 否则服务器将在本次 lec 执行完成并返回结果后删除本次 case 等
数据, 一般仅用于调试, 用户使用时不需要开启.

-\-script 参数
------------------------------

指定本次 lec 使用的脚本, 一般来说无需指定, lec 会自动生成相关的脚本, 若有更改的需求, 建议用户在生成的脚本上进行
修改以满足自己的需求.

-\-help 参数
------------------------------

查看 help 文档, 其指令如下:

.. code:: 

   tools lec --help

自定义 lec server IP & port
::::::::::::::::::::::::::::::::::

tools lec 是一个 RPC 接口, 该接口的调用需要一个可提供 lec rpc server 的服务器. rpc server 也是 tools 工具
包中的一个工具, 由 tools rpc-server 可以启动. 启动后, 使用该 rpc server 需要在配置文件中或使用 -\-config更
改 lec rpc 调用本次 rpc-server 启动时指定的 IP 和端口. 其具体流程如下:

1. 启动一个 rpc-server.

.. include:: tools-rpc-server.rst

1. 调用 lec rpc 时, 指定 rpc-server 的 IP 和端口.

有多种方式可以指定 lec rpc 的 IP 和端口, 详情可参考如下链接:

* :ref:`使用 --config 参数控制控制 lec(maat). <option_maat_ymal>`
* :ref:`使用配置文件控制 lec rpc 调用的 IP 和 PORT(maat). <maat_config_file>`
* :ref:`使用 --config 参数控制控制 lec(nabu). <option_maat_ymal>`
* :ref:`使用配置文件控制 lec rpc 调用的 IP 和 PORT(nabu). <nabu_config_file>`

.. code:: bash

   # 使用 --config 指定 lec rpc 调用的 IP 和端口
   tools rpc revised.v golden.v --config lec.IP=192.168.15.200 --config lec.PORT=12345