Skip to contentSkip to conversation

eth/net driver documentation

U-Boot New Mike Frysinger 5 participants 23 messages Jul 16, 2009 – Oct 5, 2009 Networking

lore
Share & tools
lore
#0 lore raw

is there any documentation that covers the NET_MULTI driver stack ? i.e. if i was a network chip vendor and wanted to write a u-boot driver for my part, where would i look ? or is it a matter of "the code is the documentation" ? i can start a small doc that covers the existing stack if that is the case ... more to keep my sanity so i dont have to keep going through the ethernet stack to remind myself of how things fit together ;).
-mike
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 836 bytes
Desc: This is a digitally signed message part.
Url : http://lists.denx.de/pipermail/u-boot/attachments/20090715/8eeb9f58/attachment.pgp

#1 lore raw

Hi Mike,

Quoted 8 lines · Mike Frysinger

is there any documentation that covers the NET_MULTI driver stack ? i.e. if i was a network chip vendor and wanted to write a u-boot driver for my part, where would i look ? or is it a matter of "the code is the documentation" ? i can start a small doc that covers the existing stack if that is the case ... more to keep my sanity so i dont have to keep going through the ethernet stack to remind myself of how things fit together ;).
-mike

Isn't the code nicely self-documenting? :) I think yours is a great idea. It's a pretty simple interface, but not necessarily intuitive. I'll be glad to help if needed.

regards,
Ben

#2 lore raw

PATCH 1/2 net: rename NetRxPkt to NetRxPacket

The net code is mostly consistent in using 'Packet' rather than 'Pkt', so rename the minor detractor to follow suite.

---
 include/net.h |    4 ++--
 net/bootp.c   |    2 +-
 net/net.c     |    8 ++++----
 3 files changed, 7 insertions(+), 7 deletions(-)
include/net.h +2 -2
index 5a1d36e..88a9513 100644
@@ -331,8 +331,8 @@ extern IPaddr_t		NetOurIP;		/* Our    IP addr (0 = unknown)	*/
 extern IPaddr_t		NetServerIP;		/* Server IP addr (0 = unknown)	*/
 extern volatile uchar * NetTxPacket;		/* THE transmit packet		*/
 extern volatile uchar * NetRxPackets[PKTBUFSRX];/* Receive packets		*/
-extern volatile uchar * NetRxPkt;		/* Current receive packet	*/
-extern int		NetRxPktLen;		/* Current rx packet length	*/
+extern volatile uchar * NetRxPacket;		/* Current receive packet	*/
+extern int		NetRxPacketLen;		/* Current rx packet length	*/
 extern unsigned		NetIPID;		/* IP ID (counting)		*/
 extern uchar		NetBcastAddr[6];	/* Ethernet boardcast address	*/
 extern uchar		NetEtherNullAddr[6];
net/bootp.c +1 -1
index 77057c6..d5f9c4b 100644
@@ -124,7 +124,7 @@ static void BootpCopyNetParams(Bootp_t *bp)
 	NetCopyIP(&tmp_ip, &bp->bp_siaddr);
 	if (tmp_ip != 0)
 		NetCopyIP(&NetServerIP, &bp->bp_siaddr);
-	memcpy (NetServerEther, ((Ethernet_t *)NetRxPkt)->et_src, 6);
+	memcpy (NetServerEther, ((Ethernet_t *)NetRxPacket)->et_src, 6);
 #endif
 	if (strlen(bp->bp_file) > 0)
 		copy_filename (BootFile, bp->bp_file, sizeof(BootFile));
net/net.c +4 -4
index 5637cf5..e215fd8 100644
@@ -139,8 +139,8 @@ uchar		NetServerEther[6] =	/* Boot server enet address		*/
 			{ 0, 0, 0, 0, 0, 0 };
 IPaddr_t	NetOurIP;		/* Our IP addr (0 = unknown)		*/
 IPaddr_t	NetServerIP;		/* Server IP addr (0 = unknown)		*/
-volatile uchar *NetRxPkt;		/* Current receive packet		*/
-int		NetRxPktLen;		/* Current rx packet length		*/
+volatile uchar *NetRxPacket;		/* Current receive packet		*/
+int		NetRxPacketLen;		/* Current rx packet length		*/
 unsigned	NetIPID;		/* IP packet ID				*/
 uchar		NetBcastAddr[6] =	/* Ethernet bcast address		*/
 			{ 0xff, 0xff, 0xff, 0xff, 0xff, 0xff };
@@ -1122,8 +1122,8 @@ NetReceive(volatile uchar * inpkt, int len)
 	printf("packet received\n");
 #endif
 
-	NetRxPkt = inpkt;
-	NetRxPktLen = len;
+	NetRxPacket = inpkt;
+	NetRxPacketLen = len;
 	et = (Ethernet_t *)inpkt;
 
 	/* too small packet? */
Signature · 1 line
1.6.3.3
Applied
#3 lore raw

PATCH 1/2 net: rename NetRxPkt to NetRxPacket

Mike,

Quoted 10 lines · Mike Frysinger

The net code is mostly consistent in using 'Packet' rather than 'Pkt', so rename the minor detractor to follow suite.

---
 include/net.h |    4 ++--
 net/bootp.c   |    2 +-
 net/net.c     |    8 ++++----
 3 files changed, 7 insertions(+), 7 deletions(-)

Applied to net repo.

thanks,
Ben

#4 lore raw

PATCH 2/2 document network driver framework

In reply to Ben Warren

