OPEN Alliance TC6 Framework Support

10BASE-T1L, 10BASE-T1S와 MAC-PHY

IEEE 802.3cg 프로젝트는 단일 도체 쌍에서 동작하는 두 가지 10 Mbit/s PHY를 정의합니다. 10BASE-T1L(Clause 146)은 단일 balanced pair에서 최대 1 km의 full-duplex point-to-point 동작을 지원하는 장거리 PHY입니다. 10BASE-T1S(Clause 147)는 단일 balanced pair에서 최대 15 m의 full/half-duplex point-to-point 동작 또는 최대 25 m의 half-duplex multidrop bus 동작을 지원하는 단거리 PHY입니다.

이 프로젝트는 CSMA/CD media access 방식의 결정성을 높이기 위한 새로운 Physical Layer Collision Avoidance(PLCA) Reconciliation Sublayer(Clause 148)도 정의합니다. PLCA는 multidrop mode로 동작하는 10BASE-T1S PHY와 함께 사용합니다.

이 PHY들은 산업·자동차 환경의 저속·저비용 응용을 대상으로 합니다. IEEE 802.3 Clause 22의 MII interface가 요구하는 16개 pin은 이 목표를 달성할 때 해결해야 할 주요 비용 요인입니다.

MAC-PHY 해법은 IEEE Clause 4 MAC과 10BASE-T1x PHY를 통합하고 host microcontroller에는 pin 수가 적은 Serial Peripheral Interface(SPI)를 노출합니다. 따라서 MAC controller가 내장되지 않은 기존 저사양 microcontroller에도 Ethernet 기능을 추가할 수 있습니다. 하나의 full-duplex SPI가 Ethernet frame data와 register access control transaction을 모두 운반합니다.

.. SPDX-License-Identifier: GPL-2.0+

=========================================================================
OPEN Alliance 10BASE-T1x MAC-PHY Serial Interface (TC6) Framework Support
=========================================================================

Introduction
------------

The IEEE 802.3cg project defines two 10 Mbit/s PHYs operating over a
single pair of conductors. The 10BASE-T1L (Clause 146) is a long reach
PHY supporting full duplex point-to-point operation over 1 km of single
balanced pair of conductors. The 10BASE-T1S (Clause 147) is a short reach
PHY supporting full / half duplex point-to-point operation over 15 m of
single balanced pair of conductors, or half duplex multidrop bus
operation over 25 m of single balanced pair of conductors.

Furthermore, the IEEE 802.3cg project defines the new Physical Layer
Collision Avoidance (PLCA) Reconciliation Sublayer (Clause 148) meant to
provide improved determinism to the CSMA/CD media access method. PLCA
works in conjunction with the 10BASE-T1S PHY operating in multidrop mode.

The aforementioned PHYs are intended to cover the low-speed / low-cost
applications in industrial and automotive environment. The large number
of pins (16) required by the MII interface, which is specified by the
IEEE 802.3 in Clause 22, is one of the major cost factors that need to be
addressed to fulfil this objective.

The MAC-PHY solution integrates an IEEE Clause 4 MAC and a 10BASE-T1x PHY
exposing a low pin count Serial Peripheral Interface (SPI) to the host
microcontroller. This also enables the addition of Ethernet functionality
to existing low-end microcontrollers which do not integrate a MAC
controller.

Overview
--------

The MAC-PHY is specified to carry both data (Ethernet frames) and control
(register access) transactions over a single full-duplex serial peripheral
interface.

Data·control transaction과 SPI timing

Protocol에는 Ethernet frame 전송용 data transaction과 register read/write용 control transaction이 있습니다. Data transaction의 기본 단위인 chunk는 4바이트 overhead와 64바이트 payload로 구성되며 Ethernet frame 하나는 하나 이상의 data chunk로 운반됩니다. Control transaction은 하나 이상의 register read/write control command로 구성됩니다.

SPI host가 CSn을 low로 assert하면 transaction이 시작되고 high로 deassert하면 끝납니다. Transaction 사이에는 host가 추가 처리를 수행하고 다음 data 또는 control transaction을 준비할 시간이 필요할 수 있습니다.

SPI data transaction은 같은 수의 TX chunk와 RX chunk로 이루어집니다. 두 방향의 chunk는 서로 독립적으로 유효한 frame data를 포함하거나 비어 있을 수 있으므로 길이가 다른 frame도 동시에 송수신할 수 있습니다.

