From f92316649b0f926daf5db63971452c14489c2c1e Mon Sep 17 00:00:00 2001 From: tbrennan3 Date: Wed, 24 Mar 2010 03:41:39 +0000 Subject: [PATCH] Started a Doxygen module for DataLink layer, for the default DataLink templates and for BACnet/IP. --- bacnet-stack/BACnet-stack.doxyfile | 6 +++--- bacnet-stack/include/bip.h | 10 +++++++++ bacnet-stack/include/datalink.h | 33 ++++++++++++++++++++++++++++- bacnet-stack/ports/linux/bip-init.c | 27 +++++++++++++++++++++-- bacnet-stack/src/bip.c | 22 +++++++++++++++++-- bacnet-stack/src/datalink.c | 25 +++++++++++++++++++++- 6 files changed, 114 insertions(+), 9 deletions(-) diff --git a/bacnet-stack/BACnet-stack.doxyfile b/bacnet-stack/BACnet-stack.doxyfile index bfa46a29..94325096 100644 --- a/bacnet-stack/BACnet-stack.doxyfile +++ b/bacnet-stack/BACnet-stack.doxyfile @@ -271,7 +271,7 @@ EXTRACT_PRIVATE = YES # If the EXTRACT_STATIC tag is set to YES all static members of a file # will be included in the documentation. -EXTRACT_STATIC = YES +EXTRACT_STATIC = NO # If the EXTRACT_LOCAL_CLASSES tag is set to YES classes (and structs) # defined locally in source files will be included in the documentation. @@ -506,7 +506,7 @@ WARN_LOGFILE = # directories like "/usr/src/myproject". Separate the files or directories # with spaces. -INPUT = include src demo/server ports/linux demo/handler demo/object +INPUT = include src demo/server ports/linux demo/handler demo/object # This tag can be used to specify the character encoding of the source files # that doxygen parses. Internally doxygen uses the UTF-8 encoding, which is @@ -1108,7 +1108,7 @@ INCLUDE_FILE_PATTERNS = # undefined via #undef or recursively expanded use the := operator # instead of the = operator. -PREDEFINED = +PREDEFINED = FOR_DOXYGEN # If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then # this tag can be used to specify a list of macro names that should be expanded. diff --git a/bacnet-stack/include/bip.h b/bacnet-stack/include/bip.h index fb04e953..542cdc3e 100644 --- a/bacnet-stack/include/bip.h +++ b/bacnet-stack/include/bip.h @@ -122,4 +122,14 @@ extern "C" { #ifdef __cplusplus } #endif /* __cplusplus */ + +/** @defgroup DLBIP BACnet/IP DataLink Network Layer + * @ingroup DataLink + * Implementation of the Network Layer using BACnet/IP as the transport, as + * described in Annex J. + * The functions described here fulfill the roles defined generically at the + * DataLink level by serving as the implementation of the function templates. + * + */ + #endif diff --git a/bacnet-stack/include/datalink.h b/bacnet-stack/include/datalink.h index dc7926f1..bca2f574 100644 --- a/bacnet-stack/include/datalink.h +++ b/bacnet-stack/include/datalink.h @@ -83,7 +83,7 @@ #define datalink_get_broadcast_address bip_get_broadcast_address #define datalink_get_my_address bip_get_my_address -#else +#else /* Ie, BACDL_ALL */ #include "npdu.h" #define MAX_HEADER (8) @@ -118,4 +118,35 @@ extern "C" { } #endif /* __cplusplus */ #endif + +/** @defgroup DataLink The BACnet Network (DataLink) Layer + * 6 THE NETWORK LAYER
+ * The purpose of the BACnet network layer is to provide the means by which + * messages can be relayed from one BACnet network to another, regardless of + * the BACnet data link technology in use on that network. Whereas the data + * link layer provides the capability to address messages to a single device + * or broadcast them to all devices on the local network, the network layer + * allows messages to be directed to a single remote device, broadcast on a + * remote network, or broadcast globally to all devices on all networks. + * A BACnet Device is uniquely located by a network number and a MAC address. + * + * Each client or server application must define exactly one of these + * DataLink settings, which will control which parts of the code will be built: + * - BACDL_ETHERNET -- for Clause 7 ISO 8802-3 ("Ethernet") LAN + * - BACDL_ARCNET -- for Clause 8 ARCNET LAN + * - BACDL_MSTP -- for Clause 9 MASTER-SLAVE/TOKEN PASSING (MS/TP) LAN + * - BACDL_BIP -- for ANNEX J - BACnet/IP + * - BACDL_ALL -- Unspecified for the build, so the transport can be + * chosen at runtime from among these choices. + * - Clause 10 POINT-TO-POINT (PTP) and Clause 11 EIA/CEA-709.1 ("LonTalk") LAN + * are not currently supported by this project. + */ + +/** @defgroup DLTemplates DataLink Template Functions + * @ingroup DataLink + * Most of the functions in this group are function templates which are assigned + * to a specific DataLink network layer implementation either at compile time or + * at runtime. + */ + #endif diff --git a/bacnet-stack/ports/linux/bip-init.c b/bacnet-stack/ports/linux/bip-init.c index 2aad427c..5d94e63e 100644 --- a/bacnet-stack/ports/linux/bip-init.c +++ b/bacnet-stack/ports/linux/bip-init.c @@ -96,7 +96,12 @@ static int get_local_address_ioctl( return rv; } -/* on Linux, ifname is eth0, ath0, arc0, and others. */ +/** Gets the local IP address and local broadcast address from the system, + * and saves it into the BACnet/IP data structures. + * + * @param ifname [in] The named interface to use for the network layer. + * Eg, for Linux, ifname is eth0, ath0, arc0, and others. + */ static void bip_set_interface( char *ifname) { @@ -128,6 +133,24 @@ static void bip_set_interface( } } +/** Initialize the BACnet/IP services at the given interface. + * @ingroup DLBIP + * -# Gets the local IP address and local broadcast address from the system, + * and saves it into the BACnet/IP data structures. + * -# Opens a UDP socket + * -# Configures the socket for sending and receiving + * -# Configures the socket so it can send broadcasts + * -# Binds the socket to the local IP address at the specified port for + * BACnet/IP (by default, 0xBAC0 = 47808). + * + * @note For Linux, ifname is eth0, ath0, arc0, and others. + For Windows, ifname is the dotted ip address of the interface. + + * @param ifname [in] The named interface to use for the network layer. + * If NULL, the "eth0" interface is assigned. + * @return True if the socket is successfully opened for BACnet/IP, + * else False if the socket functions fail. + */ bool bip_init( char *ifname) { @@ -163,7 +186,7 @@ bool bip_init( if (status < 0) { close(sock_fd); bip_set_socket(-1); - return status; + return false; } /* bind the socket to the local port number and IP address */ sin.sin_family = AF_INET; diff --git a/bacnet-stack/src/bip.c b/bacnet-stack/src/bip.c index bdafce75..7cb6e092 100644 --- a/bacnet-stack/src/bip.c +++ b/bacnet-stack/src/bip.c @@ -52,12 +52,20 @@ static struct in_addr BIP_Address; /* Broadcast Address - stored in host byte order */ static struct in_addr BIP_Broadcast_Address; +/** Setter for the BACnet/IP socket handle. + * + * @param sock_fd [in] Handle for the BACnet/IP socket. + */ void bip_set_socket( int sock_fd) { BIP_Socket = sock_fd; } +/** Getter for the BACnet/IP socket handle. + * + * @return The handle to the BACnet/IP socket. + */ int bip_socket( void) { @@ -70,6 +78,9 @@ bool bip_valid( return (BIP_Socket != -1); } +/** Cleanup and close out the BACnet/IP services by closing the socket. + * @ingroup DLBIP + */ void bip_cleanup( void) { @@ -140,8 +151,15 @@ static int bip_decode_bip_address( return len; } -/* function to send a packet out the BACnet/IP socket (Annex J) */ -/* returns number of bytes sent on success, negative number on failure */ +/** Function to send a packet out the BACnet/IP socket (Annex J). + * @ingroup DLBIP + * + * @param dest [in] Destination address (may encode an IP address and port #). + * @param npdu_data [in] The NPDU header (Network) information (not used). + * @param pdu [in] Buffer of data to be sent - may be null (why?). + * @param pdu_len [in] Number of bytes in the pdu buffer. + * @return Number of bytes sent on success, negative number on failure. + */ int bip_send_pdu( BACNET_ADDRESS * dest, /* destination address */ BACNET_NPDU_DATA * npdu_data, /* network information */ diff --git a/bacnet-stack/src/datalink.c b/bacnet-stack/src/datalink.c index 7a8a681a..108d70e8 100644 --- a/bacnet-stack/src/datalink.c +++ b/bacnet-stack/src/datalink.c @@ -36,10 +36,30 @@ /** @file datalink.c Optional run-time assignment of datalink transport */ -#if defined(BACDL_ALL) +#if defined(BACDL_ALL) || defined FOR_DOXYGEN /* Function pointers - point to your datalink */ + +/** Function template to Initialize the DataLink services at the given interface. + * @ingroup DLTemplates + * + * @note For Linux, ifname is eth0, ath0, arc0, ttyS0, and others. + For Windows, ifname is the COM port or dotted ip address of the interface. + + * @param ifname [in] The named interface to use for the network layer. + * @return True if the interface is successfully initialized, + * else False if the initialization fails. + */ bool(*datalink_init) (char *ifname); +/** Function template to send a packet via the DataLink. + * @ingroup DLTemplates + * + * @param dest [in] Destination address. + * @param npdu_data [in] The NPDU header (Network) information. + * @param pdu [in] Buffer of data to be sent - may be null. + * @param pdu_len [in] Number of bytes in the pdu buffer. + * @return Number of bytes sent on success, negative number on failure. + */ int ( *datalink_send_pdu) ( BACNET_ADDRESS * dest, @@ -50,6 +70,9 @@ int ( uint16_t(*datalink_receive) (BACNET_ADDRESS * src, uint8_t * pdu, uint16_t max_pdu, unsigned timeout); +/** Function template to close the DataLink services and perform any cleanup. + * @ingroup DLTemplates + */ void ( *datalink_cleanup) ( void);