Coverage for hdl_registers/generator/c/header.py: 96%

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

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

3# 

4# This file is part of the hdl-registers project, an HDL register generator fast enough to run 

5# in real time. 

6# https://hdl-registers.com 

7# https://github.com/hdl-registers/hdl-registers 

8# -------------------------------------------------------------------------------------------------- 

9 

10from __future__ import annotations 

11 

12from typing import TYPE_CHECKING, Any 

13 

14from hdl_registers.constant.bit_vector_constant import UnsignedVectorConstant 

15from hdl_registers.constant.boolean_constant import BooleanConstant 

16from hdl_registers.constant.float_constant import FloatConstant 

17from hdl_registers.constant.integer_constant import IntegerConstant 

18from hdl_registers.constant.string_constant import StringConstant 

19from hdl_registers.field.enumeration import Enumeration 

20from hdl_registers.generator.register_code_generator import RegisterCodeGenerator 

21from hdl_registers.register import Register 

22 

23if TYPE_CHECKING: 

24 from pathlib import Path 

25 

26 from hdl_registers.register_array import RegisterArray 

27 from hdl_registers.register_list import RegisterList 

28 

29# There is no unit test of this class that checks the generated code. It is instead functionally 

30# tested in the file 'test_compiled_c_code.py'. That test generates C code from an example 

31# register set, compiles it and performs some run-time assertions in a C program. 

32# That test is considered more meaningful and exhaustive than a unit test would be. 

33 

34 

35class CHeaderGenerator(RegisterCodeGenerator): 

36 """ 

37 Generate a C header. 

38 See the :ref:`generator_c` article for usage details. 

39 

40 The header will contain: 

41 

42 * Constant values for all :ref:`register constants <constant_overview>`. 

43 

44 * Enumeration types for all :ref:`field_enumeration`. 

45 

46 * A ``struct`` type with all registers as members, which can be memory mapped directly. 

47 

48 * For each register, ``#define`` constants with the index and address of the register. 

49 

50 * For each field in each register, ``#define`` constants with the bit shift, bit mask and 

51 inverse bit mask of the field. 

52 """ 

53 

54 __version__ = "1.0.0" 

55 

56 SHORT_DESCRIPTION = "C header" 

57 

58 COMMENT_START = "//" 

59 

60 # The most commonly used indentation. 

61 # For code at the top level. 

62 DEFAULT_INDENTATION_LEVEL = 0 

63 

64 @property 

65 def output_file(self) -> Path: 

66 """ 

67 Result will be placed in this file. 

68 """ 

69 return self.output_folder / self._file_name 

70 

71 def __init__( # noqa: D417 

72 self, register_list: RegisterList, output_folder: Path, file_name: str | None = None 

73 ) -> None: 

74 """ 

75 For argument description, please see the super class. 

76 

77 Arguments: 

78 file_name: Optionally specify an explicit result file name. 

79 If not specified, the name will be derived from the name of the register list. 

80 """ 

81 super().__init__(register_list=register_list, output_folder=output_folder) 

82 

83 self._file_name = f"{self.name}_regs.h" if file_name is None else file_name 

84 

85 def get_code( 

86 self, 

87 **kwargs: Any, # noqa: ANN401, ARG002 

88 ) -> str: 

89 """ 

90 Get a complete C header with all constants and all registers. 

91 """ 

92 define_name = f"{self.name.upper()}_REGS_H" 

93 

94 return f"""\ 

95#ifndef {define_name} 

96#define {define_name} 

97 

98{self._constants()} 

99{self._number_of_registers()} 

100{self._register_struct()} 

101{self._register_defines()}\ 

102#endif {self.comment(define_name)}""" 

103 

104 def _register_struct(self) -> str: 

105 array_structs = "" 

106 

107 register_struct_type = f"{self.name}_regs_t" 

108 

109 register_struct = self.comment("Type for this register list.") 

110 register_struct += f"typedef struct {register_struct_type}\n" 

111 register_struct += "{\n" 

112 

113 for register_object in self.iterate_register_objects(): 

114 if isinstance(register_object, Register): 

115 register_struct += self.comment(f'Mode "{register_object.mode.name}".', indent=2) 

116 register_struct += f" uint32_t {register_object.name};\n" 

117 

118 else: 

119 array_struct_type = f"{self.name}_{register_object.name}_t" 

120 

121 array_structs += self.comment( 

122 f"Type for the '{register_object.name}' register array." 

123 ) 

124 array_structs += f"typedef struct {array_struct_type}\n" 

125 array_structs += "{\n" 

126 for register in register_object.registers: 

127 array_structs += self.comment(f"Mode '{register.mode.name}'.", indent=2) 

128 array_structs += f" uint32_t {register.name};\n" 

129 array_structs += f"} {array_struct_type};\n\n" 

130 

131 register_struct += ( 

132 f" {array_struct_type} {register_object.name}[{register_object.length}];\n" 

133 ) 

134 

135 register_struct += f"} {register_struct_type};\n" 

136 

137 return array_structs + register_struct 

138 

139 def _number_of_registers(self) -> str: 

