ktechlab/doc/en/microbe.docbook

<!-- kate: tab-width 2; indent-mode xml; -->
<chapter id="microbe">
<title>&microbe;</title>
<sect1>
	<title>Introduction and General Syntax</title>
	<para>
		<application>Microbe</application> compiles programs written in the custom language for PICs, as a companion program to <application>&kappname;</application>. The syntax has been designed to suit a &flowcode; program.
		
		The syntax for running <command>microbe</command> from the commandline is:
		
		<programlisting>microbe [options] [input.microbe] [output.asm]</programlisting>
		
		where options are:
		<itemizedlist>
			<listitem><para><function>--show-source</function> - Puts each line of &microbe; source code as a comment in the assembly output before the assembly instructions themselves for that line.</para></listitem>
			<listitem><para><function>--no-optimize</function> - Prevent optimization of the instructions generated from the source. Optimization is usually safe, and so this option is mainly used for debugging.</para></listitem>
		</itemizedlist>
		
		The .microbe input file must identify the target PIC by inserting the PIC name at the top of the .microbe file; e.g. the name of a PIC16F84 is "P16F84".
		
		<example><title>Simple complete &microbe; program</title>
			<programlisting role="correct">
P16F84

a = 0
repeat
{
	PORTA = a
	a = a + 1
}
until a == 5

end</programlisting>
			</example>
		</para>

	<sect2 id="namingconventions">
		<title>Naming conventions</title>
		<para>
			The following rules apply to variable names and labels:
			<itemizedlist>
				<listitem><para>They can only contain alphanumerical characters [a..z][A..Z][0..9] and the underscore "_".</para></listitem>
				<listitem><para>They are case-sensitive.</para></listitem>
				<listitem><para>They cannot start with a number.</para></listitem>
				<listitem><para>They should not start with "__" (double underscore), as this is reserved for use by the compiler.</para></listitem>
			</itemizedlist>
		</para>
	</sect2>

	<sect2 id="bracingconventions">
		<title>Bracing conventions</title>
		<para>
			Curly braces, {}, indicate the start and end of a code block.
			
			They can appear anywhere before the start and after the end of the code block.
			
			Examples of acceptable code blocks:
	<programlisting role="correct">
statement1 {
	some code
}</programlisting>
		<programlisting role="correct">
statement2 {
	other code }</programlisting>
		
		<programlisting role="correct">
statement3
{
	other code
}</programlisting>
		
		<programlisting role="correct">
statement5 {
	code block
} statement6</programlisting>
			</para>
		</sect2>
		<sect2 id="commenting">
			<title>Commenting</title>
			<para>
				Commenting is similar to C. // comments out the rest of the line. /* and */ denote a multiline comment.
				<programlisting role="correct">
// This is a comment
x = 2 
/* As is this
multiline comment */</programlisting>
		</para>
	</sect2>

	<sect2 id="structure">
		<title>Program Structure</title>
		<para>
			The PIC id must be inserted at the top of the program. The end of the main program is denoted with "end". Subroutines must placed after "end".
		</para>
	</sect2>

	<sect2 id="subroutines">
		<title>Subroutines</title>
		<para>
			A subroutine can be called from anywhere in the code. Syntax:
		</para>
		<programlisting role="correct">
sub SubName
{
	// Code...
}</programlisting>
		<para>The subroutine is called with "call SubName".</para>
	</sect2>
</sect1>

<sect1 id="languagereference">
	<title>&microbe; language reference</title>
	<sect2 id="if">
		<title>if</title>
		<para>Conditional branching.
			
			Syntax:
			<programlisting role="correct">if [expression] then [statement]</programlisting>
			or
			<programlisting role="correct">
if [expression] then
{
	[statement block]
}</programlisting>
		
			Similarly for else:
			<programlisting role="correct">else [statement]</programlisting>
			or
			<programlisting role="correct">
else
{
	[statement block]
}</programlisting>
			</para>
			
			<example><title>if</title>
			<programlisting role="correct">
if porta.0 is high then
{
	delay 200
}
else
{
	delay 300
}</programlisting>
		</example>
	</sect2>
	
	<sect2 id="alias">
		<title>alias</title>
		<para>Aliases one string to another. Syntax:
			<programlisting role="correct">alias [from] [to]</programlisting>
		</para>
	</sect2>
	
	<sect2 id="repeat">
		<title>repeat</title>
		<para>Executes the statement block repeatedly until expression evaluates to true.
			
			The evaluation of the expression is performed after the statement block, so the statement block will always be executed at least once. Syntax:
	<programlisting role="correct">
repeat
{
	[statement block]
}
until [expression]</programlisting>
	</para>
</sect2>

<sect2 id="while">
<title>while</title>
	<para>
	Similar to repeat, this repeatedly executes the statement block. However, the expression is evaluated before execution, not after. So if the expression evaluates to false on the first pass, then the statement block will not get executed.
	
	Syntax:
	<programlisting role="correct">
