The functions in this chapter are generic and may have application beyond the Open Powerline Toolkit. In some cases, these functions appear in other Atheros or Open Source software packages. In a few cases, the Toolkit may include complementary or supplementary support functions but only use one or two of them. For example, functions memincr and memdecr are both included but memdecr is not used.

void binout void const * memory size_t extent char c char e FILE * fp Print a memory region as a series of binary octets separated by character c and terminated by character e. Normally, character c will be BIN_EXTENDER, defined in file number.h, but it could be any character value. Normally, character e will be a space or newline, but it could be any character value. A typical use might be to print a register in readable format. For example, specifying c as '-', e as ';' and extent as 4 would produce output looking something like "10101010-1111111-00000000-11001100;" where each octet is expressed as a binary integer. The function is declared in memory.h and defined in binout.c.

unint32_t checksum32 const uint32_t memory [] size_t extent uint32_t checksum Return the 32 bit checksum of a memory region. The checksum is the one's complement of the XOR of all 32 bit words in the region. Argument extent is the region extent in 32 bit words. Argument checksum is the reference checksum. The function will return the computed checksum when referencechecksum is 0 and will return 0 if reference checksum equals the computed checksum. A typical use is to validate PIB and NVM files or compute new checksums when these files are created or modified. The function is declared in memory.h and defined in checksum32.c. This function is similar to checksum_32 but is used exclusively by API functions. It may be deprecated at some point in the future.

unint32_t checksum_32 void const * memory size_t extent uint32_t checksum Return the 32 bit checksum of a memory region. The checksum is the one's complement of the XOR of all 32 bit words in the region. The region extent is specified in bytes but it will be rounded down to the nearest multiple of 4 bytes. Argument checksum is the reference checksum. The function will return the computed checksum when referencechecksum is 0 and will return 0 if reference checksum equals the computed checksum. A typical use is to validate PIB and NVM files or compute new checksums when these files are created or modified. The function is declared in memory.h and defined in checksum_32.c. This function is similar to function checksum32 however there is no need to cast memory to uint32_t and there is no need to round extent down to a multiple of 4 bytes before calling the function because both operations are performed internally. Also, there is no unecessary endian manipulation of the checksum. It is the prefered method of computing a checksum.

void chrout void const * memory size_t extent char c char e FILE * fp Print a memory region as a string of printable ASCII characters terminated by character e. Character c is printed in place of non-printable characters. The string is terminated by character e. Normally, character c is '.' but it could be any character value. Normally, character e is space or newline but it could be any charcter value. A typical use might be to print a memory region that may (or may not) contain an HFID or other printable text. The function is declared in memory.h and defined in chrout.c.

void decout void const * memory size_t extent char c char e FILE * fp Print a memory region as a series of decimal octets separated by character c and terminated by character e. Normally, character c will be DEC_EXTENDER, defined in file number.h, but it could be any character value. Normally, character e will be a space or newline but it could be any character value. A typical use might be to print an IP address in readable format. For example, specifying c as '.', character e as '/' and extent as 4 would produce output looking something like "192.168.099.001/" where each octet is expressed as a decimal integer. The function is declared in memory.h and defined in decout.c.

void endian void * memory size_t extent Reverse the byte order of a memory region. It is a variable extent version of functions like __bswap_16, __bswap_32 and __bswap_64. The function is declared in memory.h and defined in endian.c.

unit32_t fdchecksum32 int fd size_t extent unit32_t checksum Return the 32 bit checksum of a file region starting from the current file position. The checksum is the one's complement of the XOR or of all 32 bit words in the region. Argument extent must be specified in 32 bit words, not bytes. Argument checksum is the reference checksum. The function will return the computed checksum when referencechecksum is 0 and will return 0 if reference checksum equals the computed checksum. A typical use is to validate NVM files header by header or section by section. The function is declared in memory.h and defined in fdchecksum32.c.

