Appendix: Migrating from io-net

This appendix describes the compatibility between io-net and io-pkt.

• Overview
• Compatibility between io-net and io-pkt
• Compatibility issues
• Behavioral differences
• Simultaneous support
• Discontinued features
• Using pfil hooks to implement an io-net filter

For information about converting drivers, see the “Porting an io-net driver to io-pkt” technote.

Overview

The previous generation of the QNX Neutrino networking stack (io-net) was designed based on a modular approach. It served its purpose in the past by allowing users to separate protocols and drivers, but this came at the expense of incurring a significant amount of overhead when converting to a particular protocol's domain from io-net and vice versa.

Note that io-pkt and the new utilities and daemons aren't backward-compatible with io-net.

Changes to the networking stack.

Compatibility between io-net and io-pkt

Both io-net and io-pkt can co-exist on the same system. The updated socket library provided with io-pkt is compatible with io-net. This lets you run both io-net and io-pkt simultaneously.

---

The reverse isn't true; if you use the io-net version of the socket library with io-pkt, unresolved symbols will occur when you attempt to use the io-pkt configuration utilities (e.g. ifconfig).

---

We've updated the following binaries for io-pkt:

• netmanager
• ifconfig
• route
• sysctl
• arp
• netstat
• ping
• ping6
• sockstat (see the NetBSD documentation)
• ftp
• ftpd
• inetd
• nicinfo
• pppd
• pppoed — this is now simply a shim layer that phdialer uses to dial up PPPOE

Compatibility issues

Binaries

The following replaced binaries are known to have compatibility issues with io-net. Essentially, new utilities are likely to contain enhanced features that aren't supported by the old stack:

• pppoed
• inetd
• ftp
• sysctl
• ifconfig

The following io-net binaries are known to have compatibility issues with io-pkt:

• snmpd

Sockets

The socket library is fully backward-compatible with all BSD socket API applications. This also extends to the routing socket.

Protocols

A bind() on an AF_INET socket now requires that the second argument have its (struct sockaddr *)->af_family member be initialized to AF_INET. Previously a value of 0 was accepted and assumed to be this value.

Drivers

A special “shim” layer makes drivers that were written for io-net compatible with io-pkt. For more information, see the Network Drivers chapter in this guide.

Behavioral differences

• If io-pkt has problems loading a device, it doesn't print failure messages to the console by default; they're automatically sent to slogger. You can use the -v option to io-pkt to force the output to the console for debugging purposes.
• The way in which the SIOCGIFCONF ioctl() command was used in our io-net code was incorrect but it worked. We've changed the implementation, but applications that use the old method will no longer work. Here's some code that illustrates the old and new methods:

  /*
   * Example demonstrating a common pitfall with SIOCGIFCONF handling.
   */
  
  
  #include <sys/sockio.h>
  #include <net/if.h>
  #include <malloc.h>
  #include <stdlib.h>
  #include <err.h>
  #include <ifaddrs.h>
  
  void gifconf(int);
  void gifaddrs(int);
  
  
  int
  main(void)
  {
  	int             s;
  
  	if ((s = socket(AF_INET, SOCK_DGRAM, 0)) == -1)
  		err(EXIT_FAILURE, "socket");
  
  	gifconf(s);     /* Old code often used SIOCGIFCONF ioctl        */
  	gifaddrs(s);    /* New code should use getifaddrs()             */
  
  	close(s);
  
  	return 0;
  }
  
  void
  gifconf(int s)
  {
  	struct ifconf   ifc;
  	struct ifreq    *inext, *iend, *icur;
  	size_t		size;
  
  
  	size = 4096;
  	ifc.ifc_len = size;
  	if ((ifc.ifc_buf = malloc(ifc.ifc_len)) == NULL)
  		err(EXIT_FAILURE, "malloc");
  	if (ioctl(s, SIOCGIFCONF, &ifc) == -1)
  		err(EXIT_FAILURE, "SIOCGIFCONF");
  
  	if (ifc.ifc_len >= size) {
  		/* realloc and try again */
  		errx(EXIT_FAILURE, "SIOCGIFCONF: buf too small");
  	}
  
  	inext = ifc.ifc_req;
  	iend = (struct ifreq *)(ifc.ifc_buf + ifc.ifc_len);
  	for (;;) {
  		icur = inext;
  #if 0
  		/*
  		 * Broken code.  This would happen to work for most cases
  		 * because previously:
  		 *
  		 * sizeof(struct sockaddr) + IFNAMSIZ == sizeof(struct ifreq)
  		 *
  		 * Under this scenario  the two 'if' cases in the working
  		 * case below work out to the same thing.
  		 */
  		inext = (struct ifreq *)
  		    ((char *)inext + inext->ifr_addr.sa_len + IFNAMSIZ);
  #else
  		/* This will work against old / new libsocket */
  		if (inext->ifr_addr.sa_len + IFNAMSIZ > sizeof(struct ifreq))
  			inext = (struct ifreq *)
  			    ((char *)inext + inext->ifr_addr.sa_len + IFNAMSIZ);
  		else
  			inext++;
  #endif
  		if (inext > iend)
  			break;
  
  		/* process icur */
  	}
  
  	free(ifc.ifc_buf);
  }
  
  void
  gifaddrs(int s)
  {
  	struct ifaddrs	*ifaddrs, *ifap;
  
  	if (getifaddrs(&ifaddrs) == -1)
  		err(EXIT_FAILURE, "getifaddrs");
  
  	for (ifap = ifaddrs; ifap != NULL; ifap = ifap->ifa_next) {
  		continue;
  	}
  
  	freeifaddrs(ifaddrs);
  }

  If you compile the test case against the old headers, the SIOCGIFCONF ioctl() will produce the expected results in all environments: old / new stack, old / new libc. If you compile it against the io-pkt headers, the SIOCGIFCONF command will work only with the io-pkt stack and the 6.4 libc. In either case, there's no dependency on any version of libsocket.

  The getifaddrs() call will work everywhere and is recommended for new code.

