Proper use of RS232 module

[podhrmic]

Hello,
I have a question about the proper use of the RS232 module. In my top level module, I can instantiate it with for example UART #(4) uart <- mkUART(8, NONE, STOP_1, 16);, but it is not clear to me how to connect the sin and sout actions of the RS232 interface to the actual pins on the FPGA board.

I am using uart.tx.get(); and uart.rx.put(val); to get/put a character, but I still need to assign the IO pins, as mentioned above.

Do you have a minimal example of using this interface?

[quark17]

An interface (or subinterface) of an instantiated submodule can be directly assigned as the interface of the parent module. For example, this line:

  interface rs232 = uart.rs232;

in the following (abridged) example:

interface FPGA_Top_Ifc;
   (* prefix = "" *)
   interface RS232 rs232;
   (* prefix="PCIE" *)
   interface PCIE_EXP#(8) pcie;
   (* always_ready *)
   method Bit#(8) leds();
endinterface

(* synthesize, no_default_clock, no_default_reset *)
module fpga_top #(Clock sys_clk_p, Clock sys_clk_n,
               Clock pci_sys_clk_p, Clock pci_sys_clk_n,
               Reset pci_sys_reset_n)
              (FPGA_Top_Ifc);

  Clock sys_clk <- mkClockIBUFDS(..., sys_clk_p, sys_clk_n);

  PCIE pcie <- mkPCIE(...);

  UART uart <- mkUART(...);

  ...

  interface rs232 = uart.rs232;

  interface pcie = pcie.exp;

  method leds = zeroExtend({ is_link_up, is_out_of_reset });

endmodule

Is that what you're asking?

[rsnikhil]

I think the answer to Michal's question has two parts:

(1) One has to bring the UART 'sin' and 'sout' interfaces out to the
top-level of the design. Julie's response addresses this
"plumbing" question.

(2) The top-level of the design has to be connected to FPGA pins.
This will be an FPGA-vendor specified mechanism, and will likely
be the same for all top-level i/o signals.

Not sure whether Michal is asking about (1), or (2), or both?

Also, Michal may also want to consider using a vendor-supplied IP for
the UART itself (you can instantiate it in a top-level Verilog, or
inside the BSV design using import BVI).

[podhrmic]

Thanks @rsnikhil and @quark17 for the answers!
I was actually asking about both - I need to deploy a Bluespec SoC design to a Lattice FPGA and I couldn't find a good example to follow.
What I am hearing is that mkTop module doesn't map 1:1 to a verilog top level module. mkTop always has an empty interface. So in the example above, I need to do something like:

module mkTop (Empty)
...
FPGA_Top_Ifc fpga = mkFPGA_Top(...)

I have a constraints file, when I assign the pins - so once I know the names of the top level wires, I can assign them.

