GEN_AMBA_2021

gen_amba is a set of programs that generate AMBA bus Verilog-HDL, which include AMBA AXI, AMBA AHB, and AMBA APB.

gen_amba_axi: AMBA AXI bus generator for multi-master and multi-slave

AMBA AXI4 and AXI3

gen_amba_ahb: AMBA AHB bus generator for multi-master and multi-slave

gen_amba_apb: AMBA APB bus-bridge generator for AMBA AXI or AHB

Note that it is a new version of 'gen_amba' (https://github.com/adki/gen_amba).
Note there are AXI4-to-AXI3 and AXI3-to-AXI4 in *gen_amba_axi/verification/ip'.

Click to expand table of contents

Quick start for AMBA AXI and AHB
1.1 Quick start for AMBA AXI
1.2 Quick start for AMBA AHB
GEN_AMBA
2.1 gen_amba_axi
2.2 gen_amba_ahb
2.3 gen_amba_apb
GEN_TOP
3.1 GEN_TOP for AMBA AXI
3.2 GEN_TOP for AMBA AHB
3.3 GEN_TOP for AMBA APB
Bus tasks
4.1 AMBA AXI Bus tasks
4.2 AMBA AHB Bus tasks
Where to get more information
Where it has been used
Other things

License

This is licensed with the 2-clause BSD license to make the program and library useful in open and closed source products independent of their licensing scheme.

Prerequisites

This program requires followings.

Shell: Bash
GNU GCC: C compiler
HDL simulator: Xilinx Vivado simulator, icarus Verilog, or Mentor Graphics ModelSim

Maturity

RTL simulation
FPGA proven (refer to CON-FMC)
ASIC partially proven, but not whole yet

Limitations

For AMBA AXI, master should be 2 or larger and slave should be 2 or larger.

1. Quick start for AMBA AXI and AHB

1.1 Quick start for AMBA AXI

1.1.1 generating AMBA AXI

Click to expand

go to 'gen_amba_axi' directory
$ cd gen_amba_axi
run Makefile
$ make cleanup
$ make
. It should generate 'gen_amba_axi'.
have a look the help message
$ ./gen_amba_axi -h
generate AMBA AXI
$ ./gen_amba_axi --master=2 --slave=3 --output=amba_axi_m2s3.v
. It generates an AXI bus ("amba_axi_m2s3.v") with 2 master-ports and 3 slave-ports.

1.1.2 verification AMBA AXI

go to 'gen_amba_axi/verification/sim/xsim' directory
$ cd gen_amba_axi/verification/sim/xsim
. Use 'iverilog' for Icarus Verilog.
run Makefile
$ make cleanup
$ make MST=2 SLV=3
. It should generate necessary bus and top model and then invoke HDL simulator.
. It uses top-level generator.
have a look the result VCD wave
$ gtkwave wave.vcd

1.1.3 change verification configuration

how to change the number of masters and slaves
- modify 'MST' and 'SLV' macro in the 'Makefile' in 'gen_amba_axi/verification/sim/xsim' directory or
- set command-line option of 'make' as follows
  $ make MST=3 SLV=3
how to change width of address and data
- modify 'WIDTH_AD' and 'WIDTH_DA' macros in 'sim_define.v' in 'gen_amba_axi/verification/sim/xsim' directory
how to change testing scenario
- set 1 for the verilog plus command-line argument in the 'Makefile' in 'gen_amba_axi/verification/sim/xsim' directory
  [xsim case] -testplusarg BURST_TEST=1
  [iverilog case] +BURST_TEST=1
  [ModelSim case] +BURST_TEST=1
how to add new testing scenario
- add your scenario in the 'axi_tester.v' file in the 'gen_amba_axi/verification/ip' directory, where you can find some testing scenarios.
- there is AMBA AXI task library in the 'gen_amba_axi/verification/ip/axi_master_tasks.v'.

1.2. Quick start for AMBA AHB

1.2.1 generating AMBA AHB

Click to expand

go to 'gen_amba_ahb' directory
$ cd gen_amba_ahb
run Makefile
$ make cleanup
$ make
. It should generate 'gen_amba_ahb'.
have a look the help message
$ ./gen_amba_ahb -h
generate AMBA AHB
$ ./gen_amba_ahb --mst=2 --slv=3 --out=amba_ahb_m2s3.v
. It generates an AHB bus ("amba_ahb_m2s3.v") with 2 master-ports and 3 slave-ports.

1.2.2 verification AMBA AHB

go to 'gen_amba_ahb/verification/sim/xsim' directory
*$ cd gen_amba_ahb/verification/sim/xsim* . Use 'iverilog' for Icarus Verilog.
run Makefile
$ make cleanup
$ make MST=2 SLV=3
. It should generate necessary bus and top model and then invoke ModelSim simulator.
. It uses top-level generator.
have a look the result VCD wave
$ gtkwave wave.vcd

2. GEN_AMBA

There is AMBA bus generator for each bus.

2.1 gen_amba_axi

It generates AMBA AXI switch.

Click to expand

$ ./gen_amba_axi -h
[Usage] ./gen_amba_axi [options]
	-M,--master=num   num of masters (default: 2)
	-S,--slave=num    num of slaves  (default: 2)
	-D,--module=str   module name (default: "amba_axi_mXsY")
	-P,--prefix=str   prefix of module (default: none)
	-O,--output=file  output file name (stdout if not given)
	-3,--axi3         force to use AXI3 (AIX4 by default, if not given)
	-g,--verbose=num  verbose level  (default: 0)
	-v,--version      print version
	-l,--license      print license message
	-h                print help message

'--prefix' option makes use of prefix for the internal modules and this enables to use multiple AXI buses in the same design by preventing from warning of multiple definition modules.

'--axi3' option forces to generate AMBA AXI3, which uses 'AxLENG[3:0]', 'AxLOCK[1:0]', and 'WID[..]', while without '--axi3' option 'gen_amba_axi' generates AMBA AXI4.


AMBA AXI internal structure

2.2 gen_amba_ahb

It generates AMBA AHB bus.

Click to expand

$ ./gen_amba_ahb -h
[Usage] ./gen_amba_ahb [options]
	-T,--lite         AMBA AHB-lite
	-M,--master=num   num of masters (default: 2)
	-S,--slave=num    num of slaves  (default: 2)
	-D,--module=str   module name (default: "amba_ahb_mXsY")
	-P,--prefix=str   prefix of module
	-O,--output=file  output file name (stdout if not given)
	-g,--verbose=num  verbose level  (default: 0)
	-v,--version      print version
	-l,--license      print license message
	-h                print help message

	note: amba_ahb_lite_s? for -M 1

'--prefix' option makes use of prefix for the internal modules and this enables to use multiple AHB buses in the same design by preventing from warning of multiple definition modules.


AMBA AHB internal structure

2.3 gen_amba_apb

It generates AMBA APB bus bridge for AHB or AXI.

Click to expand

$ ./gen_amba_apb -h
[Usage] ./gen_amba_ahb [options]
	-X|H,--axi|ahb    make "axi_to_apb" or "ahb_to_apb" (axi if not given)
	-S,--slave=num    num of APB ports  (default: 2)
	-D,--module=str   module name (default: "axi_to_apb_sX" or "ahb_to_apb_sX")
	-P,--prefix=str   prefix of sub-module name (none if not given)
	-O,--output=file  output file name (stdout if not given)
	-g,--verbose=num  verbose level  (default: 0)
	-v,--version      print version
	-l,--license      print license message
	-h                print help message

'--prefix' option makes use of prefix for the internal modules and this enables to use multiple APB buses in the same design by preventing from warning of multiple definition modules.


AMBA APB bus bridge

3. GEN_TOP

There is top-level generator for each bus in 'verification' directory.

3.1 GEN_TOP for AMBA AXI

go to 'gen_amba_axi/verification'
$ cd gen_amba_axi/verification
have a look the help message
$ ./gen_axi_top.sh -h
generate a top-level
$ ./gen_axi_top.sh -mst 2 -slv 2 -siz 1024 -out top.v
. It generates a top-level verilog ("top.v") supporting two AXI masters and two AXI memories.
. Each memory takes care of 1Kbyte range of memory; i.e., memory0 covers 0-1023 and memory1 covers 1024-2047.

Click to expand

$ ./gen_axi_top.sh -h
Usage : ./gen_axi_top.sh [options]
      -mst    num        :num of masters, 2
      -slv    num        :num of slaves, i.e., memories, 2
      -axi3              :force to use AXI3 (to use AXI4, not specify)
      -siz    bytes      :size of each slave in bytes, 0; 0 for auto
      -bus    module     :name of bus, 
      -out    file_name  :output file name, top.v
      -h/-?              :printf help

3.2 GEN_TOP for AMBA AHB

go to 'gen_amba_ahb/verification'
$ cd gen_amba_ahb/verification
have a look the help message
$ ./gen_ahb_top.sh -h
generate a top-level
$ ./gen_ahb_top.sh -mst 2 -slv 2 -siz 1024 -out top.v
. It generates a top-level verilog ("top.v") supporting two AXI masters and two AXI memories.
. Each memory takes care of 1Kbyte range of memory; i.e., memory0 covers 0-1023 and memory1 covers 1024-2047.

Click to expand

$ ./gen_ahb_top.sh -h
Usage : ./gen_ahb_top.sh [options]
      -mst    num        :num of masters, 2
      -slv    num        :num of slaves, i.e., memories, 2
      -siz    bytes      :size of each slave in bytes, 1024
      -bus    module     :name of bus, 
      -out    file_name  :output file name, top.v
      -h/-?              :printf help

3.3 GEN_TOP for AMBA APB

go to 'gen_amba_apb/verification'
$ cd gen_amba_apb/verification
have a look the help message
$ ./gen_apb_top.sh -h
generate a top-level
$ ./gen_apb_top.sh -ahb -slv 2 -siz 1024 -out top.v
. It generates a top-level verilog ("top.v") supporting AHB masters and two APB memories.
. Each memory takes care of 1Kbyte range of memory; i.e., memory0 covers 0-1023 and memory1 covers 1024-2047.

Click to expand

$ ./gen_apb_top.sh -h
Usage : ./gen_apb_top.sh [options]
      -ahb|axi           :AHB or AXI master: ahb
      -slv    num        :num of slaves, i.e., memories, 2
      -siz    bytes      :size of each slave in bytes, 1024
      -bus    module     :name of bus, 
      -out    file_name  :output file name, top.v
      -h/-?              :printf help

4. Bus tasks

BFM (Bus Functional Model) is a widely adopted approach to build verification envrionment for a bus-based system, where BFM generates bus transactions to test functionality of blocks through the bus. BFM carries out testing scenario using bus tasks as shown in the picture below. This project contains bus tasks for AMBA AXI and AHB.

4.1 AMBA AXI Bus tasks

Refer to 'axi_master_tasks.v' in 'gen_amba_axi/verification/ip' directory.

4.1.1 AMBA AXI write task

This task generates AXI write burst transaction.

Click to expand

task axi_master_write;
     input [WIDTH_AD-1:0] addr ;
     input [15:0]         bnum ; // num of byte for a beat of burst
     input [15:0]         bleng; // burst length: 1, 2, ...
     input [ 1:0]         burst; // 0:fixed, 1:incr, 2:wrap
     input [ 1:0]         lock ; // 2'b10:lock, 2'b01:excl
     input                delay; // 0:don't use delay
     reg   [WIDTH_ID-1:0] awid;
begin
     if (bnum!=1<<$clog2(bnum)) $display($time,,"%m ERROR size in bytes not supported %d", bnum);
     awid <= $random(seed_awid);
     @ (posedge ACLK);
     fork axi_master_write_aw( awid
                             , addr
                             , bnum
                             , bleng
                             , burst
                             , lock);
          axi_master_write_w( awid
                            , addr
                            , bnum
                            , bleng
                            , burst
                            , delay);
          axi_master_write_b( awid);
     join
     num_of_writes = num_of_writes + 1;
end
endtask

4.1.2 AMBA AXI read task

This task generates AXI read burst transaction.

Click to expand

task axi_master_read;
     input [WIDTH_AD-1:0] addr ;
     input [15:0]         bnum ; // num of byte for a beat of burst
     input [15:0]         bleng; // burst length: 1, 2, ...
     input [ 1:0]         burst; // 0:fixed, 1:incr, 2:wrap
     input [ 1:0]         lock ; // 2'b10:lock, 2'b01:excl
     input                delay; // 0:don't use delay
     reg   [WIDTH_ID-1:0] arid;
begin
     if (bnum!=1<<$clog2(bnum)) $display($time,,"%m ERROR size in bytes not supported %d", bnum);
     arid <= $random(seed_arid);
     @ (posedge ACLK);
     fork axi_master_read_ar( arid
                            , addr
                            , bnum
                            , bleng
                            , burst
                            , lock);
          axi_master_read_r( arid
                           , bleng
                           , delay);
     join
     num_of_reads = num_of_reads + 1;
end
endtask

4.2 AMBA AHB Bus tasks

Refer to 'ahb_tasks.v' in 'gen_amba_ahb/verification/ip' directory.

4.2.1 AMBA AHB write task

This task generates AHB write transaction, which writes 'size'-byte of data to 'addr' address and retuns 'status' after completion.

Click to expand

task ahb_write;
     input  [31:0] addr; // byte-wise adddress
     input  [31:0] data; // justifed data
     input  [ 2:0] size; // num of bytes
     output [ 1:0] status; // 0 for OK
begin
       ahb_write_core( addr
                     , data
                     , size
                     , 4'b0001 // non-cacheable,non-bufferable,user,data
                     , 1'b0 // hlock
                     , status);
end
endtask

4.2.2 AMBA AHB read task

This task generates AHB read transaction, which reads 'size'-byte of data from 'addr' address and retuns 'status' after completion.

Click to expand

task ahb_read;
     input  [31:0] addr; // byte-wise address
     output [31:0] data; // justified data
     input  [ 2:0] size; // num of bytes
     output [ 1:0] status; // 0 for OK
begin
       ahb_read_core( addr
                    , data
                    , size
                    , 4'b0001 // non-cacheable,non-bufferable,user,data
                    , 1'b0 // lock
                    , status);
end
endtask

5. Where to get more information

The author has been giving open lecture on AMBA bus at following two institutes:

IDEC (IC Design Education Center) at KAIST: https://www.idec.or.kr
SW-SoC Academy at ETRI: https://www.asic.net

Lecture materials and codes are also available from Ando's GitHub:

AMBA lecture materials at GitHub: https://github.com/adki/AMBA_AXI_AHB_APB

Source code is available from Ando's GitHub:

https://github.com/adki/gen_amba_2021

6. Where it has been used

6.1 HW-SW transaction-level co-simulation

Cosim BFM library is a package to provide HW-SW co-simulation between the HDL (Hardware Description Language) simulator and the host program, where BFM (Bus Functional Model or Bus Functional Module) generates bus transaction by interacting with the host program in C or Python. Refer to HW-SW co-simulation library repository.

6.2 Future Design Systems CON-FMC^TM project

6.2.1 Gigabit Ethernet project

6.2.2 AMBA AXI project

6.2.3 AMBA AHB project

6.3 Core-A project

6.3.1 Papers

Ji-Hoon Kim, Jong-Yeol Lee, and Ando Ki, Core-A: A 32-bit Synthesizable Processor Core, IEIE Transactions on Smart Processing and Computing, vol. 4, no. 2, April 2015.

6.3.2 Basic platforms

Ando Ki, Platform Design using Core-A Processor (Core-A 프로세서를 활용한 플랫폼 설계), HongReung Publishing, 2010.

6.3.2.1 Audio platform

6.3.2.2 Video platform

6.3.2.3 Ethernet platform

6.3.3 Application platforms

Ando Ki, Application Design using Core-A Processor (Core-A 프로세서를 활용한 응용 설계), HongReung Publishing, 2011.

6.3.3.1 FAT file system

6.3.3.2 uC/OS-II application

6.3.3.3 FreeRTOS application

6.3.3.4 JPEG application

6.3.3.5 MP3 application

6.3.3.6 Webserver application

7. Other things

Author(s)

Ando Ki - Initial work - Future Design Systems and KAIST.

Acknowledgments

Thanks to all who gave me valuable feedback.

Revision history

2023.07.16: Bug-fixed: SystemVerilog keyword conflict resolved. Simulation using Vivado XSIM in 'verification' uses SystemVerilog compiler. (Thanks 'dale40' for raising this issue.)
2021.09.05: Bug-fixed: 'ADDR_BASE' parameter updated to support address wider than 32-bit in 'gen_axi_top.sh'.
2021.09.05: Bug-fixed: address range parameters changed from "32'h???" to "'h???" to support wider address width.
2021.07.10: 'gen_amba_axi' option changed.
2021.07.01: AMBA AXI4 feature applied, in which WID[..] removed.
2021.06.01: M?_MID[..] removed.
2021.06.01: '--axi3' option added in order to force to use AMBA AXI3 instead of AXI4.
A long time ago: Started by Ando Ki (adki(at)gmail.com).

jumanamp/gen_amba_2021

GEN_AMBA_2021

Table of contents

License

Prerequisites

Maturity

Limitations

1. Quick start for AMBA AXI and AHB

1.1 Quick start for AMBA AXI

1.1.1 generating AMBA AXI

1.1.2 verification AMBA AXI

1.1.3 change verification configuration

1.2. Quick start for AMBA AHB

1.2.1 generating AMBA AHB

1.2.2 verification AMBA AHB

2. GEN_AMBA

2.1 gen_amba_axi

2.2 gen_amba_ahb

2.3 gen_amba_apb

3. GEN_TOP

3.1 GEN_TOP for AMBA AXI

3.2 GEN_TOP for AMBA AHB

3.3 GEN_TOP for AMBA APB

4. Bus tasks

4.1 AMBA AXI Bus tasks

4.1.1 AMBA AXI write task

4.1.2 AMBA AXI read task

4.2 AMBA AHB Bus tasks

4.2.1 AMBA AHB write task

4.2.2 AMBA AHB read task

5. Where to get more information

6. Where it has been used

6.1 HW-SW transaction-level co-simulation

6.2 Future Design Systems CON-FMCTM project

6.2.1 Gigabit Ethernet project

6.2.2 AMBA AXI project

6.2.3 AMBA AHB project

6.3 Core-A project

6.3.1 Papers

6.3.2 Basic platforms

6.3.2.1 Audio platform

6.3.2.2 Video platform

6.3.2.3 Ethernet platform

6.3.3 Application platforms

6.3.3.1 FAT file system

6.3.3.2 uC/OS-II application

6.3.3.3 FreeRTOS application

6.3.3.4 JPEG application

6.3.3.5 MP3 application

6.3.3.6 Webserver application

7. Other things

Author(s)

Acknowledgments

Revision history

6.2 Future Design Systems CON-FMC^TM project