ynl 0.2.4 → 0.4.1

data/lib/ynl/models.rb

@@ -1,12 +1,14 @@
 module Ynl
   module Models
-    Family = ::Struct.new(:name, :protocol, :protonum, :doc,
+    Family = ::Struct.new(:name, :protocol, :version, :protonum, :doc,
       :consts, :enums, :flags, :structs,
       :attribute_sets, :sub_messages, :operations, :mcast_groups)
     class Family
       def resolve
         structs.transform_values! {|s| s.resolve(self) }
+        sub_messages.transform_values! {|s| s.resolve(self) }
         attribute_sets.transform_values! {|s| s.resolve(self) }
+        operations.transform_values! {|operation| operation.resolve(self) }
         self
       end
 
@@ -28,9 +30,16 @@ module Ynl
     end
 
     Const = ::Struct.new(:name, :value, :doc)
+    Check = ::Struct.new(:operation, :value)
 
     class SubMessage
-      Format = ::Struct.new(:value, :attribute_set)
+      Format = ::Struct.new(:value, :fixed_header, :attribute_set) do
+        def resolve(f)
+          self.fixed_header = fixed_header.resolve(f) if fixed_header.is_a?(Thunk)
+          self.attribute_set = attribute_set.resolve(f) if attribute_set.is_a?(Thunk)
+          self
+        end
+      end
 
       attr_reader :name, :formats
 
@@ -40,6 +49,7 @@ module Ynl
       end
 
       def resolve(f)
+        formats.map! { it.resolve(f) }
         self
       end
     end
@@ -99,11 +109,16 @@ module Ynl
     end
 
     class AttributeSet
-      Attribute = ::Struct.new(:name, :type, :value, :checks, :doc) do
+      Attribute = ::Struct.new(:name, :type, :value, :checks, :doc, :multi_attr, :enum, :enum_as_flags) do
         def resolve(f)
           self.type = type.resolve(f)
+          self.enum = enum.resolve(f) if enum
           self
         end
+
+        def multi?
+          multi_attr
+        end
       end
 
       attr_reader :name, :name_prefix, :attributes, :doc
@@ -134,36 +149,58 @@ module Ynl
       end
 
       def attributes
-        # WORKAROUND: Some upstream specs (e.g. devlink) contain duplicate attribute
-        # entries in subset-of attribute sets. Deduplicate by name here until the
-        # upstream specs are fixed.
-        @attributes.uniq {|attr| attr.fetch('name') }.map do |attr|
-          name = attr.fetch('name')
-          superset.attributes.find { it.name == name } or raise ParseError "No attribute with name #{name}"
-        end
+        @attributes
       end
 
       def resolve(f)
+        attributes.map! { it.resolve(f) }
         self
+      rescue
+        raise ParseError, "Failed to resolve attribute subset: #{name}"
       end
     end
 
+    McastGroup = ::Struct.new(:name, :value, :doc)
+
     class Operation
-      attr_reader :name, :doc, :fixed_header, :attribute_set, :doit, :dumpit
+      attr_reader :name, :doc, :flags, :fixed_header, :attribute_set, :doit, :dumpit, :notification
 
-      def initialize(name:, doc:, fixed_header:, attribute_set:, doit:, dumpit:)
+      def initialize(name:, doc:, flags:, fixed_header:, attribute_set:, doit:, dumpit:, notification:)
         @name = name
         @doc = doc
+        @flags = flags
         @fixed_header = fixed_header
         @attribute_set = attribute_set
         @doit = doit
         @dumpit = dumpit
+        @notification = notification
       end
 
       def resolve(f)
         @doit = @doit&.resolve(f)
         @dumpit = @dumpit&.resolve(f)
+        @notification = @notification&.resolve(f)
+        self
+      end
+    end
+
+    class Notification
+      attr_reader :kind, :message, :source, :group
+
+      def initialize(kind:, message:, source:, group:)
+        @kind = kind
+        @message = message
+        @source = source
+        @group = group
+      end
+
+      def resolve(f)
+        @message = @message.resolve(f)
+        @source = f.operations.fetch(@source) if @source
+        @group = f.mcast_groups.fetch(@group) if @group
         self
+      rescue KeyError => error
+        raise ParseError, "Failed to resolve #{kind} notification: #{error.message}"
       end
     end
 

data/lib/ynl/parser.rb

@@ -4,6 +4,8 @@ require_relative 'models'
 
 module Ynl
   class Parser
+    # @param [String, #read] source
+    # @rbs (String | _Readable source) -> void
     def initialize(source)
       @yaml = YAML.load(source, aliases: true)
 
@@ -13,17 +15,24 @@ module Ynl
       @structs = {}
 
       @attribute_sets = {}
+      @attribute_definitions = {}
       @sub_messages = {}
       @operations = {}
       @mcast_groups = {}
     end
 
+    # @param [String, #to_path] path
+    # @return [Models::Family]
+    # @rbs (String | _PathLike path) -> Models::Family
     def self.parse_file(path)
       File.open(path) {|f| new(f) }.parse
     end
 
+    # @return [Models::Family]
+    # @rbs () -> Models::Family
     def parse
       protocol = @yaml['protocol'] || 'genetlink'
+      version = @yaml.fetch('version', 1)
       protonum = @yaml['protonum']
       name = @yaml['name']
       doc = translate_doc(@yaml['doc'])
@@ -79,13 +88,14 @@ module Ynl
           end
         end
       end
-      @yaml['mcast-groups']&.each do |d|
+      @yaml.dig('mcast-groups', 'list')&.each do |d|
         parse_mcast_group(d)
       end
 
       Models::Family.new(
         name:,
         protocol:,
+        version:,
         protonum:,
         doc:,
         consts: @consts,
@@ -106,9 +116,11 @@ module Ynl
         @consts[v.name] = v
       when 'enum'
         v = parse_enum_flags(d, type: :enum)
+        reject_enum_flags_name_collision(v.name, @flags)
         @enums[v.name] = v
       when 'flags'
         v = parse_enum_flags(d, type: :flags)
+        reject_enum_flags_name_collision(v.name, @enums)
         @flags[v.name] = v
       when 'struct'
         v = parse_struct(d)
@@ -118,19 +130,33 @@ module Ynl
       end
     end
 
+    private def reject_enum_flags_name_collision(name, other_definitions)
+      return unless other_definitions.key?(name)
+
+      raise ParseError, "Definition #{name.inspect} cannot be both an enum and flags"
+    end
+
     private def parse_const(d)
       name = "#{d['name-prefix']}#{d.fetch('name')}"
-      Models::Const.new(name, d.fetch('value'), translate_doc(d['doc']))
+      value = d.fetch('value')
+      unless value.is_a?(Integer) || value.is_a?(String)
+        raise ParseError, "Constant value must be a string or an integer: #{name}"
+      end
+
+      Models::Const.new(name, value, translate_doc(d['doc']))
     end
 
     private def parse_enum_flags(d, type:)
       cls = type == :enum ? Models::Enum : Models::Flags
       result = cls.new(name: d.fetch('name'), doc: translate_doc(d['doc']))
 
-      start_value = d['start-value'] || 0
-      value = type == :enum ? start_value : 1 << start_value
+      start_value = d['value-start'] || 0
+      raw_value = start_value
 
       d.fetch('entries').each do |v|
+        explicit_value = v.is_a?(Hash) ? v['value'] : nil
+        raw_value = explicit_value unless explicit_value.nil?
+        value = type == :enum ? raw_value : 1 << raw_value
         case v
         when String
           entry = cls::Entry.new(name: v, value:)
@@ -142,7 +168,7 @@ module Ynl
 
         result.entries << entry
 
-        value = type == :enum ? value + 1 : value << 1
+        raw_value += 1
 
       rescue
         raise ParseError, "Failed to parse enum/flags entry: #{v.fetch('name')}"
@@ -164,6 +190,7 @@ module Ynl
       when 'binary'
         Types::Binary.new(
           struct: d['struct'] ? Models::Thunk.new {|f| f.structs.fetch(d['struct']) } : nil,
+          length: d['len'],
           display_hint: d['display-hint'],
         )
       when 'pad'
@@ -184,10 +211,15 @@ module Ynl
           byte_order: parse_byte_order(d['byte-order']),
         )
       when 'binary'
-        Types::Binary.new(
-          struct: d['struct'] ? Models::Thunk.new {|f| f.structs.fetch(d.fetch('struct')) } : nil,
-          display_hint: d['display-hint'],
-        )
+        if d.key?('sub-type')
+          Types::PackedArray.new(sub_type: parse_packed_array_sub_type(d))
+        else
+          Types::Binary.new(
+            struct: d['struct'] ? Models::Thunk.new {|f| f.structs.fetch(d.fetch('struct')) } : nil,
+            length: nil,
+            display_hint: d['display-hint'],
+          )
+        end
       when 'string'
         Types::String.new
       when 'nest'
@@ -200,11 +232,12 @@ module Ynl
         )
       when 'nest-type-value'
         if d['nested-attributes']
