콘텐츠로 이동

여러 카드의 펌웨어를 차례로 업데이트하기

호스트에 꽂힌 LPU를 모두 같은 펌웨어 이미지로 업데이트합니다. 예제 스크립트가 카드를 한 장씩 차례로 ha-fw-update로 업데이트하며 결과를 기록하고, 어느 카드든 정상적으로 끝나지 않으면 다음 카드를 시작하지 않고 멈춥니다. 카드 한 장을 업데이트하는 절차, 업데이트 중의 제약, 안전 규칙은 펌웨어 업데이트에 있으며, 이 페이지는 그 절차를 여러 장에 차례로 적용하는 방법만 다룹니다. 호스트의 root 권한과 드라이버 패키지에 들어 있는 ha-fw-update, ha-hotreset(설치 위치)이 필요합니다. 예에서는 카드 세 장(0000:01:00.0, 0000:41:00.0, 0000:81:00.0)을 펌웨어 1.0.5에서 1.0.6으로 올립니다. 주소, 버전, 이미지 이름은 실제 값으로 바꾸어 읽으십시오.


시작하기 전에

  1. 새 펌웨어가 드라이버와 맞는지 확인합니다. 지원 환경에서 새 펌웨어와 설치한 드라이버의 조합을 확인합니다. 지금 실행 중인 펌웨어가 명령 프로토콜 v7 미만인 카드는 ha-fw-update로 업데이트할 수 없습니다.
  2. 업데이트할 카드를 쓰는 워크로드를 모두 멈춥니다. 어떤 카드의 /dev/haN을 연 프로세스가 있으면 그 카드의 업데이트가 종료 코드 2로 끝나고, 스크립트도 거기서 멈춥니다. hyperaccel-smi처럼 sysfs만 읽는 모니터링은 그대로 두어도 됩니다. 일부 카드만 업데이트한다면 다른 카드에서 그 카드들과 데이터를 주고받는 작업도 멈춥니다(한 카드를 리셋하거나 제거할 때).
  3. 카드마다 핫 리셋할 수 있는지 확인합니다. sudo ha-hotreset --list에서 NOT resettable로 표시되는 카드가 있으면, 스크립트를 실행할 때 나머지 카드의 PCI 주소만 적어 그 카드를 빼십시오. 주소를 적지 않으면 등록된 카드를 모두 업데이트합니다. 뺀 카드는 리셋을 나중에 하기의 방법대로 따로 업데이트합니다. the path is masked for the reset으로 표시되는 카드는 리셋하는 동안 경로를 마스킹하고 리셋합니다. 이런 카드가 있는 플랫폼을 처음 쓴다면 시작하기 전에 sudo ha-hotreset --check-mask --bdf <PCI 주소>로 마스킹이 유지되는지 확인하십시오. 오류를 다른 경로로 감시하는 플랫폼에서는 마스킹해도 그 카드를 리셋할 때 호스트 전체가 재시작될 수 있습니다(경로 마스킹). --list는 부모 포트만 판정하므로, 같은 부모 브리지 아래에 다른 디바이스가 있는 카드는 쓰기를 마친 뒤 리셋이 거부되어 종료 코드 5로 멈춥니다.
  4. 모든 카드가 끝날 때까지 호스트를 그대로 둡니다. 업데이트하는 동안 호스트 전원을 끄거나 재부팅하지 않습니다. 원격 세션이면 tmux나 screen 안에서 실행합니다. 안전 규칙을 먼저 읽으십시오.
  5. 지금 버전을 기록합니다. 스크립트의 -n이 카드마다 PCI 주소, 노드, 펌웨어 버전을 출력합니다(1. 대상 카드를 확인합니다).

스크립트는 드라이버에 등록된 카드, 즉 /dev/haN이 있는 카드만 다룹니다. 장착한 카드가 모두 등록되었는지 lspci -D -d 20fb:의 카드 수와 비교하십시오. 번호와 등록에 관한 규칙은 카드 번호에 있습니다.