MOSI의 각 TX chunk는 32비트 data header 뒤에 payload가 옵니다. Header는 송신 frame data의 존재 여부와 payload에서 유효한 byte 범위를 알려 줍니다. 동시에 MISO로 받는 RX chunk는 payload 뒤에 32비트 data footer가 오며, footer가 수신 frame data의 존재 여부와 유효 byte 범위를 나타냅니다.

규격의 기준 문서는 `OPEN Alliance 10BASE-T1x MAC-PHY Serial Interface Specification` V1.1이며 원문에 다운로드 URL이 보존되어 있습니다.

Protocol Overview
-----------------

Two types of transactions are defined in the protocol: data transactions
for Ethernet frame transfers and control transactions for register
read/write transfers. A chunk is the basic element of data transactions
and is composed of 4 bytes of overhead plus 64 bytes of payload size for
each chunk. Ethernet frames are transferred over one or more data chunks.
Control transactions consist of one or more register read/write control
commands.

SPI transactions are initiated by the SPI host with the assertion of CSn
low to the MAC-PHY and ends with the deassertion of CSn high. In between
each SPI transaction, the SPI host may need time for additional
processing and to setup the next SPI data or control transaction.

SPI data transactions consist of an equal number of transmit (TX) and
receive (RX) chunks. Chunks in both transmit and receive directions may
or may not contain valid frame data independent from each other, allowing
for the simultaneous transmission and reception of different length
frames.

Each transmit data chunk begins with a 32-bit data header followed by a
data chunk payload on MOSI. The data header indicates whether transmit
frame data is present and provides the information to determine which
bytes of the payload contain valid frame data.

In parallel, receive data chunks are received on MISO. Each receive data
chunk consists of a data chunk payload ending with a 32-bit data footer.
The data footer indicates if there is receive frame data present within
the payload or not and provides the information to determine which bytes
of the payload contain valid frame data.

Reference
---------

10BASE-T1x MAC-PHY Serial Interface Specification,

Link: https://opensig.org/download/document/OPEN_Alliance_10BASET1x_MAC-PHY_Serial_Interface_V1.1.pdf

Hardware·software architecture와 구현 책임

Hardware에서는 SPI host가 MAC-PHY의 SPI slave와 연결되고, MAC-PHY 내부에는 MAC과 PHY가 함께 들어 있습니다. 즉 host의 저 pin-count SPI 경계 뒤에서 Ethernet MAC·PHY 기능이 완결됩니다.

Software stack의 위쪽에는 Networking Subsystem이 있습니다. MAC driver는 network device와 연결되고 OA TC6 framework와 상호 작용합니다. MAC driver와 framework는 아래 SPI Subsystem을 거쳐 10BASE-T1x MAC-PHY device에 접근하며, framework는 networking subsystem으로 수신 frame도 전달합니다.

MAC driver는 SPI subsystem에 의해 probe됩니다. 이 driver는 MAC-PHY용 OA TC6 framework를 초기화하고 network device를 등록·구성하며, networking subsystem에서 받은 TX Ethernet frame을 OA TC6 framework로 보냅니다.

OA TC6 framework는 PHYLIB interface와 MAC-PHY interrupt를 초기화·등록합니다. OPEN Alliance 규격의 control transaction protocol로 MAC-PHY register를 읽고 쓰며, data transaction protocol로 Ethernet frame을 송수신합니다. 10BASE-T1x MAC-PHY에서 받은 Ethernet frame은 networking subsystem으로 전달합니다.

Hardware Architecture
---------------------

.. code-block:: none

  +----------+      +-------------------------------------+
  |          |      |                MAC-PHY              |
  |          |<---->| +-----------+  +-------+  +-------+ |
  | SPI Host |      | | SPI Slave |  |  MAC  |  |  PHY  | |
  |          |      | +-----------+  +-------+  +-------+ |
  +----------+      +-------------------------------------+

Software Architecture
---------------------

.. code-block:: none

  +----------------------------------------------------------+
  |                 Networking Subsystem                     |
  +----------------------------------------------------------+
            / \                             / \
             |                               |
             |                               |
            \ /                              |
  +----------------------+     +-----------------------------+
  |     MAC Driver       |<--->| OPEN Alliance TC6 Framework |
  +----------------------+     +-----------------------------+
            / \                             / \
             |                               |
             |                               |
             |                              \ /
  +----------------------------------------------------------+
  |                    SPI Subsystem                         |
  +----------------------------------------------------------+
                          / \
                           |
                           |
                          \ /
  +----------------------------------------------------------+
  |                10BASE-T1x MAC-PHY Device                 |
  +----------------------------------------------------------+

