시스템SW 기술문서와 인터페이스 계약

1. 길이는 8인데 호출자는 왜 3바이트만 받았나

함수 이름과 인자형, 반환형이 적힌 문서를 보고도 구현자는 서로 다른 코드를 만들 수 있다. 반환값 3을 성공으로 보면 요청한 8바이트가 다 들어왔다고 오해할 수 있고, 시간초과를 취소 완료로 해석하면 앞 절처럼 사용 중인 버퍼를 지울 수 있다.

이번 절은 SS-SENSOR의 책임을 호출 계약과 기술문서로 옮긴다. 별도의 학습용 SAMPLE-v1 바이트 형식과 SS-D1/D2 사례를 선언하고 무엇을 확인해야 같은 의미의 구현이 되는지 살핀다. 실제 운영 인터페이스나 특정 Linux ioctl 명령을 구현한 결과는 아니다.

계약은 입력과 반환형보다 넓었다

클라이언트·서버·API에서 API 계약은 입력·출력·상태 변화·오류·권한·시간·버전의 약속이었다. 이번에는 그 약속이 시스템SW의 버퍼·실행 문맥·부분 결과에 어떤 문장으로 나타나야 하는지 적용한다.

회수할 수 있는 상태를 앞 절에서 나눴다

시스템SW 아키텍처와 하드웨어 경계는 요청 대기 종료와 장치 사용 종료를 구분하고 남은 접근이 없을 때 자원을 회수했다. 문서가 그 구분을 빼면 같은 구조 그림을 보고도 서로 다른 해제 시점을 구현할 수 있다.

API·ABI와 부분 입출력은 앞 장의 정의를 따른다

시스템 프로그래밍과 운영체제 인터페이스는 소스 수준 인터페이스와 바이너리 규약, 부분 반환과 자원 수명을 다뤘다. 이번 예는 자료형 이름만 적기보다 바이트 순서·길이·상태의 관찰 의미를 명시한다.

정확한 정의와 담당 경계

시스템SW 기술문서는 구조·인터페이스·자원·실행 문맥·오류와 검증 근거를 판본에 연결하여 구현·운영·변경 담당자가 같은 계약을 따르도록 기록한 문서 체계다.

API·ABI의 일반 개념은 앞서 학습한 호출 계약과 운영체제 인터페이스를, 시스템SW 구조는 앞 절의 책임과 경계를 재사용한다. 이 절은 그 구조를 인수·반환·상태·자원·문맥·시험의 명시 계약으로 문서화하며 자동 문서 생성이나 함수 목록만으로 완료하지 않는다.

구조에서 시험까지 같은 식별자로 잇는다

문서의 호출 이름은 출발점이다. 어떤 조건에서 누구의 자원을 바꾸며 무엇을 보장하는지, 그 보장이 어느 판본에서 확인됐는지까지 따라갈 수 있어야 한다.

기술문서마다 답하는 질문이 다르다

하나의 거대한 문서에 중복 복사하기보다 담당 문서와 식별자를 연결한다. 자동 추출된 함수 목록에 상태나 락 규칙이 없다면 다른 문서에서 명시해야 한다. 문서 수·페이지 수는 계약 완성의 기준이 아니다.

호출 하나의 계약 카드를 만든다

SAMPLE-v1의 카드는 호출 목적, 사용할 수 있는 주체·권한, 입력 버퍼의 바이트 형식과 길이, 출력의 단위, 상태 변화, 반환값별 의미, 오류 시 부작용, 실행 문맥·잠금, 버퍼 접근 수명, 시간초과·취소·종료 조건을 가진다. SS-SENSOR의 역할과 자원 ID를 그대로 사용한다.

함수 서명에 없는 조건도 구현자가 알아야 같은 의미로 사용할 수 있다면 계약에 포함한다. 예를 들어 “성공 시 실제 쓴 바이트 수 반환”과 “성공 시 요청량 전체 완료”는 다르다. 오류일 때 출력 버퍼 일부가 바뀔 수 있는지, 재시도가 새 작업을 만드는지도 따로 정한다.

2. SS-D1: 바이트 형식을 정확히 고정한다

SAMPLE-v1은 이 절에서 만든 학습용 메시지이며 헤더 8바이트 뒤에 N바이트의 자료가 온다. 모든 정수는 부호 없는 리틀엔디언이고 아래 오프셋은 메시지 첫 바이트 기준이다.