스크립트

  • 카드를 PCI 주소로 가리킵니다. 주소를 주지 않으면 /sys/class/ha/haN/device 링크가 가리키는 PCI 주소로 등록된 카드를 모두 고릅니다. /dev/haN 번호는 카드의 신원이 아니므로 쓰지 않습니다(카드 번호).
  • 카드마다 ha-fw-update -d <PCI 주소> -y --json IMAGE를 실행하고, 결과 JSON을 결과 디렉터리의 <PCI 주소>.json에 저장합니다. 핫 리셋과 새 펌웨어 확인은 ha-fw-update가 합니다. 스크립트는 카드를 직접 리셋하지 않고 --force도 쓰지 않습니다.
  • ha-fw-update의 종료 코드가 0이 아니면 멈추고, 그 카드에 할 일과 이어서 실행할 명령을 출력합니다. 결과 JSON의 exit_code가 종료 코드와 다르면, 즉 ha-fw-update가 결과를 남기지 못하고 끝났으면 그 카드의 결과를 unknown으로 표시하고 종료 코드 4와 같이 안내합니다.
  • Ctrl+C, SIGTERM, SIGHUP을 받으면 진행 중인 카드의 ha-fw-update가 끝나기를 기다린 뒤 멈춥니다. 다음 카드는 시작하지 않습니다.
  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
#!/bin/sh
# ha-fw-update-all.sh: 카드를 한 장씩 같은 펌웨어 이미지로 업데이트하고, 첫 문제에서 멈춥니다.
# 사용법: sh ha-fw-update-all.sh [-n] IMAGE [BDF...]
#   -n   카드와 지금의 펌웨어 버전만 보여 주고 아무것도 쓰지 않습니다
#   BDF  업데이트할 카드의 PCI 주소(예: 0000:01:00.0). 생략하면 드라이버에 등록된 카드 전부
# 종료 코드: 0 모든 카드 성공, 1 멈춤 또는 오류, 2 잘못된 사용법
# 환경 변수: LOGDIR(카드별 결과 JSON을 둘 디렉터리), SYSFS(sysfs 경로, 기본 /sys)
set -u
SYSFS=${SYSFS:-/sys}

die() { echo "ERROR: $*" >&2; exit 1; }
row() { printf '%-14s %-9s %-9s %s\n' "$1" "$2" "$3" "$4"; }

# 등록된 카드마다 "PCI주소 노드 펌웨어버전" 한 줄을 냅니다.
cards() {
    for d in "$SYSFS"/class/ha/ha*; do
        [ -e "$d/device" ] || continue
        pci=$(basename "$(readlink -f "$d/device")")
        echo "$pci ${d##*/} $(cat "$d/fw_version" 2>/dev/null || echo unknown)"
    done
}

# 그 PCI 주소에 있는 카드의 지금 펌웨어 버전을 냅니다. 등록된 카드가 아니면 -입니다.
fwver() {
    cards | awk -v b="$1" '$1 == b { v = $3 } END { print (v == "" ? "-" : v) }'
}

