usb-gadget.sh.j2

#!/usr/bin/env bash
# USB Gadget: https://www.kernel.org/doc/html/latest/usb/index.html

SCRIPT_DIR="$(cd "$(dirname "$(readlink -f "${BASH_SOURCE[0]}" || true)")" >/dev/null 2>&1 && pwd)"

# shellcheck source=./../../pihero/files/lib/lib.bash
. "$SCRIPT_DIR/lib/lib.bash"

shopt -s nullglob
declare -r gadget_name=pihero
declare -r config_name=c.1
declare -r instance_name=usb0

CONFIGFS_HOME=$(findmnt --output TARGET --noheadings configfs) || die '%s: not found' configfs
declare -r gadget_dir="$CONFIGFS_HOME/usb_gadget/$gadget_name"

start_gadget() {
  printf "\e[1mStarting USB gadget \e[3m%s\e[23m...\e[0m\n" "$gadget_name"

  create_gadget
  create_config

  {% set feature_mappings = { "ethernet": "ecm", "serial": "acm" } %}

  local -a post_scripts=()

  {% for feature_name, function_parameters in usb_gadget_features.items() %}
    {% set function_name = feature_mappings[feature_name] if feature_name in feature_mappings else feature_name %}
    ### BEGIN {{ function_name }} ###

    post_script=$(mktemp)
    {% if function_parameters is none %}
    create_function '{{ function_name }}' "$instance_name" >"$post_script"
    {% else %}
    create_function '{{ function_name }}' "$instance_name" "$(printf %s '{{ function_parameters | b64encode }}' | base64 --decode)" >"$post_script"
    {% endif %}
    if [ $? -eq 0 ]; then
      post_scripts+=('{{ function_name }}' "$instance_name" "$post_script")
      ln -s "functions/{{ function_name }}.$instance_name" "configs/$config_name/"
    else
      rm "$post_script"
      printf "\e[31mERROR: The function \e[3m%s.%s\e[23m failed to create. It won't be associated with configuration \e[3m%s\e[23m.\e[0m\n" \
        '{{ function_name }}' "$instance_name" "$config_name" >&2
      local indent='    '
      local state=$(ls -1lAFhctR "functions/{{ function_name }}.$instance_name" | tail -n +2 | sed 's/^/'"$indent"'/')
      printf "This is what \e[3m%s\e[23m looked like:\n%sDirectory %s\n%s\n" \
        "functions/{{ function_name }}.$instance_name" \
        "$indent" \
        "$PWD/functions/{{ function_name }}.$instance_name" \
        "${state:-$(printf '%s\e[3m%s\e[23m' "$indent" empty)}" >&2
    fi

    ### END {{ function_name }} ###
  {% endfor %}

  # watch the udev event queue until all current events are handled
  # but no longer than 5 seconds
  udevadm settle -t 5 || :

  bind_gadget

  # Post scripts
  {% raw %}
  while (( ${#post_scripts[@]} > 0 )); do
    printf "Running post script for function \e[3m%s.%s\e[23m...\n" "${post_scripts[0]}" "${post_scripts[1]}"
    local exit_code
    bash "${post_scripts[2]}"
    exit_code=$?
    if [ $exit_code -eq 0 ]; then
      printf "Post script for function \e[3m%s.%s\e[23m completed successfully.\n" "${post_scripts[0]}" "${post_scripts[1]}"
      rm "${post_scripts[2]}"
    else
      printf "\e[31mERROR: Post script \e[3m%s\e[23m for function \e[3m%s.%s\e[23m terminated with exit code \e[3m%d\e[23m.\e[0m\n" \
        "${post_scripts[2]}" "${post_scripts[0]}" "${post_scripts[1]}" "$exit_code" >&2
    fi
    post_scripts=("${post_scripts[@]:3}")
  done
  {% endraw %}

  printf "\e[1mStarted USB gadget \e[3m%s\e[23m.\e[0m\n" "$gadget_name"
}

# see https://www.kernel.org/doc/html/latest/usb/gadget_configfs.html#creating-the-gadgets
create_gadget() {
  printf "\e[1mCreating gadget \e[3m%s\e[23m...\e[0m\n" "$gadget_name"

  mkdir -p "$gadget_dir" || die '%s: directory creation failed' "$gadget_dir"
  cd "$gadget_dir" || die '%s: directory change failed' "$gadget_dir"

  echo '0x1d6b' >idVendor  # The Linux Foundation,
                           # see https://www.usb.org/sites/default/files/usb_vids_080223.pdf
                           # in "Vendor ID (Decimal Format)" column (0x1d6b = 7523)
  echo '0x0104' >idProduct # Multifunction Composite Gadget,
                           # see https://devicehunt.com/view/type/usb/vendor/1D6B/device/0104
  echo '0x0100' >bcdDevice # v1.0.0
  echo '0x0200' >bcdUSB    # USB2
  echo '0xef' >bDeviceClass
  echo '0x02' >bDeviceSubClass
  echo '0x01' >bDeviceProtocol

  mkdir -p strings/0x409
  echo '{{ usb_gadget.manufacturer }}' >strings/0x409/manufacturer
  echo '{{ usb_gadget.product }}' >strings/0x409/product
  echo '{{ usb_gadget.serialnumber }}' >strings/0x409/serialnumber
}

# see https://www.kernel.org/doc/html/latest/usb/gadget_configfs.html#creating-the-configurations
create_config() {
  printf "\e[1mCreating configuration \e[3m%s\e[23m...\e[0m\n" "$config_name"

  case $config_name in
  *.*)
    mkdir -p "configs/$config_name"
    mkdir -p "configs/$config_name"/strings/0x409
    echo 'USB gadget features: {% if usb_gadget_features.keys() %}{{ usb_gadget_features.keys() | join(', ') }}{% else %}-{% endif %}' >"configs/$config_name"/strings/0x409/configuration
    case "$(cat /sys/firmware/devicetree/base/model | tr --delete '[:cntrl:]')" in
    Raspberry\ Pi\ 4*)
      echo '500'
      ;;
    Raspberry\ Pi\ Zero\ 2*)
      echo '200'
      ;;
    *)
      echo '100'
      ;;
    esac >configs/c.1/MaxPower
    ;;
  *)
      die '%s: configuration name not matching <name>.<number>' "$config_name"
    ;;
  esac
}

