1.. SPDX-License-Identifier: GPL-2.0+ 2 3========================================================================= 4OPEN Alliance 10BASE-T1x MAC-PHY Serial Interface (TC6) Framework Support 5========================================================================= 6 7Introduction 8------------ 9 10The IEEE 802.3cg project defines two 10 Mbit/s PHYs operating over a 11single pair of conductors. The 10BASE-T1L (Clause 146) is a long reach 12PHY supporting full duplex point-to-point operation over 1 km of single 13balanced pair of conductors. The 10BASE-T1S (Clause 147) is a short reach 14PHY supporting full / half duplex point-to-point operation over 15 m of 15single balanced pair of conductors, or half duplex multidrop bus 16operation over 25 m of single balanced pair of conductors. 17 18Furthermore, the IEEE 802.3cg project defines the new Physical Layer 19Collision Avoidance (PLCA) Reconciliation Sublayer (Clause 148) meant to 20provide improved determinism to the CSMA/CD media access method. PLCA 21works in conjunction with the 10BASE-T1S PHY operating in multidrop mode. 22 23The aforementioned PHYs are intended to cover the low-speed / low-cost 24applications in industrial and automotive environment. The large number 25of pins (16) required by the MII interface, which is specified by the 26IEEE 802.3 in Clause 22, is one of the major cost factors that need to be 27addressed to fulfil this objective. 28 29The MAC-PHY solution integrates an IEEE Clause 4 MAC and a 10BASE-T1x PHY 30exposing a low pin count Serial Peripheral Interface (SPI) to the host 31microcontroller. This also enables the addition of Ethernet functionality 32to existing low-end microcontrollers which do not integrate a MAC 33controller. 34 35Overview 36-------- 37 38The MAC-PHY is specified to carry both data (Ethernet frames) and control 39(register access) transactions over a single full-duplex serial peripheral 40interface. 41 42Protocol Overview 43----------------- 44 45Two types of transactions are defined in the protocol: data transactions 46for Ethernet frame transfers and control transactions for register 47read/write transfers. A chunk is the basic element of data transactions 48and is composed of 4 bytes of overhead plus 64 bytes of payload size for 49each chunk. Ethernet frames are transferred over one or more data chunks. 50Control transactions consist of one or more register read/write control 51commands. 52 53SPI transactions are initiated by the SPI host with the assertion of CSn 54low to the MAC-PHY and ends with the deassertion of CSn high. In between 55each SPI transaction, the SPI host may need time for additional 56processing and to setup the next SPI data or control transaction. 57 58SPI data transactions consist of an equal number of transmit (TX) and 59receive (RX) chunks. Chunks in both transmit and receive directions may 60or may not contain valid frame data independent from each other, allowing 61for the simultaneous transmission and reception of different length 62frames. 63 64Each transmit data chunk begins with a 32-bit data header followed by a 65data chunk payload on MOSI. The data header indicates whether transmit 66frame data is present and provides the information to determine which 67bytes of the payload contain valid frame data. 68 69In parallel, receive data chunks are received on MISO. Each receive data 70chunk consists of a data chunk payload ending with a 32-bit data footer. 71The data footer indicates if there is receive frame data present within 72the payload or not and provides the information to determine which bytes 73of the payload contain valid frame data. 74 75Reference 76--------- 77 7810BASE-T1x MAC-PHY Serial Interface Specification, 79 80Link: https://opensig.org/download/document/OPEN_Alliance_10BASET1x_MAC-PHY_Serial_Interface_V1.1.pdf 81 82Hardware Architecture 83--------------------- 84 85.. code-block:: none 86 87 +----------+ +-------------------------------------+ 88 | | | MAC-PHY | 89 | |<---->| +-----------+ +-------+ +-------+ | 90 | SPI Host | | | SPI Slave | | MAC | | PHY | | 91 | | | +-----------+ +-------+ +-------+ | 92 +----------+ +-------------------------------------+ 93 94Software Architecture 95--------------------- 96 97.. code-block:: none 98 99 +----------------------------------------------------------+ 100 | Networking Subsystem | 101 +----------------------------------------------------------+ 102 / \ / \ 103 | | 104 | | 105 \ / | 106 +----------------------+ +-----------------------------+ 107 | MAC Driver |<--->| OPEN Alliance TC6 Framework | 108 +----------------------+ +-----------------------------+ 109 / \ / \ 110 | | 111 | | 112 | \ / 113 +----------------------------------------------------------+ 114 | SPI Subsystem | 115 +----------------------------------------------------------+ 116 / \ 117 | 118 | 119 \ / 120 +----------------------------------------------------------+ 121 | 10BASE-T1x MAC-PHY Device | 122 +----------------------------------------------------------+ 123 124Implementation 125-------------- 126 127MAC Driver 128~~~~~~~~~~ 129 130- Probed by SPI subsystem. 131 132- Initializes OA TC6 framework for the MAC-PHY. 133 134- Registers and configures the network device. 135 136- Sends the tx ethernet frames from n/w subsystem to OA TC6 framework. 137 138OPEN Alliance TC6 Framework 139~~~~~~~~~~~~~~~~~~~~~~~~~~~ 140 141- Initializes PHYLIB interface. 142 143- Registers mac-phy interrupt. 144 145- Performs mac-phy register read/write operation using the control 146 transaction protocol specified in the OPEN Alliance 10BASE-T1x MAC-PHY 147 Serial Interface specification. 148 149- Performs Ethernet frames transaction using the data transaction protocol 150 for Ethernet frames specified in the OPEN Alliance 10BASE-T1x MAC-PHY 151 Serial Interface specification. 152 153- Forwards the received Ethernet frame from 10Base-T1x MAC-PHY to n/w 154 subsystem. 155 156Data Transaction 157~~~~~~~~~~~~~~~~ 158 159The Ethernet frames that are typically transferred from the SPI host to 160the MAC-PHY will be converted into multiple transmit data chunks. Each 161transmit data chunk will have a 4 bytes header which contains the 162information needed to determine the validity and the location of the 163transmit frame data within the 64 bytes data chunk payload. 164 165.. code-block:: none 166 167 +---------------------------------------------------+ 168 | Tx Chunk | 169 | +---------------------------+ +----------------+ | MOSI 170 | | 64 bytes chunk payload | | 4 bytes header | |------------> 171 | +---------------------------+ +----------------+ | 172 +---------------------------------------------------+ 173 1744 bytes header contains the below fields, 175 176DNC (Bit 31) - Data-Not-Control flag. This flag specifies the type of SPI 177 transaction. For TX data chunks, this bit shall be ’1’. 178 0 - Control command 179 1 - Data chunk 180 181SEQ (Bit 30) - Data Chunk Sequence. This bit is used to indicate an 182 even/odd transmit data chunk sequence to the MAC-PHY. 183 184NORX (Bit 29) - No Receive flag. The SPI host may set this bit to prevent 185 the MAC-PHY from conveying RX data on the MISO for the 186 current chunk (DV = 0 in the footer), indicating that the 187 host would not process it. Typically, the SPI host should 188 set NORX = 0 indicating that it will accept and process 189 any receive frame data within the current chunk. 190 191RSVD (Bit 28..24) - Reserved: All reserved bits shall be ‘0’. 192 193VS (Bit 23..22) - Vendor Specific. These bits are implementation specific. 194 If the MAC-PHY does not implement these bits, the host 195 shall set them to ‘0’. 196 197DV (Bit 21) - Data Valid flag. The SPI host uses this bit to indicate 198 whether the current chunk contains valid transmit frame data 199 (DV = 1) or not (DV = 0). When ‘0’, the MAC-PHY ignores the 200 chunk payload. Note that the receive path is unaffected by 201 the setting of the DV bit in the data header. 202 203SV (Bit 20) - Start Valid flag. The SPI host shall set this bit when the 204 beginning of an Ethernet frame is present in the current 205 transmit data chunk payload. Otherwise, this bit shall be 206 zero. This bit is not to be confused with the Start-of-Frame 207 Delimiter (SFD) byte described in IEEE 802.3 [2]. 208 209SWO (Bit 19..16) - Start Word Offset. When SV = 1, this field shall 210 contain the 32-bit word offset into the transmit data 211 chunk payload that points to the start of a new 212 Ethernet frame to be transmitted. The host shall write 213 this field as zero when SV = 0. 214 215RSVD (Bit 15) - Reserved: All reserved bits shall be ‘0’. 216 217EV (Bit 14) - End Valid flag. The SPI host shall set this bit when the end 218 of an Ethernet frame is present in the current transmit data 219 chunk payload. Otherwise, this bit shall be zero. 220 221EBO (Bit 13..8) - End Byte Offset. When EV = 1, this field shall contain 222 the byte offset into the transmit data chunk payload 223 that points to the last byte of the Ethernet frame to 224 transmit. This field shall be zero when EV = 0. 225 226TSC (Bit 7..6) - Timestamp Capture. Request a timestamp capture when the 227 frame is transmitted onto the network. 228 00 - Do not capture a timestamp 229 01 - Capture timestamp into timestamp capture register A 230 10 - Capture timestamp into timestamp capture register B 231 11 - Capture timestamp into timestamp capture register C 232 233RSVD (Bit 5..1) - Reserved: All reserved bits shall be ‘0’. 234 235P (Bit 0) - Parity. Parity bit calculated over the transmit data header. 236 Method used is odd parity. 237 238The number of buffers available in the MAC-PHY to store the incoming 239transmit data chunk payloads is represented as transmit credits. The 240available transmit credits in the MAC-PHY can be read either from the 241Buffer Status Register or footer (Refer below for the footer info) 242received from the MAC-PHY. The SPI host should not write more data chunks 243than the available transmit credits as this will lead to transmit buffer 244overflow error. 245 246In case the previous data footer had no transmit credits available and 247once the transmit credits become available for transmitting transmit data 248chunks, the MAC-PHY interrupt is asserted to SPI host. On reception of the 249first data header this interrupt will be deasserted and the received 250footer for the first data chunk will have the transmit credits available 251information. 252 253The Ethernet frames that are typically transferred from MAC-PHY to SPI 254host will be sent as multiple receive data chunks. Each receive data 255chunk will have 64 bytes of data chunk payload followed by 4 bytes footer 256which contains the information needed to determine the validity and the 257location of the receive frame data within the 64 bytes data chunk payload. 258 259.. code-block:: none 260 261 +---------------------------------------------------+ 262 | Rx Chunk | 263 | +----------------+ +---------------------------+ | MISO 264 | | 4 bytes footer | | 64 bytes chunk payload | |------------> 265 | +----------------+ +---------------------------+ | 266 +---------------------------------------------------+ 267 2684 bytes footer contains the below fields, 269 270EXST (Bit 31) - Extended Status. This bit is set when any bit in the 271 STATUS0 or STATUS1 registers are set and not masked. 272 273HDRB (Bit 30) - Received Header Bad. When set, indicates that the MAC-PHY 274 received a control or data header with a parity error. 275 276SYNC (Bit 29) - Configuration Synchronized flag. This bit reflects the 277 state of the SYNC bit in the CONFIG0 configuration 278 register (see Table 12). A zero indicates that the MAC-PHY 279 configuration may not be as expected by the SPI host. 280 Following configuration, the SPI host sets the 281 corresponding bitin the configuration register which is 282 reflected in this field. 283 284RCA (Bit 28..24) - Receive Chunks Available. The RCA field indicates to 285 the SPI host the minimum number of additional receive 286 data chunks of frame data that are available for 287 reading beyond the current receive data chunk. This 288 field is zero when there is no receive frame data 289 pending in the MAC-PHY’s buffer for reading. 290 291VS (Bit 23..22) - Vendor Specific. These bits are implementation specific. 292 If not implemented, the MAC-PHY shall set these bits to 293 ‘0’. 294 295DV (Bit 21) - Data Valid flag. The MAC-PHY uses this bit to indicate 296 whether the current receive data chunk contains valid 297 receive frame data (DV = 1) or not (DV = 0). When ‘0’, the 298 SPI host shall ignore the chunk payload. 299 300SV (Bit 20) - Start Valid flag. The MAC-PHY sets this bit when the current 301 chunk payload contains the start of an Ethernet frame. 302 Otherwise, this bit is zero. The SV bit is not to be 303 confused with the Start-of-Frame Delimiter (SFD) byte 304 described in IEEE 802.3 [2]. 305 306SWO (Bit 19..16) - Start Word Offset. When SV = 1, this field contains the 307 32-bit word offset into the receive data chunk payload 308 containing the first byte of a new received Ethernet 309 frame. When a receive timestamp has been added to the 310 beginning of the received Ethernet frame (RTSA = 1) 311 then SWO points to the most significant byte of the 312 timestamp. This field will be zero when SV = 0. 313 314FD (Bit 15) - Frame Drop. When set, this bit indicates that the MAC has 315 detected a condition for which the SPI host should drop the 316 received Ethernet frame. This bit is only valid at the end 317 of a received Ethernet frame (EV = 1) and shall be zero at 318 all other times. 319 320EV (Bit 14) - End Valid flag. The MAC-PHY sets this bit when the end of a 321 received Ethernet frame is present in this receive data 322 chunk payload. 323 324EBO (Bit 13..8) - End Byte Offset: When EV = 1, this field contains the 325 byte offset into the receive data chunk payload that 326 locates the last byte of the received Ethernet frame. 327 This field is zero when EV = 0. 328 329RTSA (Bit 7) - Receive Timestamp Added. This bit is set when a 32-bit or 330 64-bit timestamp has been added to the beginning of the 331 received Ethernet frame. The MAC-PHY shall set this bit to 332 zero when SV = 0. 333 334RTSP (Bit 6) - Receive Timestamp Parity. Parity bit calculated over the 335 32-bit/64-bit timestamp added to the beginning of the 336 received Ethernet frame. Method used is odd parity. The 337 MAC-PHY shall set this bit to zero when RTSA = 0. 338 339TXC (Bit 5..1) - Transmit Credits. This field contains the minimum number 340 of transmit data chunks of frame data that the SPI host 341 can write in a single transaction without incurring a 342 transmit buffer overflow error. 343 344P (Bit 0) - Parity. Parity bit calculated over the receive data footer. 345 Method used is odd parity. 346 347SPI host will initiate the data receive transaction based on the receive 348chunks available in the MAC-PHY which is provided in the receive chunk 349footer (RCA - Receive Chunks Available). SPI host will create data invalid 350transmit data chunks (empty chunks) or data valid transmit data chunks in 351case there are valid Ethernet frames to transmit to the MAC-PHY. The 352receive chunks available in MAC-PHY can be read either from the Buffer 353Status Register or footer. 354 355In case the previous data footer had no receive data chunks available and 356once the receive data chunks become available again for reading, the 357MAC-PHY interrupt is asserted to SPI host. On reception of the first data 358header this interrupt will be deasserted and the received footer for the 359first data chunk will have the receive chunks available information. 360 361MAC-PHY Interrupt 362~~~~~~~~~~~~~~~~~ 363 364The MAC-PHY interrupt is asserted when the following conditions are met. 365 366Receive chunks available - This interrupt is asserted when the previous 367data footer had no receive data chunks available and once the receive 368data chunks become available for reading. On reception of the first data 369header this interrupt will be deasserted. 370 371Transmit chunk credits available - This interrupt is asserted when the 372previous data footer indicated no transmit credits available and once the 373transmit credits become available for transmitting transmit data chunks. 374On reception of the first data header this interrupt will be deasserted. 375 376Extended status event - This interrupt is asserted when the previous data 377footer indicated no extended status and once the extended event become 378available. In this case the host should read status #0 register to know 379the corresponding error/event. On reception of the first data header this 380interrupt will be deasserted. 381 382Control Transaction 383~~~~~~~~~~~~~~~~~~~ 384 3854 bytes control header contains the below fields, 386 387DNC (Bit 31) - Data-Not-Control flag. This flag specifies the type of SPI 388 transaction. For control commands, this bit shall be ‘0’. 389 0 - Control command 390 1 - Data chunk 391 392HDRB (Bit 30) - Received Header Bad. When set by the MAC-PHY, indicates 393 that a header was received with a parity error. The SPI 394 host should always clear this bit. The MAC-PHY ignores the 395 HDRB value sent by the SPI host on MOSI. 396 397WNR (Bit 29) - Write-Not-Read. This bit indicates if data is to be written 398 to registers (when set) or read from registers 399 (when clear). 400 401AID (Bit 28) - Address Increment Disable. When clear, the address will be 402 automatically post-incremented by one following each 403 register read or write. When set, address auto increment is 404 disabled allowing successive reads and writes to occur at 405 the same register address. 406 407MMS (Bit 27..24) - Memory Map Selector. This field selects the specific 408 register memory map to access. 409 410ADDR (Bit 23..8) - Address. Address of the first register within the 411 selected memory map to access. 412 413LEN (Bit 7..1) - Length. Specifies the number of registers to read/write. 414 This field is interpreted as the number of registers 415 minus 1 allowing for up to 128 consecutive registers read 416 or written starting at the address specified in ADDR. A 417 length of zero shall read or write a single register. 418 419P (Bit 0) - Parity. Parity bit calculated over the control command header. 420 Method used is odd parity. 421 422Control transactions consist of one or more control commands. Control 423commands are used by the SPI host to read and write registers within the 424MAC-PHY. Each control commands are composed of a 4 bytes control command 425header followed by register write data in case of control write command. 426 427The MAC-PHY ignores the final 4 bytes of data from the SPI host at the end 428of the control write command. The control write command is also echoed 429from the MAC-PHY back to the SPI host to identify which register write 430failed in case of any bus errors. The echoed Control write command will 431have the first 4 bytes unused value to be ignored by the SPI host 432followed by 4 bytes echoed control header followed by echoed register 433write data. Control write commands can write either a single register or 434multiple consecutive registers. When multiple consecutive registers are 435written, the address is automatically post-incremented by the MAC-PHY. 436Writing to any unimplemented or undefined registers shall be ignored and 437yield no effect. 438 439The MAC-PHY ignores all data from the SPI host following the control 440header for the remainder of the control read command. The control read 441command is also echoed from the MAC-PHY back to the SPI host to identify 442which register read is failed in case of any bus errors. The echoed 443Control read command will have the first 4 bytes of unused value to be 444ignored by the SPI host followed by 4 bytes echoed control header followed 445by register read data. Control read commands can read either a single 446register or multiple consecutive registers. When multiple consecutive 447registers are read, the address is automatically post-incremented by the 448MAC-PHY. Reading any unimplemented or undefined registers shall return 449zero. 450 451Device drivers API 452================== 453 454The include/linux/oa_tc6.h defines the following functions: 455 456.. c:function:: struct oa_tc6 *oa_tc6_init(struct spi_device *spi, \ 457 struct net_device *netdev) 458 459Initialize OA TC6 lib. 460 461.. c:function:: void oa_tc6_exit(struct oa_tc6 *tc6) 462 463Free allocated OA TC6 lib. 464 465.. c:function:: int oa_tc6_write_register(struct oa_tc6 *tc6, u32 address, \ 466 u32 value) 467 468Write a single register in the MAC-PHY. 469 470.. c:function:: int oa_tc6_write_registers(struct oa_tc6 *tc6, u32 address, \ 471 u32 value[], u8 length) 472 473Writing multiple consecutive registers starting from @address in the MAC-PHY. 474Maximum of 128 consecutive registers can be written starting at @address. 475 476.. c:function:: int oa_tc6_read_register(struct oa_tc6 *tc6, u32 address, \ 477 u32 *value) 478 479Read a single register in the MAC-PHY. 480 481.. c:function:: int oa_tc6_read_registers(struct oa_tc6 *tc6, u32 address, \ 482 u32 value[], u8 length) 483 484Reading multiple consecutive registers starting from @address in the MAC-PHY. 485Maximum of 128 consecutive registers can be read starting at @address. 486 487.. c:function:: netdev_tx_t oa_tc6_start_xmit(struct oa_tc6 *tc6, \ 488 struct sk_buff *skb); 489 490The transmit Ethernet frame in the skb is or going to be transmitted through 491the MAC-PHY. 492 493.. c:function:: int oa_tc6_zero_align_receive_frame_enable(struct oa_tc6 *tc6); 494 495Zero align receive frame feature can be enabled to align all receive ethernet 496frames data to start at the beginning of any receive data chunk payload with a 497start word offset (SWO) of zero. 498