Implementation
--------------

MAC Driver
~~~~~~~~~~

- Probed by SPI subsystem.

- Initializes OA TC6 framework for the MAC-PHY.

- Registers and configures the network device.

- Sends the tx ethernet frames from n/w subsystem to OA TC6 framework.

OPEN Alliance TC6 Framework
~~~~~~~~~~~~~~~~~~~~~~~~~~~

- Initializes PHYLIB interface.

- Registers mac-phy interrupt.

- Performs mac-phy register read/write operation using the control
  transaction protocol specified in the OPEN Alliance 10BASE-T1x MAC-PHY
  Serial Interface specification.

- Performs Ethernet frames transaction using the data transaction protocol
  for Ethernet frames specified in the OPEN Alliance 10BASE-T1x MAC-PHY
  Serial Interface specification.

- Forwards the received Ethernet frame from 10Base-T1x MAC-PHY to n/w
  subsystem.

TX data chunk header와 transmit credit

SPI host에서 MAC-PHY로 보내는 Ethernet frame은 여러 TX data chunk로 나뉩니다. 각 chunk에는 64바이트 payload의 유효성과 frame data 위치를 기술하는 4바이트 header가 있습니다. 원문의 그림은 wire 진행 방향과 별개로 payload와 header의 chunk 구성을 표시하며, MOSI로 MAC-PHY에 전달됩니다.

`DNC` bit 31은 Data-Not-Control로 TX data chunk에서 1입니다(0은 control command, 1은 data chunk). `SEQ` bit 30은 MAC-PHY에 짝수/홀수 TX chunk sequence를 알립니다. `NORX` bit 29를 세우면 host가 현재 chunk의 MISO RX data를 처리하지 않을 것이므로 MAC-PHY가 footer의 `DV=0`으로 RX data를 전달하지 않게 합니다. 일반적으로 RX frame을 받을 수 있도록 `NORX=0`을 사용합니다.

`RSVD` bits 28..24와 bit 15, bits 5..1은 모두 0이어야 합니다. `VS` bits 23..22는 vendor-specific이며 MAC-PHY가 구현하지 않았으면 host가 0으로 설정합니다. `DV` bit 21은 현재 payload의 유효한 TX frame data 여부입니다. 0이면 MAC-PHY가 payload를 무시하지만 RX path에는 영향을 주지 않습니다.

`SV` bit 20은 payload에 Ethernet frame 시작이 있을 때 1이며 IEEE 802.3의 Start-of-Frame Delimiter(SFD) byte와는 다릅니다. `SWO` bits 19..16은 `SV=1`일 때 새 frame 시작을 가리키는 32비트 word offset이고, `SV=0`이면 0입니다. `EV` bit 14는 frame 끝의 존재 여부, `EBO` bits 13..8은 `EV=1`일 때 마지막 frame byte의 offset이며 `EV=0`이면 0입니다.

`TSC` bits 7..6은 network 송신 시 timestamp capture를 요청합니다. 00은 capture하지 않음, 01·10·11은 각각 timestamp capture register A·B·C를 뜻합니다. `P` bit 0은 TX data header 전체에 대해 계산한 odd parity입니다.

MAC-PHY가 들어오는 TX payload를 저장할 수 있는 buffer 수는 transmit credit으로 표시됩니다. Host는 Buffer Status Register 또는 MAC-PHY가 돌려준 footer에서 가용 credit을 읽습니다. Credit보다 많은 chunk를 쓰면 transmit buffer overflow가 발생하므로 이를 넘겨서는 안 됩니다.

이전 footer에서 TX credit이 0이었는데 다시 credit이 생기면 MAC-PHY가 SPI host에 interrupt를 assert합니다. 첫 data header를 받으면 interrupt가 deassert되고, 첫 chunk의 수신 footer에는 가용 TX credit 정보가 들어 있습니다.

Data Transaction
~~~~~~~~~~~~~~~~

The Ethernet frames that are typically transferred from the SPI host to
the MAC-PHY will be converted into multiple transmit data chunks. Each
transmit data chunk will have a 4 bytes header which contains the
information needed to determine the validity and the location of the
transmit frame data within the 64 bytes data chunk payload.

