ctypes 0.2.0

data/lib/ctypes/exporter.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2025 Cisco
+# SPDX-License-Identifier: MIT
+
+module CTypes
+  # Used to export CTypes
+  # @api private
+  class Exporter
+    def initialize(output = "".dup)
+      @output = output
+      @indent = 0
+      @indented = false
+      @type_lookup = nil
+    end
+    attr_writer :type_lookup
+    attr_reader :output
+
+    def nest(indent, &block)
+      @indent += indent
+      yield
+    ensure
+      @indent -= indent
+    end
+
+    def break
+      self << "\n"
+    end
+
+    def <<(arg)
+      case arg
+      when CTypes::Type
+        if buf = @type_lookup&.call(arg)
+          self << buf
+        else
+          nest(2) { arg.export_type(self) }
+        end
+      when ::String
+        unless @indented
+          @output << " " * @indent
+          @indented = true
+        end
+        @output << arg
+        @indented = !arg.end_with?("\n")
+      else
+        raise Error, "not supported"
+      end
+    end
+  end
+end

data/lib/ctypes/helpers.rb

@@ -0,0 +1,190 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2025 Cisco
+# SPDX-License-Identifier: MIT
+
+require "dry-types"
+
+module CTypes
+  module Helpers
+    extend self
+
+    # define integer types
+    [8, 16, 32, 64, 128].each do |bits|
+      define_method("uint%d" % bits) { CTypes.const_get("UInt#{bits}") }
+      define_method("int%d" % bits) { CTypes.const_get("Int#{bits}") }
+    end
+
+    # create an {Enum} type
+    # @param type [Type] integer type to encode as; default uint32
+    # @param values [Array, Hash] value names, or name-value pairs
+    #
+    # @example 8-bit enum with two known values
+    #   t = enum(uint8, [:a, :b])
+    #   t.pack(:a)                  # => "\x00"
+    #   t.pack(:b)                  # => "\x01"
+    #   t.pack(:c)                  # Dry::Types::ConstraintError
+    #
+    # @example sparse 32-bit enum
+    #   t = enum(uint32, {none: 0, a: 0x1000, b: 0x20})
+    #   t.pack(:none)               # => "\0\0\0\0"
+    #   t.pack(:a)                  # => "\x00\x10\x00\x00" (little endian)
+    #   t.pack(:b)                  # => "\x20\x00\x00\x00" (little endian)
+    #
+    # @example sparse 32-bit enum using builder
+    #   t = enum(uint16) do |e|
+    #     e << %i{a b c}            # a = 0, b = 1, c = 2
+    #     e << {d: 16}              # d = 16
+    #     e << :e                   # e = 17
+    #   end
+    #   t.pack(:e)                  # => "\x11\x00" (little endian)
+    def enum(type = nil, values = nil, &)
+      Enum.new(type, values, &)
+    end
+
+    # create a {Bitmap} type
+    # @param type [Type] integer type to encode as; default min bytes required
+    # @param bits [Hash, Enum] map of names to bit position
+    #
+    # @example 32-bit bitmap
+    #   bitmap({a: 0, b: 1, c: 2})  # => #<Bitmap ...>
+    #
+    # @example 32-bit bitmap using block syntax; same as [Enum]
+    #   bitmap do |b|
+    #     b << :a
+    #     b << :b
+    #   end # => #<Bitmap a: 0, b: 1>
+    #
+    # @example 8-bit bitmap
+    #   bitmap(uint8, {a: 0, b: 1}) # => #<Bitmap a: 0, b: 1>
+    #
+    def bitmap(type = nil, bits = nil, &)
+      if bits.nil?
+        bits = type
+        type = uint32
+      end
+
+      bits = enum(bits, &) unless bits.is_a?(Enum)
+      Bitmap.new(type: type, bits: bits)
+    end
+
+    # create a {String} type
+    # @param size [Integer] optional string size in bytes
+    # @param trim [Boolean] set to false to preserve trailing null bytes when
+    #   unpacking
+    #
+    # @example 5 byte string
+    #   s = string(5)
+    #   s.unpack("hello world")   # => "hello")
+    def string(size = nil, trim: true)
+      String.new(size:, trim:)
+    end
+
+    # create a {Struct} type
+    # @param attributes [Hash] name/type attribute pairs
+    # @yield block passed to {Struct::Builder}
+    #
+    # @example hash syntax
+    #   t = struct(id: uint32, name: string.terminated)
+    #   t.pack({id: 1, name: "Karlach"})    # => "\1\0\0\0Karlach\0"
+    #
+    # @example block syntax
+    #   t = struct do
+    #     attribute :id, uint32
+    #     attrubite :name, string.terminated
+    #   end
+    #   t.pack({id: 1, name: "Karlach"})    # => "\1\0\0\0Karlach\0"
+    def struct(attributes = nil, &block)
+      Class.new(Struct) do
+        if attributes
+          layout do
+            attributes.each do |name, type|
+              attribute name, type
+            end
+          end
+        else
+          layout(&block)
+        end
+      end
+    end
+
+    # create a {Union} type
+    # @param members [Hash] name/type member pairs
+    # @yield block bassed to {Union::Builder}
+    #
+    # @example hash syntax
+    #   t = union(word: uint32, halfword: uint16, byte: uint8)
+    #   t.pack({byte: 3})   # => "\x03\x00\x00\x00"
+    #
+    # @example block syntax
+    #   t = union do
+    #     member :word, uint32
+    #     member :halfword, uint16
+    #     member :byte, uint8
+    #   end
+    #   t.pack({byte: 3})   # => "\x03\x00\x00\x00"
+    def union(members = nil, &block)
+      Class.new(Union) do
+        if members
+          layout do
+            members.each do |name, type|
+              member name, type
+            end
+          end
+        else
+          layout(&block)
+        end
+      end
+    end
+
+    # create an {Array} type
+    # @param type [Type] data type contained within the array
+    # @param size [Integer] optional array size; no size implies greedy array
+    # @param terminator optional unpacked value that represents the array
+    #   terminator
+    #
+    # @example
+    #   # greedy array of uint32 values
+    #   array(uint32)
+    #   # array of 4 uint8 values
+    #   array(uint8, 4)
+    #   # array of signed 32-bit integers terminated with a -1
+    #   array(int32, terminator: -1)
+    def array(type, size = nil, terminator: nil)
+      Array.new(type:, size:, terminator:)
+    end
+
+    # create a {Bitfield} type
+    # @param type [Type] type to use for packed representation
+    # @param bits [Hash] map of name to bit count
+    # @yield block passed to {Bitfield::Builder}
+    #
+    # @example dynamically sized
+    #   t = bitfield(a: 1, b: 2, c: 3)
+    #   t.pack({c: 0b111})    # => "\x38" (0b00111000)
+    #
+    # @example fixed size to pad to 16 bits.
+    #   t = bitfield(uint16, a: 1, b: 2, c: 3)
+    #   t.pack({c: 0b111})    # => "\x38\x00" (0b00111000_00000000)
+    #
+    def bitfield(type = nil, bits = nil, &block)
+      if bits.nil? && !block
+        bits = type
+        type = nil
+      end
+
+      Class.new(Bitfield) do
+        if bits
+          layout do
+            bytes(type.size) if type
+            bits.each do |name, size|
+              unsigned name, size
+            end
+          end
+        else
+          layout(&block)
+        end
+      end
+    end
+  end
+end

