clarify eth driver halt/recv steps

The dev->halt() func can be called at any time, and the dev->recv() func does not need to use NetRxPackets[] when calling NetReceive(). Signed-off-by: Mike Frysinger <vapier@gentoo.org> Signed-off-by: Ben Warren <biggerbadderben@gmail.com>

clarify eth driver halt/recv steps
The dev->halt() func can be called at any time, and the dev->recv() func does not need to use NetRxPackets[] when calling NetReceive(). Signed-off-by: Mike Frysinger <vapier@gentoo.org> Signed-off-by: Ben Warren <biggerbadderben@gmail.com>
Mike Frysinger · Ben Warren
1 parent 497ab0eec5
Showing 1 changed file with 8 additions and 5 deletions Side-by-side Diff
doc/README.drivers.eth
@@ -122,10 +122,12 @@
  
 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:
+For each packet you receive, you should call the NetReceive() function on it
+along with the packet length.  The common code sets up packet buffers for you
+already in the .bss (NetRxPackets), so there should be no need to allocate your
+own.  This doesn't mean you must use the NetRxPackets array however; you're
+free to call the NetReceive() function with any buffer you wish.  So the pseudo
+code here would look something like:
 int ape_recv(struct eth_device *dev)
 {
 	int length, i = 0;
@@ -145,7 +147,8 @@
 }
  
 The halt function should turn off / disable the hardware and place it back in
-its reset state.
+its reset state.  It can be called at any time (before any call to the related
+init function), so make sure it can handle this sort of thing.
  
 So the call graph at this stage would look something like:
 some net operation (ping / tftp / whatever...)
...	...	@@ -122,10 +122,12 @@
122	122
123	123	The recv function should process packets as long as the hardware has them
124	124	readily available before returning. i.e. you should drain the hardware fifo.
125		-The common code sets up packet buffers for you already (NetRxPackets), so there
126		-is no need to allocate your own. For each packet you receive, you should call
127		-the NetReceive() function on it with the packet length. So the pseudo code
128		-here would look something like:
	125	+For each packet you receive, you should call the NetReceive() function on it
	126	+along with the packet length. The common code sets up packet buffers for you
	127	+already in the .bss (NetRxPackets), so there should be no need to allocate your
	128	+own. This doesn't mean you must use the NetRxPackets array however; you're
	129	+free to call the NetReceive() function with any buffer you wish. So the pseudo
	130	+code here would look something like:
129	131	int ape_recv(struct eth_device *dev)
130	132	{
131	133	int length, i = 0;
...	...	@@ -145,7 +147,8 @@
145	147	}
146	148
147	149	The halt function should turn off / disable the hardware and place it back in
148		-its reset state.
	150	+its reset state. It can be called at any time (before any call to the related
	151	+init function), so make sure it can handle this sort of thing.
149	152
150	153	So the call graph at this stage would look something like:
151	154	some net operation (ping / tftp / whatever...)