On a related note - how do you deal with complex clock setup? I need to use a specific PLL, and I have a verilog module (here - is using BVI still the best way, even if I need to get only a clock signal?

[rsnikhil]

What I am hearing is that mkTop module doesn't map 1:1 to a verilog
top level module. mkTop always has an empty interface.

[Caveat re. my comments: I'm not an expert on this topic of connecting to FPGA pins; usually someone else has done this and I've just used it.]

On an FPGA device, the upper-level of module hierarchy is often like this:

Verilog top-level module    (signal interfaces connect to pins)
    (Verilog of) BSV top-level module
    Other Verilog modules, often from FPGA vendor's IP library (such as clock generators, UARTs, DRAM interfaces, ...)

If the BSV top-level contains everything, it can directly be the FPGA top-level

(Verilog of) BSV top-level module (signal interfaces connect to pins)

In either case, the BSV top-level module's interface is not Empty.

Note: when we simulate the BSV top-level module, we give it a wrapper that will have an Empty interface.

In Julie's and my previous comments, the point about "plumbing" the UART pins out to the module interface is to bring those signals up to the BSV top-level module's interface.

On a related note - how do you deal with complex clock setup? I
need to use a specific PLL, and I have a verilog module (here -
is using BVI still the best way, even if I need to get only a
clock signal?

I don't have direct experience with this. Let me forward your question to others at Bluespec, some of whom may have worked with Lattice FPGAs.

[quark17]

Let me briefly answer these three questions, which I will also answer in more detail below by expounding on the code example that I gave.

What I am hearing is that mkTop module doesn't map 1:1 to a verilog top level module. mkTop always has an empty interface.

No, a BSV module with no interface will produce Verilog with no ports, which isn't helpful for synthesis! (If you're doing simulation, that's the only time you'd make a BSV module with no interface, where the top level is stimulating a design instantiated within.)

I have a constraints file, when I assign the pins - so once I know the names of the top level wires, I can assign them.

One thing you can do is just synthesize your design to Verilog and you'll see what the ports are called! However, the names are generated predictably based on the BSV names and applying any renaming attributes (in the BSV source) that have been attached to the interface or to the module.

I believe the User Guide has a section on what the generated Verilog looks like (and the correlation of names to source). If you haven't read that section, I'd suggest having a look, because you'll want to get to a point, as a BSV coder, where you know what Verilog you are getting when you write the BSV.

There is also a BSV Ref Guide, which is more about the language, and it has documentation about the renaming attributes.

On a related note - how do you deal with complex clock setup? I need to use a specific PLL, and I have a verilog module (here - is using BVI still the best way, even if I need to get only a clock signal?

Yes, if the FPGA/synthesis vendor has provided a module/macro, then use "import-BVI" to make it instantiable in your BSV.

This import should only need to be done once, though, and then anyone who is making BSV designs for that FPGA can use the same import. For example, our bsc-contrib repo has a directory Libraries/FPGA/ and under that is a Xilinx directory with some imports that we've developed in the past. If you create anything for Lattice, feel free to submit a PR to add a new Lattice subdirectory with those files.

Of course, you can always instantiate the IP in a top-level hand-written Verilog, and that Verilog is a wrapper that then instantiates the top-level of your BSV and connects up the output clock to your design -- if you prefer. But we've generally done everything directly in BSV, for Xilinx boards.

In the code example I gave before, I have shown you the BSV module that generates the top-level Verilog file that you feed to the synthesis tool as the top file for the FPGA. The top-level Verilog that BSC generates has ports like this:

(
 // System clock pair
 sys_clk_p,
 sys_clk_n,
 // PCI clock pair
 pci_sys_clk_p,
 pci_sys_clk_n,
 // PCI reset
 pci_sys_reset_n,
 // UART pins
 SIN,
 SOUT,
 // PCIE tx/rx pairs
 PCIE_rxp,
 PCIE_rxn,
 PCIE_txp,
 PCIE_txn,
 // LEDs
 leds
)

The names of these ports are controlled by the BSV source -- you can see some of this in the attributes in the interface. If your synthesis tool can infer connections based on names, then you can change the source to provide different names. Or, you can always write a Verilog module that wraps about the one generated by BSC.

Even though I've written the BSV to declare the _p and _n signals as clocks, they are not clocks as BSC expects them. They need to go through a PLL or other IP to generate an oscillator for BSC. This can be done in a Verilog wrapper around the BSV top module, but it can also be done in BSV, using "import-BVI" to bring vendor IP into BSV. That's what I've shown in my example, in two ways.

My example is based off Xilinx, which is what I am familiar with. First I create a clock from the "sys_clk" pairs, by instantiating Xilinx's IBUFDS macro:

Clock sys_clk <- mkClockIBUFDS(..., sys_clk_p, sys_clk_n);

The "import-BVI" declaration for this can be seen in the bsc-contrib repo, in Libraries/FPGA/Xilinx/XilinxCells.bsv.

Second, the PCI raw clock and reset signals are fed into a Xilinx PCIe endpoint block. This block has input for the clocks and resets from the FPGA pins; and it has outputs for the TX/RX pairs that also connect to the pins; but it also provides an interface to the user, for sending and receiving bytes of data, and it provides the user with a clock oscillating at the speed of that data. (In fact, Xilinx's PCIe macro can generate several speeds of user clock for you.) So this instantiation is producing an interface that also includes user clocks and resets (although I haven't shown their use):

PCIE pcie <- mkPCIE(...);

And this, too, is an "import-BVI" of Verilog from Xilinx.

As Nikhil said, I probably also want to instantiate UART IP from Xilinx, so this line, too, is likely to be an "import-BVI":

UART uart <- mkUART(...);

With Xilinx, I have to specify the pin connections in a file provided separately to the synthesis tool. And also, in my Tcl scripts for synthesis, I have to specify information about the clocks (and that the timing constraint doesn't apply to logic in different domains etc). (Although these can also be done via GUI.)

Once you generate Verilog from the BSV, you work with it the same way that you would a Verilog design. If there are situations with name in the generated Verilog that you don't know how to predictably determine from the source (or how to ask BSC/Bluetcl to compute the generated name for you), then feel free to ask about those specific situations.

[podhrmic]

Thanks! I now got the design working on an FPGA - blinks LEDs and sends data over UART. However, I am a bit puzzled by the RS232 baud generator. Unlike some other UART modules, it has only one divisor to set the baud rate (which is manageable, although limiting). The odd thing is that on my system with 12MHz input clock (verified with a scope), and a divisor of 10 I get an effective baudrate of 76800, instead of the expected 1.2Mbaud (which is not a standard baud rate). This is independent of the CPU, in fact even without a CPU I get this result. Is there something I am missing about how to use the RS232 module, or why would there be such discrepancy in the frequency?