data/lib/ctypes/importers/castxml/loader.rb

@@ -0,0 +1,150 @@
+# SPDX-FileCopyrightText: 2025 Cisco
+# SPDX-License-Identifier: MIT
+
+require "nokogiri"
+
+module CTypes
+  class Importers::CastXML::Loader
+    include CTypes::Helpers
+
+    def initialize(io)
+      @doc = Nokogiri.parse(io)
+      @xml = @doc.xpath("//castxml[1]")&.first or
+        raise Error, "<castxml> node not found"
+      @nodes = @xml.xpath("./*[@id]").each_with_object({}) { |n, o|
+        o[n[:id]] = n
+      }
+      @ctypes = {}
+    end
+    attr_reader :xml
+
+    def load
+      m = Module.new
+      load_into(m)
+    end
+
+    def load_into(namespace)
+      @xml.children.each do |node|
+        next unless node.element?
+
+        case node.name
+        when "typedef", "struct", "union", "array", "enumeration"
+          # skip builtin types
+          next if node[:file] == "f0"
+
+          name, type = ctype(node[:id])
+          next if name.empty?
+
+          namespace.define_singleton_method(name) { type }
+        end
+      end
+
+      namespace
+    end
+
+    private
+
+    def ctype(id)
+      return @ctypes[id] if @ctypes.has_key?(id)
+      node = @nodes[id] or raise Error, "node not found: id=\"#{id}\""
+
+      return node[:name], nil if node[:incomplete] == "1"
+
+      type = case node.name
+      when "fundamentaltype"
+        unsigned = node[:name].include?("unsigned")
+        case node[:size]
+        when "0"
+          nil
+        when "128"
+          array(unsigned ? uint64 : int64, 2)
+        when "64"
+          unsigned ? uint64 : int64
+        when "32"
+          unsigned ? uint32 : int32
+        when "16"
+          unsigned ? uint16 : int16
+        when "8"
+          unsigned ? uint8 : int8
+        else
+          raise Error, "unknown FundamentalType: %s" % node.pretty_inspect
+        end
+      when "typedef", "field", "elaboratedtype", "cvqualifiedtype"
+        _, t = ctype(node[:type])
+        t
+      when "struct"
+        if node.has_attribute?("members")
+          pos = 0
+          members = node[:members].split.each_with_object({}) do |mid, o|
+            # to support member alignment, we need to do some extra work here
+            # to add padding members to structures when there are gaps.  Note
+            # that for some reason, anonymous structs are not counted towards
+            # the offset of following struct fields; this may be a bug in llvm,
+            # as castxml just prints what was provided.
+            mem = @nodes[mid] or raise Error, "node not found: id=\"#{mid}\""
+            if mem.has_attribute?("offset")
+
+              # add a padding member to the struct if needed
+              offset = mem[:offset].to_i
+              if pos < offset
+                o[:"__pad_#{pos / 8}"] =
+                  string((offset - pos) / 8, trim: false)
+              end
+
+              # always set pos to the current offset; this handles the case
+              # where we added the size of a nested anonymous struct, but llvm
+              # does not appear to.
+              pos = offset
+            end
+
+            name, mtype = ctype(mid)
+            o[name.to_sym] = mtype unless name.empty?
+            pos += mtype.size * 8
+          end
+        else
+          members = {unknown: array(uint8, node[:size].to_i)}
+        end
+        struct(members)
+      when "union"
+        members = node[:members].split.each_with_object({}) do |mid, o|
+          name, mtype = ctype(mid)
+          o[name.to_sym] = mtype
+        end
+        union(members)
+      when "arraytype"
+        n, t = ctype(node[:type])
+        if n == "char"
+          string(node[:max].to_i + 1)
+        else
+          array(t, node[:max].to_i + 1)
+        end
+      when "enumeration"
+        values = node.children.each_with_object({}) do |v, o|
+          o[v[:name].downcase] = v[:init].to_i if v.name == "enumvalue"
+        end
+        type = if node[:type]
+          _, t = ctype(node[:type])
+          t
+        elsif node[:size] == "32"
+          uint32
+        else
+          raise Error, "unsupported enum node: %p" % node
+        end
+        enum(type, values)
+      when "pointertype"
+        case node[:size]
+        when "64"
+          uint64
+        when "32"
+          uint32
+        else
+          raise Error, "unknown PointerType size: %s" % node.pretty_inspect
+        end
+      else
+        raise "unsupported node: %s" % node.pretty_inspect
+      end
+
+      @ctypes[id] = [node[:name], type]
+    end
+  end
+end