여기서 리틀엔디언은 정수의 낮은 자리 바이트를 먼저 두는 순서다. 처음 두 바이트가 01 00이면 1이며 반대로 읽으면 256이다. 수신 바이트의 순서·폭을 명시적으로 해석하며 C 구조체를 그대로 복사한 배치를 규약이라고 가정하지 않는다. 이 학습용 판본 필드는 Linux ioctl 변경을 모두 같은 명령의 버전 번호로 처리하라는 권고가 아니다.

언어 자료형 이름만으로 이진 배치가 고정되지는 않는다

Linux ioctl 지침은 플랫폼에 따라 long이나 포인터 크기, 정렬과 패딩이 달라질 수 있는 문제를 지적한다. 고정 폭 정수와 명시한 배치를 쓰고, 불필요한 패딩에 남은 커널 정보를 사용자에게 복사하지 않도록 해야 한다. 이는 바이너리 경계의 구체적인 확인 사례다. [SRC-SS-IOCTL]

SAMPLE-v1은 특정 컴파일러의 구조체 배치와 무관하게 8바이트 헤더를 직접 해석한다. 호스트 자료형 변환 뒤에도 범위·단위와 허용 flags를 확인한다. 읽을 수 있는 주소라는 사실은 내용이 현재 판본의 유효한 메시지라는 뜻이 아니다.

길이 검사는 더하기가 넘치기 전에 수행한다

SS-D1에서 N=4이면 필요한 전체 길이는 8+4=12바이트다. 가용 버퍼가 11바이트면 거부하고 12바이트면 길이 조건은 충족한다. 이 예는 여분 바이트가 있어도 앞의 선언된 범위만 읽고, 자료 내용은 별도 검사하는 계약이다.

숫자 N이 실제 입력에서 어떻게 나오는지도 따라가 보자. 헤더의 바이트를 01 00 00 00 04 00 00 00처럼 두 자리 16진수로 적으면, 왼쪽부터 위치 0~7의 바이트다. 위치 0~1은 판본 1, 2~3은 flags 0, 4~7은 N의 04 00 00 00이다. 리틀엔디언에서는 N의 첫 바이트가 가장 낮은 자리이고 다음 바이트의 자리값은 256배이므로 여기서는 N=4다. cap=12이면 먼저 12≥8을 확인하고, 남은 자료 공간 12−8=4에 N=4가 들어가므로 길이 조건을 통과한다. 이제 위치 5의 바이트만 01로 바뀌면 N은 4+1×256=260이고 같은 cap=12에서는 거부해야 한다. 헤더 전체를 한 정수로 읽거나 04 01을 두 개의 자료 바이트로 세는 답은 2. SS-D1: 바이트 형식을 정확히 고정한다에서 설명한 필드 경계를 놓친 것이므로 바이트 위치부터 다시 나눈다. 길이 통과 뒤에도 실제 측정 자료의 내용 검사는 남아 있다.

1. 가용 길이 cap이 8 이상인지 확인한다.
2. 헤더에서 N을 부호 없는 32비트 값으로 읽는다.
3. N <= cap - 8인지 확인한다.
4. 확인된 범위만 읽고 자료 내용의 계약을 검사한다.

길이의 합을 작은 정수형에서 먼저 계산해 넘친 값을 검사하지 않는다. 예컨대 N=4,294,967,295에 8을 32비트로 더하면 작은 값으로 돌아갈 수 있다. 넓은 정수나 검증된 뺄셈 비교를 사용하며, cap<8에서 먼저 cap−8을 부호 없는 수로 계산하는 오류도 피한다. 이 조건은 가상 메시지의 범위 검사이지 포인터 접근권한·원천 진실성의 검증이 아니다.

알 수 없는 판본과 변경 가능한 입력을 숨기지 않는다

SAMPLE-v1은 판본 1·flags 0만 받아들이며 다른 값은 이 계약에서 지원하지 않는 입력으로 거부한다. 알 수 없는 값을 조용히 0으로 바꾸면 호출자가 의도한 의미와 실행이 달라질 수 있다. 길이·판본 검증 실패 시 장치 제출이나 상태 변경을 하지 않는다는 전제도 명시한다.