# see https://www.kernel.org/doc/html/latest/usb/gadget_configfs.html#creating-the-functions
create_function() {
  local -r function_name=${1:?function name missing}
  local -r function="$function_name.$instance_name"

  printf "\e[1mCreating function \e[3m%s\e[23m...\e[0m\n" "$function" >&2

  mkdir -p "functions/$function"

  case $function_name in
  acm)
    # see https://www.kernel.org/doc/html/latest/usb/gadget-testing.html#acm-function

    port_num_file="$PWD/functions/$function/port_num"
    echo 'if [ -f "'$port_num_file'" ]; then
        N="$(<"'$port_num_file'")"
        systemctl start "serial-getty@ttyGS${N}.service" &
    fi'
    ;;
  ecm)
    # Ethernet Control Model (ECM): ethernet over USB protocol by the USB Implementers Forum
    # see https://www.kernel.org/doc/html/latest/usb/gadget-testing.html#ecm-function
    # see https://en.wikipedia.org/wiki/Ethernet_over_USB
    {% if usb_gadget_features.ethernet.device_mac is defined %}
    echo '{{ usb_gadget_features.ethernet.device_mac }}' >"functions/$function"/dev_addr
    {% endif %}
    {% if usb_gadget_features.ethernet.host_mac is defined %}
    echo '{{ usb_gadget_features.ethernet.host_mac }}' >"functions/$function"/host_addr
    {% endif %}

    ifname_file="$PWD/functions/$function/ifname"
    echo 'usb%d'   > "$ifname_file"
    echo 'if [ -f "'$ifname_file'" ]; then
        N="$(<"'$ifname_file'")"
        ifconfig "$N" {{ usb0_cidr_address }} netmask {{ usb0_cidr_netmask }}
    fi'
    ;;
  rndis)
    # Remote NDIS (RNDIS): proprietary ethernet over USB protocol by Microsoft
    # see https://en.wikipedia.org/wiki/RNDIS
    # see https://en.wikipedia.org/wiki/Ethernet_over_USB
    # TODO test (on Windows)
    echo RNDIS     >"functions/$function"/os_desc/interface.rndis/compatible_id
    echo 5162001   >"functions/$function"/os_desc/interface.rndis/sub_compatible_id

    ln -s "$gadget_dir"/configs/c.1 "$gadget_dir"/os_desc
    echo "0xcd"    > "$gadget_dir"/os_desc/b_vendor_code
    echo "MSFT100" > "$gadget_dir"/os_desc/qw_sign
    echo "1"       > "$gadget_dir"/os_desc/use

    ifname_file="$PWD/functions/$function/ifname"
    echo 'usb%d'   > "$ifname_file"
    echo 'if [ -f "'$ifname_file'" ]; then
        N="$(<"'$ifname_file'")"
        ifconfig "$N" {{ usb0_cidr_address }} netmask {{ usb0_cidr_netmask }}
    fi'
    ;;
  *)
    printf "\e[1mDelegating creation of function \e[3m%s\e[23m to \e[3m%s\e[23m...\e[0m\n" "$function" 'usb-gadget-custom'
    ({{ package_dir }}/usb-gadget-custom create_custom_function "$@")
    ;;
  esac
}

