| .. 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. | |
| 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 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. | |
| 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. | |
| 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 | |
| ~~~~~~~~~~~~~~~~~ | |
| 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 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 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. |