-          Types::NestedAttributes.new(
+          Types::NestTypeValue.new(
             attribute_set: Models::Thunk.new {|f| f.attribute_sets.fetch(d.fetch('nested-attributes')) },
+            type_values: d.fetch('type-value'),
           )
         else
-          Types::Binary.new(struct: nil, display_hint: nil)
+          Types::Binary.new(struct: nil, length: nil, display_hint: nil)
         end
       when 'sub-message'
         Types::SubMessage.new(
@@ -237,6 +270,7 @@ module Ynl
       when 'binary'
         Types::Binary.new(
           struct: nil,
+          length: nil,
           display_hint: d['display-hint'],
         )
       when 'nest'
@@ -248,13 +282,26 @@ module Ynl
       end
     end
 
+    private def parse_packed_array_sub_type(d)
+      sub_type = d.fetch('sub-type')
+      case sub_type
+      when 'u8', 'u16', 'u32', 'u64', 's8', 's16', 's32', 's64', 'int'
+        Types::Scalar.new(
+          type: sub_type,
+          byte_order: parse_byte_order(d['byte-order']),
+        )
+      else
+        raise ParseError, "Unknown packed-array sub-type: #{sub_type}"
+      end
+    end
+
     private def parse_byte_order(v)
       case v
       when nil
         :host
       when 'big-endian'
         :big
-      when 'litten-endian'
+      when 'little-endian'
         :little
       else
         raise ParseError, "Unknown endian: #{v}"
@@ -287,21 +334,8 @@ module Ynl
 
     private def parse_check(op, value_literal)
       case op
-      when 'max'
-        value = parse_value(value_literal)
-        return %{raise ArgumentError, "Value \#{it.inspect} is greater than maximum #{value}" unless it <= #{value}}
-      when 'min'
-        value = parse_value(value_literal)
-        return %{raise ArgumentError, "Value \#{it.inspect} is less than minimum #{value}" unless it >= #{value}}
-      when 'min-len'
-        value = parse_value(value_literal)
-        return %{raise ArgumentError, "Value \#{it.inspect} is shorter than minimum length #{value}" unless it.bytesize >= #{value}}
-      when 'max-len'
-        value = parse_value(value_literal)
-        return %{raise ArgumentError, "Value \#{it.inspect} is longer than maximum length #{value}" unless it.bytesize <= #{value}}
-      when 'exact-len'
-        value = parse_value(value_literal)
-        return %{raise ArgumentError, "Value \#{it.inspect} is not equal to length #{value}" unless it.bytesize == #{value}}
+      when 'max', 'min', 'min-len', 'max-len', 'exact-len'
+        Models::Check.new(operation: op, value: parse_value(value_literal))
       when 'unterminated-ok'
         return nil
       else
@@ -321,7 +355,7 @@ module Ynl
         (2 ** 31) - 1
       when String
         const = @consts[v] or raise ParseError, "Unknown value: #{v}"
-        const.value
+        const
       else
         raise ParseError, "Unknown value: #{v}"
       end
@@ -331,38 +365,72 @@ module Ynl
       name = d.fetch('name')
       if subset_of = d['subset-of']
         superset = @attribute_sets.fetch(subset_of)
-        result = Models::AttributeSubset.new(name:, superset:, attributes: d.fetch('attributes'), doc: translate_doc(d['doc']))
+        inherited = @attribute_definitions.fetch(subset_of).to_h { [it.fetch('name'), it] }
+        definitions = d.fetch('attributes').uniq { it.fetch('name') }.map do |override|
+          parent = inherited.fetch(override.fetch('name'))
+          parent.merge(override).merge('value' => parent.fetch('value'))
+        end
+        attributes = definitions.filter_map { parse_attribute(it) }
+        result = Models::AttributeSubset.new(name:, superset:, attributes:, doc: translate_doc(d['doc']))
       else
         name_prefix = d['name_prefix']
         result = Models::AttributeSet.new(name:, name_prefix:, doc: translate_doc(d['doc']))
         value = 0
-
-        d.fetch('attributes').each do |v|
+        definitions = d.fetch('attributes').map do |v|
           value = v.fetch('value', value + 1)
-          if type = parse_attribute_type(v)
-            attribute = Models::AttributeSet::Attribute.new(name: v.fetch('name'), type: type, value:)
-            result.attributes << attribute
-            if checks = v['checks']
-              attribute.checks = parse_checks(checks)
-            end
-          end
-        rescue
-          raise ParseError, "Failed to parse attribute: #{v.fetch('name')}"
+          v.merge('value' => value)
         end
+        result.attributes.concat(definitions.filter_map { parse_attribute(it) })
       end
 
       @attribute_sets[name] = result
+      @attribute_definitions[name] = definitions
 
-    rescue
-      raise ParseError, "Failed to parse attribute set: #{d.fetch('name')}"
+    rescue => error
+      raise ParseError, "Failed to parse attribute set #{d.fetch('name')}: #{error.message}"
+    end
+
+    private def parse_attribute(d)
+      multi_attr = d.fetch('multi-attr', false)
+      unless multi_attr == true || multi_attr == false
+        raise ParseError, "multi-attr must be a boolean"
+      end
+
+      enum_as_flags = d.fetch('enum-as-flags', false)
+      unless enum_as_flags == true || enum_as_flags == false
+        raise ParseError, "enum-as-flags must be a boolean"
+      end
+      if enum_as_flags && !d['enum']
+        raise ParseError, "enum-as-flags requires enum"
+      end
+
+      return unless type = parse_attribute_type(d)
+
+      Models::AttributeSet::Attribute.new(
+        name: d.fetch('name'),
+        type:,
+        value: d.fetch('value'),
+        checks: (parse_checks(d['checks']) if d['checks']),
+        doc: translate_doc(d['doc']),
+        multi_attr:,
+        enum: d['enum']&.then { |ref| Models::Thunk.new {|f| f.find_type(ref) } },
+        enum_as_flags:,
+      )
+    rescue => error
+      raise ParseError, "Failed to parse attribute #{d.fetch('name')}: #{error.message}"
     end
 
     private def parse_sub_message(d)
       name = d.fetch('name')
       result = Models::SubMessage.new(name:)
       d.fetch('formats', []).each do |fmt|
-        attr_set = fmt['attribute-set']&.then { @attribute_sets[it] }
-        result.formats << Models::SubMessage::Format.new(fmt['value'], attr_set)
+        fixed_header = fmt['fixed-header']&.then do |ref|
+          Models::Thunk.new {|f| f.structs.fetch(ref) }
+        end
+        attr_set = fmt['attribute-set']&.then do |ref|
+          Models::Thunk.new {|f| f.attribute_sets.fetch(ref) }
+        end
+        result.formats << Models::SubMessage::Format.new(fmt.fetch('value'), fixed_header, attr_set)
       end
       @sub_messages[name] = result
     end
@@ -384,18 +452,35 @@ module Ynl
 
       doit = d['do']&.then { parse_request_reply(it, default_request_id: request_id, default_reply_id: reply_id) }
       dumpit = d['dump']&.then { parse_request_reply(it, default_request_id: request_id, default_reply_id: reply_id) }
-
-      # TODO: notify
+      notification = parse_notification(d, default_id: reply_id)
 
       @operations[name] = Models::Operation.new(
-        name:, doc: translate_doc(d['doc']), fixed_header:, attribute_set:,
-        doit:, dumpit:,
+        name:, doc: translate_doc(d['doc']), flags: d.fetch('flags', []), fixed_header:, attribute_set:,
+        doit:, dumpit:, notification:,
       )
     end
 
+    private def parse_notification(d, default_id:)
+      if source = d['notify']
+        Models::Notification.new(
+          kind: :notify,
+          message: parse_message({}, default_id:),
+          source:,
+          group: d['mcgrp'],
+        )
+      elsif event = d['event']
+        Models::Notification.new(
+          kind: :event,
+          message: parse_message(event, default_id:),
+          source: nil,
+          group: d['mcgrp'],
+        )
+      end
+    end
+
     private def parse_request_reply(d, default_request_id:, default_reply_id:)
       Models::RequestReply.new(
-        request: d['request']&.then { parse_message(it, default_id: default_request_id) },
+        request: parse_message(d.fetch('request', {}), default_id: default_request_id),
         reply: d['reply']&.then { parse_message(it, default_id: default_reply_id) },
       )
     end
@@ -405,6 +490,12 @@ module Ynl
     end
 
     private def parse_mcast_group(d)
+      name = d.fetch('name')
+      @mcast_groups[name] = Models::McastGroup.new(
+        name,
+        d['value'],
+        translate_doc(d['doc']),
+      )
     end
 
     private def translate_doc(doc)

data/lib/ynl/version.rb

@@ -1,3 +1,3 @@
 module Ynl
-  VERSION = '0.2.4'
+  VERSION = '0.4.1'
 end

data/lib/ynl.rb

@@ -1,12 +1,27 @@
-# Parse for YNL netlink specification
+# Parser for YNL netlink specification
 #
 # See: https://www.kernel.org/doc/html/latest/userspace-api/netlink/specs.html
 
 require_relative 'ynl/family'
 
+# Ynl parser and code generator. See {Family} for library entrypoint.
 module Ynl
+  # @rbs!
+  #   interface _Readable
+  #     def read: () -> String
+  #   end
+  #
+  #   interface _Writable
+  #     def write: (*String strings) -> untyped
+  #   end
+  #
+  #   interface _PathLike
+  #      def to_path: () -> String
+  #   end
+
   class ParseError < StandardError; end
 
+  # @private
   module Types
     Scalar = Data.define(:type, :byte_order) do
       def resolve(f)
@@ -27,13 +42,25 @@ module Ynl
       end
     end
     Binary = Struct.new(:struct, :length, :display_hint) do
+      using Generator::Refinements
+
       def resolve(f)
         self.struct = struct.resolve(f) if self.struct
         self
       end
 
       def rbs_type
-        'untyped'
+        struct ? 'Structs::' + struct.name.as_class_name : '::String'
+      end
+    end
+    PackedArray = Struct.new(:sub_type) do
+      def resolve(f)
+        self.sub_type = sub_type.resolve(f)
+        self
+      end
+
+      def rbs_type
+        "::Array[#{sub_type.rbs_type}]"
       end
     end
     NestedAttributes = Struct.new(:attribute_set) do
@@ -48,6 +75,20 @@ module Ynl
         'AttributeSets::' + attribute_set.name.as_class_name
       end
     end
+    NestTypeValue = Struct.new(:attribute_set, :type_values) do
+      using Generator::Refinements
+
+      def resolve(f)
+        self.attribute_set = attribute_set.resolve(f)
+        self
+      end
+
+      def rbs_type
+        type = 'AttributeSets::' + attribute_set.name.as_class_name
+        type_values.length.times { type = "::Hash[::Integer, #{type}]" }
+        type
+      end
+    end
     SubMessage = Struct.new(:sub_message, :selector) do
       def resolve(f)
         self.sub_message = sub_message.resolve(f)
@@ -55,7 +96,7 @@ module Ynl
       end
 
       def rbs_type
-        'untyped'
+        '::Nl::SubMessage'
       end
     end
 
@@ -85,7 +126,7 @@ module Ynl
       end
 
       def rbs_type
-        '::Integer'
+        '::Nl::Bitfield32'
       end
     end
 
@@ -96,7 +137,7 @@ module Ynl
       end
 
       def rbs_type
-        'untyped'
+        "::Array[#{sub_type.rbs_type}]"
       end
     end
   end

data/sig/generated/ynl/family.rbs

@@ -0,0 +1,24 @@
+# Generated from lib/ynl/family.rb with RBS::Inline
+
+module Ynl
+  # Entry points for generating family classes from YNL specifications.
+  class Family
+    # Builds a family class from a YNL specification file.
+    #
+    # @param [String, #to_path] path a path to a YNL specification file
+    # @return [Class<Nl::Family>] the generated family class
+    # @rbs (String | _PathLike path) -> Class
+    def self.build: (String | _PathLike path) -> Class
+
+    # Generates Ruby source code to define a family class from a YNL specification.
+    #
+    # @param [String, #read] source a YAML string or readable IO containing the YNL specification
+    # @param [#write] out the destination for the generated source code
+    # @option kwargs [String, nil] superclass the name of the generated class's superclass
+    # @option kwargs [String, nil] namespace the namespace in which to define the family class
+    # @option kwargs [String, nil] default_resolver the expression used as the default family resolver
+    # @return [String] the generated family class name
+    # @rbs (String | _Readable source, _Writable out, ?superclass: String?, ?namespace: String?, ?default_resolver: String?) -> String
+    def self.generate: (String | _Readable source, _Writable out, ?superclass: String?, ?namespace: String?, ?default_resolver: String?) -> String
+  end
+end