doc/README.capture-module - platform/external/libpcap - Git at Google

 		    How to write a libpcap module

 WARNING: this document describes an unstable interface; future releases
 of libpcap may, and some probably will, change the interface in an
 incompatible fashion.  If you submit your module to the libpcap
 developers for inclusion in libpcap, not only does that make it more
 likely that it will be available in the libpcap provided by operating
 system vendors (such as Linux distributions), but it also means that we
 will attempt to update it to handle future changes to this interface.
 If we add new capabilities, we may have to ask you how to provide those
 additional capabilities if you're using an underlying mechanism for
 which we have neither the source code nor the documentation.

 NOTE: this document assumes familiarity with the entire libpcap API.

 TODO: more routines, more stuff that the activate routine has to do
 (such as setting the list of DLT_s), convert to Markdown?

 On Linux, *BSD, macOS, Solaris, AIX, HP-UX, IRIX, and Tru64 UNIX,
 Libpcap supports capturing on network interfaces as supported by the
 operating system networking stack, using the native packet capture
 mechanism provided by the OS.  On Windows, it supports it with the help
 of the driver and library supplied by WinPcap and Npcap.

 In addition, it also supports capturing on other types of devices, such
 as:

 	specialized capture cards, such as Endace DAG cards;

 	network adapters that provide special high-performance code
 	paths, such as CSPI Myricom adapters;

 	buses such as USB;

 	software communication channels such as D-Bus and Linux netlink;

 	etc..

 Support for those devices is provided by modules compiled into libpcap.

 If you want to add such a module, you would first have to check the list
 of link-layer header types supported by libpcap, to see if one of those
 would be sufficient for your device.  The current version of the list
 can be found at

 	https://www.tcpdump.org/linktypes.html

 If none of those would work for your device, please read
 doc/DLT_ALLOCATE_HOWTO.md and the introductory paragraphs on the Web
 page mentioned above, and then send a request for the new link-layer
 header type to tcpdump-workers@lists.tcpdump.org.

 Once you have a link-layer header type value or values that you can use,
 you can add new module.

 The module should be a C source file, with a name of the form
 pcap-{MOD}.c, where {MOD} is a name appropriate for your device; for
 example, the support for DAG cards is in pcap-dag.c, and the support for
 capturing USB traffic on Linux is pcap-usb-linux.c.

 Your module is assumed to support one or more named devices.  The names
 should be relatively short names, containing only lower-case
 alphanumeric characters, consisting of a prefix that ends with an
 alphabetic character and, if there can be more than one device instance,
 possibly followed by a numerical device ID, such as "mydevice" or
 "mydevice0"/"mydevice1"/....  If you have more than one type of device
 that you can support, you can have more than one prefix, each of which
 can be followed by a numerical device ID.

 The two exported functions that your module must provide are routines to
 provide a list of device instances and a program to initialize a
 created-but-not-activated pcap_t for an instance of one of your devices.

 The "list of device instances" routine takes, as arguments:

 	a pointer to a pcap_if_list_t;

 	a pointer to an error message buffer.

 The error message buffer may be assumed to be PCAP_ERRBUF_SIZE bytes
 large, but must not be assumed to be larger.  By convention, the routine
 typically has a name containing "findalldevs".

 The routine should attempt to determine what device instances are
 available and add them to the list pointed to by the first argument;
 this may be impossible for some modules, but, for those modules, it may
 be difficult to capture on the devices using Wirehshark (although it
 should be possible to capture on them using tcpdump, TShark, or other
 programs that take a device name on the command line), so we recommend
 that your routine provide the list of devices if possible.  If it
 cannot, it should just immediately return 0.

 The routine should add devices to the list by calling the add_dev()
 routine in libpcap, declared in the pcap-int.h header.  It takes, as
 arguments:

 	the pointer to the pcap_if_list_t passed as an argument to the
 	routine;

 	the device name, as described above;

 	a 32-bit word of flags, as provided by pcap_findalldevs();

 	a text description of the device, or NULL if there is no
 	description;

 	the error message buffer pointer provided to the routine.

 add_dev() will, if it succeeds, return a pointer to a pcap_if_t that was
 added to the list of devices.  If it fails, it will return NULL; in this
 case, the error message buffer has been filled in with an error string,
 and your routine must return -1 to indicate the error.

 If your routine succeeds, it must return 0.  If it fails, it must fill
 in the error message buffer with an error string and return -1.

 The "initialize the pcap_t" routine takes, as arguments:

 	a pointer to a device name;

 	a pointer to an error message buffer;

 	a pointer to an int.

 It returns a pointer to a pcap_t.

 Your module will probably need, for each pcap_t for an opened device, a
 private data structure to maintain its own information about the opened
 device.  These should be allocated per opened instance, not per device;
 if, for example, mydevice0 can be captured on by more than one program
 at the same time, there will be more than one pcap_t opened for
 mydevice0, and so there will be separate private data structures for
 each pcap_t.  If you need to maintain per-device, rather than per-opened
 instance information, you will have to maintain that yourself.

 The routine should first check the device to see whether it looks like a
 device that this module would handle; for example, it should begin with
 one of the device name prefixes for your module and, if your devices
 have instance numbers, be followed by a number.  If it is not one of
 those devices, you must set the integer pointed to by the third
 argument to 0, to indicate that this is *not* one of the devices for
 your module, and return NULL.

 If it *is* one of those devices, it should call pcap_create_common,
 passing to it the error message buffer as the first argument and the
 size of the per-opened instance data structure as the second argument.
 If it fails, it will return NULL; you must return NULL in this case.

 If it succeeds, the pcap_t pointed to by the return value has been
 partially initialized, but you will need to complete the process.  It
 has a "priv" member, which is a void * that points to the private data
 structure attached to it; that structure has been initialized to zeroes.

 What you need to set are some function pointers to your routines to
 handle certain operations:

 	activate_op
 		the routine called when pcap_activate() is done on the
 		pcap_t

 	can_set_rfmon_op
 		the routine called when pcap_can_set_rfmon() is done on
 		the pcap_t - if your device doesn't support 802.11
 		monitor mode, you can leave this as initialized by
 		pcap_create_common(), as that routine will return "no,
 		monitor mode isn't supported".

 Once you've set the activate_op and, if necessary, the can_set_rfmon_op,
 you must return the pcap_t * that was returned to you.

 Your activate routine takes, as an argument, a pointer to the pcap_t
 being activated, and returns an int.

 The perameters set for the device in the pcap_create() call, and after
 that call(), are mostly in the opt member of the pcap_t:

 	device
 		the name of the device

 	timeout
 		the buffering timeout, in milliseconds

 	buffer_size
 		the buffer size to use

 	promisc
 		1 if promiscuous mode is to be used, 0 otherwise

 	rfmon
 		1 if monitor mode is to be used, 0 otherwise

 	immediate
 		1 if the device should be in immediate mode, 0 otherwise

 	nonblock
 		1 if the device should be in non-blocking mode, 0
 		otherwise

 	tstamp_type
 		the type of time stamp to supply

 	tstamp_precision
 		the time stamp precision to supply

 The snapshot member of the pcap_t structure will contain the snapshot
 length to be used.

 Your routine should attempt to set up the device for capturing.  If it
 fails, it must return an error indication which is one of the PCAP_ERROR
 values.  For PCAP_ERROR, it must also set the errbuf member of the
 pcap_t to an error string.  For PCAP_ERROR_NO_SUCH_DEVICE and
 PCAP_ERROR_PERM_DENIED, it may set it to an error string providing
 additional information that may be useful for debugging, or may just
 leave it as a null string.

 If it succeeds, it must set certain function pointers in the pcap_t
 structure:

 	read_op
 		called whenever packets are to be read

 	inject_op
 		called whenever packets are to be injected

 	setfilter_op
 		called whenever pcap_setfilter() is called

 	setdirection_op
 		called whenever pcap_setdirection() is called

 	set_datalink_op
 		called whnever pcap_set_datalink() is called

 	getnonblock_op
 		called whenever pcap_getnonblock() is called

 	setnonblock_op
 		called whenever pcap_setnonblock() is called

 	stats_op
 		called whenever pcap_stats() is called

 	cleanup_op
 		called if the activate routine fails or pcap_close() is
 		called

 and must also set the linktype member to the DLT_ value for the device.

 On UN*Xes, if the device supports waiting for packets to arrive with
 select()/poll()/epoll()/kqueues etc., it should set the selectable_fd
 member of the structure to the descriptor you would use with those
 calls.  If it does not, then, if that's because the device polls for
 packets rather than receiving interrupts or other signals when packets
 arrive, it should have a struct timeval in the private data structure,
 set the value of that struct timeval to the poll timeout, and set the
 required_select_timeout member of the pcap_t to point to the struct
 timeval.

 The read_op routine is called when pcap_dispatch(), pcap_loop(),
 pcap_next(), or pcap_next_ex() is called.  It is passed the same
 arguments as pcap_dispatch() is called.

 The routine should first check if the break_loop member of the pcap_t is
 non-zero and, if so, set that member to zero and return
 PCAP_ERROR_BREAK.

 Then, if the pcap_t is in blocking mode (as opposed to non-blocking
 mode), and there are no packets immediately available to be passed to
 the callback, it should block waiting for packets to arrive, using the
 buffering timeout, first, and read packets from the device if necessary.

 Then it should loop through the available packets, calling the callback
 routine for each packet:

 	If the PACKET_COUNT_IS_UNLIMITED() macro evaluates to true when
 	passed the packet count argument, the loop should continue until
 	there are no more packets immediately available or the
 	break_loop member of the pcap_t is non-zero.  If the break_loop
 	member is fount to be non-zero, it should set that member to
 	zero and return PCAP_ERROR_BREAK.

 	If it doesn't evaluat to true, then the loop should also
 	terminate if the specified number of packets have been delivered
 	to the callback.

 Note that there is *NO* requirement that the packet header or data
 provided to the callback remain available, or valid, after the callback
 routine returns; if the callback needs to save the data for other code
 to use, it must make a copy of that data.  This means that the module is
 free to, for example, overwrite the buffer into which it read the
 packet, or release back to the kernel a packet in a memory-mapped
 buffer shared between the kernel and userland, after the callback
 returns.

 If an error occurs when reading packets from the device, it must set the
 errbuf member of the pcap_t to an error string and return PCAP_ERROR.

 If no error occurs, it must return the number of packets that were
 supplied to the callback routine.

 The inject routine is passed a pointer to the pcap_t, a buffer
 containing the contents of the packet to inject, and the number of bytes
 in the packet.  If the device doesn't support packet injection, the
 routine must set the errbuf member of the pcap_t to a message indicating
 that packet injection isn't supported and return PCAP_ERROR.  Otherwise,
 it should attempt to inject the packet; if the attempt fails, it must
 set the errbuf member of the pcap_t to an error message and return
 PCAP_ERROR.  Otherwise, it should return the number of bytes injected.

 The setfilter routine is passed a pointer to the pcap_t and a pointer
 to a struct bpf_program containing a BPF program to be used as a filter.
 If the mechanism used by your module can perform filtering with a BPF
 program, it would attempt to set that filter to the specified program.

 If that failed because the program was too large, or used BPF features
 not supported by that mechanism, the module should fall back on
 filtering in userland by saving a copy of the filter with a call to
 install_bpf_program(), setting a flag in the private data instructure
 indicating that filtering is being done by the module and, in the read
 routine's main loop, checking the flag and, if it's set, calling
 pcap_filter(), passing it the fcode.bf_insns member of the pcap_t, the
 raw packet data, the on-the-wire length of the packet, and the captured
 length of the packet, and only passing the packet to the callback
 routine, and counting it, if pcap_filter() returns a non-zero value.
 (If the flag is not set, all packets should be passed to the callback
 routine and counted, as the filtering is being done by the mechanism
 used by the module.)  If install_bpf_program() returns a negative value,
 the routine should return PCAP_ERROR.

 If the attempt to set the filter failed for any other reason, the
 routine must set the errbuf member of the pcap_t to an error message and
 return PCAP_ERROR.

 If the attempt to set the filter succeeded, or it failed because the
 mechanism used by the module rejected it and the call to
 install_bpf_program() succeeded, the routine should return 0.

 If the mechanism the module uses doesn't support filtering, the pointer
 to the setfilter routine can just be set to point to
 install_bpf_program; the module does not need a routine of its own to
 handle that.

 The setdirection routine is passed a pointer to the pcap_t and a
 pcap_direction_t indicating which packet directions should be accepted.
 If the module can't arrange to handle only incoming packets or only
 outgoing packets, it can set the pointer to the setdirection routine to
 NULL, and calls to pcap_setdirection() will fail with an error message
 indicating that setting the direction isn't supported.

 XXX describe set_datalink, including what the activate routine has to do
 XXX

 XXX describe the rest of the routines XXX
	How to write a libpcap module

	WARNING: this document describes an unstable interface; future releases
	of libpcap may, and some probably will, change the interface in an
	incompatible fashion. If you submit your module to the libpcap
	developers for inclusion in libpcap, not only does that make it more
	likely that it will be available in the libpcap provided by operating
	system vendors (such as Linux distributions), but it also means that we
	will attempt to update it to handle future changes to this interface.
	If we add new capabilities, we may have to ask you how to provide those
	additional capabilities if you're using an underlying mechanism for
	which we have neither the source code nor the documentation.

	NOTE: this document assumes familiarity with the entire libpcap API.

	TODO: more routines, more stuff that the activate routine has to do
	(such as setting the list of DLT_s), convert to Markdown?

	On Linux, *BSD, macOS, Solaris, AIX, HP-UX, IRIX, and Tru64 UNIX,
	Libpcap supports capturing on network interfaces as supported by the
	operating system networking stack, using the native packet capture
	mechanism provided by the OS. On Windows, it supports it with the help
	of the driver and library supplied by WinPcap and Npcap.

	In addition, it also supports capturing on other types of devices, such
	as:

	specialized capture cards, such as Endace DAG cards;

	network adapters that provide special high-performance code
	paths, such as CSPI Myricom adapters;

	buses such as USB;

	software communication channels such as D-Bus and Linux netlink;

	etc..

	Support for those devices is provided by modules compiled into libpcap.

	If you want to add such a module, you would first have to check the list
	of link-layer header types supported by libpcap, to see if one of those
	would be sufficient for your device. The current version of the list
	can be found at

	https://www.tcpdump.org/linktypes.html

	If none of those would work for your device, please read
	doc/DLT_ALLOCATE_HOWTO.md and the introductory paragraphs on the Web
	page mentioned above, and then send a request for the new link-layer
	header type to tcpdump-workers@lists.tcpdump.org.

	Once you have a link-layer header type value or values that you can use,
	you can add new module.

	The module should be a C source file, with a name of the form
	pcap-{MOD}.c, where {MOD} is a name appropriate for your device; for
	example, the support for DAG cards is in pcap-dag.c, and the support for
	capturing USB traffic on Linux is pcap-usb-linux.c.

	Your module is assumed to support one or more named devices. The names
	should be relatively short names, containing only lower-case
	alphanumeric characters, consisting of a prefix that ends with an
	alphabetic character and, if there can be more than one device instance,
	possibly followed by a numerical device ID, such as "mydevice" or
	"mydevice0"/"mydevice1"/.... If you have more than one type of device
	that you can support, you can have more than one prefix, each of which
	can be followed by a numerical device ID.

	The two exported functions that your module must provide are routines to
	provide a list of device instances and a program to initialize a
	created-but-not-activated pcap_t for an instance of one of your devices.

	The "list of device instances" routine takes, as arguments:

	a pointer to a pcap_if_list_t;

	a pointer to an error message buffer.

	The error message buffer may be assumed to be PCAP_ERRBUF_SIZE bytes
	large, but must not be assumed to be larger. By convention, the routine
	typically has a name containing "findalldevs".

	The routine should attempt to determine what device instances are
	available and add them to the list pointed to by the first argument;
	this may be impossible for some modules, but, for those modules, it may
	be difficult to capture on the devices using Wirehshark (although it
	should be possible to capture on them using tcpdump, TShark, or other
	programs that take a device name on the command line), so we recommend
	that your routine provide the list of devices if possible. If it
	cannot, it should just immediately return 0.

	The routine should add devices to the list by calling the add_dev()
	routine in libpcap, declared in the pcap-int.h header. It takes, as
	arguments:

	the pointer to the pcap_if_list_t passed as an argument to the
	routine;

	the device name, as described above;

	a 32-bit word of flags, as provided by pcap_findalldevs();

	a text description of the device, or NULL if there is no
	description;

	the error message buffer pointer provided to the routine.

	add_dev() will, if it succeeds, return a pointer to a pcap_if_t that was
	added to the list of devices. If it fails, it will return NULL; in this
	case, the error message buffer has been filled in with an error string,
	and your routine must return -1 to indicate the error.

	If your routine succeeds, it must return 0. If it fails, it must fill
	in the error message buffer with an error string and return -1.

	The "initialize the pcap_t" routine takes, as arguments:

	a pointer to a device name;

	a pointer to an error message buffer;

	a pointer to an int.

	It returns a pointer to a pcap_t.

	Your module will probably need, for each pcap_t for an opened device, a
	private data structure to maintain its own information about the opened
	device. These should be allocated per opened instance, not per device;
	if, for example, mydevice0 can be captured on by more than one program
	at the same time, there will be more than one pcap_t opened for
	mydevice0, and so there will be separate private data structures for
	each pcap_t. If you need to maintain per-device, rather than per-opened
	instance information, you will have to maintain that yourself.

	The routine should first check the device to see whether it looks like a
	device that this module would handle; for example, it should begin with
	one of the device name prefixes for your module and, if your devices
	have instance numbers, be followed by a number. If it is not one of
	those devices, you must set the integer pointed to by the third
	argument to 0, to indicate that this is not one of the devices for
	your module, and return NULL.

	If it is one of those devices, it should call pcap_create_common,
	passing to it the error message buffer as the first argument and the
	size of the per-opened instance data structure as the second argument.
	If it fails, it will return NULL; you must return NULL in this case.

	If it succeeds, the pcap_t pointed to by the return value has been
	partially initialized, but you will need to complete the process. It
	has a "priv" member, which is a void * that points to the private data
	structure attached to it; that structure has been initialized to zeroes.

	What you need to set are some function pointers to your routines to
	handle certain operations:

	activate_op
	the routine called when pcap_activate() is done on the
	pcap_t

	can_set_rfmon_op
	the routine called when pcap_can_set_rfmon() is done on
	the pcap_t - if your device doesn't support 802.11
	monitor mode, you can leave this as initialized by
	pcap_create_common(), as that routine will return "no,
	monitor mode isn't supported".

	Once you've set the activate_op and, if necessary, the can_set_rfmon_op,
	you must return the pcap_t * that was returned to you.

	Your activate routine takes, as an argument, a pointer to the pcap_t
	being activated, and returns an int.

	The perameters set for the device in the pcap_create() call, and after
	that call(), are mostly in the opt member of the pcap_t:

	device
	the name of the device

	timeout
	the buffering timeout, in milliseconds

	buffer_size
	the buffer size to use

	promisc
	1 if promiscuous mode is to be used, 0 otherwise

	rfmon
	1 if monitor mode is to be used, 0 otherwise

	immediate
	1 if the device should be in immediate mode, 0 otherwise

	nonblock
	1 if the device should be in non-blocking mode, 0
	otherwise

	tstamp_type
	the type of time stamp to supply

	tstamp_precision
	the time stamp precision to supply

	The snapshot member of the pcap_t structure will contain the snapshot
	length to be used.

	Your routine should attempt to set up the device for capturing. If it
	fails, it must return an error indication which is one of the PCAP_ERROR
	values. For PCAP_ERROR, it must also set the errbuf member of the
	pcap_t to an error string. For PCAP_ERROR_NO_SUCH_DEVICE and
	PCAP_ERROR_PERM_DENIED, it may set it to an error string providing
	additional information that may be useful for debugging, or may just
	leave it as a null string.

	If it succeeds, it must set certain function pointers in the pcap_t
	structure:

	read_op
	called whenever packets are to be read

	inject_op
	called whenever packets are to be injected

	setfilter_op
	called whenever pcap_setfilter() is called

	setdirection_op
	called whenever pcap_setdirection() is called

	set_datalink_op
	called whnever pcap_set_datalink() is called

	getnonblock_op
	called whenever pcap_getnonblock() is called

	setnonblock_op
	called whenever pcap_setnonblock() is called

	stats_op
	called whenever pcap_stats() is called

	cleanup_op
	called if the activate routine fails or pcap_close() is
	called

	and must also set the linktype member to the DLT_ value for the device.

	On UN*Xes, if the device supports waiting for packets to arrive with
	select()/poll()/epoll()/kqueues etc., it should set the selectable_fd
	member of the structure to the descriptor you would use with those
	calls. If it does not, then, if that's because the device polls for
	packets rather than receiving interrupts or other signals when packets
	arrive, it should have a struct timeval in the private data structure,
	set the value of that struct timeval to the poll timeout, and set the
	required_select_timeout member of the pcap_t to point to the struct
	timeval.

	The read_op routine is called when pcap_dispatch(), pcap_loop(),
	pcap_next(), or pcap_next_ex() is called. It is passed the same
	arguments as pcap_dispatch() is called.

	The routine should first check if the break_loop member of the pcap_t is
	non-zero and, if so, set that member to zero and return
	PCAP_ERROR_BREAK.

	Then, if the pcap_t is in blocking mode (as opposed to non-blocking
	mode), and there are no packets immediately available to be passed to
	the callback, it should block waiting for packets to arrive, using the
	buffering timeout, first, and read packets from the device if necessary.

	Then it should loop through the available packets, calling the callback
	routine for each packet:

	If the PACKET_COUNT_IS_UNLIMITED() macro evaluates to true when
	passed the packet count argument, the loop should continue until
	there are no more packets immediately available or the
	break_loop member of the pcap_t is non-zero. If the break_loop
	member is fount to be non-zero, it should set that member to
	zero and return PCAP_ERROR_BREAK.

	If it doesn't evaluat to true, then the loop should also
	terminate if the specified number of packets have been delivered
	to the callback.

	Note that there is NO requirement that the packet header or data
	provided to the callback remain available, or valid, after the callback
	routine returns; if the callback needs to save the data for other code
	to use, it must make a copy of that data. This means that the module is
	free to, for example, overwrite the buffer into which it read the
	packet, or release back to the kernel a packet in a memory-mapped
	buffer shared between the kernel and userland, after the callback
	returns.

	If an error occurs when reading packets from the device, it must set the
	errbuf member of the pcap_t to an error string and return PCAP_ERROR.

	If no error occurs, it must return the number of packets that were
	supplied to the callback routine.

	The inject routine is passed a pointer to the pcap_t, a buffer
	containing the contents of the packet to inject, and the number of bytes
	in the packet. If the device doesn't support packet injection, the
	routine must set the errbuf member of the pcap_t to a message indicating
	that packet injection isn't supported and return PCAP_ERROR. Otherwise,
	it should attempt to inject the packet; if the attempt fails, it must
	set the errbuf member of the pcap_t to an error message and return
	PCAP_ERROR. Otherwise, it should return the number of bytes injected.

	The setfilter routine is passed a pointer to the pcap_t and a pointer
	to a struct bpf_program containing a BPF program to be used as a filter.
	If the mechanism used by your module can perform filtering with a BPF
	program, it would attempt to set that filter to the specified program.

	If that failed because the program was too large, or used BPF features
	not supported by that mechanism, the module should fall back on
	filtering in userland by saving a copy of the filter with a call to
	install_bpf_program(), setting a flag in the private data instructure
	indicating that filtering is being done by the module and, in the read
	routine's main loop, checking the flag and, if it's set, calling
	pcap_filter(), passing it the fcode.bf_insns member of the pcap_t, the
	raw packet data, the on-the-wire length of the packet, and the captured
	length of the packet, and only passing the packet to the callback
	routine, and counting it, if pcap_filter() returns a non-zero value.
	(If the flag is not set, all packets should be passed to the callback
	routine and counted, as the filtering is being done by the mechanism
	used by the module.) If install_bpf_program() returns a negative value,
	the routine should return PCAP_ERROR.

	If the attempt to set the filter failed for any other reason, the
	routine must set the errbuf member of the pcap_t to an error message and
	return PCAP_ERROR.

	If the attempt to set the filter succeeded, or it failed because the
	mechanism used by the module rejected it and the call to
	install_bpf_program() succeeded, the routine should return 0.

	If the mechanism the module uses doesn't support filtering, the pointer
	to the setfilter routine can just be set to point to
	install_bpf_program; the module does not need a routine of its own to
	handle that.

	The setdirection routine is passed a pointer to the pcap_t and a
	pcap_direction_t indicating which packet directions should be accepted.
	If the module can't arrange to handle only incoming packets or only
	outgoing packets, it can set the pointer to the setdirection routine to
	NULL, and calls to pcap_setdirection() will fail with an error message
	indicating that setting the direction isn't supported.

	XXX describe set_datalink, including what the activate routine has to do
	XXX

	XXX describe the rest of the routines XXX