File Descriptors

The NetBurner environment integrates the RTOS, TCP/IP stack, and other peripherals with a file I/O system based on file descriptors. A file descriptor can be described as a handle to a network socket, serial port, system peripheral, or any other object that can be read or written to. Most of the API functions pass a file descriptor as a parameter to such an object

By default there are a maximum of 255 file descriptors:

• 0 – 2 for stdin, stdout and stderr
• 3 – 4 for the first two UART serial ports, 0 and 1.
• 5 – 128 for TCP (32 in total)
• 129 – 250 for expansion (additional UARTs, TCP sockets, or custom)

The expansion file descriptor positions can be used for many things, including additional serial ports, such as an external UART, TCP ports, or even buffers.

Creating Custom I/O Drivers Using File Descriptors

The header file in \nburn\include\iointernal.h defines the programming interface functions to create a custom file descriptor.

• SetDataAvail()
• ClrDataAvail()
• SetWriteAvail()
• ClrWriteAvail()
• SetHaveError()
• ClrHaveError()

struct IoExpandStruct
{
    int ( * read )  ( int fd, char *buf, int nbytes );
    int ( * write ) ( int fd, const char *buf, int nbytes );
    int ( * close ) ( int fd );
    void *extra;
}
 
int  GetExtraFD( void *extra_data, struct IoExpandStruct *pFuncs );
void *GetExtraData( int fd );
void FreeExtraFd( int fd );

The TCP state call back, fd = socket has new data, fd < 0 means error typedef void ( tcp_read_notify_handler )( int tcp_fd );

When data comes in or the TCP connection enters an error state, register a callback to handle the event void RegisterTCPReadNotify( int tcp_fd, tcp_read_notify_handler *newhandler );

The Set and Clr functions are used to update the state of your fd device for file I/O functions such as select(), read() and write(). The IoExpandStruct is used to declare function pointers for the read(), write() and close() functions that will be implemented in your application, as well as an “extra” void pointer that you can use for whatever you wish.

GetExtraFD() is the function that will return a fd for the object passed as the IoExpandStruct. The extra_data void pointer is optional, and can be used to pass data into your fd. You can read the extra_data value at any time with the GetExtraData() function. FreeExtraFd() will release the fd back to the pool of available fds.

The tcp_read_notify_handler and RegisterTCPReadNotify() are callback functions. These functions will get called by the system if you define them for the corresponding TCP event.

Using File Descriptors to Pend on Multiple Events

Once you have created a file descriptor you can use the select() function call just as you would for network or serial file descriptors. In fact, you can pend on a mixture of them all at the same time.