---
Ben: some things to note:
- i adopted Jean's proposed naming scheme in the CONFIG section
- i deprecated calling the driver-specific entry point "xxx_initialization()" in favor of "xxx_register()" because the former is way too confusing with everyone also having "xxx_init()"

 doc/README.drivers.eth |  199 ++++++++++++++++++++++++++++++++++++++++++++++++
 1 files changed, 199 insertions(+), 0 deletions(-)
 create mode 100644 doc/README.drivers.eth
doc/README.drivers.eth new file +199 -0
new file mode 100644
index 0000000..00b4eb1
@@ -0,0 +1,199 @@
+-----------------------
+ Ethernet Driver Guide
+-----------------------
+
+The networking stack in Das U-Boot is designed for multiple network devices
+to be easily added and controlled at runtime.  This guide is meant for people
+who wish to review the net driver stack with an eye towards implementing your
+own ethernet device driver.  Here we will describe a new pseudo 'APE' driver.
+
+----------------
+ CONFIG Options
+----------------
+
+The common config defines your device should respect (if applicable):
+	CONFIG_MII  - configure in MII mode
+	CONFIG_RMII - configure in RMII mode
+
+	CONFIG_CMD_MII - support the MII command
+
+If you want to add config options specific to your driver, you should use the
+naming convention:
+	CONFIG_NET_<DRIVERNAME>_<OPTION>
+For example, if the APE driver could operate in either 16bit or 32bit mode,
+there would probably be the option:
+	CONFIG_NET_APE_32BIT - operate in 32bit mode rather than 16bit default
+
+And to control whether your driver is even enabled, you should use:
+	CONFIG_SYS_NET_<DRIVERNAME>
+So the APE driver would look like:
+	CONFIG_SYS_NET_APE
+
+------------------
+ Driver Functions
+------------------
+
+All functions you will be implementing in this document have the return value
+meaning of 0 for success and non-zero for failure.
+
+ ----------
+  Register
+ ----------
+
+When U-Boot initializes, it will call the common function eth_initialize().
+This will in turn call the board-specific board_eth_init() (or if that fails,
+the cpu-specific cpu_eth_init()).  These board-specific functions can do random
+system handling, but ultimately they will call the driver-specific register
+function which in turn takes care of initializing that particular instance.
+
+Keep in mind that you should code the driver to avoid storing state in global
+data as someone might want to hook up two of the same devices to one board.  If
+the state is maintained as global data, it makes using both of those devices
+impossible.
+
+So the call graph at this stage would look something like:
+board_init()
+	eth_initialize()
+		board_eth_init() / cpu_eth_init()
+			driver_register()
+				initialize eth_device
+				eth_register()
+
+At this point in time, the only thing you need to worry about is the driver's
+register function.  The pseudo code would look something like:
+int ape_register(bd_t *bis, int iobase)
+{
+	struct ape_priv *priv;
+	struct eth_device *dev;
+
+	priv = malloc(sizeof(*priv));
+	if (priv == NULL)
+		return 1;
+
+	dev = malloc(sizeof(*dev));
+	if (dev == NULL) {
+		free(priv);
+		return 1;
+	}
+
+	/* setup whatever private state you need */
+
+	memset(dev, 0, sizeof(*dev));
+	sprintf(dev->name, "APE");
+
+	/* if your device has dedicated hardware storage for the
+	 * MAC, read it and initialize dev->enetaddr with it
+	 */
+	ape_mac_read(dev->enetaddr);
+
+	dev->iobase = iobase;
+	dev->priv = priv;
+	dev->init = ape_init;
+	dev->halt = ape_halt;
+	dev->send = ape_send;
+	dev->recv = ape_recv;
+
+	eth_register(dev);
+
+#ifdef CONFIG_CMD_MII)
+	miiphy_register(dev->name, ape_mii_read, ape_mii_write);
+#endif
+
+	return 0;
+}
+
+The exact arguments needed to initialize your device are up to you.  If you
+need to pass more/less arguments, that's fine.  You should also add the
+prototype for your new register function to include/netdev.h.  You might notice
+that many drivers seem to use xxx_initialize() rather than xxx_register().
+This is the old naming convention and should be avoided as it causes confusion
+with the driver-specific init function.
+
+Other than locating the MAC address in dedicated hardware storage, you should
+not touch the hardware in anyway.  That step is handled in the driver-specific
+init function.  Remember that we are only registering the device here, we are
+not checking its state or doing random probing.
+
+ -----------
+  Callbacks
+ -----------
+
+Now that we've registered with the ethernet layer, we can start getting some
+real work done.  You will need four functions:
+	int ape_init(struct eth_device *dev, bd_t *bis);
+	int ape_send(struct eth_device *dev, volatile void *packet, int length);
+	int ape_recv(struct eth_device *dev);
+	int ape_halt(struct eth_device *dev);
+
+The init function checks the hardware (probing/identifying) and gets it ready
+for send/recv operations.  You often do things here such as resetting the MAC
+and/or PHY, and waiting for the link to autonegotiate.  You should also take
+the opportunity to program the device's MAC address with the dev->enetaddr
+member.  This allows the rest of U-Boot to dynamically change the MAC address
+and have the new settings be respected.
+
+The send function does what you think -- transmit the specified packet whose
+size is specified by length (in bytes).  You should not return until the
+transmission is complete, and you should leave the state such that the send
+function can be called multiple times in a row.
+
+The recv function should process packets as long as the hardware has them
+readily available before returning.  i.e. you should drain the hardware fifo.
+The common code sets up packet buffers for you already (NetRxPackets), so there
+is no need to allocate your own.  For each packet you receive, you should call
+the NetReceive() function on it with the packet length.  So the pseudo code
+here would look something like:
+int ape_recv(struct eth_device *dev)
+{
+	int length, i = 0;
+	...
+	while (packets_are_available()) {
+		...
+		length = ape_get_packet(&NetRxPackets[i]);
+		...
+		NetReceive(&NetRxPackets[i], length);
+		...
+		if (++i >= PKTBUFSRX)
+			i = 0;
+		...
+	}
+	...
+	return 0;
+}
+
+The halt function should turn off / disable the hardware and place it back in
+its reset state.
+
+So the call graph at this stage would look something like:
+some net operation (ping / tftp / whatever...)
+	eth_init()
+		dev->init()
+	eth_send()
+		dev->send()
+	eth_rx()
+		dev->recv()
+	eth_halt()
+		dev->halt()
+
+----------------
+ CONFIG_CMD_MII
+----------------
+
+If your device supports banging arbitrary values on the MII bus (pretty much
+every device does), you should add support for the mii command.  Doing so is
+fairly trivial and makes debugging mii issues a lot easier at runtime.
+
+After you have called eth_register() in your driver's register function, add
+a call to miiphy_register() like so:
+#ifdef CONFIG_CMD_MII
+	miiphy_register(dev->name, mii_read, mii_write);
+#endif
+
+And then define the mii_read and mii_write functions if you haven't already.
+Their syntax is straightforward:
+	int mii_read(char *devname, uchar addr, uchar reg, ushort *val);
+	int mii_write(char *devname, uchar addr, uchar reg, ushort val);
+
+The read function should read the register 'reg' from the phy at address 'addr'
+and store the result in the pointer 'val'.  The implementation for the write
+function should logically follow.
Signature · 1 line
1.6.3.3
#5 lore raw

