This is the mail archive of the
ecos-patches@sources.redhat.com
mailing list for the eCos project.
DOC - Add ethernet PHY driver documentation
- From: Gary Thomas <gary at mlbassoc dot com>
- To: eCos patches <ecos-patches at sources dot redhat dot com>
- Date: 11 Sep 2003 07:11:29 -0600
- Subject: DOC - Add ethernet PHY driver documentation
- Organization: MLB Associates
Rather minimal, but it's a start :-)
--
Gary Thomas <gary@mlbassoc.com>
MLB Associates
Index: doc/ChangeLog
===================================================================
RCS file: /misc/cvsfiles/ecos/doc/ChangeLog,v
retrieving revision 1.18
diff -u -5 -p -r1.18 ChangeLog
--- doc/ChangeLog 9 Jul 2003 13:27:10 -0000 1.18
+++ doc/ChangeLog 11 Sep 2003 13:07:00 -0000
@@ -1,5 +1,9 @@
+2003-09-11 Gary Thomas <gary@mlbassoc.com>
+
+ * sgml/doclist: Add ethernet PHY documentation.
+
2003-07-09 Jonathan Larmour <jifl@eCosCentric.com>
* sgml/makemakefile: Update trademark info and sort.
2003-05-01 Jonathan Larmour <jifl@eCosCentric.com>
Index: doc/sgml/doclist
===================================================================
RCS file: /misc/cvsfiles/ecos/doc/sgml/doclist,v
retrieving revision 1.9
diff -u -5 -p -r1.9 doclist
--- doc/sgml/doclist 25 Feb 2003 14:38:27 -0000 1.9
+++ doc/sgml/doclist 11 Sep 2003 00:54:52 -0000
@@ -16,10 +16,11 @@ net/common/current/doc/tcpip.sgml
net/common/current/doc/tcpip-manpages.sgml
net/bsd_tcpip/current/doc/freebsd.sgml
net/tcpip/current/doc/openbsd.sgml
net/ns/dns/current/doc/dns.sgml
io/eth/current/doc/ethdrv.sgml
+devs/eth/phy/current/doc/eth_phy.sgml
net/snmp/agent/current/doc/snmp.sgml
net/snmp/agent/current/doc/snmp-manpages.sgml
net/httpd/current/doc/httpd.sgml
net/ftpclient/current/doc/ftpclient.sgml
net/sntp/current/doc/sntp.sgml
Index: packages/io/eth/current/doc/ethdrv.sgml
===================================================================
RCS file: /misc/cvsfiles/ecos/packages/io/eth/current/doc/ethdrv.sgml,v
retrieving revision 1.2
diff -u -5 -p -r1.2 ethdrv.sgml
--- packages/io/eth/current/doc/ethdrv.sgml 15 Sep 2002 22:10:52 -0000 1.2
+++ packages/io/eth/current/doc/ethdrv.sgml 11 Sep 2003 00:07:42 -0000
@@ -34,11 +34,11 @@
<chapter id="io-eth-drv-generic1">
<title>Generic Ethernet Device Driver</title>
<sect1 id="io-eth-drv-api">
<title>Generic Ethernet API</title>
<para>
-This file provides a simple description of how to write a low-level,
+This section provides a simple description of how to write a low-level,
hardware dependent ethernet driver.
</para>
<para>
There is a high-level driver (which is only code — with no state of
its own) that is part of the stack. There will be one or more low-level
Index: packages/devs/eth/phy/current/ChangeLog
===================================================================
RCS file: /misc/cvsfiles/ecos/packages/devs/eth/phy/current/ChangeLog,v
retrieving revision 1.2
diff -u -5 -p -r1.2 ChangeLog
--- packages/devs/eth/phy/current/ChangeLog 26 Aug 2003 17:54:00 -0000 1.2
+++ packages/devs/eth/phy/current/ChangeLog 11 Sep 2003 13:08:25 -0000
@@ -1,5 +1,11 @@
+2003-09-11 Gary Thomas <gary@mlbassoc.com>
+
+ * include/eth_phy.h: Minor improvement in status bitfield [comments]
+
+ * doc/eth_phy.sgml: New file - add basic documentation on PHY API.
+
2003-08-26 Gary Thomas <gary@mlbassoc.com>
* src/DP83847.c:
* src/AM79C874.c: New file(s) - driver(s) for PHY devices.
Index: packages/devs/eth/phy/current/doc/eth_phy.sgml
===================================================================
RCS file: packages/devs/eth/phy/current/doc/eth_phy.sgml
diff -N packages/devs/eth/phy/current/doc/eth_phy.sgml
--- /dev/null 1 Jan 1970 00:00:00 -0000
+++ packages/devs/eth/phy/current/doc/eth_phy.sgml 11 Sep 2003 13:00:59 -0000
@@ -0,0 +1,173 @@
+<!-- {{{ Banner -->
+
+<!-- =============================================================== -->
+<!-- -->
+<!-- eth_phy.sgml -->
+<!-- -->
+<!-- eCos ethernet PHY device driver documentation -->
+<!-- -->
+<!-- =============================================================== -->
+<!-- ####COPYRIGHTBEGIN#### -->
+<!-- -->
+<!-- =============================================================== -->
+<!-- Copyright (C) 1997, 1998, 1999, 2000, 2001, 2002 Red Hat, Inc. -->
+<!-- This material may be distributed only subject to the terms -->
+<!-- and conditions set forth in the Open Publication License, v1.0 -->
+<!-- or later (the latest version is presently available at -->
+<!-- http://www.opencontent.org/openpub/) -->
+<!-- Distribution of the work or derivative of the work in any -->
+<!-- standard (paper) book form is prohibited unless prior -->
+<!-- permission obtained from the copyright holder -->
+<!-- =============================================================== -->
+<!-- -->
+<!-- ####COPYRIGHTEND#### -->
+<!-- =============================================================== -->
+<!-- #####DESCRIPTIONBEGIN#### -->
+<!-- -->
+<!-- ####DESCRIPTIONEND#### -->
+<!-- =============================================================== -->
+
+<!-- }}} -->
+
+<part id="io-eth-phy-generic">
+<title>Ethernet PHY Device Support</title>
+<chapter id="io-eth-phy-generic1">
+<title>Ethernet PHY Device Support</title>
+<sect1 id="io-eth-phy-api">
+<title>Ethernet PHY Device API</title>
+<para>
+Modern ethernet subsystems are often separated into two pieces, the
+media access controller (sometimes known as a MAC) and the physical
+device or line interface (often refered to as a PHY). In this case,
+the MAC handles generating and parsing physical frames and the PHY
+handles how this data is actually moved to/from the wire. The MAC
+and PHY communicate via a special protocol, known as MII. This MII
+protocol can handle control over the PHY which allows for selection
+of such transmission criteria as line speed, duplex mode, etc.
+</para>
+<para>
+In most cases, etnernet drivers only need to bother with the PHY during
+system initialization. Since the details of the PHY are separate from
+the MAC, there are different drivers for each. The drivers for the PHY
+are described by a set of exported functions which are commonly used by
+by the MAC. The primary use of these functions currently is to initialize
+the PHY and determine the status of the line connection.
+</para>
+<para>
+The connection between the MAC and the PHY differs from MAC to MAC, so
+the actual routines to manipulate this data channel are a property of
+the MAC instance. Furthermore, there are many PHY devices each with their
+own internal operations. A complete MAC/PHY driver setup will be comprised
+of the MAC MII access functions and the PHY internal driver.
+</para>
+<para>
+A driver instance is contained within a
+<type>eth_phy_access_t</type>:
+<programlisting>
+
+#define PHY_BIT_LEVEL_ACCESS_TYPE 0
+#define PHY_REG_LEVEL_ACCESS_TYPE 1
+
+typedef struct {
+ int ops_type; // 0 => bit level, 1 => register level
+ bool init_done;
+ void (*init)(void);
+ void (*reset)(void);
+ union {
+ struct {
+ void (*set_data)(int);
+ int (*get_data)(void);
+ void (*set_clock)(int);
+ void (*set_dir)(int);
+ } bit_level_ops;
+ struct {
+ void (*put_reg)(int reg, int unit, unsigned short data);
+ bool (*get_reg)(int reg, int unit, unsigned short *data);
+ } reg_level_ops;
+ } ops;
+ int phy_addr;
+ struct _eth_phy_dev_entry *dev; // Chip access functions
+} eth_phy_access_t;
+
+struct _eth_phy_dev_entry {
+ char *name;
+ unsigned long id;
+ bool (*stat)(eth_phy_access_t *f, int *stat);
+};
+
+</programlisting>
+The <varname>dev</varname> element points to the PHY speficic support
+functions.
+Currently, the only function which must be defined is <function>stat()</function>.
+</para>
+<para>
+The MAC-MII-PHY interface is a narrow connection, with commands and status
+moving between the MAC and PHY using a bit-serial protocol.
+Some MAC devices contain the intelligence to run this protocol, exposing
+a mechanism to access PHY registers one at a time. Other MAC devices may only
+provide access to the MII data lines (or even still, this may be considered
+completely separate from the MAC). In these cases, the PHY support layer
+must handle the serial protocol.
+The choice between the access methods is in the
+<varname>ops_type</varname> field.
+If it has the value
+<varname>PHY_BIT_LEVEL_ACCESS_TYPE</varname>, then the PHY device layer will
+run the protocol, using the access functions
+<function>set_data()</function>,
+<function>get_data()</function>,
+<function>set_clock()</function>,
+<function>set_dir()</function> are used to control the MII signals and run
+the protocol.
+If <varname>ops_type</varname> has the value
+<varname>PHY_REG_LEVEL_ACCESS_TYPE</varname>,
+then the routines
+<function>put_reg()</function>, and
+<function>get_reg()</function>
+are used to access the PHY registers.
+</para>
+<para>
+Two additional functions may be defined.
+These are
+<function>init()</function>, and
+<function>reset()</function>.
+The purpose of these functions is for gross-level management of the
+MII interface.
+The
+<function>init()</function>
+function will be called once, at system initialization time.
+It should do whatever operations are necessary to prepare the
+MII channel.
+In the case of
+<varname>PHY_BIT_LEVEL_ACCESS_TYPE</varname> devices,
+<function>init()</function>
+should prepare the signals for use, i.e. set up the appropriate
+parallel port registers, etc.
+The
+<function>reset()</function>
+function may be called by a driver to cause the PHY device to
+be reset to a known state.
+Not all drivers will require this and this function may not even
+be possible, so it's use and behaviour is somewhat target specific.
+</para>
+<para>
+Currently, the only function required of device specific drivers is
+<function>stat()</function>.
+This routine should query appropriate registers in the PHY and return
+a status bitmap indicating the state of the physical connection.
+In the case where the PHY can auto-negotiate a line speed and condition,
+this information may be useful to the MAC to indicate what spped it should
+provide data, etc.
+The status bitmask contains these bits:
+<programlisting>
+#define ETH_PHY_STAT_LINK 0x0001 // Link up/down
+#define ETH_PHY_STAT_100MB 0x0002 // Connection is 100Mb/10Mb
+#define ETH_PHY_STAT_FDX 0x0004 // Connection is full/half duplex
+</programlisting>
+Note: the usage here is that if the bit is set, then the condition
+exists. For example, if the
+<varname>ETH_PHY_STAT_LINK</varname>
+is set, then a physical link has been established.
+</para>
+</sect1>
+</chapter>
+</part>
Index: packages/devs/eth/phy/current/include/eth_phy.h
===================================================================
RCS file: /misc/cvsfiles/ecos/packages/devs/eth/phy/current/include/eth_phy.h,v
retrieving revision 1.2
diff -u -5 -p -r1.2 eth_phy.h
--- packages/devs/eth/phy/current/include/eth_phy.h 26 Aug 2003 17:54:00 -0000 1.2
+++ packages/devs/eth/phy/current/include/eth_phy.h 11 Sep 2003 12:53:28 -0000
@@ -84,12 +84,12 @@ static eth_phy_access_t _l = {PHY_BIT_LE
#define ETH_PHY_REG_LEVEL_ACCESS_FUNS(_l,_init,_reset,_put_reg,_get_reg) \
static eth_phy_access_t _l = {PHY_REG_LEVEL_ACCESS_TYPE, false, _init, _reset, \
{.reg_level_ops = {_put_reg, _get_reg}}}
#define ETH_PHY_STAT_LINK 0x0001 // Link up/down
-#define ETH_PHY_STAT_100MB 0x0002 // Connection is 100Mb
-#define ETH_PHY_STAT_FDX 0x0004 // Connection is full duplex
+#define ETH_PHY_STAT_100MB 0x0002 // Connection is 100Mb/10Mb
+#define ETH_PHY_STAT_FDX 0x0004 // Connection is full/half duplex
externC bool _eth_phy_init(eth_phy_access_t *f);
externC void _eth_phy_reset(eth_phy_access_t *f);
externC int _eth_phy_state(eth_phy_access_t *f);
externC int _eth_phy_cfg(eth_phy_access_t *f, int mode);