doc/html/ref/io-eth-drv-api-funcs.html

   1 <!-- Copyright (C) 2003 Red Hat, Inc.                                -->
   2 <!-- This material may be distributed only subject to the terms      -->
   3 <!-- and conditions set forth in the Open Publication License, v1.0  -->
   4 <!-- or later (the latest version is presently available at          -->
   5 <!-- http://www.opencontent.org/openpub/).                           -->
   6 <!-- Distribution of the work or derivative of the work in any       -->
   7 <!-- standard (paper) book form is prohibited unless prior           -->
   8 <!-- permission is obtained from the copyright holder.               -->
   9 <HTML
  10 ><HEAD
  11 ><TITLE
  12 >Review of the functions</TITLE
  13 ><meta name="MSSmartTagsPreventParsing" content="TRUE">
  14 <META
  15 NAME="GENERATOR"
  16 CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+
  17 "><LINK
  18 REL="HOME"
  19 TITLE="eCos Reference Manual"
  20 HREF="ecos-ref.html"><LINK
  21 REL="UP"
  22 TITLE="Generic Ethernet Device Driver"
  23 HREF="io-eth-drv-generic1.html"><LINK
  24 REL="PREVIOUS"
  25 TITLE="Generic Ethernet Device Driver"
  26 HREF="io-eth-drv-generic1.html"><LINK
  27 REL="NEXT"
  28 TITLE="Upper Layer Functions"
  29 HREF="io-eth-drv-upper-api.html"></HEAD
  30 ><BODY
  31 CLASS="SECT1"
  32 BGCOLOR="#FFFFFF"
  33 TEXT="#000000"
  34 LINK="#0000FF"
  35 VLINK="#840084"
  36 ALINK="#0000FF"
  37 ><DIV
  38 CLASS="NAVHEADER"
  39 ><TABLE
  40 SUMMARY="Header navigation table"
  41 WIDTH="100%"
  42 BORDER="0"
  43 CELLPADDING="0"
  44 CELLSPACING="0"
  45 ><TR
  46 ><TH
  47 COLSPAN="3"
  48 ALIGN="center"
  49 >eCos Reference Manual</TH
  50 ></TR
  51 ><TR
  52 ><TD
  53 WIDTH="10%"
  54 ALIGN="left"
  55 VALIGN="bottom"
  56 ><A
  57 HREF="io-eth-drv-generic1.html"
  58 ACCESSKEY="P"
  59 >Prev</A
  60 ></TD
  61 ><TD
  62 WIDTH="80%"
  63 ALIGN="center"
  64 VALIGN="bottom"
  65 >Chapter 46. Generic Ethernet Device Driver</TD
  66 ><TD
  67 WIDTH="10%"
  68 ALIGN="right"
  69 VALIGN="bottom"
  70 ><A
  71 HREF="io-eth-drv-upper-api.html"
  72 ACCESSKEY="N"
  73 >Next</A
  74 ></TD
  75 ></TR
  76 ></TABLE
  77 ><HR
  78 ALIGN="LEFT"
  79 WIDTH="100%"></DIV
  80 ><DIV
  81 CLASS="SECT1"
  82 ><H1
  83 CLASS="SECT1"
  84 ><A
  85 NAME="IO-ETH-DRV-API-FUNCS">Review of the functions</H1
  86 ><P
  87 >Now a brief review of the functions.  This discussion will use generic
  88 names for the functions &#8212; your driver should use hardware-specific
  89 names to maintain uniqueness against any other drivers.</P
  90 ><DIV
  91 CLASS="SECT2"
  92 ><H2
  93 CLASS="SECT2"
  94 ><A
  95 NAME="IO-ETH-DRV-API-INIT">Init function</H2
  96 ><P
  97 ><TABLE
  98 BORDER="5"
  99 BGCOLOR="#E0E0F0"
 100 WIDTH="70%"
 101 ><TR
 102 ><TD
 103 ><PRE
 104 CLASS="PROGRAMLISTING"
 105 >static bool <TT
 106 CLASS="REPLACEABLE"
 107 ><I
 108 >DRV_HDWR</I
 109 ></TT
 110 >_init(struct cyg_netdevtab_entry *tab)</PRE
 111 ></TD
 112 ></TR
 113 ></TABLE
 114 >
 115 This function is called as part of system initialization.  Its primary
 116 function is to decide if the hardware (as indicated via
 117 <SPAN
 118 CLASS="TYPE"
 119 >tab-&gt;device_instance</SPAN
 120 >)
 121 is working and if the interface needs to be made
 122 available in the system.  If this is the case, this function needs to
 123 finish with a call to the ethernet driver function:
 124 <TABLE
 125 BORDER="5"
 126 BGCOLOR="#E0E0F0"
 127 WIDTH="70%"
 128 ><TR
 129 ><TD
 130 ><PRE
 131 CLASS="PROGRAMLISTING"
 132 >    struct eth_drv_sc *sc = (struct eth_drv_sc *)tab-&#62;device_instance;
 133     <TT
 134 CLASS="REPLACEABLE"
 135 ><I
 136 >....initialization code....</I
 137 ></TT
 138 >
 139     // Initialize upper level driver
 140     (sc-&gt;funs-&gt;eth_drv-&gt;init)( sc, unsigned char *enaddr );</PRE
 141 ></TD
 142 ></TR
 143 ></TABLE
 144 >
 145 where <TT
 146 CLASS="PARAMETER"
 147 ><I
 148 >enaddr</I
 149 ></TT
 150 >
 151 is a pointer to the ethernet station address for this unit, to inform
 152 the stack of this device's readiness and availability.</P
 153 ><DIV
 154 CLASS="NOTE"
 155 ><BLOCKQUOTE
 156 CLASS="NOTE"
 157 ><P
 158 ><B
 159 >Note: </B
 160 >The ethernet station address
 161 (<SPAN
 162 CLASS="ACRONYM"
 163 >ESA</SPAN
 164 >)
 165 is supposed to be a
 166 world-unique, 48 bit address for this particular ethernet interface.
 167 Typically it is provided by the board/hardware manufacturer in ROM.</P
 168 ><P
 169 >In many packages it is possible for the
 170 <SPAN
 171 CLASS="ACRONYM"
 172 >ESA</SPAN
 173 >
 174 to be set from RedBoot,
 175 (perhaps from 'fconfig' data), hard-coded from
 176 <SPAN
 177 CLASS="ACRONYM"
 178 >CDL</SPAN
 179 >, or from an <SPAN
 180 CLASS="ACRONYM"
 181 >EPROM</SPAN
 182 >.
 183 A driver should choose a run-time specified
 184 <SPAN
 185 CLASS="ACRONYM"
 186 >ESA</SPAN
 187 >
 188 (e.g. from RedBoot)
 189 preferentially, otherwise (in order) it should use a <SPAN
 190 CLASS="ACRONYM"
 191 >CDL</SPAN
 192 > specified
 193 <SPAN
 194 CLASS="ACRONYM"
 195 >ESA</SPAN
 196 >
 197 if one has been set, otherwise an <SPAN
 198 CLASS="ACRONYM"
 199 >EPROM</SPAN
 200 > set
 201 <SPAN
 202 CLASS="ACRONYM"
 203 >ESA</SPAN
 204 >, or otherwise
 205 fail. See the <TT
 206 CLASS="FILENAME"
 207 >cl/cs8900a</TT
 208 >
 209 ethernet driver for an example.</P
 210 ></BLOCKQUOTE
 211 ></DIV
 212 ></DIV
 213 ><DIV
 214 CLASS="SECT2"
 215 ><H2
 216 CLASS="SECT2"
 217 ><A
 218 NAME="IO-ETH-DRV-API-START">Start function</H2
 219 ><P
 220 ><TABLE
 221 BORDER="5"
 222 BGCOLOR="#E0E0F0"
 223 WIDTH="70%"
 224 ><TR
 225 ><TD
 226 ><PRE
 227 CLASS="PROGRAMLISTING"
 228 >static void
 229 <TT
 230 CLASS="REPLACEABLE"
 231 ><I
 232 >HRDWR</I
 233 ></TT
 234 >_start(struct eth_drv_sc *sc, unsigned char *enaddr, int flags)</PRE
 235 ></TD
 236 ></TR
 237 ></TABLE
 238 >
 239 This function is called, perhaps much later than system initialization
 240 time, when the system (an application) is ready for the interface to
 241 become active.  The purpose of this function is to set up the hardware
 242 interface to start accepting packets from the network and be able to
 243 send packets out.  The receiver hardware should not be enabled prior to
 244 this call.</P
 245 ><DIV
 246 CLASS="NOTE"
 247 ><BLOCKQUOTE
 248 CLASS="NOTE"
 249 ><P
 250 ><B
 251 >Note: </B
 252 >This function will be called whenever the
 253 up/down state of the logical interface changes, e.g. when the IP address
 254 changes, or when promiscuous mode is selected by means of an
 255 <TT
 256 CLASS="FUNCTION"
 257 >ioctl()</TT
 258 > call in the application.
 259 This may occur more than once, so this function needs to
 260 be prepared for that case.</P
 261 ></BLOCKQUOTE
 262 ></DIV
 263 ><DIV
 264 CLASS="NOTE"
 265 ><BLOCKQUOTE
 266 CLASS="NOTE"
 267 ><P
 268 ><B
 269 >Note: </B
 270 >In future, the <TT
 271 CLASS="PARAMETER"
 272 ><I
 273 >flags</I
 274 ></TT
 275 >
 276 field (currently unused) may be used to tell the
 277 function how to start up, e.g. whether interrupts will be used,
 278 alternate means of selecting promiscuous mode etc.</P
 279 ></BLOCKQUOTE
 280 ></DIV
 281 ></DIV
 282 ><DIV
 283 CLASS="SECT2"
 284 ><H2
 285 CLASS="SECT2"
 286 ><A
 287 NAME="IO-ETH-DRV-API-STOP">Stop function</H2
 288 ><P
 289 ><TABLE
 290 BORDER="5"
 291 BGCOLOR="#E0E0F0"
 292 WIDTH="70%"
 293 ><TR
 294 ><TD
 295 ><PRE
 296 CLASS="PROGRAMLISTING"
 297 >static void <TT
 298 CLASS="REPLACEABLE"
 299 ><I
 300 >HRDWR</I
 301 ></TT
 302 >_stop(struct eth_drv_sc *sc)</PRE
 303 ></TD
 304 ></TR
 305 ></TABLE
 306 >
 307 This function is the inverse of &#8220;start.&#8221;
 308 It should shut down the hardware, disable the receiver, and keep it from
 309 interacting with the physical network.</P
 310 ></DIV
 311 ><DIV
 312 CLASS="SECT2"
 313 ><H2
 314 CLASS="SECT2"
 315 ><A
 316 NAME="IO-ETH-DRV-API-CONTROL">Control function</H2
 317 ><P
 318 ><TABLE
 319 BORDER="5"
 320 BGCOLOR="#E0E0F0"
 321 WIDTH="70%"
 322 ><TR
 323 ><TD
 324 ><PRE
 325 CLASS="PROGRAMLISTING"
 326 >static int
 327 <TT
 328 CLASS="REPLACEABLE"
 329 ><I
 330 >HRDWR</I
 331 ></TT
 332 >_control(
 333         struct eth_drv_sc *sc, unsigned long key,
 334         void *data, int len)</PRE
 335 ></TD
 336 ></TR
 337 ></TABLE
 338 >
 339 This function is used to perform low-level &#8220;control&#8221;
 340 operations on the
 341 interface.  These operations would typically be initiated via
 342 <TT
 343 CLASS="FUNCTION"
 344 >ioctl()</TT
 345 > calls in the BSD
 346 stack, and would be anything that might require the hardware setup to
 347 change (i.e. cannot be performed totally by the
 348 platform-independent layers).</P
 349 ><P
 350 >The <TT
 351 CLASS="PARAMETER"
 352 ><I
 353 >key</I
 354 ></TT
 355 > parameter selects the operation, and the
 356 <TT
 357 CLASS="PARAMETER"
 358 ><I
 359 >data</I
 360 ></TT
 361 > and <TT
 362 CLASS="PARAMETER"
 363 ><I
 364 >len</I
 365 ></TT
 366 > params point describe,
 367 as required, some data for the operation in question.</P
 368 ><P
 369 ></P
 370 ><DIV
 371 CLASS="VARIABLELIST"
 372 ><P
 373 ><B
 374 >Available Operations:</B
 375 ></P
 376 ><DL
 377 ><DT
 378 >ETH_DRV_SET_MAC_ADDRESS</DT
 379 ><DD
 380 ><P
 381 >This operation sets the ethernet station address (ESA or MAC) for the
 382 device.  Normally this address is kept in non-volatile memory and is
 383 unique in the world.  This function must at least set the interface to
 384 use the new address.  It may also update the NVM as appropriate.</P
 385 ></DD
 386 ><DT
 387 >ETH_DRV_GET_IF_STATS_UD, ETH_DRV_GET_IF_STATS</DT
 388 ><DD
 389 ><P
 390 >These acquire a set of statistical counters from the interface, and write
 391 the information into the memory pointed to by <TT
 392 CLASS="PARAMETER"
 393 ><I
 394 >data</I
 395 ></TT
 396 >.
 397 The &#8220;UD&#8221; variant explicitly instructs the driver to acquire
 398 up-to-date values.  This is a separate option because doing so may take
 399 some time, depending on the hardware.</P
 400 ><P
 401 >The definition of the data structure is in
 402 <TT
 403 CLASS="FILENAME"
 404 >cyg/io/eth/eth_drv_stats.h</TT
 405 >.</P
 406 ><P
 407 >This call is typically made by SNMP, see <A
 408 HREF="net-snmp-ecos-port.html"
 409 >Chapter 47</A
 410 >.</P
 411 ></DD
 412 ><DT
 413 >ETH_DRV_SET_MC_LIST</DT
 414 ><DD
 415 ><P
 416 >This entry instructs the device to set up multicast packet filtering
 417 to receive only packets addressed to the multicast ESAs in the list pointed
 418 to by <TT
 419 CLASS="PARAMETER"
 420 ><I
 421 >data</I
 422 ></TT
 423 >.</P
 424 ><P
 425 >The format of the data is a 32-bit count of the ESAs in the list, followed
 426 by packed bytes which are the ESAs themselves, thus:
 427 <TABLE
 428 BORDER="5"
 429 BGCOLOR="#E0E0F0"
 430 WIDTH="70%"
 431 ><TR
 432 ><TD
 433 ><PRE
 434 CLASS="PROGRAMLISTING"
 435 >#define ETH_DRV_MAX_MC 8
 436 struct eth_drv_mc_list {
 437     int len;
 438     unsigned char addrs[ETH_DRV_MAX_MC][ETHER_ADDR_LEN];
 439 };</PRE
 440 ></TD
 441 ></TR
 442 ></TABLE
 443 ></P
 444 ></DD
 445 ><DT
 446 >ETH_DRV_SET_MC_ALL</DT
 447 ><DD
 448 ><P
 449 >This entry instructs the device to receive all multicast packets, and
 450 delete any explicit filtering which had been set up.</P
 451 ></DD
 452 ></DL
 453 ></DIV
 454 ><P
 455 >This function should return zero if the specified operation was
 456 completed successfully.  It should return non-zero if the operation
 457 could not be performed, for any reason.</P
 458 ></DIV
 459 ><DIV
 460 CLASS="SECT2"
 461 ><H2
 462 CLASS="SECT2"
 463 ><A
 464 NAME="IO-ETH-DRV-API-CAN-SEND">Can-send function</H2
 465 ><P
 466 ><TABLE
 467 BORDER="5"
 468 BGCOLOR="#E0E0F0"
 469 WIDTH="70%"
 470 ><TR
 471 ><TD
 472 ><PRE
 473 CLASS="PROGRAMLISTING"
 474 >static int <TT
 475 CLASS="REPLACEABLE"
 476 ><I
 477 >HRDWR</I
 478 ></TT
 479 >_can_send(struct eth_drv_sc *sc)</PRE
 480 ></TD
 481 ></TR
 482 ></TABLE
 483 >
 484 This function is called to determine if it is possible to start the
 485 transmission of a packet on the interface.  Some interfaces will allow
 486 multiple packets to be "queued" and this function allows for the highest
 487 possible utilization of that mode.</P
 488 ><P
 489 >Return the number of packets which could be accepted at this time, zero
 490 implies that the interface is saturated/busy.</P
 491 ></DIV
 492 ><DIV
 493 CLASS="SECT2"
 494 ><H2
 495 CLASS="SECT2"
 496 ><A
 497 NAME="IO-ETH-DRV-API-SEND">Send function</H2
 498 ><P
 499 ><TABLE
 500 BORDER="5"
 501 BGCOLOR="#E0E0F0"
 502 WIDTH="70%"
 503 ><TR
 504 ><TD
 505 ><PRE
 506 CLASS="PROGRAMLISTING"
 507 >struct eth_drv_sg {
 508     CYG_ADDRESS  buf;
 509     CYG_ADDRWORD len;
 510 };
 511
 512 static void
 513 <TT
 514 CLASS="REPLACEABLE"
 515 ><I
 516 >HRDWR</I
 517 ></TT
 518 >_send(
 519         struct eth_drv_sc *sc,
 520         struct eth_drv_sg *sg_list, int sg_len,
 521         int total_len, unsigned long key)</PRE
 522 ></TD
 523 ></TR
 524 ></TABLE
 525 >
 526 This function is used to send a packet of data to the network.  It is
 527 the responsibility of this function to somehow hand the data over to the
 528 hardware interface.  This will most likely require copying, but just the
 529 address/length values could be used by smart hardware.</P
 530 ><DIV
 531 CLASS="NOTE"
 532 ><BLOCKQUOTE
 533 CLASS="NOTE"
 534 ><P
 535 ><B
 536 >Note: </B
 537 >All data in/out of the driver is specified via a
 538 &#8220;scatter-gather&#8221;
 539 list.  This is just an array of address/length pairs which describe
 540 sections of data to move (in the order given by the array), as in the
 541 <SPAN
 542 CLASS="TYPE"
 543 >struct eth_drv_sg</SPAN
 544 > defined above and pointed to by
 545 <TT
 546 CLASS="PARAMETER"
 547 ><I
 548 >sg_list</I
 549 ></TT
 550 >.</P
 551 ></BLOCKQUOTE
 552 ></DIV
 553 ><P
 554 >Once the data has been successfully sent by the interface (or if an
 555 error occurs), the driver should call
 556 <TT
 557 CLASS="FUNCTION"
 558 >(sc-&#62;funs-&#62;eth_drv-&#62;tx_done)()</TT
 559 >
 560 (see <A
 561 HREF="io-eth-drv-upper-api.html#IO-ETH-DRV-TX-DONE"
 562 >the Section called <I
 563 >Callback Tx-Done function</I
 564 ></A
 565 >)
 566 using the specified <TT
 567 CLASS="PARAMETER"
 568 ><I
 569 >key</I
 570 ></TT
 571 >.
 572 Only then will the upper layers release the resources
 573 for that packet and start another transmission.</P
 574 ><DIV
 575 CLASS="NOTE"
 576 ><BLOCKQUOTE
 577 CLASS="NOTE"
 578 ><P
 579 ><B
 580 >Note: </B
 581 >In future, this function may be extended so that the data need not be
 582 copied by having the function return a &#8220;disposition&#8221; code
 583 (done, send pending, etc).  At this point, you should move the data to some
 584 &#8220;safe&#8221; location before returning.</P
 585 ></BLOCKQUOTE
 586 ></DIV
 587 ></DIV
 588 ><DIV
 589 CLASS="SECT2"
 590 ><H2
 591 CLASS="SECT2"
 592 ><A
 593 NAME="IO-ETH-DRV-API-DELIVER">Deliver function</H2
 594 ><P
 595 ><TABLE
 596 BORDER="5"
 597 BGCOLOR="#E0E0F0"
 598 WIDTH="70%"
 599 ><TR
 600 ><TD
 601 ><PRE
 602 CLASS="PROGRAMLISTING"
 603 >static void
 604 <TT
 605 CLASS="REPLACEABLE"
 606 ><I
 607 >HRDWR</I
 608 ></TT
 609 >_deliver(struct eth_drv_sc *sc)</PRE
 610 ></TD
 611 ></TR
 612 ></TABLE
 613 >
 614 This function is called from the &#8220;Network Delivery Thread&#8221; in
 615 order to let the device driver do the time-consuming work associated with
 616 receiving a packet &#8212; usually copying the entire packet from the
 617 hardware or a special memory location into the network stack's memory.</P
 618 ><P
 619 >After handling any outstanding incoming packets or pending transmission
 620 status, it can unmask the device's interrupts, and free any relevant
 621 resources so it can process further packets.</P
 622 ><P
 623 >It will be called when the interrupt handler for the network device
 624 has called
 625 <TABLE
 626 BORDER="5"
 627 BGCOLOR="#E0E0F0"
 628 WIDTH="70%"
 629 ><TR
 630 ><TD
 631 ><PRE
 632 CLASS="PROGRAMLISTING"
 633 >    eth_drv_dsr( vector, count, (cyg_addrword_t)sc );</PRE
 634 ></TD
 635 ></TR
 636 ></TABLE
 637 >
 638 to alert the system that &#8220;something requires attention.&#8221;
 639 This <TT
 640 CLASS="FUNCTION"
 641 >eth_drv_dsr()</TT
 642 > call must occur from within the
 643 interrupt handler's DSR (not the ISR) or actually <SPAN
 644 CLASS="emphasis"
 645 ><I
 646 CLASS="EMPHASIS"
 647 >be</I
 648 ></SPAN
 649 >
 650 the DSR, whenever it is determined that
 651 the device needs attention from the foreground.  The third parameter
 652 (<TT
 653 CLASS="PARAMETER"
 654 ><I
 655 >data</I
 656 ></TT
 657 > in the prototype of
 658 <TT
 659 CLASS="FUNCTION"
 660 >eth_drv_dsr()</TT
 661 > <SPAN
 662 CLASS="emphasis"
 663 ><I
 664 CLASS="EMPHASIS"
 665 >must</I
 666 ></SPAN
 667 >
 668 be a valid <SPAN
 669 CLASS="TYPE"
 670 >struct eth_drv_sc</SPAN
 671 > pointer <TT
 672 CLASS="VARNAME"
 673 >sc</TT
 674 >.</P
 675 ><P
 676 >The reason for this slightly convoluted train of events is to keep the DSR
 677 (and ISR) execution time as short as possible, so that other activities of
 678 higher priority than network servicing are not denied the CPU by network
 679 traffic.</P
 680 ><P
 681 >To deliver a newly-received packet into the network stack, the deliver
 682 routine must call
 683 <TABLE
 684 BORDER="5"
 685 BGCOLOR="#E0E0F0"
 686 WIDTH="70%"
 687 ><TR
 688 ><TD
 689 ><PRE
 690 CLASS="PROGRAMLISTING"
 691 >(sc-&#62;funs-&#62;eth_drv-&#62;recv)(sc, len);</PRE
 692 ></TD
 693 ></TR
 694 ></TABLE
 695 >
 696 which will in turn call the receive function, which we talk about next.
 697 See also <A
 698 HREF="io-eth-drv-upper-api.html#IO-ETH-DRV-UPPER-RECV"
 699 >the Section called <I
 700 >Callback Receive function</I
 701 ></A
 702 > below.</P
 703 ></DIV
 704 ><DIV
 705 CLASS="SECT2"
 706 ><H2
 707 CLASS="SECT2"
 708 ><A
 709 NAME="IO-ETH-DRV-API-RECV">Receive function</H2
 710 ><P
 711 ><TABLE
 712 BORDER="5"
 713 BGCOLOR="#E0E0F0"
 714 WIDTH="70%"
 715 ><TR
 716 ><TD
 717 ><PRE
 718 CLASS="PROGRAMLISTING"
 719 >static void
 720 <TT
 721 CLASS="REPLACEABLE"
 722 ><I
 723 >HRDWR</I
 724 ></TT
 725 >_recv(
 726         struct eth_drv_sc *sc,
 727         struct eth_drv_sg *sg_list, int sg_len)</PRE
 728 ></TD
 729 ></TR
 730 ></TABLE
 731 >
 732 This function is a call back, only invoked after the
 733 upper-level function
 734 <TABLE
 735 BORDER="5"
 736 BGCOLOR="#E0E0F0"
 737 WIDTH="70%"
 738 ><TR
 739 ><TD
 740 ><PRE
 741 CLASS="PROGRAMLISTING"
 742 >(sc-&#62;funs-&#62;eth_drv-&#62;recv)(struct eth_drv_sc *sc, int total_len)</PRE
 743 ></TD
 744 ></TR
 745 ></TABLE
 746 >
 747 has been called itself from your deliver function when it knows that a
 748 packet of data is available on the
 749 interface.  The <TT
 750 CLASS="FUNCTION"
 751 >(sc-&#62;funs-&#62;eth_drv-&#62;recv)()</TT
 752 >
 753 function then arranges network buffers
 754 and structures for the data and then calls
 755 <TT
 756 CLASS="FUNCTION"
 757 ><TT
 758 CLASS="REPLACEABLE"
 759 ><I
 760 >HRDWR</I
 761 ></TT
 762 >_recv()</TT
 763 > to actually
 764 move the data from the interface.</P
 765 ><P
 766 >A scatter-gather list (<SPAN
 767 CLASS="TYPE"
 768 >struct eth_drv_sg</SPAN
 769 >) is used once more,
 770 just like in the send case.</P
 771 ></DIV
 772 ><DIV
 773 CLASS="SECT2"
 774 ><H2
 775 CLASS="SECT2"
 776 ><A
 777 NAME="IO-ETH-DRV-API-POLL">Poll function</H2
 778 ><P
 779 ><TABLE
 780 BORDER="5"
 781 BGCOLOR="#E0E0F0"
 782 WIDTH="70%"
 783 ><TR
 784 ><TD
 785 ><PRE
 786 CLASS="PROGRAMLISTING"
 787 >static void
 788 <TT
 789 CLASS="REPLACEABLE"
 790 ><I
 791 >HRDWR</I
 792 ></TT
 793 >_poll(struct eth_drv_sc *sc)</PRE
 794 ></TD
 795 ></TR
 796 ></TABLE
 797 >
 798 This function is used when in a non-interrupt driven system, e.g. when
 799 interrupts are completely disabled. This allows the driver time to check
 800 whether anything needs doing either for transmission, or to check if
 801 anything has been received, or if any other processing needs doing.</P
 802 ><P
 803 >It is perfectly correct and acceptable for the poll function to look like
 804 this:
 805 <TABLE
 806 BORDER="5"
 807 BGCOLOR="#E0E0F0"
 808 WIDTH="70%"
 809 ><TR
 810 ><TD
 811 ><PRE
 812 CLASS="PROGRAMLISTING"
 813 >static void
 814 <TT
 815 CLASS="REPLACEABLE"
 816 ><I
 817 >HRDWR</I
 818 ></TT
 819 >_poll(struct eth_drv_sc *sc)
 820 {
 821    <TT
 822 CLASS="REPLACEABLE"
 823 ><I
 824 >my_interrupt_ISR</I
 825 ></TT
 826 >(sc);
 827    <TT
 828 CLASS="REPLACEABLE"
 829 ><I
 830 >HRDWR</I
 831 ></TT
 832 >_deliver(struct eth_drv_sc *sc);
 833 }</PRE
 834 ></TD
 835 ></TR
 836 ></TABLE
 837 >
 838 provided that both the ISR and the deliver functions are idempotent and
 839 harmless if called when there is no attention needed by the hardware.  Some
 840 devices might not need a call to the ISR here if the deliver function
 841 contains all the &#8220;intelligence.&#8221;</P
 842 ></DIV
 843 ><DIV
 844 CLASS="SECT2"
 845 ><H2
 846 CLASS="SECT2"
 847 ><A
 848 NAME="IO-ETH-DRV-API-INT-VECTOR">Interrupt-vector function</H2
 849 ><P
 850 ><TABLE
 851 BORDER="5"
 852 BGCOLOR="#E0E0F0"
 853 WIDTH="70%"
 854 ><TR
 855 ><TD
 856 ><PRE
 857 CLASS="PROGRAMLISTING"
 858 >static int
 859 <TT
 860 CLASS="REPLACEABLE"
 861 ><I
 862 >HRDWR</I
 863 ></TT
 864 >_int_vector(struct eth_drv_sc *sc)</PRE
 865 ></TD
 866 ></TR
 867 ></TABLE
 868 >
 869 This function returns the interrupt vector number used for receive
 870 interrupts.
 871 This is so that the common GDB stubs can detect when to check
 872 for incoming &#8220;CTRL-C&#8221; packets (used to asynchronously
 873 halt the application) when debugging over ethernet.
 874 The GDB stubs need to know which interrupt the ethernet device uses
 875 so that they can mask or unmask that interrupt as required.</P
 876 ></DIV
 877 ></DIV
 878 ><DIV
 879 CLASS="NAVFOOTER"
 880 ><HR
 881 ALIGN="LEFT"
 882 WIDTH="100%"><TABLE
 883 SUMMARY="Footer navigation table"
 884 WIDTH="100%"
 885 BORDER="0"
 886 CELLPADDING="0"
 887 CELLSPACING="0"
 888 ><TR
 889 ><TD
 890 WIDTH="33%"
 891 ALIGN="left"
 892 VALIGN="top"
 893 ><A
 894 HREF="io-eth-drv-generic1.html"
 895 ACCESSKEY="P"
 896 >Prev</A
 897 ></TD
 898 ><TD
 899 WIDTH="34%"
 900 ALIGN="center"
 901 VALIGN="top"
 902 ><A
 903 HREF="ecos-ref.html"
 904 ACCESSKEY="H"
 905 >Home</A
 906 ></TD
 907 ><TD
 908 WIDTH="33%"
 909 ALIGN="right"
 910 VALIGN="top"
 911 ><A
 912 HREF="io-eth-drv-upper-api.html"
 913 ACCESSKEY="N"
 914 >Next</A
 915 ></TD
 916 ></TR
 917 ><TR
 918 ><TD
 919 WIDTH="33%"
 920 ALIGN="left"
 921 VALIGN="top"
 922 >Generic Ethernet Device Driver</TD
 923 ><TD
 924 WIDTH="34%"
 925 ALIGN="center"
 926 VALIGN="top"
 927 ><A
 928 HREF="io-eth-drv-generic1.html"
 929 ACCESSKEY="U"
 930 >Up</A
 931 ></TD
 932 ><TD
 933 WIDTH="33%"
 934 ALIGN="right"
 935 VALIGN="top"
 936 >Upper Layer Functions</TD
 937 ></TR
 938 ></TABLE
 939 ></DIV
 940 ></BODY
 941 ></HTML
 942 >