PATCH 2/2 document network driver framework

Quoted 5 lines · Mike Frysinger

---
Ben: some things to note:
- i adopted Jean's proposed naming scheme in the CONFIG section

Is this a generally-accepted naming convention? I personally think it's crap, and since there isn't a single driver that uses it yet, you might say this is a bit ahead of the curve.

Quoted 4 lines

- i deprecated calling the driver-specific entry point "xxx_initialization()" in favor of "xxx_register()" because the former is way too confusing with everyone also having "xxx_init()"

That may be so, but since there isn't a single driver that uses this naming convention, you're wishing something that ain't so.

Other than that, nice writeup. thanks!

Ben

#6 lore raw

PATCH 2/2 document network driver framework

Quoted 9 lines · On Tuesday 21 July 2009 01:09:11 Ben Warren wrote:
Quoted 4 lines · Mike Frysinger

---
Ben: some things to note:
- i adopted Jean's proposed naming scheme in the CONFIG section

Is this a generally-accepted naming convention? I personally think it's crap, and since there isn't a single driver that uses it yet, you might say this is a bit ahead of the curve.

some style needed to be suggested, and what Jean proposed is better than what we have today (which is nothing)

Quoted 6 lines
Quoted 3 lines

- i deprecated calling the driver-specific entry point "xxx_initialization()" in favor of "xxx_register()" because the former is way too confusing with everyone also having "xxx_init()"

That may be so, but since there isn't a single driver that uses this naming convention, you're wishing something that ain't so.

that's why i said "should", deprecated current naming, and noted existing practice. if you agree with the proposal, it's easy enough to run sed on a few files to fix one function name. you agree with my comment that today's behavior is confusing even if you stare and bang on the code day in and day out ? it's even worse for the occasional observer ...
-mike
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 836 bytes
Desc: This is a digitally signed message part.
Url : http://lists.denx.de/pipermail/u-boot/attachments/20090721/ac05a5f9/attachment.pgp

#7 lore raw

PATCH 2/2 document network driver framework

Dear Mike Frysinger,

Quoted 7 lines · In message <[email protected]> you wrote:
Quoted 4 lines

Is this a generally-accepted naming convention? I personally think it's crap, and since there isn't a single driver that uses it yet, you might say this is a bit ahead of the curve.

some style needed to be suggested, and what Jean proposed is better than what we have today (which is nothing)

Arent't we pretty much doing what Linux is doing here, too? I see lots of XXX_init functions in the Linux network code, for example.

Quoted 5 lines

that's why i said "should", deprecated current naming, and noted existing practice. if you agree with the proposal, it's easy enough to run sed on a few files to fix one function name. you agree with my comment that today's behavior is confusing even if you stare and bang on the code day in and day out ? it's even worse for the occasional observer ...

Hm... renaming something from "xxx_init()" into "xxx_register()" because other code is also also using "xxx_init()" does not really make anything clearer to me. Actually IMO it just adds confusion, because if other's use "xxx_init()" I'd expect from a consistence point of view that we use "xxx_init()", too.

Best regards,

Wolfgang Denk

Signature · 5 lines
DENX Software Engineering GmbH,     MD: Wolfgang Denk & Detlev Zundel
HRB 165235 Munich, Office: Kirchenstr.5, D-82194 Groebenzell, Germany
Phone: (+49)-8142-66989-10 Fax: (+49)-8142-66989-80 Email: wd at denx.de
The one who says it cannot be done should never interrupt the one who
is doing it.
#8 lore raw

PATCH 2/2 document network driver framework

Quoted 17 lines · On Tuesday 21 July 2009 03:32:55 Wolfgang Denk wrote:
Quoted 6 lines · Mike Frysinger
Quoted 3 lines

Is this a generally-accepted naming convention? I personally think it's crap, and since there isn't a single driver that uses it yet, you might say this is a bit ahead of the curve.

some style needed to be suggested, and what Jean proposed is better than what we have today (which is nothing)

Arent't we pretty much doing what Linux is doing here, too? I see lots of XXX_init functions in the Linux network code, for example.

Quoted 5 lines