.. code-block:: none

  +---------------------------------------------------+
  |                     Tx Chunk                      |
  | +---------------------------+  +----------------+ |   MOSI
  | | 64 bytes chunk payload    |  | 4 bytes header | |------------>
  | +---------------------------+  +----------------+ |
  +---------------------------------------------------+

4 bytes header contains the below fields,

DNC (Bit 31) - Data-Not-Control flag. This flag specifies the type of SPI
               transaction. For TX data chunks, this bit shall be ’1’.
               0 - Control command
               1 - Data chunk

SEQ (Bit 30) - Data Chunk Sequence. This bit is used to indicate an
               even/odd transmit data chunk sequence to the MAC-PHY.

NORX (Bit 29) - No Receive flag. The SPI host may set this bit to prevent
                the MAC-PHY from conveying RX data on the MISO for the
                current chunk (DV = 0 in the footer), indicating that the
                host would not process it. Typically, the SPI host should
                set NORX = 0 indicating that it will accept and process
                any receive frame data within the current chunk.

RSVD (Bit 28..24) - Reserved: All reserved bits shall be ‘0’.

VS (Bit 23..22) - Vendor Specific. These bits are implementation specific.
                  If the MAC-PHY does not implement these bits, the host
                  shall set them to ‘0’.

DV (Bit 21) - Data Valid flag. The SPI host uses this bit to indicate
              whether the current chunk contains valid transmit frame data
              (DV = 1) or not (DV = 0). When ‘0’, the MAC-PHY ignores the
              chunk payload. Note that the receive path is unaffected by
              the setting of the DV bit in the data header.

SV (Bit 20) - Start Valid flag. The SPI host shall set this bit when the
              beginning of an Ethernet frame is present in the current
              transmit data chunk payload. Otherwise, this bit shall be
              zero. This bit is not to be confused with the Start-of-Frame
              Delimiter (SFD) byte described in IEEE 802.3 [2].

SWO (Bit 19..16) - Start Word Offset. When SV = 1, this field shall
                   contain the 32-bit word offset into the transmit data
                   chunk payload that points to the start of a new
                   Ethernet frame to be transmitted. The host shall write
                   this field as zero when SV = 0.

RSVD (Bit 15) - Reserved: All reserved bits shall be ‘0’.

EV (Bit 14) - End Valid flag. The SPI host shall set this bit when the end
              of an Ethernet frame is present in the current transmit data
              chunk payload. Otherwise, this bit shall be zero.

EBO (Bit 13..8) - End Byte Offset. When EV = 1, this field shall contain
                  the byte offset into the transmit data chunk payload
                  that points to the last byte of the Ethernet frame to
                  transmit. This field shall be zero when EV = 0.

TSC (Bit 7..6) - Timestamp Capture. Request a timestamp capture when the
                 frame is transmitted onto the network.
                 00 - Do not capture a timestamp
                 01 - Capture timestamp into timestamp capture register A
                 10 - Capture timestamp into timestamp capture register B
                 11 - Capture timestamp into timestamp capture register C

RSVD (Bit 5..1) - Reserved: All reserved bits shall be ‘0’.

P (Bit 0) - Parity. Parity bit calculated over the transmit data header.
            Method used is odd parity.

The number of buffers available in the MAC-PHY to store the incoming
transmit data chunk payloads is represented as transmit credits. The
available transmit credits in the MAC-PHY can be read either from the
Buffer Status Register or footer (Refer below for the footer info)
received from the MAC-PHY. The SPI host should not write more data chunks
than the available transmit credits as this will lead to transmit buffer
overflow error.

In case the previous data footer had no transmit credits available and
once the transmit credits become available for transmitting transmit data
chunks, the MAC-PHY interrupt is asserted to SPI host. On reception of the
first data header this interrupt will be deasserted and the received
footer for the first data chunk will have the transmit credits available
information.

RX data footer와 receive availability

MAC-PHY에서 SPI host로 가는 Ethernet frame도 여러 RX data chunk로 나뉩니다. 각 chunk는 64바이트 payload 뒤에 4바이트 footer를 붙이며, footer는 payload의 유효성과 수신 frame data 위치를 설명합니다.

