Menu [hide]

Porting Guide

Platform support code for dccp-tp is responsible for the interface between the dccp-tp core code and the base operating system. There are three classes of code that are needed — support routines, platform-specific data types and packet input routines.

Support routines provide typical utility functions and prototypes are defined in dctpSupport.h. The following routines are needed:

  • void dctpoSocketLockInit(dctpSocket *sock) — Each socket has a data structure used to prevent simultaneous access to the socket. This routine initializes whatever data structures are necessary.

  • void dctpoSocketLock(dctpSocket *sock) — Locks a socket. If the socket is already locked, the calling thread is suspended until the socket is unlocked. A socket is never locked more than once before being unlock (no need for recursive locking).

  • void dctpoSocketUnlock(dctpSocket *sock) — Unlocks a socket.

  • void dctpoSocketWait(dctpSocket *sock) — Waits for a condition on a socket. The calling thread (or whatever multitasking structure is in use) is blocked until the socket is signaled by dctpoSocketSignal.

  • void dctpSocketSignal(dctpSocket *sock) — Signals that conditions on a socket have changed and waiting threads should awake and check for the condition they're awaiting.

  • void dctpoObjectLock(dctpSupportMutex_t *lock) — Acquire a lock on an arbitrary object protected by the dctpSupportMutex_t pointed to by 'lock'.

  • void dctpoObjectUnlock(dctpSupportMutex_t *lock) — Release the lock on an arbitrary object.

  • void dctpoMemcpy(void *dest, void *src, int len) — Copy a block of memory from one location to another. Similar to Posix standard 'memcpy'.

  • void dctpoMemset(void *dst, int val, int len) — Set a block of memory of length 'len', to 'val'. Similar to Posix standard 'memcpy'.

  • void *dctpoMalloc(int size) — Allocate a block of memory of length 'size' from the heap or similar. Similar to Posix 'malloc'.

  • void *dctpoRealloc(void *ptr, int size) — Expand (or shrink) the size of a memory region allocated with dctpoMalloc. Similar to the Posix standard 'realloc'.

  • void dctpoFree(void *ptr) — Free a block of memory allocated with dctpoFree or dctpoRealloc. Similar to the Posix standard 'free'.

  • void dctpoStartTimer(dctpTimer *t, uint32_t timeout, dctpTimerAction action, void *arg) — Start a timer that will call the function 'action' with the argument 'arg' after at least 'timeout' microseconds. Timeout action routines will typically need to call functions that will block the thread such as dctpoSocketLock, so care must be taken in implementing the timer function to not serialize the actions of expired timers. It is not an error to start a timer that is already running. The timer is restarted.

  • void dctpoStopTimer(dctpTimer *t) — Stop a timer. The timers action is canceled. It is not an error to stop an already stopped timer.

  • uint64_t dctpoRandomSeqno(void) — Returns a randomly generated 48-bit number. The high-order 16 bits of the return value must be 0.

  • void dctpoLog(int pri, char *form, ...) — Print a log message to whatever logging facility is supplied by the operating system. 'pri' is a priority level taken from the DCTPLOG_ definitions, 'form' is a format string using the 'printf' standard formats. The remaining arguments are defined by the format string. Similar to the Posix function 'syslog'.

  • uint64_t dctpoNow(void) — Returns the current time in microseconds since whatever reference point is used by the system.

  • uint_t dctpoStrlen(char *s) — Returns the length of the zero-terminated string point to by 's'. Similar to the Posix standard 'strlen'.

  • dctpPacket *dctpoPacketMalloc(int size) — Allocate a packet buffer with application data area of at least 'size' bytes. Should also allocate enough buffer space to add normally expected DCCP and IP headers (normally the define DCTPPKT_DEF_HDRSPACE). In the allocated dctpPacket structure, 'buflen' is set to 'size' plus the added header space; 'appdata', 'dccphdr' and 'iphdr' point to just past the allocated header space (to where application data should be added to the packet); 'appdatalen', 'dccphdrlen' and 'chdr.doffset' are set to 0.

  • dctpoPacketFree(dctpPacket *pkt) — Free a packet buffer allocated with dctpoPacketMalloc.

  • dctpoPacketCopyTo(dctpPacket *pkt, uint_t offset, uint8_t *src, uint_t len) — Copy data from contiguous memory to the appdata portion of a packet buffer. 'len' bytes starting at 'src' are copied to 'pkt->appdata[offset]'. If the packet doesn't have enough room in 'appdata', a new packet can be allocated and the old one freed. Returns a pointer to the packet that contains the new data.

  • dctpoPacketCopyFrom(dctpPacket *pkt, uint_t offset, utin8_t *dst, uint_t len) — Copy data from a packet buffer to contiguous memory. Copies 'len' bytes starting at 'pkt->appdata[offset]' to 'dst'.

  • void dctpoPacketCopyData(dctpPacket *dpkt, dctpPacket *spkt) — Copy 'appdata' from 'dpkt' to 'spkt'. The 'appdata' portion of 'spkt' must be big enough to accommodate the data.

  • dctpPacket *dctpoPacketExtendDccpHdr(dctpPacket *pkt, uint_t len) — Extend the 'dccphdr' space by 'len' bytes. A new packet may be allocated (and all data copied). Adds 'len' to 'dccphdrlen'. Returns packet with enough DCCP header space.

  • int dctpoMemcmp(void *s1, void *s2, uint_t len) — Compares two blocks of memory of length 'len'. Returns -1, 0 or 1 if s1 is less than, equal to or greater than s2, respectively. Similar to Posix standard 'memcmp'.

  • uint16_t dctpoHtons(uint16_t h) — Convert 16-bit value from host to network order. Similar to Posix standard 'htons'.

  • uint32_t dctpoHtonl(uint32_t h) — Convert 32-bit value from host to network order. Similar to Posix standard 'htonl'.

  • uint16_t dctpoNtohs(uint16_t ns) — Convert 16-bit value from network to host order. Similar to Posix standard 'ntohs'.

  • uint32_t dctpoNtohl(uint32_t nl) — Convert 32-bit value from network to host order. Similar to Posix standard 'ntohl'.

Platform-specific data types are defined in dctpSupportTypes.h. They provide operating system-specific types for locking and conditions. The types are:

  • dctpSupportMutex_t — An object lock.

  • dctpSupportCond_t — An object conditional wait.

Packet input and output routines — to be completed.

Created by: trphelan last modification: Friday 04 of June, 2010 [19:58:23 UTC] by trphelan