KallistiOS  ##version##
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups
Data Structures | Macros | Typedefs | Functions
ppp.h File Reference

PPP interface for network communications. More...

#include <sys/cdefs.h>
#include <stdint.h>
#include <sys/types.h>
#include <sys/queue.h>

Go to the source code of this file.

Data Structures

struct  ppp_device
 PPP device structure. More...
 
struct  ppp_proto
 PPP Protocol structure. More...
 

Macros

#define PPP_TX_END_OF_PKT   0x00000001
 End of packet flag. More...
 
#define PPP_PROTO_ENTRY_INIT   { NULL, NULL }
 Static initializer for protocol list entry. More...
 
#define PPP_PHASE_DEAD   0x01
 Pre-connection. More...
 
#define PPP_PHASE_ESTABLISH   0x02
 Establishing connection. More...
 
#define PPP_PHASE_AUTHENTICATE   0x03
 Authentication to peer. More...
 
#define PPP_PHASE_NETWORK   0x04
 Established and working. More...
 
#define PPP_PHASE_TERMINATE   0x05
 Tearing down the link. More...
 
#define PPP_FLAG_AUTH_PAP   0x00000001
 PAP authentication. More...
 
#define PPP_FLAG_AUTH_CHAP   0x00000002
 CHAP authentication. More...
 
#define PPP_FLAG_PCOMP   0x00000004
 Protocol compression. More...
 
#define PPP_FLAG_ACCOMP   0x00000008
 Addr/ctrl compression. More...
 
#define PPP_FLAG_MAGIC_NUMBER   0x00000010
 Use magic numbers. More...
 
#define PPP_FLAG_WANT_MRU   0x00000020
 Specify MRU. More...
 
#define PPP_FLAG_NO_ACCM   0x00000040
 No ctl character map. More...
 

Typedefs

typedef struct ppp_device ppp_device_t
 PPP device structure. More...
 
typedef struct ppp_proto ppp_protocol_t
 PPP Protocol structure. More...
 

Functions

int ppp_set_device (ppp_device_t *dev)
 Set the device used to do PPP communications. More...
 
int ppp_set_login (const char *username, const char *password)
 Set the login credentials used to authenticate to the peer. More...
 
int ppp_send (const uint8_t *data, size_t len, uint16_t proto)
 Send a packet on the PPP link. More...
 
int ppp_add_protocol (ppp_protocol_t *hnd)
 Register a protocol with the PPP stack. More...
 
int ppp_del_protocol (ppp_protocol_t *hnd)
 Unregister a protocol from the PPP stack. More...
 
int ppp_lcp_send_proto_reject (uint16_t proto, const uint8_t *pkt, size_t len)
 Send a Protocol Reject packet on the link. More...
 
uint32_t ppp_get_flags (void)
 Get the flags set for our side of the link. More...
 
uint32_t ppp_get_peer_flags (void)
 Get the flags set for the peer's side of the link. More...
 
void ppp_set_flags (uint32_t flags)
 Get the flags set for our side of the link. More...
 
int ppp_connect (void)
 Establish a point-to-point link across a previously set-up device. More...
 
int ppp_scif_init (int bps)
 Initialize the Dreamcast serial port for a PPP link. More...
 
int ppp_modem_init (const char *number, int blind, int *conn_rate)
 Initialize the Dreamcast modem for a PPP link. More...
 
int ppp_init (void)
 Initialize the PPP library. More...
 
int ppp_shutdown (void)
 Shut down the PPP library. More...
 

Detailed Description

PPP interface for network communications.

This file defines the API provided by libppp to interact with the PPP stack. PPP is a network communication protocol used to establish a direct link between two peers. It is most commonly used as the data link layer protocol for dialup internet access, but can also be potentially used on broadband connections (PPP over Ethernet or PPPoE) or on a direct serial line to a computer.

The API presented by this library is designed to be extensible to whatever devices you might want to use it with, and was designed to integrate fairly simply into the rest of KOS' network stack.

Author
Lawrence Sebald

Macro Definition Documentation

#define PPP_PROTO_ENTRY_INIT   { NULL, NULL }

Static initializer for protocol list entry.

#define PPP_TX_END_OF_PKT   0x00000001

End of packet flag.

Typedef Documentation

typedef struct ppp_device ppp_device_t

PPP device structure.

This structure defines a basic output device for PPP packets. This structure is largely modeled after netif_t from the main network stack, with a bit of functionality removed that is irrelevant for PPP.

Note that we only allow one device and one connection in this library.

typedef struct ppp_proto ppp_protocol_t

PPP Protocol structure.

Each protocol that the PPP library can handle must have one of these registered. All protocols should be registered BEFORE attempting to actually establish a PPP session to ensure that each protocol can be used in the setup of the connection as needed.

Function Documentation

int ppp_add_protocol ( ppp_protocol_t hnd)

Register a protocol with the PPP stack.

This function adds a new protocol to the PPP stack, allowing the stack to communicate packets for the given protocol across the link. Generally, you should not have any reason to call this function, as the library includes a set of protocols to do normal communications.

