Quick Start Guide for FlexC on P2

Overview

The C programming language is widely used for programming all kinds of computers, from embedded systems to super computers. It is a relatively low level language, but much easier to use than assembly language. Because it is so popular, many good resources exist for learning C, both on-line and in books.

C is not officially supported for the Parallax P2, but there are a number of third party solutions which allow programming the P2 in C. This guide will show you how to get started with FlexC, the C compiler in the FlexProp suite of programming languages. FlexProp is a community developed and supported compiler which allows programming the P2 in C, BASIC, Spin 1, Spin 2, and assembly language.

This document assumes that you are familiar with the C language already. If you are not, there are a lot of excellent resources available online for learning C. We will mainly focus on discussing the features peculiar to the P2 and to the FlexProp C compiler.

C in FlexProp: Overview

FlexC (the FlexProp C language) is still a work in progress, but it is intended to support the C99 programming language specification, with some extensions from C++ and GNU C.

Platforms Supported

FlexProp runs on Windows, Mac OS X, and Linux. The instructions below are for Windows. For the Mac you would use very similar instructions. For Linux, it’s probably easiest to clone the FlexProp git source repository and do “make install”.

P2 specific Language Features

FlexC also has some notable extensions for programming the P2, including:

  • Support for inline assembly
  • Support for calling Spin2 and BASIC objects
  • __builtin_cogstart for running functions in another COG
  • Some other builtin intrinsics for accessing P2 instructions

Current Limitations

The current version of FlexC has some limitations with respect to C99

  • No support for 64 bit arithmetic (long long is not support, and double is treated the same as float)
  • No variable length arrays
  • No anonymous structs and unions
  • Limits on designated initializers
  • Incomplete standard library

Getting FlexC / FlexProp

To download the FlexProp GUI, go to the FlexProp releases page and download the flexprop.zip file. Unzip this somewhere convenient, e.g. to your desktop.

