src/vpp-api/python/vpp_papi/vpp_serializer.py

   1 #
   2 # Copyright (c) 2018 Cisco and/or its affiliates.
   3 # Licensed under the Apache License, Version 2.0 (the "License");
   4 # you may not use this file except in compliance with the License.
   5 # You may obtain a copy of the License at:
   6 #
   7 #     http://www.apache.org/licenses/LICENSE-2.0
   8 #
   9 # Unless required by applicable law or agreed to in writing, software
  10 # distributed under the License is distributed on an "AS IS" BASIS,
  11 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  12 # See the License for the specific language governing permissions and
  13 # limitations under the License.
  14 #
  15 import collections
  16 import logging
  17 import socket
  18 import struct
  19 import sys
  20
  21 if sys.version_info <= (3, 4):
  22     from aenum import IntEnum  # noqa: F401
  23 else:
  24     from enum import IntEnum  # noqa: F401
  25
  26 if sys.version_info <= (3, 6):
  27     from aenum import IntFlag  # noqa: F401
  28 else:
  29
  30     from enum import IntFlag  # noqa: F401
  31
  32 from . import vpp_format  # noqa: E402
  33
  34 #
  35 # Set log-level in application by doing e.g.:
  36 # logger = logging.getLogger('vpp_serializer')
  37 # logger.setLevel(logging.DEBUG)
  38 #
  39 logger = logging.getLogger(__name__)
  40
  41 if sys.version[0] == '2':
  42     def check(d): type(d) is dict
  43 else:
  44     def check(d): type(d) is dict or type(d) is bytes
  45
  46
  47 def conversion_required(data, field_type):
  48     if check(data):
  49         return False
  50     try:
  51         if type(data).__name__ in vpp_format.conversion_table[field_type]:
  52             return True
  53     except KeyError:
  54         return False
  55
  56
  57 def conversion_packer(data, field_type):
  58     t = type(data).__name__
  59     return types[field_type].pack(vpp_format.
  60                                   conversion_table[field_type][t](data))
  61
  62
  63 def conversion_unpacker(data, field_type):
  64     if field_type not in vpp_format.conversion_unpacker_table:
  65         return data
  66     return vpp_format.conversion_unpacker_table[field_type](data)
  67
  68
  69 # TODO: post 20.01, remove inherit from object.
  70 class Packer(object):
  71     options = {}
  72
  73     def pack(self, data, kwargs):
  74         raise NotImplementedError
  75
  76     def unpack(self, data, offset, result=None, ntc=False):
  77         raise NotImplementedError
  78
  79     # override as appropriate in subclasses
  80     def _get_packer_with_options(self, f_type, options):
  81         return types[f_type]
  82
  83     def get_packer_with_options(self, f_type, options):
  84         if options is not None:
  85             try:
  86                 return self._get_packer_with_options(f_type, options)
  87             except IndexError:
  88                 raise VPPSerializerValueError(
  89                     "Options not supported for {}{} ({})".
  90                         format(f_type, types[f_type].__class__,
  91                                options))
  92
  93
  94 class BaseTypes(Packer):
  95     def __init__(self, type, elements=0, options=None):
  96         self._type = type
  97         self._elements = elements
  98         base_types = {'u8': '>B',
  99                       'i8': '>b',
 100                       'string': '>s',
 101                       'u16': '>H',
 102                       'i16': '>h',
 103                       'u32': '>I',
 104                       'i32': '>i',
 105                       'u64': '>Q',
 106                       'i64': '>q',
 107                       'f64': '=d',
 108                       'bool': '>?',
 109                       'header': '>HI'}
 110
 111         if elements > 0 and (type == 'u8' or type == 'string'):
 112             self.packer = struct.Struct('>%ss' % elements)
 113         else:
 114             self.packer = struct.Struct(base_types[type])
 115         self.size = self.packer.size
 116         self.options = options
 117
 118     def pack(self, data, kwargs=None):
 119         if data is None:  # Default to zero if not specified
 120             if self.options and 'default' in self.options:
 121                 data = self.options['default']
 122             else:
 123                 data = 0
 124         return self.packer.pack(data)
 125
 126     def unpack(self, data, offset, result=None, ntc=False):
 127         return self.packer.unpack_from(data, offset)[0], self.packer.size
 128
 129     def _get_packer_with_options(self, f_type, options):
 130         c = types[f_type].__class__
 131         return c(f_type, options=options)
 132
 133     def __repr__(self):
 134         return "BaseTypes(type=%s, elements=%s, options=%s)" % (self._type,
 135                                                                 self._elements,
 136                                                                 self.options)
 137
 138
 139 class String(Packer):
 140     def __init__(self, name, num, options):
 141         self.name = name
 142         self.num = num
 143         self.size = 1
 144         self.length_field_packer = BaseTypes('u32')
 145         self.limit = options['limit'] if 'limit' in options else num
 146         self.fixed = True if num else False
 147         if self.fixed and not self.limit:
 148             raise VPPSerializerValueError(
 149                 "Invalid argument length for: {}, {} maximum {}".
 150                 format(list, len(list), self.limit))
 151
 152     def pack(self, list, kwargs=None):
 153         if not list:
 154             if self.fixed:
 155                 return b"\x00" * self.limit
 156             return self.length_field_packer.pack(0) + b""
 157         if self.limit and len(list) > self.limit - 1:
 158             raise VPPSerializerValueError(
 159                 "Invalid argument length for: {}, {} maximum {}".
 160                 format(list, len(list), self.limit - 1))
 161         if self.fixed:
 162             return list.encode('ascii').ljust(self.limit, b'\x00')
 163         return self.length_field_packer.pack(len(list)) + list.encode('ascii')
 164
 165     def unpack(self, data, offset=0, result=None, ntc=False):
 166         if self.fixed:
 167             p = BaseTypes('u8', self.num)
 168             s = p.unpack(data, offset)
 169             s2 = s[0].split(b'\0', 1)[0]
 170             return (s2.decode('ascii'), self.num)
 171
 172         length, length_field_size = self.length_field_packer.unpack(data,
 173                                                                     offset)
 174         if length == 0:
 175             return '', 0
 176         p = BaseTypes('u8', length)
 177         x, size = p.unpack(data, offset + length_field_size)
 178         #x2 = x.split(b'\0', 1)[0]
 179         return (x.decode('ascii', errors='replace'), size + length_field_size)
 180
 181
 182 types = {'u8': BaseTypes('u8'), 'i8': BaseTypes('i8'),
 183          'u16': BaseTypes('u16'), 'i16': BaseTypes('i16'),
 184          'u32': BaseTypes('u32'), 'i32': BaseTypes('i32'),
 185          'u64': BaseTypes('u64'), 'i64': BaseTypes('i64'),
 186          'f64': BaseTypes('f64'),
 187          'bool': BaseTypes('bool'), 'string': String}
 188
 189 class_types = {}
 190
 191
 192 def vpp_get_type(name):
 193     try:
 194         return types[name]
 195     except KeyError:
 196         return None
 197
 198
 199 class VPPSerializerValueError(ValueError):
 200     pass
 201
 202
 203 class FixedList_u8(Packer):
 204     def __init__(self, name, field_type, num):
 205         self.name = name
 206         self.num = num
 207         self.packer = BaseTypes(field_type, num)
 208         self.size = self.packer.size
 209         self.field_type = field_type
 210
 211     def pack(self, data, kwargs=None):
 212         """Packs a fixed length bytestring. Left-pads with zeros
 213         if input data is too short."""
 214         if not data:
 215             return b'\x00' * self.size
 216
 217         if len(data) > self.num:
 218             raise VPPSerializerValueError(
 219                 'Fixed list length error for "{}", got: {}'
 220                 ' expected: {}'
 221                 .format(self.name, len(data), self.num))
 222
 223         try:
 224             return self.packer.pack(data)
 225         except struct.error:
 226             raise VPPSerializerValueError(
 227                 'Packing failed for "{}" {}'
 228                 .format(self.name, kwargs))
 229
 230     def unpack(self, data, offset=0, result=None, ntc=False):
 231         if len(data[offset:]) < self.num:
 232             raise VPPSerializerValueError(
 233                 'Invalid array length for "{}" got {}'
 234                 ' expected {}'
 235                 .format(self.name, len(data[offset:]), self.num))
 236         return self.packer.unpack(data, offset)
 237
 238     def __repr__(self):
 239         return "FixedList_u8(name=%s, field_type=%s, num=%s)" % (
 240             self.name, self.field_type, self.num
 241         )
 242
 243
 244 class FixedList(Packer):
 245     def __init__(self, name, field_type, num):
 246         self.num = num
 247         self.packer = types[field_type]
 248         self.size = self.packer.size * num
 249         self.name = name
 250         self.field_type = field_type
 251
 252     def pack(self, list, kwargs):
 253         if len(list) != self.num:
 254             raise VPPSerializerValueError(
 255                 'Fixed list length error, got: {} expected: {}'
 256                 .format(len(list), self.num))
 257         b = bytes()
 258         for e in list:
 259             b += self.packer.pack(e)
 260         return b
 261
 262     def unpack(self, data, offset=0, result=None, ntc=False):
 263         # Return a list of arguments
 264         result = []
 265         total = 0
 266         for e in range(self.num):
 267             x, size = self.packer.unpack(data, offset, ntc=ntc)
 268             result.append(x)
 269             offset += size
 270             total += size
 271         return result, total
 272
 273     def __repr__(self):
 274         return "FixedList_(name=%s, field_type=%s, num=%s)" % (
 275             self.name, self.field_type, self.num )
 276
 277
 278 class VLAList(Packer):
 279     def __init__(self, name, field_type, len_field_name, index):
 280         self.name = name
 281         self.field_type = field_type
 282         self.index = index
 283         self.packer = types[field_type]
 284         self.size = self.packer.size
 285         self.length_field = len_field_name
 286
 287     def pack(self, lst, kwargs=None):
 288         if not lst:
 289             return b""
 290         if len(lst) != kwargs[self.length_field]:
 291             raise VPPSerializerValueError(
 292                 'Variable length error, got: {} expected: {}'
 293                 .format(len(lst), kwargs[self.length_field]))
 294
 295         # u8 array
 296         if self.packer.size == 1:
 297             if isinstance(lst, list):
 298                 return b''.join(lst)
 299             return bytes(lst)
 300
 301         b = bytes()
 302         for e in lst:
 303             b += self.packer.pack(e)
 304         return b
 305
 306     def unpack(self, data, offset=0, result=None, ntc=False):
 307         # Return a list of arguments
 308         total = 0
 309
 310         # u8 array
 311         if self.packer.size == 1:
 312             if result[self.index] == 0:
 313                 return b'', 0
 314             p = BaseTypes('u8', result[self.index])
 315             return p.unpack(data, offset, ntc=ntc)
 316
 317         r = []
 318         for e in range(result[self.index]):
 319             x, size = self.packer.unpack(data, offset, ntc=ntc)
 320             r.append(x)
 321             offset += size
 322             total += size
 323         return r, total
 324
 325     def __repr__(self):
 326         return "VLAList(name=%s, field_type=%s, " \
 327                "len_field_name=%s, index=%s)" % (
 328             self.name, self.field_type, self.length_field, self.index
 329         )
 330
 331
 332 class VLAList_legacy(Packer):
 333     def __init__(self, name, field_type):
 334         self.name = name
 335         self.field_type = field_type
 336         self.packer = types[field_type]
 337         self.size = self.packer.size
 338
 339     def pack(self, list, kwargs=None):
 340         if self.packer.size == 1:
 341             return bytes(list)
 342
 343         b = bytes()
 344         for e in list:
 345             b += self.packer.pack(e)
 346         return b
 347
 348     def unpack(self, data, offset=0, result=None, ntc=False):
 349         total = 0
 350         # Return a list of arguments
 351         if (len(data) - offset) % self.packer.size:
 352             raise VPPSerializerValueError(
 353                 'Legacy Variable Length Array length mismatch.')
 354         elements = int((len(data) - offset) / self.packer.size)
 355         r = []
 356         for e in range(elements):
 357             x, size = self.packer.unpack(data, offset, ntc=ntc)
 358             r.append(x)
 359             offset += self.packer.size
 360             total += size
 361         return r, total
 362
 363     def __repr__(self):
 364         return "VLAList_legacy(name=%s, field_type=%s)" % (
 365             self.name, self.field_type
 366         )
 367
 368
 369 class VPPEnumType(Packer):
 370     def __init__(self, name, msgdef, options=None):
 371         self.size = types['u32'].size
 372         self.name = name
 373         self.enumtype = 'u32'
 374         self.msgdef = msgdef
 375         e_hash = {}
 376         for f in msgdef:
 377             if type(f) is dict and 'enumtype' in f:
 378                 if f['enumtype'] != 'u32':
 379                     self.size = types[f['enumtype']].size
 380                     self.enumtype = f['enumtype']
 381                 continue
 382             ename, evalue = f
 383             e_hash[ename] = evalue
 384         self.enum = IntFlag(name, e_hash)
 385         types[name] = self
 386         class_types[name] = VPPEnumType
 387         self.options = options
 388
 389     def __getattr__(self, name):
 390         return self.enum[name]
 391
 392     def __bool__(self):
 393         return True
 394
 395     # TODO: Remove post 20.01.
 396     if sys.version[0] == '2':
 397         __nonzero__ = __bool__
 398
 399     def pack(self, data, kwargs=None):
 400         if data is None:  # Default to zero if not specified
 401             if self.options and 'default' in self.options:
 402                 data = self.options['default']
 403             else:
 404                 data = 0
 405
 406         return types[self.enumtype].pack(data)
 407
 408     def unpack(self, data, offset=0, result=None, ntc=False):
 409         x, size = types[self.enumtype].unpack(data, offset)
 410         return self.enum(x), size
 411
 412     def _get_packer_with_options(self, f_type, options):
 413         c = types[f_type].__class__
 414         return c(f_type, types[f_type].msgdef, options=options)
 415
 416     def __repr__(self):
 417         return "VPPEnumType(name=%s, msgdef=%s, options=%s)" % (
 418             self.name, self.msgdef, self.options
 419         )
 420
 421
 422 class VPPUnionType(Packer):
 423     def __init__(self, name, msgdef):
 424         self.name = name
 425         self.msgdef = msgdef
 426         self.size = 0
 427         self.maxindex = 0
 428         fields = []
 429         self.packers = collections.OrderedDict()
 430         for i, f in enumerate(msgdef):
 431             if type(f) is dict and 'crc' in f:
 432                 self.crc = f['crc']
 433                 continue
 434             f_type, f_name = f
 435             if f_type not in types:
 436                 logger.debug('Unknown union type {}'.format(f_type))
 437                 raise VPPSerializerValueError(
 438                     'Unknown message type {}'.format(f_type))
 439             fields.append(f_name)
 440             size = types[f_type].size
 441             self.packers[f_name] = types[f_type]
 442             if size > self.size:
 443                 self.size = size
 444                 self.maxindex = i
 445
 446         types[name] = self
 447         self.tuple = collections.namedtuple(name, fields, rename=True)
 448
 449     # Union of variable length?
 450     def pack(self, data, kwargs=None):
 451         if not data:
 452             return b'\x00' * self.size
 453
 454         for k, v in data.items():
 455             logger.debug("Key: {} Value: {}".format(k, v))
 456             b = self.packers[k].pack(v, kwargs)
 457             break
 458         r = bytearray(self.size)
 459         r[:len(b)] = b
 460         return r
 461
 462     def unpack(self, data, offset=0, result=None, ntc=False):
 463         r = []
 464         maxsize = 0
 465         for k, p in self.packers.items():
 466             x, size = p.unpack(data, offset, ntc=ntc)
 467             if size > maxsize:
 468                 maxsize = size
 469             r.append(x)
 470         return self.tuple._make(r), maxsize
 471
 472     def __repr__(self):
 473         return"VPPUnionType(name=%s, msgdef=%r)" % (self.name, self.msgdef)
 474
 475
 476 class VPPTypeAlias(Packer):
 477     def __init__(self, name, msgdef, options=None):
 478         self.name = name
 479         self.msgdef = msgdef
 480         t = vpp_get_type(msgdef['type'])
 481         if not t:
 482             raise ValueError('No such type: {}'.format(msgdef['type']))
 483         if 'length' in msgdef:
 484             if msgdef['length'] == 0:
 485                 raise ValueError()
 486             if msgdef['type'] == 'u8':
 487                 self.packer = FixedList_u8(name, msgdef['type'],
 488                                            msgdef['length'])
 489                 self.size = self.packer.size
 490             else:
 491                 self.packer = FixedList(name, msgdef['type'], msgdef['length'])
 492         else:
 493             self.packer = t
 494             self.size = t.size
 495
 496         types[name] = self
 497         self.toplevelconversion = False
 498         self.options = options
 499
 500     def pack(self, data, kwargs=None):
 501         if data and conversion_required(data, self.name):
 502             try:
 503                 return conversion_packer(data, self.name)
 504             # Python 2 and 3 raises different exceptions from inet_pton
 505             except(OSError, socket.error, TypeError):
 506                 pass
 507         if data is None:  # Default to zero if not specified
 508             if self.options and 'default' in self.options:
 509                 data = self.options['default']
 510             else:
 511                 data = 0
 512
 513         return self.packer.pack(data, kwargs)
 514
 515     def _get_packer_with_options(self, f_type, options):
 516         c = types[f_type].__class__
 517         return c(f_type, types[f_type].msgdef, options=options)
 518
 519     def unpack(self, data, offset=0, result=None, ntc=False):
 520         if ntc is False and self.name in vpp_format.conversion_unpacker_table:
 521             # Disable type conversion for dependent types
 522             ntc = True
 523             self.toplevelconversion = True
 524         t, size = self.packer.unpack(data, offset, result, ntc=ntc)
 525         if self.toplevelconversion:
 526             self.toplevelconversion = False
 527             return conversion_unpacker(t, self.name), size
 528         return t, size
 529
 530     def __repr__(self):
 531         return "VPPTypeAlias(name=%s, msgdef=%s, options=%s)" % (
 532             self.name, self.msgdef, self.options)
 533
 534
 535 class VPPType(Packer):
 536     # Set everything up to be able to pack / unpack
 537     def __init__(self, name, msgdef):
 538         self.name = name
 539         self.msgdef = msgdef
 540         self.packers = []
 541         self.fields = []
 542         self.fieldtypes = []
 543         self.field_by_name = {}
 544         size = 0
 545         for i, f in enumerate(msgdef):
 546             if type(f) is dict and 'crc' in f:
 547                 self.crc = f['crc']
 548                 continue
 549             f_type, f_name = f[:2]
 550             self.fields.append(f_name)
 551             self.field_by_name[f_name] = None
 552             self.fieldtypes.append(f_type)
 553             if f_type not in types:
 554                 logger.debug('Unknown type {}'.format(f_type))
 555                 raise VPPSerializerValueError(
 556                     'Unknown message type {}'.format(f_type))
 557
 558             fieldlen = len(f)
 559             options = [x for x in f if type(x) is dict]
 560             if len(options):
 561                 self.options = options[0]
 562                 fieldlen -= 1
 563             else:
 564                 self.options = {}
 565             if fieldlen == 3:  # list
 566                 list_elements = f[2]
 567                 if list_elements == 0:
 568                     if f_type == 'string':
 569                         p = String(f_name, 0, self.options)
 570                     else:
 571                         p = VLAList_legacy(f_name, f_type)
 572                     self.packers.append(p)
 573                 elif f_type == 'u8':
 574                     p = FixedList_u8(f_name, f_type, list_elements)
 575                     self.packers.append(p)
 576                     size += p.size
 577                 elif f_type == 'string':
 578                     p = String(f_name, list_elements, self.options)
 579                     self.packers.append(p)
 580                     size += p.size
 581                 else:
 582                     p = FixedList(f_name, f_type, list_elements)
 583                     self.packers.append(p)
 584                     size += p.size
 585             elif fieldlen == 4:  # Variable length list
 586                 length_index = self.fields.index(f[3])
 587                 p = VLAList(f_name, f_type, f[3], length_index)
 588                 self.packers.append(p)
 589             else:
 590                 # default support for types that decay to basetype
 591                 if 'default' in self.options:
 592                     p = self.get_packer_with_options(f_type, self.options)
 593                 else:
 594                     p = types[f_type]
 595
 596                 self.packers.append(p)
 597                 size += p.size
 598
 599         self.size = size
 600         self.tuple = collections.namedtuple(name, self.fields, rename=True)
 601         types[name] = self
 602         self.toplevelconversion = False
 603
 604     def pack(self, data, kwargs=None):
 605         if not kwargs:
 606             kwargs = data
 607         b = bytes()
 608
 609         # Try one of the format functions
 610         if data and conversion_required(data, self.name):
 611             return conversion_packer(data, self.name)
 612
 613         for i, a in enumerate(self.fields):
 614             if data and type(data) is not dict and a not in data:
 615                 raise VPPSerializerValueError(
 616                     "Invalid argument: {} expected {}.{}".
 617                     format(data, self.name, a))
 618
 619             # Defaulting to zero.
 620             if not data or a not in data:  # Default to 0
 621                 arg = None
 622                 kwarg = None  # No default for VLA
 623             else:
 624                 arg = data[a]
 625                 kwarg = kwargs[a] if a in kwargs else None
 626             if isinstance(self.packers[i], VPPType):
 627                 b += self.packers[i].pack(arg, kwarg)
 628             else:
 629                 b += self.packers[i].pack(arg, kwargs)
 630
 631         return b
 632
 633     def unpack(self, data, offset=0, result=None, ntc=False):
 634         # Return a list of arguments
 635         result = []
 636         total = 0
 637         if ntc is False and self.name in vpp_format.conversion_unpacker_table:
 638             # Disable type conversion for dependent types
 639             ntc = True
 640             self.toplevelconversion = True
 641
 642         for p in self.packers:
 643             x, size = p.unpack(data, offset, result, ntc)
 644             if type(x) is tuple and len(x) == 1:
 645                 x = x[0]
 646             result.append(x)
 647             offset += size
 648             total += size
 649         t = self.tuple._make(result)
 650
 651         if self.toplevelconversion:
 652             self.toplevelconversion = False
 653             t = conversion_unpacker(t, self.name)
 654         return t, total
 655
 656     def __repr__(self):
 657         return "%s(name=%s, msgdef=%s)" % (
 658             self.__class__.__name__, self.name, self.msgdef
 659         )
 660
 661
 662 class VPPMessage(VPPType):
 663     pass