doc/html/ref/io-eth-drv-upper-api.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 >Upper Layer 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="Review of the functions"
  26 HREF="io-eth-drv-api-funcs.html"><LINK
  27 REL="NEXT"
  28 TITLE="Calling graph for Transmission and Reception"
  29 HREF="io-eth-call-graph.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-api-funcs.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-call-graph.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-UPPER-API">Upper Layer Functions</H1
  86 ><P
  87 >Upper layer functions are called by drivers to deliver received packets
  88 or transmission completion status back up into the network stack.</P
  89 ><P
  90 >These functions are defined by the hardware independent upper layers of
  91 the networking driver support.  They are present to hide the interfaces
  92 to the actual networking stack so that the hardware drivers may
  93 be used by different network stack implementations without change.</P
  94 ><P
  95 >These functions require a pointer to a <SPAN
  96 CLASS="TYPE"
  97 >struct eth_drv_sc</SPAN
  98 >
  99 which describes the interface at a logical level.  It is assumed that the
 100 low level hardware driver will keep track of this pointer so
 101 it may be passed &#8220;up&#8221; as appropriate.</P
 102 ><DIV
 103 CLASS="SECT2"
 104 ><H2
 105 CLASS="SECT2"
 106 ><A
 107 NAME="IO-ETH-DRV-UPPER-INIT">Callback Init function</H2
 108 ><P
 109 ><TABLE
 110 BORDER="5"
 111 BGCOLOR="#E0E0F0"
 112 WIDTH="70%"
 113 ><TR
 114 ><TD
 115 ><PRE
 116 CLASS="PROGRAMLISTING"
 117 >void (sc-&#62;funs-&#62;eth_drv-&#62;init)(
 118                 struct eth_drv_sc *sc, unsigned char *enaddr)</PRE
 119 ></TD
 120 ></TR
 121 ></TABLE
 122 >
 123 This function establishes the device at initialization time.
 124 It should be called once per device instance only, from the
 125 initialization function, if all is well
 126 (see <A
 127 HREF="io-eth-drv-api-funcs.html#IO-ETH-DRV-API-INIT"
 128 >the Section called <I
 129 >Init function</I
 130 ></A
 131 >).
 132 The hardware should be totally initialized
 133 (<SPAN
 134 CLASS="emphasis"
 135 ><I
 136 CLASS="EMPHASIS"
 137 >not</I
 138 ></SPAN
 139 > &#8220;started&#8221;)
 140 when this function is called.</P
 141 ></DIV
 142 ><DIV
 143 CLASS="SECT2"
 144 ><H2
 145 CLASS="SECT2"
 146 ><A
 147 NAME="IO-ETH-DRV-TX-DONE">Callback Tx-Done function</H2
 148 ><P
 149 ><TABLE
 150 BORDER="5"
 151 BGCOLOR="#E0E0F0"
 152 WIDTH="70%"
 153 ><TR
 154 ><TD
 155 ><PRE
 156 CLASS="PROGRAMLISTING"
 157 >void (sc-&#62;funs-&#62;eth_drv-&#62;tx_done)(
 158                 struct eth_drv_sc *sc,
 159                 unsigned long key, int status)</PRE
 160 ></TD
 161 ></TR
 162 ></TABLE
 163 >
 164 This function is called when a packet completes transmission on the
 165 interface.  The <TT
 166 CLASS="PARAMETER"
 167 ><I
 168 >key</I
 169 ></TT
 170 >
 171 value must be one of the keys provided to
 172 <TT
 173 CLASS="FUNCTION"
 174 ><TT
 175 CLASS="REPLACEABLE"
 176 ><I
 177 >HRDWR</I
 178 ></TT
 179 >_send()</TT
 180 >
 181 above.  The value <TT
 182 CLASS="PARAMETER"
 183 ><I
 184 >status</I
 185 ></TT
 186 > should be non-zero
 187 (details currently undefined) to indicate that an error occurred during the
 188 transmission, and zero if all was well.</P
 189 ><P
 190 >It should be called from the deliver function
 191 (see <A
 192 HREF="io-eth-drv-api-funcs.html#IO-ETH-DRV-API-DELIVER"
 193 >the Section called <I
 194 >Deliver function</I
 195 ></A
 196 >)
 197 or poll function
 198 (see <A
 199 HREF="io-eth-drv-api-funcs.html#IO-ETH-DRV-API-POLL"
 200 >the Section called <I
 201 >Poll function</I
 202 ></A
 203 >).</P
 204 ></DIV
 205 ><DIV
 206 CLASS="SECT2"
 207 ><H2
 208 CLASS="SECT2"
 209 ><A
 210 NAME="IO-ETH-DRV-UPPER-RECV">Callback Receive function</H2
 211 ><P
 212 ><TABLE
 213 BORDER="5"
 214 BGCOLOR="#E0E0F0"
 215 WIDTH="70%"
 216 ><TR
 217 ><TD
 218 ><PRE
 219 CLASS="PROGRAMLISTING"
 220 >void (sc-&#62;funs-&#62;eth_drv-&#62;recv)(struct eth_drv_sc *sc, int len)</PRE
 221 ></TD
 222 ></TR
 223 ></TABLE
 224 >
 225 This function is called to indicate that a packet of length
 226 <TT
 227 CLASS="PARAMETER"
 228 ><I
 229 >len</I
 230 ></TT
 231 > has
 232 arrived at the interface.
 233 The callback
 234 <TT
 235 CLASS="FUNCTION"
 236 ><TT
 237 CLASS="REPLACEABLE"
 238 ><I
 239 >HRDWR</I
 240 ></TT
 241 >_recv()</TT
 242 > function
 243 described above will be used to actually unload the data from the
 244 interface into buffers used by the device independent layers.</P
 245 ><P
 246 >It should be called from the deliver function
 247 (see <A
 248 HREF="io-eth-drv-api-funcs.html#IO-ETH-DRV-API-DELIVER"
 249 >the Section called <I
 250 >Deliver function</I
 251 ></A
 252 >)
 253 or poll function
 254 (see <A
 255 HREF="io-eth-drv-api-funcs.html#IO-ETH-DRV-API-POLL"
 256 >the Section called <I
 257 >Poll function</I
 258 ></A
 259 >).</P
 260 ></DIV
 261 ></DIV
 262 ><DIV
 263 CLASS="NAVFOOTER"
 264 ><HR
 265 ALIGN="LEFT"
 266 WIDTH="100%"><TABLE
 267 SUMMARY="Footer navigation table"
 268 WIDTH="100%"
 269 BORDER="0"
 270 CELLPADDING="0"
 271 CELLSPACING="0"
 272 ><TR
 273 ><TD
 274 WIDTH="33%"
 275 ALIGN="left"
 276 VALIGN="top"
 277 ><A
 278 HREF="io-eth-drv-api-funcs.html"
 279 ACCESSKEY="P"
 280 >Prev</A
 281 ></TD
 282 ><TD
 283 WIDTH="34%"
 284 ALIGN="center"
 285 VALIGN="top"
 286 ><A
 287 HREF="ecos-ref.html"
 288 ACCESSKEY="H"
 289 >Home</A
 290 ></TD
 291 ><TD
 292 WIDTH="33%"
 293 ALIGN="right"
 294 VALIGN="top"
 295 ><A
 296 HREF="io-eth-call-graph.html"
 297 ACCESSKEY="N"
 298 >Next</A
 299 ></TD
 300 ></TR
 301 ><TR
 302 ><TD
 303 WIDTH="33%"
 304 ALIGN="left"
 305 VALIGN="top"
 306 >Review of the functions</TD
 307 ><TD
 308 WIDTH="34%"
 309 ALIGN="center"
 310 VALIGN="top"
 311 ><A
 312 HREF="io-eth-drv-generic1.html"
 313 ACCESSKEY="U"
 314 >Up</A
 315 ></TD
 316 ><TD
 317 WIDTH="33%"
 318 ALIGN="right"
 319 VALIGN="top"
 320 >Calling graph for Transmission and Reception</TD
 321 ></TR
 322 ></TABLE
 323 ></DIV
 324 ></BODY
 325 ></HTML
 326 >