mirror of
https://github.com/u-boot/u-boot.git
synced 2024-11-28 15:13:31 +08:00
document network driver framework
Signed-off-by: Mike Frysinger <vapier@gentoo.org> Acked-by: Wolfgang Denk <wd@denx.de> Signed-off-by: Ben Warren <biggerbadderben@gmail.com>
This commit is contained in:
Mike Frysinger
Ben Warren
parent
aba8237257
commit
1f1e774ec6
177
doc/README.drivers.eth
Normal file
177
doc/README.drivers.eth
Normal file
@ -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.
|
||||
Loading…
Reference in New Issue
Block a user