요약·해설과 원문, 전문 번역을 서로 분리했습니다. API 이름, symbol, source path는 원문 표기를 사용합니다.
1. 요약·해설
원문의 핵심 논리와 kernel programming 관점의 보충 설명입니다. 아래의 전문 번역과는 별도로 작성했습니다.
2. 영어 원문 전체
번역 기준이 된 Linux v6.18.37 원문입니다. 줄 번호는 이 버전의 파일 좌표입니다.
원문 전체 펼치기
Serial Peripheral Interface (SPI)
=================================
SPI is the "Serial Peripheral Interface", widely used with embedded
systems because it is a simple and efficient interface: basically a
multiplexed shift register. Its three signal wires hold a clock (SCK,
often in the range of 1-20 MHz), a "Master Out, Slave In" (MOSI) data
line, and a "Master In, Slave Out" (MISO) data line. SPI is a full
duplex protocol; for each bit shifted out the MOSI line (one per clock)
another is shifted in on the MISO line. Those bits are assembled into
words of various sizes on the way to and from system memory. An
additional chipselect line is usually active-low (nCS); four signals are
normally used for each peripheral, plus sometimes an interrupt.
The SPI bus facilities listed here provide a generalized interface to
declare SPI buses and devices, manage them according to the standard
Linux driver model, and perform input/output operations. At this time,
only "master" side interfaces are supported, where Linux talks to SPI
peripherals and does not implement such a peripheral itself. (Interfaces
to support implementing SPI slaves would necessarily look different.)
The programming interface is structured around two kinds of driver, and
two kinds of device. A "Controller Driver" abstracts the controller
hardware, which may be as simple as a set of GPIO pins or as complex as
a pair of FIFOs connected to dual DMA engines on the other side of the
SPI shift register (maximizing throughput). Such drivers bridge between
whatever bus they sit on (often the platform bus) and SPI, and expose
the SPI side of their device as a :c:type:`struct spi_controller
<spi_controller>`. SPI devices are children of that master,
represented as a :c:type:`struct spi_device <spi_device>` and
manufactured from :c:type:`struct spi_board_info
<spi_board_info>` descriptors which are usually provided by
board-specific initialization code. A :c:type:`struct spi_driver
<spi_driver>` is called a "Protocol Driver", and is bound to a
spi_device using normal driver model calls.
The I/O model is a set of queued messages. Protocol drivers submit one
or more :c:type:`struct spi_message <spi_message>` objects,
which are processed and completed asynchronously. (There are synchronous
wrappers, however.) Messages are built from one or more
:c:type:`struct spi_transfer <spi_transfer>` objects, each of
which wraps a full duplex SPI transfer. A variety of protocol tweaking
options are needed, because different chips adopt very different
policies for how they use the bits transferred with SPI.
.. kernel-doc:: include/linux/spi/spi.h
:internal:
.. kernel-doc:: drivers/spi/spi.c
:functions: spi_register_board_info
.. kernel-doc:: drivers/spi/spi.c
:export:
3. 한국어 전문 번역
영어 원문의 문단 순서와 의미를 유지한 전체 번역입니다. 코드, 함수명, symbol과 URL은 원문 표기를 유지합니다.
직렬 주변장치 인터페이스와 신호
1-13SPI는 "Serial Peripheral Interface"의 약자입니다. 기본적으로 다중화된 shift register인 단순하고 효율적인 인터페이스이므로 embedded system에서 널리 사용됩니다.
세 신호선은 clock인 SCK, "Master Out, Slave In" 데이터선인 MOSI, "Master In, Slave Out" 데이터선인 MISO입니다. SCK는 흔히 1-20 MHz 범위에서 동작합니다.
SPI는 full duplex protocol입니다. clock마다 MOSI로 한 bit를 내보낼 때 MISO에서는 다른 한 bit가 들어옵니다. 이 bit들은 system memory로 오가는 과정에서 여러 크기의 word로 조립됩니다.
추가 chipselect 선은 보통 active-low인 nCS입니다. 따라서 주변장치마다 일반적으로 네 신호를 사용하고, 경우에 따라 interrupt도 추가합니다.
Serial Peripheral Interface (SPI)
=================================
SPI is the "Serial Peripheral Interface", widely used with embedded
systems because it is a simple and efficient interface: basically a
multiplexed shift register. Its three signal wires hold a clock (SCK,
often in the range of 1-20 MHz), a "Master Out, Slave In" (MOSI) data
line, and a "Master In, Slave Out" (MISO) data line. SPI is a full
duplex protocol; for each bit shifted out the MOSI line (one per clock)
another is shifted in on the MISO line. Those bits are assembled into
words of various sizes on the way to and from system memory. An
additional chipselect line is usually active-low (nCS); four signals are
normally used for each peripheral, plus sometimes an interrupt.Linux SPI bus facility의 범위
14-20여기에 나열된 SPI bus facility는 SPI bus와 device를 선언하고, 표준 Linux driver model에 따라 이를 관리하며, input/output operation을 수행하기 위한 일반화된 interface를 제공합니다.
현재는 Linux가 SPI peripheral과 통신하되 그 주변장치 자체를 구현하지 않는 "master" side interface만 지원합니다. SPI slave 구현을 지원하는 interface는 구조가 필연적으로 달라집니다.
The SPI bus facilities listed here provide a generalized interface to
declare SPI buses and devices, manage them according to the standard
Linux driver model, and perform input/output operations. At this time,
only "master" side interfaces are supported, where Linux talks to SPI
peripherals and does not implement such a peripheral itself. (Interfaces
to support implementing SPI slaves would necessarily look different.)Controller Driver와 Protocol Driver
21-44Programming interface는 두 종류의 driver와 두 종류의 device를 중심으로 구성됩니다.
"Controller Driver"는 controller hardware를 추상화합니다. 이 hardware는 GPIO pin 집합처럼 단순할 수도 있고, SPI shift register 반대편에서 dual DMA engine에 연결된 FIFO 쌍처럼 throughput을 극대화하는 복잡한 구조일 수도 있습니다.
Controller Driver는 자신이 놓인 bus, 흔히 platform bus와 SPI 사이를 연결합니다. SPI 쪽 controller는 `struct spi_controller`로 노출됩니다.
SPI device는 그 master의 child이며 `struct spi_device`로 표현됩니다. 보통 board-specific initialization code가 제공하는 `struct spi_board_info` descriptor에서 이 device를 만듭니다.
`struct spi_driver`는 "Protocol Driver"라고 부르며, 일반적인 driver model call을 사용해 `spi_device`에 bind합니다.
I/O model은 queued message 집합입니다. Protocol Driver는 하나 이상의 `struct spi_message` 객체를 제출하고, 이 객체는 asynchronous하게 처리된 뒤 완료됩니다. 다만 synchronous wrapper도 제공됩니다.
Message는 하나 이상의 `struct spi_transfer` 객체로 구성되며, 각 transfer는 하나의 full duplex SPI transfer를 감쌉니다. SPI로 전송된 bit를 사용하는 정책이 chip마다 매우 다르므로 여러 protocol tuning option이 필요합니다.
Controller 쪽 bus bridge부터 Protocol Driver가 제출하는 비동기 transfer까지의 객체 관계입니다.
The programming interface is structured around two kinds of driver, and
two kinds of device. A "Controller Driver" abstracts the controller
hardware, which may be as simple as a set of GPIO pins or as complex as
a pair of FIFOs connected to dual DMA engines on the other side of the
SPI shift register (maximizing throughput). Such drivers bridge between
whatever bus they sit on (often the platform bus) and SPI, and expose
the SPI side of their device as a :c:type:`struct spi_controller
<spi_controller>`. SPI devices are children of that master,
represented as a :c:type:`struct spi_device <spi_device>` and
manufactured from :c:type:`struct spi_board_info
<spi_board_info>` descriptors which are usually provided by
board-specific initialization code. A :c:type:`struct spi_driver
<spi_driver>` is called a "Protocol Driver", and is bound to a
spi_device using normal driver model calls.
The I/O model is a set of queued messages. Protocol drivers submit one
or more :c:type:`struct spi_message <spi_message>` objects,
which are processed and completed asynchronously. (There are synchronous
wrappers, however.) Messages are built from one or more
:c:type:`struct spi_transfer <spi_transfer>` objects, each of
which wraps a full duplex SPI transfer. A variety of protocol tweaking
options are needed, because different chips adopt very different
policies for how they use the bits transferred with SPI.SPI API kernel-doc 추출 범위
45-53첫 번째 `kernel-doc` 지시문은 `include/linux/spi/spi.h`의 internal API 문서를 포함합니다.
두 번째 지시문은 `drivers/spi/spi.c`에서 `spi_register_board_info` 함수 문서를 추출합니다.
마지막 지시문은 같은 `drivers/spi/spi.c`에서 export된 API 문서를 포함합니다.
.. kernel-doc:: include/linux/spi/spi.h
:internal:
.. kernel-doc:: drivers/spi/spi.c
:functions: spi_register_board_info
.. kernel-doc:: drivers/spi/spi.c
:export:
요약과 해설
spi.rst:1-53SPI는 SCK·MOSI·MISO와 보통 active-low인 nCS로 full-duplex 전송을 수행합니다. Linux SPI subsystem은 현재 master side를 지원하며, Controller Driver가 `spi_controller`를 제공하고 Protocol Driver가 child `spi_device`에 bind합니다. I/O는 하나 이상의 `spi_transfer`로 구성된 `spi_message`를 queue에 제출하는 모델이고 synchronous wrapper도 제공합니다.