esp_flash 0.1.0

data/lib/esp_flash/monitor.rb

@@ -0,0 +1,268 @@
+# frozen_string_literal: true
+
+require "io/console"
+
+module EspFlash
+  # A serial terminal for the device. Keystrokes reach the device byte for byte, terminal replies included
+  # (the answer to a "ESC [5n"/"ESC [6n" query, which the picoruby-shell sends to detect the terminal), and
+  # what the device sends is written out as it arrives. Ctrl-C goes to the device too.
+  #
+  #   Ctrl-]          quit
+  #   Ctrl-T Ctrl-R   reset the device (Ctrl-T Ctrl-H lists the menu)
+  #
+  # When the ELF and the toolchain's addr2line are available, addresses in a panic's backtrace are decoded.
+  #
+  # On a terminal, a line feed from the device also returns the cursor to the start of the line (the
+  # terminal is in raw mode, which would leave that to the device), and ESP-IDF log lines are colored by
+  # their level ("I (123) tag: ..." green, W yellow, E red) as esp-idf-monitor does.
+  class Monitor
+    EXIT_KEY = 0x1d # Ctrl-]
+    MENU_KEY = 0x14 # Ctrl-T
+    LOG_COLORS = { "I" => "\e[0;32m", "W" => "\e[0;33m", "E" => "\e[1;31m" }.freeze
+    COLOR_RESET = "\e[0m"
+    LOG_HEADER = /\A([IWE]) \([\d:. -]+\)/n
+    LOG_HEADER_PREFIX = /\A(?:[IWE](?: (?:\([\d:. -]*)?)?)?\z/n # what may still become a LOG_HEADER
+    XTENSA_TARGETS = %w[esp32 esp32s2 esp32s3].freeze
+
+    def initialize(path, baud:, target: nil, elf: nil, reset: true, input: $stdin, output: $stdout, terminal: nil)
+      @path = path
+      @baud = baud
+      @reset = reset
+      @input = input
+      @output = output
+      @terminal = terminal.nil? ? output.respond_to?(:tty?) && output.tty? : terminal
+      @line_start = true # the next byte from the device starts a line
+      @held = "".b # the start of a line that may be a log header, until the rest of it arrives
+      @colored = false # a log line's color is on
+      @elf = elf if elf && File.exist?(elf)
+      @addr2line = find_addr2line(target) if @elf
+      @menu = false
+      @line = "".b
+      @out_mutex = Mutex.new
+    end
+
+    def run
+      @port = SerialPort.open(@path, @baud)
+      status "--- Monitoring #{@path}#{" at #{@baud} baud" if @port.resettable?}. " \
+             "Quit: Ctrl-]  Reset: Ctrl-T Ctrl-R  Help: Ctrl-T Ctrl-H ---"
+      reset_device if @reset
+      reader = Thread.new { read_loop }
+      raw_input { input_loop }
+    ensure
+      reader&.kill
+      @port&.close
+    end
+
+    private
+
+    def input_loop
+      loop do
+        data = begin
+          @input.readpartial(1024)
+        rescue EOFError
+          return
+        end
+        out = "".b
+        data.each_byte do |byte|
+          if @menu
+            @menu = false
+            case byte
+            when 0x12, 0x52, 0x72 # Ctrl-R, R, r
+              send_to_device(out)
+              out = "".b
+              reset_device
+            when MENU_KEY then out << byte # Ctrl-T Ctrl-T sends Ctrl-T itself
+            when 0x18, 0x58, 0x78 # Ctrl-X, X, x
+              send_to_device(out)
+              return
+            else help
+            end
+          elsif byte == EXIT_KEY
+            send_to_device(out)
+            return
+          elsif byte == MENU_KEY
+            @menu = true
+          else
+            out << byte
+          end
+        end
+        send_to_device(out)
+      end
+    end
+
+    def read_loop
+      loop do
+        data = @port.read(4096, 0.2)
+        next flush_held if data.empty?
+
+        @out_mutex.synchronize do
+          @output.write(@terminal ? render(data) : data)
+          @output.flush
+        end
+        decode_backtrace(data) if @addr2line
+      rescue Disconnected
+        reconnect
+      end
+    end
+
+    # A USB serial device can vanish for a moment while the chip resets (e.g. the USB-Serial/JTAG one).
+    def reconnect
+      status "--- #{@path} disconnected; waiting for it to come back (Ctrl-] to quit) ---"
+      @port.close
+      loop do
+        sleep 0.5
+        begin
+          @port = SerialPort.open(@path, @baud)
+          break
+        rescue Error
+          next
+        end
+      end
+      status "--- Reconnected to #{@path} ---"
+    end
+
+    # For a terminal: "\n" => "\r\n" (unless after "\r"), and log lines colored by their level.
+    def render(data)
+      data = @held + data
+      @held = "".b
+      out = "".b
+      pos = 0
+      while pos < data.bytesize
+        if @line_start
+          rest = data.byteslice(pos..)
+          if (header = LOG_HEADER.match(rest))
+            out << LOG_COLORS[header[1]]
+            @colored = true
+          elsif LOG_HEADER_PREFIX.match?(rest)
+            @held = rest
+            break
+          end
+          @line_start = false
+        end
+        newline = data.index("\n", pos)
+        unless newline
+          out << data.byteslice(pos..)
+          break
+        end
+        line = data.byteslice(pos, newline - pos)
+        line = line.chomp("\r")
+        out << line
+        out << COLOR_RESET if @colored
+        out << "\r\n"
+        @colored = false
+        @line_start = true
+        pos = newline + 1
+      end
+      out
+    end
+
+    # Writes out what render held back, when no more of the line came.
+    def flush_held
+      return if @held.empty?
+
+      @out_mutex.synchronize do
+        @output.write(@held)
+        @output.flush
+      end
+      @held = "".b
+      @line_start = false
+    end
+
+    def send_to_device(bytes)
+      @port.write(bytes) unless bytes.empty?
+    rescue Disconnected, IOError
+      nil # read_loop reconnects
+    end
+
+    def reset_device
+      return status("--- #{@path} cannot reset the device ---") unless @port.resettable?
+
+      status "--- Resetting the device ---"
+      EspFlash.hard_reset(@port)
+    end
+
+    def help
+      status "--- Ctrl-]: quit  Ctrl-T Ctrl-R: reset  Ctrl-T Ctrl-X: quit  Ctrl-T Ctrl-T: send Ctrl-T ---"
+    end
+
+    def status(message)
+      @out_mutex.synchronize do
+        @output.write("\r\n#{message}\r\n")
+        @output.flush
+      end
+    end
+
+    # Raw mode so that every key (and every terminal reply) is read as it comes, without echo or signals.
+    def raw_input(&block)
+      return yield unless @input.respond_to?(:tty?) && @input.tty?
+
+      @input.raw(intr: false) do
+        windows_vt_mode(&block)
+      end
+    end
+
+    # The Windows console answers "ESC [6n" and sends keys as escape sequences only in its VT modes.
+    def windows_vt_mode
+      return yield unless Gem.win_platform?
+
+      require "fiddle/import"
+      k32 = Module.new do
+        extend Fiddle::Importer
+        dlload "kernel32.dll"
+        extern "void* GetStdHandle(long)"
+        extern "int GetConsoleMode(void*, void*)"
+        extern "int SetConsoleMode(void*, unsigned long)"
+      end
+      saved = [[-10, 0x0200], [-11, 0x0004]].filter_map do |std, flag| # VT input / VT processing
+        handle = k32.GetStdHandle(std)
+        mode = [0].pack("V")
+        next if k32.GetConsoleMode(handle, mode).zero?
+
+        mode = mode.unpack1("V")
+        k32.SetConsoleMode(handle, mode | flag)
+        [handle, mode]
+      end
+      begin
+        yield
+      ensure
+        saved.each { |handle, mode| k32.SetConsoleMode(handle, mode) }
+      end
+    end
+
+    def find_addr2line(target)
+      names = if XTENSA_TARGETS.include?(target)
+                ["xtensa-esp-elf-addr2line", "xtensa-#{target}-elf-addr2line"]
+              else
+                ["riscv32-esp-elf-addr2line"]
+              end
+      exts = Gem.win_platform? ? [".exe", ""] : [""]
+      ENV["PATH"].to_s.split(File::PATH_SEPARATOR).product(names, exts).each do |dir, name, ext|
+        path = File.join(dir, name + ext)
+        return path if File.file?(path) && File.executable?(path)
+      end
+      nil
+    end
+
+    # Decodes the code addresses of a panic's "Backtrace:" line (Xtensa) or "MEPC"/"RA" registers (RISC-V).
+    def decode_backtrace(data)
+      @line << data
+      while (newline = @line.index("\n"))
+        line = @line.slice!(0..newline)
+        next unless line.match?(/Backtrace:|^\s*(PC|MEPC|RA)\s*:/n)
+
+        addresses = line.scan(/0x4[0-9a-f]{7}/in).uniq
+        next if addresses.empty?
+
+        decoded = IO.popen([@addr2line, "-pfiaC", "-e", @elf, *addresses], err: File::NULL, &:read).to_s
+        lines = decoded.lines.map(&:chomp).reject { |l| l.include?("?? ??:0") }
+        @out_mutex.synchronize do
+          lines.each { |l| @output.write("--- #{l}\r\n") }
+          @output.flush
+        end
+      end
+      @line = @line.byteslice(-1024..) if @line.bytesize > 4096
+    rescue SystemCallError
+      @addr2line = nil
+    end
+  end
+end

data/lib/esp_flash/serial_port.rb

@@ -0,0 +1,348 @@
+# frozen_string_literal: true
+
+require "io/wait"
+require "socket"
+
+module EspFlash
+  # A serial port without any gem or C extension. Every backend has the same interface:
+  #   read(max, timeout)   up to +max+ bytes, waiting up to +timeout+ seconds for the first one ("" if none)
+  #   write(bytes)
+  #   baud = rate
+  #   set_lines(dtr:, rts:) asserts (true) / deasserts (false) DTR and RTS; nil leaves a line as it is
+  #   discard_input        drops whatever has been received so far
+  #   resettable?          false when DTR/RTS do not reach a chip (a TCP socket)
+  #   close
+  #
+  # "socket://HOST:PORT" opens a TCP connection instead (e.g. QEMU's UART).
+  module SerialPort
+    def self.open(path, baud)
+      if path.start_with?("socket://")
+        TcpPort.new(path, baud)
+      elsif Gem.win_platform?
+        WindowsPort.new(path, baud)
+      else
+        PosixPort.new(path, baud)
+      end
+    end
+
+    # Serial ports that are likely to be a USB-connected board.
+    def self.candidates
+      if Gem.win_platform?
+        WindowsPort.list
+      elsif RUBY_PLATFORM.include?("darwin")
+        Dir["/dev/cu.{usbserial,usbmodem,SLAB_USBtoUART,wchusbserial}*"].sort
+      else
+        Dir["/dev/tty{USB,ACM}*"].sort
+      end
+    end
+
+    # The port to use: +given+ (e.g. ENV['PORT']) if set, the only candidate, or one the user picks when
+    # there are several and stdin is a terminal.
+    def self.resolve(given)
+      return given if given && !given.empty?
+
+      ports = candidates
+      case ports.size
+      when 0
+        raise Error, "No serial port found. Connect the board, or set PORT (e.g. PORT=/dev/ttyUSB0)."
+      when 1
+        ports.first
+      else
+        raise Error, "Several serial ports found (#{ports.join(", ")}); set PORT to pick one." unless $stdin.tty?
+
+        $stderr.puts "Several serial ports found:"
+        ports.each_with_index { |port, i| $stderr.puts "  #{i + 1}) #{port}" }
+        $stderr.print "Select one [1-#{ports.size}]: "
+        index = Integer($stdin.gets.to_s.strip, exception: false)
+        raise Error, "No port selected." unless index && (1..ports.size).cover?(index)
+
+        ports[index - 1]
+      end
+    end
+
+    # A USB serial device on Linux/macOS, set up with stty(1) and its modem lines driven with ioctl(2).
+    class PosixPort
+      LINUX = RUBY_PLATFORM.include?("linux")
+      TIOCMGET = LINUX ? 0x5415 : 0x4004746a
+      TIOCMSET = LINUX ? 0x5418 : 0x8004746d
+      TIOCM_DTR = 0x002
+      TIOCM_RTS = 0x004
+
+      # struct termios2 (asm-generic/termbits.h): 4 x u32 flags, c_line, c_cc[19], u32 c_ispeed/c_ospeed.
+      # BOTHER takes any rate from c_ispeed/c_ospeed.
+      TCGETS2 = 0x802c542a
+      TCSETS2 = 0x402c542b
+      TERMIOS2 = "V4Ca19VV"
+      CBAUD = 0o010017
+      BOTHER = 0o010000
+      CSIZE = 0o000060
+      CS8 = 0o000060
+      CSTOPB = 0o000100
+      CREAD = 0o000200
+      PARENB = 0o000400
+      CLOCAL = 0o004000
+      CRTSCTS = 0o20000000000
+      VTIME = 5
+      VMIN = 6
+
+      attr_reader :path
+
+      def initialize(path, baud)
+        @path = path
+        @io = File.open(path, File::RDWR | File::NOCTTY | File::NONBLOCK)
+        @io.binmode
+        @io.sync = true
+        self.baud = baud
+      rescue SystemCallError => e
+        @io&.close
+        raise Error, "Cannot open #{path}: #{e.message}"
+      end
+
+      def resettable? = true
+
+      # ESP-IDF's USB-Serial/JTAG controller (VID:PID 303a:1001), known on Linux only (nil elsewhere).
+      def usb_jtag_serial?
+        return nil unless LINUX
+
+        dir = File.realpath("/sys/class/tty/#{File.basename(File.realpath(@path))}/device")
+        dir = File.dirname(dir) until dir == "/" || File.exist?(File.join(dir, "idVendor"))
+        return false if dir == "/"
+
+        File.read(File.join(dir, "idVendor")).strip == "303a" && File.read(File.join(dir, "idProduct")).strip == "1001"
+      rescue SystemCallError
+        nil
+      end
+
+      # Raw 8N1 without flow control at +baud+.
+      def baud=(baud)
+        LINUX ? linux_termios2(baud) : stty(baud)
+      rescue SystemCallError => e
+        raise Error, "Cannot set #{@path} to #{baud} baud: #{e.message}"
+      end
+
+      def read(max, timeout)
+        return "".b unless @io.wait_readable(timeout)
+
+        data = @io.read_nonblock(max, exception: false)
+        data.is_a?(String) ? data : "".b
+      rescue EOFError, Errno::EIO, Errno::ENXIO => e
+        raise Disconnected, "#{@path}: #{e.message}"
+      end
+
+      def write(bytes)
+        @io.write(bytes)
+      rescue Errno::EIO, Errno::ENXIO => e
+        raise Disconnected, "#{@path}: #{e.message}"
+      end
+
+      # Both lines change in one ioctl when both are given (what esptool's "tight" reset relies on).
+      def set_lines(dtr: nil, rts: nil)
+        buf = [0].pack("i")
+        @io.ioctl(TIOCMGET, buf)
+        bits = buf.unpack1("i")
+        bits = dtr ? bits | TIOCM_DTR : bits & ~TIOCM_DTR unless dtr.nil?
+        bits = rts ? bits | TIOCM_RTS : bits & ~TIOCM_RTS unless rts.nil?
+        @io.ioctl(TIOCMSET, [bits].pack("i"))
+      end
+
+      def discard_input
+        loop { break if read(4096, 0).empty? }
+      end
+
+      def close
+        @io.close unless @io.closed?
+      end
+
+      private
+
+      def linux_termios2(baud)
+        buf = "\0".b * 44
+        @io.ioctl(TCGETS2, buf)
+        _iflag, _oflag, cflag, _lflag, line, cc, = buf.unpack(TERMIOS2)
+        cflag &= ~(CBAUD | CSIZE | CSTOPB | PARENB | CRTSCTS)
+        cflag |= BOTHER | CS8 | CREAD | CLOCAL
+        cc = cc.b
+        cc.setbyte(VTIME, 0)
+        cc.setbyte(VMIN, 1)
+        @io.ioctl(TCSETS2, [0, 0, cflag, 0, line, cc, baud, baud].pack(TERMIOS2))
+      end
+
+      # stty(1) sets up its stdin, which is this port (kept open, so the settings stay).
+      def stty(baud)
+        ok = system("stty", baud.to_s, "raw", "-echo", "cs8", "-cstopb", "-parenb", "-crtscts", "clocal", "cread",
+                    in: @io, err: File::NULL)
+        raise Error, "Cannot set #{@path} to #{baud} baud (stty failed)" unless ok
+      end
+    end
+
+    # A TCP connection, e.g. to QEMU's UART. There are no modem lines, so the chip cannot be reset.
+    class TcpPort
+      attr_reader :path
+
+      def initialize(path, _baud)
+        @path = path
+        host, port = path.delete_prefix("socket://").split(":", 2)
+        @io = Socket.tcp(host, Integer(port), connect_timeout: 5)
+        @io.setsockopt(Socket::IPPROTO_TCP, Socket::TCP_NODELAY, 1)
+      rescue SystemCallError, SocketError, ArgumentError, TypeError => e
+        raise Error, "Cannot connect to #{path}: #{e.message}"
+      end
+
+      def resettable? = false
+      def usb_jtag_serial? = false
+      def baud=(_baud); end
+      def set_lines(dtr: nil, rts: nil); end
+
+      def read(max, timeout)
+        return "".b unless @io.wait_readable(timeout)
+
+        @io.read_nonblock(max)
+      rescue IO::WaitReadable
+        "".b
+      rescue EOFError, SystemCallError => e
+        raise Disconnected, "#{@path}: #{e.message}"
+      end
+
+      def write(bytes)
+        @io.write(bytes)
+      rescue SystemCallError => e
+        raise Disconnected, "#{@path}: #{e.message}"
+      end
+
+      def discard_input
+        loop { break if read(4096, 0).empty? }
+      end
+
+      def close
+        @io.close unless @io.closed?
+      end
+    end
+
+    # A COM port on Windows, through kernel32 with Fiddle.
+    class WindowsPort
+      GENERIC_READ_WRITE = 0xC0000000
+      OPEN_EXISTING = 3
+      MAXDWORD = 0xFFFFFFFF
+      SETRTS = 3
+      CLRRTS = 4
+      SETDTR = 5
+      CLRDTR = 6
+      PURGE_RXCLEAR = 0x0008
+
+      def self.kernel32
+        @kernel32 ||= begin
+          require "fiddle/import"
+          Module.new do
+            extend Fiddle::Importer
+            dlload "kernel32.dll"
+            extern "void* CreateFileW(void*, unsigned long, unsigned long, void*, unsigned long, unsigned long, void*)"
+            extern "int GetCommState(void*, void*)"
+            extern "int SetCommState(void*, void*)"
+            extern "int SetCommTimeouts(void*, void*)"
+            extern "int ReadFile(void*, void*, unsigned long, void*, void*)"
+            extern "int WriteFile(void*, void*, unsigned long, void*, void*)"
+            extern "int EscapeCommFunction(void*, unsigned long)"
+            extern "int PurgeComm(void*, unsigned long)"
+            extern "int CloseHandle(void*)"
+            extern "unsigned long GetLastError()"
+          end
+        end
+      end
+
+      def self.list
+        require "win32/registry"
+        Win32::Registry::HKEY_LOCAL_MACHINE.open('HARDWARE\DEVICEMAP\SERIALCOMM') do |key|
+          key.map { |_name, _type, value| value }.sort_by { |name| name[/\d+/].to_i }
+        end
+      rescue LoadError, StandardError
+        []
+      end
+
+      attr_reader :path
+
+      def initialize(path, baud)
+        @path = path
+        @k = self.class.kernel32
+        name = path.start_with?("\\\\.\\") ? path : "\\\\.\\#{path}"
+        @handle = @k.CreateFileW("#{name}\0".encode("UTF-16LE"), GENERIC_READ_WRITE, 0, nil, OPEN_EXISTING, 0, nil)
+        if @handle.to_i == (1 << (8 * Fiddle::SIZEOF_VOIDP)) - 1 || @handle.to_i == -1
+          raise Error, "Cannot open #{path} (error #{@k.GetLastError})"
+        end
+
+        @dtr = @rts = false
+        @read_timeout = nil
+        self.baud = baud
+      end
+
+      def resettable? = true
+      def usb_jtag_serial? = nil
+
+      # The DCB also carries the DTR/RTS state, so a baud change keeps the lines as they are.
+      def baud=(baud)
+        @baud = baud
+        dcb = "\0".b * 28
+        dcb[0, 4] = [28].pack("V")
+        check(@k.GetCommState(@handle, dcb), "GetCommState")
+        flags = 0x0001 # fBinary; no parity check, no flow control
+        flags |= 0x0010 if @dtr # fDtrControl = DTR_CONTROL_ENABLE
+        flags |= 0x1000 if @rts # fRtsControl = RTS_CONTROL_ENABLE
+        dcb[4, 4] = [baud].pack("V")
+        dcb[8, 4] = [flags].pack("V")
+        dcb[18, 3] = [8, 0, 0].pack("C3") # 8 data bits, no parity, 1 stop bit
+        check(@k.SetCommState(@handle, dcb), "SetCommState")
+      end
+
+      def read(max, timeout)
+        ms = (timeout * 1000).ceil
+        if @read_timeout != ms
+          # Return as soon as any byte is there, or after +ms+ when nothing comes.
+          timeouts = ms.zero? ? [MAXDWORD, 0, 0, 0, 0] : [MAXDWORD, MAXDWORD, ms, 0, 0]
+          check(@k.SetCommTimeouts(@handle, timeouts.pack("V5")), "SetCommTimeouts")
+          @read_timeout = ms
+        end
+        buf = "\0".b * max
+        count = [0].pack("V")
+        raise Disconnected, "#{@path}: ReadFile failed" if @k.ReadFile(@handle, buf, max, count, nil).zero?
+
+        buf.byteslice(0, count.unpack1("V"))
+      end
+
+      def write(bytes)
+        bytes = bytes.b
+        until bytes.empty?
+          count = [0].pack("V")
+          raise Disconnected, "#{@path}: WriteFile failed" if @k.WriteFile(@handle, bytes, bytes.bytesize, count, nil).zero?
+
+          bytes = bytes.byteslice(count.unpack1("V")..)
+        end
+      end
+
+      # DTR first: usbser.sys only passes a DTR change on together with the next RTS one.
+      def set_lines(dtr: nil, rts: nil)
+        unless dtr.nil?
+          @dtr = dtr
+          @k.EscapeCommFunction(@handle, dtr ? SETDTR : CLRDTR)
+        end
+        return if rts.nil? && dtr.nil?
+
+        @rts = rts unless rts.nil?
+        @k.EscapeCommFunction(@handle, @rts ? SETRTS : CLRRTS)
+      end
+
+      def discard_input
+        @k.PurgeComm(@handle, PURGE_RXCLEAR)
+      end
+
+      def close
+        @k.CloseHandle(@handle) if @handle
+        @handle = nil
+      end
+
+      private
+
+      def check(result, what)
+        raise Error, "#{what} failed on #{@path} (error #{@k.GetLastError})" if result.zero?
+      end
+    end
+  end
+end