data/lib/ctypes/importers/castxml.rb

@@ -0,0 +1,59 @@
+# SPDX-FileCopyrightText: 2025 Cisco
+# SPDX-License-Identifier: MIT
+
+require "open3"
+begin
+  require "nokogiri"
+rescue LoadError
+  puts <<~ERR
+    WARNING: Failed to require `nokogiri` gem.
+    
+    `nokogiri` is required to parse CastXML output.  To use the CastXML
+    importer, please install the gem.
+  ERR
+end
+
+module CTypes
+  module Importers
+    module CastXML
+      class CompilerError < CTypes::Error; end
+
+      def self.load_xml(xml)
+        io = case xml
+        when IO
+          xml
+        when ::String
+          StringIO.new(xml)
+        else
+          raise Error, "arg must be IO or String: %p" % xml
+        end
+
+        l = Loader.new(io)
+        l.load
+      end
+
+      def self.load_xml_file(path)
+        File.open(path) do |f|
+          load_xml(f)
+        end
+      end
+
+      def self.load_source(src)
+        Tempfile.open(["", ".c"]) do |f|
+          f.write(src)
+          f.flush
+          load_source_file(f.path)
+        end
+      end
+
+      def self.load_source_file(path)
+        stdout, stderr, status = Open3
+          .capture3("castxml --castxml-output=1 #{path} -o -")
+        raise CompilerError, stderr unless status.success?
+        load_xml(stdout)
+      end
+    end
+  end
+end
+
+require_relative "castxml/loader"

