3 # Copyright (c) 2018 Cisco and/or its affiliates.
4 # Licensed under the Apache License, Version 2.0 (the "License");
5 # you may not use this file except in compliance with the License.
6 # You may obtain a copy of the License at:
8 # http://www.apache.org/licenses/LICENSE-2.0
10 # Unless required by applicable law or agreed to in writing, software
11 # distributed under the License is distributed on an "AS IS" BASIS,
12 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 # See the License for the specific language governing permissions and
14 # limitations under the License.
18 from collections import OrderedDict
22 BASE_PACKAGE = "io.fd.vpp.jvpp"
25 class ParseException(Exception):
30 def __init__(self, name, java_name, java_name_fqn, jni_signature, jni_type, jni_accessor,
31 host_to_net_function, net_to_host_function):
33 Initializes Type class.
35 :param name: name of type as defined in .api file, e.g. u8, u32[] or mac_entry
36 :param java_name: corresponding java name, e.g. byte, int[] or MacEntry
37 :param java_name_fqn: fully qualified java name, e.g. io.fd.vpp.jvpp.core.types.MacEntry
38 :param jni_signature: JNI Type signature, e.g. B, [I or Lio.fd.vpp.jvpp.core.types.MacEntry;
39 See https://docs.oracle.com/javase/8/docs/technotes/guides/jni/spec/types.html#type_signatures
40 :param jni_type: JNI reference type, e.g. jbyte jintArray, jobject
41 See https://docs.oracle.com/javase/8/docs/technotes/guides/jni/spec/types.html#reference_types
42 :param jni_accessor: Java type do by used in Get<type>Field, Set<type>Field and other functions.
43 See https://docs.oracle.com/javase/8/docs/technotes/guides/jni/spec/functions.html#accessing_fields_of_objects
44 :param host_to_net_function: name of function host to net byte order swap function
45 :param net_to_host_function: name of function net to host byte order swap function
48 self.java_name = java_name
50 # Java generation specific properties, TODO(VPP-1186): move to Java specific subclass
51 self.java_name_fqn = java_name_fqn
53 # JNI generation specific properties, TODO(VPP-1186): move to JNI specific subclass
54 self.jni_signature = jni_signature
57 # https://docs.oracle.com/javase/8/docs/technotes/guides/jni/spec/types.html#primitive_types
59 # https://docs.oracle.com/javase/8/docs/technotes/guides/jni/spec/types.html#reference_types
60 self.jni_type = jni_type
62 # Java type do by used in Get<type>Field, Set<type>Field and other functions, see:
63 # https://docs.oracle.com/javase/8/docs/technotes/guides/jni/spec/functions.html#accessing_fields_of_objects
64 self.jni_accessor = jni_accessor
66 self.host_to_net_function = host_to_net_function
67 self.net_to_host_function = net_to_host_function
68 self.is_swap_needed = host_to_net_function and net_to_host_function
71 class SimpleType(Type):
72 def __init__(self, name, java_name, jni_signature, jni_type, jni_accessor,
73 host_to_net_function=None, net_to_host_function=None):
74 super(SimpleType, self).__init__(
77 java_name_fqn=java_name,
78 jni_signature=jni_signature,
80 jni_accessor=jni_accessor,
81 host_to_net_function=host_to_net_function,
82 net_to_host_function=net_to_host_function
86 def get_host_to_net_function(self, host_ref_name, net_ref_name):
87 return "%s = %s(%s)" % (net_ref_name, self.host_to_net_function, host_ref_name)
90 return "SimpleType{name:%s, java_name:%s}" % (self.name, self.java_name)
93 # TODO(VPP-1187): add array host to net functions to reduce number of members and simplify JNI generation
95 def __init__(self, base_type):
96 super(Array, self).__init__(
97 name=base_type.name + _ARRAY_SUFFIX,
98 java_name=base_type.java_name + _ARRAY_SUFFIX,
99 java_name_fqn=base_type.java_name_fqn + _ARRAY_SUFFIX,
100 jni_signature="[%s" % base_type.jni_signature,
101 jni_type="%sArray" % base_type.jni_type,
102 jni_accessor="Object",
103 host_to_net_function=base_type.host_to_net_function,
104 net_to_host_function=base_type.net_to_host_function
106 self.base_type = base_type
108 def get_host_to_net_function(self, host_ref_name, net_ref_name):
109 return self.base_type.get_host_to_net_function(host_ref_name, net_ref_name)
112 return "Array{name:%s, java_name:%s}" % (self.name, self.java_name)
116 def __init__(self, name, value, constants, definition, plugin_name):
117 _java_name = _underscore_to_camelcase_upper(name)
119 super(Enum, self).__init__(
121 java_name=_java_name,
122 java_name_fqn="io.fd.vpp.jvpp.%s.types.%s" % (plugin_name, _java_name),
123 jni_signature="Lio/fd/vpp/jvpp/%s/types/%s;" % (plugin_name, _java_name),
125 jni_accessor="Object",
126 host_to_net_function="_host_to_net_%s" % name,
127 net_to_host_function="_net_to_host_%s" % name
131 self.constants = constants
132 self.doc = _message_to_javadoc(definition)
133 self.java_name_lower = _underscore_to_camelcase_lower(name)
134 self.vpp_name = "%s%s%s" % (_VPP_TYPE_PREFIX, name, _VPP_TYPE_SUFFIX)
135 # Fully qualified class name used by FindClass function, see:
136 # https://docs.oracle.com/javase/8/docs/technotes/guides/jni/spec/functions.html#FindClass
137 self.jni_name = "io/fd/vpp/jvpp/%s/types/%s" % (plugin_name, _java_name)
139 def get_host_to_net_function(self, host_ref_name, net_ref_name):
140 return "_host_to_net_%s(env, %s, &(%s))" % (self.name, host_ref_name, net_ref_name)
144 def __init__(self, name, crc, fields, definition, plugin_name):
145 _java_name = _underscore_to_camelcase_upper(name)
147 super(Class, self).__init__(
149 java_name=_java_name,
150 java_name_fqn="io.fd.vpp.jvpp.%s.types.%s" % (plugin_name, _java_name),
151 jni_signature="Lio/fd/vpp/jvpp/%s/types/%s;" % (plugin_name, _java_name),
153 jni_accessor="Object",
154 host_to_net_function="_host_to_net_%s" % name,
155 net_to_host_function="_net_to_host_%s" % name
160 self.doc = _message_to_javadoc(definition)
161 self.java_name_lower = _underscore_to_camelcase_lower(name)
162 self.vpp_name = "%s%s%s" % (_VPP_TYPE_PREFIX, name, _VPP_TYPE_SUFFIX)
163 # Fully qualified class name used by FindClass function, see:
164 # https://docs.oracle.com/javase/8/docs/technotes/guides/jni/spec/functions.html#FindClass
165 self.jni_name = "io/fd/vpp/jvpp/%s/types/%s" % (plugin_name, _java_name)
167 def get_host_to_net_function(self, host_ref_name, net_ref_name):
168 return "_host_to_net_%s(env, %s, &(%s))" % (self.name, host_ref_name, net_ref_name)
172 def __init__(self, name, crc, fields, definition, plugin_name):
173 _java_name = _underscore_to_camelcase_upper(name)
175 super(Union, self).__init__(
177 java_name=_java_name,
178 java_name_fqn="io.fd.vpp.jvpp.%s.types.%s" % (plugin_name, _java_name),
179 jni_signature="Lio/fd/vpp/jvpp/%s/types/%s;" % (plugin_name, _java_name),
181 jni_accessor="Object",
182 host_to_net_function="_host_to_net_%s" % name,
183 net_to_host_function="_net_to_host_%s" % name
188 self.doc = _message_to_javadoc(definition)
189 self.java_name_lower = _underscore_to_camelcase_lower(name)
190 self.vpp_name = "%s%s%s" % (_VPP_TYPE_PREFIX, name, _VPP_TYPE_SUFFIX)
191 # Fully qualified class name used by FindClass function, see:
192 # https://docs.oracle.com/javase/8/docs/technotes/guides/jni/spec/functions.html#FindClass
193 self.jni_name = "io/fd/vpp/jvpp/%s/types/%s" % (plugin_name, _java_name)
195 def get_host_to_net_function(self, host_ref_name, net_ref_name):
196 return "_host_to_net_%s(env, %s, &(%s))" % (self.name, host_ref_name, net_ref_name)
200 def __init__(self, name, field_type, array_len=None, array_len_field=None):
202 self.java_name = _underscore_to_camelcase_lower(name)
203 self.java_name_upper = _underscore_to_camelcase_upper(name)
204 self.type = field_type
205 self.array_len = array_len
206 self.array_len_field = array_len_field
209 return "Field{name:%s, java_name:%s, type:%s}" % (self.name, self.java_name, self.type)
212 class Message(object):
213 def __init__(self, name, crc, fields, definition):
215 self.java_name_upper = _underscore_to_camelcase_upper(name)
216 self.java_name_lower = _underscore_to_camelcase_lower(name)
219 self.has_fields = fields != []
220 self.doc = _message_to_javadoc(definition)
223 return "Message{name:%s, java_name:%s, crc:%s, fields:%s}" % (
224 self.name, self.java_name_upper, self.crc, self.fields)
227 class Event(Message):
228 def __init__(self, name, crc, fields, definition):
229 super(Event, self).__init__(name, crc, fields, definition)
232 class Request(Message):
233 def __init__(self, name, reply, crc, fields, definition):
234 super(Request, self).__init__(name, crc, fields, definition)
236 self.reply_java = _underscore_to_camelcase_upper(reply)
239 return "Request{name:%s, reply:%s, crc:%s, fields:%s}" % (self.name, self.reply, self.crc, self.fields)
242 class Reply(Message):
243 def __init__(self, name, request, crc, fields, definition):
244 super(Reply, self).__init__(name, crc, fields, definition)
245 self.request = request
246 self.request_java = _underscore_to_camelcase_upper(request)
249 return "Reply{name:%s, request:%s, crc:%s, fields:%s}" % (self.name, self.request, self.crc, self.fields)
253 def __init__(self, name, details, crc, fields, definition):
254 super(Dump, self).__init__(name, crc, fields, definition)
255 self.details = details
256 self.reply_java = _underscore_to_camelcase_upper(details)
259 return "Dump{name:%s, details:%s, crc:%s, fields:%s}" % (self.name, self.details, self.crc, self.fields)
262 class Details(Message):
263 def __init__(self, name, dump, crc, fields, definition):
264 super(Details, self).__init__(name, crc, fields, definition)
266 self.request_java = _underscore_to_camelcase_upper(dump)
269 return "Details{name:%s, dump:%s, crc:%s, fields:%s}" % (self.name, self.dump, self.crc, self.fields)
272 def is_retval(field):
273 return field.name == u'retval'
277 return field.array_len is not None
281 return hasattr(msg, 'reply')
285 return hasattr(msg, 'request')
289 return hasattr(msg, 'details')
293 return hasattr(msg, 'dump')
297 return isinstance(msg, Event)
300 def is_control_ping(msg):
301 return msg.name == u'control_ping'
304 def is_control_ping_reply(msg):
305 return msg.name == u'control_ping_reply'
309 s = str(block).encode()
310 return binascii.crc32(s) & 0xffffffff
313 class JVppModel(object):
314 def __init__(self, logger, json_api_files, plugin_name):
316 # TODO(VPP-1188): provide json_file_by_definition map to improve javadoc
317 self.json_api_files = json_api_files
318 self.plugin_package = BASE_PACKAGE + "." + plugin_name
319 self.plugin_name = plugin_name
320 self.plugin_java_name = _underscore_to_camelcase_upper(plugin_name)
321 self._load_json_files(json_api_files)
322 self._parse_services()
323 self._parse_messages()
324 self._validate_messages()
326 def _load_json_files(self, json_api_files):
331 for file_name in json_api_files:
332 with open(file_name) as f:
334 types.update({d[0]: {'type': 'enum', 'data': d} for d in j['enums']})
335 types.update({d[0]: {'type': 'type', 'data': d} for d in j['types']})
336 types.update({d[0]: {'type': 'union', 'data': d} for d in j['unions']})
337 self._messages.extend(j['messages'])
338 self._services.update(j['services'])
339 self._aliases.update(j['aliases'])
341 self._parse_types(types)
343 def _parse_aliases(self, types):
344 for alias_name in self._aliases:
345 alias = self._aliases[alias_name]
346 alias_type = {"type": "type"}
347 java_name_lower = _underscore_to_camelcase_lower(alias_name)
348 vpp_type = alias["type"]
349 crc_value = '0x%08x' % crc(alias_name)
350 if "length" in alias:
351 length = alias["length"]
352 alias_type["data"] = [
364 alias_type["data"] = [
375 types[alias_name] = alias_type
377 def _parse_types(self, types):
378 self._parse_simple_types()
379 self._parse_aliases(types)
383 for name, value in types.items():
384 if name in self._types_by_name:
388 data = value['data'][1:]
391 type = self._parse_enum(name, data)
392 elif type == 'union':
393 type = self._parse_union(name, data)
395 type = self._parse_type(name, data)
397 self.logger.warning("Unsupported type %s. Ignoring...", type)
400 self._types_by_name[name] = type
401 self._types_by_name[name + _ARRAY_SUFFIX] = Array(type)
402 except ParseException as e:
403 self.logger.debug("Failed to parse %s type in iteration %s: %s.", name, i, e)
404 unresolved[name] = value
405 if len(unresolved) == 0:
408 raise ParseException('Unresolved type definitions {}'
413 self.types = self._types_by_name.values()
415 def _parse_simple_types(self):
416 # Mapping according to:
417 # http://docs.oracle.com/javase/7/do+'[]'cs/technotes/guides/jni/spec/types.html
419 # https://docs.oracle.com/javase/8/docs/technotes/guides/jni/spec/functions.html#Get_type_Field_routines
421 # Unsigned types are converted to signed java types that have the same size.
422 # It is the API user responsibility to interpret them correctly.
424 self._types_by_name = OrderedDict({
425 'u8': SimpleType('u8', 'byte', 'B', 'jbyte', 'Byte'),
426 'i8': SimpleType('i8', 'byte', 'B', 'jbyte', 'Byte'),
427 'u16': SimpleType('u16', 'short', 'S', 'jshort', 'Short',
428 host_to_net_function='clib_host_to_net_u16',
429 net_to_host_function='clib_net_to_host_u16'),
430 'i16': SimpleType('i16', 'short', 'S', 'jshort', 'Short',
431 host_to_net_function='clib_host_to_net_i16',
432 net_to_host_function='clib_net_to_host_i16'),
433 'u32': SimpleType('u32', 'int', 'I', 'jint', 'Int',
434 host_to_net_function='clib_host_to_net_u32',
435 net_to_host_function='clib_net_to_host_u32'),
436 'i32': SimpleType('i32', 'int', 'I', 'jint', 'Int',
437 host_to_net_function='clib_host_to_net_i32',
438 net_to_host_function='clib_net_to_host_i32'),
439 'u64': SimpleType('u64', 'long', 'J', 'jlong', 'Long',
440 host_to_net_function='clib_host_to_net_u64',
441 net_to_host_function='clib_net_to_host_u64'),
442 'i64': SimpleType('i64', 'long', 'J', 'jlong', 'Long',
443 host_to_net_function='clib_host_to_net_i64',
444 net_to_host_function='clib_net_to_host_i64'),
445 'f64': SimpleType('f64', 'double', 'D', 'jdouble', 'Double')
448 for n, t in self._types_by_name.items():
449 self._types_by_name[n + _ARRAY_SUFFIX] = Array(t)
451 def _parse_enum(self, name, definition):
452 self.logger.debug("Parsing enum %s: %s", name, definition)
455 for item in definition:
456 if type(item) is dict and 'enumtype' in item:
457 type_name = item['enumtype']
459 constants.append({'name': item[0], 'value': item[1]})
461 raise ParseException("'enumtype' was not defined for %s" % definition)
462 return Enum(name, Field('value', self._types_by_name[type_name]), constants, definition, self.plugin_name)
464 def _parse_union(self, name, definition):
465 self.logger.debug("Parsing union %s: %s", name, definition)
466 crc, fields = self._parse_fields(definition)
467 return Union(name, crc, fields, definition, self.plugin_name)
469 def _parse_type(self, name, definition):
470 self.logger.debug("Parsing type %s: %s", name, definition)
471 crc, fields = self._parse_fields(definition)
472 return Class(name, crc, fields, definition, self.plugin_name)
474 def _parse_services(self):
475 self._dumps_by_details = {}
476 self._requests_by_reply = {}
477 for name, service in self._services.iteritems():
478 if _is_stream(service):
479 self._dumps_by_details[service['reply']] = name
481 self._requests_by_reply[service['reply']] = name
483 def _parse_messages(self):
484 # Preserve ordering from JSON file to make debugging easier.
485 self._messages_by_name = OrderedDict()
486 for msg in self._messages:
490 self._messages_by_name[name] = self._parse_message(name, definition)
491 except ParseException as e:
492 self.logger.warning("Failed to parse message %s: %s. Skipping message.", name, e)
494 def _parse_message(self, name, definition):
495 self.logger.debug("Parsing message %s: %s", name, definition)
496 crc, fields = self._parse_fields(definition)
497 if name in self._services:
498 service = self._services[name]
499 reply = service['reply']
500 if _is_stream(service):
501 return Dump(name, reply, crc, filter(_is_request_field, fields), definition)
503 return Request(name, reply, crc, filter(_is_request_field, fields), definition)
505 return Event(name, crc, filter(_is_request_field, fields), definition)
506 elif name in self._requests_by_reply:
507 return Reply(name, self._requests_by_reply[name], crc, filter(_is_reply_field, fields), definition)
508 elif name in self._dumps_by_details:
509 return Details(name, self._dumps_by_details[name], crc, filter(_is_reply_field, fields), definition)
511 # TODO: some messages like combined_counters are not visible in the services.
512 # Throw exception instead (requires fixing vppagigen).
513 return Event(name, crc, filter(_is_request_field, fields), definition)
515 def _parse_fields(self, definition):
518 for item in definition:
519 if type(item) == dict and 'crc' in item:
522 fields.append(self._parse_field(item, fields))
524 raise ParseException("CRC was not defined for %s" % definition)
527 def _parse_field(self, field, fields):
528 type_name = _extract_type_name(field[0])
530 if type_name in self._types_by_name:
533 array_len_field = None
536 if f.name == field[3]:
538 if not array_len_field:
539 raise ParseException("Could not find field %s declared as length of array %s",
541 return Field(field[1], self._types_by_name[type_name + _ARRAY_SUFFIX], field[2], array_len_field)
543 return Field(field[1], self._types_by_name[type_name])
545 raise ParseException("Unknown field type %s" % field)
547 def _validate_messages(self):
549 In case if message A is known to be reply for message B, and message B was not correctly parsed,
550 remove message A from the set of all messages.
553 messages = self._messages_by_name
554 for name, msg in messages.iteritems():
555 if (is_request(msg) and msg.reply not in messages) \
556 or (is_reply(msg) and msg.request not in messages) \
557 or (is_dump(msg) and msg.details not in messages) \
558 or (is_details(msg) and msg.dump not in messages):
559 to_be_removed.append(name)
561 for name in to_be_removed:
564 self.messages = self._messages_by_name.values()
570 def _underscore_to_camelcase_upper(name):
571 return name.title().replace("_", "")
574 def _underscore_to_camelcase_lower(name):
575 name = name.title().replace("_", "")
576 return name[0].lower() + name[1:]
579 def _message_to_javadoc(message_definition):
580 """ Converts JSON message definition to javadoc """
581 formatted_message = pprint.pformat(message_definition, indent=4, width=120, depth=None)
582 return " * " + formatted_message.replace("\n", "\n * ")
585 def _is_stream(service):
587 Checks if service represents stream, e.g.:
589 "reply": "ip_address_details",
592 :param service: JSON definition of service
593 :return: value assigned to "stream" or None
595 return "stream" in service
598 def _extract_type_name(name):
599 if name.startswith(_VPP_TYPE_PREFIX) and name.endswith(_VPP_TYPE_SUFFIX):
600 return name[len(_VPP_TYPE_PREFIX): - len(_VPP_TYPE_SUFFIX)]
603 _VPP_TYPE_PREFIX = "vl_api_"
605 _VPP_TYPE_SUFFIX = "_t"
608 def _is_request_field(field):
609 # Skip fields that are hidden to the jvpp user (handled by JNI layer)
610 return field.name not in {'_vl_msg_id', 'client_index', 'context'}
613 def _is_reply_field(field):
614 # Skip fields that are hidden to the jvpp user:
615 # _vl_msg_id is handled at JNI layer,
616 # Unlike in the request case, context is visible to allow matching replies with requests at Java layer.
617 return field.name not in {'_vl_msg_id'}