rpp/include/rpp/eth.h

   1 /**
   2  * Ethernet Communication RPP API header file.
   3  *
   4  * @file eth.h
   5  *
   6  * @copyright Copyright (C) 2013 Czech Technical University in Prague
   7  *
   8  * @author Carlos Jenkins <carlos@jenkins.co.cr>
   9  * @author Rostislav Lisový
  10  * @author Jan Doležal <pm.jenik@gmail.com>
  11  */
  12
  13 #ifndef __RPP_ETH_H
  14 #define __RPP_ETH_H
  15
  16 #include <stdio.h>
  17
  18 #include "os/os.h"
  19 #include "lwip/netif.h"
  20
  21 /* this MAC address is used when user put NULL on the right place when calling postInit function */
  22 /**
  23  * Default MAC address for interface.
  24  */
  25 #define RPP_MAC_ADDR             { 0x12 /* Unicast, Locally administered */, 0x34, 0x56, 0x78, 0x9A, 0xBC }
  26 #if STATIC_IP_ADDRESS
  27 /**
  28  * When static IP is configured in lwipopts.h, this IP address is used for interface.
  29  */
  30 #define RPP_IP_ADDR               0xC0A8F701 /* 192.168.247.1   IP4_ADDR(rppip, 192,168,0,10);       */
  31 /**
  32  * When static IP is configured in lwipopts.h, this NETMASK address is used for interface.
  33  */
  34 #define RPP_NETMASK               0xFFFFFF00 /* 255.255.255.0   IP4_ADDR(rppnetmask, 255,255,255,0); */
  35 /**
  36  * When static IP is configured in lwipopts.h, this Gateway address is used for interface.
  37  */
  38 #define RPP_GW                    0xC0A8F7FE /* 192.168.247.254 IP4_ADDR(rppgw, 192,168,0,254);      */
  39 #endif
  40
  41 /**
  42  * While scanning phy addresses no alive phy was found.
  43  * Return value of rpp_eth_hw_init() function.
  44  */
  45 #define NO_PHY_ALIVE             -1
  46 /**
  47  * Scanning default phy address, it was found it's not alive.
  48  * Return value of rpp_eth_hw_init() function.
  49  */
  50 #define DFLT_PHY_NOT_ALIVE       -1
  51 /**
  52  * When setting autonegotiation parameters to EMAC module, there was found impossible mode (usually on timeout of autonegotiation).
  53  * Return value of rpp_eth_hw_init_postInit() function.
  54  */
  55 #define UNKN_DUPLEX_MODE         -2 /* this could mean that autonegotiation was not completed yet */
  56 /**
  57  * Phy is down error.
  58  * Return value of rpp_eth_init_postInit() function.
  59  */
  60 #define PHY_LINK_DOWN            -3
  61
  62 /**
  63  * LwIP netif couldn't be added, it is likely that there was an error during initialization of the hardware.
  64  */
  65 #define NETIF_ADD_ERR            -10 /* could be one of previous, except PHY_LINK_DOWN - currently */
  66 /**
  67  * Memory requirements couldn't be satisfied.
  68  */
  69 #define DHCP_MEM_ERR             -11
  70
  71 /**
  72  * Configure which function will be used for debugging prints
  73  */
  74 #ifdef DEBUG
  75 #define rpp_debug_printf rpp_sci_printf
  76 #else
  77 #define rpp_debug_printf(...)
  78 #endif
  79
  80 /**
  81  * configures whether rpp_eth_get_macAddrStr() creates string with big or small latin letters
  82  */
  83 #define MAC_BIG_LETTERS           1
  84
  85 /**
  86  * This function allows application to check whether eth was already initialized
  87  * (it's post OS starup part)
  88  *
  89  * @return TRUE if initialized
  90  *         FALSE if not initialized
  91  */
  92 boolean_t isPostInitialized();
  93
  94 /**
  95  * ETH module system startup initialization.
  96  *
  97  * Call this method before using this module.
  98  * This method starts autonegotiation and doesn't check for end of autoneg.
  99  * When eth module is about to be used, you have to run rpp_eth_init_postInit()
 100  * first and you should check whether link is up.
 101  *
 102  * @return SUCCESS if initialization successful.\n
 103  *         FAILURE if module already initialized.
 104  */
 105 int8_t rpp_eth_init();
 106
 107 /**
 108  * ETH module application initialization.
 109  *
 110  * Call this method before using eth module.
 111  * This method waits for a while on autonegotiation till it's complete, if not completed
 112  * in predefined time it continues with creating tasks for lwIP (including lwIP init),
 113  * for receiving and for handling transmission buffer descriptors. Sets IP address using
 114  * predefined static IP or DHCP. Before calling this method you must call rpp_eth_init() first.
 115  *
 116  * @param instNum number of EMAC instance
 117  * @param macArray address assigned to link layer - when NULL RPP_MAC_ADDR is used
 118  *
 119  * @return SUCCESS if init successful.
 120  *         FAILURE if module was already initialized
 121  *         NETIF_ADD_ERR if lwip netif was not succesfully initialized or on low hw init error.
 122  *         DHCP_MEM_ERR if DHCP unsuccesfull.
 123  */
 124 int8_t rpp_eth_init_postInit(uint32_t instNum, uint8_t *macArray);
 125
 126 // Helper routines/functions for command processor and other applications
 127
 128 /**
 129  * Uses MDIO module to read link status of PHY attached to instNum network interface
 130  *
 131  * @param instNum Number of network interface
 132  *
 133  * @return TRUE if link is UP
 134  *         FALSE if link is DOWN
 135  */
 136 uint32_t rpp_eth_phylinkstat(uint32_t instNum);
 137
 138 /**
 139  * Fills macStr field with MAC address of given network interface instance as 'string'
 140  *
 141  * @note 18 bytes will be filled {2 chars per 6 mac bytes + 5 semicolons + 1 null termination}
 142  *
 143  * @param instNum Number of network interface
 144  * @param *macStr field where null terminated string will be inserted
 145  */
 146 void rpp_eth_get_macAddrStr(uint32_t instNum, uint8_t *macStr);
 147
 148 /**
 149  * Fills ipStr field with IP address in ip_addr_t as 'string';
 150  * prepares an IP address to ipStr in form of null terminated string;
 151  * each byte of ip is converted to one of 4 field in IPv4 IP address format 0xAABBCCDD -> "aaa.bbb.ccc.ddd"
 152  *
 153  * @note up to 16 bytes will be filled {1-3 * 4 IP fields + 3 dots + 1 null termination}
 154  *
 155  *
 156  * @param ip ip address to be converted
 157  * @param ipStr pointer to string where ip will be filled as text
 158  */
 159 inline void rpp_eth_getIPDecimalStr(ip_addr_t ip, uint8_t *ipStr)
 160 {
 161         snprintf((char *)ipStr, 16, "%d.%d.%d.%d",(ip.addr >> 24),((ip.addr >> 16) & 0xff),((ip.addr >> 8) & 0xff),(ip.addr & 0xff));
 162 }
 163
 164 /**
 165  * Fills ip.addr with converted ipstr. Checks for correct format of IP string
 166  * x.x.x.x where x = [0..9]. When FAILURE is returned struct ip was not modified.
 167  *
 168  * @param ip struct to be filled
 169  * @param ipstr string to be converted
 170  *
 171  * @return SUCCESS when succesfully converted
 172  *         FAILURE when wrong format of IP string
 173  */
 174 err_t rpp_eth_stringToIP(ip_addr_t *ip, uint8_t *ipstr);
 175
 176 /**
 177  * Converts given null terminated string containing number to number in
 178  * range <1-65535>
 179  *
 180  * @param string to be converted
 181  * @return 0 on error
 182  *         port number otherwise
 183  */
 184 uint16_t rpp_eth_portStrToInt(uint8_t *string);
 185
 186 /**
 187  * Returns struct describing network interface
 188  *
 189  * @param instNum instance number of network interface
 190  *
 191  * @return pointer to struct netif
 192  */
 193 struct netif *rpp_eth_get_netif(uint32_t instNum);
 194
 195 /**
 196  * Adjusts packet (pbuf) length and send it within critical section
 197  * using rpp_eth_send_raw()
 198  *
 199  * @param netif lwIP network interface describing struct
 200  * @param p buffer for data to be sent
 201  */
 202 err_t rpp_eth_send(struct netif *netif, struct pbuf *p);
 203
 204 /**
 205  * Handles transmission of data buffer p through EMAC to network.
 206  *
 207  * @param netif lwIP network interface describing struct
 208  * @param p buffer for data to be sent
 209  */
 210 static err_t rpp_eth_send_raw(struct netif *netif, struct pbuf *p);
 211
 212 /**
 213  * Receives raw data and sends them upward to lwIP stack.
 214  * Handles rx emac descriptors.
 215  *
 216  * @note when using OS tasks (!NO_SYS) this function is used as
 217  *       task, otherwise (NO_SYS) this is called from RX ISR.
 218  *
 219  * @param arg netif
 220  */
 221 void rpp_eth_recv_raw_thr(void *arg);
 222
 223 void rpp_eth_send_raw_thr(void *arg);
 224
 225 /**
 226  * Handles freeing of buffer descriptors and other structures in memory
 227  * after transmission of bd was completed.
 228  *
 229  * @param arg hdkif
 230  */
 231 void rpp_eth_send_bd_handler(void *arg);
 232
 233 /**
 234  * Handles receiving by running rpp_eth_recv_raw_thr()
 235  *
 236  * @param instNum number of EMAC instance
 237  */
 238 void RxIntHandler(u32_t instNum);
 239
 240 /**
 241  * Handles tx emac descriptors.
 242  *
 243  * @param instNum number of EMAC instance
 244  */
 245 void TxIntHandler(u32_t instNum);
 246
 247 #endif /* __RPP_ETH_H */