명령은 한 트리, 접속 경로는 여러 개

1. 백엔드는 바이트를 옮기고 명령 등록은 트리를 만든다

Shell은 여러 인스턴스와 UART·RTT·DUMMY 등 여러 전송 백엔드를 지원한다. 정적 명령은 컴파일할 때 전용 섹션에 등록되며, v3.7.0 문서는 생성된 명령을 모든 셸 인스턴스에서 쓸 수 있다고 명시한다. 따라서 백엔드를 두 개 켠다고 해서 명령 집합이 두 개 정의되는 것은 아니다. Shell 인스턴스가 입력을 편집·파싱해 명령 트리에서 핸들러를 찾고, 출력은 그 인스턴스의 전송 경로로 간다.

근거: 3.7.0 Shell 개요·인스턴스, 명령 등록과 모든 인스턴스에서의 가용성.

2. 가장 깊이 맞는 핸들러가 실행된다

루트와 하위 명령은 트리로 묶인다. v3.7.0 문서는 입력 경로에서 찾은 가장 깊은 핸들러를 실행하고, 더 이상 핸들러가 없는 뒤쪽 토큰을 인자로 넘기는 규칙을 설명한다. 부모에 핸들러가 없고 자식도 못 찾으면 실행할 함수가 없다. 정적 하위 명령의 개수와 이름은 빌드 때 정해진다. 동적 하위 명령은 조회 함수가 현재 항목을 제공하지만, 그것도 해당 루트 아래의 경로를 구성한다.

근거: 3.7.0 가장 깊은 핸들러 규칙, v3.7.0 매크로 인자 계약.

3. 작고 읽을 수 있는 정적 명령부터 만든다

아래는 공식 3.7.0 문서의 정적 명령 구성과 동일한 공개 API를 써서 새로 작성한 최소 예시다. lab는 핸들러가 없는 루트, ping이 실제 응답을 낸다. 이 소스만으로 전송 장치가 준비되지는 않으며 프로젝트에서 CONFIG_SHELL과 적절한 백엔드·보드 입출력을 선택해야 한다.

#include <zephyr/shell/shell.h>
#include <zephyr/sys/util.h>

static int cmd_lab_ping(const struct shell *sh, size_t argc, char **argv)
{
    ARG_UNUSED(argc);
    ARG_UNUSED(argv);
    shell_print(sh, "pong");
    return 0;
}

SHELL_STATIC_SUBCMD_SET_CREATE(sub_lab,
    SHELL_CMD(ping, NULL, "Reply with pong", cmd_lab_ping),
    SHELL_SUBCMD_SET_END
);
SHELL_CMD_REGISTER(lab, &sub_lab, "Lab diagnostics", NULL);

핸들러는 const struct shell *sh를 통해 호출한 인스턴스에 출력한다. argc/argv는 선택된 명령 기준으로 해석해야 하므로 인자를 추가할 때 범위를 검사한다. 예시는 읽기·출력만 수행한다. 명령을 통해 하드웨어 상태를 바꾸려면 입력의 범위, 동시 호출, 권한을 별도로 설계한다.

근거: 3.7.0 공식 demo ping 예시, v3.7.0 사용자 명령 샘플 원본.

4. 동적 명령은 런타임 데이터의 수명도 관리한다

v3.7.0의 동적 하위 명령 예시는 조회 콜백이 idx번째 항목의 syntax, 핸들러, help 등을 채우고, 끝에서는 syntax = NULL을 설정한다. Shell은 이를 탭 완성과 명령 탐색에도 사용한다. 따라서 콜백이 가리키는 문자열의 수명과, 목록이 바뀔 때의 정렬·동기화는 애플리케이션이 책임진다. 데이터가 고정이라면 정적 명령이 더 단순하다.

근거: 3.7.0 동적 명령 예시와 syntax=NULL 종료 규칙, 사전 명령.

5. 프롬프트가 없을 때는 명령보다 백엔드부터 본다

UART는 보드의 실제 콘솔·핀 설정, RTT는 디버거 연결과 채널, DUMMY는 물리 전송 없는 시험 경로라는 서로 다른 전제가 있다. 3.7.0 문서는 USB CDC ACM과 Bluetooth LE NUS를 위한 스니펫도 제시하지만, 이 글에서 다루는 것은 전송 선택이 Shell 인스턴스를 어디에 붙이는지다. CONFIG_SHELL_MINIMAL은 RAM·flash 사용량을 줄이는 기본 선택이므로 필요한 편집·완성 기능을 선택적으로 켜야 한다.

명령 트리와 노출 경로를 함께 검토한다. 명령 등록은 특정 UART에만 묶이지 않는다. 배포 빌드에서 어떤 백엔드를 켜는지와 어떤 진단·변경 명령을 포함하는지가 접근 표면을 결정한다. 네트워크 백엔드를 쓴다면 별도의 접근 제어와 운영 환경도 검토해야 한다. shell_execute_cmd()는 문서상 디버깅·진단용이며 Shell 명령 핸들러 안에서 다시 호출하면 안 된다.

근거: 3.7.0 Shell 백엔드 목록·USB 스니펫·RTT, 최소 구성 안내.

6. 핸들러 출력과 로그 출력은 수명이 다르다

shell_print() 등은 핸들러나 스레드에서 사용할 수 있지만 v3.7.0 문서는 인터럽트 컨텍스트에서 쓰지 말고 Logging을 사용하라고 안내한다. CONFIG_SHELL_LOG_BACKEND를 켜면 Shell 인스턴스가 로거 백엔드 역할을 하며 로그가 큐를 거쳐 셸 스레드에서 처리된다. 큐가 차면 설정된 시간 동안 로거 스레드가 막히거나 오래된 메시지가 제거될 수 있다. shell stats show는 이 경로의 드롭을 조사하는 관측점이다.

근거: 3.7.0 출력 함수의 ISR 제한, Shell 로그 큐·드롭·시작 전 동작.

7. 같은 “안 된다”도 네 경계로 나눈다

핸들러가 오래 막히는 작업을 직접 수행하면 해당 인스턴스의 입력 처리도 지연될 수 있다. 작업을 별도 스레드나 작업 큐로 넘길지는 실행 시간과 동시성 요구를 보고 정한다. Shell을 디버그용 콘솔로 쓸지 제품의 조작 인터페이스로 쓸지도 배포 빌드에서 결정해야 한다.

근거: 명령 선택, 로그 큐.

8. 소스와 확인 범위

Zephyr 릴리스 v3.7.0의 공식 Shell 문서와 같은 태그의 헤더·샘플을 기준으로 썼다. 이 글의 트리·파이프라인·큐 그림은 문서를 복제한 것이 아니라 역할과 실패 경계를 새로 배열한 설명용 도식이다. 특정 보드의 UART/RTT/USB 설정이나 명령의 접근 권한을 실제 장비에서 검증한 것은 아니다.