dry=0
[ "${1:-}" = -n ] && dry=1 && shift
[ $# -ge 1 ] || { echo "usage: $0 [-n] IMAGE [BDF...]" >&2; exit 2; }
image=$1
shift
[ -f "$image" ] || die "$image: no such file"
if [ $# -eq 0 ]; then
    while read -r b _; do [ -n "$b" ] && set -- "$@" "$b"; done <<EOF
$(cards)
EOF
fi
[ $# -gt 0 ] || die "no card is registered in $SYSFS/class/ha"
for b in "$@"; do
    [ "$(fwver "$b")" != - ] || die "$b is not a registered card (list them with: sh $0 -n $image)"
done

if [ "$dry" = 1 ]; then
    printf '%-14s %-5s %s\n' BDF NODE FIRMWARE
    for b in "$@"; do
        cards | awk -v b="$b" '$1 == b { printf "%-14s %-5s %s\n", $1, $2, $3 }'
    done
    echo "dry run: nothing written; $# card(s) would be updated with $image"
    exit 0
fi

command -v ha-fw-update >/dev/null || die "ha-fw-update not found in PATH"
log=${LOGDIR:-ha-fw-update-$(date +%Y%m%d-%H%M%S)}
mkdir -p "$log" || die "cannot create $log"

# Ctrl+C 등을 받으면 진행 중인 ha-fw-update가 끝나기를 기다리고, 다음 카드는 시작하지 않습니다.
stop=0
trap 'stop=1' INT TERM HUP
total=$#
rc=0
table=$(row BDF BEFORE AFTER RESULT)
while [ $# -gt 0 ]; do
    before=$(fwver "$1")
    [ "$stop" = 0 ] || break
    bdf=$1
    shift
    echo "[$((total - $#))/$total] $bdf: firmware $before, updating"
    ha-fw-update -d "$bdf" -y --json "$image" >"$log/$bdf.json"
    st=$?
    rc=$st res="exit $st"
    # 끝까지 실행된 ha-fw-update만 종료 코드와 같은 exit_code를 JSON에 남깁니다. 아니면 상태를 모릅니다.
    grep -q "\"exit_code\": $st," "$log/$bdf.json" || { rc=unknown; res=unknown; }
    table="$table
$(row "$bdf" "$before" "$(fwver "$bdf")" "$res")"
    [ "$rc" = 0 ] || break
done
echo
echo "$table"
for b in "$@"; do row "$b" "$(fwver "$b")" - "not run"; done
echo "results: $log/"
[ "$rc" = 0 ] && [ $# -eq 0 ] && exit 0
echo
[ "$rc" = 0 ] || sed -n 's/^  "error": "\(.*\)",$/\1/p' "$log/$bdf.json" | awk '{ gsub(/\\n/, "\n       "); gsub(/\\"/, "\""); print "ERROR: " $0 }'
case $rc in
    0) echo "Stopped on request." ;;
    1|2|3)
        echo "$bdf: exit $rc. This run did not change its flash. Fix the cause, then resume."
        set -- "$bdf" "$@" ;;
    5)
        echo "$bdf: exit 5. Its flash holds the new image, but the card was not reset."
        echo "Fix the cause, then run 'ha-hotreset --bdf $bdf' or power cycle the host." ;;
    6)
        echo "$bdf: exit 6. Its flash holds the new image and the card was reset,"
        echo "but the version check did not finish. Check it with: sh $0 -n $image" ;;
    *)
        echo "$bdf: exit status $st. Its flash may be partially written."
        echo "Do NOT reboot the host or reset the card. Update this card again; if dmesg shows"
        echo "'fw_update: no answer from firmware', first wait for 'late completion from firmware'."
        set -- "$bdf" "$@" ;;
