Coverage for tsfpga/test/unit/test_vhdl_file_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://gitlab.com/tsfpga/tsfpga 

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

8 

9# First party libraries 

10from tsfpga.system_utils import create_file 

11from tsfpga.vhdl_file_documentation import VHDL_COMMENT_SEPARATOR, VhdlFileDocumentation 

12 

13 

14def test_documentation_header(tmp_path): 

15 data = f"""\ 

16{VHDL_COMMENT_SEPARATOR} 

17-- Copyright bla bla 

18{VHDL_COMMENT_SEPARATOR} 

19-- This is my documentation 

20-- 

21-- with 

22-- indentation 

23-- 

24-- And empty lines. 

25{VHDL_COMMENT_SEPARATOR} 

26 

27""" 

28 expected = """\ 

29This is my documentation 

30 

31 with 

32 indentation 

33 

34And empty lines. 

35""" 

36 

37 vhd_file = create_file(tmp_path / "file_for_test.vhd", data) 

38 assert VhdlFileDocumentation(vhd_file).get_header_rst() == expected 

39 

40 

41def test_only_copyright_header_should_return_no_documentation_header(tmp_path): 

42 data = f"""\ 

43{VHDL_COMMENT_SEPARATOR} 

44-- Copyright bla bla 

45{VHDL_COMMENT_SEPARATOR} 

46 

47""" 

48 

49 vhd_file = create_file(tmp_path / "file_for_test.vhd", data) 

50 assert VhdlFileDocumentation(vhd_file).get_header_rst() is None 

51 

52 

53def run_get_symbolator_component_test(tmp_path, vhdl_code, expected): 

54 vhd_file_path = create_file(tmp_path / "test_entity.vhd", vhdl_code) 

55 got = VhdlFileDocumentation(vhd_file_path).get_symbolator_component() 

56 

57 assert got == expected 

58 

59 

60def test_get_symbolator_component_simple(tmp_path): 

61 data = """ 

62entity test_entity is 

63 generic ( 

64 num_interfaces : positive 

65 ); 

66 port ( 

67 clk : in std_ulogic; 

68 --# {{}} 

69 input_ready : out std_ulogic := '0'; 

70 input_valid : in std_ulogic; 

71 --# {{}} 

72 output_ready : in std_ulogic_vector(0 to num_interfaces - 1); 

73 output_valid : out std_ulogic_vector(0 to num_interfaces - 1) := (others => '0') 

74 ); 

75end entity; 

76""" 

77 

78 # entity->component, no ranges, and no default values. 

79 expected = """\ 

80component test_entity is 

81 generic ( 

82 num_interfaces : positive 

83 ); 

84 port ( 

85 clk : in std_ulogic; 

86 --# {{}} 

87 input_ready : out std_ulogic; 

88 input_valid : in std_ulogic; 

89 --# {{}} 

90 output_ready : in std_ulogic_vector; 

91 output_valid : out std_ulogic_vector 

92 ); 

93end component;""" 

94 

95 run_get_symbolator_component_test(tmp_path=tmp_path, vhdl_code=data, expected=expected) 

96 

97 

98def test_get_symbolator_component_complex(tmp_path): 

99 data = """ 

100library common; 

101use common.addr_pkg.all; 

102 

103 

104entity test_entity is 

105 generic( 

106 buffer_segment_length_bytes : positive; 

107 dummy : positive := 10; 

108 -- comment 

109 silly : positive_vec_t(0 to 1) := 

110 -- comment again 

111 (others => 4) 

112 ) 

113 ;port( 

114 clk : in std_ulogic; 

115 --# {{}} 

116 request_ready : in std_ulogic := '0'; 

117 request_valid : out std_ulogic_vector(my_range_constant) := '0'; 

118 request_address : out addr_t(apa to hest) := (others => '0'); 

119 request_funky : out addr_t(apa to hest) := 

120 (others => '0'); 

121 request_slinky : out addr_t(apa to hest) := ( 

122 -- comment 

123 others => '0' 

124 ); 

125 --# {{}} 

126 release_last_address : in std_ulogic_vector(enables'range) 

127 := '0'; 

128 --# {{}} 

129 buffer_start_address : in addr_t(hest downto 0); 

130 buffer_last_address : in addr_t 

131 := (others => '0') 

132 ); 

133end entity; 

134 

135architecture a of test_entity is 

136 

137begin 

138 

139end architecture; 

140end; 

141end a; 

142""" 

143 

144 # entity->component, no ranges, and no default values. 

145 expected = """\ 

146component test_entity is 

147 generic( 

148 buffer_segment_length_bytes : positive; 

149 dummy : positive; 

150 -- comment 

151 silly : positive_vec_t 

152 ); 

153 port ( 

154 clk : in std_ulogic; 

155 --# {{}} 

156 request_ready : in std_ulogic; 

157 request_valid : out std_ulogic_vector; 

158 request_address : out addr_t; 

159 request_funky : out addr_t; 

160 request_slinky : out addr_t; 

161 --# {{}} 

162 release_last_address : in std_ulogic_vector; 

163 --# {{}} 

164 buffer_start_address : in addr_t; 

165 buffer_last_address : in addr_t 

166 ); 

167end component;""" 

168 

169 run_get_symbolator_component_test(tmp_path=tmp_path, vhdl_code=data, expected=expected) 

170 

171 

172def test_get_symbolator_component_no_generics(tmp_path): 