while [expression]
{
	[statement block]
}</programlisting>
	</para>
</sect2>


<sect2 id="goto">
	<title>goto</title>
	<para>
		This causes execution of the code to continue at the next statement after the label specified.
		
		Goto syntax:
		<programlisting role="correct"><function>goto</function> [labelname]</programlisting>
		
		Label syntax:
		<programlisting role="correct"><function>labelname:</function></programlisting>
		
		It is often considered good programming practice to avoid the use of goto. Use of control statements and subroutines will result in a much more readable program.
	</para>
	
	<example><title>goto</title>
	<programlisting role="correct">
goto MyLabel

...

[MyLabel]:
// Code will continue at this point</programlisting>
		</example>
	</sect2>
	
	<sect2 id="call">
		<title>call</title>
		<para>
			Calls a subroutine.
			
			Syntax:
			<programlisting role="correct"><function>call</function> [SubName]</programlisting>
			where SubName is the name of the subroutine to be called.
		</para>
	</sect2>
	
	<sect2 id="delay">
	<title>delay</title>
		<para>
		This causes the code execution to stop for the given period of time. The interval is in milliseconds.
		
		Syntax:
		<programlisting role="correct"><function>delay</function> [interval]</programlisting>
		
		<note><para>At present, &microbe; assumes that the PIC is operating at a frequency of 4Mhz - i.e. each instruction takes 1 microsecond to execute. If this is not the case, the interval must be adjusted proportionately.</para></note>
		</para>
	</sect2>
	
	<sect2 id="sevenseg">
		<title>sevenseg</title>
		<para>This is used to define the pin mapping for a (common cathode) seven segment display connected to the PIC. Syntax:
			<programlisting role="correct"><function>sevenseg</function> [name] [a] [b] [c] [d] [e] [f] [g]</programlisting>
			
			where [a]...[g] are the PIC pins to which the respective segments of the seven segment display are attached. The pins can be written either as PORTX.N or RXN.
		</para>
		
		<para>To display a number on the seven segment, the pin mapping is treated as a write only variable.
			<example>
				<title>Defining and outputting to a seven segment</title>
				<programlisting role="correct">
sevenseg seg1 RB0 RB1 RB2 RB3 RB4 RB5 RB6
seg1 = x + 2</programlisting>
				</example>
		</para>
	</sect2>
	
	<sect2 id="keypad">
		<title>keypad</title>
		<para>This is used to define the pin mapping for a keypad connected to the PIC. Syntax:
			<programlisting role="correct"><function>keypad</function> [name] [row 1] ... [row 4] [column 1] ... [column n]</programlisting>
			
			where [row 1] ... [row 4] and [column 1] ... [column n] are the PIC pins to which the respective rows and columns of the keypad are attached (at the moment, the number of rows is not changeable). See <xref linkend="sevenseg"/> (above) for more information on pin mappings.
		</para>
		
		<para>The columns of the keypad should be pulled down via 100k resistors to ground. The row pins must be configured as outputs and the column pins as inputs. Once the keypad has been defined, it is treated as a read only variable.
			<example>
				<title>Defining and reading from a keypad</title>
					<programlisting role="correct">
keypad keypad1 RB0 RB1 RB2 RB3 RB4 RB5 RB6
x = keypad1</programlisting>
			</example>
		</para>
			
		<para>
			By default, the values returned for a keypad are:
			<itemizedlist>
				<listitem><para>The value of the number if it is a numeric key (1 to 3 along top row; hexadecimal A to D down the fourth column and continuing for each extra column).</para></listitem>
				<listitem><para>253 for the key in row 4, column 1.</para></listitem>
				<listitem><para>254 for the key in row 4, column 3.</para></listitem>
			</itemizedlist>
			These values can be redefined by using the alias command, where the name of the key in row x, column y (rows and columns starting at 1), is Keypad_x_y. For example, to give the star key on a 4x3 keypad the value zero, the following alias would be used:
			<example>
				<title>Aliasing a keypad key to a value</title>
				<programlisting role="correct">alias Keypad_4_1 0</programlisting>
			</example>
		</para>
	</sect2>
</sect1>

