요약·해설과 원문, 전문 번역을 서로 분리했습니다. API 이름, symbol, source path는 원문 표기를 사용합니다.
1. 요약·해설
원문의 핵심 논리와 kernel programming 관점의 보충 설명입니다. 아래의 전문 번역과는 별도로 작성했습니다.
2. 영어 원문 전체
번역 기준이 된 Linux v6.18.37 원문입니다. 줄 번호는 이 버전의 파일 좌표입니다.
원문 전체 펼치기
.. SPDX-License-Identifier: GPL-2.0
Digital TV Common functions
---------------------------
DVB devices
~~~~~~~~~~~
Those functions are responsible for handling the DVB device nodes.
.. kernel-doc:: include/media/dvbdev.h
Digital TV Ring buffer
~~~~~~~~~~~~~~~~~~~~~~
Those routines implement ring buffers used to handle digital TV data and
copy it from/to userspace.
.. note::
1) For performance reasons read and write routines don't check buffer sizes
and/or number of bytes free/available. This has to be done before these
routines are called. For example:
.. code-block:: c
/* write @buflen: bytes */
free = dvb_ringbuffer_free(rbuf);
if (free >= buflen)
count = dvb_ringbuffer_write(rbuf, buffer, buflen);
else
/* do something */
/* read min. 1000, max. @bufsize: bytes */
avail = dvb_ringbuffer_avail(rbuf);
if (avail >= 1000)
count = dvb_ringbuffer_read(rbuf, buffer, min(avail, bufsize));
else
/* do something */
2) If there is exactly one reader and one writer, there is no need
to lock read or write operations.
Two or more readers must be locked against each other.
Flushing the buffer counts as a read operation.
Resetting the buffer counts as a read and write operation.
Two or more writers must be locked against each other.
.. kernel-doc:: include/media/dvb_ringbuffer.h
Digital TV VB2 handler
~~~~~~~~~~~~~~~~~~~~~~
.. kernel-doc:: include/media/dvb_vb2.h
3. 한국어 전문 번역
영어 원문의 문단 순서와 의미를 유지한 전체 번역입니다. 코드, 함수명, symbol과 URL은 원문 표기를 유지합니다.
DVB device node
1-12이 `GPL-2.0` 문서의 첫 절은 Digital TV 공통 function 가운데 DVB device node를 처리하는 API를 설명합니다. Function과 structure의 상세 정의는 `include/media/dvbdev.h` kernel-doc에서 가져옵니다.
.. SPDX-License-Identifier: GPL-2.0
Digital TV Common functions
---------------------------
DVB devices
~~~~~~~~~~~
Those functions are responsible for handling the DVB device nodes.
.. kernel-doc:: include/media/dvbdev.h
Digital TV ring buffer
13-49이 routine들은 digital TV data를 다루고 userspace와 주고받는 ring buffer를 구현합니다. 성능상의 이유로 read·write routine은 buffer 크기나 free·available byte 수를 스스로 검사하지 않으므로 caller가 호출 전에 반드시 확인해야 합니다.
Write 예제는 `dvb_ringbuffer_free(rbuf)`가 `buflen` 이상일 때만 `dvb_ringbuffer_write(rbuf, buffer, buflen)`를 호출합니다. Read 예제는 `dvb_ringbuffer_avail(rbuf)`가 최소 1000 byte 이상일 때 `dvb_ringbuffer_read(rbuf, buffer, min(avail, bufsize))`로 읽습니다.
Reader 하나와 writer 하나만 있으면 read와 write operation 사이에 lock이 필요하지 않습니다. Reader가 둘 이상이면 reader끼리 lock해야 하고, buffer flush는 read operation으로 간주합니다.
Writer가 둘 이상이면 writer끼리 lock해야 합니다. Buffer reset은 read와 write 양쪽 operation으로 간주하므로 두 방향의 동시 접근 규칙을 모두 적용해야 합니다. 상세 API는 `include/media/dvb_ringbuffer.h`에 있습니다.
Read·write helper가 용량을 검사하지 않으므로 caller가 조건을 보장합니다.
Digital TV Ring buffer
~~~~~~~~~~~~~~~~~~~~~~
Those routines implement ring buffers used to handle digital TV data and
copy it from/to userspace.
.. note::
1) For performance reasons read and write routines don't check buffer sizes
and/or number of bytes free/available. This has to be done before these
routines are called. For example:
.. code-block:: c
/* write @buflen: bytes */
free = dvb_ringbuffer_free(rbuf);
if (free >= buflen)
count = dvb_ringbuffer_write(rbuf, buffer, buflen);
else
/* do something */
/* read min. 1000, max. @bufsize: bytes */
avail = dvb_ringbuffer_avail(rbuf);
if (avail >= 1000)
count = dvb_ringbuffer_read(rbuf, buffer, min(avail, bufsize));
else
/* do something */
2) If there is exactly one reader and one writer, there is no need
to lock read or write operations.
Two or more readers must be locked against each other.
Flushing the buffer counts as a read operation.
Resetting the buffer counts as a read and write operation.
Two or more writers must be locked against each other.
.. kernel-doc:: include/media/dvb_ringbuffer.h
Digital TV VB2 handler
50-53Digital TV용 videobuf2 handler의 function과 structure는 `include/media/dvb_vb2.h` kernel-doc에서 가져옵니다.
Digital TV VB2 handler
~~~~~~~~~~~~~~~~~~~~~~
.. kernel-doc:: include/media/dvb_vb2.h
요약과 해설
dtv-common.rst:1-53DVB 공통 API에서 가장 중요한 계약은 ring buffer read·write helper가 용량을 검사하지 않는다는 점입니다. Caller는 free·available byte를 먼저 확인하고, reader·writer 수와 flush·reset 의미에 맞게 locking해야 합니다.