Debian Codegraph @

build-aux/qmi-codegen/Message.py

raw
1 # -*- Mode: python; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*-
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 from Container import Container
26
27 """
28 The Message class takes care of request/response message handling
29 """
30 class Message:
31
32 """
33 Constructor
34 """
35 def __init__(self, dictionary, common_objects_dictionary):
36 # Validate input fields in the dictionary, and only allow those
37 # explicitly expected.
38 for message_key in dictionary:
39 if message_key not in [ "name", "type", "service", "id", "since", "input", "output", "vendor", "scope", "abort", "output-compat", "input-compat" ]:
40 raise ValueError('Invalid message field: "' + message_key + '"')
41
42 # The message service, e.g. "Ctl"
43 self.service = dictionary['service']
44 # The name of the specific message, e.g. "Something"
45 self.name = dictionary['name']
46 # The specific message ID
47 self.id = dictionary['id']
48 # The type, which must always be 'Message' or 'Indication'
49 self.type = dictionary['type']
50
51 self.static = True if 'scope' in dictionary and dictionary['scope'] == 'library-only' else False
52 self.abort = True if 'abort' in dictionary and dictionary['abort'] == 'yes' else False
53
54 # libqmi version where the message was introduced
55 self.since = dictionary['since'] if 'since' in dictionary else None
56 if self.since is None:
57 raise ValueError('Message ' + self.name + ' requires a "since" tag specifying the major version where it was introduced')
58
59 # The vendor id if this command is vendor specific
60 self.vendor = dictionary['vendor'] if 'vendor' in dictionary else None
61 if self.type == 'Indication' and self.vendor is not None:
62 raise ValueError('Vendor-specific indications unsupported')
63
64 # The message prefix
65 self.prefix = 'Qmi ' + self.type
66
67 # Create the composed full name (prefix + service + name),
68 # e.g. "Qmi Message Ctl Something"
69 self.fullname = self.prefix + ' ' + self.service + ' ' + self.name
70
71 # Create the ID enumeration name
72 self.id_enum_name = utils.build_underscore_name(self.fullname).upper()
73
74 # Create the build symbol name
75 self.build_symbol = 'HAVE_' + self.id_enum_name
76
77 # Build output container.
78 # Every defined message will have its own output container, which
79 # will generate a new Output type and public getters for each output
80 # field. This applies to both Request/Response and Indications.
81 # Output containers are actually optional in Indications
82 self.output_compat = True if 'output-compat' in dictionary and dictionary['output-compat'] == 'yes' else False
83 self.output = Container(self.service,
84 self.fullname,
85 'Output',
86 dictionary['output'] if 'output' in dictionary else None,
87 common_objects_dictionary,
88 self.static,
89 self.since,
90 self.output_compat)
91
92 self.input = None
93 if self.type == 'Message':
94 # Build input container (Request/Response only).
95 # Every defined message will have its own input container, which
96 # will generate a new Input type and public getters for each input
97 # field
98 self.input_compat = True if 'input-compat' in dictionary and dictionary['input-compat'] == 'yes' else False
99 self.input = Container(self.service,
100 self.fullname,
101 'Input',
102 dictionary['input'] if 'input' in dictionary else None,
103 common_objects_dictionary,
104 self.static,
105 self.since,
106 self.input_compat)
107
108
109 """
110 Emit method responsible for creating a new request of the given type
111 """
112 def __emit_request_creator(self, hfile, cfile):
113 translations = { 'name' : self.name,
114 'service' : self.service,
115 'container' : utils.build_camelcase_name (self.input.fullname),
116 'underscore' : utils.build_underscore_name (self.fullname),
117 'message_id' : self.id_enum_name }
118
119 input_arg_template = 'gpointer unused' if self.input.fields is None else '${container} *input'
120 template = (
121 '\n'
122 'static QmiMessage *\n'
123 '__${underscore}_request_create (\n'
124 ' guint16 transaction_id,\n'
125 ' guint8 cid,\n'
126 ' %s,\n'
127 ' GError **error)\n'
128 '{\n'
129 ' g_autoptr(QmiMessage) self = NULL;\n'
130 '\n'
131 ' self = qmi_message_new (QMI_SERVICE_${service},\n'
132 ' cid,\n'
133 ' transaction_id,\n'
134 ' ${message_id});\n' % input_arg_template)
135 cfile.write(string.Template(template).substitute(translations))
136
137 if self.input.fields:
138 # Count how many mandatory fields we have
139 n_mandatory = 0
140 for field in self.input.fields:
141 if field.mandatory:
142 n_mandatory += 1
143
144 if n_mandatory == 0:
145 # If we don't have mandatory fields, we do allow to have
146 # a NULL input
147 cfile.write(
148 '\n'
149 ' /* All TLVs are optional, we allow NULL input */\n'
150 ' if (!input)\n'
151 ' return g_steal_pointer (&self);\n')
152 else:
153 # If we do have mandatory fields, issue error if no input
154 # given.
155 template = (
156 '\n'
157 ' /* There is at least one mandatory TLV, don\'t allow NULL input */\n'
158 ' if (!input) {\n'
159 ' g_set_error (error,\n'
160 ' QMI_CORE_ERROR,\n'
161 ' QMI_CORE_ERROR_INVALID_ARGS,\n'
162 ' "Message \'${name}\' has mandatory TLVs");\n'
163 ' return NULL;\n'
164 ' }\n')
165 cfile.write(string.Template(template).substitute(translations))
166
167 # Now iterate fields
168 for field in self.input.fields:
169 translations['tlv_name'] = field.name
170 translations['variable_name'] = field.variable_name
171 template = (
172 '\n'
173 ' /* Try to add the \'${tlv_name}\' TLV */\n'
174 ' if (input->${variable_name}_set) {\n')
175 cfile.write(string.Template(template).substitute(translations))
176
177 # Emit the TLV getter
178 field.emit_input_tlv_add(cfile, ' ')
179
180 if field.mandatory:
181 template = (
182 ' } else {\n'
183 ' g_set_error (error,\n'
184 ' QMI_CORE_ERROR,\n'
185 ' QMI_CORE_ERROR_INVALID_ARGS,\n'
186 ' "Missing mandatory TLV \'${tlv_name}\' in message \'${name}\'");\n'
187 ' return NULL;\n')
188 cfile.write(string.Template(template).substitute(translations))
189
190 cfile.write(
191 ' }\n')
192 cfile.write(
193 '\n'
194 ' return g_steal_pointer (&self);\n'
195 '}\n')
196
197
198 """
199 Emit method responsible for parsing a response/indication of the given type
200 """
201 def __emit_response_or_indication_parser(self, hfile, cfile):
202 # If no output fields to parse, don't emit anything
203 if self.output is None or self.output.fields is None:
204 return
205
206 translations = { 'name' : self.name,
207 'type' : 'response' if self.type == 'Message' else 'indication',
208 'method_prefix' : '__' if self.static else '',
209 'method_scope' : 'static ' if self.static else '',
210 'since' : self.since if utils.version_compare('1.34',self.since) > 0 else '1.34',
211 'container' : utils.build_camelcase_name (self.output.fullname),
212 'container_underscore' : utils.build_underscore_name (self.output.fullname),
213 'underscore' : utils.build_underscore_name (self.fullname),
214 'message_id' : self.id_enum_name }
215
216 if not self.static:
217 template = (
218 '\n'
219 '/**\n'
220 ' * ${method_prefix}${underscore}_${type}_parse:\n'
221 ' * @message: a #QmiMessage.\n'
222 ' * @error: return location for error or %NULL.\n'
223 ' *\n'
224 ' * Parses a #QmiMessage and builds a #${container} out of it.\n'
225 ' * The operation fails if the message is of the wrong type.\n'
226 ' *\n'
227 ' * Returns: a #${container}, or %NULL if @error is set. The returned value should be freed with ${container_underscore}_unref().\n'
228 ' *\n'
229 ' * Since: ${since}\n'
230 ' */\n'
231 '${container} *${method_prefix}${underscore}_${type}_parse (\n'
232 ' QmiMessage *message,\n'
233 ' GError **error);\n')
234 hfile.write(string.Template(template).substitute(translations))
235
236 template = (
237 '\n'
238 '${method_scope}${container} *\n'
239 '${method_prefix}${underscore}_${type}_parse (\n'
240 ' QmiMessage *message,\n'
241 ' GError **error)\n'
242 '{\n'
243 ' ${container} *self;\n'
244 '\n'
245 ' g_assert_cmphex (qmi_message_get_message_id (message), ==, ${message_id});\n'
246 '\n'
247 ' self = g_slice_new0 (${container});\n'
248 ' self->ref_count = 1;\n')
249 cfile.write(string.Template(template).substitute(translations))
250
251 for field in self.output.fields:
252 cfile.write(
253 '\n'
254 ' do {\n')
255 field.emit_output_prerequisite_check(cfile, ' ')
256 cfile.write(
257 '\n'
258 ' {\n')
259 field.emit_output_tlv_get(cfile, ' ')
260 cfile.write(
261 '\n'
262 ' }\n')
263 cfile.write(
264 ' } while (0);\n')
265 cfile.write(
266 '\n'
267 ' return self;\n'
268 '}\n')
269
270
271 """
272 Emit method responsible for getting a printable representation of the whole
273 request/response
274 """
275 def __emit_helpers(self, hfile, cfile):
276 need_tlv_printable = False
277 if self.input is not None and self.input.fields is not None:
278 need_tlv_printable = True
279 for field in self.input.fields:
280 field.emit_tlv_helpers(cfile)
281
282 if self.output is not None and self.output.fields is not None:
283 need_tlv_printable = True
284 for field in self.output.fields:
285 field.emit_tlv_helpers(cfile)
286
287 translations = { 'name' : self.name,
288 'service' : self.service,
289 'id' : self.id,
290 'type' : utils.build_underscore_name(self.type),
291 'underscore' : utils.build_underscore_name(self.name) }
292
293 template = ''
294 if need_tlv_printable:
295 template += (
296 '\n'
297 'struct ${type}_${underscore}_context {\n'
298 ' QmiMessage *self;\n'
299 ' const gchar *line_prefix;\n'
300 ' GString *printable;\n'
301 '};\n'
302 '\n'
303 'static void\n'
304 '${type}_${underscore}_get_tlv_printable (\n'
305 ' guint8 type,\n'
306 ' const guint8 *value,\n'
307 ' gsize length,\n'
308 ' struct ${type}_${underscore}_context *ctx)\n'
309 '{\n'
310 ' const gchar *tlv_type_str = NULL;\n'
311 ' g_autofree gchar *translated_value = NULL;\n'
312 ' gboolean value_has_personal_info = FALSE;\n'
313 '\n')
314
315 if self.type == 'Message':
316 template += (
317 ' if (!qmi_message_is_response (ctx->self)) {\n'
318 ' switch (type) {\n')
319
320 if self.input is not None and self.input.fields is not None:
321 for field in self.input.fields:
322 translations['underscore_field'] = utils.build_underscore_name(field.fullname)
323 translations['field_enum'] = field.id_enum_name
324 translations['field_name'] = field.name
325 field_template = (
326 ' case ${field_enum}:\n'
327 ' tlv_type_str = "${field_name}";\n'
328 ' translated_value = ${underscore_field}_get_printable (\n'
329 ' ctx->self,\n'
330 ' ctx->line_prefix);\n')
331 if field.variable is not None and field.variable.contains_personal_info:
332 field_template += (
333 ' value_has_personal_info = TRUE;\n')
334 field_template += (
335 ' break;\n')
336 template += string.Template(field_template).substitute(translations)
337
338 template += (
339 ' default:\n'
340 ' break;\n'
341 ' }\n'
342 ' } else {\n')
343 else:
344 template += (' {\n')
345
346 template += (' switch (type) {\n')
347 if self.output is not None and self.output.fields is not None:
348 for field in self.output.fields:
349 translations['underscore_field'] = utils.build_underscore_name(field.fullname)
350 translations['field_enum'] = field.id_enum_name
351 translations['field_name'] = field.name
352 field_template = (
353 ' case ${field_enum}:\n'
354 ' tlv_type_str = "${field_name}";\n'
355 ' translated_value = ${underscore_field}_get_printable (\n'
356 ' ctx->self,\n'
357 ' ctx->line_prefix);\n')
358 if field.variable is not None and field.variable.contains_personal_info:
359 field_template += (
360 ' value_has_personal_info = TRUE;\n')
361 field_template += (
362 ' break;\n')
363 template += string.Template(field_template).substitute(translations)
364
365 template += (
366 ' default:\n'
367 ' break;\n'
368 ' }\n'
369 ' }\n'
370 '\n'
371 ' if (!tlv_type_str) {\n'
372 ' g_autofree gchar *value_str = NULL;\n'
373 '\n'
374 ' value_str = qmi_message_get_tlv_printable (ctx->self,\n'
375 ' ctx->line_prefix,\n'
376 ' type,\n'
377 ' value,\n'
378 ' length);\n'
379 ' g_string_append (ctx->printable, value_str);\n'
380 ' } else {\n'
381 ' g_autofree gchar *value_hex = NULL;\n'
382 '\n'
383 ' if (qmi_utils_get_show_personal_info () || !value_has_personal_info)\n'
384 ' value_hex = qmi_common_str_hex (value, length, \':\');\n'
385 ' else\n'
386 ' value_hex = g_strdup ("###...");\n'
387 '\n'
388 ' g_string_append_printf (ctx->printable,\n'
389 ' "%sTLV:\\n"\n'
390 ' "%s type = \\"%s\\" (0x%02x)\\n"\n'
391 ' "%s length = %" G_GSIZE_FORMAT "\\n"\n'
392 ' "%s value = %s\\n"\n'
393 ' "%s translated = %s\\n",\n'
394 ' ctx->line_prefix,\n'
395 ' ctx->line_prefix, tlv_type_str, type,\n'
396 ' ctx->line_prefix, length,\n'
397 ' ctx->line_prefix, value_hex,\n'
398 ' ctx->line_prefix, translated_value ? translated_value : "");\n'
399 ' }\n'
400 '}\n')
401
402 template += (
403 '\n'
404 'static gchar *\n'
405 '${type}_${underscore}_get_printable (\n'
406 ' QmiMessage *self,\n'
407 ' const gchar *line_prefix)\n'
408 '{\n'
409 ' GString *printable;\n'
410 '\n'
411 ' printable = g_string_new ("");\n'
412 ' g_string_append_printf (printable,\n'
413 ' "%s message = \\\"${name}\\\" (${id})\\n",\n'
414 ' line_prefix);\n')
415
416 if need_tlv_printable:
417 template += (
418 '\n'
419 ' {\n'
420 ' struct ${type}_${underscore}_context ctx;\n'
421 ' ctx.self = self;\n'
422 ' ctx.line_prefix = line_prefix;\n'
423 ' ctx.printable = printable;\n'
424 ' qmi_message_foreach_raw_tlv (self,\n'
425 ' (QmiMessageForeachRawTlvFn)${type}_${underscore}_get_tlv_printable,\n'
426 ' &ctx);\n'
427 ' }\n')
428 template += (
429 '\n'
430 ' return g_string_free (printable, FALSE);\n'
431 '}\n')
432 cfile.write(string.Template(template).substitute(translations))
433
434
435 """
436 Emit request/response/indication handling implementation
437 """
438 def emit(self, hfile, cfile):
439 if self.type == 'Message':
440 utils.add_separator(hfile, 'REQUEST/RESPONSE', self.fullname);
441 utils.add_separator(cfile, 'REQUEST/RESPONSE', self.fullname);
442 else:
443 utils.add_separator(hfile, 'INDICATION', self.fullname);
444 utils.add_separator(cfile, 'INDICATION', self.fullname);
445
446 if self.type == 'Message':
447 hfile.write('\n/* --- Input -- */\n');
448 cfile.write('\n/* --- Input -- */\n');
449 self.input.emit(hfile, cfile)
450 self.__emit_request_creator(hfile, cfile)
451
452 hfile.write('\n/* --- Output -- */\n');
453 cfile.write('\n/* --- Output -- */\n');
454 self.output.emit(hfile, cfile)
455 self.__emit_helpers(hfile, cfile)
456 self.__emit_response_or_indication_parser(hfile, cfile)
457
458 """
459 Emit the sections
460 """
461 def emit_sections(self, sfile):
462 message = []
463 types = []
464
465 if self.static:
466 return
467
468 translations = { 'hyphened' : utils.build_dashed_name (self.fullname),
469 'service' : utils.build_underscore_name (self.service),
470 'service_camelcase' : utils.build_camelcase_name (self.service),
471 'name_underscore' : utils.build_underscore_name (self.name),
472 'fullname' : self.service + ' ' + self.name,
473 'type' : 'response' if self.type == 'Message' else 'indication' }
474
475 if self.type == 'Message':
476 template = ''
477 if not self.static and self.output is not None and self.output.fields is not None:
478 template += (
479 '- [func@message_${service}_${name_underscore}_response_parse]\n\n')
480 template += (
481 '- [method@QmiClient${service_camelcase}.${name_underscore}]\n\n'
482 '- [method@QmiClient${service_camelcase}.${name_underscore}_finish]\n')
483 message = string.Template(template).substitute(translations)
484 translations['message_type'] = 'request and response'
485 translations['message_type_subject'] = 'Request'
486 elif self.type == 'Indication':
487 if not self.static and self.output is not None and self.output.fields is not None:
488 template = (
489 '- [func@indication_${service}_${name_underscore}_indication_parse]\n')
490 message = string.Template(template).substitute(translations)
491 translations['message_type'] = 'indication'
492 translations['message_type_subject'] = 'Indication'
493
494 translations['message'] = message or ''
495
496 translations['message_types'] = ''
497 if not self.static:
498 if self.output is not None and self.output.fields is not None:
499 translations['output_type'] = utils.build_camelcase_name (self.output.fullname)
500 template = ('- [struct@${output_type}]\n')
501 translations['message_types'] += string.Template(template).substitute(translations)
502 if self.input is not None and self.input.fields is not None:
503 translations['input_type'] = utils.build_camelcase_name (self.input.fullname)
504 template = ('- [struct@${input_type}]')
505 translations['message_types'] += string.Template(template).substitute(translations)
506
507 template = (
508 '### ${fullname} ${message_type_subject}\n'
509 'Methods to manage the ${fullname} ${message_type}:\n'
510 '\n'
511 '${message}\n'
512 '\n'
513 'Types to manage the ${fullname} ${message_type}:\n'
514 '\n'
515 '${message_types}'
516 '\n')
517 sfile.write(string.Template(template).substitute(translations))