UHD FPGA Coding Standards

• UHD FPGA Coding Standards
  
  • Preamble序言
  • General Coding Guidelines
  • Verilog Style Guidelines
    
    • General Syntax
    • Assignments
    • Modules
    • Clocking and Resets
    • Parameters, defines and constants
    • AXI Specific
  • Design Best Practices

USRP hardware driver (Universal Software Radio Peripheral#Software), the device driver used with the USRP product family

Preamble序言

To quote R. W. Emerson: “A foolish consistency is the hobgoblin of little minds,adored by little statesmen and philosophers and divines”. Ignoring the little statesmen for a minute, these coding standards are here to make our life easier, not simply add additional rules. They are meant as additional guidance for developers, and are not meant to be interpreted as law.

用r·w·爱默生的话来说:“愚蠢的一致性是小心灵的妖怪，被小政治家、哲学家和神学家崇拜。”忽略小政治家一分钟，这些编码标准是为了让我们的生活更轻松，而不是简单地添加额外的规则。它们是为开发人员提供的附加指导，不应该被解释为法律。

So, ultimately, it is up to the developer to decide how much these guidelines should be heeded when writing code, and up to reviewers how much they are relevant to new submissions.

因此，最终，由开发人员决定在编写代码时应该注意多少这些指导原则，并由评审人员决定它们与新提交的内容有多大关系。

That said, a consistent codebase is easier to maintain, read, understand, and extend. Choosing personal preferences over these coding guidelines is not a helpful move for the team and future maintainability of the UHD FPGA codebase.
也就是说，一致的代码基更容易维护、读取、理解和扩展。选择个人偏好而不是这些编码指南，对团队和UHD FPGA代码库未来的可维护性没有帮助。

General Coding Guidelines

• Code layout: We use 2 spaces for indentation levels, and never tabs.
• Never submit code with trailing whitespace.
• Code is read more often than it’s written. Code readability is thus something worth optimizing for.
• Try and keep line lengths to 79 characters, unless readability suffers.
• Comment your code. Especially if your code is tricky or makes unique assumptions.
• Use the following header at the top of each file:
  

  • 代码布局:缩进级别使用2个空格，不使用制表符。
    
  • 不要提交带有尾空格的代码。
    
  • 代码被读得比写得多。因此，代码可读性是一种东西,值得优化的。
    
  • 尽量保持行长度为79个字符，除非可读性受到影响。
    
  • 注释你的代码。特别是如果你的代码很复杂或者做出了独特的假设。
    
  • 在每个文件的顶部使用以下标题:

  
  

//
// Copyright <YEAR> Ettus Research, A National Instruments Company
//
// SPDX-License-Identifier: LGPL-3.0
//
// Module: <MODULE_NAME>
// Description:
// <DESCRIPTION>

Verilog Style Guidelines

General Syntax

• Always use beginand end statements for more complex code blocks even if the enclosing code is only one line.
  

  对于更复杂的代码块，始终使用’ begin ‘和’ end ‘语句，即使所包含的代码是唯一的一行。

• Indent begin/end as follows:

if (foo) begin
  // Do something
end else if (bar) begin
  case(xyz)
    1'b0: begin
      // Handle 0
    end
    default: begin
      // Handle 1
    end
  endcase
end else begin
  // Do nothing
end

• Instantiate and declare modules as follows:
  

  实例化和声明模块如下。

dummy_module #(
  .PARAM1(0), .PARAM2(1)
) inst (
  .clk(clk), .rst(rst)
);

Assignments

• Sequential blocks must only have non-blocking assignments (<=)
• Combinational blocks should only have blocking assignments (=)
• Don’t mix blocking and non-blocking assignments
  

  顺序块 必须只有非阻塞赋值(’ <= ‘)
  组合逻辑应该只有阻塞分配(’ = ‘)
  不要将阻塞和非阻塞任务混合在一起

Modules

• Each module should be defined in a separate file
• Use Verilog 2001 ANSI-C style port declarations
  

  每个模块应该在单独的文件中定义
  使用Verilog 2001 ANSI-C风格的端口声明

