Coverage for tsfpga/examples/example_env.py: 0%

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 __future__ import annotations 

10 

11""" 

12Common functions and definitions in the example build environment. 

13""" 

14 

15from typing import TYPE_CHECKING 

16 

17if TYPE_CHECKING: 

18 from tsfpga.module_list import ModuleList 

19 

20# Import before others since it modifies PYTHONPATH. 

21import tsfpga.examples.example_pythonpath 

22 

23from hdl_registers.register import Register 

24from hdl_registers.register_modes import REGISTER_MODES 

25 

26import tsfpga 

27from tsfpga.module import get_modules 

28 

29TSFPGA_EXAMPLES_TEMP_DIR = tsfpga.TSFPGA_GENERATED 

30 

31 

32def get_default_registers() -> list[Register]: 

33 """ 

34 Default registers for tsfpga examples. 

35 """ 

36 return [ 

37 Register("config", 0, REGISTER_MODES["r_w"], "Configuration register."), 

38 Register( 

39 "command", 

40 1, 

41 REGISTER_MODES["wpulse"], 

42 "When this register is written, all '1's in the written word will be asserted for one " 

43 "clock cycle in the FPGA logic.", 

44 ), 

45 Register("status", 2, REGISTER_MODES["r"], "Status register."), 

46 Register( 

47 "irq_status", 

48 3, 

49 REGISTER_MODES["r_wpulse"], 

50 "Reading a '1' in this register means the corresponding interrupt has triggered.\n" 

51 "Writing to this register will clear the interrupts where there is a '1' in the " 

52 "written word.", 

53 ), 

54 Register( 

55 "irq_mask", 

56 4, 

57 REGISTER_MODES["r_w"], 

58 "A '1' in this register means that the corresponding interrupt is enabled.", 

59 ), 

60 ] 

61 

62 

63def get_tsfpga_example_modules( 

64 names_include: set[str] | None = None, names_avoid: set[str] | None = None 

65) -> ModuleList: 

66 """ 

67 Wrapper of the regular :func:`.get_modules`. call with correct settings for tsfpga 

68 example modules. 

69 This will include the example tsfpga modules, but not the "real" modules. 

70 

71 Arguments will be passed on to :func:`.get_modules`. 

72 """ 

73 return get_modules( 

74 modules_folders=[tsfpga.TSFPGA_EXAMPLE_MODULES], 

75 names_include=names_include, 

76 names_avoid=names_avoid, 

77 library_name_has_lib_suffix=False, 

78 default_registers=get_default_registers(), 

79 ) 

80 

81 

82def get_hdl_modules( 

83 names_include: set[str] | None = None, names_avoid: set[str] | None = None 

84) -> ModuleList: 

85 """ 

86 Wrapper of :func:`.get_modules` which returns the ``hdl-modules`` module objects 

87 (https://hdl-modules.com), if available. 

88 

89 If ``hdl-modules`` can not be found in the default repo checkout location, 

90 the function will assert False. 

91 

92 Arguments will be passed on to :func:`.get_modules`. 

93 

94 Return: 

95 :class:`.ModuleList`: The module objects. 

96 """ 

97 # Presumed location of the hdl-modules repo 

98 hdl_modules_repo_root = tsfpga.REPO_ROOT.parent.parent.resolve() / "hdl-modules" / "hdl-modules" 

99 if (hdl_modules_repo_root / "modules").exists(): 

100 return get_modules( 

101 modules_folders=[hdl_modules_repo_root / "modules"], 

102 names_include=names_include, 

103 names_avoid=names_avoid, 

104 library_name_has_lib_suffix=False, 

105 ) 

106 

107 raise FileNotFoundError( 

108 f"The hdl-modules modules could not be found. Searched in {hdl_modules_repo_root}" 

109 )