Ethernet.h

00001 /* mbed Microcontroller Library
00002  * Copyright (c) 2006-2013 ARM Limited
00003  *
00004  * Licensed under the Apache License, Version 2.0 (the "License");
00005  * you may not use this file except in compliance with the License.
00006  * You may obtain a copy of the License at
00007  *
00008  *     http://www.apache.org/licenses/LICENSE-2.0
00009  *
00010  * Unless required by applicable law or agreed to in writing, software
00011  * distributed under the License is distributed on an "AS IS" BASIS,
00012  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00013  * See the License for the specific language governing permissions and
00014  * limitations under the License.
00015  */
00016 #ifndef MBED_ETHERNET_H
00017 #define MBED_ETHERNET_H
00018 
00019 #include "platform/platform.h"
00020 #include "platform/NonCopyable.h"
00021 
00022 #if defined (DEVICE_ETHERNET) || defined(DOXYGEN_ONLY)
00023 
00024 namespace mbed {
00025 /** \addtogroup drivers */
00026 
00027 /** An ethernet interface, to use with the ethernet pins.
00028  *
00029  * @note Synchronization level: Not protected
00030  *
00031  * Example:
00032  * @code
00033  * // Read destination and source from every ethernet packet
00034  *
00035  * #include "mbed.h"
00036  *
00037  * Ethernet eth;
00038  *
00039  * int main() {
00040  *     char buf[0x600];
00041  *
00042  *     while(1) {
00043  *         int size = eth.receive();
00044  *         if(size > 0) {
00045  *             eth.read(buf, size);
00046  *             printf("Destination:  %02X:%02X:%02X:%02X:%02X:%02X\n",
00047  *                     buf[0], buf[1], buf[2], buf[3], buf[4], buf[5]);
00048  *             printf("Source: %02X:%02X:%02X:%02X:%02X:%02X\n",
00049  *                     buf[6], buf[7], buf[8], buf[9], buf[10], buf[11]);
00050  *         }
00051  *
00052  *         wait(1);
00053  *     }
00054  * }
00055  * @endcode
00056  * @ingroup drivers
00057  */
00058 class Ethernet : private NonCopyable<Ethernet> {
00059 
00060 public:
00061 
00062     /** Initialise the ethernet interface.
00063      */
00064     Ethernet();
00065 
00066     /** Powers the hardware down.
00067      */
00068     virtual ~Ethernet();
00069 
00070     enum Mode {
00071         AutoNegotiate,
00072         HalfDuplex10,
00073         FullDuplex10,
00074         HalfDuplex100,
00075         FullDuplex100
00076     };
00077 
00078     /** Writes into an outgoing ethernet packet.
00079      *
00080      *  It will append size bytes of data to the previously written bytes.
00081      *
00082      *  @param data An array to write.
00083      *  @param size The size of data.
00084      *
00085      *  @returns
00086      *   The number of written bytes.
00087      */
00088     int write(const char *data, int size);
00089 
00090     /** Send an outgoing ethernet packet.
00091      *
00092      *  After filling in the data in an ethernet packet it must be send.
00093      *  Send will provide a new packet to write to.
00094      *
00095      *  @returns
00096      *    0 if the sending was failed,
00097      *    or the size of the packet successfully sent.
00098      */
00099     int send();
00100 
00101     /** Receives an arrived ethernet packet.
00102      *
00103      *  Receiving an ethernet packet will drop the last received ethernet packet
00104      *  and make a new ethernet packet ready to read.
00105      *  If no ethernet packet is arrived it will return 0.
00106      *
00107      *  @returns
00108      *    0 if no ethernet packet is arrived,
00109      *    or the size of the arrived packet.
00110      */
00111     int receive();
00112 
00113     /** Read from an received ethernet packet.
00114      *
00115      *  After receive returned a number bigger than 0 it is
00116      *  possible to read bytes from this packet.
00117      *
00118      *  @param data      Pointer to data packet
00119      *  @param size      Size of data to be read.
00120      *  @returns         The number of byte read.
00121      *
00122      *  @note It is possible to use read multiple times.
00123      *  Each time read will start reading after the last read byte before.
00124      *
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 present or not. It takes a while after Ethernet initialization to show up.
00135      *
00136      *  @returns
00137      *   0 if no ethernet link is present,
00138      *   1 if an ethernet link is present.
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