+++ /dev/null
-<!-- Copyright (C) 2003 Red Hat, Inc. -->
-<!-- This material may be distributed only subject to the terms -->
-<!-- and conditions set forth in the Open Publication License, v1.0 -->
-<!-- or later (the latest version is presently available at -->
-<!-- http://www.opencontent.org/openpub/). -->
-<!-- Distribution of the work or derivative of the work in any -->
-<!-- standard (paper) book form is prohibited unless prior -->
-<!-- permission is obtained from the copyright holder. -->
-<HTML
-><HEAD
-><TITLE
->Generic Ethernet Device Driver</TITLE
-><meta name="MSSmartTagsPreventParsing" content="TRUE">
-<META
-NAME="GENERATOR"
-CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+
-"><LINK
-REL="HOME"
-TITLE="eCos Reference Manual"
-HREF="ecos-ref.html"><LINK
-REL="UP"
-TITLE="Ethernet Device Drivers"
-HREF="io-eth-drv-generic.html"><LINK
-REL="PREVIOUS"
-TITLE="Ethernet Device Drivers"
-HREF="io-eth-drv-generic.html"><LINK
-REL="NEXT"
-TITLE="Review of the functions"
-HREF="io-eth-drv-api-funcs.html"></HEAD
-><BODY
-CLASS="CHAPTER"
-BGCOLOR="#FFFFFF"
-TEXT="#000000"
-LINK="#0000FF"
-VLINK="#840084"
-ALINK="#0000FF"
-><DIV
-CLASS="NAVHEADER"
-><TABLE
-SUMMARY="Header navigation table"
-WIDTH="100%"
-BORDER="0"
-CELLPADDING="0"
-CELLSPACING="0"
-><TR
-><TH
-COLSPAN="3"
-ALIGN="center"
->eCos Reference Manual</TH
-></TR
-><TR
-><TD
-WIDTH="10%"
-ALIGN="left"
-VALIGN="bottom"
-><A
-HREF="io-eth-drv-generic.html"
-ACCESSKEY="P"
->Prev</A
-></TD
-><TD
-WIDTH="80%"
-ALIGN="center"
-VALIGN="bottom"
-></TD
-><TD
-WIDTH="10%"
-ALIGN="right"
-VALIGN="bottom"
-><A
-HREF="io-eth-drv-api-funcs.html"
-ACCESSKEY="N"
->Next</A
-></TD
-></TR
-></TABLE
-><HR
-ALIGN="LEFT"
-WIDTH="100%"></DIV
-><DIV
-CLASS="CHAPTER"
-><H1
-><A
-NAME="IO-ETH-DRV-GENERIC1">Chapter 46. Generic Ethernet Device Driver</H1
-><DIV
-CLASS="TOC"
-><DL
-><DT
-><B
->Table of Contents</B
-></DT
-><DT
-><A
-HREF="io-eth-drv-generic1.html#IO-ETH-DRV-API"
->Generic Ethernet API</A
-></DT
-><DT
-><A
-HREF="io-eth-drv-api-funcs.html"
->Review of the functions</A
-></DT
-><DT
-><A
-HREF="io-eth-drv-upper-api.html"
->Upper Layer Functions</A
-></DT
-><DT
-><A
-HREF="io-eth-call-graph.html"
->Calling graph for Transmission and Reception</A
-></DT
-></DL
-></DIV
-><DIV
-CLASS="SECT1"
-><H1
-CLASS="SECT1"
-><A
-NAME="IO-ETH-DRV-API">Generic Ethernet API</H1
-><P
->This file provides a simple description of how to write a low-level,
-hardware dependent ethernet driver.</P
-><P
->There is a high-level driver (which is only code — with no state of
-its own) that is part of the stack. There will be one or more low-level
-drivers tied to the actual network hardware. Each of these drivers
-contains one or more driver instances. The intent is that the
-low-level drivers know nothing of the details of the stack that will be
-using them. Thus, the same driver can be used by the
-<SPAN
-CLASS="PRODUCTNAME"
->eCos</SPAN
->
-supported
-<SPAN
-CLASS="ACRONYM"
->TCP/IP</SPAN
->
-stack,
-<SPAN
-CLASS="PRODUCTNAME"
->RedBoot</SPAN
->,
-or any other, with no changes.</P
-><P
->A driver instance is contained within a
-<SPAN
-CLASS="TYPE"
->struct eth_drv_sc</SPAN
->:
-<TABLE
-BORDER="5"
-BGCOLOR="#E0E0F0"
-WIDTH="70%"
-><TR
-><TD
-><PRE
-CLASS="PROGRAMLISTING"
->struct eth_hwr_funs {
- // Initialize hardware (including startup)
- void (*start)(struct eth_drv_sc *sc,
- unsigned char *enaddr,
- int flags);
- // Shut down hardware
- void (*stop)(struct eth_drv_sc *sc);
- // Device control (ioctl pass-thru)
- int (*control)(struct eth_drv_sc *sc,
- unsigned long key,
- void *data,
- int data_length);
- // Query - can a packet be sent?
- int (*can_send)(struct eth_drv_sc *sc);
- // Send a packet of data
- void (*send)(struct eth_drv_sc *sc,
- struct eth_drv_sg *sg_list,
- int sg_len,
- int total_len,
- unsigned long key);
- // Receive [unload] a packet of data
- void (*recv)(struct eth_drv_sc *sc,
- struct eth_drv_sg *sg_list,
- int sg_len);
- // Deliver data to/from device from/to stack memory space
- // (moves lots of memcpy()s out of DSRs into thread)
- void (*deliver)(struct eth_drv_sc *sc);
- // Poll for interrupts/device service
- void (*poll)(struct eth_drv_sc *sc);
- // Get interrupt information from hardware driver
- int (*int_vector)(struct eth_drv_sc *sc);
- // Logical driver interface
- struct eth_drv_funs *eth_drv, *eth_drv_old;
-};
-
-struct eth_drv_sc {
- struct eth_hwr_funs *funs;
- void *driver_private;
- const char *dev_name;
- int state;
- struct arpcom sc_arpcom; /* ethernet common */
-};</PRE
-></TD
-></TR
-></TABLE
-></P
-><DIV
-CLASS="NOTE"
-><BLOCKQUOTE
-CLASS="NOTE"
-><P
-><B
->Note: </B
->If you have two instances of the same hardware, you only need one
-<SPAN
-CLASS="TYPE"
->struct eth_hwr_funs</SPAN
-> shared between them.</P
-></BLOCKQUOTE
-></DIV
-><P
->There is another structure which is used to communicate with the rest of
-the stack:
-<TABLE
-BORDER="5"
-BGCOLOR="#E0E0F0"
-WIDTH="70%"
-><TR
-><TD
-><PRE
-CLASS="PROGRAMLISTING"
->struct eth_drv_funs {
- // Logical driver - initialization
- void (*init)(struct eth_drv_sc *sc,
- unsigned char *enaddr);
- // Logical driver - incoming packet notifier
- void (*recv)(struct eth_drv_sc *sc,
- int total_len);
- // Logical driver - outgoing packet notifier
- void (*tx_done)(struct eth_drv_sc *sc,
- CYG_ADDRESS key,
- int status);
-};</PRE
-></TD
-></TR
-></TABLE
->
-Your driver does <SPAN
-CLASS="emphasis"
-><I
-CLASS="EMPHASIS"
->not</I
-></SPAN
-> create an instance of this
-structure. It is provided for driver code to use in the
-<SPAN
-CLASS="TYPE"
->eth_drv</SPAN
-> member of the function record.
-Its usage is described below in <A
-HREF="io-eth-drv-upper-api.html"
->the Section called <I
->Upper Layer Functions</I
-></A
-></P
-><P
->One more function completes the API with which your driver communicates
-with the rest of the stack:
-<TABLE
-BORDER="5"
-BGCOLOR="#E0E0F0"
-WIDTH="70%"
-><TR
-><TD
-><PRE
-CLASS="PROGRAMLISTING"
->extern void eth_drv_dsr(cyg_vector_t vector,
- cyg_ucount32 count,
- cyg_addrword_t data);</PRE
-></TD
-></TR
-></TABLE
-></P
-><P
->This function is designed so that it can be registered as the DSR for your
-interrupt handler. It will awaken the
-“Network Delivery Thread”
-to call your deliver routine. See <A
-HREF="io-eth-drv-api-funcs.html#IO-ETH-DRV-API-DELIVER"
->the Section called <I
->Deliver function</I
-></A
->.</P
-><P
->You create an instance of <SPAN
-CLASS="TYPE"
->struct eth_drv_sc</SPAN
->
-using the
-<TT
-CLASS="FUNCTION"
->ETH_DRV_SC()</TT
->
-macro which
-sets up the structure, including the prototypes for the functions, etc.
-By doing things this way, if the internal design of the ethernet drivers
-changes (e.g. we need to add a new low-level implementation function),
-existing drivers will no longer compile until updated. This is much
-better than to have all of the definitions in the low-level drivers
-themselves and have them be (quietly) broken if the interfaces change.</P
-><P
->The “magic”
-which gets the drivers started (and indeed, linked) is
-similar to what is used for the I/O subsystem.
-This is done using the
-<TT
-CLASS="FUNCTION"
->NETDEVTAB_ENTRY()</TT
->
-macro, which defines an initialization function
-and the basic data structures for the low-level driver.</P
-><P
-><TABLE
-BORDER="5"
-BGCOLOR="#E0E0F0"
-WIDTH="70%"
-><TR
-><TD
-><PRE
-CLASS="PROGRAMLISTING"
-> typedef struct cyg_netdevtab_entry {
- const char *name;
- bool (*init)(struct cyg_netdevtab_entry *tab);
- void *device_instance;
- unsigned long status;
- } cyg_netdevtab_entry_t;</PRE
-></TD
-></TR
-></TABLE
->
-The <TT
-CLASS="VARNAME"
->device_instance</TT
->
-entry here would point to the <SPAN
-CLASS="TYPE"
->struct eth_drv_sc</SPAN
->
-entry previously defined. This allows the network driver
-setup to work with any class of driver, not just ethernet drivers. In
-the future, there will surely be serial <SPAN
-CLASS="ACRONYM"
->PPP</SPAN
->
-drivers, etc. These will
-use the <TT
-CLASS="FUNCTION"
->NETDEVTAB_ENTRY()</TT
->
-setup to create the basic driver, but they will
-most likely be built on top of other high-level device driver layers.</P
-><P
->To instantiate itself, and connect it to the system,
-a hardware driver will have a template
-(boilerplate) which looks something like this:
-<TABLE
-BORDER="5"
-BGCOLOR="#E0E0F0"
-WIDTH="70%"
-><TR
-><TD
-><PRE
-CLASS="PROGRAMLISTING"
->#include <cyg/infra/cyg_type.h>
-#include <cyg/hal/hal_arch.h>
-#include <cyg/infra/diag.h>
-#include <cyg/hal/drv_api.h>
-#include <cyg/io/eth/netdev.h>
-#include <cyg/io/eth/eth_drv.h>
-
-ETH_DRV_SC(<TT
-CLASS="REPLACEABLE"
-><I
->DRV</I
-></TT
->_sc,
- 0, // No driver specific data needed
- "eth0", // Name for this interface
- <TT
-CLASS="REPLACEABLE"
-><I
->HRDWR</I
-></TT
->_start,
- <TT
-CLASS="REPLACEABLE"
-><I
->HRDWR</I
-></TT
->_stop,
- <TT
-CLASS="REPLACEABLE"
-><I
->HRDWR</I
-></TT
->_control,
- <TT
-CLASS="REPLACEABLE"
-><I
->HRDWR</I
-></TT
->_can_send
- <TT
-CLASS="REPLACEABLE"
-><I
->HRDWR</I
-></TT
->_send,
- <TT
-CLASS="REPLACEABLE"
-><I
->HRDWR</I
-></TT
->_recv,
- <TT
-CLASS="REPLACEABLE"
-><I
->HRDWR</I
-></TT
->_deliver,
- <TT
-CLASS="REPLACEABLE"
-><I
->HRDWR</I
-></TT
->_poll,
- <TT
-CLASS="REPLACEABLE"
-><I
->HRDWR</I
-></TT
->_int_vector
-);
-
-NETDEVTAB_ENTRY(<TT
-CLASS="REPLACEABLE"
-><I
->DRV</I
-></TT
->_netdev,
- "<TT
-CLASS="REPLACEABLE"
-><I
->DRV</I
-></TT
->",
- <TT
-CLASS="REPLACEABLE"
-><I
->DRV_HRDWR</I
-></TT
->_init,
- &<TT
-CLASS="REPLACEABLE"
-><I
->DRV</I
-></TT
->_sc);</PRE
-></TD
-></TR
-></TABLE
-></P
-><P
->This, along with the referenced functions, completely define the driver.</P
-><DIV
-CLASS="NOTE"
-><BLOCKQUOTE
-CLASS="NOTE"
-><P
-><B
->Note: </B
->If one needed the same low-level driver to handle
-multiple similar hardware interfaces, you would need multiple invocations
-of the
-<TT
-CLASS="FUNCTION"
->ETH_DRV_SC()</TT
->/<TT
-CLASS="FUNCTION"
->NETDEVTAB_ENTRY()</TT
->
-macros. You would add a pointer
-to some instance specific data, e.g. containing base addresses, interrupt
-numbers, etc, where the
-<TABLE
-BORDER="5"
-BGCOLOR="#E0E0F0"
-WIDTH="70%"
-><TR
-><TD
-><PRE
-CLASS="PROGRAMLISTING"
-> 0, // No driver specific data</PRE
-></TD
-></TR
-></TABLE
->
-is currently.</P
-></BLOCKQUOTE
-></DIV
-></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-generic.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-api-funcs.html"
-ACCESSKEY="N"
->Next</A
-></TD
-></TR
-><TR
-><TD
-WIDTH="33%"
-ALIGN="left"
-VALIGN="top"
->Ethernet Device Drivers</TD
-><TD
-WIDTH="34%"
-ALIGN="center"
-VALIGN="top"
-><A
-HREF="io-eth-drv-generic.html"
-ACCESSKEY="U"
->Up</A
-></TD
-><TD
-WIDTH="33%"
-ALIGN="right"
-VALIGN="top"
->Review of the functions</TD
-></TR
-></TABLE
-></DIV
-></BODY
-></HTML
->
\ No newline at end of file
projects / karo-tx-redboot.git / blobdiff