data/lib/ctypes/importers.rb

@@ -0,0 +1,7 @@
+# SPDX-FileCopyrightText: 2025 Cisco
+# SPDX-License-Identifier: MIT
+
+module CTypes
+  # Tools for importing types from other sources to declare ctypes
+  module Importers; end
+end

data/lib/ctypes/int.rb

@@ -0,0 +1,147 @@
+# encoding: ASCII-8BIT
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2025 Cisco
+# SPDX-License-Identifier: MIT
+
+module CTypes
+  # Handles packing and unpacking of integer types of various lengths and
+  # signed-ness.  The most common integer sizes have been declared as
+  # constants:
+  # - unsigned: {UInt64}, {UInt32}, {UInt16}, {UInt8}
+  # - signed: {Int64}, {Int32}, {Int16}, {Int8}
+  # or their respective helpers in {Helpers}.
+  class Int
+    include Type
+
+    # initialize an {Int} type
+    #
+    # @param [Integer] bits number of bits in the integer
+    # @param [Boolean] signed set to true if integer is signed
+    # @param [String] format {::Array#pack} format for integer
+    # @param [String] desc human-readable description of type
+    #
+    def initialize(bits:, signed:, format:, desc:)
+      type = Dry::Types["integer"].default(0)
+      @signed = !!signed
+      if @signed
+        @min = 0 - (1 << (bits - 1))
+        @max = 1 << (bits - 1) - 1
+      else
+        @min = 0
+        @max = (1 << bits) - 1
+      end
+      @dry_type = type.constrained(gteq: @min, lteq: @max)
+      @size = bits / 8
+      if @size > 1
+        @format_big = "#{format}>"
+        @format_little = "#{format}<"
+      else
+        @format_big = @format_little = format.to_s
+      end
+      @fmt = (@size > 1) ? {big: "#{format}>", little: "#{format}<"} :
+        {big: format.to_s, little: format.to_s}
+      @desc = desc
+    end
+    attr_reader :size, :min, :max
+
+    # convert an Integer into a String containing the binary representation of
+    # that number for the given type.
+    #
+    # @param value [Integer] number to pack
+    # @param endian [Symbol] byte order
+    # @param validate [Boolean] set to false to disable bounds checking
+    # @return [String] binary encoding for value
+    #
+    # @example pack a uint32_t using the native endian
+    #   CTypes::UInt32.pack(0x12345678) # => "\x78\x56\x34\x12"
+    #
+    # @example pack a big endian uint32_t
+    #   CTypes::UInt32.pack(endian: :big) # => "\x12\x34\x56\x78"
+    #
+    # @example pack a fixed-endian (big) uint32_t
+    #   t = UInt32.with_endian(:big)
+    #   t.pack(0x12345678) # => "\x12\x34\x56\x78"
+    #
+    # @see CTypes::Type#pack
+    def pack(value, endian: default_endian, validate: true)
+      value = (value.nil? ? @dry_type[] : @dry_type[value]) if validate
+      endian ||= default_endian
+      [value].pack(@fmt[endian])
+    end
+
+    # decode an Integer from the byte String provided, returning both the
+    # Integer and any unused bytes in the String
+    #
+    # @param buf [String] bytes to be unpacked
+    # @param endian [Symbol] endian of data within buf
+    # @return [Integer, String] decoded Integer, and remaining bytes
+    #
+    # @example pack a uint32_t using the native endian
+    #   CTypes::UInt32.pack(0x12345678) # => "\x78\x56\x34\x12"
+    #
+    # @example pack a big endian uint32_t
+    #   CTypes::UInt32.pack(endian: :big) # => "\x12\x34\x56\x78"
+    #
+    # @example pack a fixed-endian (big) uint32_t
+    #   t = UInt32.with_endian(:big)
+    #   t.pack(0x12345678) # => "\x12\x34\x56\x78"
+    #
+    # @see CTypes::Type#unpack
+    # @see CTypes::Type#unpack_one
+    def unpack_one(buf, endian: default_endian)
+      endian ||= default_endian # override nil
+      value = buf.unpack1(@fmt[endian]) or
+        raise missing_bytes_error(input: buf, need: @size)
+      [value, buf.byteslice(@size..)]
+    end
+
+    # @api private
+    def greedy?
+      false
+    end
+
+    # @api private
+    def signed?
+      @signed
+    end
+
+    # @api private
+    def pretty_print(q) # :nodoc:
+      if @endian
+        q.text(@desc + ".with_endian(%p)" % @endian)
+      else
+        q.text(@desc)
+      end
+    end
+    alias_method :inspect, :pretty_inspect # :nodoc:
+
+    # @api private
+    def export_type(q) # :nodoc:
+      q << @desc
+      q << ".with_endian(%p)" % [@endian] if @endian
+    end
+
+    # @api private
+    def type_name
+      "#{@desc}_t"
+    end
+  end
+
+  # base type for unsiged 8-bit integers
+  UInt8 = Int.new(bits: 8, signed: false, format: "C", desc: "uint8")
+  # base type for unsiged 16-bit integers
+  UInt16 = Int.new(bits: 16, signed: false, format: "S", desc: "uint16")
+  # base type for unsiged 32-bit integers
+  UInt32 = Int.new(bits: 32, signed: false, format: "L", desc: "uint32")
+  # base type for unsiged 64-bit integers
+  UInt64 = Int.new(bits: 64, signed: false, format: "Q", desc: "uint64")
+  # base type for siged 8-bit integers
+  Int8 = Int.new(bits: 8, signed: true, format: "c", desc: "int8")
+  # base type for siged 16-bit integers
+  Int16 = Int.new(bits: 16, signed: true, format: "s", desc: "int16")
+  # base type for siged 32-bit integers
+  Int32 = Int.new(bits: 32, signed: true, format: "l", desc: "int32")
+  # base type for siged 64-bit integers
+  Int64 = Int.new(bits: 64, signed: true, format: "q", desc: "int64")
+end

