csu3_am335x/EVSE/GPL/open-plc-utils-0.3/docbook/folders.xml

	<section id='overview-folders'>
		<title>
			Toolkit Folders 
			</title>
		<para>
			The  Atheros  Open Powerline Toolkit package folder has many subfolders. Some contain source code, some contain documentation and others contain shell scripts. Some source folders contain programs that require components in neighboring folders. Consequently, you will see references to relative pathnames like ../folder, throughout source code, makefiles and shell scripts. This notation simplifies development and maintenance and is helpful when locating specific files. 
			</para>
		<para>
			Folder descriptions appear below in alphabetical order: 
			</para>
		<variablelist>
			<varlistentry id="folder-applets">
				<term>
					./applets
					</term>
				<listitem>
					<para>
					A library of programs that can run, stand-alone, on Atheros powerline devices and perform diagnostic tests for connection, functionality and performance. Some run to completion and return to the <application>Bootloader</application>. Others run continuously until the device is reset. Most can be run and executed in sequence using program <link linkend='program-int6ktest'>int6ktest</link>.   
						</para>
					</listitem>
				</varlistentry>
			<varlistentry id="folder-classes">
				<term>
					./classes
					</term>
				<listitem>
					<para>
						A collection of C++ classes that implement many of the ANSI C functions found elsewhere in the toolkit. These classes will compile and run on most platforms but are still a work-in-progress. The <link linkend='folder-programs'>programs</link> folder contains actual and sample programs that use these classes. 
						</para>
					</listitem>
				</varlistentry>
			<varlistentry id="folder-docbook">
				<term>
					./docbook
					</term>
				<listitem>
					<para>
						HTML pages generated by several methods, but mostly <ulink url="http://www.docbook.org/">Docbook 4.5</ulink>. Some pages have been created using special tools that are not provided and will not be made available. The <filename>Makefile</filename> in this folder will compile the core XML source files on GNU/Linux systems that have <application>Docbook 4.5</application> installed with extentions by <ulink url='http://nwalsh.com/'>Normal Walsh</ulink> but it does not install the pages. See <link linkend="install-linux">Installation on Linux</link> for more information.
						</para>
					</listitem>
				</varlistentry>
			<varlistentry id="folder-ether">
				<term>
					./ether 
					</term>
				<listitem>
					<para>
						Network specific source code that supports raw ethernet packets in a platform independent fashion using plugin modules. The principle feature is the <constant>channel</constant> data structure used to read and write raw ethernet packets using network features on GNU/Linux, with or without <application>libpcap</application>, and on  <productname>Windows</productname> with <application>winpcap</application>. The source code in this folder is difficult to port cross-platform due to the way different operating systems implement their system header files and network stacks. 
						</para>
					</listitem>
				</varlistentry>
			<varlistentry id="folder-int6k">
				<term>
					./plc 
					</term>
				<listitem>
					<para>
						The main source code for programs that communicate with Qualcomm Atheros powerline devices over Ethernet. The programs in this folder are essential programs for engineers and embedded software developers wanting to explore powerline device behavior. The Makefile in this folder will compile and install programs in <filename>/usr/local/bin</filename> on GNU/Linux systems. 
						</para>
					</listitem>
				</varlistentry>
			<varlistentry id="folder-mme">
				<term>
					./mme 
					</term>
				<listitem>
					<para>
						A collection of helper functions dealing with <trademark class='registered'>HomePlug</trademark> and Atheros management messages. They are not needed for proper toolkit operation but they can be useful during development and debugging because they print message content in readable format. Most of these functions require extra memory because they include symbol tables and extra data conversion functions.
						</para>
					</listitem>
				</varlistentry>
			<varlistentry id="folder-nodes">
				<term>
					./nodes
					</term>
				<listitem>
					<para>
						A collection of functions that comrpise a generic,  light-weight XML parser. Atheros is currently exprimenting with various XML-based applications to support device management on embedded systems. These functions are the core. Currently,  they are only used by the <ulink url="pxe.7.html">pxe</ulink> and <ulink url="int6k2.7.html">int6k2</ulink> programs. See <link linkend="support-xml">XML Editing Functions</link> for more information.
						</para>
					</listitem>
				</varlistentry>
			<varlistentry id="folder-nvm">
				<term>
					./nvm 
					</term>
				<listitem>
					<para>
						Programs,  functions and make files related to Atheros NonVolatile Memory (<acronym>NVM</acronym>) files. All programs in this folder either read from or write to NVM files. None communicate with powerline devices. Some of the popular programs are <ulink url='chknvm.7.html'>chknvm</ulink>, <ulink url='nvmsplit.7.html'>nvmsplit</ulink> and <ulink url='nvmmerge.7.html'>nvmmerge</ulink>.
						</para>
					</listitem>
				</varlistentry>
			<varlistentry id="folder-patches">
				<term>
					./patches
					</term>
				<listitem>
					<para>
						A collection of useful <productname>Linux</productname> kernel patches and install scripts. Of particular interest is the <link linkend="hardware-send-to-self">send-to-self</link> patch that enables external routing of ISO Layer 3 traffic between two Ethernet interfaces on the same host. Atheros provides them but does not support them.
						</para>
					</listitem>
				</varlistentry>
			<varlistentry id="folder-pib">
				<term>
					./pib 
					</term>
				<listitem>
					<para>
						Programs, functions and make files related to Atheros Parameter Information Block (<acronym>PIB</acronym>) files. All programs in this folder either read from or write to PIB files. None communicate with powerline devices. Some of the popular programs are <ulink url='chkpib.7.html'>chkpib</ulink>, <ulink url='modpib.7.html'>modpib</ulink>, <ulink url='getpib.7.html'>getpib</ulink> and <ulink url='setpib.7.html'>setpib</ulink>.
						</para>
					</listitem>
				</varlistentry>
			<varlistentry id="folder-programs">
				<term>
					./programs
					</term>
				<listitem>
					<para>
						A small collection of sample C++ programs that use the Atheros C++ powerline classes. These programs compile and run on most environments but are still a work-in-progress. Users may actually find <ulink url='netifs.7.html'>netifs</ulink> and <ulink url='plcnets.7.html'>plcnets</ulink> useful.
						</para>
					</listitem>
				</varlistentry>
			<varlistentry id="folder-serial">
				<term>
					./serial 
					</term>
				<listitem>
					<para>
						Programs, functions and make files related to the Atheros Serial Communication Interface for Powerline devices. All of the programs in this folder communicate using a host serial port. None communicate with powerline devices over Ethernet. The main program of interest is <ulink url='int6kuart.7.html'>int6kuart</ulink>.
						</para>
					</listitem>
				</varlistentry>
			<varlistentry id="folder-scripts">
				<term>
					./scripts 
					</term>
				<listitem>
					<para>
						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. 
						</para>
					</listitem>
				</varlistentry>
			<varlistentry id="folder-ram">
				<term>
					./ram 
					</term>
				<listitem>
					<para>
						Support modules for reading, printing and checking <acronym>NVRAM</acronym> and <acronym>SDRAM</acronym> configuration files. The <filename>.cfg</filename> files in this folder have a different format than the <filename>.config</filename> files released with the Atheros Windows <application>Device Manager</application>. The files distributed with the Windows <application>Device Manger</application> 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 <ulink url="sdram.c.html">sdram.c</ulink>, using <command>gcc -o sdram sdram.c</command> and running it without any command line arguments. 
						</para>
					</listitem>
				</varlistentry>
			<varlistentry id="folder-tools">
				<term>
					./tools 
					</term>
				<listitem>
					<para>
						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 <link linkend="support-functions">Support Function Reference</link> for more information.
						</para>
					</listitem>
				</varlistentry>
			<varlistentry id="folder-visualstudio-net">
				<term>
					./VisualStudioNET 
					</term>
				<listitem>
					<para>
						Components unique to Microsoft Windows are kept in and under this folder. Specifically, it contains a <productname>Visual Studio .NET</productname> solution to compile most of the programs in this package using only Microsoft and winpcap libraries. Compiled .exe files can be run on <trademark>Windows</trademark> enabled systems having <application>winpcap</application> installed. Adjustments may be necessary depending on your environment. 
						</para>
					<para>
						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 <ulink url="unistd.h.html">unistd.h</ulink> and an alternative version of <ulink url="stdint.h.html">stdint.h</ulink> are included under <filename>VisualStudioNET/include</filename>. Other significant header files included here are <ulink url="ethernet.h.html">ethernet.h</ulink>, <ulink url="if_ether.h.html" >if_ether.h</ulink> and <ulink url="in.h.html">in.h</ulink>. Subfolder <filename>VisualStudio\Library</filename> contains <productname>WinPcap</productname> libraries. These folders are referenced in appropriate compiler and linker options for Microsoft Development environments. 
						</para>
					</listitem>
				</varlistentry>
			</variablelist>
		</section>