that's why i said "should", deprecated current naming, and noted existing practice. if you agree with the proposal, it's easy enough to run sed on a few files to fix one function name. you agree with my comment that today's behavior is confusing even if you stare and bang on the code day in and day out ? it's even worse for the occasional observer ...

Quoted 5 lines

Hm... renaming something from "xxx_init()" into "xxx_register()" because other code is also also using "xxx_init()" does not really make anything clearer to me. Actually IMO it just adds confusion, because if other's use "xxx_init()" I'd expect from a consistence point of view that we use "xxx_init()", too.

your reply reinforces my point. i'm not talking about xxx_init(), i'm talking about xxx_initialize(). network drivers atm define both -- xxx_initialize() is to initialize the eth_driver structure and *register* with the eth layer, and xxx_init() to *initialize* the hardware. i'm proposing renaming xxx_initialize() to xxx_register().
-mike
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 836 bytes
Desc: This is a digitally signed message part.
Url : http://lists.denx.de/pipermail/u-boot/attachments/20090721/e729fcc0/attachment-0001.pgp

#9 lore raw

PATCH 2/2 document network driver framework

Quoted 28 lines · Mike Frysinger
Quoted 19 lines · On Tuesday 21 July 2009 03:32:55 Wolfgang Denk wrote:
Quoted 7 lines · Mike Frysinger
Quoted 4 lines

Is this a generally-accepted naming convention? I personally think it's crap, and since there isn't a single driver that uses it yet, you might say this is a bit ahead of the curve.

some style needed to be suggested, and what Jean proposed is better than what we have today (which is nothing)

Arent't we pretty much doing what Linux is doing here, too? I see lots of XXX_init functions in the Linux network code, for example.

Quoted 6 lines

that's why i said "should", deprecated current naming, and noted existing practice. if you agree with the proposal, it's easy enough to run sed on a few files to fix one function name. you agree with my comment that today's behavior is confusing even if you stare and bang on the code day in and day out ? it's even worse for the occasional observer ...

Quoted 6 lines

Hm... renaming something from "xxx_init()" into "xxx_register()" because other code is also also using "xxx_init()" does not really make anything clearer to me. Actually IMO it just adds confusion, because if other's use "xxx_init()" I'd expect from a consistence point of view that we use "xxx_init()", too.

Quoted 7 lines

your reply reinforces my point. i'm not talking about xxx_init(), i'm talking about xxx_initialize(). network drivers atm define both -- xxx_initialize() is to initialize the eth_driver structure and *register* with the eth layer, and xxx_init() to *initialize* the hardware. i'm proposing renaming xxx_initialize() to xxx_register().
-mike

I understand what you're saying, and think in principle it's probably a good idea to rename to something other than xxx_initialize(). I just think a document that outlines best practices that are not in use *at all* seems a bit silly.

If we're going to go this way, IMHO we should change all function names at once. It would be easy to do, but would be a huge, potentially intrusive patch that I'm not sure buys us much.

regards,
Ben

#10 lore raw

PATCH 2/2 document network driver framework

Quoted 32 lines · On Tuesday 21 July 2009 16:55:34 Ben Warren wrote:
Quoted 25 lines · Mike Frysinger
Quoted 18 lines · On Tuesday 21 July 2009 03:32:55 Wolfgang Denk wrote:
Quoted 6 lines · Mike Frysinger
Quoted 3 lines

Is this a generally-accepted naming convention? I personally think it's crap, and since there isn't a single driver that uses it yet, you might say this is a bit ahead of the curve.

some style needed to be suggested, and what Jean proposed is better than what we have today (which is nothing)

Arent't we pretty much doing what Linux is doing here, too? I see lots of XXX_init functions in the Linux network code, for example.

Quoted 6 lines

that's why i said "should", deprecated current naming, and noted existing practice. if you agree with the proposal, it's easy enough to run sed on a few files to fix one function name. you agree with my comment that today's behavior is confusing even if you stare and bang on the code day in and day out ? it's even worse for the occasional observer ...

Quoted 5 lines

Hm... renaming something from "xxx_init()" into "xxx_register()" because other code is also also using "xxx_init()" does not really make anything clearer to me. Actually IMO it just adds confusion, because if other's use "xxx_init()" I'd expect from a consistence point of view that we use "xxx_init()", too.

Quoted 5 lines

your reply reinforces my point. i'm not talking about xxx_init(), i'm talking about xxx_initialize(). network drivers atm define both -- xxx_initialize() is to initialize the eth_driver structure and *register* with the eth layer, and xxx_init() to *initialize* the hardware. i'm proposing renaming xxx_initialize() to xxx_register().

Quoted 4 lines

I understand what you're saying, and think in principle it's probably a good idea to rename to something other than xxx_initialize(). I just think a document that outlines best practices that are not in use *at all* seems a bit silly.

considering the document makes note of existing practice and suggests the new naming schema, i think it's fine and shouldnt hold up merging.

Quoted 3 lines

If we're going to go this way, IMHO we should change all function names at once. It would be easy to do, but would be a huge, potentially intrusive patch that I'm not sure buys us much.

how quickly we convert older drivers doesnt matter to me, but if you prefer sooner rather than later, that's easy enough to do and hand off to Wolfgang for the first patch in "next".
-mike
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 836 bytes
Desc: This is a digitally signed message part.
Url : http://lists.denx.de/pipermail/u-boot/attachments/20090721/8d30c793/attachment.pgp

#11 lore raw

PATCH 2/2 document network driver framework

In reply to Ben Warren

Dear Ben Warren,

Quoted 9 lines · In message <[email protected]> you wrote:
Quoted 5 lines · Mike Frysinger

