3 <!-- =============================================================== -->
7 <!-- eCos generic ethernet driver documentation -->
9 <!-- =============================================================== -->
10 <!-- ####COPYRIGHTBEGIN#### -->
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 <!-- =============================================================== -->
23 <!-- ####COPYRIGHTEND#### -->
24 <!-- =============================================================== -->
25 <!-- #####DESCRIPTIONBEGIN#### -->
27 <!-- ####DESCRIPTIONEND#### -->
28 <!-- =============================================================== -->
32 <part id="io-eth-drv-generic">
33 <title>Ethernet Device Drivers</title>
34 <chapter id="io-eth-drv-generic1">
35 <title>Generic Ethernet Device Driver</title>
36 <sect1 id="io-eth-drv-api">
37 <title>Generic Ethernet API</title>
39 This section provides a simple description of how to write a low-level,
40 hardware dependent ethernet driver.
43 There is a high-level driver (which is only code — with no state of
44 its own) that is part of the stack. There will be one or more low-level
45 drivers tied to the actual network hardware. Each of these drivers
46 contains one or more driver instances. The intent is that the
47 low-level drivers know nothing of the details of the stack that will be
48 using them. Thus, the same driver can be used by the
49 <productname>eCos</productname>
51 <acronym>TCP/IP</acronym>
53 <productname>RedBoot</productname>,
54 or any other, with no changes.
57 A driver instance is contained within a
58 <type>struct eth_drv_sc</type>:
61 // Initialize hardware (including startup)
62 void (*start)(struct eth_drv_sc *sc,
63 unsigned char *enaddr,
66 void (*stop)(struct eth_drv_sc *sc);
67 // Device control (ioctl pass-thru)
68 int (*control)(struct eth_drv_sc *sc,
72 // Query - can a packet be sent?
73 int (*can_send)(struct eth_drv_sc *sc);
74 // Send a packet of data
75 void (*send)(struct eth_drv_sc *sc,
76 struct eth_drv_sg *sg_list,
80 // Receive [unload] a packet of data
81 void (*recv)(struct eth_drv_sc *sc,
82 struct eth_drv_sg *sg_list,
84 // Deliver data to/from device from/to stack memory space
85 // (moves lots of memcpy()s out of DSRs into thread)
86 void (*deliver)(struct eth_drv_sc *sc);
87 // Poll for interrupts/device service
88 void (*poll)(struct eth_drv_sc *sc);
89 // Get interrupt information from hardware driver
90 int (*int_vector)(struct eth_drv_sc *sc);
91 // Logical driver interface
92 struct eth_drv_funs *eth_drv, *eth_drv_old;
96 struct eth_hwr_funs *funs;
100 struct arpcom sc_arpcom; /* ethernet common */
104 If you have two instances of the same hardware, you only need one
105 <type>struct eth_hwr_funs</type> shared between them.
107 There is another structure which is used to communicate with the rest of
110 struct eth_drv_funs {
111 // Logical driver - initialization
112 void (*init)(struct eth_drv_sc *sc,
113 unsigned char *enaddr);
114 // Logical driver - incoming packet notifier
115 void (*recv)(struct eth_drv_sc *sc,
117 // Logical driver - outgoing packet notifier
118 void (*tx_done)(struct eth_drv_sc *sc,
123 Your driver does <emphasis>not</emphasis> create an instance of this
124 structure. It is provided for driver code to use in the
125 <type>eth_drv</type> member of the function record.
126 Its usage is described below in <xref linkend=io-eth-drv-upper-api>
128 One more function completes the API with which your driver communicates
129 with the rest of the stack:
131 extern void eth_drv_dsr(cyg_vector_t vector,
133 cyg_addrword_t data);
136 This function is designed so that it can be registered as the DSR for your
137 interrupt handler. It will awaken the
138 “Network Delivery Thread”
139 to call your deliver routine. See <xref linkend=io-eth-drv-api-deliver>.
141 You create an instance of <type>struct eth_drv_sc</type>
143 <function>ETH_DRV_SC()</function>
145 sets up the structure, including the prototypes for the functions, etc.
146 By doing things this way, if the internal design of the ethernet drivers
147 changes (e.g. we need to add a new low-level implementation function),
148 existing drivers will no longer compile until updated. This is much
149 better than to have all of the definitions in the low-level drivers
150 themselves and have them be (quietly) broken if the interfaces change.
152 The “magic”
153 which gets the drivers started (and indeed, linked) is
154 similar to what is used for the I/O subsystem.
155 This is done using the
156 <function>NETDEVTAB_ENTRY()</function>
157 macro, which defines an initialization function
158 and the basic data structures for the low-level driver.
160 <para><programlisting>
161 typedef struct cyg_netdevtab_entry {
163 bool (*init)(struct cyg_netdevtab_entry *tab);
164 void *device_instance;
165 unsigned long status;
166 } cyg_netdevtab_entry_t;
168 The <varname>device_instance</varname>
169 entry here would point to the <type>struct eth_drv_sc</type>
170 entry previously defined. This allows the network driver
171 setup to work with any class of driver, not just ethernet drivers. In
172 the future, there will surely be serial <acronym>PPP</acronym>
173 drivers, etc. These will
174 use the <function>NETDEVTAB_ENTRY()</function>
175 setup to create the basic driver, but they will
176 most likely be built on top of other high-level device driver layers.
178 To instantiate itself, and connect it to the system,
179 a hardware driver will have a template
180 (boilerplate) which looks something like this:
182 #include <cyg/infra/cyg_type.h>
183 #include <cyg/hal/hal_arch.h>
184 #include <cyg/infra/diag.h>
185 #include <cyg/hal/drv_api.h>
186 #include <cyg/io/eth/netdev.h>
187 #include <cyg/io/eth/eth_drv.h>
189 ETH_DRV_SC(<replaceable>DRV</replaceable>_sc,
190 0, // No driver specific data needed
191 "eth0", // Name for this interface
192 <replaceable>HRDWR</replaceable>_start,
193 <replaceable>HRDWR</replaceable>_stop,
194 <replaceable>HRDWR</replaceable>_control,
195 <replaceable>HRDWR</replaceable>_can_send
196 <replaceable>HRDWR</replaceable>_send,
197 <replaceable>HRDWR</replaceable>_recv,
198 <replaceable>HRDWR</replaceable>_deliver,
199 <replaceable>HRDWR</replaceable>_poll,
200 <replaceable>HRDWR</replaceable>_int_vector
203 NETDEVTAB_ENTRY(<replaceable>DRV</replaceable>_netdev,
204 "<replaceable>DRV</replaceable>",
205 <replaceable>DRV_HRDWR</replaceable>_init,
206 &<replaceable>DRV</replaceable>_sc);
209 This, along with the referenced functions, completely define the driver.
211 If one needed the same low-level driver to handle
212 multiple similar hardware interfaces, you would need multiple invocations
214 <function>ETH_DRV_SC()</function>/<function>NETDEVTAB_ENTRY()</function>
215 macros. You would add a pointer
216 to some instance specific data, e.g. containing base addresses, interrupt
217 numbers, etc, where the
219 0, // No driver specific data
224 <sect1 id="io-eth-drv-api-funcs">
225 <title>Review of the functions</title>
227 Now a brief review of the functions. This discussion will use generic
228 names for the functions — your driver should use hardware-specific
229 names to maintain uniqueness against any other drivers.
231 <sect2 id="io-eth-drv-api-init">
232 <title>Init function</title>
235 static bool <replaceable>DRV_HDWR</replaceable>_init(struct cyg_netdevtab_entry *tab)
237 This function is called as part of system initialization. Its primary
238 function is to decide if the hardware (as indicated via
239 <type>tab->device_instance</type>)
240 is working and if the interface needs to be made
241 available in the system. If this is the case, this function needs to
242 finish with a call to the ethernet driver function:
244 struct eth_drv_sc *sc = (struct eth_drv_sc *)tab->device_instance;
245 <replaceable>....initialization code....</replaceable>
246 // Initialize upper level driver
247 (sc->funs->eth_drv->init)( sc, unsigned char *enaddr );
249 where <parameter>enaddr</parameter>
250 is a pointer to the ethernet station address for this unit, to inform
251 the stack of this device's readiness and availability.
253 <note><para>The ethernet station address
254 (<acronym>ESA</acronym>)
256 world-unique, 48 bit address for this particular ethernet interface.
257 Typically it is provided by the board/hardware manufacturer in ROM.
260 In many packages it is possible for the
261 <acronym>ESA</acronym>
262 to be set from RedBoot,
263 (perhaps from 'fconfig' data), hard-coded from
264 <acronym>CDL</acronym>, or from an <acronym>EPROM</acronym>.
265 A driver should choose a run-time specified
266 <acronym>ESA</acronym>
268 preferentially, otherwise (in order) it should use a <acronym>CDL</acronym> specified
269 <acronym>ESA</acronym>
270 if one has been set, otherwise an <acronym>EPROM</acronym> set
271 <acronym>ESA</acronym>, or otherwise
272 fail. See the <filename>cl/cs8900a</filename>
273 ethernet driver for an example.
276 <sect2 id="io-eth-drv-api-start">
277 <title>Start function</title>
281 <replaceable>HRDWR</replaceable>_start(struct eth_drv_sc *sc, unsigned char *enaddr, int flags)
283 This function is called, perhaps much later than system initialization
284 time, when the system (an application) is ready for the interface to
285 become active. The purpose of this function is to set up the hardware
286 interface to start accepting packets from the network and be able to
287 send packets out. The receiver hardware should not be enabled prior to
289 </para><note><para>This function will be called whenever the
290 up/down state of the logical interface changes, e.g. when the IP address
291 changes, or when promiscuous mode is selected by means of an
292 <function>ioctl()</function> call in the application.
293 This may occur more than once, so this function needs to
294 be prepared for that case.
295 </para></note><note><para>
296 In future, the <parameter>flags</parameter>
297 field (currently unused) may be used to tell the
298 function how to start up, e.g. whether interrupts will be used,
299 alternate means of selecting promiscuous mode etc.
302 <sect2 id="io-eth-drv-api-stop">
303 <title>Stop function</title>
306 static void <replaceable>HRDWR</replaceable>_stop(struct eth_drv_sc *sc)
308 This function is the inverse of “start.”
309 It should shut down the hardware, disable the receiver, and keep it from
310 interacting with the physical network.
313 <sect2 id="io-eth-drv-api-control">
314 <title>Control function</title>
318 <replaceable>HRDWR</replaceable>_control(
319 struct eth_drv_sc *sc, unsigned long key,
322 This function is used to perform low-level “control”
324 interface. These operations would typically be initiated via
325 <function>ioctl()</function> calls in the BSD
326 stack, and would be anything that might require the hardware setup to
327 change (i.e. cannot be performed totally by the
328 platform-independent layers).
330 The <parameter>key</parameter> parameter selects the operation, and the
331 <parameter>data</parameter> and <parameter>len</parameter> params point describe,
332 as required, some data for the operation in question.
334 <variablelist><title>Available Operations:</title>
335 <varlistentry><term>ETH_DRV_SET_MAC_ADDRESS</term>
337 This operation sets the ethernet station address (ESA or MAC) for the
338 device. Normally this address is kept in non-volatile memory and is
339 unique in the world. This function must at least set the interface to
340 use the new address. It may also update the NVM as appropriate.
345 <term>ETH_DRV_GET_IF_STATS_UD</term>
346 <term>ETH_DRV_GET_IF_STATS</term>
348 These acquire a set of statistical counters from the interface, and write
349 the information into the memory pointed to by <parameter>data</parameter>.
350 The “UD” variant explicitly instructs the driver to acquire
351 up-to-date values. This is a separate option because doing so may take
352 some time, depending on the hardware.
354 The definition of the data structure is in
355 <filename>cyg/io/eth/eth_drv_stats.h</filename>.
357 This call is typically made by SNMP, see <xref linkend=net-snmp-ecos-port>.
361 <varlistentry><term>ETH_DRV_SET_MC_LIST</term>
363 This entry instructs the device to set up multicast packet filtering
364 to receive only packets addressed to the multicast ESAs in the list pointed
365 to by <parameter>data</parameter>.
367 The format of the data is a 32-bit count of the ESAs in the list, followed
368 by packed bytes which are the ESAs themselves, thus:
370 #define ETH_DRV_MAX_MC 8
371 struct eth_drv_mc_list {
373 unsigned char addrs[ETH_DRV_MAX_MC][ETHER_ADDR_LEN];
379 <varlistentry><term>ETH_DRV_SET_MC_ALL</term>
381 This entry instructs the device to receive all multicast packets, and
382 delete any explicit filtering which had been set up.
388 This function should return zero if the specified operation was
389 completed successfully. It should return non-zero if the operation
390 could not be performed, for any reason.
393 <sect2 id="io-eth-drv-api-can-send">
394 <title>Can-send function</title>
397 static int <replaceable>HRDWR</replaceable>_can_send(struct eth_drv_sc *sc)
399 This function is called to determine if it is possible to start the
400 transmission of a packet on the interface. Some interfaces will allow
401 multiple packets to be "queued" and this function allows for the highest
402 possible utilization of that mode.
404 Return the number of packets which could be accepted at this time, zero
405 implies that the interface is saturated/busy.
408 <sect2 id="io-eth-drv-api-send">
409 <title>Send function</title>
418 <replaceable>HRDWR</replaceable>_send(
419 struct eth_drv_sc *sc,
420 struct eth_drv_sg *sg_list, int sg_len,
421 int total_len, unsigned long key)
423 This function is used to send a packet of data to the network. It is
424 the responsibility of this function to somehow hand the data over to the
425 hardware interface. This will most likely require copying, but just the
426 address/length values could be used by smart hardware.
428 All data in/out of the driver is specified via a
429 “scatter-gather”
430 list. This is just an array of address/length pairs which describe
431 sections of data to move (in the order given by the array), as in the
432 <type>struct eth_drv_sg</type> defined above and pointed to by
433 <parameter>sg_list</parameter>.
435 Once the data has been successfully sent by the interface (or if an
436 error occurs), the driver should call
437 <function>(sc->funs->eth_drv->tx_done)()</function>
438 (see <xref linkend=io-eth-drv-tx-done>)
439 using the specified <parameter>key</parameter>.
440 Only then will the upper layers release the resources
441 for that packet and start another transmission.
443 In future, this function may be extended so that the data need not be
444 copied by having the function return a “disposition” code
445 (done, send pending, etc). At this point, you should move the data to some
446 “safe” location before returning.
449 <sect2 id="io-eth-drv-api-deliver">
450 <title>Deliver function</title>
454 <replaceable>HRDWR</replaceable>_deliver(struct eth_drv_sc *sc)
456 This function is called from the “Network Delivery Thread” in
457 order to let the device driver do the time-consuming work associated with
458 receiving a packet — usually copying the entire packet from the
459 hardware or a special memory location into the network stack's memory.
461 After handling any outstanding incoming packets or pending transmission
462 status, it can unmask the device's interrupts, and free any relevant
463 resources so it can process further packets.
465 It will be called when the interrupt handler for the network device
468 eth_drv_dsr( vector, count, (cyg_addrword_t)sc );
470 to alert the system that “something requires attention.”
471 This <function>eth_drv_dsr()</function> call must occur from within the
472 interrupt handler's DSR (not the ISR) or actually <emphasis>be</emphasis>
473 the DSR, whenever it is determined that
474 the device needs attention from the foreground. The third parameter
475 (<parameter>data</parameter> in the prototype of
476 <function>eth_drv_dsr()</function> <emphasis>must</emphasis>
477 be a valid <type>struct eth_drv_sc</type> pointer <varname>sc</varname>.
479 The reason for this slightly convoluted train of events is to keep the DSR
480 (and ISR) execution time as short as possible, so that other activities of
481 higher priority than network servicing are not denied the CPU by network
484 To deliver a newly-received packet into the network stack, the deliver
487 (sc->funs->eth_drv->recv)(sc, len);
489 which will in turn call the receive function, which we talk about next.
490 See also <xref linkend=io-eth-drv-upper-recv> below.
493 <sect2 id="io-eth-drv-api-recv">
494 <title>Receive function</title>
498 <replaceable>HRDWR</replaceable>_recv(
499 struct eth_drv_sc *sc,
500 struct eth_drv_sg *sg_list, int sg_len)
502 This function is a call back, only invoked after the
505 (sc->funs->eth_drv->recv)(struct eth_drv_sc *sc, int total_len)
507 has been called itself from your deliver function when it knows that a
508 packet of data is available on the
509 interface. The <function>(sc->funs->eth_drv->recv)()</function>
510 function then arranges network buffers
511 and structures for the data and then calls
512 <function><replaceable>HRDWR</replaceable>_recv()</function> to actually
513 move the data from the interface.
515 A scatter-gather list (<type>struct eth_drv_sg</type>) is used once more,
516 just like in the send case.
519 <sect2 id="io-eth-drv-api-poll">
520 <title>Poll function</title>
524 <replaceable>HRDWR</replaceable>_poll(struct eth_drv_sc *sc)
526 This function is used when in a non-interrupt driven system, e.g. when
527 interrupts are completely disabled. This allows the driver time to check
528 whether anything needs doing either for transmission, or to check if
529 anything has been received, or if any other processing needs doing.
531 It is perfectly correct and acceptable for the poll function to look like
535 <replaceable>HRDWR</replaceable>_poll(struct eth_drv_sc *sc)
537 <replaceable>my_interrupt_ISR</replaceable>(sc);
538 <replaceable>HRDWR</replaceable>_deliver(struct eth_drv_sc *sc);
541 provided that both the ISR and the deliver functions are idempotent and
542 harmless if called when there is no attention needed by the hardware. Some
543 devices might not need a call to the ISR here if the deliver function
544 contains all the “intelligence.”
547 <sect2 id="io-eth-drv-api-int-vector">
548 <title>Interrupt-vector function</title>
552 <replaceable>HRDWR</replaceable>_int_vector(struct eth_drv_sc *sc)
554 This function returns the interrupt vector number used for receive
556 This is so that the common GDB stubs can detect when to check
557 for incoming “CTRL-C” packets (used to asynchronously
558 halt the application) when debugging over ethernet.
559 The GDB stubs need to know which interrupt the ethernet device uses
560 so that they can mask or unmask that interrupt as required.
564 <sect1 id=io-eth-drv-upper-api>
565 <title>Upper Layer Functions</title>
567 Upper layer functions are called by drivers to deliver received packets
568 or transmission completion status back up into the network stack.
570 These functions are defined by the hardware independent upper layers of
571 the networking driver support. They are present to hide the interfaces
572 to the actual networking stack so that the hardware drivers may
573 be used by different network stack implementations without change.
575 These functions require a pointer to a <type>struct eth_drv_sc</type>
576 which describes the interface at a logical level. It is assumed that the
577 low level hardware driver will keep track of this pointer so
578 it may be passed “up” as appropriate.
580 <sect2 id="io-eth-drv-upper-init">
581 <title>Callback Init function</title>
584 void (sc->funs->eth_drv->init)(
585 struct eth_drv_sc *sc, unsigned char *enaddr)
587 This function establishes the device at initialization time.
588 It should be called once per device instance only, from the
589 initialization function, if all is well
590 (see <xref linkend=io-eth-drv-api-init>).
591 The hardware should be totally initialized
592 (<emphasis>not</emphasis> “started”)
593 when this function is called.
596 <sect2 id="io-eth-drv-tx-done">
597 <title>Callback Tx-Done function</title>
600 void (sc->funs->eth_drv->tx_done)(
601 struct eth_drv_sc *sc,
602 unsigned long key, int status)
604 This function is called when a packet completes transmission on the
605 interface. The <parameter>key</parameter>
606 value must be one of the keys provided to
607 <function><replaceable>HRDWR</replaceable>_send()</function>
608 above. The value <parameter>status</parameter> should be non-zero
609 (details currently undefined) to indicate that an error occurred during the
610 transmission, and zero if all was well.
612 It should be called from the deliver function
613 (see <xref linkend=io-eth-drv-api-deliver>)
615 (see <xref linkend=io-eth-drv-api-poll>).
618 <sect2 id="io-eth-drv-upper-recv">
619 <title>Callback Receive function</title>
622 void (sc->funs->eth_drv->recv)(struct eth_drv_sc *sc, int len)
624 This function is called to indicate that a packet of length
625 <parameter>len</parameter> has
626 arrived at the interface.
628 <function><replaceable>HRDWR</replaceable>_recv()</function> function
629 described above will be used to actually unload the data from the
630 interface into buffers used by the device independent layers.
632 It should be called from the deliver function
633 (see <xref linkend=io-eth-drv-api-deliver>)
635 (see <xref linkend=io-eth-drv-api-poll>).
639 <sect1 id=io-eth-call-graph>
640 <title>Calling graph for Transmission and Reception</title>
642 It may be worth clarifying further the flow of control in the transmit and
643 receive cases, where the hardware driver does use interrupts and so DSRs to
644 tell the “foreground” when something asynchronous has occurred.
646 <sect2 id=io-eth-call-graph-tx>
647 <title>Transmission</title>
650 Some foreground task such as the application, SNMP “daemon”,
651 DHCP management thread or whatever, calls into network stack to send a
652 packet, or the stack decides to send a packet in response to incoming
653 traffic such as a “ping” or <acronym>ARP</acronym> request.
657 <function><replaceable>HRDWR</replaceable>_can_send()</function>
658 function in the hardware driver.
661 <function><replaceable>HRDWR</replaceable>_can_send()</function>
662 returns the number of available "slots" in which it
663 can store a pending transmit packet.
664 If it cannot send at this time, the packet is queued outside the
665 hardware driver for later; in this case, the hardware is already busy
666 transmitting, so expect an interrupt as described below for completion
667 of the packet currently outgoing.
670 If it can send right now, <replaceable>HRDWR</replaceable>_send() is called.
671 <function><replaceable>HRDWR</replaceable>_send()</function> copies the
672 data into special hardware buffers, or instructs the hardware to
673 “send that.” It also remembers the key that is associated with
677 These calls return … time passes …
680 Asynchronously, the hardware makes an interrupt to say
681 “transmit is done.”
682 The ISR quietens the interrupt source in the hardware and
683 requests that the associated DSR be run.
686 The DSR calls (or <emphasis>is</emphasis>) the
687 <function>eth_drv_dsr()</function> function in the generic driver.
690 <function>eth_drv_dsr()</function> in the generic driver awakens the
691 “Network Delivery Thread” which calls the deliver function
692 <replaceable>HRDWR</replaceable>_deliver() in the driver.
695 The deliver function realizes that a transmit request has completed,
696 and calls the callback tx-done function
697 <function>(sc->funs->eth_drv->tx_done)()</function>
698 with the same key that it remembered for this tx.
701 The callback tx-done function
702 uses the key to find the resources associated with
703 this transmit request; thus the stack knows that the transmit has
704 completed and its resources can be freed.
707 The callback tx-done function
708 also enquires whether <replaceable>HRDWR</replaceable>_can_send() now says
709 “yes, we can send”
710 and if so, dequeues a further transmit request
711 which may have been queued as described above. If so, then
712 <replaceable>HRDWR</replaceable>_send() copies the data into the hardware buffers, or
713 instructs the hardware to "send that" and remembers the new key, as above.
714 These calls then all return to the “Network Delivery Thread”
715 which then sleeps, awaiting the next asynchronous event.
722 <sect2 id=io-eth-call-graph-rx>
723 <title>Receive</title>
726 Asynchronously, the hardware makes an interrupt to say
727 “there is ready data in a receive buffer.”
728 The ISR quietens the interrupt source in the hardware and
729 requests that the associated DSR be run.
732 The DSR calls (or <emphasis>is</emphasis>) the
733 <function>eth_drv_dsr()</function> function in the generic driver.
736 <function>eth_drv_dsr()</function> in the generic driver awakens the
737 “Network Delivery Thread” which calls the deliver function
738 <replaceable>HRDWR</replaceable>_deliver() in the driver.
741 The deliver function realizes that there is data ready and calls
742 the callback receive function
743 <function>(sc->funs->eth_drv->recv)()</function>
744 to tell it how many bytes to prepare for.
747 The callback receive function allocates memory within the stack
748 (eg. <type>MBUFs</type> in BSD/Unix style stacks) and prepares
749 a set of scatter-gather buffers that can
750 accommodate the packet.
753 It then calls back into the hardware driver routine
754 <replaceable>HRDWR</replaceable>_recv().
755 <replaceable>HRDWR</replaceable>_recv() must copy the data from the
756 hardware's buffers into the scatter-gather buffers provided, and return.
759 The network stack now has the data in-hand, and does with it what it will.
760 This might include recursive calls to transmit a response packet.
761 When this all is done, these calls return, and the
762 “Network Delivery Thread”
763 sleeps once more, awaiting the next asynchronous event.