data/lib/ctypes/missing_bytes_error.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2025 Cisco
+# SPDX-License-Identifier: MIT
+
+module CTypes
+  # Exception raised when attempting to unpack a {Type} that requires more
+  # bytes than were provided in the input.
+  class MissingBytesError < Error
+    def initialize(type:, input:, need:)
+      @type = type
+      @input = input
+      @need = need
+      super("insufficent input to unpack %s; missing %d bytes" %
+        [@type, missing])
+    end
+    attr_reader :type, :input, :need
+
+    # get the number of additional bytes required to unpack this type
+    def missing
+      @need - @input.size
+    end
+  end
+end

data/lib/ctypes/pad.rb

@@ -0,0 +1,56 @@
+# encoding: ASCII-8BIT
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2025 Cisco
+# SPDX-License-Identifier: MIT
+
+module CTypes
+  # Generic type to represent a gap in the data structure.  Unpacking this
+  # type will consume the pad size and return nil.  Packing this type will
+  # return a string of null bytes of the appropriate size.
+  #
+  # @example
+  #   t = Pad.new(4)
+  #   t.unpack_one("hello_world)  # => [nil, "o_world"]
+  #   t.pack("blahblahblah")      # => "\0\0\0\0"
+  class Pad
+    include Type
+
+    def initialize(size)
+      @size = size
+      @dry_type = Dry::Types::Any.default(nil)
+    end
+    attr_reader :size
+
+    def pack(value, endian: default_endian, validate: true)
+      "\0" * @size
+    end
+
+    def unpack_one(buf, endian: default_endian)
+      raise missing_bytes_error(input: buf, need: @size) if
+        @size && buf.size < @size
+      [nil, buf.byteslice(@size..)]
+    end
+
+    def greedy?
+      false
+    end
+
+    def to_s
+      "pad(%d)" % [@size]
+    end
+
+    def pretty_print(q)
+      q.text("pad(%d)" % @size)
+    end
+    alias_method :inspect, :pretty_inspect # :nodoc:
+
+    def export_type(q)
+      q << ".pad(%d)" % [@size]
+    end
+
+    def ==(other)
+      other.is_a?(self.class) && other.size == size
+    end
+  end
+end