---
Ben: some things to note:
- i adopted Jean's proposed naming scheme in the CONFIG section

Is this a generally-accepted naming convention? I personally think it's crap, and since there isn't a single driver that uses it yet, you might say this is a bit ahead of the curve.

No, this is NOT a generally-accepted naming convention. It has been proposed, and rejected.

Quoted 2 lines

That may be so, but since there isn't a single driver that uses this naming convention, you're wishing something that ain't so.

Thanks for pointing out.

Best regards,

Wolfgang Denk

Signature · 5 lines
DENX Software Engineering GmbH,     MD: Wolfgang Denk & Detlev Zundel
HRB 165235 Munich, Office: Kirchenstr.5, D-82194 Groebenzell, Germany
Phone: (+49)-8142-66989-10 Fax: (+49)-8142-66989-80 Email: wd at denx.de
The only thing necessary for the triumph of evil is for good  men  to
do nothing.                                            - Edmund Burke
#12 lore raw

PATCH 2/2 document network driver framework

In reply to Mike Frysinger
Quoted 31 lines · Mike Frysinger

---
Ben: some things to note:
- i adopted Jean's proposed naming scheme in the CONFIG section
- i deprecated calling the driver-specific entry point "xxx_initialization()" in favor of "xxx_register()" because the former is way too confusing with everyone also having "xxx_init()"

 doc/README.drivers.eth |  199
++++++++++++++++++++++++++++++++++++++++++++++++
 1 files changed, 199 insertions(+), 0 deletions(-)
 create mode 100644 doc/README.drivers.eth
doc/README.drivers.eth new file +5 -0
new file mode 100644
index 0000000..00b4eb1
@@ -0,0 +1,199 @@
+-----------------------
+ Ethernet Driver Guide
+-----------------------
+
+The networking stack in Das U-Boot is designed for multiple network

devices
+to be easily added and controlled at runtime. This guide is meant for people
+who wish to review the net driver stack with an eye towards implementing your
+own ethernet device driver. Here we will describe a new pseudo 'APE' driver.

doc/README.drivers.eth line 16

Quoted 8 lines
doc/README.drivers.eth new file +8 -0
+
+----------------
+ CONFIG Options
+----------------
+
+The common config defines your device should respect (if applicable):
+       CONFIG_MII  - configure in MII mode
+       CONFIG_RMII - configure in RMII mode

That's awfully global, and inflexible. I don't think there's any convention here that should be encouraged. The data bus configuration is a per-device attribute. If some system architects choose to allow this into their config files, far be it from me to protest, but I'm against it.

Also, CONFIG_MII doesn't mean what you think it means. It stems from the obnoxious overlap in terms set forth by IEEE 802.3. The MII in this case refers to the MII Management bus. Defining CONFIG_MII will cause miiphyutil.c to be built, which is a bit-bang MII Management bus driver. It will also enable some MII Management features. CONFIG_MII is therefore a relevant CONFIG option for most drivers.

Andy

#13 lore raw

PATCH 2/2 document network driver framework

Quoted 13 lines · On Wednesday 22 July 2009 19:00:40 Andy Fleming wrote:

doc/README.drivers.eth line 16

Quoted 7 lines · Mike Frysinger

+----------------
+ CONFIG Options
+----------------

doc/README.drivers.eth new file +4 -0
+
+The common config defines your device should respect (if applicable):
+       CONFIG_MII  - configure in MII mode
+       CONFIG_RMII - configure in RMII mode

That's awfully global, and inflexible. I don't think there's any convention here that should be encouraged. The data bus configuration is a per-device attribute. If some system architects choose to allow this into their config files, far be it from me to protest, but I'm against it.

feel free to fix it then. this is a case of me documenting existing practice and not feeling like doing the footwork to fix drivers. you can not like it all you want, but that doesnt change reality.

Quoted 6 lines

Also, CONFIG_MII doesn't mean what you think it means. It stems from the obnoxious overlap in terms set forth by IEEE 802.3. The MII in this case refers to the MII Management bus. Defining CONFIG_MII will cause miiphyutil.c to be built, which is a bit-bang MII Management bus driver. It will also enable some MII Management features. CONFIG_MII is therefore a relevant CONFIG option for most drivers.

yes, that's obvious, so i'm not sure why i missed it (especially considering i also wrote support for it in the Blackfin net driver). i'll update the doc. -mike
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 836 bytes
Desc: This is a digitally signed message part.
Url : http://lists.denx.de/pipermail/u-boot/attachments/20090722/8996d90e/attachment.pgp

#14 lore raw

PATCH 2/2 document network driver framework

In reply to Mike Frysinger
Quoted 24 lines · Mike Frysinger

---
Ben: some things to note:
- i adopted Jean's proposed naming scheme in the CONFIG section
- i deprecated calling the driver-specific entry point "xxx_initialization()" in favor of "xxx_register()" because the former is way too confusing with everyone also having "xxx_init()"

 doc/README.drivers.eth |  199 ++++++++++++++++++++++++++++++++++++++++++++++++
 1 files changed, 199 insertions(+), 0 deletions(-)
 create mode 100644 doc/README.drivers.eth
doc/README.drivers.eth new file +6 -0
new file mode 100644
index 0000000..00b4eb1
@@ -0,0 +1,199 @@
+-----------------------
+ Ethernet Driver Guide
+-----------------------
+
+The networking stack in Das U-Boot is designed for multiple network devices
+to be easily added and controlled at runtime.  This guide is meant for people

doc/README.drivers.eth line 16

