src/vpp-api/java/jvpp/gen/jvppgen/jvpp_model.py

   1 #!/usr/bin/env python2
   2 #
   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:
   7 #
   8 #     http://www.apache.org/licenses/LICENSE-2.0
   9 #
  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.
  15 #
  16 import json
  17 import pprint
  18 from collections import OrderedDict
  19
  20 BASE_PACKAGE = "io.fd.vpp.jvpp"
  21
  22
  23 class ParseException(Exception):
  24     pass
  25
  26
  27 class Type(object):
  28     def __init__(self, name, java_name, java_name_fqn, jni_signature, jni_type, jni_accessor,
  29                  host_to_net_function, net_to_host_function):
  30         """
  31         Initializes Type class.
  32
  33         :param name: name of type as defined in .api file, e.g. u8, u32[] or mac_entry
  34         :param java_name: corresponding java name, e.g. byte, int[] or MacEntry
  35         :param java_name_fqn: fully qualified java name, e.g. io.fd.vpp.jvpp.core.types.MacEntry
  36         :param jni_signature: JNI Type signature, e.g. B, [I or Lio.fd.vpp.jvpp.core.types.MacEntry;
  37                               See https://docs.oracle.com/javase/8/docs/technotes/guides/jni/spec/types.html#type_signatures
  38         :param jni_type: JNI reference type, e.g. jbyte jintArray, jobject
  39                          See https://docs.oracle.com/javase/8/docs/technotes/guides/jni/spec/types.html#reference_types
  40         :param jni_accessor: Java type do by used in Get<type>Field, Set<type>Field and other functions.
  41                              See https://docs.oracle.com/javase/8/docs/technotes/guides/jni/spec/functions.html#accessing_fields_of_objects
  42         :param host_to_net_function: name of function host to net byte order swap function
  43         :param net_to_host_function: name of function net to host byte order swap function
  44         """
  45         self.name = name
  46         self.java_name = java_name
  47
  48         # Java generation specific properties, TODO(VPP-1186): move to Java specific subclass
  49         self.java_name_fqn = java_name_fqn
  50
  51         # JNI generation specific properties, TODO(VPP-1186): move to JNI specific subclass
  52         self.jni_signature = jni_signature
  53
  54         # Native type, see:
  55         # https://docs.oracle.com/javase/8/docs/technotes/guides/jni/spec/types.html#primitive_types
  56         # and
  57         # https://docs.oracle.com/javase/8/docs/technotes/guides/jni/spec/types.html#reference_types
  58         self.jni_type = jni_type
  59
  60         # Java type do by used in Get<type>Field, Set<type>Field and other functions, see:
  61         # https://docs.oracle.com/javase/8/docs/technotes/guides/jni/spec/functions.html#accessing_fields_of_objects
  62         self.jni_accessor = jni_accessor
  63
  64         self.host_to_net_function = host_to_net_function
  65         self.net_to_host_function = net_to_host_function
  66         self.is_swap_needed = host_to_net_function and net_to_host_function
  67
  68
  69 class SimpleType(Type):
  70     def __init__(self, name, java_name, jni_signature, jni_type, jni_accessor,
  71                  host_to_net_function=None, net_to_host_function=None):
  72         super(SimpleType, self).__init__(
  73             name=name,
  74             java_name=java_name,
  75             java_name_fqn=java_name,
  76             jni_signature=jni_signature,
  77             jni_type=jni_type,
  78             jni_accessor=jni_accessor,
  79             host_to_net_function=host_to_net_function,
  80             net_to_host_function=net_to_host_function
  81         )
  82         self.vpp_name = name
  83
  84     def get_host_to_net_function(self, host_ref_name, net_ref_name):
  85         return "%s = %s(%s)" % (net_ref_name, self.host_to_net_function, host_ref_name)
  86
  87     def __str__(self):
  88         return "SimpleType{name:%s, java_name:%s}" % (self.name, self.java_name)
  89
  90
  91 # TODO(VPP-1187): add array host to net functions to reduce number of members and simplify JNI generation
  92 class Array(Type):
  93     def __init__(self, base_type):
  94         super(Array, self).__init__(
  95             name=base_type.name + _ARRAY_SUFFIX,
  96             java_name=base_type.java_name + _ARRAY_SUFFIX,
  97             java_name_fqn=base_type.java_name_fqn + _ARRAY_SUFFIX,
  98             jni_signature="[%s" % base_type.jni_signature,
  99             jni_type="%sArray" % base_type.jni_type,
 100             jni_accessor="Object",
 101             host_to_net_function=base_type.host_to_net_function,
 102             net_to_host_function=base_type.net_to_host_function
 103         )
 104         self.base_type = base_type
 105
 106     def get_host_to_net_function(self, host_ref_name, net_ref_name):
 107         return self.base_type.get_host_to_net_function(host_ref_name, net_ref_name)
 108
 109     def __str__(self):
 110         return "Array{name:%s, java_name:%s}" % (self.name, self.java_name)
 111
 112
 113 class Enum(Type):
 114     def __init__(self, name, value, constants, definition, plugin_name):
 115         _java_name = _underscore_to_camelcase_upper(name)
 116
 117         super(Enum, self).__init__(
 118             name=name,
 119             java_name=_java_name,
 120             java_name_fqn="io.fd.vpp.jvpp.%s.types.%s" % (plugin_name, _java_name),
 121             jni_signature="Lio/fd/vpp/jvpp/%s/types/%s;" % (plugin_name, _java_name),
 122             jni_type="jobject",
 123             jni_accessor="Object",
 124             host_to_net_function="_host_to_net_%s" % name,
 125             net_to_host_function="_net_to_host_%s" % name
 126         )
 127
 128         self.value = value
 129         self.constants = constants
 130         self.doc = _message_to_javadoc(definition)
 131         self.java_name_lower = _underscore_to_camelcase_lower(name)
 132         self.vpp_name = "%s%s%s" % (_VPP_TYPE_PREFIX, name, _VPP_TYPE_SUFFIX)
 133         # Fully qualified class name used by FindClass function, see:
 134         # https://docs.oracle.com/javase/8/docs/technotes/guides/jni/spec/functions.html#FindClass
 135         self.jni_name = "io/fd/vpp/jvpp/%s/types/%s" % (plugin_name, _java_name)
 136
 137     def get_host_to_net_function(self, host_ref_name, net_ref_name):
 138         return "_host_to_net_%s(env, %s, &(%s))" % (self.name, host_ref_name, net_ref_name)
 139
 140
 141 class Class(Type):
 142     def __init__(self, name, crc, fields, definition, plugin_name):
 143         _java_name = _underscore_to_camelcase_upper(name)
 144
 145         super(Class, self).__init__(
 146             name=name,
 147             java_name=_java_name,
 148             java_name_fqn="io.fd.vpp.jvpp.%s.types.%s" % (plugin_name, _java_name),
 149             jni_signature="Lio/fd/vpp/jvpp/%s/types/%s;" % (plugin_name, _java_name),
 150             jni_type="jobject",
 151             jni_accessor="Object",
 152             host_to_net_function="_host_to_net_%s" % name,
 153             net_to_host_function="_net_to_host_%s" % name
 154         )
 155
 156         self.crc = crc
 157         self.fields = fields
 158         self.doc = _message_to_javadoc(definition)
 159         self.java_name_lower = _underscore_to_camelcase_lower(name)
 160         self.vpp_name = "%s%s%s" % (_VPP_TYPE_PREFIX, name, _VPP_TYPE_SUFFIX)
 161         # Fully qualified class name used by FindClass function, see:
 162         # https://docs.oracle.com/javase/8/docs/technotes/guides/jni/spec/functions.html#FindClass
 163         self.jni_name = "io/fd/vpp/jvpp/%s/types/%s" % (plugin_name, _java_name)
 164
 165     def get_host_to_net_function(self, host_ref_name, net_ref_name):
 166         return "_host_to_net_%s(env, %s, &(%s))" % (self.name, host_ref_name, net_ref_name)
 167
 168
 169 class Field(object):
 170     def __init__(self, name, field_type, array_len=None, array_len_field=None):
 171         self.name = name
 172         self.java_name = _underscore_to_camelcase_lower(name)
 173         self.type = field_type
 174         self.array_len = array_len
 175         self.array_len_field = array_len_field
 176
 177     def __str__(self):
 178         return "Field{name:%s, java_name:%s, type:%s}" % (self.name, self.java_name, self.type)
 179
 180
 181 class Message(object):
 182     def __init__(self, name, crc, fields, definition):
 183         self.name = name
 184         self.java_name_upper = _underscore_to_camelcase_upper(name)
 185         self.java_name_lower = _underscore_to_camelcase_lower(name)
 186         self.crc = crc[2:]
 187         self.fields = fields
 188         self.has_fields = fields != []
 189         self.doc = _message_to_javadoc(definition)
 190
 191     def __str__(self):
 192         return "Message{name:%s, java_name:%s, crc:%s, fields:%s}" % (
 193             self.name, self.java_name_upper, self.crc, self.fields)
 194
 195
 196 class Event(Message):
 197     def __init__(self, name, crc, fields, definition):
 198         super(Event, self).__init__(name, crc, fields, definition)
 199
 200
 201 class Request(Message):
 202     def __init__(self, name, reply, crc, fields, definition):
 203         super(Request, self).__init__(name, crc, fields, definition)
 204         self.reply = reply
 205         self.reply_java = _underscore_to_camelcase_upper(reply)
 206
 207     def __str__(self):
 208         return "Request{name:%s, reply:%s, crc:%s, fields:%s}" % (self.name, self.reply, self.crc, self.fields)
 209
 210
 211 class Reply(Message):
 212     def __init__(self, name, request, crc, fields, definition):
 213         super(Reply, self).__init__(name, crc, fields, definition)
 214         self.request = request
 215         self.request_java = _underscore_to_camelcase_upper(request)
 216
 217     def __str__(self):
 218         return "Reply{name:%s, request:%s, crc:%s, fields:%s}" % (self.name, self.request, self.crc, self.fields)
 219
 220
 221 class Dump(Message):
 222     def __init__(self, name, details, crc, fields, definition):
 223         super(Dump, self).__init__(name, crc, fields, definition)
 224         self.details = details
 225         self.reply_java = _underscore_to_camelcase_upper(details)
 226
 227     def __str__(self):
 228         return "Dump{name:%s, details:%s, crc:%s, fields:%s}" % (self.name, self.details, self.crc, self.fields)
 229
 230
 231 class Details(Message):
 232     def __init__(self, name, dump, crc, fields, definition):
 233         super(Details, self).__init__(name, crc, fields, definition)
 234         self.dump = dump
 235         self.request_java = _underscore_to_camelcase_upper(dump)
 236
 237     def __str__(self):
 238         return "Details{name:%s, dump:%s, crc:%s, fields:%s}" % (self.name, self.dump, self.crc, self.fields)
 239
 240
 241 def is_retval(field):
 242     return field.name == u'retval'
 243
 244
 245 def is_array(field):
 246     return field.array_len is not None
 247
 248
 249 def is_request(msg):
 250     return hasattr(msg, 'reply')
 251
 252
 253 def is_reply(msg):
 254     return hasattr(msg, 'request')
 255
 256
 257 def is_dump(msg):
 258     return hasattr(msg, 'details')
 259
 260
 261 def is_details(msg):
 262     return hasattr(msg, 'dump')
 263
 264
 265 def is_event(msg):
 266     return isinstance(msg, Event)
 267
 268
 269 def is_control_ping(msg):
 270     return msg.name == u'control_ping'
 271
 272
 273 def is_control_ping_reply(msg):
 274     return msg.name == u'control_ping_reply'
 275
 276
 277 class JVppModel(object):
 278     def __init__(self, logger, json_api_files, plugin_name):
 279         self.logger = logger
 280         # TODO(VPP-1188): provide json_file_by_definition map to improve javadoc
 281         self.json_api_files = json_api_files
 282         self.plugin_package = BASE_PACKAGE + "." + plugin_name
 283         self.plugin_name = plugin_name
 284         self.plugin_java_name = _underscore_to_camelcase_upper(plugin_name)
 285         self._load_json_files(json_api_files)
 286         self._parse_simple_types()
 287         self._parse_enums()
 288         self._parse_types()
 289         self._parse_services()
 290         self._parse_messages()
 291         self._validate_messages()
 292
 293     def _load_json_files(self, json_api_files):
 294         self._enums = []
 295         self._types = []
 296         self._messages = []
 297         self._services = {}
 298         for file_name in json_api_files:
 299             with open(file_name) as f:
 300                 j = json.load(f)
 301                 self._enums.extend(j['enums'])
 302                 self._types.extend(j['types'])
 303                 self._messages.extend(j['messages'])
 304                 self._services.update(j['services'])
 305
 306     def _parse_simple_types(self):
 307         # Mapping according to:
 308         # http://docs.oracle.com/javase/7/do+'[]'cs/technotes/guides/jni/spec/types.html
 309         # and
 310         # https://docs.oracle.com/javase/8/docs/technotes/guides/jni/spec/functions.html#Get_type_Field_routines
 311         #
 312         # Unsigned types are converted to signed java types that have the same size.
 313         # It is the API user responsibility to interpret them correctly.
 314
 315         self._types_by_name = OrderedDict({
 316             'u8': SimpleType('u8', 'byte', 'B', 'jbyte', 'Byte'),
 317             'i8': SimpleType('i8', 'byte', 'B', 'jbyte', 'Byte'),
 318             'u16': SimpleType('u16', 'short', 'S', 'jshort', 'Short',
 319                               host_to_net_function='clib_host_to_net_u16',
 320                               net_to_host_function='clib_net_to_host_u16'),
 321             'i16': SimpleType('i16', 'short', 'S', 'jshort', 'Short',
 322                               host_to_net_function='clib_host_to_net_i16',
 323                               net_to_host_function='clib_net_to_host_i16'),
 324             'u32': SimpleType('u32', 'int', 'I', 'jint', 'Int',
 325                               host_to_net_function='clib_host_to_net_u32',
 326                               net_to_host_function='clib_net_to_host_u32'),
 327             'i32': SimpleType('i32', 'int', 'I', 'jint', 'Int',
 328                               host_to_net_function='clib_host_to_net_i32',
 329                               net_to_host_function='clib_net_to_host_i32'),
 330             'u64': SimpleType('u64', 'long', 'J', 'jlong', 'Long',
 331                               host_to_net_function='clib_host_to_net_u64',
 332                               net_to_host_function='clib_net_to_host_u64'),
 333             'i64': SimpleType('i64', 'long', 'J', 'jlong', 'Long',
 334                               host_to_net_function='clib_host_to_net_i64',
 335                               net_to_host_function='clib_net_to_host_i64'),
 336             'f64': SimpleType('f64', 'double', 'D', 'jdouble', 'Double')
 337         })
 338
 339         for n, t in self._types_by_name.items():
 340             self._types_by_name[n + _ARRAY_SUFFIX] = Array(t)
 341
 342     def _parse_enums(self):
 343         for json_type in self._enums:
 344             name = json_type[0]
 345             definition = json_type[1:]
 346             _type = self._parse_enum(name, definition)
 347             self._types_by_name[name] = _type
 348             self._types_by_name[name + _ARRAY_SUFFIX] = Array(_type)
 349
 350     def _parse_enum(self, name, definition):
 351         self.logger.debug("Parsing enum %s: %s", name, definition)
 352         constants = []
 353         type_name = None
 354         for item in definition:
 355             if type(item) is dict and 'enumtype' in item:
 356                 type_name = item['enumtype']
 357                 continue
 358             constants.append({'name': item[0], 'value': item[1]})
 359         if not type_name:
 360             raise ParseException("'enumtype' was not defined for %s" % definition)
 361         return Enum(name, Field('value', self._types_by_name[type_name]), constants, definition, self.plugin_name)
 362
 363     def _parse_types(self):
 364         for json_type in self._types:
 365             try:
 366                 name = json_type[0]
 367                 definition = json_type[1:]
 368                 _type = self._parse_type(name, definition)
 369                 self._types_by_name[name] = _type
 370                 self._types_by_name[name + _ARRAY_SUFFIX] = Array(_type)
 371             except ParseException as e:
 372                 self.logger.warning("Failed to parse %s type: %s. Skipping type definition.", name, e)
 373
 374         self.types = self._types_by_name.values()
 375
 376     def _parse_type(self, name, definition):
 377         self.logger.debug("Parsing type %s: %s", name, definition)
 378         crc, fields = self._parse_fields(definition)
 379         return Class(name, crc, fields, definition, self.plugin_name)
 380
 381     def _parse_services(self):
 382         self._dumps_by_details = {}
 383         self._requests_by_reply = {}
 384         for name, service in self._services.iteritems():
 385             if _is_stream(service):
 386                 self._dumps_by_details[service['reply']] = name
 387             else:
 388                 self._requests_by_reply[service['reply']] = name
 389
 390     def _parse_messages(self):
 391         # Preserve ordering from JSON file to make debugging easier.
 392         self._messages_by_name = OrderedDict()
 393         for msg in self._messages:
 394             try:
 395                 name = msg[0]
 396                 definition = msg[1:]
 397                 self._messages_by_name[name] = self._parse_message(name, definition)
 398             except ParseException as e:
 399                 self.logger.warning("Failed to parse message %s: %s. Skipping message.", name, e)
 400
 401     def _parse_message(self, name, definition):
 402         self.logger.debug("Parsing message %s: %s", name, definition)
 403         crc, fields = self._parse_fields(definition)
 404         if name in self._services:
 405             service = self._services[name]
 406             reply = service['reply']
 407             if _is_stream(service):
 408                 return Dump(name, reply, crc, filter(_is_request_field, fields), definition)
 409             if reply:
 410                 return Request(name, reply, crc, filter(_is_request_field, fields), definition)
 411             else:
 412                 return Event(name, crc, filter(_is_request_field, fields), definition)
 413         elif name in self._requests_by_reply:
 414             return Reply(name, self._requests_by_reply[name], crc, filter(_is_reply_field, fields), definition)
 415         elif name in self._dumps_by_details:
 416             return Details(name, self._dumps_by_details[name], crc, filter(_is_reply_field, fields), definition)
 417         else:
 418             # TODO: some messages like combined_counters are not visible in the services.
 419             # Throw exception instead (requires fixing vppagigen).
 420             return Event(name, crc, filter(_is_request_field, fields), definition)
 421
 422     def _parse_fields(self, definition):
 423         crc = None
 424         fields = []
 425         for item in definition:
 426             if type(item) == dict and 'crc' in item:
 427                 crc = item['crc']
 428             else:
 429                 fields.append(self._parse_field(item, fields))
 430         if not crc:
 431             raise ParseException("CRC was not defined for %s" % definition)
 432         return crc, fields
 433
 434     def _parse_field(self, field, fields):
 435         type_name = _extract_type_name(field[0])
 436         if type_name in self._types_by_name:
 437             if len(field) > 2:
 438                 # Array field
 439                 array_len_field = None
 440                 if len(field) == 4:
 441                     for f in fields:
 442                         if f.name == field[3]:
 443                             array_len_field = f
 444                     if not array_len_field:
 445                         raise ParseException("Could not find field %s declared as length of array %s",
 446                                              field[3], field[1])
 447                 return Field(field[1], self._types_by_name[type_name + _ARRAY_SUFFIX], field[2], array_len_field)
 448             else:
 449                 return Field(field[1], self._types_by_name[type_name])
 450         else:
 451             raise ParseException("Unknown field type %s" % field)
 452
 453     def _validate_messages(self):
 454         """
 455         In case if message A is known to be reply for message B, and message B was not correctly parsed,
 456         remove message A from the set of all messages.
 457         """
 458         to_be_removed = []
 459         messages = self._messages_by_name
 460         for name, msg in messages.iteritems():
 461             if (is_request(msg) and msg.reply not in messages) \
 462                     or (is_reply(msg) and msg.request not in messages) \
 463                     or (is_dump(msg) and msg.details not in messages) \
 464                     or (is_details(msg) and msg.dump not in messages):
 465                 to_be_removed.append(name)
 466
 467         for name in to_be_removed:
 468             del messages[name]
 469
 470         self.messages = self._messages_by_name.values()
 471
 472 _ARRAY_SUFFIX = '[]'
 473
 474
 475 def _underscore_to_camelcase_upper(name):
 476     return name.title().replace("_", "")
 477
 478
 479 def _underscore_to_camelcase_lower(name):
 480     name = name.title().replace("_", "")
 481     return name[0].lower() + name[1:]
 482
 483
 484 def _message_to_javadoc(message_definition):
 485     """ Converts JSON message definition to javadoc """
 486     formatted_message = pprint.pformat(message_definition, indent=4, width=120, depth=None)
 487     return " * " + formatted_message.replace("\n", "\n * ")
 488
 489
 490 def _is_stream(service):
 491     """
 492     Checks if service represents stream, e.g.:
 493     "ip_address_dump": {
 494         "reply": "ip_address_details",
 495         "stream": true
 496     }
 497     :param service: JSON definition of service
 498     :return: value assigned to "stream" or None
 499     """
 500     return "stream" in service
 501
 502
 503 def _extract_type_name(name):
 504     if name.startswith(_VPP_TYPE_PREFIX) and name.endswith(_VPP_TYPE_SUFFIX):
 505         return name[len(_VPP_TYPE_PREFIX): - len(_VPP_TYPE_SUFFIX)]
 506     return name
 507
 508 _VPP_TYPE_PREFIX = "vl_api_"
 509
 510 _VPP_TYPE_SUFFIX = "_t"
 511
 512
 513 def _is_request_field(field):
 514     # Skip fields that are hidden to the jvpp user (handled by JNI layer)
 515     return field.name not in {'_vl_msg_id', 'client_index', 'context'}
 516
 517
 518 def _is_reply_field(field):
 519     # Skip fields that are hidden to the jvpp user:
 520     # _vl_msg_id is handled at JNI layer,
 521     # Unlike in the request case, context is visible to allow matching replies with requests at Java layer.
 522     return field.name not in {'_vl_msg_id'}