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