Quoted 10 lines
doc/README.drivers.eth new file +10 -0
+who wish to review the net driver stack with an eye towards implementing your
+own ethernet device driver.  Here we will describe a new pseudo 'APE' driver.
+
+----------------
+ CONFIG Options
+----------------
+
+The common config defines your device should respect (if applicable):
+	CONFIG_MII  - configure in MII mode
+	CONFIG_RMII - configure in RMII mode

how will you deal you on your board you have a MII and a RMII chip used I think need to be configure via drivers specifc CONFIG if your driver can not deal with 2 different instance config or via driver init param

doc/README.drivers.eth line 28

Quoted 12 lines
doc/README.drivers.eth new file +12 -0
+
+	CONFIG_CMD_MII - support the MII command
+
+If you want to add config options specific to your driver, you should use the
+naming convention:
+	CONFIG_NET_<DRIVERNAME>_<OPTION>
+For example, if the APE driver could operate in either 16bit or 32bit mode,
+there would probably be the option:
+	CONFIG_NET_APE_32BIT - operate in 32bit mode rather than 16bit default
+
+And to control whether your driver is even enabled, you should use:
+	CONFIG_SYS_NET_<DRIVERNAME>

In my proposition CONFIG_SYS_ will be not use for driver enabling but for hardware specific information

doc/README.drivers.eth line 30

Quoted 2 lines
doc/README.drivers.eth new file +2 -0
+So the APE driver would look like:
+	CONFIG_SYS_NET_APE

so it will be
CONFIG_NET_APE

Quoted 8 lines
doc/README.drivers.eth new file +8 -0
+
+------------------
+ Driver Functions
+------------------
+
+All functions you will be implementing in this document have the return value
+meaning of 0 for success and non-zero for failure.
+

<snip>

Quoted 12 lines

+----------------
+ CONFIG_CMD_MII
+----------------

doc/README.drivers.eth new file +9 -0
+
+If your device supports banging arbitrary values on the MII bus (pretty much
+every device does), you should add support for the mii command.  Doing so is
+fairly trivial and makes debugging mii issues a lot easier at runtime.
+
+After you have called eth_register() in your driver's register function, add
+a call to miiphy_register() like so:
+#ifdef CONFIG_CMD_MII
+	miiphy_register(dev->name, mii_read, mii_write);

doc/README.drivers.eth line 199

Quoted 10 lines
doc/README.drivers.eth new file +10 -0
+#endif
+
+And then define the mii_read and mii_write functions if you haven't already.
+Their syntax is straightforward:
+	int mii_read(char *devname, uchar addr, uchar reg, ushort *val);
+	int mii_write(char *devname, uchar addr, uchar reg, ushort val);
+
+The read function should read the register 'reg' from the phy at address 'addr'
+and store the result in the pointer 'val'.  The implementation for the write
+function should logically follow.

we will rewrite this api when we will push the phylib

Best Regards,
J.

#15 lore raw

PATCH 2/2 document network driver framework

Dear Jean-Christophe PLAGNIOL-VILLARD,

Quoted 5 lines · In message <[email protected]> you wrote:

doc/README.drivers.eth line 28

Quoted 3 lines
doc/README.drivers.eth new file +2 -0
+And to control whether your driver is even enabled, you should use:
+	CONFIG_SYS_NET_<DRIVERNAME>

In my proposition CONFIG_SYS_ will be not use for driver enabling but for hardware specific information

Enabling or disabling a driver i ssomething that a dumb user can do, so it should be done using

CONFIG_<DRIVERNAME>

as in CONFIG_E1000, CONFIG_EEPRO100, etc.

Quoted 4 lines

doc/README.drivers.eth line 30

Quoted 2 lines
doc/README.drivers.eth new file +2 -0
+So the APE driver would look like:
+	CONFIG_SYS_NET_APE

so it will be
CONFIG_NET_APE

No. It should be CONFIG_APE

Best regards,

Wolfgang Denk

Signature · 7 lines
DENX Software Engineering GmbH,     MD: Wolfgang Denk & Detlev Zundel
HRB 165235 Munich, Office: Kirchenstr.5, D-82194 Groebenzell, Germany
Phone: (+49)-8142-66989-10 Fax: (+49)-8142-66989-80 Email: wd at denx.de
Niklaus Wirth has lamented that, whereas Europeans pronounce his name
correctly (Ni-klows Virt), Americans invariably mangle it into (Nick-
les Worth). Which is to say that Europeans  call  him  by  name,  but
Americans call him by value.
#16 lore raw

PATCH 2/2 document network driver framework

Quoted 11 lines · Wolfgang Denk

Dear Jean-Christophe PLAGNIOL-VILLARD,

Quoted 6 lines · In message <[email protected]> you wrote:

doc/README.drivers.eth line 28

Quoted 3 lines
doc/README.drivers.eth new file +2 -0
+And to control whether your driver is even enabled, you should use:
+	CONFIG_SYS_NET_<DRIVERNAME>

In my proposition CONFIG_SYS_ will be not use for driver enabling but for hardware specific information

Quoted 8 lines

Enabling or disabling a driver i ssomething that a dumb user can do, so it should be done using

CONFIG_<DRIVERNAME>

as in CONFIG_E1000, CONFIG_EEPRO100, etc.

Fine with me, although I understand the argument that it doesn't convey enough information, especially when dealing with devices that are more obscure than Intel E1000. CONFIG_SYS_APE is definitely wrong, I think CONFIG_NET_APE should be for networking features such as selectable protocols. Maybe a compromise if one is needed would be CONFIG_NETDEV_APE ? Or is it too verbose?

regards,
Ben

#17 lore raw

PATCH 2/2 document network driver framework

Dear Ben Warren,

Quoted 4 lines · In message <[email protected]> you wrote:
Quoted 4 lines

Enabling or disabling a driver i ssomething that a dumb user can do, so it should be done using

