Debian Codegraph @

build-aux/qmi-codegen/Field.py

raw
1 # -*- Mode: python; tab-width: 4; indent-tabs-mode: nil -*-
2 #
3 # This program is free software; you can redistribute it and/or modify it under
4 # the terms of the GNU Lesser General Public License as published by the Free
5 # Software Foundation; either version 2 of the License, or (at your option) any
6 # later version.
7 #
8 # This program is distributed in the hope that it will be useful, but WITHOUT
9 # ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
10 # FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more
11 # details.
12 #
13 # You should have received a copy of the GNU Lesser General Public License along
14 # with this program; if not, write to the Free Software Foundation, Inc., 51
15 # Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
16 #
17 # Copyright (C) 2012 Lanedo GmbH
18 # Copyright (C) 2012-2022 Aleksander Morgado <[email protected]>
19 # Copyright (c) 2022 Qualcomm Innovation Center, Inc.
20 #
21
22 import string
23
24 import utils
25 import VariableFactory
26 import TypeFactory
27
28 """
29 The Field class takes care of handling Input and Output TLVs
30 """
31 class Field:
32
33 """
34 Constructor
35 """
36 def __init__(self, service, prefix, dictionary, common_objects_dictionary, container_type, static):
37 # The current QMI service
38 self.service = service
39 # The field prefix, usually the name of the Container,
40 # e.g. "Qmi Message Ctl Something Output"
41 self.prefix = prefix
42 # The name of the specific field, e.g. "Result"
43 self.name = dictionary['name']
44 # The specific TLV ID
45 self.id = dictionary['id']
46 # Overridden mandatory field, the default is calculated from id
47 self._mandatory = dictionary.get('mandatory')
48 # The type, which must always be "TLV"
49 self.type = dictionary['type']
50 # The container type, which must be either "Input" or "Output"
51 self.container_type = container_type
52 # Whether the whole field is internally used only
53 self.static = static
54
55 # Create the composed full name (prefix + name),
56 # e.g. "Qmi Message Ctl Something Output Result"
57 self.fullname = dictionary['fullname'] if 'fullname' in dictionary else self.prefix + ' ' + self.name
58
59 # libqmi version where the message was introduced
60 self.since = dictionary['since'] if 'since' in dictionary else None
61 if self.since is None:
62 raise ValueError('TLV ' + self.fullname + ' requires a "since" tag specifying the major version where it was introduced')
63
64 # TLVs can no longer be structs, they must be sequences instead
65 if dictionary['format'] == 'struct':
66 raise ValueError('TLV ' + self.fullname + ' cannot have type "struct": use "sequence" instead')
67
68 # Create our variable object
69 self.variable = VariableFactory.create_variable(self.service, dictionary, self.fullname, self.container_type)
70
71 # Create the variable name within the Container
72 self.variable_name = 'arg_' + utils.build_underscore_name(self.name).lower()
73
74 # Create the ID enumeration name
75 self.id_enum_name = utils.build_underscore_name(self.prefix + ' TLV ' + self.name).upper()
76
77 # Output Fields may have prerequisites
78 self.prerequisites = []
79 if 'prerequisites' in dictionary:
80 self.prerequisites = dictionary['prerequisites']
81 # First, look for references to common types
82 for prerequisite_dictionary in self.prerequisites:
83 if 'common-ref' in prerequisite_dictionary:
84 for common in common_objects_dictionary:
85 if common['type'] == 'prerequisite' and \
86 common['common-ref'] == prerequisite_dictionary['common-ref']:
87 # Replace the reference with a copy of the common dictionary
88 copy = dict(common)
89 self.prerequisites.remove(prerequisite_dictionary)
90 self.prerequisites.append(copy)
91 break
92 else:
93 raise RuntimeError('Common type \'%s\' not found' % prerequisite_dictionary['name'])
94
95 if 'personal-info' in dictionary:
96 self.personal_info = True;
97 else:
98 self.personal_info = False;
99
100
101 @property
102 def mandatory(self):
103 if self._mandatory is None:
104 return int(self.id, 0) < 0x10
105 return self._mandatory == 'yes'
106
107
108 """
109 Emit new types required by this field
110 """
111 def emit_types(self, hfile, cfile):
112 if not TypeFactory.is_type_emitted(self.fullname):
113 TypeFactory.set_type_emitted(self.fullname)
114 self.variable.emit_types(hfile, cfile, self.since, False)
115 if self.variable.needs_compat_gir and self.service != 'CTL':
116 self.variable.emit_types_gir(hfile, cfile, self.since)
117
118
119 """
120 Common getter logic
121 """
122 def emit_getter_common(self, hfile, cfile, dec, doc, imp, since, suffix_gir):
123 translations = { 'name' : self.name,
124 'variable_name' : self.variable_name,
125 'variable_getter_dec' : dec,
126 'variable_getter_doc' : doc,
127 'variable_getter_imp' : imp,
128 'underscore' : utils.build_underscore_name(self.name),
129 'suffix_gir' : suffix_gir,
130 'prefix_camelcase' : utils.build_camelcase_name(self.prefix),
131 'prefix_underscore' : utils.build_underscore_name(self.prefix),
132 'since' : since,
133 'static' : 'static ' if self.static else '' }
134
135 # Emit the getter header
136 template = '\n'
137 if not self.static and self.service != 'CTL':
138 template += (
139 '\n'
140 '/**\n')
141
142 if self.variable.needs_compat_gir:
143 # Rename the GIR specific method to the original method name, and
144 # skip the original method completely
145 if suffix_gir == '':
146 template += (
147 ' * ${prefix_underscore}_get_${underscore}: (skip)\n')
148 else:
149 template += (
150 ' * ${prefix_underscore}_get_${underscore}${suffix_gir}: (rename-to ${prefix_underscore}_get_${underscore})\n')
151 else:
152 if suffix_gir != '':
153 raise RuntimeError('GIR suffix given and variable does not need compat GIR support')
154 template += (
155 ' * ${prefix_underscore}_get_${underscore}:\n')
156
157 template += (
158 ' * @self: a #${prefix_camelcase}.\n'
159 '${variable_getter_doc}'
160 ' * @error: Return location for error or %NULL.\n'
161 ' *\n'
162 ' * Get the \'${name}\' field from @self.\n')
163
164 if self.variable.needs_compat_gir:
165 if suffix_gir != '':
166 template += (
167 ' *\n'
168 ' * Version of ${prefix_underscore}_get_${underscore}() using arrays of pointers to\n'
169 ' * structs instead of arrays of structs, for easier binding in other languages.\n')
170
171 template += (
172 ' *\n'
173 ' * Returns: (skip): %TRUE if the field is found, %FALSE otherwise.\n'
174 ' *\n'
175 ' * Since: ${since}\n'
176 ' */\n')
177 template += (
178 '${static}gboolean ${prefix_underscore}_get_${underscore}${suffix_gir} (\n'
179 ' ${prefix_camelcase} *self,\n'
180 '${variable_getter_dec}'
181 ' GError **error);\n')
182 hfile.write(string.Template(template).substitute(translations))
183
184 # Emit the getter source
185 template = (
186 '\n'
187 '${static}gboolean\n'
188 '${prefix_underscore}_get_${underscore}${suffix_gir} (\n'
189 ' ${prefix_camelcase} *self,\n'
190 '${variable_getter_dec}'
191 ' GError **error)\n'
192 '{\n'
193 ' g_return_val_if_fail (self != NULL, FALSE);\n'
194 '\n'
195 ' if (!self->${variable_name}_set) {\n'
196 ' g_set_error (error,\n'
197 ' QMI_CORE_ERROR,\n'
198 ' QMI_CORE_ERROR_TLV_NOT_FOUND,\n'
199 ' "Field \'${name}\' was not found in the message");\n'
200 ' return FALSE;\n'
201 ' }\n'
202 '\n'
203 '${variable_getter_imp}'
204 '\n'
205 ' return TRUE;\n'
206 '}\n')
207 cfile.write(string.Template(template).substitute(translations))
208
209
210 """
211 Emit the method responsible for declaring variable(s) for this TLV in the
212 input/output container
213 """
214 def emit_variable_declaration(self, cfile):
215
216 template = self.variable.build_variable_declaration(' ', self.variable_name)
217 cfile.write(template)
218
219 if self.variable.needs_compat_gir and self.service != 'CTL':
220 template = self.variable.build_variable_declaration_gir(' ', self.variable_name)
221 cfile.write(template)
222
223
224 """
225 Emit the method responsible for getting this TLV from the input/output
226 container
227 """
228 def emit_getter(self, hfile, cfile):
229 input_variable_name = 'value_' + utils.build_underscore_name(self.name)
230 dec = self.variable.build_getter_declaration(' ', input_variable_name)
231 doc = self.variable.build_getter_documentation(' * ', input_variable_name)
232 imp = self.variable.build_getter_implementation(' ', 'self->' + self.variable_name, input_variable_name)
233 since = self.since
234 self.emit_getter_common(hfile, cfile, dec, doc, imp, since, '')
235
236 if self.variable.needs_compat_gir and self.service != 'CTL':
237 input_variable_name = 'value_' + utils.build_underscore_name(self.name)
238 dec = self.variable.build_getter_declaration_gir(' ', input_variable_name)
239 doc = self.variable.build_getter_documentation_gir(' * ', input_variable_name)
240 imp = self.variable.build_getter_implementation_gir(' ', 'self->' + self.variable_name, input_variable_name)
241 since = self.since if utils.version_compare('1.32',self.since) > 0 else '1.32'
242 self.emit_getter_common(hfile, cfile, dec, doc, imp, since, '_gir')
243
244
245 """
246 Common setter logic
247 """
248 def emit_setter_common(self, hfile, cfile, dec, doc, imp, since, suffix_gir):
249 translations = { 'name' : self.name,
250 'variable_name' : self.variable_name,
251 'variable_setter_dec' : dec,
252 'variable_setter_doc' : doc,
253 'variable_setter_imp' : imp,
254 'underscore' : utils.build_underscore_name(self.name),
255 'prefix_camelcase' : utils.build_camelcase_name(self.prefix),
256 'prefix_underscore' : utils.build_underscore_name(self.prefix),
257 'since' : since,
258 'suffix_gir' : suffix_gir,
259 'static' : 'static ' if self.static else '' }
260
261 # Emit the setter header
262 template = '\n'
263 if not self.static and self.service != 'CTL':
264 template += (
265 '\n'
266 '/**\n')
267
268 if self.variable.needs_compat_gir:
269 # Rename the GIR specific method to the original method name, and
270 # skip the original method completely
271 if suffix_gir == '':
272 template += (
273 ' * ${prefix_underscore}_set_${underscore}: (skip)\n')
274 else:
275 template += (
276 ' * ${prefix_underscore}_set_${underscore}${suffix_gir}: (rename-to ${prefix_underscore}_set_${underscore})\n')
277 else:
278 if suffix_gir != '':
279 raise RuntimeError('GIR suffix given and variable does not need compat GIR support')
280 template += (
281 ' * ${prefix_underscore}_set_${underscore}:\n')
282
283 template += (
284 ' * @self: a #${prefix_camelcase}.\n'
285 '${variable_setter_doc}'
286 ' * @error: Return location for error or %NULL.\n'
287 ' *\n'
288 ' * Set the \'${name}\' field in the message.\n'
289 ' *\n'
290 ' * Returns: (skip): %TRUE if @value was successfully set, %FALSE otherwise.\n'
291 ' *\n'
292 ' * Since: ${since}\n'
293 ' */\n')
294 template += (
295 '${static}gboolean ${prefix_underscore}_set_${underscore}${suffix_gir} (\n'
296 ' ${prefix_camelcase} *self,\n'
297 '${variable_setter_dec}'
298 ' GError **error);\n')
299 hfile.write(string.Template(template).substitute(translations))
300
301 # Emit the setter source
302 template = (
303 '\n'
304 '${static}gboolean\n'
305 '${prefix_underscore}_set_${underscore}${suffix_gir} (\n'
306 ' ${prefix_camelcase} *self,\n'
307 '${variable_setter_dec}'
308 ' GError **error)\n'
309 '{\n'
310 ' g_return_val_if_fail (self != NULL, FALSE);\n'
311 '\n'
312 '${variable_setter_imp}'
313 ' self->${variable_name}_set = TRUE;\n'
314 '\n'
315 ' return TRUE;\n'
316 '}\n')
317 cfile.write(string.Template(template).substitute(translations))
318
319 """
320 Emit the method responsible for setting this TLV in the input/output
321 container
322 """
323 def emit_setter(self, hfile, cfile):
324 input_variable_name = 'value_' + utils.build_underscore_name(self.name)
325 dec = self.variable.build_setter_declaration(' ', input_variable_name)
326 doc = self.variable.build_setter_documentation(' * ', input_variable_name)
327 imp = self.variable.build_setter_implementation(' ', input_variable_name, 'self->' + self.variable_name)
328 since = self.since
329 self.emit_setter_common(hfile, cfile, dec, doc, imp, since, '')
330
331 if self.variable.needs_compat_gir and self.service != 'CTL':
332 input_variable_name = 'value_' + utils.build_underscore_name(self.name)
333 dec = self.variable.build_setter_declaration_gir(' ', input_variable_name)
334 doc = self.variable.build_setter_documentation_gir(' * ', input_variable_name)
335 imp = self.variable.build_setter_implementation_gir(' ', input_variable_name, 'self->' + self.variable_name)
336 since = self.since if utils.version_compare('1.32',self.since) > 0 else '1.32'
337 self.emit_setter_common(hfile, cfile, dec, doc, imp, since, '_gir')
338
339
340 """
341 Emit the code responsible for adding the TLV to the QMI message
342 """
343 def emit_input_tlv_add(self, f, line_prefix):
344 translations = { 'name' : self.name,
345 'tlv_id' : self.id_enum_name,
346 'variable_name' : self.variable_name,
347 'lp' : line_prefix }
348
349 template = (
350 '${lp}gsize tlv_offset;\n'
351 '\n'
352 '${lp}if (!(tlv_offset = qmi_message_tlv_write_init (self, (guint8)${tlv_id}, error))) {\n'
353 '${lp} g_prefix_error (error, "Cannot initialize TLV \'${name}\': ");\n'
354 '${lp} return NULL;\n'
355 '${lp}}\n'
356 '\n')
357 f.write(string.Template(template).substitute(translations))
358
359 # Now, write the contents of the variable into the buffer
360 self.variable.emit_buffer_write(f, line_prefix, self.name, 'input->' + self.variable_name)
361
362 template = (
363 '\n'
364 '${lp}if (!qmi_message_tlv_write_complete (self, tlv_offset, error)) {\n'
365 '${lp} g_prefix_error (error, "Cannot complete TLV \'${name}\': ");\n'
366 '${lp} return NULL;\n'
367 '${lp}}\n')
368 f.write(string.Template(template).substitute(translations))
369
370
371 """
372 Emit the code responsible for checking prerequisites in output TLVs
373 """
374 def emit_output_prerequisite_check(self, f, line_prefix):
375 if self.prerequisites == []:
376 f.write('%s/* No Prerequisites for field */\n' % line_prefix)
377 return
378
379 for prerequisite in self.prerequisites:
380 translations = { 'lp' : line_prefix,
381 'prerequisite_field' : utils.build_underscore_name(prerequisite['field']),
382 'prerequisite_operation' : prerequisite['operation'],
383 'prerequisite_value' : prerequisite['value'] }
384 template = (
385 '${lp}/* Prerequisite.... */\n'
386 '${lp}if (!(self->arg_${prerequisite_field} ${prerequisite_operation} ${prerequisite_value}))\n'
387 '${lp} break;\n')
388 f.write(string.Template(template).substitute(translations))
389
390
391 """
392 Emit the code responsible for retrieving the TLV from the QMI message
393 """
394 def emit_output_tlv_get(self, f, line_prefix):
395 tlv_out = utils.build_underscore_name (self.fullname) + '_out'
396 error = 'error' if self.mandatory else 'NULL'
397 translations = { 'name' : self.name,
398 'container_underscore' : utils.build_underscore_name (self.prefix),
399 'tlv_out' : tlv_out,
400 'tlv_id' : self.id_enum_name,
401 'variable_name' : self.variable_name,
402 'lp' : line_prefix,
403 'error' : error }
404
405 template = (
406 '${lp}gsize offset = 0;\n'
407 '${lp}gsize init_offset;\n'
408 '\n'
409 '${lp}if ((init_offset = qmi_message_tlv_read_init (message, ${tlv_id}, NULL, ${error})) == 0) {\n')
410
411 if self.mandatory:
412 template += (
413 '${lp} g_prefix_error (${error}, "Couldn\'t get the mandatory ${name} TLV: ");\n'
414 '${lp} ${container_underscore}_unref (self);\n'
415 '${lp} return NULL;\n')
416 else:
417 template += (
418 '${lp} goto ${tlv_out};\n')
419
420 template += (
421 '${lp}}\n')
422
423 f.write(string.Template(template).substitute(translations))
424
425 # Now, read the contents of the buffer into the variable
426 self.variable.emit_buffer_read(f, line_prefix, tlv_out, error, 'self->' + self.variable_name)
427
428 template = (
429 '\n'
430 '${lp}/* The remaining size of the buffer needs to be 0 if we successfully read the TLV */\n'
431 '${lp}if ((offset = qmi_message_tlv_read_remaining_size (message, init_offset, offset)) > 0) {\n'
432 '${lp} g_warning ("Left \'%" G_GSIZE_FORMAT "\' bytes unread when getting the \'${name}\' TLV", offset);\n'
433 '${lp}}\n'
434 '\n'
435 '${lp}self->${variable_name}_set = TRUE;\n'
436 '\n'
437 '${tlv_out}:\n')
438 if self.mandatory:
439 template += (
440 '${lp}if (!self->${variable_name}_set) {\n'
441 '${lp} ${container_underscore}_unref (self);\n'
442 '${lp} return NULL;\n'
443 '${lp}}\n')
444 else:
445 template += (
446 '${lp};\n')
447 f.write(string.Template(template).substitute(translations))
448
449
450 """
451 Emit the method responsible for creating a printable representation of the TLV
452 """
453 def emit_tlv_helpers(self, f):
454 if TypeFactory.helpers_emitted(self.fullname):
455 return
456
457 TypeFactory.set_helpers_emitted(self.fullname)
458
459 translations = { 'name' : self.name,
460 'tlv_id' : self.id_enum_name,
461 'underscore' : utils.build_underscore_name (self.fullname) }
462
463 template = (
464 '\n'
465 'static gchar *\n'
466 '${underscore}_get_printable (\n'
467 ' QmiMessage *message,\n'
468 ' const gchar *line_prefix)\n'
469 '{\n'
470 ' gsize offset = 0;\n'
471 ' gsize init_offset;\n'
472 ' GString *printable;\n'
473 ' GError *error = NULL;\n'
474 '\n'
475 ' if ((init_offset = qmi_message_tlv_read_init (message, ${tlv_id}, NULL, NULL)) == 0)\n'
476 ' return NULL;\n'
477 '\n'
478 ' printable = g_string_new ("");\n')
479 f.write(string.Template(template).substitute(translations))
480
481 # Now, read the contents of the buffer into the printable representation
482 self.variable.emit_get_printable(f, ' ', self.personal_info)
483
484 template = (
485 '\n'
486 ' if ((offset = qmi_message_tlv_read_remaining_size (message, init_offset, offset)) > 0)\n'
487 ' g_string_append_printf (printable, "Additional unexpected \'%" G_GSIZE_FORMAT "\' bytes", offset);\n'
488 '\n'
489 'out:\n'
490 ' if (error) {\n'
491 ' g_string_append_printf (printable, " ERROR: %s", error->message);\n'
492 ' g_error_free (error);\n'
493 ' }\n'
494 ' return g_string_free (printable, FALSE);\n'
495 '}\n')
496 f.write(string.Template(template).substitute(translations))
497
498
499 """
500 Add sections
501 """
502 def add_sections(self, sections):
503 translations = { 'underscore' : utils.build_underscore_name(self.name),
504 'prefix_camelcase' : utils.build_camelcase_name(self.prefix),
505 'prefix_underscore' : utils.build_underscore_name(self.prefix) }
506
507 if not TypeFactory.is_section_emitted(self.fullname):
508 TypeFactory.set_section_emitted(self.fullname)
509 self.variable.add_sections(sections)
510
511 # Public methods
512 template = (
513 '${prefix_underscore}_get_${underscore}\n')
514 if self.variable.needs_compat_gir and self.service != 'CTL':
515 template += (
516 '${prefix_underscore}_get_${underscore}_gir\n')
517 if self.container_type == 'Input':
518 template += (
519 '${prefix_underscore}_set_${underscore}\n')
520 if self.variable.needs_compat_gir and self.service != 'CTL':
521 template += (
522 '${prefix_underscore}_set_${underscore}_gir\n')
523 sections['public-methods'] += string.Template(template).substitute(translations)