<sect1 id="picio">
<title>PIC I/O</title>
	
	<sect2 id="tristate">
	<title>Port Direction</title>
		<para>
		The port direction is set by assigning a value to TRIS*, where * is the port letter. For example:
		</para>
		<example><title>Setting port directions</title>
		<programlisting role="correct">TRISB = b'01111001'</programlisting>
		</example>
		<para>
		The above sets pins RB1, RB2 and RB7 on PORTB as outputs, and the other pins on PORTB as inputs. In this example, b'01111001' is a binary representation of the output type. The 1 on the right represents an output on RB0, and the 0 on the left represents an input on RB7.
		</para>
	</sect2>
	
	<sect2 id="ports">
	<title>Port I/O</title>
		<para>
		The port can be treated as a variable. For example:
		</para>
		
		<example><title>Writing to a port</title>
		<programlisting role="correct">x = PORTA</programlisting>
		</example>
		
		<para>
		The above assigns the value of PORTA to the variable x.
		</para>
	</sect2>
	
	<sect2 id="pins">
	<title>Pin I/O</title>
		<para>
		Each pin on a port is obtained by prefixing the pin number by the port name; e.g. Pin 2 (starting from Pin 0) on PORTA is known as
		<emphasis>PORTA.0</emphasis>.
		
		The syntax to set a pin state is:
		<programlisting role="correct">PORTX.N = <emphasis>STATE</emphasis></programlisting>
		where <emphasis>STATE</emphasis> can be <emphasis>high</emphasis> or <emphasis>low</emphasis>.
		
		The syntax to test a pin state is:
		<programlisting role="correct"><function>if</function> PORTX.N is <emphasis>STATE</emphasis> <function>then</function></programlisting>
		
		Combining these examples, we have:
		</para>
		<example><title>Setting and testing pin state</title>
		<programlisting role="correct">
TRISA = 0
TRISB = 255
<function>if</function> PORTA.3 is <function>high</function> <function>then</function>
{
	PORTB.5 = <function>low</function>
}
<function>else</function>
{
	PORTB = PORTA + 15
}</programlisting>
		</example>
	</sect2>
</sect1>
	
<sect1 id="variables">
<title>Variables</title>
	<para>
	All variables are 8-bit unsigned integers, giving a range from 0 to 255.
	
	<application>&microbe;</application> supports the typical unary operations (acting on one variable) and binary operations (acting on two variables) that are supported by the PIC. In addition, &microbe; also supports division and multiplication.
	</para>
	<sect2 id="unary">
	<title>Unary Operations</title>
		<para>
		<itemizedlist>
		<listitem><para><emphasis>rotateleft x</emphasis> - Rotates the variable x left through carry.</para></listitem>
		<listitem><para><emphasis>rotateright x</emphasis> - Rotates the variable x right through carry.</para></listitem>
		<listitem><para><emphasis>increment x</emphasis> - Increments the variable x. If x has a value of 255, then x wraps round to 0.</para></listitem>
		<listitem><para><emphasis>decrement x</emphasis> - Decrements the variable x. If x has a value of 0, then x wraps round to 255.</para></listitem>
		</itemizedlist>
		</para>
	</sect2>
	
	<sect2 id="arithmetic">
	<title>Arithmetic</title>
		<para>
		Supported operations:
		<itemizedlist>
		<listitem><para><emphasis>Addition:</emphasis> x + y</para></listitem>
		<listitem><para><emphasis>Subtraction:</emphasis> x - y</para></listitem>
		<listitem><para><emphasis>Multiplication:</emphasis> x * y</para></listitem>
		<listitem><para><emphasis>Division:</emphasis> x / y</para></listitem>
		<listitem><para><emphasis>Binary XOR:</emphasis> x XOR y</para></listitem>
		<listitem><para><emphasis>Binary AND:</emphasis> x AND y</para></listitem>
		<listitem><para><emphasis>Binary OR:</emphasis> x OR y</para></listitem>
		</itemizedlist>
		</para>
	</sect2>
	
	<sect2 id="comparison">
	<title>Comparison</title>
	<para>
	Supported operations:
	<itemizedlist>
	<listitem><para><emphasis>Equals:</emphasis> x == y</para></listitem>
	<listitem><para><emphasis>Does not equal:</emphasis> x != y</para></listitem>
	<listitem><para><emphasis>Is greater than:</emphasis> x > y</para></listitem>
	<listitem><para><emphasis>Is less than:</emphasis> x &lt; y</para></listitem>
	<listitem><para><emphasis>Is greater than or equal to:</emphasis> x &gt;= y</para></listitem>
	<listitem><para><emphasis>Is less than or equal to:</emphasis> x &lt;= y</para></listitem>
	</itemizedlist>
	
	For example:
	</para>
	<example><title>Comparison</title>
	<programlisting role="correct">
<function>if</function> PORTA >= 5 <function>then</function>
{
	...
}</programlisting>
	</example>
	</sect2>
</sect1>

<!--
<sect1 id="interrupts">
<title>Interrupts</title>
	<para>
	There are several types of events, and some of these take an optional parameter making
	the condition under which the routine is called more specific.
	<itemizedlist>
	<listitem><para><emphasis>changed &lt;pin name&gt;</emphasis>	
		 - Occurs when the state of the specified pin changes. Pin name is in the usual syntax of PORTX.n, e.g. <programlisting>interrupt changed PORTB.4</programlisting></para></listitem>
	<listitem><para><emphasis>triggered</emphasis> - Rotates the variable x right through carry.</para></listitem>
	<listitem><para><emphasis>timer</emphasis> - ///TODO</para></listitem>
	<listitem><para><emphasis>write_complete</emphasis> - ///TODO</para></listitem>
	</itemizedlist>
	</para>
</sect1>
-->
</chapter>