csu3_am335x/EVSE/GPL/plc-utils.LNX.2.1.20/source/docbook/qcaspi-pseudo-code.txt

	<section id="pseudo-code">
		<title>
			Serial Driver Pseudo Code
			</title>
		<para>
			This chapter presents pseudo code for the QCA7000 SPI driver. Qualcomm Atheros provides a precoded driver for Linux but customers may want to write their own driver for a non-Linux environment. In either case, the following steps are required for efficient SPI communications. 
			</para>
<screen>
function receive frame 
	allocate an input buffer;
	if no memory available then
		return failure;
		end if;
	read the read buffer space available register;
	if read buffer is empty then
		return an error;
		end if;
	write frame length into buffer size register;
	if mode is legacy then
		send SPI read command;
		end if;
	while read buffer is not empty do
		read read buffer;
		extract Ethernet frame from your frame buffer;
		update any read statistics;
		end while;
	return success;
	end function;
</screen>

<screen>
function transmit frame do
	read the write buffer space available register;
	while transmit queue is not empty and write buffer space is available do
		encapsulate transmit frame;
		write transmit frame to write buffer;
		update transmit statistics;
		if error then
			return failure;
			end if;
		update transmit statistics;
		remove frame from transmit queue;
		end while;
	return success;
	end function;
</screen>

		<para>
			The interrupt service routine suspends, waiting for an interrupt from the QCA7000. Use of an interrupt means that the host need not continuously poll the SPI status and space available registers to detect if an operation has completed successfully before starting the next operation. Once an interrupt is detected by the host, this routine disables further interrupts and determines shy the interrupt occured by inspecting the <varname>INTR_CAUSE</varname> and <varname>SPI_STATUS</varname> registers. It then handles the interrupt by calling appropriate functions. When done, it clears the interrupt cause and SPI status registers and suspends. 
			</para>
<screen>
function interrupt service routine do
	while terminate is false do
		set thread state to interruptable;
		if no interrupts and synchronization state is synchronized and transmit queue is empty then
			allow other tasks to run;
			end if;
		set thread state to busy;
		check synchronization state;
		if syncrhonization state is not synchronized then
			flush transmit queue;
			suspend for a while;
			end if;
		if interrupt occurred then
			disable interrupts;
			read interrupt cause register;
			if interrupt cause is CPU on then
				update synchronization state;
				if synchronization state is synchronized then
					continue;
					end if;
				end if;
			if interrupt cause is packet available then
				if synchronization state is synchronized then
					call receive frame function;
					end if;
				end if;
			if interrupt cause is read buffer error then
				set synchronization state to unknown;
				continue;
				end if;
			if interrupt cause is write buffer error then
				set synchronization state to unknown;
				continue;
				end if;
			clear interrupt cause register;
			clear SPI status register;
			end if;
		if transmit queue is not empty then
			call transmit frame function;
			end if;
		end while;
		set thread state to dormant;
		return;
	end function;
</screen>

<screen>
function synchronize slave do 
	allocate a static reset counter; 
	if synchronization state is CPU on then 
		read QCA7000 signature register; 
		read QCA7000 signature register; 
		if signature is invalid then 
			set synchronization state to unknown; 
		else 
			read write buffer space available register; 
			if write buffer is empty then 
				set qca.SynchState to QCASPI_SYNC_READY; 
				set synchronization state to ready; 
				return; 
			else 
				set synchronization state to unknown; 
				end if; 
			end if; 
		end if; 
		if synchronization state is ready then 
			if mode is legacy then 
				return; 
				end if; 
			read QCA7000 signature register; 
			if signature is invalid then 
				set synchronization state to unknown; 
				return; 
				end if; 
			end if; 
		if synchronization state is unknown then 
			if mode is legacy then 
				use GPIO to reset QCA7000; 
			else 
				read QCA7000 signature register; 
				if signature is invalid then 
					return; 
					end if; 
				set soc_core_reset bit in QCA SPI configuration register; 
				end if; 
			set synchronization state to reset; 
			clear reset counter; 
			return; 
		end if; 
	if synchronization state is reset then 
		increment reset counter; 
		if reset counter exceeds reset limit then 
			set synchronization state to unknown; 
			end if; 
		end if; 
	return; 
	end function;
</screen>

<screen>
function interrupt handler do
	increment interrupt count;
	if thread is available and thread is dormant then
		wake up thread to service interrupt;
		end if;
	return success;
	end function;