esac
[ $# -eq 0 ] || echo "Resume with: sudo sh $0 $image $*"
exit 1
환경 변수 기본값 뜻
LOGDIR 현재 디렉터리의 ha-fw-update-<날짜>-<시각> 카드별 결과 JSON을 저장할 디렉터리입니다(예: sudo env LOGDIR=/var/tmp/fw-update sh ha-fw-update-all.sh image.gpt)
SYSFS /sys 카드 목록과 fw_version을 읽을 sysfs 경로입니다. 호스트의 /sys가 다른 경로에 마운트되어 있을 때 바꿉니다. ha-fw-update는 이 값과 관계없이 /sys를 읽습니다

실행하기

1. 대상 카드를 확인합니다

-n은 카드와 지금의 펌웨어 버전만 출력하고 ha-fw-update를 실행하지 않습니다. sysfs만 읽으므로 root 권한이 없어도 됩니다.

1
sh ha-fw-update-all.sh -n image.gpt
1
2
3
4
5
BDF            NODE  FIRMWARE
0000:01:00.0   ha0   1.0.5
0000:41:00.0   ha1   1.0.5
0000:81:00.0   ha2   1.0.5
dry run: nothing written; 3 card(s) would be updated with image.gpt
  • 일부 카드만 업데이트하려면 이미지 뒤에 PCI 주소를 도메인까지 포함한 형식으로 적습니다. 적은 순서대로 업데이트합니다.
  • 적은 주소 가운데 등록된 카드가 아닌 것이 있으면 ERROR: <주소> is not a registered card를 출력하고, 어느 카드도 업데이트하지 않습니다.
  • 카드마다 ha-fw-update의 사전 점검까지 해 보려면 sudo ha-fw-update -d <PCI 주소> --dry-run image.gpt를 카드마다 실행합니다. 스크립트에는 이 옵션이 없습니다. 사전 점검을 합니다를 보십시오.

2. 업데이트합니다

1
sudo sh ha-fw-update-all.sh image.gpt

스크립트는 ha-fw-update의 확인 프롬프트를 건너뛰고, 도구가 업데이트 전에 출력하는 요약과 경고도 보여 주지 않습니다. 시작하기 전에를 모두 확인한 뒤 실행하십시오. 모든 카드가 성공하면 다음과 같이 출력하고 종료 코드 0으로 끝납니다.

1
2
3
4
5
6
7
8
9
[1/3] 0000:01:00.0: firmware 1.0.5, updating
[2/3] 0000:41:00.0: firmware 1.0.5, updating
[3/3] 0000:81:00.0: firmware 1.0.5, updating

BDF            BEFORE    AFTER     RESULT
0000:01:00.0   1.0.5     1.0.6     exit 0
0000:41:00.0   1.0.5     1.0.6     exit 0
0000:81:00.0   1.0.5     1.0.6     exit 0
results: ha-fw-update-20261008-101500/
  • [n/전체] 줄은 그 카드의 업데이트를 시작할 때 출력됩니다. 카드 한 장이 끝날 때까지 진행률은 출력되지 않습니다. 진행률은 다른 터미널에서 그 카드의 fw_update_progress로 봅니다(예: cat /sys/class/ha/ha1/fw_update_progress).
  • BEFORE와 AFTER는 그 카드의 ha-fw-update 실행 직전과 직후에 읽은 fw_version입니다(not run인 카드의 BEFORE는 지금 값, 등록되지 않은 카드는 -). RESULT는 ha-fw-update의 종료 코드(exit N), 결과를 확인할 수 없음(unknown), 실행하지 않음(not run) 가운데 하나입니다.
  • 결과 디렉터리에는 카드마다 ha-fw-update의 결과 JSON이 남습니다. result, exit_code, error, fw_version_before, fw_version_after 같은 필드의 뜻은 JSON 출력에 있습니다.

끝난 뒤 확인하기

sh ha-fw-update-all.sh -n image.gpt를 다시 실행하거나 hyperaccel-smi -q의 Firmware Version으로 모든 카드가 새 버전을 보고하는지 확인합니다.

  • 업데이트 전과 버전 번호가 같은 이미지를 썼다면 AFTER가 BEFORE와 같아도 성공입니다. 이때 결과 JSON의 version_changed는 false이며(grep '"version_changed"' ha-fw-update-20261008-101500/*.json), 버전 번호로는 새 이미지를 구분할 수 없습니다. 새 펌웨어로 부팅되었는지 확인을 보십시오.
  • fw_version이 unknown인 카드는 아직 부팅 중이거나 펌웨어가 준비되지 않은 것입니다. 잠시 뒤 다시 확인하고, 계속되면 카드가 돌아오지 않을 때를 따릅니다.
  • 확인이 끝나면 멈춘 워크로드를 다시 시작합니다. 핫 리셋으로 호스트의 노드가 새로 만들어지므로, 업데이트한 카드를 쓰던 컨테이너는 다시 시작합니다.

중간에 멈췄을 때

어느 카드든 ha-fw-update가 0이 아닌 종료 코드로 끝나면 스크립트는 다음 카드를 시작하지 않습니다. 요약 표 아래에 그 카드의 오류 메시지(ERROR: 줄), 할 일, 이어서 실행할 명령(Resume with: 줄)을 출력하고 종료 코드 1로 끝납니다. 다음은 두 번째 카드가 종료 코드 4로 끝난 예입니다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
[1/3] 0000:01:00.0: firmware 1.0.5, updating
[2/3] 0000:41:00.0: firmware 1.0.5, updating

BDF            BEFORE    AFTER     RESULT
0000:01:00.0   1.0.5     1.0.6     exit 0
0000:41:00.0   1.0.5     1.0.5     exit 4
0000:81:00.0   1.0.5     -         not run
results: ha-fw-update-20261008-101500/

ERROR: firmware did not answer within the budget -- state unknown, do NOT reboot; retry, then use a debug tool (e.g., Trace32)
0000:41:00.0: exit status 4. Its flash may be partially written.
Do NOT reboot the host or reset the card. Update this card again; if dmesg shows
'fw_update: no answer from firmware', first wait for 'late completion from firmware'.
Resume with: sudo sh ha-fw-update-all.sh image.gpt 0000:41:00.0 0000:81:00.0

ERROR: 줄은 ha-fw-update가 남긴 오류 메시지를 그대로 옮긴 것입니다. 메시지에 나오는 디버그 도구는 JTAG 디버거를 이용한 복구를 뜻하며, 호스트 소프트웨어로는 복구할 수 없는 상태를 가리킵니다. 직접 시도하지 말고 아래 표의 할 일을 따르십시오. 그래도 복구되지 않으면 HyperAccel에 문의하십시오.

멈춘 카드의 RESULT에 따라 다음과 같이 합니다. 종료 코드의 정의는 종료 코드에 있습니다.

RESULT 그 카드의 플래시 할 일
exit 1, exit 2, exit 3 이 실행으로는 바뀌지 않음 ERROR: 줄의 원인을 고친 뒤 Resume with: 명령을 실행합니다. 메시지별 조치는 쓰기 전에 끝났을 때에 있습니다
exit 4, unknown 일부만 기록되었을 수 있음 카드를 리셋하거나 호스트를 재부팅하지 말고 종료 코드 4이면을 따릅니다
exit 5 새 이미지. 카드는 리셋되지 않음 리셋하지 못했을 때의 안내대로 원인을 고친 뒤 sudo ha-hotreset --bdf <PCI 주소>를 실행하거나 호스트 전원을 껐다 켭니다. 그다음 Resume with: 명령으로 남은 카드를 업데이트합니다
exit 6 새 이미지. 카드는 리셋됨 카드가 돌아오지 않을 때의 안내대로 확인합니다. 그 카드가 새 버전을 보고하면 Resume with: 명령으로 남은 카드를 업데이트합니다
  • unknown은 ha-fw-update가 결과를 남기지 못하고 끝난 경우입니다(시그널로 종료되었거나 Python 오류로 중단된 경우). 그 실행이 플래시를 어디까지 썼는지 알 수 없으므로 종료 코드 4와 같이 다룹니다.
  • Resume with: 명령은 아직 실행하지 않은 카드를 원래 순서대로 넘깁니다. 종료 코드 1~4와 unknown이면 멈춘 카드를 맨 앞에 다시 넣고, 종료 코드 5와 6이면 넣지 않습니다. 이미 성공한 카드는 다시 업데이트하지 않습니다.
  • Ctrl+C는 스크립트와 함께 진행 중인 ha-fw-update에도 전달됩니다. 그 카드의 쓰기가 시작되기 전이면 도구가 종료 코드 1로 끝나 플래시가 바뀌지 않고, 쓰기가 시작된 뒤면 쓰기와 리셋을 마친 뒤 종료 코드 6으로 끝납니다(리셋에 실패하면 5). 스크립트는 그 종료 코드에 맞는 안내를 출력합니다. 카드와 카드 사이에서 멈췄거나 진행 중인 카드가 성공으로 끝났으면 Stopped on request.를 출력합니다.

종료 코드 4이면

호스트가 펌웨어의 응답을 받지 못했으면 커널 로그에 첫째 줄이 남습니다. 그 뒤 펌웨어가 늦게라도 응답하면 둘째 줄이 남습니다.

1
2
ha 0000:41:00.0: fw_update: no answer from firmware (<오류 번호>); resets stay refused until it answers or the update is retried
ha 0000:41:00.0: fw_update: late completion from firmware; resets re-enabled
  1. 호스트 전원을 끄거나 재부팅하지 마십시오. ha-hotreset이나 애플리케이션의 리셋으로 그 카드를 리셋하지도 마십시오. 카드를 다시 시작하지 않는 한 일부만 기록된 플래시로 부팅하는 일은 없습니다.
  2. sudo dmesg에 그 카드의 첫째 줄이 있으면 둘째 줄이 남을 때까지 기다립니다. 그동안 드라이버는 그 카드에 명령을 보내는 요청과 애플리케이션의 리셋 요청을 거부하고, ha-fw-update가 이미지를 올리는 것도 거부합니다. 그래서 그 전에 다시 실행하면 그 카드는 upload failed: Device or resource busy와 함께 종료 코드 2로 끝나고, 플래시는 바뀌지 않습니다.
  3. Resume with: 명령을 실행합니다. 그 카드를 같은 이미지로 다시 업데이트하고(플래시와 내용이 다른 부분만 다시 씁니다), 성공하면 남은 카드로 넘어갑니다.
  4. 다시 실패하거나 펌웨어가 끝내 응답하지 않으면 카드를 리셋하지 말고 HyperAccel에 문의하십시오. 결과 디렉터리의 JSON, sudo dmesg, hyperaccel-smi -q의 출력을 함께 보내십시오. 배경은 응답을 받지 못했을 때에 있습니다.

함께 보기