Ethernet.h

00001 /* mbed Microcontroller Library
00002  * Copyright (c) 2006-2013 ARM Limited
00003  * SPDX-License-Identifier: Apache-2.0
00004  *
00005  * Licensed under the Apache License, Version 2.0 (the "License");
00006  * you may not use this file except in compliance with the License.
00007  * You may obtain a copy of the License at
00008  *
00009  *     http://www.apache.org/licenses/LICENSE-2.0
00010  *
00011  * Unless required by applicable law or agreed to in writing, software
00012  * distributed under the License is distributed on an "AS IS" BASIS,
00013  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00014  * See the License for the specific language governing permissions and
00015  * limitations under the License.
00016  */
00017 #ifndef MBED_ETHERNET_H
00018 #define MBED_ETHERNET_H
00019 
00020 #include "platform/platform.h"
00021 #include "platform/NonCopyable.h"
00022 
00023 #if DEVICE_ETHERNET || defined(DOXYGEN_ONLY)
00024 
00025 namespace mbed {
00026 /** \addtogroup drivers */
00027 
00028 /** An ethernet interface, to use with the ethernet pins.
00029  *
00030  * @note Synchronization level: Not protected
00031  *
00032  * Example:
00033  * @code
00034  * // Read destination and source from every ethernet packet
00035  *
00036  * #include "mbed.h"
00037  *
00038  * Ethernet eth;
00039  *
00040  * int main() {
00041  *     char buf[0x600];
00042  *
00043  *     while(1) {
00044  *         int size = eth.receive();
00045  *         if(size > 0) {
00046  *             eth.read(buf, size);
00047  *             printf("Destination:  %02X:%02X:%02X:%02X:%02X:%02X\n",
00048  *                     buf[0], buf[1], buf[2], buf[3], buf[4], buf[5]);
00049  *             printf("Source: %02X:%02X:%02X:%02X:%02X:%02X\n",
00050  *                     buf[6], buf[7], buf[8], buf[9], buf[10], buf[11]);
00051  *         }
00052  *
00053  *         wait(1);
00054  *     }
00055  * }
00056  * @endcode
00057  * @ingroup drivers
00058  */
00059 class Ethernet : private NonCopyable<Ethernet> {
00060 
00061 public:
00062 
00063     /** Initialize 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      *    or the size of the packet successfully sent.
00099      */
00100     int send();
00101 
00102     /** Receives 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 received ethernet packet.
00115      *
00116      *  After receive returned a number bigger than 0 it is
00117      *  possible to read bytes from this packet.
00118      *
00119      *  @param data      Pointer to data packet
00120      *  @param size      Size of data to be read.
00121      *  @returns         The number of byte read.
00122      *
00123      *  @note It is possible to use read multiple times.
00124      *  Each time read will start reading after the last read byte before.
00125      *
00126      */
00127     int read(char *data, int size);
00128 
00129     /** Gives the ethernet address of the mbed.
00130      *
00131      *  @param mac Must be a pointer to a 6 byte char array to copy the ethernet address in.
00132      */
00133     void address(char *mac);
00134 
00135     /** Returns if an ethernet link is present or not. It takes a while after Ethernet initialization to show up.
00136      *
00137      *  @returns
00138      *   0 if no ethernet link is present,
00139      *   1 if an ethernet link is present.
00140      *
00141      * Example:
00142      * @code
00143      * // Using the Ethernet link function
00144      * #include "mbed.h"
00145      *
00146      * Ethernet eth;
00147      *
00148      * int main() {
00149      *     wait(1); // Needed after startup.
00150      *     if (eth.link()) {
00151      *          printf("online\n");
00152      *     } else {
00153      *          printf("offline\n");
00154      *     }
00155      * }
00156      * @endcode
00157      */
00158     int link();
00159 
00160     /** Sets the speed and duplex parameters of an ethernet link
00161      *
00162      * - AutoNegotiate      Auto negotiate speed and duplex
00163      * - HalfDuplex10       10 Mbit, half duplex
00164      * - FullDuplex10       10 Mbit, full duplex
00165      * - HalfDuplex100      100 Mbit, half duplex
00166      * - FullDuplex100      100 Mbit, full duplex
00167      *
00168      *  @param mode the speed and duplex mode to set the link to:
00169      */
00170     void set_link(Mode mode);
00171 };
00172 
00173 } // namespace mbed
00174 
00175 #endif
00176 
00177 #endif