140 # It is possible that we have constants but no registers 

141 num_regs = 0 

142 if self.register_list.register_objects: 

143 num_regs = self.register_list.register_objects[-1].index + 1 

144 

145 c_code = self.comment("Number of registers within this register list.") 

146 c_code += f"#define {self.name.upper()}_NUM_REGS ({num_regs}u)\n" 

147 

148 return c_code 

149 

150 def _register_defines(self) -> str: 

151 c_code = "" 

152 for register, register_array in self.iterate_registers(): 

153 c_code += self._addr_define(register, register_array) 

154 c_code += self._field_definitions(register, register_array) 

155 c_code += "\n" 

156 

157 return c_code 

158 

159 def _addr_define(self, register: Register, register_array: RegisterArray | None) -> str: 

160 name = self.qualified_register_name( 

161 register=register, register_array=register_array 

162 ).upper() 

163 

164 register_description = self.register_description( 

165 register=register, register_array=register_array 

166 ) 

167 

168 register_array_comment = ( 

169 f" (array_index < {register_array.length})" if register_array else "" 

170 ) 

171 comment = [ 

172 f"Address of the {register_description}{register_array_comment}.", 

173 f"Mode '{register.mode.name}'.", 

174 ] 

175 c_code = self.comment_block(comment) 

176 

177 if register_array: 

178 c_code += ( 

179 f"#define {name}_INDEX(array_index) ({register_array.base_index}u + " 

180 f"(array_index) * {len(register_array.registers)}u + {register.index}u)\n" 

181 ) 

182 c_code += f"#define {name}_ADDR(array_index) (4u * {name}_INDEX(array_index))\n" 

183 else: 

184 c_code += f"#define {name}_INDEX ({register.index}u)\n" 

185 c_code += f"#define {name}_ADDR (4u * {name}_INDEX)\n" 

186 

187 return c_code 

188 

189 def _field_definitions(self, register: Register, register_array: RegisterArray | None) -> str: 

190 c_code = "" 

191 for field in register.fields: 

192 field_description = self.field_description( 

193 register=register, register_array=register_array, field=field 

194 ) 

195 c_code += self.comment(f"Attributes for the {field_description}.") 

196 

197 name = self.qualified_field_name( 

198 register=register, field=field, register_array=register_array 

199 ).upper() 

200 c_code += f"#define {name}_SHIFT ({field.base_index}u)\n" 

201 c_code += f"#define {name}_MASK (0b{'1' * field.width}u << {field.base_index}u)\n" 

202 c_code += f"#define {name}_MASK_INVERSE (~{name}_MASK)\n" 

203 

204 if isinstance(field, Enumeration): 

205 # Enums in C export their enumerators to the surrounding scope, causing huge risk of 

206 # name clashes. 

207 # Hence we give the enumerators long names qualified with the register name, etc. 

208 name_value_pairs = [ 

209 f"{name}_{element.name.upper()} = {element.value}," 

210 for element in field.elements 

211 ] 

212 separator = "\n " 

213 

214 c_code += f"""\ 

215enum {self.to_pascal_case(name)} 

216{ 

217 {separator.join(name_value_pairs)} 

218} ; 

219""" 

220 

221 return c_code 

222 

223 def _constants(self) -> str: 

224 c_code = "" 

225 

226 def define(name: str, value: str) -> str: 

227 return f"#define {name} ({value})\n" 

228 

229 for constant in self.iterate_constants(): 

230 c_code += self.comment(f"Value of register constant '{constant.name}'.") 

231 

232 constant_name = f"{self.name.upper()}_{constant.name.upper()}" 

233 

234 if isinstance(constant, BooleanConstant): 

235 c_code += define(constant_name, str(constant.value).lower()) 

236 elif isinstance(constant, IntegerConstant): 

237 # No suffix -> "int", i.e. signed integer of at least 32 bits. 

238 c_code += define(constant_name, str(constant.value)) 

239 elif isinstance(constant, FloatConstant): 

240 # No suffix -> "double" (https://stackoverflow.com/questions/13276862). 

241 # Matches the VHDL type which is at least 64 bits (IEEE 1076-2008, 5.2.5.1). 

242 # Note that casting a Python float to string guarantees full precision in the 

243 # resulting string: https://stackoverflow.com/a/60026172 

244 c_code += define(constant_name, str(constant.value)) 

245 elif isinstance(constant, StringConstant): 

246 # C string literal: Raw value enclosed in double quotation marks. 

247 # Without "static", we get a linker warning about multiple definitions 

248 # despite the multiple-include guard. 

249 # See here https://stackoverflow.com/a/9196883 for some other information. 

250 c_code += f'static char *{constant_name} = "{constant.value}";\n' 

251 elif isinstance(constant, UnsignedVectorConstant): 

252 # "unsigned" and "long" as suffix. 

253 # Makes it possible to use large numbers for e.g. base addresses. 

254 c_code += define( 

255 constant_name, f"{constant.prefix}{constant.value_without_separator}UL" 

256 ) 

257 else: 

258 raise TypeError(f"Got unexpected constant type. {constant}") 

259 

260 return c_code