Deprecate drivers/Ethernet and hal/ethernet_api (#4)

drivers/Ethernet, and anything Ethernet-related in the “HAL” region has
never been used in Mbed OS 5. Ethernet is not provided like
other core things such as serial.

So drivers/Ethernet.h, drivers/Ethernet.cpp and hal/ethernet_api.h,
and anything referring to them is obsolete.

From 5.0-5.8, Ethernet drivers were written natively as lwIP or
Nanostack drivers, and attached via their native APIs. No Mbed OS APIs
were involved for driver attachment.

Since 5.9, Ethernet drivers are provided by a class derived from
`EMAC`, and is attached to lwIP or Nanostack.

The above assume Ethernet drivers that send and receive Ethernet frames,
in other words it assumes it uses an on-board IP stack. If the interface
has an off-board IP stack, then a custom driver needs to derive from
`EthInterface` or `WifiInterface` and implement the complete socket API
for them.

Applications can use various degrees of abstraction by designating
particular classes:

  * NetworkInterface  - any interface type

  * EthInterface/WifiInterface/MeshInterface/CellularInterface –
    specific interface type, no particular implementation

  * EthernetInterface – Ethernet using on-board stack, default EMAC

  * EthernetInterface<EMAC> - Ethernet using on-board stack and
    particular EMAC

  ESP8266Interface/BG96CellularModem – Particular network interface

The top couple have static “get_default_instance()” methods to locate
an appropriate interface for the current target. Or applications can
nominate their driver specifically using the lower forms.

“EthernetInterface” is a concrete implementation of the abstract
“EthInterface”, it means “Use default onboard stack with default EMAC
driver, defaults selected by get_default_instance”.

That’s only half an abstraction – really portable apps should be saying
“EthInterface::get_default_instance” (not caring about onboard or
offboard), or “NetworkInterface::get_default_instance” (not caring about
Wifi or Ethernet).

drivers/Ethernet.h

@@ -56,6 +56,11 @@ namespace mbed {
  * @endcode
  * @ingroup drivers
  */
+MBED_DEPRECATED(
+    "EthInterface is now the preferred way to get an Ethernet object.",
+    "Alternatively, use NetworkInterface to get an instance of an appropriate network"
+    "interface (WiFi or Ethernet)."
+)
 class Ethernet : private NonCopyable<Ethernet> {
 
 public:

hal/ethernet_api.h

@@ -29,32 +29,67 @@ extern "C" {
 #endif
 
 // Connection constants
-
+MBED_DEPRECATED(
+    "Ethernet drivers are provided by a class derived from `EMAC` attached to"
+    " either lwIP or Nanostack."
+)
 int ethernet_init(void);
+MBED_DEPRECATED(
+    "Ethernet drivers are provided by a class derived from `EMAC` attached to"
+    " either lwIP or Nanostack."
+)
 void ethernet_free(void);
 
 // write size bytes from data to ethernet buffer
 // return num bytes written
 // or -1 if size is too big
+MBED_DEPRECATED(
+    "Ethernet drivers are provided by a class derived from `EMAC` attached to"
+    " either lwIP or Nanostack."
+)
 int ethernet_write(const char *data, int size);
 
 // send ethernet write buffer, returning the packet size sent
+MBED_DEPRECATED(
+    "Ethernet drivers are provided by a class derived from `EMAC` attached to"
+    " either lwIP or Nanostack."
+)
 int ethernet_send(void);
 
 // receive from ethernet buffer, returning packet size, or 0 if no packet
+MBED_DEPRECATED(
+    "Ethernet drivers are provided by a class derived from `EMAC` attached to"
+    " either lwIP or Nanostack."
+)
 int ethernet_receive(void);
 
 // read size bytes in to data, return actual num bytes read (0..size)
 // if data == NULL, throw the bytes away
+MBED_DEPRECATED(
+    "Ethernet drivers are provided by a class derived from `EMAC` attached to"
+    " either lwIP or Nanostack."
+)
 int ethernet_read(char *data, int size);
 
 // get the ethernet address
+MBED_DEPRECATED(
+    "Ethernet drivers are provided by a class derived from `EMAC` attached to"
+    " either lwIP or Nanostack."
+)
 void ethernet_address(char *mac);
 
 // see if the link is up
+MBED_DEPRECATED(
+    "Ethernet drivers are provided by a class derived from `EMAC` attached to"
+    " either lwIP or Nanostack."
+)
 int ethernet_link(void);
 
 // force link settings
+MBED_DEPRECATED(
+    "Ethernet drivers are provided by a class derived from `EMAC` attached to"
+    " either lwIP or Nanostack."
+)
 void ethernet_set_link(int speed, int duplex);
 
 #ifdef __cplusplus