</screen>
		</section>

	<section id="qcaspi1">
		<title>
			SPI Serial Driver
			</title>
		<section id="qcaspi_spi_thread">
			<title>
				qcaspi_spi_thread
				</title>
			<funcsynopsis>
				<funcprototype>
					<funcdef>static int <function>qcaspi_spi_thread</function></funcdef>
	  				<paramdef>char void * <parameter>data</parameter></paramdef>
	  				</funcprototype>
				</funcsynopsis>
			<para>
				Manages synchronization with the exteranl QCA7000. 
				Handles interrupts fomr the external QCA7000. 
				Transmits frames for the transmit queue to the QCA7000.
				</para>
			</section>
		<section id="qcaspi_qca7k_sync">
			<title>
				qcaspi_qca7k_sync
				</title>
			<funcsynopsis>
				<funcprototype>
					<funcdef>void <function>qca_qca7k_sync</function></funcdef>
	  				<paramdef>char struct qcaspi * <parameter>qca</parameter></paramdef>
	   				<paramdef>int <parameter>event</parameter></paramdef>
	  				</funcprototype>
				</funcsynopsis>
			<para>
				Keeps track of the current synchonization state.
				</para>
			</section>
		</section>

	<section id="qcaspi2">
			<title>
				Register Functions
				</title>
		<section id="qcaspi_read_register">
			<title>
				qcaspi_read_register
				</title>
			<funcsynopsis>
				<funcprototype>
					<funcdef>uint16_t <function>qcaspi_read_register</function></funcdef>
	  				<paramdef>struct qcaspi * <parameter>qca</parameter></paramdef>
	  				<paramdef>uint16_t <parameter>reg</parameter></paramdef>
	  				</funcprototype>
				</funcsynopsis>
			<para>
				Reads a QCA7000 register and returns register content.
				</para>
			</section>
		<section id="qcaspi_write_register">
			<title>
				qcaspi_write_register
				</title>
			<funcsynopsis>
				<funcprototype>
					<funcdef>void <function>qcaspi_write_register</function></funcdef>
	  				<paramdef>struct qcaspi * <parameter>qca</parameter></paramdef>
	  				<paramdef>uint16_t <parameter>reg</parameter></paramdef>
	  				<paramdef>uint16_t <parameter>value</parameter></paramdef>
	  				</funcprototype>
				</funcsynopsis>
			<para>
				Write a value into a QCA7000 register.
				</para>
			</section>
		<section id="qcaspi_tx_cmd">
			<title>
				qcaspi_tx_cmd
				</title>
			<funcsynopsis>
				<funcprototype>
					<funcdef>int <function>qcaspi_tx_cmd</function></funcdef>
	  				<paramdef>struct qcaspi * <parameter>qca</parameter></paramdef>
	  				<paramdef>uint16_t <parameter>cmd</parameter></paramdef>
	  				</funcprototype>
				</funcsynopsis>
			<para>
				Transmit a 16-bit command to the QCA7000. This is currently used when performing a legacy DMA read or write.
				</para>
			</section>
		</section>
	
	<section id="qcaspi3">
			<title>
				Interrupt Functions
				</title>
		<section id="disable_spi_interrupts">
			<title>
				disable_spi_interrupts
				</title>
			<funcsynopsis>
				<funcprototype>
					<funcdef>uint32_t <function>disable_spi_interrupts</function></funcdef>
	  				<paramdef>struct qcaspi * <parameter>qca</parameter></paramdef>
	  				</funcprototype>
				</funcsynopsis>
			<para>
				Disables interrupts by writing <constant>0</constant> to the QCA7000 <varname>INTR_ENABLE</varname> register.
				</para>
			</section>
		<section id="enable_spi_interrupts">
			<title>
				enable_spi_interrupts
				</title>
			<funcsynopsis>
				<funcprototype>
					<funcdef>uint32_t <function>enable_spi_interrupts</function></funcdef>
	  				<paramdef>struct qcaspi * <parameter>qca</parameter></paramdef>
	  				<paramdef>uint32_t <parameter>intr_enable</parameter></paramdef>
	  				</funcprototype>
				</funcsynopsis>
			<para>
				Enables interrupts specified by writing to the QCA7000 <varname>INTR_ENABLE</varname> register and returns the previous register value.
				</para>
			</section>
		<section id="qcaspi_intr_handler">
			<title>
				qcaspi_intr_handler
				</title>
			<funcsynopsis>
				<funcprototype>
					<funcdef>static irqreturn_t <function>qcaspi_intr_handler</function></funcdef>
	  				<paramdef>int <parameter>irq</parameter></paramdef>
	  				<paramdef>void * <parameter>data</parameter></paramdef>
	  				</funcprototype>
				</funcsynopsis>
			<para>
				Called to service interrupts on rising edge of the QCA7000 interrupt line.
				</para>
			</section>
		</section>