`EXST` bit 31은 mask되지 않은 `STATUS0` 또는 `STATUS1` bit가 설정되었을 때 1인 Extended Status입니다. `HDRB` bit 30은 MAC-PHY가 parity error가 있는 control 또는 data header를 받았음을 뜻합니다. `SYNC` bit 29는 `CONFIG0`의 SYNC 상태를 반영하며 0이면 MAC-PHY 구성이 host 기대와 다를 수 있습니다. 설정 후 host가 configuration register의 해당 bit를 세우면 이 field에도 반영됩니다.

`RCA` bits 28..24는 현재 chunk 이외에 읽을 수 있는 추가 RX frame data chunk의 최소 개수입니다. MAC-PHY buffer에 대기 data가 없으면 0입니다. `VS` bits 23..22는 vendor-specific이며 미구현 시 MAC-PHY가 0으로 둡니다. `DV` bit 21은 현재 RX payload가 유효한지 나타내며 0이면 host가 payload를 무시합니다.

`SV` bit 20은 현재 payload에 Ethernet frame 시작이 있음을 나타내며 SFD byte와는 다릅니다. `SWO` bits 19..16은 `SV=1`일 때 새 frame 첫 byte가 든 32비트 word offset입니다. `RTSA=1`로 timestamp가 frame 앞에 붙었다면 timestamp의 최상위 byte를 가리키며, `SV=0`이면 0입니다.

`FD` bit 15는 MAC이 host에게 해당 frame을 버리라고 알리는 Frame Drop입니다. RX frame 끝(`EV=1`)에서만 유효하고 다른 때에는 0입니다. `EV` bit 14는 현재 payload에 frame 끝이 있음을 뜻합니다. `EBO` bits 13..8은 `EV=1`일 때 마지막 byte offset이며 `EV=0`이면 0입니다.

`RTSA` bit 7은 RX frame 앞에 32비트 또는 64비트 timestamp가 추가되었음을 뜻하며 `SV=0`이면 0입니다. `RTSP` bit 6은 추가 timestamp에 대한 odd parity이고 `RTSA=0`이면 0입니다. `TXC` bits 5..1은 host가 한 transaction에서 overflow 없이 쓸 수 있는 TX frame data chunk의 최소 개수입니다. `P` bit 0은 RX footer 전체의 odd parity입니다.

SPI host는 footer의 `RCA`를 보고 receive transaction을 시작합니다. 보낼 Ethernet frame이 없으면 data-invalid empty TX chunk를, 있으면 data-valid TX chunk를 만들면서 동시에 RX chunk를 받습니다. 가용 RX chunk 수는 Buffer Status Register 또는 footer에서 읽을 수 있습니다.

이전 footer의 가용 RX chunk가 0이었다가 다시 읽을 data가 생기면 MAC-PHY가 interrupt를 assert합니다. 첫 data header를 받으면 interrupt가 deassert되고 첫 RX footer가 가용 chunk 정보를 전달합니다.

The Ethernet frames that are typically transferred from MAC-PHY to SPI
host will be sent as multiple receive data chunks. Each receive data
chunk will have 64 bytes of data chunk payload followed by 4 bytes footer
which contains the information needed to determine the validity and the
location of the receive frame data within the 64 bytes data chunk payload.

.. code-block:: none

  +---------------------------------------------------+
  |                     Rx Chunk                      |
  | +----------------+  +---------------------------+ |   MISO
  | | 4 bytes footer |  | 64 bytes chunk payload    | |------------>
  | +----------------+  +---------------------------+ |
  +---------------------------------------------------+

4 bytes footer contains the below fields,

EXST (Bit 31) - Extended Status. This bit is set when any bit in the
                STATUS0 or STATUS1 registers are set and not masked.

HDRB (Bit 30) - Received Header Bad. When set, indicates that the MAC-PHY
                received a control or data header with a parity error.

SYNC (Bit 29) - Configuration Synchronized flag. This bit reflects the
                state of the SYNC bit in the CONFIG0 configuration
                register (see Table 12). A zero indicates that the MAC-PHY
                configuration may not be as expected by the SPI host.
                Following configuration, the SPI host sets the
                corresponding bitin the configuration register which is
                reflected in this field.

RCA (Bit 28..24) - Receive Chunks Available. The RCA field indicates to
                   the SPI host the minimum number of additional receive
                   data chunks of frame data that are available for
                   reading beyond the current receive data chunk. This
                   field is zero when there is no receive frame data
                   pending in the MAC-PHY’s buffer for reading.