173 data = """ 

174entity test_entity is 

175 port ( 

176 dummy_signal : out std_ulogic_vector(my_range_constant) := '0' 

177 ); 

178end entity; 

179""" 

180 

181 # entity->component, no ranges, and no default values. 

182 expected = """\ 

183component test_entity is 

184 port ( 

185 dummy_signal : out std_ulogic_vector 

186 ); 

187end component;""" 

188 

189 run_get_symbolator_component_test(tmp_path=tmp_path, vhdl_code=data, expected=expected) 

190 

191 

192def test_get_symbolator_component_last_port_no_newline(tmp_path): 

193 data = """ 

194entity test_entity is 

195 generic ( 

196 buffer_segment_length_bytes : positive_vec_t(0 to 1)); 

197 port ( 

198 dummy_signal : out std_ulogic_vector(my_range_constant) := '0');end entity; 

199""" 

200 

201 # entity->component, no ranges, and no default values. 

202 expected = """\ 

203component test_entity is 

204 generic ( 

205 buffer_segment_length_bytes : positive_vec_t 

206 ); 

207 port ( 

208 dummy_signal : out std_ulogic_vector 

209 ); 

210end component;""" 

211 

212 run_get_symbolator_component_test(tmp_path=tmp_path, vhdl_code=data, expected=expected) 

213 

214 

215def test_get_symbolator_component_last_port_parenthesis_on_same_line(tmp_path): 

216 data = """ 

217entity test_entity is 

218 generic ( 

219 buffer_segment_length_bytes : positive_vec_t(0 to 1) := (1, 2) ) 

220 ; 

221 port ( 

222 dummy_signal : out std_ulogic_vector(my_range_constant) := '0' ) 

223 ; 

224end entity; 

225""" 

226 

227 # entity->component, no ranges, and no default values. 

228 expected = """\ 

229component test_entity is 

230 generic ( 

231 buffer_segment_length_bytes : positive_vec_t 

232 ); 

233 port ( 

234 dummy_signal : out std_ulogic_vector 

235 ); 

236end component;""" 

237 

238 run_get_symbolator_component_test(tmp_path=tmp_path, vhdl_code=data, expected=expected) 

239 

240 

241def run_get_symbolator_component_end_test(tmp_path, end_statement): 

242 data = f""" 

243entity test_entity is 

244 port ( 

245 clk : in std_ulogic; 

246 dummy_signal : out std_ulogic_vector(my_range_constant) := '0' 

247 ); 

248{end_statement}; 

249 

250architecture a of test_entity is 

251begin 

252 

253end architecture; 

254end; 

255end a; 

256""" 

257 

258 # entity->component, no ranges, and no default values. 

259 expected = """\ 

260component test_entity is 

261 port ( 

262 clk : in std_ulogic; 

263 dummy_signal : out std_ulogic_vector 

264 ); 

265end component;""" 

266 

267 run_get_symbolator_component_test(tmp_path=tmp_path, vhdl_code=data, expected=expected) 

268 

269 

270def run_get_symbolator_component_end_test_with_whitespace(tmp_path, end_statement): 

271 # As above but with lots of whitespace around the keywords. 

272 data = f""" 

273entity 

274 test_entity 

275 is 

276 

277 port ( 

278 clk : in std_ulogic; 

279 dummy_signal : out std_ulogic_vector(my_range_constant) := '0' 

280 ) 

281 ; 

282 

283 

284 {end_statement} 

285 ; 

286 

287architecture a of test_entity is 

288begin 

289 

290end architecture; 

291end; 

292end a; 

293""" 

294 

295 # entity->component, no ranges, and no default values. 

296 expected = """\ 

297component test_entity is 

298 port ( 

299 clk : in std_ulogic; 

300 dummy_signal : out std_ulogic_vector 

301 ); 

302end component;""" 

303 

304 run_get_symbolator_component_test(tmp_path=tmp_path, vhdl_code=data, expected=expected) 

305 

306 

307def test_get_symbolator_component_end_only_keyword(tmp_path): 

308 end_statement = "end" 

309 run_get_symbolator_component_end_test(tmp_path=tmp_path, end_statement=end_statement) 

310 

311 

312def test_get_symbolator_component_no_end_entity_with_whitespace(tmp_path): 

313 end_statement = "end \n" 

314 run_get_symbolator_component_end_test_with_whitespace( 

315 tmp_path=tmp_path, end_statement=end_statement 

316 ) 

317 

318 

319def test_get_symbolator_component_end_name(tmp_path): 

320 end_statement = "end test_entity" 

321 run_get_symbolator_component_end_test(tmp_path=tmp_path, end_statement=end_statement) 

322 

323 

324def test_get_symbolator_component_end_name_with_whitespace(tmp_path): 

325 end_statement = "end \n test_entity \n" 

326 run_get_symbolator_component_end_test_with_whitespace( 

327 tmp_path=tmp_path, end_statement=end_statement 

328 ) 

329 

330 

331def test_get_symbolator_component_end_entity_name(tmp_path): 

332 end_statement = "end entity test_entity" 

333 run_get_symbolator_component_end_test(tmp_path=tmp_path, end_statement=end_statement) 

334 

335 

336def test_get_symbolator_component_end_entity_name_with_whitespace(tmp_path): 

337 end_statement = "end \n entity \n test_entity \n" 

338 run_get_symbolator_component_end_test_with_whitespace( 

339 tmp_path=tmp_path, end_statement=end_statement 

340 )