VGA Text Display - new C tutorial & Learn folder update

Steph Lindsay

Hi Folks,

In honor of our just-released VGA SIP Adapter Board, Andy has made a Propeller C Tutorial "VGA Text Display."

The tutorial requires a freshly updated version of the vgatext library. So, we've updated the Learn folder to include the new vgatext, along with some other additions. The folder download and "What's New" information can be found here:

http://learn.parallax.com/propeller-c-set-simpleide/update-your-learn-folder

tdlivings

In the new SimpleTools library doc the new function cog_run looks to be saying two different things.

In the list of functions there is this which makes sense.

int * cog_run (void(*function)(void *par), int stacksize)
Run a function's code in the next available cog (processor).

cog_run has as it's first parameter a pointer to a function that returns void and has a void pointer as a parameter.
This looks right as a wrapper around the Multicore Example that used cogstart,

Later in the detail part describing cog_run I think the auto doc generator messed up the definition to this.

int* cog_run ( void(*)(void *par) function,
int stacksize
)

Maybe that says the same thing another way but it looks like it got messed up trying to keep the word function in red all by itself.

However later on in the description there is this
cog_run is designed to make launching application level functions (typically from the main file) quick and easy. All you have to do is pass a pointer to a function with no return value or parameters along with the number for extra memory to reserve.

This is not what the first cog_run defintion in the list does and I wonder what good it would do to be able to launch a function
into a cog that you cannot tell it anything and it cannot tell you anything..

I hope the first definition as a wrapper around cogstart where there is a void *par is the way it is .

As always I am open to being educated. Also I have written a few functions in my time that just used up memory and clock cycles
and did nothing else.

Tom

jazzed

Tom,

I understand what you mean. It's really a matter of syntax though.

"void(*)(void *par) function" ... looks confusing, but "void(*)(void *par)" is simply a type like "int" is a type. C is a typed language that allows for checking for problems at compile time. The only thing that "void(*)(void *par)" says is, that what is expected is a function that looks like this: void myFunction(void* par) {}

Andy could have defined a new type like this: typedef void(*)(void *par) cog_funcptr_t;

Then the declaration syntax would be clearer: int cog_run(cog_funcptr_t function, int stacksize);

The reason to use _t is to tell the user that it is a type. This makes code readable. Normally it is not good practice to hide the * pointer aspect inside a type. In this case however we don't have much choice.

Also, regarding par. Andy writes lots of the example code using global variables. To me that makes things painful to try and reuse, however it eliminates needing to understand the more advanced structure concept or the error prone array variable for par. If it was C++ cog_run could be defined two different ways.

Andy Lindsay (Parallax)

Hi Tom,

Thanks for pointing this out; I'll clean up the documentation for the next update. I should have added some discussion about the other cog launching function options, which these do not not replace. They are just there to add an option for quick and convenient launching of main file functions into other cogs. ...and also to provide a more approachable conceptual step toward launching cogs in the tutorial sequence with fewer "we'll talk about that later because it's an advanced topic" elements. Here is an example:

#include "simpletools.h"

void blink();

int main()
{
  int *cog = cog_run(&blink, 10);
  pause(3000);
  cog_end(cog);
}

void blink()
{
  low(26);
  while(1)
  {
    toggle(26);
    pause(100);
  }
}

Andy