Quoted 8 lines
Quoted 5 lines

CONFIG_<DRIVERNAME>

as in CONFIG_E1000, CONFIG_EEPRO100, etc.

Fine with me, although I understand the argument that it doesn't convey enough information, especially when dealing with devices that are more obscure than Intel E1000. CONFIG_SYS_APE is definitely wrong, I think

I understand the argument, too.

But then I find it extremely useful to use the very same config names as Linux, and Linux uses CONFIG_E100, CONFIG_NATSEMI, CONFIG_NE2K_PCI, CONFIG_8139CP, CONFIG_TLAN, CONFIG_ATP, CONFIG_E1000, ...

Quoted 3 lines

CONFIG_NET_APE should be for networking features such as selectable protocols. Maybe a compromise if one is needed would be CONFIG_NETDEV_APE ? Or is it too verbose?

I think we should remain compatible with Linux here, too.

Best regards,

Wolfgang Denk

Signature · 5 lines
DENX Software Engineering GmbH,     MD: Wolfgang Denk & Detlev Zundel
HRB 165235 Munich, Office: Kirchenstr.5, D-82194 Groebenzell, Germany
Phone: (+49)-8142-66989-10 Fax: (+49)-8142-66989-80 Email: wd at denx.de
Little known fact about Middle Earth:   The Hobbits had a very sophi-
sticated computer network!   It was a Tolkien Ring...
#18 lore raw

PATCH v2 1/1 document network driver framework

In reply to Mike Frysinger

---
v2
- drop CONFIG naming section
- fix MII documentation

 doc/README.drivers.eth |  177 ++++++++++++++++++++++++++++++++++++++++++++++++
 1 files changed, 177 insertions(+), 0 deletions(-)
 create mode 100644 doc/README.drivers.eth
doc/README.drivers.eth new file +177 -0
new file mode 100644
index 0000000..7f21909
@@ -0,0 +1,177 @@
+-----------------------
+ Ethernet Driver Guide
+-----------------------
+
+The networking stack in Das U-Boot is designed for multiple network devices
+to be easily added and controlled at runtime.  This guide is meant for people
+who wish to review the net driver stack with an eye towards implementing your
+own ethernet device driver.  Here we will describe a new pseudo 'APE' driver.
+
+------------------
+ Driver Functions
+------------------
+
+All functions you will be implementing in this document have the return value
+meaning of 0 for success and non-zero for failure.
+
+ ----------
+  Register
+ ----------
+
+When U-Boot initializes, it will call the common function eth_initialize().
+This will in turn call the board-specific board_eth_init() (or if that fails,
+the cpu-specific cpu_eth_init()).  These board-specific functions can do random
+system handling, but ultimately they will call the driver-specific register
+function which in turn takes care of initializing that particular instance.
+
+Keep in mind that you should code the driver to avoid storing state in global
+data as someone might want to hook up two of the same devices to one board.  If
+the state is maintained as global data, it makes using both of those devices
+impossible.
+
+So the call graph at this stage would look something like:
+board_init()
+	eth_initialize()
+		board_eth_init() / cpu_eth_init()
+			driver_register()
+				initialize eth_device
+				eth_register()
+
+At this point in time, the only thing you need to worry about is the driver's
+register function.  The pseudo code would look something like:
+int ape_register(bd_t *bis, int iobase)
+{
+	struct ape_priv *priv;
+	struct eth_device *dev;
+
+	priv = malloc(sizeof(*priv));
+	if (priv == NULL)
+		return 1;
+
+	dev = malloc(sizeof(*dev));
+	if (dev == NULL) {
+		free(priv);
+		return 1;
+	}
+
+	/* setup whatever private state you need */
+
+	memset(dev, 0, sizeof(*dev));
+	sprintf(dev->name, "APE");
+
+	/* if your device has dedicated hardware storage for the
+	 * MAC, read it and initialize dev->enetaddr with it
+	 */
+	ape_mac_read(dev->enetaddr);
+
+	dev->iobase = iobase;
+	dev->priv = priv;
+	dev->init = ape_init;
+	dev->halt = ape_halt;
+	dev->send = ape_send;
+	dev->recv = ape_recv;
+
+	eth_register(dev);
+
+#ifdef CONFIG_CMD_MII)
+	miiphy_register(dev->name, ape_mii_read, ape_mii_write);
+#endif
+
+	return 0;
+}
+
+The exact arguments needed to initialize your device are up to you.  If you
+need to pass more/less arguments, that's fine.  You should also add the
+prototype for your new register function to include/netdev.h.  You might notice
+that many drivers seem to use xxx_initialize() rather than xxx_register().
+This is the old naming convention and should be avoided as it causes confusion
+with the driver-specific init function.
+
+Other than locating the MAC address in dedicated hardware storage, you should
+not touch the hardware in anyway.  That step is handled in the driver-specific
+init function.  Remember that we are only registering the device here, we are
+not checking its state or doing random probing.
+
+ -----------
+  Callbacks
+ -----------
+
+Now that we've registered with the ethernet layer, we can start getting some
+real work done.  You will need four functions:
+	int ape_init(struct eth_device *dev, bd_t *bis);
+	int ape_send(struct eth_device *dev, volatile void *packet, int length);
+	int ape_recv(struct eth_device *dev);
+	int ape_halt(struct eth_device *dev);
+
+The init function checks the hardware (probing/identifying) and gets it ready
+for send/recv operations.  You often do things here such as resetting the MAC
+and/or PHY, and waiting for the link to autonegotiate.  You should also take
+the opportunity to program the device's MAC address with the dev->enetaddr
+member.  This allows the rest of U-Boot to dynamically change the MAC address
+and have the new settings be respected.
+
+The send function does what you think -- transmit the specified packet whose
+size is specified by length (in bytes).  You should not return until the
+transmission is complete, and you should leave the state such that the send
+function can be called multiple times in a row.
+
+The recv function should process packets as long as the hardware has them
+readily available before returning.  i.e. you should drain the hardware fifo.
+The common code sets up packet buffers for you already (NetRxPackets), so there
+is no need to allocate your own.  For each packet you receive, you should call
+the NetReceive() function on it with the packet length.  So the pseudo code
+here would look something like:
+int ape_recv(struct eth_device *dev)
+{
+	int length, i = 0;
+	...
+	while (packets_are_available()) {
+		...
+		length = ape_get_packet(&NetRxPackets[i]);
+		...
+		NetReceive(&NetRxPackets[i], length);
+		...
+		if (++i >= PKTBUFSRX)
+			i = 0;
+		...
+	}
+	...
+	return 0;
+}
+
+The halt function should turn off / disable the hardware and place it back in
+its reset state.
+
+So the call graph at this stage would look something like:
+some net operation (ping / tftp / whatever...)
+	eth_init()
+		dev->init()
+	eth_send()
+		dev->send()
+	eth_rx()
+		dev->recv()
+	eth_halt()
+		dev->halt()
+
+-----------------------------
+ CONFIG_MII / CONFIG_CMD_MII
+-----------------------------
+
+If your device supports banging arbitrary values on the MII bus (pretty much
+every device does), you should add support for the mii command.  Doing so is
+fairly trivial and makes debugging mii issues a lot easier at runtime.
+
+After you have called eth_register() in your driver's register function, add
+a call to miiphy_register() like so:
+#if defined(CONFIG_MII) || defined(CONFIG_CMD_MII)
+	miiphy_register(dev->name, mii_read, mii_write);
+#endif
+
+And then define the mii_read and mii_write functions if you haven't already.
+Their syntax is straightforward:
+	int mii_read(char *devname, uchar addr, uchar reg, ushort *val);
+	int mii_write(char *devname, uchar addr, uchar reg, ushort val);
+
+The read function should read the register 'reg' from the phy at address 'addr'
+and store the result in the pointer 'val'.  The implementation for the write
+function should logically follow.
Signature · 1 line
1.6.4.2
#19 lore raw

