Ethernet.h

00001 /* mbed Microcontroller Library
00002  * Copyright (c) 2006-2013 ARM Limited
00003  *
00004  * Permission is hereby granted, free of charge, to any person obtaining a copy
00005  * of this software and associated documentation files (the "Software"), to deal
00006  * in the Software without restriction, including without limitation the rights
00007  * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
00008  * copies of the Software, and to permit persons to whom the Software is
00009  * furnished to do so, subject to the following conditions:
00010  *
00011  * The above copyright notice and this permission notice shall be included in
00012  * all copies or substantial portions of the Software.
00013  *
00014  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
00015  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
00016  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
00017  * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
00018  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
00019  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
00020  * SOFTWARE.
00021  */
00022 #ifndef MBED_ETHERNET_H
00023 #define MBED_ETHERNET_H
00024 
00025 #include "platform.h"
00026 
00027 #if DEVICE_ETHERNET
00028 
00029 namespace mbed {
00030 
00031 /** An ethernet interface, to use with the ethernet pins.
00032  *
00033  * Example:
00034  * @code
00035  * // Read destination and source from every ethernet packet
00036  *
00037  * #include "mbed.h"
00038  *
00039  * Ethernet eth;
00040  *
00041  * int main() {
00042  *     char buf[0x600];
00043  *
00044  *     while(1) {
00045  *         int size = eth.receive();
00046  *         if(size > 0) {
00047  *             eth.read(buf, size);
00048  *             printf("Destination:  %02X:%02X:%02X:%02X:%02X:%02X\n",
00049  *                     buf[0], buf[1], buf[2], buf[3], buf[4], buf[5]);
00050  *             printf("Source: %02X:%02X:%02X:%02X:%02X:%02X\n",
00051  *                     buf[6], buf[7], buf[8], buf[9], buf[10], buf[11]);
00052  *         }
00053  *
00054  *         wait(1);
00055  *     }
00056  * }
00057  * @endcode
00058  */
00059 class Ethernet {
00060 
00061 public:
00062 
00063     /** Initialise the ethernet interface.
00064      */
00065     Ethernet();
00066 
00067     /** Powers the hardware down.
00068      */
00069     virtual ~Ethernet();
00070 
00071     enum Mode {
00072         AutoNegotiate,
00073         HalfDuplex10,
00074         FullDuplex10,
00075         HalfDuplex100,
00076         FullDuplex100
00077     };
00078 
00079     /** Writes into an outgoing ethernet packet.
00080      *
00081      *  It will append size bytes of data to the previously written bytes.
00082      *
00083      *  @param data An array to write.
00084      *  @param size The size of data.
00085      *
00086      *  @returns
00087      *   The number of written bytes.
00088      */
00089     int write(const char *data, int size);
00090 
00091     /** Send an outgoing ethernet packet.
00092      *
00093      *  After filling in the data in an ethernet packet it must be send.
00094      *  Send will provide a new packet to write to.
00095      *
00096      *  @returns
00097      *    0 if the sending was failed,
00098      *    1 if the package is successfully sent.
00099      */
00100     int send();
00101 
00102     /** Recevies an arrived ethernet packet.
00103      *
00104      *  Receiving an ethernet packet will drop the last received ethernet packet
00105      *  and make a new ethernet packet ready to read.
00106      *  If no ethernet packet is arrived it will return 0.
00107      *
00108      *  @returns
00109      *    0 if no ethernet packet is arrived,
00110      *    or the size of the arrived packet.
00111      */
00112     int receive();
00113 
00114     /** Read from an recevied ethernet packet.
00115      *
00116      *  After receive returnd a number bigger than 0it is
00117      *  possible to read bytes from this packet.
00118      *  Read will write up to size bytes into data.
00119      *
00120      *  It is possible to use read multible times.
00121      *  Each time read will start reading after the last read byte before.
00122      *
00123      *  @returns
00124      *  The number of byte read.
00125      */
00126     int read(char *data, int size);
00127 
00128     /** Gives the ethernet address of the mbed.
00129      *
00130      *  @param mac Must be a pointer to a 6 byte char array to copy the ethernet address in.
00131      */
00132     void address(char *mac);
00133 
00134     /** Returns if an ethernet link is pressent or not. It takes a wile after Ethernet initializion to show up.
00135      *
00136      *  @returns
00137      *   0 if no ethernet link is pressent,
00138      *   1 if an ethernet link is pressent.
00139      *
00140      * Example:
00141      * @code
00142      * // Using the Ethernet link function
00143      * #include "mbed.h"
00144      *
00145      * Ethernet eth;
00146      *
00147      * int main() {
00148      *     wait(1); // Needed after startup.
00149      *     if (eth.link()) {
00150      *          printf("online\n");
00151      *     } else {
00152      *          printf("offline\n");
00153      *     }
00154      * }
00155      * @endcode
00156      */
00157     int link();
00158 
00159     /** Sets the speed and duplex parameters of an ethernet link
00160      *
00161      * - AutoNegotiate      Auto negotiate speed and duplex
00162      * - HalfDuplex10       10 Mbit, half duplex
00163      * - FullDuplex10       10 Mbit, full duplex
00164      * - HalfDuplex100      100 Mbit, half duplex
00165      * - FullDuplex100      100 Mbit, full duplex
00166      *
00167      *  @param mode the speed and duplex mode to set the link to:
00168      */
00169     void set_link(Mode mode);
00170 };
00171 
00172 } // namespace mbed
00173 
00174 #endif
00175 
00176 #endif
00177