NetBurner 3.3.9
PDF Version
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 );
read
int read(int fd, char *buf, int nbytes)
Read data from a file descriptor (fd). This function will block forever until at least one byte is av...
Definition: fileio.cpp:269
close
int close(int fd)
Close the specified file descriptor and free the associated resources.
Definition: fileio.cpp:102
write
int write(int fd, const char *buf, int nbytes)
Write data to the stream associated with a file descriptor (fd). Can be used to write data to stdio,...
Definition: fileio.cpp:155
GetExtraFD
int GetExtraFD(void *extra_data, struct IoExpandStruct *pFuncs)
Returns a file descriptor for the structure passed as the IoExpandStruct. FreeExtraFd( ) will release...
Definition: extraio.cpp:111
FreeExtraFd
void FreeExtraFd(int fd)
Free a file descriptor and associated resources.
Definition: extraio.cpp:139
GetExtraData
void * GetExtraData(int fd)
Returns the extra structure value from IoExpandStruct associated with the file descriptor.
Definition: extraio.cpp:151

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.