VS (Bit 23..22) - Vendor Specific. These bits are implementation specific.
                  If not implemented, the MAC-PHY shall set these bits to
                  ‘0’.

DV (Bit 21) - Data Valid flag. The MAC-PHY uses this bit to indicate
              whether the current receive data chunk contains valid
              receive frame data (DV = 1) or not (DV = 0). When ‘0’, the
              SPI host shall ignore the chunk payload.

SV (Bit 20) - Start Valid flag. The MAC-PHY sets this bit when the current
              chunk payload contains the start of an Ethernet frame.
              Otherwise, this bit is zero. The SV bit is not to be
              confused with the Start-of-Frame Delimiter (SFD) byte
              described in IEEE 802.3 [2].

SWO (Bit 19..16) - Start Word Offset. When SV = 1, this field contains the
                   32-bit word offset into the receive data chunk payload
                   containing the first byte of a new received Ethernet
                   frame. When a receive timestamp has been added to the
                   beginning of the received Ethernet frame (RTSA = 1)
                   then SWO points to the most significant byte of the
                   timestamp. This field will be zero when SV = 0.

FD (Bit 15) - Frame Drop. When set, this bit indicates that the MAC has
              detected a condition for which the SPI host should drop the
              received Ethernet frame. This bit is only valid at the end
              of a received Ethernet frame (EV = 1) and shall be zero at
              all other times.

EV (Bit 14) - End Valid flag. The MAC-PHY sets this bit when the end of a
              received Ethernet frame is present in this receive data
              chunk payload.

EBO (Bit 13..8) - End Byte Offset: When EV = 1, this field contains the
                  byte offset into the receive data chunk payload that
                  locates the last byte of the received Ethernet frame.
                  This field is zero when EV = 0.

RTSA (Bit 7) - Receive Timestamp Added. This bit is set when a 32-bit or
               64-bit timestamp has been added to the beginning of the
               received Ethernet frame. The MAC-PHY shall set this bit to
               zero when SV = 0.

RTSP (Bit 6) - Receive Timestamp Parity. Parity bit calculated over the
               32-bit/64-bit timestamp added to the beginning of the
               received Ethernet frame. Method used is odd parity. The
               MAC-PHY shall set this bit to zero when RTSA = 0.

TXC (Bit 5..1) - Transmit Credits. This field contains the minimum number
                 of transmit data chunks of frame data that the SPI host
                 can write in a single transaction without incurring a
                 transmit buffer overflow error.

P (Bit 0) - Parity. Parity bit calculated over the receive data footer.
            Method used is odd parity.

SPI host will initiate the data receive transaction based on the receive
chunks available in the MAC-PHY which is provided in the receive chunk
footer (RCA - Receive Chunks Available). SPI host will create data invalid
transmit data chunks (empty chunks) or data valid transmit data chunks in
case there are valid Ethernet frames to transmit to the MAC-PHY. The
receive chunks available in MAC-PHY can be read either from the Buffer
Status Register or footer.

In case the previous data footer had no receive data chunks available and
once the receive data chunks become available again for reading, the
MAC-PHY interrupt is asserted to SPI host. On reception of the first data
header this interrupt will be deasserted and the received footer for the
first data chunk will have the receive chunks available information.

MAC-PHY interrupt 조건

MAC-PHY interrupt에는 세 조건이 있습니다. 첫째, 이전 footer에 RX chunk가 없었지만 읽을 chunk가 새로 생긴 경우입니다. 둘째, 이전 footer에 TX credit이 없었지만 송신용 credit이 새로 생긴 경우입니다. 두 경우 모두 첫 data header를 받으면 interrupt가 deassert됩니다.

셋째, 이전 footer에는 extended status가 없었지만 extended event가 새로 생긴 경우입니다. Host는 대응하는 error/event를 확인하려고 status #0 register를 읽어야 합니다. 이 interrupt도 첫 data header를 받으면 deassert됩니다.

MAC-PHY Interrupt
~~~~~~~~~~~~~~~~~

The MAC-PHY interrupt is asserted when the following conditions are met.

Receive chunks available - This interrupt is asserted when the previous
data footer had no receive data chunks available and once the receive
data chunks become available for reading. On reception of the first data
header this interrupt will be deasserted.

