packages/devs/eth/phy/v2_0/doc/eth_phy.sgml

   1 <!-- {{{ Banner                         -->
   2
   3 <!-- =============================================================== -->
   4 <!--                                                                 -->
   5 <!--     eth_phy.sgml                                                -->
   6 <!--                                                                 -->
   7 <!--     eCos ethernet PHY device driver documentation               -->
   8 <!--                                                                 -->
   9 <!-- =============================================================== -->
  10 <!-- ####COPYRIGHTBEGIN####                                          -->
  11 <!--                                                                 -->
  12 <!-- =============================================================== -->
  13 <!-- Copyright (C) 1997, 1998, 1999, 2000, 2001, 2002 Red Hat, Inc.  -->
  14 <!-- This material may be distributed only subject to the terms      -->
  15 <!-- and conditions set forth in the Open Publication License, v1.0  -->
  16 <!-- or later (the latest version is presently available at          -->
  17 <!-- http://www.opencontent.org/openpub/)                            -->
  18 <!-- Distribution of the work or derivative of the work in any       -->
  19 <!-- standard (paper) book form is prohibited unless prior           -->
  20 <!-- permission obtained from the copyright holder                   -->
  21 <!-- =============================================================== -->
  22 <!--                                                                 -->
  23 <!-- ####COPYRIGHTEND####                                            -->
  24 <!-- =============================================================== -->
  25 <!-- #####DESCRIPTIONBEGIN####                                       -->
  26 <!--                                                                 -->
  27 <!-- ####DESCRIPTIONEND####                                          -->
  28 <!-- =============================================================== -->
  29
  30 <!-- }}} -->
  31
  32 <part id="io-eth-phy-generic">
  33 <title>Ethernet PHY Device Support</title>
  34 <chapter id="io-eth-phy-generic1">
  35 <title>Ethernet PHY Device Support</title>
  36 <sect1 id="io-eth-phy-api">
  37 <title>Ethernet PHY Device API</title>
  38 <para>
  39 Modern ethernet subsystems are often separated into two pieces, the
  40 media access controller (sometimes known as a MAC) and the physical
  41 device or line interface (often referred to as a PHY).  In this case,
  42 the MAC handles generating and parsing physical frames and the PHY
  43 handles how this data is actually moved to/from the wire.  The MAC
  44 and PHY communicate via a special protocol, known as MII.  This MII
  45 protocol can handle control over the PHY which allows for selection
  46 of such transmission criteria as line speed, duplex mode, etc.
  47 </para>
  48 <para>
  49 In most cases, ethernet drivers only need to bother with the PHY during
  50 system initialization.  Since the details of the PHY are separate from
  51 the MAC, there are different drivers for each.  The drivers for the PHY
  52 are described by a set of exported functions which are commonly used by
  53 the MAC.  The primary use of these functions currently is to initialize
  54 the PHY and determine the status of the line connection.
  55 </para>
  56 <para>
  57 The connection between the MAC and the PHY differs from MAC to MAC, so
  58 the actual routines to manipulate this data channel are a property of
  59 the MAC instance.  Furthermore, there are many PHY devices each with their
  60 own internal operations.  A complete MAC/PHY driver setup will be comprised
  61 of the MAC MII access functions and the PHY internal driver.
  62 </para>
  63 <para>
  64 A driver instance is contained within a
  65 <type>eth_phy_access_t</type>:
  66 <programlisting>
  67
  68 #define PHY_BIT_LEVEL_ACCESS_TYPE 0
  69 #define PHY_REG_LEVEL_ACCESS_TYPE 1
  70
  71 typedef struct {
  72     int ops_type;  // 0 => bit level, 1 => register level
  73     bool init_done;
  74     void (*init)(void);
  75     void (*reset)(void);
  76     union {
  77         struct {
  78             void (*set_data)(int);
  79             int  (*get_data)(void);
  80             void (*set_clock)(int);
  81             void (*set_dir)(int);
  82         } bit_level_ops;
  83         struct {
  84             void (*put_reg)(int reg, int unit, unsigned short data);
  85             bool (*get_reg)(int reg, int unit, unsigned short *data);
  86         } reg_level_ops;
  87     } ops;
  88     int phy_addr;
  89     struct _eth_phy_dev_entry *dev;  // Chip access functions
  90 } eth_phy_access_t;
  91
  92 struct _eth_phy_dev_entry {
  93     char          *name;
  94     unsigned long  id;
  95     bool         (*stat)(eth_phy_access_t *f, int *stat);
  96 };
  97
  98 </programlisting>
  99 The <varname>dev</varname> element points to the PHY specific support
 100 functions.
 101 Currently, the only function which must be defined is <function>stat()</function>.
 102 </para>
 103 <para>
 104 The MAC-MII-PHY interface is a narrow connection, with commands and status
 105 moving between the MAC and PHY using a bit-serial protocol.
 106 Some MAC devices contain the intelligence to run this protocol, exposing
 107 a mechanism to access PHY registers one at a time.  Other MAC devices may only
 108 provide access to the MII data lines (or even still, this may be considered
 109 completely separate from the MAC).  In these cases, the PHY support layer
 110 must handle the serial protocol.
 111 The choice between the access methods is in the
 112 <varname>ops_type</varname> field.
 113 If it has the value
 114 <varname>PHY_BIT_LEVEL_ACCESS_TYPE</varname>, then the PHY device layer will
 115 run the protocol, using the access functions
 116 <function>set_data()</function>,
 117 <function>get_data()</function>,
 118 <function>set_clock()</function>,
 119 <function>set_dir()</function> are used to control the MII signals and run
 120 the protocol.
 121 If <varname>ops_type</varname> has the value
 122 <varname>PHY_REG_LEVEL_ACCESS_TYPE</varname>,
 123 then the routines
 124 <function>put_reg()</function>, and
 125 <function>get_reg()</function>
 126 are used to access the PHY registers.
 127 </para>
 128 <para>
 129 Two additional functions may be defined.
 130 These are
 131 <function>init()</function>, and
 132 <function>reset()</function>.
 133 The purpose of these functions is for gross-level management of the
 134 MII interface.
 135 The
 136 <function>init()</function>
 137 function will be called once, at system initialization time.
 138 It should do whatever operations are necessary to prepare the
 139 MII channel.
 140 In the case of
 141 <varname>PHY_BIT_LEVEL_ACCESS_TYPE</varname> devices,
 142 <function>init()</function>
 143 should prepare the signals for use, i.e. set up the appropriate
 144 parallel port registers, etc.
 145 The
 146 <function>reset()</function>
 147 function may be called by a driver to cause the PHY device to
 148 be reset to a known state.
 149 Not all drivers will require this and this function may not even
 150 be possible, so it's use and behavior is somewhat target specific.
 151 </para>
 152 <para>
 153 Currently, the only function required of device specific drivers is
 154 <function>stat()</function>.
 155 This routine should query appropriate registers in the PHY and return
 156 a status bitmap indicating the state of the physical connection.
 157 In the case where the PHY can auto-negotiate a line speed and condition,
 158 this information may be useful to the MAC to indicate what speed it should
 159 provide data, etc.
 160 The status bitmask contains these bits:
 161 <programlisting>
 162 #define ETH_PHY_STAT_LINK  0x0001   // Link up/down
 163 #define ETH_PHY_STAT_100MB 0x0002   // Connection is 100Mb/10Mb
 164 #define ETH_PHY_STAT_FDX   0x0004   // Connection is full/half duplex
 165 </programlisting>
 166 Note: the usage here is that if the bit is set, then the condition
 167 exists.  For example, if the
 168 <varname>ETH_PHY_STAT_LINK</varname>
 169 is set, then a physical link has been established.
 170 </para>
 171 </sect1>
 172 </chapter>
 173 </part>