Parameters
hndA protocol handler structure.
Returns
0 on success, <0 on failure.
int ppp_connect ( void  )

Establish a point-to-point link across a previously set-up device.

This function establishes a point-to-point link to the peer across a device that was previously set up with ppp_set_device(). Before calling this function, the device must be ready to communicate with the peer. That is to say, any handshaking needed to establish the underlying hardware link must have already completed.

Returns
0 on success, <0 on failure.
Note
This function will block until the link is established.
int ppp_del_protocol ( ppp_protocol_t hnd)

Unregister a protocol from the PPP stack.

This function removes protocol from the PPP stack. This should be done at shutdown time of any protocols added with ppp_add_protocol().

Parameters
hndA protocol handler structure.
Returns
0 on success, <0 on failure.
uint32_t ppp_get_flags ( void  )

Get the flags set for our side of the link.

This function retrieves the connection flags set for our side of the PPP link. Before link establishment, this indicates the flags we would like to establish on the link and after establishment it represents the flags that were actually negotiated during link establishment.

Returns
Bitwise OR of PPP link configuration flags.
uint32_t ppp_get_peer_flags ( void  )

Get the flags set for the peer's side of the link.

This function retrieves the connection flags set for the other side of the PPP link. This value is only valid after link establishment.

Returns
Bitwise OR of PPP link configuration flags.
int ppp_init ( void  )

Initialize the PPP library.

This function initializes the PPP library, preparing internal structures for use and initializing the PPP protocols needed for normal IP communications.

Returns
0 on success, <0 on failure.
int ppp_lcp_send_proto_reject ( uint16_t  proto,
const uint8_t *  pkt,
size_t  len 
)

Send a Protocol Reject packet on the link.

This function sends a LCP protocol reject packet on the link for the specified packet. Generally, you should not have to call this function, as the library will handle doing so internally.

Parameters
protoThe PPP protocol number of the invalid packet.
pktThe packet itself.
lenThe length of the packet, in bytes.
Returns
0 on success, <0 on failure.
int ppp_modem_init ( const char *  number,
int  blind,
int *  conn_rate 
)

Initialize the Dreamcast modem for a PPP link.

This function sets up the Dreamcast serial port to act as a communications link for a point-to-point connection. This includes dialing the specified phone number and establishing the low-level link.

Parameters
numberThe phone number to dial out.
blindNon-zero to blind dial (don't wait for a dial tone).
conn_rateStorage for the connection rate, in bits per second. Set to NULL if you do not need this value back from the function.
Return values
0On success.
-1If modem initialization fails.
-2If not using blind dial and no dial tone is detected within 5 seconds of opening the line.
-3If dialing the modem fails.
-4If a connection is not established in 60 seconds after dialing.
int ppp_scif_init ( int  bps)

Initialize the Dreamcast serial port for a PPP link.

This function sets up the Dreamcast serial port to act as a communications link for a point-to-point connection. This can be used in conjunction with a coder's cable (or similar) to connect the Dreamcast to a PC and the internet if the target system is set up properly.

Parameters
bpsThe speed to initialize the serial port at.
Returns
0 on success, <0 on failure.
int ppp_send ( const uint8_t *  data,
size_t  len,
uint16_t  proto 
)

Send a packet on the PPP link.

This function sends a single packet to the peer on the PPP link. Generally, you should not use this function directly, but rather use the facilities provided by KOS' network stack.

Parameters
dataThe packet to send.
lenThe length of the packet, in bytes.
protoThe PPP protocol number for the packet.
Returns
0 on success, <0 on failure.
int ppp_set_device ( ppp_device_t dev)

Set the device used to do PPP communications.

This function sets the device that further communications over a point-to-point link will take place over. The device need not be ready to communicate immediately upon calling this function.

Unless you are adding support for a new device, you will probably never have to call this function. For instance, if you want to use the Dreamcast serial port to establish a link, the ppp_scif_init() function will call this for you.

Parameters
devThe device to use for communication.
Returns
0 on success, <0 on failure.
Note
Calling this function after establishing a PPP link will fail.
void ppp_set_flags ( uint32_t  flags)

Get the flags set for our side of the link.

This function retrieves the connection flags set for our side of the PPP link. Before link establishment, this indicates the flags we would like to establish on the link and after establishment it represents the flags that were actually negotiated during link establishment.

Returns
Bitwise OR of PPP link configuration flags.
int ppp_set_login ( const char *  username,
const char *  password 
)

Set the login credentials used to authenticate to the peer.

This function sets the login credentials that will be used to authenticate to the peer, if the peer requests authentication. The specifics of how the authentication takes place depends on what options are configured when establishing the link.

Parameters
usernameThe username to authenticate as.
passwordThe password to use to authenticate.
Returns
0 on success, <0 on failure.
Note
Calling this function after establishing a PPP link will fail.
int ppp_shutdown ( void  )

Shut down the PPP library.

This function cleans up the PPP library, shutting down any connections and deinitializing any protocols that have bene registered previously.

Returns
0 on success, <0 on failure.