PHY abstraction in Master Class

unref-ptr commented 1 year ago

I was checking the class IOLink::Master and was thinking about some suggestions that could help keep the software flexible and extensible in the future if a new driver is added.

In general there are two types of IOLink Master PHYs
- Raw Access: These are PHYS that give you direct access to the C/Q line. I.e. the MCU must process the raw serial frames, detect correct type, and calculate checksum. Typically they require a UART peripheral. Examples TIOL11X, LTC2874.
- Preprocessed Frames: These can preprocess the MSEQ frame and validate it.Thus the MCU requires less interrupt processing and simplify frame reception. (e.g. MAX14819)
In addition the Wakeup signal for PHYS can be:
- Generated automatically: Either by a Wakeup enable pin or digital I2C/SPI register . (E.g. LTC2874,MAX14824 )
- Manually: By manually reading the C/Q signal line, inverting the signal to the opposite state, sink current (5-15mA) and wait for 80 us. (e.g. TIOL111 + NPN transistor)
Other detail is that some PHYS report status information such as overcurrent, overtemperature, and other.
Some PHYS include more than one port.

Based on this characterization I can suggest something as follows

example implementation in C++

classDiagram
    class fault_e{
        <<enumeration>>
        OverCurrent
        OverTemp
    }
  class PhyDriver {
    - Fault_cb m_fault_cb
    - PLTransferInd_cb m_transferInd_cb
    - uint8_t m_total_ports
    - Hw_cfg_t m_hw_cfg
    # PhyDriver(hw_cfg: const Hw_cfg_t * ,port_count: uint8_t)
    + set_fault_cb(cb: Fault_cb): void
    + set_transferInd_cb(cb: PLTransferInd_cb): void
    + wakeup(port_no: uint8_t): bool
    + PLTransferReq(port_no: uint8_t, pBuf: uint8_t*, len: uint8_t): void
  }

  class Port {
    +Port(phy_driver:PhyDriver*,phy_port:uint8_t)
    -m_phyDriver: PhyDriver*
    -m_phy_port:const uint8_t
  }

  class Master {
    #Master(port_list:Port*)
    -m_port_list: Port*
  }

  class Fault_cb
  class PLTransferInd_cb

  PhyDriver --> fault_e
  PhyDriver --> Fault_cb
  PhyDriver --> PLTransferInd_cb

  Port --> PhyDriver
  Master --> Port

laith-dosinfection commented 1 year ago

The PHYS which report faults like over current and temp are those sent digitally? Could you send me a reference part number so I can research and consider ways of abstracting.

Another factor to consider around the ports and handling of the ports would be the other IC's involved in the port. There could be up to 3 ICs with enables, faults and possibly additional diagnostic data (a smart high side switch with current monitoring). A fully defined port would extend a few items: the PHY (TIOL112), a DI/DO chip (like the TIOS102x), and a high side switch (like the TPS27S100). Every IO-Link port becomes pin hungry quickly being able to implement GPIO expanders should be considered. Thanks for the detailed diagram and sample code.

unref-ptr commented 1 year ago

The PHYS which report faults like over current and temp are those sent digitally? Could you send me a reference part number so I can research and consider ways of abstracting.

TIOL112 (1 port) has a digital output that reports overcurrent, overtemperature and undervoltage. See Table 5-1. Pin Functions and diagrams in page 11.
LTC2874 (4 port) has an interrupt pin that reports faults and can be accessed over SPI. See Table 3 registers EVENT1, EVENT2, EVENT3, EVENT4.
MAX14824 (1 port) has an interrupt pin that reports faults and can be accessed over SPI.. See Page 18 Status regsiter.
MAX14819 (2 ports) has an interrupt pin that reports faults and can be accessed over SPI. See page 33 registers Status, ChanStatA, ChanStatB

Thanks for the detailed diagram and sample code.

No problem! I think diagrams always help and the PHY architecture should be clearly defined as to not have headaches when the code grows.

unref-ptr commented 1 year ago

Another factor to consider around the ports and handling of the ports would be the other IC's involved in the port.

I see. I havent compared all the PHYs in respect to high-side switching and current monitor. For example I think the LTC2874 includes a current monitor. This means that some PHYs may or may not have these functions included in the IC.

In this case I think that these port functions (are there more?) should be part of the IOLink::Port class and if the functionality is available by the PHY IC then it should call the phy driver if not a secondary driver for the High side functionality or current monitor should be called. Then the port could have an optional constructor parameter to indicate a High Side driver IC or a current monitor driver.

Example code

So my suggestion is dependency injection, and a sort of strategy design pattern.

Note: that the driver interface for high side switch and current monitor are improvised and just to show the idea of how to call other drivers in case they are not available in the phy.

classDiagram

class PhyResult_e{
    sucess,
    hw_fail,
    incorrect_mode,
    not_available
}

class CurrentDriver{
    -getCurrent(val:float *) bool
}

class HighSideDriver{
    -SetDO(val:float *) bool
}

class PhyDriver{
    -SetDO(val:bool) PhyResult_e
}

class Port {
    -m_phy_driver:PhyDriver
    -m_current_driver:CurrentDriver
    -m_highside_driver:HighSideDriver
    +Port(phy_driver:PhyDriver, highside_driver:HighSideDriver, current_driver:CurrentDriver)
    -getCurrent(val:float *) bool
    -setDO(val:bool) bool
}

PhyDriver --> PhyResult_e
Port --> PhyDriver
Port --> CurrentDriver
Port --> HighSideDriver

laith-dosinfection / lwIOlinkMaster

PHY abstraction in Master Class #7