PPPoE library's operation is persistent: once you start it by calling pppoe_start(), it will "persist" to connect to the ADSL modem. No matter how many times the connection fails, the library will keep trying. If the successfully established PPPOE link fails, the library will attempt to reestablish the link. This can only be halted by calling pppoe_stop().
The PPPoE specification envisions the use of more than one ADSL modem (a.k.a. "access concentrator") on the network. The protocol provides the means for the device to choose which access concentrator it wants to communicate through. In reality, most networks only have a single ADSL modem. Since this is a norm, the PPPOE library is designed to attempt to use whatever access concentrator responds to the device's "discovery" packets first.
A buffer space of 2 pages is required for the library operation. These are allocated when pppoe_start() is called. The library will check if the required buffer space is available and call callback_pppoe_pre_buffrq() if more space is needed. Buffer pages allocated to the PPPOE library are never released, even when successful PPPoE link is established or pppoe_stop() is called.
Successul PPPoE link establishment is a multi-step process and involves link configuration using LCP protocol, followed by the login and the configuration of device's IP address. To observe the process, add #define PPPOE_DEBUG_PRINT 1 to the defines section of the global.tbh file of your project (and don't forget to remove this later).
Once the PPPoE link is successfully established, the library will set the properties of the pppoe. object and call callback_pppoe_ok(). The library will then start monitoring PPPoE link's "health". The library will periodically send echo request packets and expect echo replies from the ADSL modem. If this times out, the library will assume that the PPPoE link has failed, call pppoe_failure(), and attempt to reestablish the link.
If your application calls pppoe_stop(), the library will property terminate the PPPoE link (if it was established) and go into the idle state until pppoe_start() is called again.
You can learn more about PPPoE here: http://en.wikipedia.org/wiki/Pppoe.