Coverage for tsfpga/test/test_module_documentation.py: 100%

1# -------------------------------------------------------------------------------------------------- 

2# Copyright (c) Lukas Vik. All rights reserved. 

3# 

4# This file is part of the tsfpga project, a project platform for modern FPGA development. 

5# https://tsfpga.com 

6# https://github.com/tsfpga/tsfpga 

7# -------------------------------------------------------------------------------------------------- 

8 

9from unittest.mock import MagicMock 

10 

11import pytest 

12from hdl_registers.register_list import RegisterList 

13 

14from tsfpga.module import BaseModule 

15from tsfpga.module_documentation import ModuleDocumentation 

16from tsfpga.module_list import ModuleList 

17from tsfpga.system_utils import create_file 

18from tsfpga.vivado.build_result_checker import BlockRams, LessThan, TotalLuts 

19from tsfpga.yosys.project import YosysNetlistBuild 

20 

21 

22@pytest.fixture 

23def module_documentation(tmp_path): 

24 module = BaseModule(path=tmp_path / "apa", library_name="apa") 

25 module_documentation_object = ModuleDocumentation(module) 

26 

27 data = """\ 

28-- ------------------------------------------------------------------------------------------------- 

29-- Copyright (c) Lukas Vik. All rights reserved. 

30-- ------------------------------------------------------------------------------------------------- 

31-- Dummy from hest.vhd. 

32-- ------------------------------------------------------------------------------------------------- 

33 

34""" 

35 create_file(module.path / "src" / "hest.vhd", contents=data) 

36 

37 return module_documentation_object 

38 

39 

40def test_documentation_header_with_no_overview_and_no_registers(module_documentation): 

41 rst = module_documentation.get_rst_document() 

42 

43 assert "\nhest.vhd\n--------" in rst 

44 assert "Dummy from hest.vhd." in rst 

45 

46 assert "Register interface" not in rst 

47 

48 

49def test_documentation_header_with_overview_and_registers(module_documentation): 

50 # ruff: noqa: SLF001 

51 module = module_documentation._module 

52 module._registers = MagicMock(spec=RegisterList) 

53 module._registers.register_objects = MagicMock(spec=list) 

54 

55 data = "Dummy from apa.rst." 

56 create_file(module.path / "doc" / "apa.rst", contents=data) 

57 

58 rst = module_documentation.get_rst_document() 

59 

60 assert "\nhest.vhd\n--------" in rst 

61 assert "Dummy from hest.vhd." in rst 

62 

63 assert "Dummy from apa.rst" in rst 

64 

65 assert "Register interface" in rst 

66 assert ":download:`separate HTML page <apa_regs.html>`" in rst 

67 

68 

69def test_submodule_documentation_with_file_exclude(module_documentation): 

70 data = """\ 

71-- ------------------------------------------------------------------------------------------------- 

72-- Copyright (c) Lukas Vik. All rights reserved. 

73-- ------------------------------------------------------------------------------------------------- 

74-- Dummy from excluded.vhd. 

75-- ------------------------------------------------------------------------------------------------- 

76 

77""" 

78 

79 excluded_vhd = create_file( 

80 module_documentation._module.path / "rtl" / "excluded.vhd", contents=data 

81 ) 

82 

83 rst = module_documentation.get_submodule_rst(heading_character="-", heading_character_2="_") 

84 assert "Dummy from excluded.vhd." in rst 

85 

86 rst = module_documentation.get_submodule_rst( 

87 heading_character="-", heading_character_2="_", exclude_files={excluded_vhd} 

88 ) 

89 assert "Dummy from excluded.vhd." not in rst 

90 

91 

92def test_submodule_documentation_with_folder_exclude(module_documentation): 

93 data = """\ 

94-- ------------------------------------------------------------------------------------------------- 

95-- Copyright (c) Lukas Vik. All rights reserved. 

96-- ------------------------------------------------------------------------------------------------- 

97-- Dummy from excluded.vhd. 

98-- ------------------------------------------------------------------------------------------------- 

99 

100""" 

101 

102 create_file(module_documentation._module.path / "rtl" / "excluded.vhd", contents=data) 

103 

104 rst = module_documentation.get_submodule_rst(heading_character="-", heading_character_2="_") 

105 assert "Dummy from excluded.vhd." in rst 

106 

107 rst = module_documentation.get_submodule_rst( 

108 heading_character="-", 

109 heading_character_2="_", 

110 exclude_module_folders=["rtl"], 

111 ) 

112 assert "Dummy from excluded.vhd." not in rst 

113 

114 

115def test_include_sim_but_not_test_folder(module_documentation): 

116 data = """\ 

117-- ------------------------------------------------------------------------------------------------- 

118-- Copyright (c) Lukas Vik. All rights reserved. 

119-- ------------------------------------------------------------------------------------------------- 

120-- Dummy from bfm.vhd. 

121-- ------------------------------------------------------------------------------------------------- 

122 

123""" 

124 

125 create_file(module_documentation._module.path / "sim" / "bfm.vhd", contents=data) 

126 

127 data = """\ 

128-- ------------------------------------------------------------------------------------------------- 

129-- Copyright (c) Lukas Vik. All rights reserved. 

130-- ------------------------------------------------------------------------------------------------- 

131-- Dummy from tb.vhd. 

132-- ------------------------------------------------------------------------------------------------- 

133 

134""" 

135 

136 create_file(module_documentation._module.path / "test" / "tb.vhd", contents=data) 

137 

138 rst = module_documentation.get_submodule_rst(heading_character="-", heading_character_2="_") 

139 assert "Dummy from bfm.vhd." in rst 

140 assert "Dummy from tb.vhd." not in rst 

141 

142 rst = module_documentation.get_submodule_rst( 

143 heading_character="-", heading_character_2="_", exclude_module_folders=["sim"] 

144 ) 

145 assert "Dummy from bfm.vhd." not in rst 

146 assert "Dummy from tb.vhd." not in rst 

147 

148 

149def test_resource_utilization_table_with_generic_block_ram_checker(tmp_path): 

150 """ 

151 The 'BlockRams' checker is the recommended one for non-Xilinx netlist builds, so it must be 

152 handled by the table sorting just like the Xilinx-specific checkers. 

153 """ 

154 module = BaseModule(path=tmp_path / "apa", library_name="apa") 

155 create_file(module.path / "src" / "hest.vhd", contents="-- Dummy.\n") 

156 

157 netlist_build = YosysNetlistBuild( 

158 name="apa.hest", 

159 modules=ModuleList(), 

160 top="hest", 

161 build_result_checkers=[TotalLuts(LessThan(10)), BlockRams(LessThan(4))], 

162 ) 

163 module.get_build_projects = lambda: [netlist_build] 

164 

165 rst = ModuleDocumentation(module).get_rst_document() 

166 

167 assert "Resource utilization" in rst 

168 # Generic block RAM column is present, and sorted after the LUT column. 

169 assert rst.index("Total LUTs") < rst.index("Block RAMs")