Simultaneous support

You can run both io-net and io-pkt simultaneously on the same target if the relevant utilities and daemons for each stack are present. Here are some specific issues you should be aware of:

• The socket library is backward-compatible with all BSD socket API applications. This also extends to the routing socket.
• Applications with a tight coupling to the TCP/IP stack, including ifconfig, netstat, arp, route, sysctl, inetd, pppd, and pppoed, aren't backward-compatible. Stack-specific versions need to be maintained and executed.
• Socket library and headers aren't saved. The new versions are backward-compatible.
• The following components may be compatible with io-pkt:
  • phdialer is compatible.
  • The network usage widget in pwm won't work with non-io-net-style drivers since they aren't compatible with the devctl() interface used by the widget.
• We've updated nicinfo to work with native io-pkt drivers (e.g. nicinfo wm0). NetBSD drivers don't operate with nicinfo.
• You can run both io-net and io-pkt simultaneously, but you have to provide different instance numbers and prefixes to the stack. For example:

  io-pkt -d pcnet pci=0 
  io-net -i1 -dpcnet pci=1 -ptcpip prefix=/alt
    

  Note that the io-net versions of the utilities must be present on the target (assumed, for this example, to have been placed in a separate directory) and run with the io-net stack. For example:

  SOCK=/alt /io-net/ifconfig en0 192.168.1.2
  SOCK=/alt /io-net/inetd
    

Discontinued features

The io-pkt networking stack doesn't support the following features:

• npm-qnet-compat.so (Neutrino 6.2.1 Qnet compatibility protocol)
• npm-ttcpip.so (tiny TCP/IP) stack

Using pfil hooks to implement an io-net filter

We recommend that you use pfil hooks to rewrite your io-net filter to work in io-pkt. Here are the basic steps:

• Change your entry point function to remove the second argument (dispatch_t) and change the third option to be struct _iopkt_self.
• Remove the io_net_dll_entry_t and replace it with the appropriate version of:

  struct _iopkt_lsm_entry IOPKT_LSM_ENTRY_SYM(mod) =
  IOPKT_LSM_ENTRY_SYM_INIT(mod_entry);
    

• The rx_up and rx_down functions are essentially pfil_hook entries with a flag of PFIL_IN and PFIL_OUT, respectively.

  Information about the interface that the packet was received on is contained in the ifp pointer (defined in usr/include/net/if.h). For example, the external interface name is in ifp->if_xname; you can use this to determine where the packet came from.

  The cell, endpoint, and iface parameters are essentially wrapped up in the ifp pointer.

• There are no advertisement packets used within io-pkt. For information about interfaces being added, removed, or reconfigured, you can add an interface hook as shown in the sample code in “Packet Filters” in the Packet Filtering chapter in this guide.
• Buffering in io-pkt is handled using a different structure than in io-net. The io-net stack uses npkt_t buffers, whereas io-pkt uses the standard mbuf buffers. You have to modify your io-net code to deal with the different buffer format.

  You can find information about using mbuf buffers in many places on the web. The header file that covers the io-pkt mbuf support is in $QNX_TARGET/usr/include/sys/mbuf.h.

• The shutdown1 and shutdown2 routines are somewhat similar to the “remove_hook” options, in which the filtering functions are removed from the processing stream. Typically, a filter requiring interaction with the user (e.g. read, write, umount) would export a resource manager interface to provide a mechanism for indicating that the filter has to be removed. You can then use pfil_remove_hook() calls after cleaning up to remove the functions from the data path.
• There isn't an equivalent of tx_done for pfil. In io-net, buffers are allocated by endpoints (e.g. a driver or a protocol) and therefore an endpoint-specific function for freeing buffers needs to be called to release the buffer back to the endpoint's buffer pool.

  In io-pkt, all buffer allocation is handled explicitly by the stack middleware. This means that any element requiring a buffer goes directly to the middleware to get it, and anything freeing a buffer (e.g. the driver) puts it directly back into the middleware buffer pools. This makes things easier to deal with, because you now no longer have to track and manage your own buffer pools as an endpoint. As soon as the code is finished with the buffer, it simply performs an m_freem() of the buffer which places it back in the general pool.

  There is one downside to the global buffer implementation. You can't create a thread using pthread_create() that allocates or frees a buffer from the stack, because the thread has to modify internal stack structures. The locking implemented within io-pkt is optimized to reduce thread context-switch times, and this means that non-stack threads can't lock-protect these structures. Instead, the stack provides its own thread-creation function (defined in trunk/sys/nw_thread.h):

  int nw_pthread_create(pthread_t *tidp,
                        pthread_attr_t *attrp,
                        void *(*funcp)(void *),
                        void *arg,
                        int flags,
                        int (*init_func)(void *),
                        void *init_arg);
    

  The first four arguments are the standard arguments to pthread_create(); the last three are specific to io-pkt. You can find a fairly simplistic example of how to use this function in net/ppp_tty.c.

• In terms of transmitting packets, the ifp interface structure contains the if_output function that you can use to transmit a user-built Ethernet packet. The if_output maps to ether_output for an Ethernet interface. This function queues the mbuf to the driver queue for sending, and subsequently calls if_start to transmit the packet on the queue. The preliminary queuing is implemented to allow traffic shaping to take place on the interface.