Do not put it in a system folder (like the Program Files folder; the FlexProp configuration file is stored next to the executable, so the folder it is in must be writable.

Running FlexC

Connecting the P2 Eval Board

Plug a micro-USB cable into the “PC USB” socket on the P2 Evaluation Board; connect the other end to a USB socket in your PC. Either USB-2 or USB-3 will work.

Running and Configuring FlexProp

Navigate to the flexprop folder where you unzipped flexprop.zip. Double click on flexprop.exe. You may receive a warning about an unknown publisher; you may ignore this warning.

You should see a window come up that looks like this:

FlexProp initial screen

The top section of the window is the editor. This will contain a number of tabs (one for each file you have open). The lower section, labelled Compiler Output, contains messages from the compiler, including any error messages.

Initially there are no open tabs in the editor. To get started, you’ll have to either start a new file (File > New File) or load one of the samples (File > Open File). For this quick start guide we will try a new file.

Running Hello World

Select File > New File. This will open a New File tab, into which you may type your program. Let’s start with the classic “hello world” program.

Enter:

#include <stdio.h>

int main() {
      printf("hello, world!\n");
      return 0;
}

Select File > Save File As… and enter a name for your program (like hello.c). The FlexProp window should now look something like:

Hello World program

Now click on the Compile & Run on P2 button. You should see some compilation messages and then a terminal window labelled Propeller Output should pop up, like:

Hello World running

Anything printed by the C program (e.g. with the printf function) will show up in the Propeller Output window. This is a standard ANSI console window (it uses the default terminal program appropriate for your platform, whether it is Windows, Mac, or Linux) and so you can use ANSI escape sequences to do things like clear screen, move the cursor, change text color, and so on.

The Propeller Output window is in fact an interactive terminal, so if your program requires terminal input you would type it in that window as well.

By default the C program uses a baud rate of 230400 on pins 63 and 62, and this output is captured in the terminal. You may change the baud rate by adding a line like _setbaud(_BAUD); right at the beginning of your C main function, before any printfs. This line will set the baud rate to whatever the value of _BAUD is. The FlexProp GUI automatically adds a define for _BAUD that matches what you’ve selected in the Ports menu.

When you have finished interacting with the program, you must close the Propeller Output window. If you do not, then future attempts to run on the P2 will fail with a Could not find a P2 error (see the Troubleshooting section below). Closing the window does not actually terminate the program on the propeller; it just closes the serial connection and leaves the P2 running.

Blinking LED

Instead of printing messages we may want to blink an LED. Select File > New and enter the following program:

#include <stdio.h> 

int main()
   {
       for(;;) {
         _pinh(56);
         _waitms(500);
         _pinl(56);
         _waitms(500);
      }
}

Select File > Save File As… and choose a name like blink.c.

Now press the Compile & Run on P2 button again. The terminal window will again appear, but no output will show in it (so you may as well just close it). Instead, you’ll see the LED attached to pin 56 blink on and off once each second.

Note that a Propeller Output window will pop up in all cases (where you aren’t expecting to interact with the P2). You may close this window immediately. Closing it does not terminate the program running on the P2; the LED will keep blinking. In any case, you must close the window before trying to run another P2 program.

The _pinh(n) function sets pin n to output and drives it high; similarly _pinl(n) drives the pin low. _waitms(m) waits for m milliseconds.

These and other propeller specific features are discussed in the FlexC documentation, which you may access via the Help > C Language menu.

Troubleshooting

Could not find a P2

If you get a “Could not find a P2” error message in the Propeller Output window, check and make sure that you’ve closed all other Propeller Output windows. Only one Propeller session may be open at a time, and if you try to run a program while a Propeller Output (terminal) window is open then it will not work and the P2 will not be found.

If that isn’t the problem, check the connection to your P2, and look under the Ports menu to see which port is selected. If you know which port the P2 is connected to, you may manually select that one to force FlexProp to use it.

If you have multiple P2 devices connected to your computer, you may select a specific port to connect to by finding it under the Ports menu in FlexProp. If the port you want does not show up, click on Ports > Scan for ports.

C syntax errors

If there’s a syntax error in your program, you’ll get a dialog box like:

Compilation Failed dialog

Click on OK, and then examine the error messages in the Compiler Output window. For example, if we forget a semicolon, there might be a syntax error message. The error message provides a link to the line where the compiler first noticed a problem. If you click on the link, it will take you to the line and highlight it:

FlexProp error message

In this case the actual error is on the line before, the one with the printf (it is missing a semicolon). The compiler can’t always figure out there’s a problem until it sees the next line, so always look at the surrounding code.

C Support for Propeller2 Features

Most Propeller2 features are included in the <propeller2.h> header file, which is (mostly) standardized across C compilers for the P2. Programs that use these features should be portable to Catalina, riscvp2, and other C compilers for the P2.

Documentation for the C features of the P2 is found under the Help > C Language menu item. This will bring open a web browser with documentation for Flex C. The propeller2.h section describes the portable functions for accessing P2 features from C.

Other useful FlexC features are also documented in that file, so it’s well worth reading it.

Using FlexC on the command line or in a Makefile

There is a front end, called flexcc, which may be used to compile FlexC programs on the command line (or when invoked from another build system, such as Make).

Using Spin2 objects from FlexC

Spin2 objects may be used directly in FlexC programs. This is discussed in the FlexC documentation, but it is important enough that we should probably hilight it here. A Spin2 object may be defined as a FlexC structure using the special struct __using syntax. A good example is in the Mandelbrot demo that comes with FlexProp. This may be found in the file samples\Multi-Language\mandelbrot.c. It uses a P2 video object written in Spin2 by Roger Loh. This is declared with:

struct __using("video/p2videodrv.spin2") vid;

This creates an object named vid which uses the Spin2 code from the file p2videodrv.spin2 located in the video subfolder. The Spin2 methods of this object may be invoked with the usual C++ syntax, like:

vid.initDisplay(&display1, vid.VGA, VGA_BASE_PIN, VGA_VSYNC_PIN, vid.RGBHV, &lineBuffer, LINEBUFSIZE, 0);

The multi-language Mandelbrot demo also illustrates some other features of FlexC, such as the use of inline assembly.

Other Resources

The FlexProp Help menu has pages which discuss various features of the languages supported by FlexProp. The Help > General Compiler Reference menu has information applicable to all of the languages, including FlexC. The Help > C Language menu has some C specific information.

For further information about FlexProp in general and FlexC in particular, see the Parallax forums.

Other C compilers for the P2

Besides FlexC there are a number of other community supported C compilers for the P2.

Catalina C

https://sourceforge.net/projects/catalina-c/

Catalina is a mature C compiler for the Parallax Propeller and Propeller 2. It supports the C89 standard, with a few C99 extensions. It is available for Windows and Linux, and comes with a GUI and debugger. Its focus is more on stability and ease of use than on performance. It’s friendly GUI and extensive documentation make it a good alternative to FlexC, especially for newcomers to the P2 and C programming.

LLVM

https://github.com/ne75/p2llvm

This is a native P2 compiler based on the LLVM toolchain, which is a mature C compiler available on many platforms. The P2 port is still a work in progress and requires some familiarity with LLVM and embedded systems programming in general to set up.

riscvp2

https://github.com/totalspectrum/riscvp2

This is a P2 toolchain based on GCC for RISC-V and a JIT compiler from RISC-V rv32imac instructions to P2 instructions (so a kind of RISC-V emulator). Because instructions are compiled to P2 code at run time it is very performant, and on some benchmarks outperforms all of the other P2 compilers available. It has a very complete runtime library as well (based on newlib). However, there is no GUI and some experience with embedded system programming is expected of its users.

New Parallax Website!

We have a brand new website to bring you all the latest and greatest Parallax has to offer. Not to worry, our old site is still available and can be accessed at https://www1.parallax.com!