io-eth-drv-api-funcs.html

ecos 文档

><PRE
CLASS="PROGRAMLISTING"
>static int <TT
CLASS="REPLACEABLE"
><I
>HRDWR</I
></TT
>_can_send(struct eth_drv_sc *sc)</PRE
></TD
></TR
></TABLE
>
This function is called to determine if it is possible to start the
transmission of a packet on the interface.  Some interfaces will allow
multiple packets to be "queued" and this function allows for the highest
possible utilization of that mode.</P
><P
>Return the number of packets which could be accepted at this time, zero
implies that the interface is saturated/busy.</P
></DIV
><DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
NAME="IO-ETH-DRV-API-SEND">Send function</H2
><P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>struct eth_drv_sg {
    CYG_ADDRESS  buf;
    CYG_ADDRWORD len;
};

static void
<TT
CLASS="REPLACEABLE"
><I
>HRDWR</I
></TT
>_send(
	struct eth_drv_sc *sc,
	struct eth_drv_sg *sg_list, int sg_len,
        int total_len, unsigned long key)</PRE
></TD
></TR
></TABLE
>
This function is used to send a packet of data to the network.  It is
the responsibility of this function to somehow hand the data over to the
hardware interface.  This will most likely require copying, but just the
address/length values could be used by smart hardware.</P
><DIV
CLASS="NOTE"
><BLOCKQUOTE
CLASS="NOTE"
><P
><B
>Note: </B
>All data in/out of the driver is specified via a
&#8220;scatter-gather&#8221;
list.  This is just an array of address/length pairs which describe
sections of data to move (in the order given by the array), as in the
<SPAN
CLASS="TYPE"
>struct eth_drv_sg</SPAN
> defined above and pointed to by
<TT
CLASS="PARAMETER"
><I
>sg_list</I
></TT
>.</P
></BLOCKQUOTE
></DIV
><P
>Once the data has been successfully sent by the interface (or if an
error occurs), the driver should call
<TT
CLASS="FUNCTION"
>(sc-&#62;funs-&#62;eth_drv-&#62;tx_done)()</TT
>
(see <A
HREF="io-eth-drv-upper-api.html#IO-ETH-DRV-TX-DONE"
>the Section called <I
>Callback Tx-Done function</I
></A
>)
using the specified <TT
CLASS="PARAMETER"
><I
>key</I
></TT
>.
Only then will the upper layers release the resources
for that packet and start another transmission.</P
><DIV
CLASS="NOTE"
><BLOCKQUOTE
CLASS="NOTE"
><P
><B
>Note: </B
>In future, this function may be extended so that the data need not be
copied by having the function return a &#8220;disposition&#8221; code
(done, send pending, etc).  At this point, you should move the data to some
&#8220;safe&#8221; location before returning.</P
></BLOCKQUOTE
></DIV
></DIV
><DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
NAME="IO-ETH-DRV-API-DELIVER">Deliver function</H2
><P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>static void
<TT
CLASS="REPLACEABLE"
><I
>HRDWR</I
></TT
>_deliver(struct eth_drv_sc *sc)</PRE
></TD
></TR
></TABLE
>
This function is called from the &#8220;Network Delivery Thread&#8221; in
order to let the device driver do the time-consuming work associated with
receiving a packet &#8212; usually copying the entire packet from the
hardware or a special memory location into the network stack's memory.</P
><P
>After handling any outstanding incoming packets or pending transmission
status, it can unmask the device's interrupts, and free any relevant
resources so it can process further packets.</P
><P
>It will be called when the interrupt handler for the network device
has called
<TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>    eth_drv_dsr( vector, count, (cyg_addrword_t)sc );</PRE
></TD
></TR
></TABLE
>
to alert the system that &#8220;something requires attention.&#8221;
This <TT
CLASS="FUNCTION"
>eth_drv_dsr()</TT
> call must occur from within the
interrupt handler's DSR (not the ISR) or actually <SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>be</I
></SPAN
>
the DSR, whenever it is determined that
the device needs attention from the foreground.  The third parameter
(<TT
CLASS="PARAMETER"
><I
>data</I
></TT
> in the prototype of
<TT
CLASS="FUNCTION"
>eth_drv_dsr()</TT
> <SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>must</I
></SPAN
>
be a valid <SPAN
CLASS="TYPE"
>struct eth_drv_sc</SPAN
> pointer <TT
CLASS="VARNAME"
>sc</TT
>.</P
><P
>The reason for this slightly convoluted train of events is to keep the DSR
(and ISR) execution time as short as possible, so that other activities of
higher priority than network servicing are not denied the CPU by network
traffic.</P
><P
>To deliver a newly-received packet into the network stack, the deliver
routine must call
<TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>(sc-&#62;funs-&#62;eth_drv-&#62;recv)(sc, len);</PRE
></TD
></TR
></TABLE
>
which will in turn call the receive function, which we talk about next.
See also <A
HREF="io-eth-drv-upper-api.html#IO-ETH-DRV-UPPER-RECV"
>the Section called <I
>Callback Receive function</I
></A
> below.</P
></DIV
><DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
NAME="IO-ETH-DRV-API-RECV">Receive function</H2
><P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>static void
<TT
CLASS="REPLACEABLE"
><I
>HRDWR</I
></TT
>_recv(
	struct eth_drv_sc *sc,
	struct eth_drv_sg *sg_list, int sg_len)</PRE
></TD
></TR
></TABLE
>
This function is a call back, only invoked after the
upper-level function
<TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>(sc-&#62;funs-&#62;eth_drv-&#62;recv)(struct eth_drv_sc *sc, int total_len)</PRE
></TD
></TR
></TABLE
>
has been called itself from your deliver function when it knows that a
packet of data is available on the
interface.  The <TT
CLASS="FUNCTION"
>(sc-&#62;funs-&#62;eth_drv-&#62;recv)()</TT
>
function then arranges network buffers
and structures for the data and then calls
<TT
CLASS="FUNCTION"
><TT
CLASS="REPLACEABLE"
><I
>HRDWR</I
></TT
>_recv()</TT
> to actually
move the data from the interface.</P
><P
>A scatter-gather list (<SPAN
CLASS="TYPE"
>struct eth_drv_sg</SPAN
>) is used once more,
just like in the send case.</P
></DIV
><DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
NAME="IO-ETH-DRV-API-POLL">Poll function</H2
><P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>static void
<TT
CLASS="REPLACEABLE"
><I
>HRDWR</I
></TT
>_poll(struct eth_drv_sc *sc)</PRE
></TD
></TR
></TABLE
>
This function is used when in a non-interrupt driven system, e.g. when
interrupts are completely disabled. This allows the driver time to check
whether anything needs doing either for transmission, or to check if
anything has been received, or if any other processing needs doing.</P
><P
>It is perfectly correct and acceptable for the poll function to look like
this:
<TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>static void
<TT
CLASS="REPLACEABLE"
><I
>HRDWR</I
></TT
>_poll(struct eth_drv_sc *sc)
{
   <TT
CLASS="REPLACEABLE"
><I
>my_interrupt_ISR</I
></TT
>(sc);
   <TT
CLASS="REPLACEABLE"
><I
>HRDWR</I
></TT
>_deliver(struct eth_drv_sc *sc);
}</PRE
></TD
></TR
></TABLE
>
provided that both the ISR and the deliver functions are idempotent and
harmless if called when there is no attention needed by the hardware.  Some
devices might not need a call to the ISR here if the deliver function
contains all the &#8220;intelligence.&#8221;</P
></DIV
><DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
NAME="IO-ETH-DRV-API-INT-VECTOR">Interrupt-vector function</H2
><P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>static int
<TT
CLASS="REPLACEABLE"
><I
>HRDWR</I
></TT
>_int_vector(struct eth_drv_sc *sc)</PRE
></TD
></TR
></TABLE
>
This function returns the interrupt vector number used for receive
interrupts.
This is so that the common GDB stubs can detect when to check
for incoming &#8220;CTRL-C&#8221; packets (used to asynchronously
halt the application) when debugging over ethernet.
The GDB stubs need to know which interrupt the ethernet device uses
so that they can mask or unmask that interrupt as required.</P
></DIV
></DIV
><DIV
CLASS="NAVFOOTER"
><HR
ALIGN="LEFT"
WIDTH="100%"><TABLE
SUMMARY="Footer navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
><A
HREF="io-eth-drv-generic1.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="ecos-ref.html"
ACCESSKEY="H"
>Home</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
><A
HREF="io-eth-drv-upper-api.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
>Generic Ethernet Device Driver</TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="io-eth-drv-generic1.html"
ACCESSKEY="U"
>Up</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
>Upper Layer Functions</TD
></TR
></TABLE
></DIV
></BODY
></HTML
>