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.h"
00020 
00021 #if DEVICE_ETHERNET
00022 
00023 namespace mbed {
00024 
00025 /** An ethernet interface, to use with the ethernet pins.
00026  *
00027  * @Note Synchronization level: Not protected
00028  *
00029  * Example:
00030  * @code
00031  * // Read destination and source from every ethernet packet
00032  *
00033  * #include "mbed.h"
00034  *
00035  * Ethernet eth;
00036  *
00037  * int main() {
00038  *     char buf[0x600];
00039  *
00040  *     while(1) {
00041  *         int size = eth.receive();
00042  *         if(size > 0) {
00043  *             eth.read(buf, size);
00044  *             printf("Destination:  %02X:%02X:%02X:%02X:%02X:%02X\n",
00045  *                     buf[0], buf[1], buf[2], buf[3], buf[4], buf[5]);
00046  *             printf("Source: %02X:%02X:%02X:%02X:%02X:%02X\n",
00047  *                     buf[6], buf[7], buf[8], buf[9], buf[10], buf[11]);
00048  *         }
00049  *
00050  *         wait(1);
00051  *     }
00052  * }
00053  * @endcode
00054  */
00055 class Ethernet {
00056 
00057 public:
00058 
00059     /** Initialise the ethernet interface.
00060      */
00061     Ethernet();
00062 
00063     /** Powers the hardware down.
00064      */
00065     virtual ~Ethernet();
00066 
00067     enum Mode {
00068         AutoNegotiate,
00069         HalfDuplex10,
00070         FullDuplex10,
00071         HalfDuplex100,
00072         FullDuplex100
00073     };
00074 
00075     /** Writes into an outgoing ethernet packet.
00076      *
00077      *  It will append size bytes of data to the previously written bytes.
00078      *
00079      *  @param data An array to write.
00080      *  @param size The size of data.
00081      *
00082      *  @returns
00083      *   The number of written bytes.
00084      */
00085     int write(const char *data, int size);
00086 
00087     /** Send an outgoing ethernet packet.
00088      *
00089      *  After filling in the data in an ethernet packet it must be send.
00090      *  Send will provide a new packet to write to.
00091      *
00092      *  @returns
00093      *    0 if the sending was failed,
00094      *    or the size of the packet successfully sent.
00095      */
00096     int send();
00097 
00098     /** Recevies an arrived ethernet packet.
00099      *
00100      *  Receiving an ethernet packet will drop the last received ethernet packet
00101      *  and make a new ethernet packet ready to read.
00102      *  If no ethernet packet is arrived it will return 0.
00103      *
00104      *  @returns
00105      *    0 if no ethernet packet is arrived,
00106      *    or the size of the arrived packet.
00107      */
00108     int receive();
00109 
00110     /** Read from an recevied ethernet packet.
00111      *
00112      *  After receive returnd a number bigger than 0it is
00113      *  possible to read bytes from this packet.
00114      *  Read will write up to size bytes into data.
00115      *
00116      *  It is possible to use read multible times.
00117      *  Each time read will start reading after the last read byte before.
00118      *
00119      *  @returns
00120      *  The number of byte read.
00121      */
00122     int read(char *data, int size);
00123 
00124     /** Gives the ethernet address of the mbed.
00125      *
00126      *  @param mac Must be a pointer to a 6 byte char array to copy the ethernet address in.
00127      */
00128     void address(char *mac);
00129 
00130     /** Returns if an ethernet link is pressent or not. It takes a wile after Ethernet initializion to show up.
00131      *
00132      *  @returns
00133      *   0 if no ethernet link is pressent,
00134      *   1 if an ethernet link is pressent.
00135      *
00136      * Example:
00137      * @code
00138      * // Using the Ethernet link function
00139      * #include "mbed.h"
00140      *
00141      * Ethernet eth;
00142      *
00143      * int main() {
00144      *     wait(1); // Needed after startup.
00145      *     if (eth.link()) {
00146      *          printf("online\n");
00147      *     } else {
00148      *          printf("offline\n");
00149      *     }
00150      * }
00151      * @endcode
00152      */
00153     int link();
00154 
00155     /** Sets the speed and duplex parameters of an ethernet link
00156      *
00157      * - AutoNegotiate      Auto negotiate speed and duplex
00158      * - HalfDuplex10       10 Mbit, half duplex
00159      * - FullDuplex10       10 Mbit, full duplex
00160      * - HalfDuplex100      100 Mbit, half duplex
00161      * - FullDuplex100      100 Mbit, full duplex
00162      *
00163      *  @param mode the speed and duplex mode to set the link to:
00164      */
00165     void set_link(Mode mode);
00166 };
00167 
00168 } // namespace mbed
00169 
00170 #endif
00171 
00172 #endif