unit32_t fdchecksum_32 int fd size_t extent unit32_t checksum Return the 32 bit checksum of a file region starting from the current file position. The checksum is the one's complement of the XOR or of all 32 bit words in the region. Argument extent is specified in bytes but is rounded down to the nearest multiple of 4 bytes. Argument checksum is the reference checksum. The function will return the computed checksum when referencechecksum is 0 and will return 0 if reference checksum equals the computed checksum. A typical use is to validate NVM files header by header or section by section. The function is declared in memory.h and defined in fdchecksum_32.c. This function is similar to function fdchecksum32 but there is no need to round extent down to the nearest multiple of 4 bytes before calling the function because that is done internally. Also, there is no unecessary endian manuipulation of the checksum.

char const * filepart char const * pathname Return the address of the filename portion of a pathname string. The filename portion is everything after the rightmost path separator. If a path separator is not present then the address of the pathname string is returned. This function is similar to the POSIX basename function but it returns an empty string whenever the rightmost character is a path separator. The path separator can be either slash ('/') or backslash ('\\'). The function is declared in files.h and defined in filepart.c.

signed hexdecode void * memory size_t extent char const buffer [] size_t extent Decode a memory region as a string of ASCII hexadecimal digits. Convert memory until the buffer or memory exhausts and return the string extent. Allow three (3) string characters for each memory byte to be decoded. The number of bytes decoded will be the lesser of argument extent divided by 3 or argument extent. The function is declared in memory.h and defined in hexdecode.c.

void hexdump void const * memory size_t offset size_t extent FILE * fp Print a full or partial memory region in hexadecimal format showing memory offsets, hexadecimal byte values and ASCII character values. Argument memory contains some memory region. Argument extent is the region extent. Argument offset is the starting display location. Locations memory [offset] up to memory [extent] are displayed, allowing a partial dump of the memory region. An offset of 0 will display the entire region. The function is declared in memory.h and defined in hexdump.c. This function is similar to but different from function hexview .

signed hexencode void * memory size_t extent char const * string Encode a memory region with the binary equivalent of an ASCII hexadecimal string. Return the number of bytes encoded or 0 on error. The value of errno is set to EINVAL if the number of bytes encoded is less than extent or the entire string cannot be converted due to illegal digits or excessive digits. Ignore optional HEX_EXTENDER characters separating octets in argument string. Constant HEX_EXTENDER is defined in file number.h. The function is declared in memory.h and defined in hexencode.c.

ssize_t hexin void const * memory size_t extent FILE * fp This function is similar to hexencode but it reads from file, instead of a string and ignores non-hexadecimal text and comments within the input stream. Incoming text is binary encoded and written to the specified memory region. The actual number of bytes encoded is returned or -1 on error. See the efsu man page for a thorough explanation of function behavior. The function is declared in memory.h and defined in hexin.c.

void hexout void const * memory size_t extent char c char e FILE * fp Print a memory region as a series of hexdecimal octets separated by character c and termianted by character e. Normally, character c will be HEX_EXTENDER, defined in file number.h, but it could be any character value. Normally, character e will be a space or newline but it could be any character value. A typical use might be to print a MAC or Ethernet address in readable format. For example, specifying c as ':', character e as ',' and extent as 6 would produce output looking something like "00:B0:52:DA:DA:01," where each octet is expressed as a hexadecimal integer. The function is declared in memory.h and defined in hexout.c.

char * hexstring char buffer [] size_t length void const * memory size_t extent Convert a memory region to a NUL terminated string and return the string address. This function is identical to function hexdecode but it return the string address instead of the number of characters decoded. The function is declared in memory.h and defined in hexstring.c.

void hexview void const * memory size_t offset size_t extent FILE * fp Print a partial memory region in hexadecimal format showing memory offsets, hexadecimal byte values and ASCII character values. Argument memory contains part of a larger memory region, much like a file window. Argument extent is the window length. Argument offset is the relative offset of the window within the region. Locations memory [0] up to but excluding memory [extent] are displayed as a partial dump, providing a window into the region. The function is declared in memory.h and defined in hexview.c. This function is similar to but different from function hexdump.