호출자가 검사 직후 입력을 바꿀 수 있다면 검사한 길이와 실제 읽은 길이가 달라질 수 있다. 사용할 바이트를 안정된 스냅숏으로 읽거나 해당 환경의 안전한 접근·검증 규칙을 적용하여 검사와 사용의 대상이 일치하도록 한다. 이 설명은 사용자 포인터를 직접 믿고 커널에서 읽으라는 코드 지시가 아니다.

3. SS-D2: 부분 결과와 오류의 의미를 분리한다

SS-D2의 읽기 요청량은 8바이트다. 계약은 양수 반환을 “이번에 실제 전달한 바이트 수”로 정한다. 따라서 3을 반환하면 3바이트 진행·5바이트 미완료이며 전체 8바이트 성공으로 기록하지 않는다.

반환 0은 이 가상 계약에서 자료 스트림이 끝났다는 뜻이고, “현재 자료가 아직 없음”은 별도 WOULD_BLOCK 상태다. 시간초과는 대기 한도에 관한 TIMEOUT 상태이며 전송 취소가 확인됐다는 뜻은 아니다. 실제 제품의 0·오류 코드 의미는 해당 API 계약에 따라 확인해야 한다.

호출 성공·실제 진행량·요청 전체 완료를 다른 항목으로 기록한다. 누적 위치와 남은 길이는 진행량만큼 갱신하고, 같은 요청을 처음부터 다시 제출하여 이미 전달한 내용을 중복 처리하지 않는다.

오류 표에는 부작용과 후속 행동을 적는다

이 상태 이름은 학습용이며 특정 운영체제의 errno를 그대로 정의한 것이 아니다. 실제 API가 양수 부분 반환을 했다면 무관한 과거 오류 상태를 읽어 실패로 다시 해석하지 않는다. 어떤 코드가 재시도 가능한지뿐 아니라 재시도 시 중복 효과와 자원 소유권도 문서화한다.

실행 문맥·잠금·수명은 주석의 장식이 아니다

Linux kernel-doc은 함수 문서에 호출 가능한 문맥, 잠들 수 있는지, 필요한 락과 반환 의미를 기술할 수 있는 형식을 제공한다. 인자 설명과 반환형만 적고 이 조건을 빠뜨리면 인터럽트 경로에서 기다리거나 해제된 자원에 접근하는 오용을 막기 어렵다. [SRC-SS-KERNELDOC]

SS-SENSOR의 호출 카드에서는 사용자 서비스에서 대기하는 함수와 하드 인터럽트에서 알림만 처리하는 함수를 구별한다. 어느 락을 호출 전에 가져야 하는지, 누가 해제하는지, 콜백이 같은 자원에 다시 접근할 수 있는지와 종료 중 허용 동작을 정한다. 구체적 커널 함수의 잠금·문맥 조건은 해당 판본의 문서와 구현을 대조한다.

버퍼 전달은 반환 시점과 분리해 기술한다

동기 호출이 반환할 때 버퍼 사용이 끝나는 계약과 비동기 제출 뒤 완료 통지를 받을 때 끝나는 계약은 다르다. 후자의 경우 호출자가 반환 직후 원본 버퍼를 바꾸거나 해제할 수 있는지 반드시 적어야 한다. 장치가 쓰는 버퍼에는 앞 절의 매핑·방향·동기화·회수 조건을 연결한다.

SS-SENSOR의 학습 계약에서는 제출 수락 뒤 버퍼를 대여하며 안전 완료·안전 취소가 확인될 때 반환한다. TIMEOUT에서는 아직 대여 상태일 수 있다. 자원 반환 조건은 응답의 빠르기나 호출자의 기다림이 아니라 남은 접근의 종료와 연결한다. 구현자는 이 계약이 보장되도록 복사 또는 수명 관리 방식을 선택해야 한다.

문장 하나를 시험으로 전환한다

같은 CT ID가 문서·코드 판본·시험 명세·실행 결과에 나타나야 어떤 약속을 확인했는지 알 수 있다. 표의 기대값을 작성한 것은 시험을 실제로 실행한 것과 다르다. 유한 입력 검산은 바이트 규칙을 확인하지만 실제 DMA·스레드 경합까지 시험하지 않는다.

자동 생성 문서는 의미 검토를 대신하지 못한다

코드에서 함수 이름과 인자 설명을 자동으로 모으면 중복 편집을 줄일 수 있다. 그러나 “성공”이라고 적은 주석이 전체 완료인지 부분 진행인지 모호하면 생성된 페이지도 모호하다. 구현의 반환값이 바뀌고 주석은 그대로인 경우도 별도로 찾아야 한다.