Transmit chunk credits available - This interrupt is asserted when the
previous data footer indicated no transmit credits available and once the
transmit credits become available for transmitting transmit data chunks.
On reception of the first data header this interrupt will be deasserted.

Extended status event - This interrupt is asserted when the previous data
footer indicated no extended status and once the extended event become
available. In this case the host should read status #0 register to know
the corresponding error/event. On reception of the first data header this
interrupt will be deasserted.

Control header와 register read/write

4바이트 control header의 `DNC` bit 31은 control command에서 0입니다. `HDRB` bit 30은 MAC-PHY가 parity error가 있는 header를 받았음을 표시하지만 SPI host는 항상 이 bit를 clear해야 하며, MAC-PHY는 MOSI로 받은 HDRB 값을 무시합니다. `WNR` bit 29는 1이면 register write, 0이면 read입니다.

`AID` bit 28은 Address Increment Disable입니다. 0이면 각 register read/write 뒤 address가 1씩 자동 증가하고, 1이면 같은 address에 연속 접근할 수 있도록 자동 증가를 끕니다. `MMS` bits 27..24는 접근할 register memory map, `ADDR` bits 23..8은 해당 map의 첫 register address입니다.

`LEN` bits 7..1은 read/write할 register 수에서 1을 뺀 값입니다. 따라서 `ADDR`에서 시작해 최대 128개 연속 register를 지정하며 0은 register 하나를 뜻합니다. `P` bit 0은 control command header에 대한 odd parity입니다.

Control transaction은 하나 이상의 control command로 구성됩니다. 각 command에는 4바이트 header가 있고 write command라면 그 뒤에 register write data가 옵니다.

Control write에서 MAC-PHY는 host가 끝에 보낸 마지막 4바이트를 무시합니다. Bus error가 났을 때 실패한 register write를 찾을 수 있도록 command를 host에 echo합니다. Echo는 host가 무시할 첫 4바이트, 4바이트 echo header, echo된 register write data 순서입니다. 하나 또는 여러 연속 register를 쓸 수 있고 연속 write에서는 MAC-PHY가 address를 자동 증가시킵니다. 구현되지 않았거나 정의되지 않은 register에 쓰면 아무 효과 없이 무시됩니다.

Control read에서는 MAC-PHY가 control header 뒤에 host가 보낸 나머지 data를 모두 무시합니다. Bus error 시 실패한 read를 찾도록 command를 echo하며, host가 무시할 첫 4바이트, 4바이트 echo header, register read data 순서입니다. 하나 또는 여러 연속 register를 읽을 수 있고 address가 자동 증가합니다. 구현되지 않았거나 정의되지 않은 register를 읽으면 0을 반환합니다.

Control Transaction
~~~~~~~~~~~~~~~~~~~

4 bytes control header contains the below fields,

DNC (Bit 31) - Data-Not-Control flag. This flag specifies the type of SPI
               transaction. For control commands, this bit shall be ‘0’.
               0 - Control command
               1 - Data chunk

HDRB (Bit 30) - Received Header Bad. When set by the MAC-PHY, indicates
                that a header was received with a parity error. The SPI
                host should always clear this bit. The MAC-PHY ignores the
                HDRB value sent by the SPI host on MOSI.

WNR (Bit 29) - Write-Not-Read. This bit indicates if data is to be written
               to registers (when set) or read from registers
               (when clear).

AID (Bit 28) - Address Increment Disable. When clear, the address will be
               automatically post-incremented by one following each
               register read or write. When set, address auto increment is
               disabled allowing successive reads and writes to occur at
               the same register address.

MMS (Bit 27..24) - Memory Map Selector. This field selects the specific
                   register memory map to access.

ADDR (Bit 23..8) - Address. Address of the first register within the
                   selected memory map to access.

LEN (Bit 7..1) - Length. Specifies the number of registers to read/write.
                 This field is interpreted as the number of registers
                 minus 1 allowing for up to 128 consecutive registers read
                 or written starting at the address specified in ADDR. A
                 length of zero shall read or write a single register.

P (Bit 0) - Parity. Parity bit calculated over the control command header.
            Method used is odd parity.

Control transactions consist of one or more control commands. Control
commands are used by the SPI host to read and write registers within the
MAC-PHY. Each control commands are composed of a 4 bytes control command
header followed by register write data in case of control write command.