(
  ...
  output reg  foo,
  input  wire bar
);

• Declare inputs and outputs one per line. This makes searching and commenting easier.
• Add inline comments to input/output ports to describe their behavior
• Be explicit about whether an input or output is a wire or reg.
• Group signals logically instead of by direction. If a single AXI-Stream bus has multiple inputs and outputs, keep them together.
• Instantiate all ports for a module even if they are tied off or unconnected. Don’t let the compiler insert values for any signals automatically.

dummy_module inst (
  .clk(clk), .rst(1'b0), .status(/* unused */)
);

• Don’t instantiate modules using positional arguments. Use the dot form illustrated above.
• Every module requires a header giving a synopsis of its function below the copyright header.

每一行声明一个输入和输出。这使得搜索和注释更容易。
将内联注释添加到输入/输出端口，以描述它们的行为
明确输入或输出是wire还是 reg。
按逻辑而不是按方向对信号进行分组。如果AXI信号总线有多个输入和输出,把它们放在一起。
实例化模块的所有端口，即使它们被绑定或断开连接。不要让编器自动为任何信号插入值。
不要使用位置参数实例化模块。使用上面所示的点形式。
每个模块都需要一个标题，在版权标题下提供其功能的概要。

Clocking and Resets

• Name clocks as clk. If there are multiple clocks then use a prefix like bus_clk and radio_clk.
• If a module has signals or input/outputs whose clock domain is not obvious, use a clock suffix to be explicit about the domain, for example axi_tdata_bclk, axi_tdata_rclk.
• Try not to encode the frequency of the clock in the name unless the particular clock can never take on any other frequency.
• Name resets as rst. If there are multiple clocks then use a prefix like bus_rst and radio_rst.
• If a reset is asynchronous, call it arst.
• Try to avoid asynchronous resets as much as possible.
• Don’t active low resets unless it is used to drive IO.

Parameters, defines and constants

• Parametrize modules wherever possible, especially if they are designed for reuse. Bus widths, addresses, buffer sizes, etc are good candidates for parametrization.
• For modules with parameters, add inline comments to describe the behavior of each parameter
• Propagate parameters as far up the hierarchy as possible as long as it makes sense.
• Place `define statements in Verilog header file (.vh) and include them in modules.
• Avoid placing `define statements in modules
• For local parameters, use localparam instead on hard-coding things like widths, etc.

尽可能地参数化模块，特别是如果它们是为重用而设计的。总线宽度、地址、缓冲区大小等都是参数化的很好的候选者。
对于具有参数的模块，添加内联注释来描述每个参数的行为
尽可能在层次结构上传播参数，只要它有意义

AXI Specific

We heavily use AXI buses in the design so here are some best practices for those:
* Keep the components of an AXI-Stream or AXI-MM bus together in port/wire instantiations
* For module ports, use the master/slave naming convention as shown below. It makes connecting modules easier because a master always connects to a slave

  input  wire [63:0] s_axis_tdata,
  input  wire        s_axis_tlast,
  input  wire        s_axis_tvalid,
  output wire        s_axis_tready,
  output reg  [63:0] m_axis_tdata,
  output reg         m_axis_tlast,
  output reg         m_axis_tvalid,
  input  wire        m_axis_tready,

• For connections between a master and slave, do not use the master/slave convention. Name the bus based on its function or underlying data.
• >我们在设计中大量使用AXI总线，因此这里有一些最佳实践。
  

在端口/线实例化中保持AXI-Stream或AXI-MM总线的组件在一起
对于模块端口，使用主/从命名约定，如下所示。它使得连接模块更容易，因为一个主总是连接到一个从。
对于master和slave之间的连接， 不要使用主/从约定。基于其功能和源数据来命名总线。

  wire [63:0] axis_eth2xbar_tdata,
  wire        axis_eth2xbar_tlast,
  wire        axis_eth2xbar_tvalid,
  wire        axis_eth2xbar_tready,

  // If "axis" is obvious, drop the prefix
  wire [63:0] samp_tdata,
  wire        samp_tlast,
  wire        samp_tvalid,
  wire        samp_tready,

Design Best Practices

TBD