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. -->
12 >Review of the functions</TITLE
13 ><meta name="MSSmartTagsPreventParsing" content="TRUE">
16 CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+
19 TITLE="eCos Reference Manual"
20 HREF="ecos-ref.html"><LINK
22 TITLE="Generic Ethernet Device Driver"
23 HREF="io-eth-drv-generic1.html"><LINK
25 TITLE="Generic Ethernet Device Driver"
26 HREF="io-eth-drv-generic1.html"><LINK
28 TITLE="Upper Layer Functions"
29 HREF="io-eth-drv-upper-api.html"></HEAD
40 SUMMARY="Header navigation table"
49 >eCos Reference Manual</TH
57 HREF="io-eth-drv-generic1.html"
65 >Chapter 46. Generic Ethernet Device Driver</TD
71 HREF="io-eth-drv-upper-api.html"
85 NAME="IO-ETH-DRV-API-FUNCS">Review of the functions</H1
87 >Now a brief review of the functions. This discussion will use generic
88 names for the functions — your driver should use hardware-specific
89 names to maintain uniqueness against any other drivers.</P
95 NAME="IO-ETH-DRV-API-INIT">Init function</H2
104 CLASS="PROGRAMLISTING"
110 >_init(struct cyg_netdevtab_entry *tab)</PRE
115 This function is called as part of system initialization. Its primary
116 function is to decide if the hardware (as indicated via
119 >tab->device_instance</SPAN
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:
131 CLASS="PROGRAMLISTING"
132 > struct eth_drv_sc *sc = (struct eth_drv_sc *)tab->device_instance;
136 >....initialization code....</I
139 // Initialize upper level driver
140 (sc->funs->eth_drv->init)( sc, unsigned char *enaddr );</PRE
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
160 >The ethernet station address
166 world-unique, 48 bit address for this particular ethernet interface.
167 Typically it is provided by the board/hardware manufacturer in ROM.</P
169 >In many packages it is possible for the
174 to be set from RedBoot,
175 (perhaps from 'fconfig' data), hard-coded from
183 A driver should choose a run-time specified
189 preferentially, otherwise (in order) it should use a <SPAN
197 if one has been set, otherwise an <SPAN
209 ethernet driver for an example.</P
218 NAME="IO-ETH-DRV-API-START">Start function</H2
227 CLASS="PROGRAMLISTING"
234 >_start(struct eth_drv_sc *sc, unsigned char *enaddr, int flags)</PRE
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
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
258 > call in the application.
259 This may occur more than once, so this function needs to
260 be prepared for that case.</P
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
287 NAME="IO-ETH-DRV-API-STOP">Stop function</H2
296 CLASS="PROGRAMLISTING"
302 >_stop(struct eth_drv_sc *sc)</PRE
307 This function is the inverse of “start.”
308 It should shut down the hardware, disable the receiver, and keep it from
309 interacting with the physical network.</P
316 NAME="IO-ETH-DRV-API-CONTROL">Control function</H2
325 CLASS="PROGRAMLISTING"
333 struct eth_drv_sc *sc, unsigned long key,
334 void *data, int len)</PRE
339 This function is used to perform low-level “control”
341 interface. These operations would typically be initiated via
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
355 > parameter selects the operation, and the
366 > params point describe,
367 as required, some data for the operation in question.</P
374 >Available Operations:</B
378 >ETH_DRV_SET_MAC_ADDRESS</DT
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
387 >ETH_DRV_GET_IF_STATS_UD, ETH_DRV_GET_IF_STATS</DT
390 >These acquire a set of statistical counters from the interface, and write
391 the information into the memory pointed to by <TT
397 The “UD” 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
401 >The definition of the data structure is in
404 >cyg/io/eth/eth_drv_stats.h</TT
407 >This call is typically made by SNMP, see <A
408 HREF="net-snmp-ecos-port.html"
413 >ETH_DRV_SET_MC_LIST</DT
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
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:
434 CLASS="PROGRAMLISTING"
435 >#define ETH_DRV_MAX_MC 8
436 struct eth_drv_mc_list {
438 unsigned char addrs[ETH_DRV_MAX_MC][ETHER_ADDR_LEN];
446 >ETH_DRV_SET_MC_ALL</DT
449 >This entry instructs the device to receive all multicast packets, and
450 delete any explicit filtering which had been set up.</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
464 NAME="IO-ETH-DRV-API-CAN-SEND">Can-send function</H2
473 CLASS="PROGRAMLISTING"
479 >_can_send(struct eth_drv_sc *sc)</PRE
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
489 >Return the number of packets which could be accepted at this time, zero
490 implies that the interface is saturated/busy.</P
497 NAME="IO-ETH-DRV-API-SEND">Send function</H2
506 CLASS="PROGRAMLISTING"
519 struct eth_drv_sc *sc,
520 struct eth_drv_sg *sg_list, int sg_len,
521 int total_len, unsigned long key)</PRE
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
537 >All data in/out of the driver is specified via a
538 “scatter-gather”
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
543 >struct eth_drv_sg</SPAN
544 > defined above and pointed to by
554 >Once the data has been successfully sent by the interface (or if an
555 error occurs), the driver should call
558 >(sc->funs->eth_drv->tx_done)()</TT
561 HREF="io-eth-drv-upper-api.html#IO-ETH-DRV-TX-DONE"
562 >the Section called <I
563 >Callback Tx-Done function</I
566 using the specified <TT
572 Only then will the upper layers release the resources
573 for that packet and start another transmission.</P
581 >In future, this function may be extended so that the data need not be
582 copied by having the function return a “disposition” code
583 (done, send pending, etc). At this point, you should move the data to some
584 “safe” location before returning.</P
593 NAME="IO-ETH-DRV-API-DELIVER">Deliver function</H2
602 CLASS="PROGRAMLISTING"
609 >_deliver(struct eth_drv_sc *sc)</PRE
614 This function is called from the “Network Delivery Thread” in
615 order to let the device driver do the time-consuming work associated with
616 receiving a packet — usually copying the entire packet from the
617 hardware or a special memory location into the network stack's memory.</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
623 >It will be called when the interrupt handler for the network device
632 CLASS="PROGRAMLISTING"
633 > eth_drv_dsr( vector, count, (cyg_addrword_t)sc );</PRE
638 to alert the system that “something requires attention.”
642 > call must occur from within the
643 interrupt handler's DSR (not the ISR) or actually <SPAN
650 the DSR, whenever it is determined that
651 the device needs attention from the foreground. The third parameter
657 > in the prototype of
670 >struct eth_drv_sc</SPAN
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
681 >To deliver a newly-received packet into the network stack, the deliver
690 CLASS="PROGRAMLISTING"
691 >(sc->funs->eth_drv->recv)(sc, len);</PRE
696 which will in turn call the receive function, which we talk about next.
698 HREF="io-eth-drv-upper-api.html#IO-ETH-DRV-UPPER-RECV"
699 >the Section called <I
700 >Callback Receive function</I
709 NAME="IO-ETH-DRV-API-RECV">Receive function</H2
718 CLASS="PROGRAMLISTING"
726 struct eth_drv_sc *sc,
727 struct eth_drv_sg *sg_list, int sg_len)</PRE
732 This function is a call back, only invoked after the
741 CLASS="PROGRAMLISTING"
742 >(sc->funs->eth_drv->recv)(struct eth_drv_sc *sc, int total_len)</PRE
747 has been called itself from your deliver function when it knows that a
748 packet of data is available on the
751 >(sc->funs->eth_drv->recv)()</TT
753 function then arranges network buffers
754 and structures for the data and then calls
764 move the data from the interface.</P
766 >A scatter-gather list (<SPAN
768 >struct eth_drv_sg</SPAN
769 >) is used once more,
770 just like in the send case.</P
777 NAME="IO-ETH-DRV-API-POLL">Poll function</H2
786 CLASS="PROGRAMLISTING"
793 >_poll(struct eth_drv_sc *sc)</PRE
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
803 >It is perfectly correct and acceptable for the poll function to look like
812 CLASS="PROGRAMLISTING"
819 >_poll(struct eth_drv_sc *sc)
832 >_deliver(struct eth_drv_sc *sc);
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 “intelligence.”</P
848 NAME="IO-ETH-DRV-API-INT-VECTOR">Interrupt-vector function</H2
857 CLASS="PROGRAMLISTING"
864 >_int_vector(struct eth_drv_sc *sc)</PRE
869 This function returns the interrupt vector number used for receive
871 This is so that the common GDB stubs can detect when to check
872 for incoming “CTRL-C” 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
883 SUMMARY="Footer navigation table"
894 HREF="io-eth-drv-generic1.html"
912 HREF="io-eth-drv-upper-api.html"
922 >Generic Ethernet Device Driver</TD
928 HREF="io-eth-drv-generic1.html"
936 >Upper Layer Functions</TD