PATCH v2 1/1 document network driver framework

Dear Mike Frysinger,

Quoted 9 lines · In message <[email protected]> you wrote:

---
v2
- drop CONFIG naming section
- fix MII documentation

 doc/README.drivers.eth |  177 ++++++++++++++++++++++++++++++++++++++++++++++++
 1 files changed, 177 insertions(+), 0 deletions(-)
 create mode 100644 doc/README.drivers.eth

Best regards,

Wolfgang Denk

Signature · 5 lines
DENX Software Engineering GmbH,     MD: Wolfgang Denk & Detlev Zundel
HRB 165235 Munich, Office: Kirchenstr.5, D-82194 Groebenzell, Germany
Phone: (+49)-8142-66989-10 Fax: (+49)-8142-66989-80 Email: wd at denx.de
Virtue is a relative term.
	-- Spock, "Friday's Child", stardate 3499.1
#20 lore raw

PATCH v2 1/1 document network driver framework

In reply to Mike Frysinger

Dear Ben,

Quoted 9 lines · In message <[email protected]> Mike Frysinger…

---
v2
- drop CONFIG naming section
- fix MII documentation

 doc/README.drivers.eth |  177 ++++++++++++++++++++++++++++++++++++++++++++++++
 1 files changed, 177 insertions(+), 0 deletions(-)
 create mode 100644 doc/README.drivers.eth

Will you run this through the net repo, or shall I pick it up directly?

Best regards,

Wolfgang Denk

Signature · 7 lines
DENX Software Engineering GmbH,     MD: Wolfgang Denk & Detlev Zundel
HRB 165235 Munich, Office: Kirchenstr.5, D-82194 Groebenzell, Germany
Phone: (+49)-8142-66989-10 Fax: (+49)-8142-66989-80 Email: wd at denx.de
How many seconds are there in a year? If I tell you there are 3.155 x
10^7, you won't even try to remember it. On the other hand, who could
forget that, to within half a percent, pi seconds is a nanocentury.
                                                - Tom Duff, Bell Labs
#21 lore raw

PATCH v2 1/1 document network driver framework

Quoted 18 lines · Wolfgang Denk

Dear Ben,

In message <[email protected]> Mike

Quoted 7 lines · Frysinger

---
v2
- drop CONFIG naming section
- fix MII documentation

 doc/README.drivers.eth |  177

++++++++++++++++++++++++++++++++++++++++++++++++

Quoted 2 lines
 1 files changed, 177 insertions(+), 0 deletions(-)
 create mode 100644 doc/README.drivers.eth

Will you run this through the net repo, or shall I pick it up directly?

Quoted 8 lines

I'll take care of it.

Best regards,

Wolfgang Denk

regards,
Ben

Applied
#22 lore raw

PATCH v2 1/1 document network driver framework

In reply to Mike Frysinger

Hi Mike,

Quoted 10 lines · Mike Frysinger

---
v2
- drop CONFIG naming section
- fix MII documentation

 doc/README.drivers.eth |  177 ++++++++++++++++++++++++++++++++++++++++++++++++
 1 files changed, 177 insertions(+), 0 deletions(-)
 create mode 100644 doc/README.drivers.eth

Applied to net repo.

I'll add info about the return code of the initialize() functions in a separate patch. It wouldn't be fair to ask you to do that.

thanks,
Ben