SPI controller common properties

SPI controller 공통 schema

이 GPL-2.0 YAML schema는 SPI controller 공통 속성을 정의합니다. Schema ID는 `http://devicetree.org/schemas/spi/spi-controller.yaml#`, maintainer는 Mark Brown입니다.

SPI bus는 controller device node와 bus 위 각 SPI peripheral의 child node 집합으로 기술합니다. System SPI controller는 master mode 또는 slave mode 중 하나로만 기술할 수 있고 동시에 두 mode로 사용할 수 없습니다.

Node 이름과 bus cell

Controller node 이름은 정규식 `^spi(@.*|-([0-9]|[1-9][0-9]+))?$`를 따릅니다. `#address-cells`는 0 또는 1이고 `#size-cells`는 0으로 고정됩니다.

GPIO와 native chip-select 매핑

`cs-gpios`는 chip-select로 사용하는 GPIO 목록입니다. 이 속성을 사용하면 chip-select 수는 `max(cs-gpios, hardware chip selects)`로 자동 증가합니다.

예를 들어 hardware CS line이 4개이고 `cs-gpios = <&gpio1 0 0>, <0>, <&gpio1 1 0>, <&gpio1 2 0>;`이면 `num_chipselect = 4`이며 빈 둘째 항목은 native CS를 뜻합니다. GPIO descriptor의 둘째 flag는 `GPIO_ACTIVE_HIGH(0)` 또는 `GPIO_ACTIVE_LOW(1)`이고 legacy device tree는 흔히 0을 사용합니다.

spi-cs-high와 GPIO polarity 조합

SPI peripheral의 선택적 `spi-cs-high`와 `cs-gpio`의 둘째 flag를 조합하는 특별 규칙이 있습니다. 표의 active state는 pinmux가 가할 수 있는 GPIO inversion은 고려하지 않은 물리적 CS pin 구동 상태입니다.

Active-high CS를 얻는 가장 단순한 방법은 controller의 `cs-gpio`를 `ACTIVE_HIGH`로 지정하고 peripheral에 `spi-cs-high`를 설정하는 것입니다.

FIFO depth, chip-select 수와 slave mode

`fifo-depth`는 RX와 TX data FIFO의 공통 크기, `rx-fifo-depth`와 `tx-fifo-depth`는 각 방향 FIFO 크기이며 단위는 byte입니다. `num-cs`는 chip-select 총수입니다.

Flag `spi-slave`를 지정하면 controller가 master 대신 slave로 동작합니다. `slave` object는 SPI device의 `compatible`을 필수로 포함합니다.

Peripheral child와 SPI mode flag

정규식 `^.*@[0-9a-f]+$`에 맞는 child는 `spi-peripheral-props.yaml`을 참조하고 추가 속성을 허용합니다. Child에는 `compatible`과 `reg`가 필수입니다.

`spi-3wire`는 장치가 3-wire mode를 요구함을, `spi-cpha`는 shifted clock phase(CPHA)를, `spi-cpol`은 inverse clock polarity(CPOL)를 요구함을 나타내는 flag입니다.

FIFO dependency와 master/slave address cell

`rx-fifo-depth`와 `tx-fifo-depth`는 서로 의존하므로 한쪽을 쓰면 다른 쪽도 필요합니다. 공통 `fifo-depth`와 방향별 `rx-fifo-depth` 또는 `tx-fifo-depth`를 동시에 지정할 수 없습니다.

`spi-slave`가 없으면 master mode이므로 `#address-cells`는 1입니다. `spi-slave`가 있으면 slave mode이므로 `#address-cells`는 0입니다. 이 공통 schema는 controller별 확장을 위해 최상위 추가 속성을 허용합니다.

Master controller와 세 peripheral 예제

첫 예제는 `fsl,imx28-spi` master controller에 display, sensor, flash child를 둡니다. Flash는 chip select 2와 3을 묶어 두 개의 `0x10000000` stacked memory를 구성합니다.

spi@80010000 {
    #address-cells = <1>;
    #size-cells = <0>;
    compatible = "fsl,imx28-spi";
    reg = <0x80010000 0x2000>;
    interrupts = <96>;
    dmas = <&dma_apbh 0>;
    dma-names = "rx-tx";

    display@0 {
        compatible = "lg,lg4573";
        spi-max-frequency = <1000000>;
        reg = <0>;
    };

    sensor@1 {
        compatible = "bosch,bme680";
        spi-max-frequency = <100000>;
        reg = <1>;
    };

    flash@2 {
        compatible = "jedec,spi-nor";
        spi-max-frequency = <50000000>;
        reg = <2>, <3>;
        stacked-memories = /bits/ 64 <0x10000000 0x10000000>;
    };
};

Active-high GPIO chip-select 예제

둘째 예제는 BCM2835 SPI controller의 GPIO 8을 `GPIO_ACTIVE_HIGH`로 지정하고 display child에 `spi-cs-high`를 설정해 active-high CS를 구성합니다.

#include <dt-bindings/gpio/gpio.h>

spi@20204000 {
    #address-cells = <1>;
    #size-cells = <0>;
    compatible = "brcm,bcm2835-spi";
    reg = <0x7e204000 0x1000>;
    interrupts = <2 22>;
    clocks = <&clk_spi>;
    cs-gpios = <&gpio 8 GPIO_ACTIVE_HIGH>;

    display@0 {
        compatible = "lg,lg4573";
        spi-max-frequency = <1000000>;
        reg = <0>;
        spi-cs-high;
    };
};