signed memdecr void * memory size_t extent Decrement a multi-byte memory region. Return 0 on success or -1 if all bytes have decremented to 0x00. For example, { 0xFF, 0xFF, 0xFF } decrements to { 0xFF, 0xFF, 0xFE } and { 0xFF, 0x00, 0x00 } decrements to { 0xFE, 0xFF, 0xFF }. A typical use is to iterate through a range if IP or MAC address values. The function is declared in memory.h and defined in memdecr.c.

signed memincr void * memory size_t extent Increment a multi-byte memory region. Return 0 on success or -1 once all bytes have been incremented to 0xFF. For example { 0x00, 0x00, 0x00 } increments to { 0x00, 0x00, 0x01 } and { 0x00, 0xFF, 0xFF } increments to { 0x01, 0x00, 0x00 }. A typical use is to iterate through a range of IP or MAC address values. The function is declared in memory.h and defined in memincr.c.

void memout void const * memory size_t extent char const * format unsigned group signed c FILE * fp Print a memory region as a series of octet groups wach separated by character c. The group argument specifies the number of octets per group. The format argument determines how each octet is displayed. Normally, character c will be one of BIN_EXTENDER, DEC_EXTENDER or HEX_EXTENDER as defined in file number.h, but it could be any character value. The function is declared in memory.h and defined in memout.c.

void memswap void * buffer1 void * buffer2 size_t length Exchange the contents of one buffer with that of another. No provision is made for buffer overlap. No value is returned. A typical use might be to exchange source and destination addresses in an ethernet packet. The function is declared in memory.h and defined in memswap.c.

signed strdecr void * memory size_t extent byte min byte max Decrement a multi-byte memory region using only ASCII character values in the range min through max. Return 0 on success or -1 once all characters have been decremented to the value of argument min. For example, if argument min is 'A' and argument max is 'Z' then { 'A', 'B', 'C' } decrements to { 'A', 'B', 'B' } and { 'B', 'Z', 'Z' } decrements to { 'A', 'A', 'A' }. A typical use is to generate a sequence of distinct character strings to seed encryption key functions. The function is declared in memory.h and defined in strdecr.c.

size_t strfbits char const buffer [] size_t length char const * operands [] char const * operator unsigned flagword Encode a buffer with an enumerated list of the operands associated with the corresponding bits in flagword. separate enumerated operands with an operator string. For example, given char const *operands [] = { "loop", "wait", "busy" } and unsigned flagword = 0x05 then strfbits (buffer, length, operands, "|", flagword) would encode buffer with "loop|busy". Observe that each bit set in flagword appears in buffer as the corresponding string from operands. A typical application for this function is the enumeration of flagword states. The function is declared in format.h and defined in strfbits.c.

signed strincr void * memory size_t extent byte min byte max Increment a multi-byte memory region using only ASCII character values in the range min through max. Return 0 on success or -1 once all characters have been incremented to the value of argument max. For example, if argument min is 'A' and argument max is 'Z' then { 'A', 'B', 'C' } increments to { 'A', 'B', 'D' } and { 'A', 'Z', 'Z' } increments to { 'B', 'A', 'A' }. A typical use is to generate a sequence of distinct character strings to seed encryption key functions. The function is declared in memory.h and defined in strincr.c.

unsigned todigit unsigned c Return the integer value of character c interpreted as digit in the base 36 number system. It is called by many encode functions to support number base conversion. If the value of c is '0' through '9' then integer 0 through 9 is returned. If the value of c is 'A' through 'Z' or 'a' through 'z' then integer 10 through 35 is returned. The function is declared in number.h and defined in todigit.c.

char const * typename const struct _type_ list [] size_t size type_t type char const * name Return the name associated with a message type by searching a list arranged in ascending order by message type. Return argument name as the function value if the message type is not present in the list. Data types struct _type_ and type_t are defined in file types.h. A typical use might be to return the name of message based on the message type. The function is declared in symbol.h and defined in typename.c.