mirror of
https://github.com/lwip-tcpip/lwip.git
synced 2025-01-27 03:35:38 +00:00
Document DNS, memory pools and PBUFs as modules
This commit is contained in:
Dirk Ziegelmeier
parent
40bc80b551
commit
bd79f6c055
@ -47,7 +47,7 @@
|
||||
* http://lists.nongnu.org/archive/html/lwip-devel/\n
|
||||
* \n
|
||||
* Continuous integration builds (GCC, clang):\n
|
||||
* https://travis-ci.org/yarrick/lwip-merged
|
||||
* https://travis-ci.org/yarrick/lwip-merged\n
|
||||
* \n
|
||||
* lwIP was originally written by Adam Dunkels:\n
|
||||
* http://dunkels.com/adam/\n
|
||||
|
||||
@ -1,18 +1,14 @@
|
||||
/**
|
||||
* @file
|
||||
* DNS - host name to IP address resolver.
|
||||
*
|
||||
*/
|
||||
|
||||
/**
|
||||
|
||||
* This file implements a DNS host name to IP address resolver.
|
||||
|
||||
/*
|
||||
* Port to lwIP from uIP
|
||||
* by Jim Pettinato April 2007
|
||||
|
||||
*
|
||||
* security fixes and more by Simon Goldschmidt
|
||||
|
||||
*
|
||||
* uIP version Copyright (c) 2002-2003, Adam Dunkels.
|
||||
* All rights reserved.
|
||||
*
|
||||
@ -39,9 +35,12 @@
|
||||
* WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
|
||||
* NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
|
||||
* SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
||||
*/
|
||||
|
||||
/**
|
||||
* @defgroup dns DNS
|
||||
*
|
||||
*
|
||||
* DNS.C
|
||||
* Implements a DNS host name to IP address resolver.
|
||||
*
|
||||
* The lwIP DNS resolver functions are used to lookup a host name and
|
||||
* map it to a numerical IP address. It maintains a list of resolved
|
||||
@ -59,6 +58,8 @@
|
||||
* Once a hostname has been resolved (or found to be non-existent),
|
||||
* the resolver code calls a specified callback function (which
|
||||
* must be implemented by the module that uses the resolver).
|
||||
*
|
||||
* All functions must be called from TCPIP thread.
|
||||
*/
|
||||
|
||||
/*-----------------------------------------------------------------------------
|
||||
@ -408,6 +409,7 @@ dns_init(void)
|
||||
}
|
||||
|
||||
/**
|
||||
* @ingroup dns
|
||||
* Initialize one of the DNS servers.
|
||||
*
|
||||
* @param numdns the index of the DNS server to set must be < DNS_MAX_SERVERS
|
||||
@ -426,6 +428,7 @@ dns_setserver(u8_t numdns, const ip_addr_t *dnsserver)
|
||||
}
|
||||
|
||||
/**
|
||||
* @ingroup dns
|
||||
* Obtain one of the currently configured DNS server.
|
||||
*
|
||||
* @param numdns the index of the DNS server
|
||||
@ -484,6 +487,7 @@ dns_init_local(void)
|
||||
}
|
||||
|
||||
/**
|
||||
* @ingroup dns
|
||||
* Scans the local host-list for a hostname.
|
||||
*
|
||||
* @param hostname Hostname to look for in the local host-list
|
||||
@ -522,7 +526,9 @@ dns_lookup_local(const char *hostname, ip_addr_t *addr LWIP_DNS_ADDRTYPE_ARG(u8_
|
||||
}
|
||||
|
||||
#if DNS_LOCAL_HOSTLIST_IS_DYNAMIC
|
||||
/** Remove all entries from the local host-list for a specific hostname
|
||||
/**
|
||||
* @ingroup dns
|
||||
* Remove all entries from the local host-list for a specific hostname
|
||||
* and/or IP address
|
||||
*
|
||||
* @param hostname hostname for which entries shall be removed from the local
|
||||
@ -558,6 +564,7 @@ dns_local_removehost(const char *hostname, const ip_addr_t *addr)
|
||||
}
|
||||
|
||||
/**
|
||||
* @ingroup dns
|
||||
* Add a hostname/IP address pair to the local host-list.
|
||||
* Duplicates are not checked.
|
||||
*
|
||||
@ -591,6 +598,7 @@ dns_local_addhost(const char *hostname, const ip_addr_t *addr)
|
||||
#endif /* DNS_LOCAL_HOSTLIST */
|
||||
|
||||
/**
|
||||
* @ingroup dns
|
||||
* Look up a hostname in the array of known hostnames.
|
||||
*
|
||||
* @note This function only looks in the internal array of known
|
||||
@ -1378,6 +1386,7 @@ dns_enqueue(const char *name, size_t hostnamelen, dns_found_callback found,
|
||||
}
|
||||
|
||||
/**
|
||||
* @ingroup dns
|
||||
* Resolve a hostname (string) into an IP address.
|
||||
* NON-BLOCKING callback version for use with raw API!!!
|
||||
*
|
||||
@ -1403,7 +1412,9 @@ dns_gethostbyname(const char *hostname, ip_addr_t *addr, dns_found_callback foun
|
||||
return dns_gethostbyname_addrtype(hostname, addr, found, callback_arg, LWIP_DNS_ADDRTYPE_DEFAULT);
|
||||
}
|
||||
|
||||
/** Like dns_gethostbyname, but returned address type can be controlled:
|
||||
/**
|
||||
* @ingroup dns
|
||||
* Like dns_gethostbyname, but returned address type can be controlled:
|
||||
* @param hostname the hostname that is to be queried
|
||||
* @param addr pointer to a ip_addr_t where to store the address if it is already
|
||||
* cached in the dns_table (only valid if ERR_OK is returned!)
|
||||
|
||||
@ -38,6 +38,10 @@
|
||||
*
|
||||
*/
|
||||
|
||||
/**
|
||||
* @defgroup mempool Memory pools
|
||||
*/
|
||||
|
||||
#include "lwip/opt.h"
|
||||
|
||||
#include "lwip/memp.h"
|
||||
|
||||
@ -1,6 +1,10 @@
|
||||
/**
|
||||
* @file
|
||||
* Packet buffer management
|
||||
*/
|
||||
|
||||
/**
|
||||
* @defgroup pbuf PBUF
|
||||
*
|
||||
* Packets are built from the pbuf data structure. It supports dynamic
|
||||
* memory allocation for packet contents or can reference externally
|
||||
@ -165,6 +169,7 @@ pbuf_pool_is_empty(void)
|
||||
#endif /* !LWIP_TCP || !TCP_QUEUE_OOSEQ || !PBUF_POOL_FREE_OOSEQ */
|
||||
|
||||
/**
|
||||
* @ingroup pbuf
|
||||
* Allocates a pbuf of the given type (possibly a chain for PBUF_POOL type).
|
||||
*
|
||||
* The actual memory allocated for the pbuf is determined by the
|
||||
@ -346,7 +351,9 @@ pbuf_alloc(pbuf_layer layer, u16_t length, pbuf_type type)
|
||||
}
|
||||
|
||||
#if LWIP_SUPPORT_CUSTOM_PBUF
|
||||
/** Initialize a custom pbuf (already allocated).
|
||||
/**
|
||||
* @ingroup pbuf
|
||||
* Initialize a custom pbuf (already allocated).
|
||||
*
|
||||
* @param l flag to define header size
|
||||
* @param length size of the pbuf's payload
|
||||
@ -413,6 +420,7 @@ pbuf_alloced_custom(pbuf_layer l, u16_t length, pbuf_type type, struct pbuf_cust
|
||||
#endif /* LWIP_SUPPORT_CUSTOM_PBUF */
|
||||
|
||||
/**
|
||||
* @ingroup pbuf
|
||||
* Shrink a pbuf chain to a desired length.
|
||||
*
|
||||
* @param p pbuf to shrink.
|
||||
@ -616,6 +624,7 @@ pbuf_header_force(struct pbuf *p, s16_t header_size_increment)
|
||||
}
|
||||
|
||||
/**
|
||||
* @ingroup pbuf
|
||||
* Dereference a pbuf chain or queue and deallocate any no-longer-used
|
||||
* pbufs at the head of this chain or queue.
|
||||
*
|
||||
@ -733,7 +742,6 @@ pbuf_free(struct pbuf *p)
|
||||
* @param p first pbuf of chain
|
||||
* @return the number of pbufs in a chain
|
||||
*/
|
||||
|
||||
u8_t
|
||||
pbuf_clen(struct pbuf *p)
|
||||
{
|
||||
@ -748,6 +756,7 @@ pbuf_clen(struct pbuf *p)
|
||||
}
|
||||
|
||||
/**
|
||||
* @ingroup pbuf
|
||||
* Increment the reference count of the pbuf.
|
||||
*
|
||||
* @param p pbuf to increase reference counter of
|
||||
@ -766,6 +775,7 @@ pbuf_ref(struct pbuf *p)
|
||||
}
|
||||
|
||||
/**
|
||||
* @ingroup pbuf
|
||||
* Concatenate two pbufs (each may be a pbuf chain) and take over
|
||||
* the caller's reference of the tail pbuf.
|
||||
*
|
||||
@ -774,7 +784,6 @@ pbuf_ref(struct pbuf *p)
|
||||
*
|
||||
* @see pbuf_chain()
|
||||
*/
|
||||
|
||||
void
|
||||
pbuf_cat(struct pbuf *h, struct pbuf *t)
|
||||
{
|
||||
@ -801,6 +810,7 @@ pbuf_cat(struct pbuf *h, struct pbuf *t)
|
||||
}
|
||||
|
||||
/**
|
||||
* @ingroup pbuf
|
||||
* Chain two pbufs (or pbuf chains) together.
|
||||
*
|
||||
* The caller MUST call pbuf_free(t) once it has stopped
|
||||
@ -865,7 +875,7 @@ pbuf_dechain(struct pbuf *p)
|
||||
}
|
||||
|
||||
/**
|
||||
*
|
||||
* @ingroup pbuf
|
||||
* Create PBUF_RAM copies of pbufs.
|
||||
*
|
||||
* Used to queue packets on behalf of the lwIP stack, such as
|
||||
@ -938,6 +948,7 @@ pbuf_copy(struct pbuf *p_to, struct pbuf *p_from)
|
||||
}
|
||||
|
||||
/**
|
||||
* @ingroup pbuf
|
||||
* Copy (part of) the contents of a packet buffer
|
||||
* to an application supplied buffer.
|
||||
*
|
||||
@ -1037,6 +1048,7 @@ void pbuf_split_64k(struct pbuf *p, struct pbuf **rest)
|
||||
#endif /* LWIP_TCP && TCP_QUEUE_OOSEQ && LWIP_WND_SCALE */
|
||||
|
||||
/**
|
||||
* @ingroup pbuf
|
||||
* Skip a number of bytes at the start of a pbuf
|
||||
*
|
||||
* @param in input pbuf
|
||||
@ -1062,6 +1074,7 @@ pbuf_skip(struct pbuf* in, u16_t in_offset, u16_t* out_offset)
|
||||
}
|
||||
|
||||
/**
|
||||
* @ingroup pbuf
|
||||
* Copy application supplied data into a pbuf.
|
||||
* This function can only be used to copy the equivalent of buf->tot_len data.
|
||||
*
|
||||
@ -1105,6 +1118,7 @@ pbuf_take(struct pbuf *buf, const void *dataptr, u16_t len)
|
||||
}
|
||||
|
||||
/**
|
||||
* @ingroup pbuf
|
||||
* Same as pbuf_take() but puts data at an offset
|
||||
*
|
||||
* @param buf pbuf to fill with data
|
||||
@ -1138,6 +1152,7 @@ pbuf_take_at(struct pbuf *buf, const void *dataptr, u16_t len, u16_t offset)
|
||||
}
|
||||
|
||||
/**
|
||||
* @ingroup pbuf
|
||||
* Creates a single pbuf out of a queue of pbufs.
|
||||
*
|
||||
* @remark: Either the source pbuf 'p' is freed by this function or the original
|
||||
@ -1209,7 +1224,9 @@ pbuf_fill_chksum(struct pbuf *p, u16_t start_offset, const void *dataptr,
|
||||
}
|
||||
#endif /* LWIP_CHECKSUM_ON_COPY */
|
||||
|
||||
/** Get one byte from the specified position in a pbuf
|
||||
/**
|
||||
* @ingroup pbuf
|
||||
* Get one byte from the specified position in a pbuf
|
||||
* WARNING: returns zero for offset >= p->tot_len
|
||||
*
|
||||
* @param p pbuf to parse
|
||||
@ -1229,7 +1246,9 @@ pbuf_get_at(struct pbuf* p, u16_t offset)
|
||||
return 0;
|
||||
}
|
||||
|
||||
/** Put one byte to the specified position in a pbuf
|
||||
/**
|
||||
* @ingroup pbuf
|
||||
* Put one byte to the specified position in a pbuf
|
||||
* WARNING: silently ignores offset >= p->tot_len
|
||||
*
|
||||
* @param p pbuf to fill
|
||||
@ -1248,7 +1267,9 @@ pbuf_put_at(struct pbuf* p, u16_t offset, u8_t data)
|
||||
}
|
||||
}
|
||||
|
||||
/** Compare pbuf contents at specified offset with memory s2, both of length n
|
||||
/**
|
||||
* @ingroup pbuf
|
||||
* Compare pbuf contents at specified offset with memory s2, both of length n
|
||||
*
|
||||
* @param p pbuf to compare
|
||||
* @param offset offset into p at which to start comparing
|
||||
@ -1283,7 +1304,9 @@ pbuf_memcmp(struct pbuf* p, u16_t offset, const void* s2, u16_t n)
|
||||
return 0xffff;
|
||||
}
|
||||
|
||||
/** Find occurrence of mem (with length mem_len) in pbuf p, starting at offset
|
||||
/**
|
||||
* @ingroup pbuf
|
||||
* Find occurrence of mem (with length mem_len) in pbuf p, starting at offset
|
||||
* start_offset.
|
||||
*
|
||||
* @param p pbuf to search, maximum length is 0xFFFE since 0xFFFF is used as
|
||||
@ -1309,7 +1332,8 @@ pbuf_memfind(struct pbuf* p, const void* mem, u16_t mem_len, u16_t start_offset)
|
||||
return 0xFFFF;
|
||||
}
|
||||
|
||||
/** Find occurrence of substr with length substr_len in pbuf p, start at offset
|
||||
/**
|
||||
* Find occurrence of substr with length substr_len in pbuf p, start at offset
|
||||
* start_offset
|
||||
* WARNING: in contrast to strstr(), this one does not stop at the first \0 in
|
||||
* the pbuf/source string!
|
||||
|
||||
@ -135,7 +135,6 @@ static u8_t tcp_timer_ctr;
|
||||
static u16_t tcp_new_port(void);
|
||||
|
||||
/**
|
||||
* @ingroup tcp_raw
|
||||
* Initialize this module.
|
||||
*/
|
||||
void
|
||||
|
||||
@ -89,7 +89,6 @@ static u16_t udp_port = UDP_LOCAL_PORT_RANGE_START;
|
||||
struct udp_pcb *udp_pcbs;
|
||||
|
||||
/**
|
||||
* @ingroup udp_raw
|
||||
* Initialize this module.
|
||||
*/
|
||||
void
|
||||
|
||||
@ -70,12 +70,15 @@ extern const struct memp_desc* const memp_pools[MEMP_MAX];
|
||||
|
||||
#else /* MEMP_MEM_MALLOC */
|
||||
|
||||
/** Declare a private memory pool
|
||||
/**
|
||||
* @ingroup mempool
|
||||
* Declare prototype for private memory pool if it is used in multiple files
|
||||
*/
|
||||
#define LWIP_MEMPOOL_PROTOTYPE(name) extern const struct memp_desc memp_ ## name
|
||||
|
||||
/** Declare a private memory pool
|
||||
/**
|
||||
* @ingroup mempool
|
||||
* Declare a private memory pool
|
||||
* Private mempools example:
|
||||
* .h: only when pool is used in multiple .c files: LWIP_MEMPOOL_PROTOTYPE(my_private_pool);
|
||||
* .c:
|
||||
@ -105,11 +108,20 @@ extern const struct memp_desc* const memp_pools[MEMP_MAX];
|
||||
|
||||
#endif /* MEMP_MEM_MALLOC */
|
||||
|
||||
/** Initialize a private memory pool */
|
||||
/**
|
||||
* @ingroup mempool
|
||||
* Initialize a private memory pool
|
||||
*/
|
||||
#define LWIP_MEMPOOL_INIT(name) memp_init_pool(&memp_ ## name)
|
||||
/** Allocate from a private memory pool */
|
||||
/**
|
||||
* @ingroup mempool
|
||||
* Allocate from a private memory pool
|
||||
*/
|
||||
#define LWIP_MEMPOOL_ALLOC(name) memp_malloc_pool(&memp_ ## name)
|
||||
/** Free element from a private memory pool */
|
||||
/**
|
||||
* @ingroup mempool
|
||||
* Free element from a private memory pool
|
||||
*/
|
||||
#define LWIP_MEMPOOL_FREE(name, x) memp_free_pool(&memp_ ## name, (x))
|
||||
|
||||
#if MEM_USE_POOLS
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user