bind_gadget() {
  printf "Binding gadget in \e[3m%s\e[23m... " "$PWD"
  if [ "$(<"$gadget_dir"/UDC)" ]; then
    printf "\e[33mWARNING: Gadget in \e[3m%s\e[23m is already bound.\e[0m\n" "$PWD"
  else
    ls /sys/class/udc >UDC
    printf "\e[32;1m✔\e[0m\n"
  fi
}

unbind_gadget() {
  printf "Unbinding gadget in \e[3m%s\e[23m... " "$PWD"
  if [ "$(<"$gadget_dir"/UDC)" ]; then
    echo '' >UDC
    printf "\e[32;1m✔\e[0m\n"
  else
    printf "\e[33mWARNING: No bound gadget found in \e[3m%s\e[23m.\e[0m\n" "$PWD"
  fi
}

# see https://www.kernel.org/doc/html/latest/usb/gadget_configfs.html#cleaning-up
stop_gadget() {

  printf "\e[1mStopping USB gadget \e[3m%s\e[23m...\e[0m\n" "$gadget_name"

  [ -d "$gadget_dir" ] || die '%s: gadget already stopped' "$gadget_name"

  printf "\e[1mStopping serial devices...\e[0m\n"
  while IFS= read -r -d '' f; do
    if [ -f "$f/port_num" ]; then
      N="$(<"$f/port_num")"
      systemctl stop "serial-getty@ttyGS${N}.service" || true
    fi
  done < <(find "$gadget_dir/functions" -type "d" -name "acm.*" -print0)

  # Unbind
  (cd "$gadget_dir" && unbind_gadget)

  printf "\e[1mRemoving functions from configurations...\e[0m\n"
  for c in "$gadget_dir"/configs/*.*; do # configs/c.1
    for f in "$c"/*.*; do # configs/c.1/acm.0
      [ -h "$f" ] || continue
      printf "Removing function \e[3m%s\e[23m from configuration \e[3m%s\e[23m.\e[0m\n" "${f##*/}" "${c##*/}"
      rm -f "$f"
    done
  done

  printf "\e[1mRemoving os_desc configurations...\e[0m\n"
  for c in "$gadget_dir"/os_desc/*.*; do # os_desc/c.1
    [ -h "$c" ] || continue
    printf "Removing os_desc configuration \e[3m%s\e[23m.\e[0m\n" "${c##*/}"
    rm -f "$c"
  done

  printf "\e[1mRemoving strings directories from configurations...\e[0m\n"
  for c in "$gadget_dir"/configs/*.*; do # configs/c.1
    for strings in "$c"/strings/*; do
      printf "Removing strings directory \e[3m%s\e[23m from configuration \e[3m%s\e[23m.\e[0m\n" "${strings##*/}" "${c##*/}"
      rmdir "$strings"
    done
  done

  printf "\e[1mRemoving configurations...\e[0m\n"
  for c in "$gadget_dir"/configs/*.*; do
    printf "Removing configuration \e[3m%s\e[23m.\e[0m\n" "${c##*/}"
    rmdir "$c"
  done

  printf "\e[1mRemoving functions from the gadget...\e[0m\n"
  for f in "$gadget_dir"/functions/*; do
    printf "Removing function \e[3m%s\e[23m.\e[0m\n" "${f##*/}"
    rmdir "$f"
  done

  printf "\e[1mRemoving strings directories from the gadget...\e[0m\n"
  for strings in "$gadget_dir"/strings/*; do
    printf "Removing strings directory \e[3m%s\e[23m from the gadget.\e[0m\n" "${strings##*/}"
    rmdir "$strings"
  done

  printf "\e[1mRemoving the gadget \e[3m%s\e[23m...\e[0m\n" "$gadget_name"
  rmdir "$gadget_dir"

  printf "\e[1mStopped USB gadget \e[3m%s\e[23m.\e[0m\n" "$gadget"
}

main() {
    while [ $# -gt 0 ]; do
        case $1 in
        --help | -h) usage --arg=command start stop && return 0 ;;
        *) break ;;
        esac
    done

    while [ $# -gt 0 ]; do
        case $1 in
        --) shift && break ;;
        --*) die --code 2 "%s: invalid option" "$1" ;;
        -*) die --code 2 "%s: invalid flag" "$1" ;;
        *) break ;;
        esac
    done

    local command
    if [ $# -gt 0 ]; then
        command=$1 && shift
    else
        "${FUNCNAME[0]}" --help
        die --code 2 'command missing'
    fi

    case $command in
    start) start_gadget "$@" ;;
    stop) stop_gadget "$@" ;;
    *)
        "${FUNCNAME[0]}" --help
        die --code 2 '%s: invalid command' "$command"
        ;;
    esac
}

main "$@"