본문으로 건너뛰기

장치 유형 추가

Sentinel의 주변 장치 카탈로그는 하드웨어 사실을 나열합니다. 새로운 종류의 장치(예: 디스플레이 또는 직렬 어댑터)에는 타입이 지정된 레코드, 이를 탐지하는 프로바이더, 테스트, 그리고 이 디렉터리의 페이지가 필요합니다. 애플리케이션이 장치를 지원하는지는 Sentinel이 아니라 해당 애플리케이션이 결정합니다.

1. 레코드 정의​

src/peripherals/ 아래에 장치용 serde 구조체를 담은 모듈을 추가하고 src/peripherals/mod.rs의 Peripheral에 변형(variant)으로 추가합니다. 변형 이름은 JSON의 type 태그가 되므로 Display(display::Display)는 {"type": "display", ...}로 직렬화됩니다. 새 변형에 맞게 Peripheral::id, kind 및 describe를 확장하십시오.

  • id는 재연결과 재부팅 후에도 안정적이어야 합니다. 버스 경로, 일련번호 또는 재연결과 재부팅 후에도 유지되는 다른 속성에서 파생하고, 카드 번호나 /dev/videoN 같은 열거 인덱스에서는 절대 파생하지 마십시오.
  • id는 또한 전체 카탈로그에서 고유해야 합니다. 워커는 이를 확인하지 않습니다. 기존 id처럼 유형과 프로바이더를 접두사로 붙이고 (camera:v4l2:…, microphone:alsa:…), 나머지는 동일한 두 장치가 공유할 수 없는 것, 예를 들어 장치가 연결된 포트로 구성하십시오. 일련번호만으로는 충분하지 않습니다. 저가 장치는 같은 일련번호를 반복하는 경우가 많습니다.
  • 선택적 사실은 다음 속성을 붙인 Option 필드로 정의합니다: #[serde(default, skip_serializing_if = "Option::is_none")](기존 레코드와 동일). 따라서 알 수 없는 사실은 JSON에서 생략됩니다. 일반 Option은 null로 직렬화됩니다.
  • 커널이나 장치가 노출하는 사실을 보고하십시오. 모드의 지원 여부와 같은 정책을 인코딩하는 필드는 추가하지 마십시오.

2. 프로바이더 작성​

Provider 트레이트를 구현하십시오:

pub trait Provider: Send {
    fn name(&self) -> &'static str;            // e.g. "display.drm"
    fn subsystems(&self) -> &'static [&'static str]; // uevent subsystems, e.g. ["drm"]
    fn discover(&mut self) -> Result<Vec<Peripheral>, ProviderError>;
}

discover는 peripherals 스레드에서 한 번의 완전한 스캔을 실행합니다. 워커는 시작 시, subsystems 중 하나에서 uevent가 발생한 후, 그리고 새로 고침 시 이를 호출합니다.

  • 읽기 전용. 장치 노드를 읽기 전용으로 열고 쿼리 인터페이스만 사용하십시오. 장치를 점유하거나, 구성하거나, 장치에서 스트리밍하지 마십시오.
  • 상한 설정. 읽는 모든 목록과 모든 쿼리 루프에 상한을 두어, 고장 난 장치가 스캔을 멈추게 할 수 없도록 하십시오. videodev2.rs의 V4L2 도우미가 이 패턴을 보여줍니다.
  • 오류. 스캔을 완료할 수 없으면 다음과 같은 코드와 함께 ProviderError를 반환하십시오: io.permission_denied 또는 io.open(sysutil.rs 참조). 그러면 카탈로그는 이 프로바이더의 마지막 정상 장치를 유지하고 errors에 오류를 나열합니다. 스캔 중에 사라진 장치는 오류가 아니라 건너뜁니다. 장치가 제거될 때 전송되는 uevent가 재스캔을 트리거합니다.
  • 실패 대신 기능 축소. 누락된 선택적 속성은 해당 필드를 생략합니다. 존재하지만 읽을 수 없는 속성은 그 용도에 따라 처리하십시오:
    • 스캔이 장치를 찾거나 식별하는 데 필요한 속성(장치의 id, USB 식별 정보)이면 오류이며, 프로바이더의 마지막 정상 장치가 유지됩니다.
    • 사실만 추가하는 속성이면 해당 사실 없이 장치를 게시하되, 레코드에 이유를 남깁니다(마이크 레코드의 issues가 읽을 수 없는 캡처 메타데이터에 대해 이렇게 합니다).

src/peripherals/mod.rs의 builtin_providers()에 프로바이더를 등록하십시오.

3. 테스트​

테스트는 실제 시스템 대신 픽스처 트리를 읽습니다. 프로바이더에 sysfs, procfs 및 /dev 루트를 매개변수로 전달하고 ioctl 계층을 가짜로 대체하십시오. alsa/tests.rs 및 v4l2/tests.rs가 그렇게 합니다. 가지고 있는 장치뿐 아니라 해당 클래스의 장치들이 서로 다른 모든 측면을 다루십시오: 개수, 형식, 범위 대 이산 값, 누락된 선택적 필드, 동시에 존재하는 여러 동일 장치, 그리고 스캔 도중 사라지는 장치. 동일한 두 장치가 서로 다른 id를 갖는지 검증하십시오. 실제 하드웨어에서 복사한 픽스처에는 실제 캡처라는 레이블을 붙이십시오.

cargo test --locked가 통과해야 하며, cargo fmt --check 및 cargo clippy --locked --all-targets는 새로운 문제를 보고하지 않아야 합니다.

4. 문서화​

이 디렉터리에 프로바이더 이름, uevent 서브시스템, id의 파생 방식, 각 필드와 그 포함 조건, 오류 코드, 그리고 JSON 예시를 나열하는 페이지를 추가하십시오. API 참조 및 문서 색인에서 이 페이지로 링크한 다음, 번역을 다시 생성하십시오 (현지화 참조).