From 43679ae5cb8934ac1f9a6b2a41f08f55979509e5 Mon Sep 17 00:00:00 2001 From: Nathan Houghton Date: Wed, 24 Oct 2018 23:37:06 -0700 Subject: [PATCH] NEEDS REVIEW: Clean up code references, and use extlinks extension to link to github --- docs/conf.py | 5 +- docs/overview.rst | 6 +- docs/software.rst | 18 ++- docs/support.rst | 285 ++++++++++++---------------------------------- plc/plc.h | 4 - tools/Makefile | 2 +- tools/files.h | 1 - 7 files changed, 88 insertions(+), 233 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index 3e80ad76..e010e517 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -25,7 +25,7 @@ # Add any Sphinx extension module names here, as strings. They can be extensions # coming with Sphinx (named 'sphinx.ext.*') or your custom ones. -extensions = [] +extensions = ['sphinx.ext.extlinks'] # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] @@ -240,3 +240,6 @@ # How to display URL addresses: 'footnote', 'no', or 'inline'. #texinfo_show_urls = 'footnote' + +# extlinks configuration -- github sourcecode pages +extlinks = {'gh-src': ('https://github.com/qca/open-plc-utils/blob/master/%s','')} diff --git a/docs/overview.rst b/docs/overview.rst index 8c99af40..d1159d20 100644 --- a/docs/overview.rst +++ b/docs/overview.rst @@ -596,7 +596,7 @@ MDIO Programming A command line utility to read and display Atheros MDIO custom modules in human readable format. This program is installed in folder :file:`/usr/local/bin` with 0555 file permissions. The main source code is located in folder :file:`./mdio`. See the `mdiodump `_ man page for more information. :program:`mdiogen` - A rudimentary command line utility that write a custom MDIO block to a fixed file. The user must edit a data statements, in the main program, to define MDIO command fields. A series of macros then mask, shift and merge the fields to create complete Clause 22 or Clause 45 MDIO commands on output. The program has no dependencies on other toolkit modules and so it will compile anywhere. This program must be manually compiled and it is not automatically installed. The main source code is located in folder :file:`./mdio` and file `mdio.h `_ is required for compilation. There are no help files available at this time. If you do not understand how to use it then you may not need it. + A rudimentary command line utility that write a custom MDIO block to a fixed file. The user must edit a data statements, in the main program, to define MDIO command fields. A series of macros then mask, shift and merge the fields to create complete Clause 22 or Clause 45 MDIO commands on output. The program has no dependencies on other toolkit modules and so it will compile anywhere. This program must be manually compiled and it is not automatically installed. The main source code is located in folder :file:`./mdio` and file :gh-src:`mdio.h ` is required for compilation. There are no help files available at this time. If you do not understand how to use it then you may not need it. .. _programs-serial: @@ -655,14 +655,14 @@ Folder descriptions appear below in alphabetical order: Miscellaneous shell scripts that call various programs in this package to perform tasks such as flashing a FW2.0 device. Care must be taken here to ensure that environment variables at the start of each script are appropriate for your system. ./ram - Support modules for reading, printing and checking NVRAM and SDRAM configuration files. The :file:`.cfg` files in this folder have a different format than the :file:`.config` files released with the Atheros Windows :program:`Device Manager`. The files distributed with the Windows :program:`Device Manger` are 64 ASCII character with no checksum. The files in this directory are 32 binary bites with trailing checksum. Users may create new sdram configuration files by compiling `sdram.c `_, using :command:`gcc -o sdram sdram.c` and running it without any command line arguments. + Support modules for reading, printing and checking NVRAM and SDRAM configuration files. The :file:`.cfg` files in this folder have a different format than the :file:`.config` files released with the Atheros Windows :program:`Device Manager`. The files distributed with the Windows :program:`Device Manger` are 64 ASCII character with no checksum. The files in this directory are 32 binary bites with trailing checksum. Users may create new sdram configuration files by compiling :gh-src:`sdram.c `, using :command:`gcc -o sdram sdram.c` and running it without any command line arguments. ./tools Source code and header files used by virtually all programs in the toolkit. These files are generic and have application beyond this package. They provide GNU/Linux-style or POSIX-style functionality to programs running in environments that do not have either. They also implement operations like checksum computation and multi-byte hexadecimal encoding and decoding. See :ref:`Support Function Reference ` for more information. ./VisualStudioNET Components unique to Microsoft Windows are kept in and under this folder. Specifically, it contains a *Visual Studio .NET* solution to compile most of the programs in this package using only Microsoft and WinPcap libraries. Compiled .exe files can be run on Windows enabled systems having :program:`WinPcap` installed. Adjustments may be necessary depending on your environment. - Microsoft does not provide full POSIX support on Windows platforms. Consequently, alternative headers and libraries are included under this folder. For example, an abridged version of `unistd.h `_ and an alternative version of `stdint.h `_ are included under :file:`VisualStudioNET/include`. Other significant header files included here are `ethernet.h `_, `if_ether.h `_ and `in.h `_. Subfolder :file:`VisualStudio\\Library` contains *WinPcap* libraries. These folders are referenced in appropriate compiler and linker options for Microsoft Development environments. + Microsoft does not provide full POSIX support on Windows platforms. Consequently, alternative headers and libraries are included under this folder. For example, an abridged version of :gh-src:`unistd.h ` and an alternative version of :gh-src:`stdint.h ` are included under :file:`VisualStudioNET/include`. Other significant header files included here are :gh-src:`ethernet.h `, :gh-src:`if_ether.h ` and :gh-src:`in.h `. Subfolder :file:`VisualStudio\\Library` contains *WinPcap* libraries. These folders are referenced in appropriate compiler and linker options for Microsoft Development environments. .. _overview-packages: diff --git a/docs/software.rst b/docs/software.rst index 6099a1b1..e7afcba2 100644 --- a/docs/software.rst +++ b/docs/software.rst @@ -236,11 +236,11 @@ The Atheros :program:`Open Powerline Toolkit` includes a *Visual Studio .NET* so - All projects should globally define preprocessor constant ``MAKEFILE`` to prevent proliferation of "already defined" link errors. See :ref:`Stand-alone Compiling on GNU/Linux ` for an explanation of this constant. -- All projects search folder :file:`..\\include` for `stdint.h `_ and `unistd.h `_ because Microsoft does not provide them. These header files are customized or abbreviated versions of their POSIX counterparts and should be used when originals are available. +- All projects search folder :file:`..\\include` for :gh-src:`stdint.h ` and :gh-src:`unistd.h ` because Microsoft does not provide them. These header files are customized or abbreviated versions of their POSIX counterparts and should be used when originals are available. - Projects that perform raw Ethernet I/O should globally define preprocessor constant ``WINPCAP`` to enable appropriate code segments. Preprocessor error statements should (but may not) alert you if ``WINPCAP`` is not defined on *Windows* platforms. -- Projects that perform raw Ethernet I/O search folder :file:`..\\include` for :program:`WinPcap` header files. These files are taken from the :program:`WinPcap` development package and may require periodic updates. Header files `pcap.h `_, `pca-stdinc.h `_, `pcap-bpf.h `_, `ipv6_misc.h `_ and `bittypes.h `_ belong in folder :file:`VisualStudioNET\\include`. Other header files belong in folder :file:`VisualStudioNET\\include\\pcap`. +- Projects that perform raw Ethernet I/O search folder :file:`..\\include` for :program:`WinPcap` header files. These files are taken from the :program:`WinPcap` development package and may require periodic updates. Header files :gh-src:`pcap.h `, :gh-src:`pcap-stdinc.h `, :gh-src:`pcap-pbf.h `, and :gh-src:`bittypes.h ` belong in folder :file:`VisualStudioNET\\include`. Other header files belong in folder :file:`VisualStudioNET\\include\\pcap`. - Projects that perform raw Ethernet I/O should include folder :file:`..\\library` for core :program:`WinPcap` libraries. @@ -251,9 +251,9 @@ The Atheros :program:`Open Powerline Toolkit` includes a *Visual Studio .NET* so Header Files ============ -Atheros :program:`Open Powerline Toolkit` programs reference POSIX functions and constants where possible. Specifically, they make wide use of the data types ``uint8_t``, ``uint16_t`` and ``uint32_t`` which are defined in file :file:`stdint.h`. Microsoft *Visual C* and *.NET* environments do not include this file. Consequently, Atheros provides an `alternative stdint.h `_ in folder :file:`../Windows/include`. This file is open source and was designed to be compatible with the Microsoft development environments; however, you may occassionally experience warnings about the "benign redefinition" for some of these data types. +Atheros :program:`Open Powerline Toolkit` programs reference POSIX functions and constants where possible. Specifically, they make wide use of the data types ``uint8_t``, ``uint16_t`` and ``uint32_t`` which are defined in file :file:`stdint.h`. Microsoft *Visual C* and *.NET* environments do not include this file. Consequently, Atheros provides an :gh-src:`alternative stdint.h ` in folder :file:`../Windows/include`. This file is open source and was designed to be compatible with the Microsoft development environments; however, you may occassionally experience warnings about the "benign redefinition" for some of these data types. -Where possible, this toolkit includes *OpenBSD* network constants because the OpenBSD project pioneered many of the common network protocols and applications used today. Some systems do not include all *OpenBSD* network header files or do not define all *OpenBSD* network constants. Specifically, Microsoft systems do not provide file :file:`netinet/if_ether.h` and so an `alternative if_ether.h `_ is included in folder :file:`../Windows/include/netinet` and *Windows* applications should include it. +Where possible, this toolkit includes *OpenBSD* network constants because the OpenBSD project pioneered many of the common network protocols and applications used today. Some systems do not include all *OpenBSD* network header files or do not define all *OpenBSD* network constants. Specifically, Microsoft systems do not provide file :file:`netinet/if_ether.h` and so an :gh-src:`alternative if_ether.h ` is included in folder :file:`../Windows/include/netinet` and *Windows* applications should include it. When the :command:`gcc -std=iso9899:1999` option is enabled, some *OpenBSD* header files found on :program:`GNU/Linux` systems will exclude required constant definitions because they do not conform to that standard. Atheros is investigating the best way to address this problem. @@ -419,7 +419,7 @@ Endian-ness Atheros vendor-specific messages contain information in mixed endian format. The Ethernet header portion is sent *big endian* but the Atheros header and payload are sent in *little endian*. The traditional endian converstion functions ``htons()``, ``htonl()``, ``ntohs()`` and ``ntohl()`` can be used to perform platform independent conversions on the Ethernet header but not the Atheros header payload. -The Open Powerline Toolkit includes similar macros ``HTOLE16``, ``HTOLE32``, ``LE16TOH`` and ``LE32TOH`` in `endian.h `_ which serve the same function but conform to recommendations for standarized byte order function on Linux, OpenBSD and FreeBSD. Observe that the names are independent of any network implications. +The Open Powerline Toolkit includes similar macros ``HTOLE16``, ``HTOLE32``, ``LE16TOH`` and ``LE32TOH`` in :gh-src:`endian.h ` which serve the same function but conform to recommendations for standarized byte order function on Linux, OpenBSD and FreeBSD. Observe that the names are independent of any network implications. .. code-block:: c @@ -441,8 +441,6 @@ The Open Powerline Toolkit includes similar macros ``HTOLE16``, ``HTOLE32``, ``L #error "Undefined host byte order." #endif -In addition, the Open Powerline Toolkit includes function :ref:`endian ` that reverses byte order over a variable-length memory region. - .. _packet-basics: Packet Basics @@ -458,7 +456,7 @@ The Ethernet header must be transmitted in newtwork byte order which is big-endi | Ethernet Header | Ethernet Payload | +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+ ... +---+---+ -Ethernet headers consist of a destination address (``ODA``), a source address (``OSA``) and an ethertype (``MTYPE``). The ethertype is always 0x88E1 for Homeplug frames of any type. Programmers may use either function `EthernetHeader.c `_ or `EncodeEthernetHeader `_ to encode a buffer with the ODA and OSA and the HomePlug ethertype. An example appears later on. Structure ``header_eth`` is defined in `ihp.h `_ for this purpose. +Ethernet headers consist of a destination address (``ODA``), a source address (``OSA``) and an ethertype (``MTYPE``). The ethertype is always 0x88E1 for Homeplug frames of any type. Programmers may use either function :gh-src:`EthernetHeader.c ` to encode a buffer with the ODA and OSA and the HomePlug ethertype. An example appears later on. Structure ``ethernet_hdr`` is defined in :gh-src:`mme.h ` for this purpose. :: @@ -466,7 +464,7 @@ Ethernet headers consist of a destination address (``ODA``), a source address (` | ODA | OSA | MTYPE | Ethernet Payload | +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+ ... +---+---+ -Management messages consist of a message header (MMHEADER) and a message entry (MMENTRY). The message header identifies the nature of the message entry that follows it. The acronyms MME and MMENTRY both mean Management Message Entry but they are often used to mean the entire management message or Ethernet frame. This imprecise usage can be confusing at times. Structure ``header_mme`` is defined in `ihp.h `_ for this purpose. +Management messages consist of a message header (MMHEADER) and a message entry (MMENTRY). The message header identifies the nature of the message entry that follows it. The acronyms MME and MMENTRY both mean Management Message Entry but they are often used to mean the entire management message or Ethernet frame. This imprecise usage can be confusing at times. Structure ``homeplug_hdr`` is defined in :gh-src:`mme.h ` for this purpose. :: @@ -484,7 +482,7 @@ The message header contains message protocol version (MMV), message type (MMTYPE The MMV value, within MMHEADER, indicates the Homeplug AV Management Message protocol version which determines how the message should be interpreted. The protocol version is defined in the HomePlug AV Specification and may change from time to time. One notable change is the recent insertion of an FMI (Fragment Management Information ) field between MMTYPE and OUI , as shown below. -In most cases, protocol changes are hidden from the application by the Atheros API functions; however, software developers should set the ``HOMEPLUG_MMV`` constant, defined in `ihp.h `_, to the version appropriate for their firmware or application. The value of this constant enables or disables conditional compilation statements throughout the HomePlug API code base. +In most cases, protocol changes are hidden from the application by the Atheros API functions; however, software developers should set the ``HOMEPLUG_MMV`` constant, defined in :gh-src:`homeplug.h `, to the version appropriate for their firmware or application. The value of this constant enables or disables conditional compilation statements throughout the HomePlug API code base. To send an MME, you must encode an Ethernet frame buffer with information and transmit it. To read an MME, you must read an Ethernet frame buffer and decode it. The information necessary to encode or decode Atheros vendor-specific Ethernet frames is covered in the INT6000 Firmware Technical Reference Manual; however, the Atheros HomePlug API includes many buffer encode and decode functions that support basic operational requirements. diff --git a/docs/support.rst b/docs/support.rst index 09c88869..b6593446 100644 --- a/docs/support.rst +++ b/docs/support.rst @@ -24,7 +24,7 @@ assist .. c:function:: void assist(char const *name, char const *type, const struct _code_ list[], size_t size, FILE *fp) -Show why a symbolic ``name`` was rejected by function :ref:`lookup ` or similar functions. Argument ``type`` contains a title for the class of names stored in ``list``. This function prints an error message on file stream ``fp`` showing the program name, the ``type`` string, the symbolic ``name`` and all names stored in the ``list``. The ``_code_`` structure is declared in `types.h `_. The function is declared in `symbol.h `_ and defined in `assist.c `_. Function :ref:`expect ` is used to print list names. +Show why a symbolic ``name`` was rejected by function :ref:`lookup ` or similar functions. Argument ``type`` contains a title for the class of names stored in ``list``. This function prints an error message on file stream ``fp`` showing the program name, the ``type`` string, the symbolic ``name`` and all names stored in the ``list``. The ``_code_`` structure is declared in :gh-src:`types.h `. The function is declared in :gh-src:`symbol.h ` and defined in :gh-src:`assist.c `. .. _support-basespec: @@ -33,7 +33,7 @@ basespec .. c:function:: uint64_t basespec(char const *string, unsigned base, unsigned size) -Return the unsigned integer equivalent of a numeric ``string``. Print an error message on ``stderr`` and exit the program with status ``1`` if a syntax error occurs or the result exceeds the capacity of the requested integer ``size`` in bytes. If ``base`` is ``0``, numeric values may be expressed in decimal, hexadecimal or binary notation where hexadecimal values start with ``"0x"`` and binary values start with ``"0b"``. When ``base`` is non-zero, the notation in ``string`` must conform to the corresponding number base rules. Applications should cast the return value to the appropriate data type prevent loss-of-data compiler warnings. This function is typically used to convert and length-check integers entered as command line arguments. The function is declared in `number.h `_ and defined in `basespec.c `_. +Return the unsigned integer equivalent of a numeric ``string``. Print an error message on ``stderr`` and exit the program with status ``1`` if a syntax error occurs or the result exceeds the capacity of the requested integer ``size`` in bytes. If ``base`` is ``0``, numeric values may be expressed in decimal, hexadecimal or binary notation where hexadecimal values start with ``"0x"`` and binary values start with ``"0b"``. When ``base`` is non-zero, the notation in ``string`` must conform to the corresponding number base rules. Applications should cast the return value to the appropriate data type prevent loss-of-data compiler warnings. This function is typically used to convert and length-check integers entered as command line arguments. The function is declared in :gh-src:`number.h ` and defined in :gh-src:`basespec.c `. Like function :ref:`uintspec `, this function both converts and range checks numeric string values, but the minimum and maximum value are implicit in the ``size`` of the integer. The minimum value is always ``0`` and the maximum value can be computed by ``((1 << size << 3) - 1)``. @@ -44,7 +44,7 @@ bytespec .. c:function:: void bytespec(char const *string, void *memory, size_t extent) -Encode a ``memory`` region with the binary equivalent of a fixed-length hexadecimal string. Print an error message on stderr and exit the program with status ``1`` if a syntax error occurs or the number of octets does not equal ``extent``. Hexadecimal octets may be separated by colons for readability but colons are not required. Empty octets are illegal. The function is declared in `memory.h `_ and defined in `bytespec.c `_. +Encode a ``memory`` region with the binary equivalent of a fixed-length hexadecimal string. Print an error message on stderr and exit the program with status ``1`` if a syntax error occurs or the number of octets does not equal ``extent``. Hexadecimal octets may be separated by colons for readability but colons are not required. Empty octets are illegal. The function is declared in :gh-src:`memory.h ` and defined in :gh-src:`bytespec.c `. This function is typically used to enter fixed-length data, like hardware addresses and encryption keys, on the command line. @@ -55,7 +55,7 @@ checkfilename .. c:function:: bool checkfilename(char const *filename) -Return logical ``true`` if the ``filename`` argument contains only letters, digits, slashes, periods, underscores and hyphens. This function can be used to detect cases where a user accidentally entered an Ethernet address in place of a filename on the command line. Ethernet address strings are, as it happens, also valid filenames. The function is declared in `files.h `_ and defined in `checkfilename.c `_. +Return logical ``true`` if the ``filename`` argument contains only letters, digits, slashes, periods, underscores and hyphens. This function can be used to detect cases where a user accidentally entered an Ethernet address in place of a filename on the command line. Ethernet address strings are, as it happens, also valid filenames. The function is declared in :gh-src:`files.h ` and defined in :gh-src:`checkfilename.c `. .. _support-dataspec: @@ -64,7 +64,7 @@ dataspec .. c:function:: void dataspec(char const *string, void *memory, size_t extent) -Encode a ``memory`` region with the binary equivalent of a variable-length hexadecimal string. Print an error message on stderr and exit the program with the status ``1`` if a syntax error occurs or the number of octets exceeds ``extent``. The number of octets may, however, be less than ``extent``. Unlike function :ref:`bytespec `, hexadecimal octets may not be separated by colons. This function is typically used to enter variable-length data from the command line. The function is declared in `memory.h `_ and defined in `dataspec.c `_. +Encode a ``memory`` region with the binary equivalent of a variable-length hexadecimal string. Print an error message on stderr and exit the program with the status ``1`` if a syntax error occurs or the number of octets exceeds ``extent``. The number of octets may, however, be less than ``extent``. Unlike function :ref:`bytespec `, hexadecimal octets may not be separated by colons. This function is typically used to enter variable-length data from the command line. The function is declared in :gh-src:`memory.h ` and defined in :gh-src:`dataspec.c `. .. _support-error: @@ -73,19 +73,10 @@ error .. c:function:: void error(int exitcode, errno_t number, char const *format, ...) -This function works like printf except that printed messages appear on ``stderr`` and are prefixed with the program name and error information. If argument ``errno`` is non-zero then messages are prefixed with the system error description. If argument ``exitcode`` is non-zero then function ``error`` exits the program with value ``exitcode`` after printing the message and does not return to the caller. The function is declared in `error.h `_ and defined in `error.c `_. +This function works like printf except that printed messages appear on ``stderr`` and are prefixed with the program name and error information. If argument ``errno`` is non-zero then messages are prefixed with the system error description. If argument ``exitcode`` is non-zero then function ``error`` exits the program with value ``exitcode`` after printing the message and does not return to the caller. The function is declared in :gh-src:`error.h ` and defined in :gh-src:`error.c `. This function is used to print informative error messages on the console and prevent program execution from proceeding when input is invalid or some error condition exists. -.. _support-expect: - -expect ------- - -.. c:function:: void expect(const struct _code_ list[], size_t size, FILE *fp) - -Display all names in argument ``list`` on file stream ``fp``. This function is called by runction :ref:`assist ` to print the list of symbolic names but other function may have use for it. The ``_code_`` structure is declared in `types.h `_. The function is declared in `symbol.h `_ and defined in `expect.c `_. - .. _support-getoptv: getoptv @@ -93,7 +84,7 @@ getoptv .. c:function:: int getoptv(int argc, char const *argv[], char const *optv[]) -A custom version of the POSIX function ``getopt``. It supports standard global variables ``optind``, ``opterr``, ``optopt`` and ``optarg`` and the non-standard variable ``optmin``. It extracts the program name from ``argv[0]`` and sets global string pointer ``program_name`` for use by functions ``alert``, ``error`` and others. Options ``-?`` and ``--help`` both display program information on ``stdout``. Options ``-!`` and ``--version`` both display program version information on ``stdout``. String vector ``optv`` includes both the standard argument ``optstring`` and usage text found in many programs. The function is declared in `getoptv.h `_ and defined in `getoptv.c `_. +A custom version of the POSIX function ``getopt``. It supports standard global variables ``optind``, ``opterr``, ``optopt`` and ``optarg`` and the non-standard variable ``optmin``. It extracts the program name from ``argv[0]`` and sets global string pointer ``program_name`` for use by functions ``alert``, ``error`` and others. Options ``-?`` and ``--help`` both display program information on ``stdout``. Options ``-!`` and ``--version`` both display program version information on ``stdout``. String vector ``optv`` includes both the standard argument ``optstring`` and usage text found in many programs. The function is declared in :gh-src:`getoptv.h ` and defined in :gh-src:`getoptv.c `. .. _support-ipv4spec: @@ -102,7 +93,7 @@ ipv4spec .. c:function:: size_t ipv4spec(char const *string, void *memory) -Encode a 4-byte ``memory`` region with an IPv4 dotted-decimal ``string`` and return the number of bytes encoded. Terminate the program with an error message and exitcode of ``1`` on conversion error. The value returned by this function is always ``4`` and memory is always encoded in network byte order. This function is typically used to convert IPv4 strings entered as command line arguments. The function is declared in `memory.h `_ and defined in `ipv4spec.c `_. +Encode a 4-byte ``memory`` region with an IPv4 dotted-decimal ``string`` and return the number of bytes encoded. Terminate the program with an error message and exitcode of ``1`` on conversion error. The value returned by this function is always ``4`` and memory is always encoded in network byte order. This function is typically used to convert IPv4 strings entered as command line arguments. The function is declared in :gh-src:`memory.h ` and defined in :gh-src:`ipv4spec.c `. Dotted-decimal format consists of decimal values in the range 0 through 255. Each value represents one octet or 8-bit value. IPv4 addresses require 4 such values separated by one decimal point. This function permits empty octets and leading zeros within octets. For example, "..." is equivalent to "0.0.0.0" and "127.0.000.001" is equivalent to "127.0.0.1". The second example will encode memory as follows ``{ 0x7F, 0x00, 0x00, 0x01 }`` which is in network byte order, or big endian. @@ -113,7 +104,7 @@ ipv6spec .. c:function:: size_t ipv6spec(char const *string, void *memory) -Encode a 16-byte ``memory`` region with an IPv6 colon-separated hexadecimal quartet ``string`` and return the number of bytes encoded. Terminate the program with an error message and exitcode of ``1`` on conversion error. The value returned by this function is always ``16`` and memory is always encoded in network byte order. This function is typically used to convert IPv6 strings entered as command line arguments. The function is declared in `memory.h `_ and defined in `ipv6spec.c `_. +Encode a 16-byte ``memory`` region with an IPv6 colon-separated hexadecimal quartet ``string`` and return the number of bytes encoded. Terminate the program with an error message and exitcode of ``1`` on conversion error. The value returned by this function is always ``16`` and memory is always encoded in network byte order. This function is typically used to convert IPv6 strings entered as command line arguments. The function is declared in :gh-src:`memory.h ` and defined in :gh-src:`ipv6spec.c `. Colon-separated hexadecimal quartet notation consists of hexadecimal values in the range 0 through FFFF. Each value represents a quartet or a 32-bit value. IPv6 addresses require 8 quartets separated by one colon. By convention, an empty quartet expands with enough zeros to right-justify the remainder of the address. This function permits multiple empty quartets and leading zeros within quartets. When multiple empty quartets appear, only the right-most occurance expands to zeros. For example, "AA12::BB34::CC56::DD78" is equivalent to "AA12:0000:BB34:0000:CC56:0000:0000:DD78" because only the right-most empty field expands. This will encode memory as follows ``{ 0xAA, 0x12, 0x00, 0x00, 0xBB, 0x34, 0x00, 0x00, 0xCC, 0x56, 0x00, 0x00, 0x00, 0x00, 0xDD, 0x78 }`` which is in network byte order, or big-endian. @@ -124,7 +115,7 @@ lookup .. c:function:: signed lookup(char const *name, const struct _code_ list[], size_t size) -Lookup a symbolic ``name`` in a ``list`` and return an associated integer or ``-1`` if the ``name`` does not appear in the ``list``. A typical use is the translation of symbolic command line arguments to integer codes. For example, some Toolkit programs assign symbolic names to field codes so that users can enter names instead of numbers. This approach becomes more useful as the number of permitted codes increases. The ``_code_`` structure is declared in `types.h `_. The function is declared in `symbol.h `_ and defined in `lookup.c `_. +Lookup a symbolic ``name`` in a ``list`` and return an associated integer or ``-1`` if the ``name`` does not appear in the ``list``. A typical use is the translation of symbolic command line arguments to integer codes. For example, some Toolkit programs assign symbolic names to field codes so that users can enter names instead of numbers. This approach becomes more useful as the number of permitted codes increases. The ``_code_`` structure is declared in :gh-src:`types.h `. The function is declared in :gh-src:`symbol.h ` and defined in :gh-src:`lookup.c `. This function offers two benefits: 1) multiple symbols can translate to one code and 2) names can be changed or new names added without affecting program logic. This function is similar to but different from function :ref:`synonym ` which returns a character string instead of an integer. @@ -135,7 +126,7 @@ putoptv .. c:function:: void putoptv(char const *optv[]) -Print program information on ``stdout``. Program information is stored in string vector ``optv``. String indexes are defined in file :file:`putoptv.h`. String ``optv[0]`` is the POSIX standard argument ``optstring``. This function is called by function ``getoptv`` whenever option ``-?`` or ``--help`` is detected on the command line. There is virtually no need to call this function directly. The function is declared in `putoptv.h `_ and defined in `putoptv.c `_. +Print program information on ``stdout``. Program information is stored in string vector ``optv``. String indexes are defined in file :file:`putoptv.h`. String ``optv[0]`` is the POSIX standard argument ``optstring``. This function is called by function ``getoptv`` whenever option ``-?`` or ``--help`` is detected on the command line. There is virtually no need to call this function directly. The function is declared in :gh-src:`putoptv.h ` and defined in :gh-src:`putoptv.c `. .. _support-synonym: @@ -144,7 +135,7 @@ synonym .. c:function:: char const *synonym(char const *string, const struct _term_ list[], size_t size) -Lookup a symbolic ``name`` in a ``list`` and return an associated string or the original ``string`` if the ``name`` does not appear in the ``list``. A typical use is the translation of symbolic command line arguments to their equivalent numeric strings before encoding them. For example, many Toolkit programs convert the command line argument "local" to "00:B0:52:00:00:01" before encoding the device MAC address. The ``_term_`` structure is declared in `types.h `_. The function is declared in `symbol.h `_ and defined in `synonym.c `_. +Lookup a symbolic ``name`` in a ``list`` and return an associated string or the original ``string`` if the ``name`` does not appear in the ``list``. A typical use is the translation of symbolic command line arguments to their equivalent numeric strings before encoding them. For example, many Toolkit programs convert the command line argument "local" to "00:B0:52:00:00:01" before encoding the device MAC address. The ``_term_`` structure is declared in :gh-src:`types.h `. The function is declared in :gh-src:`symbol.h ` and defined in :gh-src:`synonym.c `. This function is similar to but different from function :ref:`lookup ` which returns an integer instead of a character string. @@ -155,7 +146,7 @@ uintspec .. c:function:: uint64_t uintspec(char const *string, uint64_t minimum, uint64_t maximum) -Return the unsigned integer equivalent of a numeric ``string``. Print an error message on ``stderr`` and exit the program with the value ``1`` when a syntax error occurs or the result exceeds the specified ``minimum`` or ``maximum`` value. Numeric values may be expressed in decimal, hexadecimal or binary notation where hexadecimal values start with ``"0x"`` and binary values start with ``"0b"``. Applications should cast the return value to the appropriate data type to avoid loss-of-data warnings on some compilers. This function is typically used to convert and range-check integer values entered as command-line arguments. The function is declared in `number.h `_ and defined in `uintspec.c `_. +Return the unsigned integer equivalent of a numeric ``string``. Print an error message on ``stderr`` and exit the program with the value ``1`` when a syntax error occurs or the result exceeds the specified ``minimum`` or ``maximum`` value. Numeric values may be expressed in decimal, hexadecimal or binary notation where hexadecimal values start with ``"0x"`` and binary values start with ``"0b"``. Applications should cast the return value to the appropriate data type to avoid loss-of-data warnings on some compilers. This function is typically used to convert and range-check integer values entered as command-line arguments. The function is declared in :gh-src:`number.h ` and defined in :gh-src:`uintspec.c `. .. _support-version: @@ -164,7 +155,7 @@ version .. c:function:: void version(void) -Print package and program version information on ``stdout``. This function is called by function ``getoptv`` whenever option ``-!`` or ``--version`` is detected on the command line. There is no need to call this function directly. The function is declared in `version.h `_ and defined in `version.c `_. Constants ``PACKAGE`` and ``VERSION`` define the information that is displayed. They are defined in file `version.h `_ and must be maintained by developers. +Print package and program version information on ``stdout``. This function is called by function ``getoptv`` whenever option ``-!`` or ``--version`` is detected on the command line. There is no need to call this function directly. The function is declared in :gh-src:`version.h ` and defined in :gh-src:`version.c `. Constants ``PACKAGE`` and ``VERSION`` define the information that is displayed. They are defined in file :gh-src:`version.h ` and must be maintained by developers. .. _support-ethernet: @@ -223,7 +214,7 @@ The channel structure contains enough information to perform raw Ethernet I/O in ``flags`` A bitmap where each bit enables a special behavior during channel open or close or packet read or write. Of general interest is the ``CHANNEL_VERBOSE`` bit which prints outgoing and incoming frames on stderr in hexadecimal dump format. The verbose feature is implemented in for all toolkit programs that perform raw Ethernet I/O and is helpful when debugging device behavior. -Since toolkit applications typically communicate with one powerline device at a time, this structure is statically initialized in a stand-alone module that is linked into each application. It is possible to dynamically initialize it, if needed. The structure is declared in `channel.h `_ and statically defined in `channel.c `_. +Since toolkit applications typically communicate with one powerline device at a time, this structure is statically initialized in a stand-alone module that is linked into each application. It is possible to dynamically initialize it, if needed. The structure is declared in :gh-src:`channel.h ` and statically defined in :gh-src:`channel.c `. .. _support-closechannel: @@ -232,7 +223,7 @@ closechannel .. c:function:: signed closechannel(struct channel *channel) -Close the Ethernet socket associated with a channel and free associated memory and data structures. Return ``0`` on success. Return ``-1`` on failure. This function is declared in `channel.h `_ and defined in `closechannel.c `_. +Close the Ethernet socket associated with a channel and free associated memory and data structures. Return ``0`` on success. Return ``-1`` on failure. This function is declared in :gh-src:`channel.h ` and defined in :gh-src:`closechannel.c `. .. _support-openchannel: @@ -243,7 +234,7 @@ openchannel Open an Ethernet socket that supports the specified protocol and associate it with the interface referenced by the ``channel`` structure .name member. Initialize the interface as needed. The ``protocol`` effectively filters incoming frames for the application. -Interface initialization differs significantly from environment to environment. The socket descriptor is stored in the ``channel`` structure .fd member and the interface hardware address is stored in the ``channel`` structure .host member. Return ``0`` on success. Terminate the program with an error message on failure. This function is declared in `channel.h `_ and defined in `openchannel.c `_. +Interface initialization differs significantly from environment to environment. The socket descriptor is stored in the ``channel`` structure .fd member and the interface hardware address is stored in the ``channel`` structure .host member. Return ``0`` on success. Terminate the program with an error message on failure. This function is declared in :gh-src:`channel.h ` and defined in :gh-src:`openchannel.c `. .. _support-readpacket: @@ -252,7 +243,7 @@ readpacket .. c:function:: signed readpacket(struct channel *channel, void *packet, signed length) -Read one Ethernet frame from the specified channel. The frame is written into memory starting at address ``packet`` and is truncated to the specified ``length``, if necessary. Return the actual number of bytes read on success. Return ``0`` on timeout. Return ``-1`` on network error. This function behaves like the standard library ``read`` function. The target memory region remains unchanged on timeout or error. This function is declared in `channel.h `_ and defined in `readpacket.c `_. +Read one Ethernet frame from the specified channel. The frame is written into memory starting at address ``packet`` and is truncated to the specified ``length``, if necessary. Return the actual number of bytes read on success. Return ``0`` on timeout. Return ``-1`` on network error. This function behaves like the standard library ``read`` function. The target memory region remains unchanged on timeout or error. This function is declared in :gh-src:`channel.h ` and defined in :gh-src:`readpacket.c `. On systems using Berkeley Packet Filters, such as MacOS X, the ``ODA`` field is automatically replaced on transmission to prevent Ethernet address spoofing. This may not be true on other systems but the practice is becoming more common. @@ -263,7 +254,7 @@ sendpacket .. c:function:: signed sendpacket(struct channel *channel, void *packet, signed length) -Write one Ethernet frame to the specified channel. The frame is read from memory starting at address ``packet`` and ending at the specified ``length``. Return the actual number of bytes sent on success. Return ``0`` on timeout. Return ``-1`` on network error. The frame should be properly formatted as an ethernet frame and must be at least 60 bytes long or it will not be sent. This function behaves like the standard library ``write`` function. The source memory region is not modified. This function is declared in `channel.h `_ and defined in `sendpacket.c `_. +Write one Ethernet frame to the specified channel. The frame is read from memory starting at address ``packet`` and ending at the specified ``length``. Return the actual number of bytes sent on success. Return ``0`` on timeout. Return ``-1`` on network error. The frame should be properly formatted as an ethernet frame and must be at least 60 bytes long or it will not be sent. This function behaves like the standard library ``write`` function. The source memory region is not modified. This function is declared in :gh-src:`channel.h ` and defined in :gh-src:`sendpacket.c `. .. _support-network: @@ -344,7 +335,7 @@ binout .. c:function:: 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 `_. +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 :gh-src:`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 :gh-src:`memory.h ` and defined in :gh-src:`binout.c `. .. _support-checksum32: @@ -353,20 +344,7 @@ checksum32 .. c:function:: 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 reference ``checksum`` 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 :ref:`checksum_32 ` but is used exclusively by API functions. It may be deprecated at some point in the future. - -.. _support-checksum-32: - -checksum_32 ------------ - -.. c:function:: 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 reference ``checksum`` 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 :ref:`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. +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 reference ``checksum`` 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 :gh-src:`memory.h ` and defined in :gh-src:`checksum32.c `. .. _support-chrout: @@ -375,7 +353,7 @@ chrout .. c:function:: 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 `_. +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 :gh-src:`memory.h ` and defined in :gh-src:`chrout.c `. .. _support-decout: @@ -384,16 +362,7 @@ decout .. c:function:: 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 `_. - -.. _support-endian: - -endian ------- - -.. c:function:: 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 `_. +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 :gh-src:`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 :gh-src:`memory.h ` and defined in :gh-src:`decout.c `. .. _support-fdchecksum32: @@ -402,27 +371,7 @@ fdchecksum32 .. c:function:: uint32_t fdchecksum32(int fd, size_t extent, uint32_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 reference ``checksum`` 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 `_. - -.. _support-fdchecksum-32: - -fdchecksum_32 -------------- - -.. c:function:: uint32_t fdchecksum_32(int fd, size_t extent, uint32_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 reference ``checksum`` 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 :ref:`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. - -.. _support-filepar: - -filepart --------- - -.. c:function:: 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 `_. +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 reference ``checksum`` 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 :gh-src:`memory.h ` and defined in :gh-src:`fdchecksum_32.c `. .. _support-hexdecode: @@ -431,7 +380,7 @@ hexdecode .. c:function:: 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 `_. +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 :gh-src:`memory.h ` and defined in :gh-src:`hexdecode.c `. .. _support-hexdump: @@ -440,7 +389,7 @@ hexdump .. c:function:: 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 `_. +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 :gh-src:`memory.h ` and defined in :gh-src:`hexdump.c `. This function is similar to but different from function :ref:`hexview ` . @@ -451,16 +400,7 @@ hexencode .. c:function:: 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 `_. - -.. _support-hexin: - -hexin ------ - -.. c:function:: ssize_t hexin(void const *memory, size_t extent, FILE *fp) - -This function is similar to :ref:`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 `_. +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 :gh-src:`number.h `. The function is declared in :gh-src:`memory.h ` and defined in :gh-src:`hexencode.c `. .. _support-hexout: @@ -469,7 +409,7 @@ hexout .. c:function:: 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 `_. +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 :gh-src:`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 :gh-src:`memory.h ` and defined in :gh-src:`hexout.c `. .. _support-hexstring: @@ -478,7 +418,7 @@ hexstring .. c:function:: 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 :ref:`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 `_. +Convert a ``memory`` region to a ``NUL`` terminated string and return the string address. This function is identical to function :ref:`hexdecode ` but it return the string address instead of the number of characters decoded. The function is declared in :gh-src:`memory.h ` and defined in :gh-src:`hexstring.c `. .. _support-hexview: @@ -487,7 +427,7 @@ hexview .. c:function:: 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 `_. +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 :gh-src:`memory.h ` and defined in :gh-src:`hexview.c `. This function is similar to but different from function :ref:`hexdump `. @@ -498,7 +438,7 @@ memdecr .. c:function:: 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 `_. +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 :gh-src:`memory.h ` and defined in :gh-src:`memdecr.c `. .. _support-memincr: @@ -507,7 +447,7 @@ memincr .. c:function:: 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 `_. +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 :gh-src:`memory.h ` and defined in :gh-src:`memincr.c `. .. _support-memout: @@ -516,7 +456,7 @@ memout .. c:function:: 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 `_. +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 :gh-src:`number.h `, but it could be any character value. The function is declared in :gh-src:`memory.h ` and defined in :gh-src:`memout.c `. .. _support-memswap: @@ -525,7 +465,7 @@ memswap .. c:function:: 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 `_. +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 :gh-src:`memory.h ` and defined in :gh-src:`memswap.c `. .. _support-strdecr: @@ -534,7 +474,7 @@ strdecr .. c:function:: 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 `_. +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 :gh-src:`memory.h ` and defined in :gh-src:`strdecr.c `. .. _support-strfbits: @@ -543,7 +483,7 @@ strfbits .. c:function:: 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 `_. +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 :gh-src:`format.h ` and defined in :gh-src:`strfbits.c `. .. _support-strincr: @@ -552,7 +492,7 @@ strincr .. c:function:: 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 `_. +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 :gh-src:`memory.h ` and defined in :gh-src:`strincr.c `. .. _support-todigit: @@ -561,7 +501,7 @@ todigit .. c:function:: 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 `_. +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 :gh-src:`number.h ` and defined in :gh-src:`todigit.c `. .. _support-typename: @@ -570,7 +510,7 @@ typename .. c:function:: 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 `_. +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 :gh-src:`types.h `. A typical use might be to return the name of message based on the message type. The function is declared in :gh-src:`symbol.h ` and defined in :gh-src:`typename.c `. .. _support-message: @@ -586,7 +526,7 @@ MMECode .. c:function:: char const *MMECode(uint16_t MMTYPE, uint8_t MSTATUS) -Return text that explains the status code for a given Atheros vendor-specific management message. Argument ``MMTYPE`` is an unsigned integer in the range ``0xA000`` through ``0xAFFF`` and must exactly match the ``MMTYPE`` of the message returning the status code. For example, the ``CNF`` variant of a message is currently the only variant that has an ``MSTATUS`` field and so other variants return a default string. The function is declared in `mme.h `_ and defined in `MMECode.c `_. +Return text that explains the status code for a given Atheros vendor-specific management message. Argument ``MMTYPE`` is an unsigned integer in the range ``0xA000`` through ``0xAFFF`` and must exactly match the ``MMTYPE`` of the message returning the status code. For example, the ``CNF`` variant of a message is currently the only variant that has an ``MSTATUS`` field and so other variants return a default string. The function is declared in :gh-src:`mme.h ` and defined in :gh-src:`MMECode.c `. Inclusion of this function can increase application size by 3kb because the text associated with all Atheros vendor-specific management messages and errors are included whether needed or not. Conditional compilation statements are provided internally to suppress the full table with a terse substitute. @@ -599,7 +539,7 @@ MMEMode .. c:function:: char const *MMEMode(uint16_t MMTYPE) -Return the mode of a given management message type as a string. The mode is determined by the two least significant bits of argument ``MMTYPE``. The mode string will be one of "REQ", "CNF", "IND" or "RSP". The function is declared in `ihp.h `_ and defined in `MMEMode.c `_. +Return the mode of a given management message type as a string. The mode is determined by the two least significant bits of argument ``MMTYPE``. The mode string will be one of "REQ", "CNF", "IND" or "RSP". The function is declared in :gh-src:`mme.h ` and defined in :gh-src:`MMEMode.c `. Most management messages have a request and a confirmation variant while a few have an indication and a response variant. Requests originate from the host and are acknolwedged by a confirmation from the device. Indications originate from a device and are acknowledged by a response from the host. @@ -610,7 +550,7 @@ MMEName .. c:function:: char const *MMEName(uint16_t MMTYPE) -Return the name associated with a given management message type. The name is the mnemonic used to distinguish one message type from another in the *HomePlug AV Specification* or Atheros *Firwmare Technical Reference Manual*. Argument ``MMTYPE`` is an unsigned integer in the range ``0x0000`` through ``0xAFFF``. The request, confirmation, indication and response variants of a management message will all return the same message name. The function is declared in `mme.h `_ and defined in `MMEName.c `_. +Return the name associated with a given management message type. The name is the mnemonic used to distinguish one message type from another in the *HomePlug AV Specification* or Atheros *Firwmare Technical Reference Manual*. Argument ``MMTYPE`` is an unsigned integer in the range ``0x0000`` through ``0xAFFF``. The request, confirmation, indication and response variants of a management message will all return the same message name. The function is declared in :gh-src:`mme.h ` and defined in :gh-src:`MMEName.c `. .. _support-mmepeek: @@ -619,7 +559,7 @@ MMEPeek .. c:function:: void MMEPeek(void const *memory, size_t extent, FILE *fp) -Prints an Atheros vendor-specific management message to stream ``fp`` in human readable format. Argument ``buffer`` is the message address and argument ``extent`` is the message extent in bytes. Output consists of a formatted header showing decoded header. The function is declared in `mme.h `_ and defined in `MMEPeek.c `_. +Prints an Atheros vendor-specific management message to stream ``fp`` in human readable format. Argument ``buffer`` is the message address and argument ``extent`` is the message extent in bytes. Output consists of a formatted header showing decoded header. The function is declared in :gh-src:`mme.h ` and defined in :gh-src:`MMEPeek.c `. .. _support-key: @@ -667,7 +607,7 @@ The following code example illustrates how to generate, rehash and print an SHA2 } printf ("\n"); -Above, we declare struct ``sha256`` and initialize it using function :ref:`SHA256Reset `. We then write a user-defined seed string (or password) followed by an optional salt string to the digest using function :ref:`SHA256Write `. The resulting digest (or key) is obtained by calling function :ref:`SHA256Fetch `. Constant ``SHA256_DIGEST_SIZE`` is defined in `SHA256.h `_. Although the digest is probably secure enough at this point, we rehash it ``999`` times for good measure. We then print the first ``16`` bytes of the result because HomePlug AV keys are always ``16`` bytes long. +Above, we declare struct ``sha256`` and initialize it using function :ref:`SHA256Reset `. We then write a user-defined seed string (or password) followed by an optional salt string to the digest using function :ref:`SHA256Write `. The resulting digest (or key) is obtained by calling function :ref:`SHA256Fetch `. Constant ``SHA256_DIGEST_SIZE`` is defined in :gh-src:`SHA256.h `. Although the digest is probably secure enough at this point, we rehash it ``999`` times for good measure. We then print the first ``16`` bytes of the result because HomePlug AV keys are always ``16`` bytes long. .. _support-MACPasswords: @@ -676,7 +616,7 @@ MACPasswords .. c:function:: void MACPasswords(uint32_t vendor, uint32_t device, uint32_t number, unsigned count, unsigned bunch, unsigned space, flag_t flags) -Print a range of device addresses and user passwords on stdout. The calling application must split the starting device address into a three-byte OUI and three-byte device number and pass them as the unsigned 32-bit integers ``vendor`` and ``device``, respectively. Argument ``device`` is the first device number in the range and ``number`` is the final device number. Argument ``count`` is the number of uppercase letters comprising a password. Passwords contain this many letters but the letters are grouped for easy reading. Letter groups are separated by hyphens. Argument ``bunch`` defines how many letters form each group. Argument ``space`` is the character used to separate groups of letters. Argument ``flags`` enables or disables function features such as insertion of a "used" flag for use by the Atheros Production Test System or the omission of the device address on output. The output of this function is similar to that produced by the :program:`DB Builder` utility distributed with the PTS. This function is declared in `keys.h `_ and defined in `MACPasswords.c `_. +Print a range of device addresses and user passwords on stdout. The calling application must split the starting device address into a three-byte OUI and three-byte device number and pass them as the unsigned 32-bit integers ``vendor`` and ``device``, respectively. Argument ``device`` is the first device number in the range and ``number`` is the final device number. Argument ``count`` is the number of uppercase letters comprising a password. Passwords contain this many letters but the letters are grouped for easy reading. Letter groups are separated by hyphens. Argument ``bunch`` defines how many letters form each group. Argument ``space`` is the character used to separate groups of letters. Argument ``flags`` enables or disables function features such as insertion of a "used" flag for use by the Atheros Production Test System or the omission of the device address on output. The output of this function is similar to that produced by the :program:`DB Builder` utility distributed with the PTS. This function is declared in :gh-src:`keys.h ` and defined in :gh-src:`MACPasswords.c `. .. _support-HPAVKeyDAK: @@ -685,7 +625,7 @@ HPAVKeyDAK .. c:function:: void HPAVKeyDAK(byte DAK[], char const *string) -Encode buffer ``DAK`` with the Device Access Key (DAK) derived from the ``NUL`` terminated ``string``. The ``string`` is salted, hashed and re-hashed using the SHA256 algorithm. The ``DAK`` is always ``HPAVKEY_DAK_LEN`` bytes, defined in `HPAVKey.h `_, so no length argument is needed. See the HomePlug AV Specification for more information. This function is declared in `HPAVKey.h `_ and defined in `HPAVKeyDAK.c `_. +Encode buffer ``DAK`` with the Device Access Key (DAK) derived from the ``NUL`` terminated ``string``. The ``string`` is salted, hashed and re-hashed using the SHA256 algorithm. The ``DAK`` is always ``HPAVKEY_DAK_LEN`` bytes, defined in :gh-src:`HPAVKey.h `, so no length argument is needed. See the HomePlug AV Specification for more information. This function is declared in :gh-src:`HPAVKey.h ` and defined in :gh-src:`HPAVKeyDAK.c `. .. _support-HPAVKeyNMK: @@ -694,7 +634,7 @@ HPAVKeyNMK .. c:function:: void HPAVKeyNMK(byte digest[], char const *string) -Encode buffer ``NMK`` with the Network Membership Key (NMK) derived from the ``NUL`` terminated ``string``. The string is salted, hashed and re-hashed using the SHA256 algorithm. The ``DAK`` is always ``HPAVKEY_NMK_LEN`` bytes, as defined in `HPAVKey.h `_, so no length argument is needed. See the HomePlug AV Specification for more information. This function is declared in `HPAVKey.h `_ and defined in `HPAVKeyNMK.c `_. +Encode buffer ``NMK`` with the Network Membership Key (NMK) derived from the ``NUL`` terminated ``string``. The string is salted, hashed and re-hashed using the SHA256 algorithm. The ``DAK`` is always ``HPAVKEY_NMK_LEN`` bytes, as defined in :gh-src:`HPAVKey.h `, so no length argument is needed. See the HomePlug AV Specification for more information. This function is declared in :gh-src:`HPAVKey.h ` and defined in :gh-src:`HPAVKeyNMK.c `. .. _support-HPAVKeyNID: @@ -703,7 +643,7 @@ HPAVKeyNID .. c:function:: void HPAVKeyNID(byte NID[], byte const NMK[], signed level) -Encode buffer ``NID`` with the Network Identification Key (NID) derived from the 16-byte Network Membership Key (NMK). The ``NMK`` is hashed and re-hashed using the SHA256 algorithm then encoded with the security ``level``. The ``NID`` is always ``HPAVKEY_NID_LEN`` bytes, as defined in `HPAVKey.h `_, so no length argument is needed. See the HomePlug AV Specification for more information. This function is declared in `HPAVKey.h `_ and defined in `HPAVKeyNID.c `_. +Encode buffer ``NID`` with the Network Identification Key (NID) derived from the 16-byte Network Membership Key (NMK). The ``NMK`` is hashed and re-hashed using the SHA256 algorithm then encoded with the security ``level``. The ``NID`` is always ``HPAVKEY_NID_LEN`` bytes, as defined in :gh-src:`HPAVKey.h `, so no length argument is needed. See the HomePlug AV Specification for more information. This function is declared in :gh-src:`HPAVKey.h ` and defined in :gh-src:`HPAVKeyNID.c `. .. _support-HPAVKeyOut: @@ -712,7 +652,7 @@ HPAVKeyOut .. c:function:: void HPAVKeyOut(byte const digest[], size_t length, char const *phrase, flag_t flags) -Decode and print up to ``length`` bytes from buffer ``digest`` on stdout. Print ``NUL`` terminated ``phrase`` on the same line following the digest when bit ``HPAVKEY_VERBOSE``, defined in `HPAVKey.h `_, is set in ``flags``. This procedure prints keys and phrases in a standard column-oriented format that other applications can easily read and use. This function is declared in `HPAVKey.h `_ and defined in `HPAVKeyOut.c `_. +Decode and print up to ``length`` bytes from buffer ``digest`` on stdout. Print ``NUL`` terminated ``phrase`` on the same line following the digest when bit ``HPAVKEY_VERBOSE``, defined in :gh-src:`HPAVKey.h `, is set in ``flags``. This procedure prints keys and phrases in a standard column-oriented format that other applications can easily read and use. This function is declared in :gh-src:`HPAVKey.h ` and defined in :gh-src:`HPAVKeyOut.c `. .. _support-SHA256Block: @@ -721,7 +661,7 @@ SHA256Block .. c:function:: void SHA256Block(struct sha256 *sha256, void const *memory) -Merge 64 bytes of memory into the current SHA256 digest. This function performs the core computations required by the SHA256 algoithm. It is called by function :ref:`SHA256Fetch ` and so there is no reason to call this function directly. The ``sha256`` structure is defined in `SHA256.h `_. The function is declared in `SHA256.h `_ and defined in `SHA256Block.c `_. +Merge 64 bytes of memory into the current SHA256 digest. This function performs the core computations required by the SHA256 algoithm. It is called by function :ref:`SHA256Fetch ` and so there is no reason to call this function directly. The ``sha256`` structure is defined in :gh-src:`SHA256.h `. The function is declared in :gh-src:`SHA256.h ` and defined in :gh-src:`SHA256Block.c `. .. _support-SHA256Fetch: @@ -730,7 +670,7 @@ SHA256Fetch .. c:function:: void SHA256Fetch(struct sha256 *sha256, byte digest[]) -Conclude SHA256 computation and transfer the result to the named 32-byte ``digest`` then flush the ``sha256`` structure. The ``digest`` is always 32 bytes long regardless of the amount of information that has been written using function :ref:`SHA256Write `. The ``sha256`` structure is defined in `SHA256.h `_. This function is declared in `SHA256.h `_ and defined in `SHA256Fetch.c `_. +Conclude SHA256 computation and transfer the result to the named 32-byte ``digest`` then flush the ``sha256`` structure. The ``digest`` is always 32 bytes long regardless of the amount of information that has been written using function :ref:`SHA256Write `. The ``sha256`` structure is defined in :gh-src:`SHA256.h `. This function is declared in :gh-src:`SHA256.h ` and defined in :gh-src:`SHA256Fetch.c `. Once this function is called, the ``sha256`` structure is purged for security reasons. You must call :ref:`SHA256Reset ` again before starting another hash or subsequent calls to this function or :ref:`SHA256Write ` will have unpredictable results. . @@ -741,7 +681,7 @@ SHA256Ident .. c:function:: void SHA256Ident(int fd, byte digest[]) -Compute the SHA256 digest from the content of a file. The digest serves as the file "fingerprint" and can be used to identify identical content despite filename changes. File descriptor ``fd`` is the subject file which must be positioned to the start befor calling this function. Buffer ``digest`` will be written with the computed 256-digest and must be ``SHA256_DIGEST_SIZE`` bytes long, as defined in `SHA256.h `_. This function is declared in `SHA256.h `_ and defined in `SHA256Ident.c `_. +Compute the SHA256 digest from the content of a file. The digest serves as the file "fingerprint" and can be used to identify identical content despite filename changes. File descriptor ``fd`` is the subject file which must be positioned to the start befor calling this function. Buffer ``digest`` will be written with the computed 256-digest and must be ``SHA256_DIGEST_SIZE`` bytes long, as defined in :gh-src:`SHA256.h `. This function is declared in :gh-src:`SHA256.h ` and defined in :gh-src:`SHA256Ident.c `. .. _support-SHA256Match: @@ -750,7 +690,7 @@ SHA256Match .. c:function:: void SHA256Match(int fd, byte const digest[]) -Search a registry file for a known SHA256 digest. Return ``true`` on success or ``false`` on failure. File descriptor ``fd`` is the registry file which must be positioned to the start before calling this function. Buffer ``digest`` contains the known 256-bit digest and must be ``SHA256_DIGEST_SIZE`` bytes long, as defined in `SHA256.h `_. A registry file consists of 64-digit hexadecimal strings that represent SHA256 digest values. Optional text may be appear between the digest and newline to document digest significance. This function ignores such text. This function is declared in `SHA256.h `_ and defined in `SHA256Match.c `_. +Search a registry file for a known SHA256 digest. Return ``true`` on success or ``false`` on failure. File descriptor ``fd`` is the registry file which must be positioned to the start before calling this function. Buffer ``digest`` contains the known 256-bit digest and must be ``SHA256_DIGEST_SIZE`` bytes long, as defined in :gh-src:`SHA256.h `. A registry file consists of 64-digit hexadecimal strings that represent SHA256 digest values. Optional text may be appear between the digest and newline to document digest significance. This function ignores such text. This function is declared in :gh-src:`SHA256.h ` and defined in :gh-src:`SHA256Match.c `. .. _support-SHA256Print: @@ -759,7 +699,7 @@ SHA256Print .. c:function:: void SHA256Print(byte const digest[], char const *string) -Print an SHA256 ``digest`` and optional ``string`` on ``stdout``. Buffer ``digest`` must be ``SHA256_DIGEST_SIZE`` bytes long, as defined in `SHA256.h `_, which results in 64 hexadecimal digits on output. Variable length string is ``NUL`` terminated but may be ``NULL``. If ``string`` is not ``NULL`` and is not empty then a space is inserted between the digest and the string on output. This function may be used to print SHA256 digests and optional strings in standard format, such as a registry file. This function is declared in `SHA256.h `_ and defined in `SHA256Print.c `_. +Print an SHA256 ``digest`` and optional ``string`` on ``stdout``. Buffer ``digest`` must be ``SHA256_DIGEST_SIZE`` bytes long, as defined in :gh-src:`SHA256.h `, which results in 64 hexadecimal digits on output. Variable length string is ``NUL`` terminated but may be ``NULL``. If ``string`` is not ``NULL`` and is not empty then a space is inserted between the digest and the string on output. This function may be used to print SHA256 digests and optional strings in standard format, such as a registry file. This function is declared in :gh-src:`SHA256.h ` and defined in :gh-src:`SHA256Print.c `. .. _support-SHA256Reset: @@ -768,7 +708,7 @@ SHA256Reset .. c:function:: void SHA256Reset(struct sha256 *sha256) -Initialize a ``sha256`` structure before computing a new SHA256 digest. This function should be called once before calling :ref:`SHA256Write ` for the first time for a given digest. The ``sha256`` structure is defined in `SHA256.h `_. This function is declared in `SHA256.h `_ and defined in `SHA256Reset.c `_. +Initialize a ``sha256`` structure before computing a new SHA256 digest. This function should be called once before calling :ref:`SHA256Write ` for the first time for a given digest. The ``sha256`` structure is defined in :gh-src:`SHA256.h `. This function is declared in :gh-src:`SHA256.h ` and defined in :gh-src:`SHA256Reset.c `. .. _support-SHA256Write: @@ -777,7 +717,7 @@ SHA256Write .. c:function:: void SHA256Write(struct sha256 *sha256, void const *memory, size_t extent) -Writes a region of memory to the current SHA256 digest contained in an ``sha256`` structure. An application may call this function any number of times to concatinate multiple memory regions before fetching the digest with function ``SHA256Fetch``. The ``sha256`` structure is defined in `SHA256.h `_. This function is declared in `SHA256.h `_ and defined in `SHA256Write.c `_. +Writes a region of memory to the current SHA256 digest contained in an ``sha256`` structure. An application may call this function any number of times to concatinate multiple memory regions before fetching the digest with function ``SHA256Fetch``. The ``sha256`` structure is defined in :gh-src:`SHA256.h `. This function is declared in :gh-src:`SHA256.h ` and defined in :gh-src:`SHA256Write.c `. .. _support-xml: @@ -788,7 +728,7 @@ Atheros provides support for remote PIB management using XML instruction files. Users may create XML files that conform to the schema and specify the PIB objects they want to change and how they want each to change. In brief, the files specify an ``offset``, a data ``length`` and a data value. A data value has type ``dataString``, ``dataHex`` or ``dataByte`` and may be a single data item or an array of data items. Each XML file should include a reference to the Atheros schema and be submitted to a validating XML parser, such as :program:`Internet Explorer` or :program:`Firefox`, to ensure that file structure and syntax are correct before use. An example XML file can be seen in piboffset.xml. -Editing involves the following steps. An example of these steps can be seen in the `pxe program source code `_ and in function `RdModWrPib2.c `_ which is a component of the `int6k2 `_ program. +Editing involves the following steps: #. Obtain a copy of the PIB to be edited. This can be done by opening a PIB file and reading the entire file into memory or by requesting the PIB directly from an active Atheros powerline device. The PIB length can be determined from the PIB header. @@ -809,7 +749,7 @@ xmledit .. c:function:: signed xmledit(struct node *node, void *memory, unsigned extent) -Write data into ``memory`` based on the data offset and length defined in XML parse tree, ``node``. This function will not apply modifications having malformed structure or having an invalid or illegal offset, length or data value. Use function :ref:`xmlschema ` to print the current schema. The function is declared in `node.h `_ and defined in `xmledit.c `_. The ``node`` structure is defined in `node.h `_. +Write data into ``memory`` based on the data offset and length defined in XML parse tree, ``node``. This function will not apply modifications having malformed structure or having an invalid or illegal offset, length or data value. Use function :ref:`xmlschema ` to print the current schema. The function is declared in :gh-src:`node.h ` and defined in :gh-src:`xmledit.c `. The ``node`` structure is defined in :gh-src:`node.h `. .. _nodes-xmlfree: @@ -818,7 +758,7 @@ xmlfree .. c:function:: void xmlfree(struct node *node) -Release memory associated with an XML parse tree. The function is declared in `node.h `_ and defined in `xmlfree.c `_. The ``node`` structure is defined in `node.h `_. +Release memory associated with an XML parse tree. The function is declared in :gh-src:`node.h ` and defined in :gh-src:`xmlfree.c `. The ``node`` structure is defined in :gh-src:`node.h `. The ``text`` member if the parse tree root node points to memory allocated by :ref:`xmlscan ` to store the original XML string. The application must either deallocate that memory before calling this function or store the text address and deallocate that memory after calling this function; otherwise, memory leaks will result. @@ -829,7 +769,7 @@ xmlnode .. c:function:: struct node *xmlnode(struct node *node) -Create an empty node blow the specified node and return a pointer to it. A typical application can be seen in function `xmlscan.c `_. The function is declared in `node.h `_ and defined in `xmlnode.c `_. The ``node`` structure is defined in `node.h `_. +Create an empty node blow the specified node and return a pointer to it. A typical application can be seen in function :gh-src:`xmlscan.c `. The function is declared in :gh-src:`node.h ` and defined in :gh-src:`xmlnode.c `. The ``node`` structure is defined in :gh-src:`node.h `. .. _nodes-xmlopen: @@ -838,7 +778,7 @@ xmlopen .. c:function:: struct node *xmlopen(char const *filename) -Open the named XML file, parse it and return the XML parse tree. The parse tree contains, among other things, all XML elements, attributes and values specified in the file. The function is declared in `node.h `_ and defined in `xmlopen.c `_. The ``node`` structure is defined in `node.h `_. +Open the named XML file, parse it and return the XML parse tree. The parse tree contains, among other things, all XML elements, attributes and values specified in the file. The function is declared in :gh-src:`node.h ` and defined in :gh-src:`xmlopen.c `. The ``node`` structure is defined in :gh-src:`node.h `. The returned parse tree is ready to traverse using struct ``node`` members ``above``, ``below``, ``prior`` and ``after``. Each node has a ``line``, ``type`` and ``test`` member. This function calls function :ref:`xmlscan ` to parse the file and generate the tree. The parse tree can be inspected by passing the root node to function :ref:`xmltree `. @@ -849,7 +789,7 @@ xmlscan .. c:function:: signed xmlscan(struct node *node) -Scan the XML string attached to the specified ``node`` and create a parse tree below it. Return ``0`` if parsing is successrul or ``-1`` if not. The function is declared in `node.h `_ and defined in `xmlscan.c `_. The ``node`` structure is defined in `node.h `_. +Scan the XML string attached to the specified ``node`` and create a parse tree below it. Return ``0`` if parsing is successrul or ``-1`` if not. The function is declared in :gh-src:`node.h ` and defined in :gh-src:`xmlscan.c `. The ``node`` structure is defined in :gh-src:`node.h `. The application must point the ``text`` member to a copy of the XML string before calling this function because parsing is destructive and requires write access to the string. The application can search and manipulate the tree on return. The application should deallocate string memory before calling :ref:`xmlfree `. @@ -899,7 +839,7 @@ xmlschema .. c:function:: void xmlschema(void) -Print an XML schema that supports function :ref:`xmledit ` on stdout. This function has no argument. The schema produced by this function is guaranteed to support the parse logic implemented by function :ref:`xmledit `. Scheme element names are defined as constants in `node.h `_ so that they can be referenced by applications that create their own XML edit instructions. The function is declared in `node.h `_ and defined in `xmlschema.c `_. +Print an XML schema that supports function :ref:`xmledit ` on stdout. This function has no argument. The schema produced by this function is guaranteed to support the parse logic implemented by function :ref:`xmledit `. Scheme element names are defined as constants in :gh-src:`node.h ` so that they can be referenced by applications that create their own XML edit instructions. The function is declared in :gh-src:`node.h ` and defined in :gh-src:`xmlschema.c `. The ``text`` member in the parse tree root node points to memory allocated by :ref:`xmlscan ` to store the original XML string. The application must either deallocate that memory before calling this function or store the text address and deallocate that memory after calling this function; otherwise, memory leaks will result. @@ -956,14 +896,14 @@ xmltree .. c:function:: void xmltree(struct node *node) -Print the XML parse tree on stdout. The function is declared in `node.h `_ and defined in `xmltree.c `_. +Print the XML parse tree on stdout. The function is declared in :gh-src:`node.h ` and defined in :gh-src:`xmltree.c `. .. _nodes-example-2: XML Parse Tree ~~~~~~~~~~~~~~ -The following is sample output from function ``xmltree``. The XML source is shown in the example for function :ref:`xmlscan `. The numbers appearing down the left margin indicate the input line number from the XML source file parsed by function :ref:`xmlscan `. The character codes indicate the node type and are defined in `node.h `_. The ``node`` structure is defined in `node.h `_. +The following is sample output from function ``xmltree``. The XML source is shown in the example for function :ref:`xmlscan `. The numbers appearing down the left margin indicate the input line number from the XML source file parsed by function :ref:`xmlscan `. The character codes indicate the node type and are defined in :gh-src:`node.h `. The ``node`` structure is defined in :gh-src:`node.h `. :: @@ -1026,24 +966,6 @@ Download Functions Download function write applets, parameters and runtime firmware to device SDRAM or NVRAM. -.. _WriteExecuteApplet: - -WriteExecuteApplet ------------------- - -.. c:function:: signed WriteExecuteApplet(struct plc *plc, void const *header) - -Write an NVM image directly into SDRAM using ``VS_WRITE_AND_EXECUTE`` messages. This function calls either :ref:`WriteExecuteApplet1 ` or :ref:`WriteExecuteApplet2 ` based on the NVM header version. The function is declared in `plc.h `_ and defined in `WriteExecuteApplet.c `_. The ``plc`` structure is defined in `plc.h `_. - -.. _WriteExecuteApplet1: - -WriteExecuteApplet1 -------------------- - -.. c:function:: signed WriteExecuteApplet1(struct plc *plc, struct nvm_header1 *header) - -Write an NVM image directly into SDRAM using ``VS_WRITE_AND_EXECUTE`` messages. This function is similar to :ref:`WriteExecuteApplet2 ` but expects a structure ``nvm_header1`` pointer instead of a structure ``nvm_header2`` pointer. The function is declared in `plc.h `_ and defined in `WriteExecuteApplet.c `_. Structure ``plc`` is defined in file `plc.h `_. Structure ``nvm_header1`` is defined in file `nvm.h `_. - .. _WriteExecuteApplet2: WriteExecuteApplet2 @@ -1051,7 +973,7 @@ WriteExecuteApplet2 .. c:function:: signed WriteExecuteApplet2(struct plc *plc, struct nvm_header2 *header) -Write an NVM image directly into SDRAM using ``VS_WRITE_AND_EXECUTE`` messages. This function is similar to :ref:`WriteExecuteApplet1 ` but expects a structure ``nvm_header2`` pointer instead of a structure ``nvm_header1`` pointer. The function is declared in `plc.h `_ and defined in `WriteExecuteApplet.c `_. Structure ``plc`` is defined in file `plc.h `_. Structure ``nvm_header1`` is defined in file `nvm.h `_. +Write an NVM image directly into SDRAM using ``VS_WRITE_AND_EXECUTE`` messages. The function is declared in :gh-src:`plc.h ` and defined in :gh-src:`WriteExecuteApplet2.c `. Structure ``plc`` is defined in file :gh-src:`plc.h `. Structure ``nvm_header1`` is defined in file :gh-src:`nvm.h `. .. _support-procrastination: @@ -1060,33 +982,6 @@ Procrastination Functions Procrastinations functions wait for specific events to occur or fail to occur. -.. _WaitForAssoc: - -WaitForAssoc ------------- - -.. c:function:: signed WaitForAssoc(struct plc *plc) - -Poll a powerline device using ``VS_NW_INFO`` messages until the device forms or joins a network. The host ethernet interface, destination hardware address and source hardware address are specified in structure ``plc``. It calls either :ref:`WaitForAssoc1 ` or :ref:`WaitForAssoc2 ` to procrastinate based on the ``hardwareID`` member of structure ``plc``. The function is declared in `plc.h `_ and defined in file `WaitForAssoc.c `_. Struct ``plc`` is declared in file `plc.h `_ and defined in file `plc.c `_. - -.. _WaitForAssoc1: - -WaitForAssoc1 -------------- - -.. c:function:: signed WaitForAssoc1(struct plc *plc) - -Poll a 200mbs powerline device using ``VS_NW_INFO`` version ``0`` messages until the device joins or forms a network. The host ethernet interface, destination hardware address and source hardware address are specified in structure ``plc``. The function is declared in file `plc.h `_ and defined in file `WaitForAssoc1.c `_. Struct ``plc`` is declared in file `plc.h `_ and defined in file `plc.c `_. - -.. _WaitForAssoc2: - -WaitForAssoc2 -------------- - -.. c:function:: signed WaitForAssoc2(struct plc *plc) - -Poll a 1000mbs powerline device using ``VS_NW_INFO`` version ``1`` messages until the device joins or forms a network. The host ethernet interface, destination hardware address and source hardware address are specified in structure ``plc``. Structure ``plc`` is declared in file `plc.h `_ and defined in file `plc.c `_. The function is declared in file `plc.h `_ and defined in file `WaitForAssoc2.c `_. - .. _WaitForReset: WaitForReset @@ -1094,7 +989,7 @@ WaitForReset .. c:function:: signed WaitForReset(struct plc *plc) -Poll a powerline device using ``VS_SW_VER`` messages until the device stops responding. The host ethernet interface, destination hardware address and source hardware address are specified in structure ``plc``. Structure ``plc`` is declared in file `plc.h `_ and define in file `plc.c `_. The function is declared in `plc.h `_ and defined in file `WaitForReset.c `_. +Poll a powerline device using ``VS_SW_VER`` messages until the device stops responding. The host ethernet interface, destination hardware address and source hardware address are specified in structure ``plc``. Structure ``plc`` is declared in file :gh-src:`plc.h ` and define in file :gh-src:`plc.c `. The function is declared in :gh-src:`plc.h ` and defined in file :gh-src:`WaitForReset.c `. .. _WaitForStart: @@ -1103,7 +998,7 @@ WaitForStart .. c:function:: signed WaitForStart(struct plc *plc, char firmware, size_t length) -Poll a powerline device using ``VS_SW_VER`` messages until the device responds. The host ethernet interface, destination hardware address and source hardware address are specified in structure ``plc``. Update the ``hardwareID`` member of the ``plc`` structure. Return the firmware revision string contained in the confirmation message. Structure ``plc`` is declared in file `plc.h `_ and defined in file `plc.c `_. The function is declared in file `plc.h `_ and defined in file `WaitForStart.c `_. +Poll a powerline device using ``VS_SW_VER`` messages until the device responds. The host ethernet interface, destination hardware address and source hardware address are specified in structure ``plc``. Update the ``hardwareID`` member of the ``plc`` structure. Return the firmware revision string contained in the confirmation message. Structure ``plc`` is declared in file :gh-src:`plc.h ` and defined in file :gh-src:`plc.c `. The function is declared in file :gh-src:`plc.h ` and defined in file :gh-src:`WaitForStart.c `. .. _support-traffic: @@ -1112,42 +1007,6 @@ Traffic Functions Traffic functions generate powerline traffic in various ways. Some send traffic direct from the host to each device while others use the ``VS_FR_LBK`` message to echo Ethernet frames back to the sender. -.. _support-CrossTraffic1: - -CrossTraffic1 -------------- - -.. c:function:: signed CrossTraffic1(struct plc *plc) - -Instruct a powerline device to send a generic Ethernet frame to another powerline device for a fixed period of time in order to set the ``TX`` rate on the source device and the ``RX`` rate on the destination device. The source and destination address are specified in ``plc->MAC`` and ``plc->RDA``, respectively, and the duration is specified in ``plc->timeperiod``. This function is similar to function :ref:`CrossTraffic2 ` but the source and destination addresses are reversed. Structure ``plc`` is declared in file `plc.h `_ and defined in file `plc.c `_. The function is declared in `plc.h `_ and defined in file `CrossTraffic1.c `_. - -.. _support-CrossTraffic2: - -CrossTraffic2 -------------- - -.. c:function:: signed CrossTraffic2(struct plc *plc) - -Instruct a powerline device to send a generic Ethernet frame to another powerline device for a fixed period of time in order to set the ``TX`` rate on the source device and the ``RX`` rate on the destination device. The source and destination address are specified in ``plc->RDA`` and ``plc->MAC``, respectively, and the duration is specified in ``plc->timeperiod``. This function is similar to function :ref:`CrossTraffic1 ` but the source and destination addresses are reversed. Structure ``plc`` is declared in file `plc.h `_ and defined in file `plc.c `_. The function is declared in `plc.h `_ and defined in file `CrossTraffic2.c `_. - -.. _support-LocalTraffic1: - -LocalTraffic1 -------------- - -.. c:function:: signed LocalTraffic1(struct plc *plc) - -Send a fixed number of generic frames from the local host a remote powerline device in order to set the ``TX`` rate on the local powerline device and the ``RX`` rate on the remote powerline device. The local and remote device address are specified in ``plc->MAC`` and ``plc->RDA``, respectively, and the count is specified in ``plc->count``. This function is similar to function :ref:`LocalTraffic2 ` which instructs a remote device to echo frames back to the local device. Structure ``plc`` is declared in file `plc.h `_ and defined in file `plc.c `_. The function is declared in `plc.h `_ and defined in file `LocalTraffic1.c `_. - -.. _support-LocalTraffic2: - -LocalTraffic2 -------------- - -.. c:function:: signed LocalTraffic2(struct plc *plc) - -Instruct a remote powerline device to echo generic Ethernet frames back to the local host for a fixed period of time in order to set the ``TX`` rate on the remote powerline device and the ``RX`` rate on the local powerline device. The local and remote device address are specified in ``plc->MAC`` and ``plc->RDA``, respectively, and the count is specified in ``plc->count``. This function is useful when there is no easy way to send traffic from the remote host. This function complements function :ref:`LocalTraffic1 ` which send frames from the local device to a remote device. Structure ``plc`` is declared in file `plc.h `_ and defined in file `plc.c `_. The function is declared in `plc.h `_ and defined in file `LocalTraffic2.c `_. - .. _support-NetworkTraffic1: NetworkTraffic1 @@ -1155,7 +1014,7 @@ NetworkTraffic1 .. c:function:: signed NetworkTraffic1(struct plc *plc) -This function is an alternative to function :ref:`NetworkTraffic2 ` which uses Qualcomm Version ``1`` management messages to determine network topology. Structure ``plc`` is declared in file `plc.h `_ and defined in file `plc.c `_. The function is declared in `plc.h `_ and defined in file `NetworkTraffic1.c `_. +This function is an alternative to function :ref:`NetworkTraffic2 ` which uses Qualcomm Version ``1`` management messages to determine network topology. Structure ``plc`` is declared in file :gh-src:`plc.h ` and defined in file :gh-src:`plc.c `. The function is declared in :gh-src:`plc.h ` and defined in file :gh-src:`NetworkTraffic1.c `. This function use ``VS_SW_INFO`` and ``VS_NW_INFO`` messages to discover powerline network topology then calls functions :ref:`LocalTraffic1 ` and :ref:`LocalTraffic2 ` to generate traffic between the local powerline device and each remote powerline device. Unlike function :ref:`NetworkTraffic1 `, it does not generate traffic between various remote devices. @@ -1166,7 +1025,7 @@ NetworkTraffic2 .. c:function:: signed NetworkTraffic2(struct plc *plc) -This function is an alternative to function :ref:`NetworkTraffic1 ` which uses Qualcomm Version ``0`` management messages to determine network topology. Structure ``plc`` is declared in file `plc.h `_ and defined in file `plc.c `_. The function is declared in `plc.h `_ and defined in file `NetworkTraffic2.c `_. +This function is an alternative to function :ref:`NetworkTraffic1 ` which uses Qualcomm Version ``0`` management messages to determine network topology. Structure ``plc`` is declared in file :gh-src:`plc.h ` and defined in file :gh-src:`plc.c `. The function is declared in :gh-src:`plc.h ` and defined in file :gh-src:`NetworkTraffic2.c `. .. _support-Traffic1: @@ -1175,7 +1034,7 @@ Traffic1 .. c:function:: signed Traffic1(struct plc *plc) -This function is an alternative to function :ref:`Traffic2 ` which uses Qualcomm Version ``1`` management messages to determine network topology. Structure ``plc`` is declared in file `plc.h `_ and defined in file `plc.c `_. The function is declared in `plc.h `_ and defined in file `Traffic1.c `_. +This function is an alternative to function :ref:`Traffic2 ` which uses Qualcomm Version ``1`` management messages to determine network topology. Structure ``plc`` is declared in file :gh-src:`plc.h ` and defined in file :gh-src:`plc.c `. The function is declared in :gh-src:`plc.h ` and defined in file :gh-src:`Traffic1.c `. This function use ``VS_SW_INFO`` and ``VS_NW_INFO`` messages to discover powerline network topology then calls functions :ref:`LocalTraffic1 ` and :ref:`LocalTraffic2 ` to generate traffic between the local powerline device and each remote powerline device. Unlike function :ref:`NetworkTraffic1 `, it does not generate traffic between remote devices. @@ -1186,7 +1045,7 @@ Traffic2 .. c:function:: signed Traffic2(struct plc *plc) -This function is an alternative to function :ref:`Traffic1 ` which uses Qualcomm Version ``0`` management messages to determine network topology. Structure ``plc`` is declared in file `plc.h `_ and defined in file `plc.c `_. The function is declared in `plc.h `_ and defined in file `Traffic2.c `_. +This function is an alternative to function :ref:`Traffic1 ` which uses Qualcomm Version ``0`` management messages to determine network topology. Structure ``plc`` is declared in file :gh-src:`plc.h ` and defined in file :gh-src:`plc.c `. The function is declared in :gh-src:`plc.h ` and defined in file :gh-src:`Traffic2.c `. This function use ``VS_SW_INFO`` and ``VS_NW_INFO`` messages to discover powerline network topology then calls functions :ref:`LocalTraffic1 ` and :ref:`LocalTraffic2 ` to generate traffic between the local powerline device and each remote powerline device. Unlike function :ref:`NetworkTraffic2 `, it does not generate traffic between remote devices. diff --git a/plc/plc.h b/plc/plc.h index 09a72f3f..78b9c8f2 100644 --- a/plc/plc.h +++ b/plc/plc.h @@ -337,9 +337,6 @@ signed BootFirmware2 (struct plc *); signed BootParameters1 (struct plc *); signed BootParameters2 (struct plc *); signed ChangeIdent (struct plc *); -signed CrossTraffic (struct plc *); -signed CrossTrafficOne (struct plc *); -signed CrossTrafficTwo (struct plc *); signed DeviceIdent (struct plc *); signed EmulateHost (struct plc *); signed EmulateHost64 (struct plc *); @@ -370,7 +367,6 @@ signed InitDevice2 (struct plc *); signed LinkStatistics (struct plc *); signed LinkStatus (struct plc *); signed ListLocalDevices (struct plc * plc, char const * space, char const * comma); -signed LocalTrafficSend (struct plc * plc); signed Antiphon (struct plc * plc, uint8_t osa [], uint8_t oda []); signed MDUTrafficStats (struct plc *, uint8_t command, uint8_t session, uint8_t slave); signed MfgString (struct plc *); diff --git a/tools/Makefile b/tools/Makefile index 1d992cf8..48904efb 100755 --- a/tools/Makefile +++ b/tools/Makefile @@ -64,7 +64,7 @@ grab: grab.o getoptv.o putoptv.o version.o basespec.o todigit.o error.o efreopen # libraries; # -------------------------------------------------------------------- -libmtools.a: binout.o bytespec.o confirmfilename.o checksum32.o dataspec.o decdecode.o decout.o emalloc.o reverse.o error.o fdchecksum32.o filepart.o getoptv.o hexdecode.o hexdump.o hexencode.o hexin.o hexout.o hexstring.o hexview.o regview.o ipv4spec.o ipv6spec.o memdecr.o memincr.o memswap.o output.o putoptv.o strdecr.o strfbits.o strincr.o synonym.o todigit.o typename.o basespec.o uintspec.o version.o +libmtools.a: binout.o bytespec.o confirmfilename.o checksum32.o dataspec.o decdecode.o decout.o emalloc.o reverse.o error.o fdchecksum32.o getoptv.o hexdecode.o hexdump.o hexencode.o hexout.o hexstring.o hexview.o regview.o ipv4spec.o ipv6spec.o memdecr.o memincr.o memswap.o output.o putoptv.o strdecr.o strfbits.o strincr.o synonym.o todigit.o typename.o basespec.o uintspec.o version.o rm -f ${@} $(AR) rc ${@} ${^} $(RANLIB) ${@} diff --git a/tools/files.h b/tools/files.h index 33f8789a..a5db5f9e 100644 --- a/tools/files.h +++ b/tools/files.h @@ -74,7 +74,6 @@ FILE *efopen (char const *filename, char const *openmode); FILE *efreopen (char const *filename, char const *openmode, FILE *fp); bool checkfilename (char const * string); -char const * filepart (char const * string); /*====================================================================* *