자동 문서 생성 성공은 문서와 구현의 의미 일치를 증명하지 않는다. 문서 예제의 기대값, 오류·경계 시험, 호출 순서와 종료 시나리오를 현재 구현과 대조한다. 독자가 올바른 호출 순서·오류 후 행동을 설명할 수 있는지도 별도 검토한다.

4. 변경 후에도 어느 계약이 유효한지 드러낸다

문서에는 지원 대상, 현재 판본·검토 시점, 코드·설정 식별자, 변경 이유와 영향 범위를 남긴다. 입력·반환·단위·락·수명 중 하나가 바뀌면 관련 호출자와 시험·운영 절차도 찾아 갱신한다. 오래된 문서를 지우는 것과 과거 판단의 증거를 보존하는 것은 구분한다.

Linux ioctl 지침은 기존 명령의 의미를 버전 번호로 과도하게 바꾸기보다 새 명령을 정의하는 방식을 권한다. 이는 그 API의 설계 지침이지 모든 네트워크 메시지의 판본 전략과 같은 규칙은 아니다. [SRC-SS-IOCTL]

이 교육 사례에서는 지원하는 계약과 종료된 계약을 명시하고, 과거 코드가 우연히 동작했다는 이유로 지원을 약속하지 않는다.

기술문서의 인계 검토를 닫는 기준

검토자는 정상 호출 하나뿐 아니라 짧은 버퍼·알 수 없는 flags·부분 결과·타임아웃·종료 경합을 읽고 기대 행동을 설명할 수 있어야 한다. 구현 담당자는 그 문장을 코드와 연결하고 시험 담당자는 입력·판본·관찰 결과를 제시한다. 운영 담당자는 사용 가능한 관찰값으로 안전한 회수·재시작 여부를 판정할 수 있어야 한다.

계약의 미정 항목과 실행하지 않은 시험은 완료 표시가 아니라 열린 쟁점으로 남긴다. 질문이 해결되지 않으면 담당자·필요 자료·종료 조건을 적는다. 모호한 약속을 “구현에 따름” 한 줄로 돌려쓰지 않고 구현과 문서 중 무엇을 바꿀지 결정한다.

공식 시스템SW 기술문서 범위

시스템SW 아키텍처의 책임을 현재 구현·호출·자료·상태·동시성·자원·시험·운영의 문서로 연결한다. SAMPLE-v1과 SS-D1/D2의 바이트·길이·반환 의미를 검산하고 미정 계약과 미실행 시험을 구별한다. 실제 운영 인터페이스나 전체 커널 문서의 적합성 승인을 대신하지 않는다.

독립 연습 — 헤더 길이와 읽기 진행량을 서로 섞지 않는다

다음은 본문 사례의 조건을 적용하거나 바꾼 자체 연습이다. 먼저 판단과 근거를 적고 풀이를 펼친다.

SAMPLE-v1의 안정된 헤더 바이트는 01 00 00 00 04 01 00 00이고 cap=268이다. 판본 1·flags 0을 유지한다. 별도의 SS-D2 읽기는 총 8 바이트 요청에서 첫 호출 3 바이트, 두 번째 호출 2 바이트를 실제 전달했다. 다음 호출에서 WOULD_BLOCK을 받았다.

• N의 값과 헤더 포함 길이 조건을 단계대로 계산하라.
• SS-D2의 누적 진행·잔여 길이를 계산하고 WOULD_BLOCK을 EOF로 보고할 수 있는지 쓰라.

자체 10점 문제

시스템SW 인터페이스 기술문서에 포함할 내용을 설명하고, 함수 서명과 자동 문서 생성만으로 계약의 정확성을 보장할 수 없는 이유를 제시하시오.

실제 기출이 아닌 자체 작성 문제다. 앞서 배운 본문의 근거와 경계를 유지하여 설명·비교·판단을 연결한다.

자체 25점 문제

SS-SENSOR의 기술문서를 작성한다고 가정하시오. SAMPLE-v1의 SS-D1 길이·바이트 검증, SS-D2 부분 결과, 자원 수명·문맥·오류·판본 및 시험 추적 방안을 제시하시오.

실제 기출이 아닌 자체 작성 문제다. 앞서 배운 본문의 근거와 경계를 유지하여 설명·비교·판단을 연결한다.