The MAC-PHY ignores the final 4 bytes of data from the SPI host at the end
of the control write command. The control write command is also echoed
from the MAC-PHY back to the SPI host to identify which register write
failed in case of any bus errors. The echoed Control write command will
have the first 4 bytes unused value to be ignored by the SPI host
followed by 4 bytes echoed control header followed by echoed register
write data. Control write commands can write either a single register or
multiple consecutive registers. When multiple consecutive registers are
written, the address is automatically post-incremented by the MAC-PHY.
Writing to any unimplemented or undefined registers shall be ignored and
yield no effect.

The MAC-PHY ignores all data from the SPI host following the control
header for the remainder of the control read command. The control read
command is also echoed from the MAC-PHY back to the SPI host to identify
which register read is failed in case of any bus errors. The echoed
Control read command will have the first 4 bytes of unused value to be
ignored by the SPI host followed by 4 bytes echoed control header followed
by register read data. Control read commands can read either a single
register or multiple consecutive registers. When multiple consecutive
registers are read, the address is automatically post-incremented by the
MAC-PHY. Reading any unimplemented or undefined registers shall return
zero.

Device driver API

`include/linux/oa_tc6.h`는 OA TC6 driver용 함수를 선언합니다. `oa_tc6_init(struct spi_device *spi, struct net_device *netdev)`는 OA TC6 library를 초기화하고 `struct oa_tc6 *`를 반환합니다. `oa_tc6_exit(struct oa_tc6 *tc6)`는 할당한 library resource를 해제합니다.

`oa_tc6_write_register(struct oa_tc6 *tc6, u32 address, u32 value)`는 MAC-PHY register 하나를 씁니다. `oa_tc6_write_registers(struct oa_tc6 *tc6, u32 address, u32 value[], u8 length)`는 `address`에서 시작하는 연속 register를 최대 128개까지 씁니다.

`oa_tc6_read_register(struct oa_tc6 *tc6, u32 address, u32 *value)`는 MAC-PHY register 하나를 읽습니다. `oa_tc6_read_registers(struct oa_tc6 *tc6, u32 address, u32 value[], u8 length)`는 `address`에서 시작하는 연속 register를 최대 128개까지 읽습니다.

`oa_tc6_start_xmit(struct oa_tc6 *tc6, struct sk_buff *skb)`는 `skb`의 Ethernet frame이 MAC-PHY를 통해 송신되었거나 송신될 예정임을 나타내며 `netdev_tx_t`를 반환합니다.

`oa_tc6_zero_align_receive_frame_enable(struct oa_tc6 *tc6)`는 zero-align receive-frame 기능을 켭니다. 모든 RX Ethernet frame data가 `SWO=0`으로 RX data chunk payload의 시작에 정렬되게 합니다.

Device drivers API
==================

The include/linux/oa_tc6.h defines the following functions:

.. c:function:: struct oa_tc6 *oa_tc6_init(struct spi_device *spi, \
                                           struct net_device *netdev)

Initialize OA TC6 lib.

.. c:function:: void oa_tc6_exit(struct oa_tc6 *tc6)

Free allocated OA TC6 lib.

.. c:function:: int oa_tc6_write_register(struct oa_tc6 *tc6, u32 address, \
                                          u32 value)

Write a single register in the MAC-PHY.

.. c:function:: int oa_tc6_write_registers(struct oa_tc6 *tc6, u32 address, \
                                           u32 value[], u8 length)

Writing multiple consecutive registers starting from @address in the MAC-PHY.
Maximum of 128 consecutive registers can be written starting at @address.

.. c:function:: int oa_tc6_read_register(struct oa_tc6 *tc6, u32 address, \
                                         u32 *value)

Read a single register in the MAC-PHY.

.. c:function:: int oa_tc6_read_registers(struct oa_tc6 *tc6, u32 address, \
                                          u32 value[], u8 length)

Reading multiple consecutive registers starting from @address in the MAC-PHY.
Maximum of 128 consecutive registers can be read starting at @address.

.. c:function:: netdev_tx_t oa_tc6_start_xmit(struct oa_tc6 *tc6, \
                                              struct sk_buff *skb);

The transmit Ethernet frame in the skb is or going to be transmitted through
the MAC-PHY.

.. c:function:: int oa_tc6_zero_align_receive_frame_enable(struct oa_tc6 *tc6);

Zero align receive frame feature can be enabled to align all receive ethernet
frames data to start at the beginning of any receive data chunk payload with a
start word offset (SWO) of zero.