Getting Started with the StarterKit

All technical discussions and projects around startKIT
IraqiGeek
Member++
Posts: 23
Joined: Wed Dec 18, 2013 3:10 pm

Getting Started with the StarterKit

Post by IraqiGeek »

Hi guys,

Was really happy to have received my StarterKit today, but now I feel quite frustrated. Not with the kit itself, mind you, but with the documentation and info, or rather lack of.

I read through the getting started document, downloaded, and installed the IDE quite quickly, but the issues started soon after. The first issue was a Java error (despite having JDK installed). A quick Google search, and I found a StackOverflow thread that resolved the issue. Still, the getting started guide needs to point the need to having Java installed, and link to the page to download it. The second was related to setting the workspace folder and project import folder. Took me a few minutes to figure this out, but a simple note about it would have prevented the issue altogether. Basically, projects cannot reside in the same folder as the workspace.

After those two snags, I was able to compile and run a couple of projects without issue, and was really surprised at the speed of building and uploading projects (coming from Arduino and .NETMF worlds).

But as soon as I wanted to make my own hello world project I was pretty much lost. Took me way longer than it should to find simple things like which pins on the starter kit are mapped to which ports in software? Only after reading the portmap table did I understand the logical mapping. I am still unable to find what should be otherwise simple info, like is a given pin in or out? or can it be configured as either? What is the voltage output of I/O pins? How much RAM does the StarterKit have? How is that used (code and data? or data only?) What hardware resources does the XCore in the starter kit have? How many cores does it have (I was able to deduce its 8 from looking at the list of analog XCores and looking which has 500MIPS)? I recall reading a table somewhere about how much processing time each core/thread gets but can't find it again. I'm sure somewhere there is a datasheet that lists all that, but I couldn't find it. Either way, having a quick bullet point list in the hardware manual (and getting started doc) would really help.

As for getting started and tutorials, a walk through of the IDE environment, a small cheat sheet of the most useful shortcut keys, an explanation of the various areas of the IDE and what each one does followed by a step by step tutorial on how to create a new project, how to write your first hellow world or blinky program focusing on explaining the program workflow, how to setup a port and how to use a pin would really really help. A few more tutorials that walk users through how to setup and use SPI, I2C, PWM, the integrated ADC (maybe linking them tegether to get a tutorial on how to setup a multi-threaded, pipelined program that can levarage the whole 500MIPS available?) and the community can really take off.

I hope the moderators of this forum, and the people at XMos don't take my comments above as criticism. The XCore StarterKit is an amazingly priced, amazingly powerful little board. Even in single threaded operation it is more powerful than most hobbyist ARM boards, and easily an order of magnitude more powerful than AVRs.

EDIT 02-01-2014: After spending over a dozen hours scouring for documents and reading said documents, I decided to start a sort of "intro series" of posts at my blog. Here are the first two:
Last edited by IraqiGeek on Sun Jan 19, 2014 4:59 am, edited 4 times in total.


AJB2K3
Member++
Posts: 27
Joined: Sat Dec 14, 2013 1:03 pm

Post by AJB2K3 »

IraqiGeek wrote:Hi guys,

Was really happy to have received my StarterKit today, but now I feel quite frustrated. Not with the kit itself, mind you, but with the documentation and info, or rather lack of.

I read through the getting started document, downloaded, and installed the IDE quite quickly, but the issues started soon after. The first issue was a Java error (despite having JDK installed). A quick Google search, and I found a StackOverflow thread that resolved the issue. Still, the getting started guide needs to point the need to having Java installed, and link to the page to download it. The second was related to setting the workspace folder and project import folder. Took me a few minutes to figure this out, but a simple note about it would have prevented the issue altogether. Basically, projects cannot reside in the same folder as the workspace.

After those two snags, I was able to compile and run a couple of projects without issue, and was really surprised at the speed of building and uploading projects (coming from Arduino and .NETMF worlds).

But as soon as I wanted to make my own hello world project I was pretty much lost. Took me way longer than it should to find simple things like which pins on the starter kit are mapped to which ports in software? Only after reading the portmap table did I understand the logical mapping. I am still unable to find what should be otherwise simple info, like is a given pin in or out? or can it be configured as either? What is the voltage output of I/O pins? How much RAM does the StarterKit have? How is that used (code and data? or data only?) What hardware resources does the XCore in the starter kit have? How many cores does it have (I was able to deduce its 8 from looking at the list of analog XCores and looking which has 500MIPS)? I recall reading a table somewhere about how much processing time each core/thread gets but can't find it again. I'm sure somewhere there is a datasheet that lists all that, but I couldn't find it. Either way, having a quick bullet point list in the hardware manual (and getting started doc) would really help.
There is a document which contains a listing of every pinout on the startkit available from the startkit mini site!
IraqiGeek wrote: As for getting started and tutorials, a walk through of the IDE environment, a small cheat sheet of the most useful shortcut keys, an explanation of the various areas of the IDE and what each one does followed by a step by step tutorial on how to create a new project, how to write your first hellow world or blinky program focusing on explaining the program workflow, how to setup a port and how to use a pin would really really help. A few more tutorials that walk users through how to setup and use SPI, I2C, PWM, the integrated ADC (maybe linking them tegether to get a tutorial on how to setup a multi-threaded, pipelined program that can levarage the whole 500MIPS available?) and the community can really take off.
There is a document which contains a listing of every pinout on the startkit available from the startkit mini site!
IraqiGeek wrote: I hope the moderators of this forum, and the people at XMos don't take my comments above as criticism. The XCore StarterKit is an amazingly priced, amazingly powerful little board. Even in single threaded operation it is more powerful than most hobbyist ARM boards, and easily an order of magnitude more powerful than AVRs.
Have you explored the Startkit mini site and all the docs ?
Tutorials are rather lacking at the moment but there are docs on the startkit and IDE and then the sample programs are well documented!
IraqiGeek
Member++
Posts: 23
Joined: Wed Dec 18, 2013 3:10 pm

Post by IraqiGeek »

AJB2K3 wrote: There is a document which contains a listing of every pinout on the startkit available from the startkit mini site!
As I said in my original post, the StarterKit Hardware Manual has tables for all the info. My comment was related to having to always rerference two tables to know which pin is in which logical port. Always jumping forth and back in the hardware manual.

My comments and suggestions are about a lot more than just listing the pins and ports mapping.
AJB2K3 wrote: Have you explored the Startkit mini site and all the docs ?
Tutorials are rather lacking at the moment but there are docs on the startkit and IDE and then the sample programs are well documented!
Thats where I found the StarterKit Hardware Manual, and getting started tutorials.
AJB2K3
Member++
Posts: 27
Joined: Sat Dec 14, 2013 1:03 pm

Post by AJB2K3 »

I take back my comment as during a reread of the docs I am comming across some confusion with pin/port numbering.
IraqiGeek
Member++
Posts: 23
Joined: Wed Dec 18, 2013 3:10 pm

Post by IraqiGeek »

So, further reading answered some questions, but again, things are way harder than they should be:
  • The Wikipedia Page about the XCore XS1 provides a sorely missing nice and simple overview of the XCore architecture.
  • The mini site's link to the xTIMEcomposer User Guide is broken. As always, Google's to the rescue. But honestly, there needs to be a quick tutorial (no more than 3 pages worth of text) on how to do the basic things. A quick cheat sheet of the 10 or most common keyboard shortcuts would also be nice.
  • Said Wikipedia Page also links to theXmos XS1 architecture book which, for the life of me, couldn't find on the mini site.
  • Reading the Architecture book, found some tidbits that answered some of my previous questions, such as:
    • 5.1 Scheduler Implementation (pages 9 and 10): really helps understand how to calculate the expected performance of a thread in the chip.
    • 11 Concurrency and Thread Synchronisation (pages 18-20): explains the concept. A similar explanation with actual C/C++ code instead of assembly would really help.
    • 12 Communication (pages 21-24): inter-thread communication. This was quite confusing to me, and this is from a guy who has written multi-stage threaded software pipelines with syncs and locks for years. A producer-consumer explanation would help.
    • 13 Locks (page 24): producer-consumer C/C++example of this would help show how to use it.
    • 14 Timers and Clocks (pages 24-26): First mention of the actual clock of the timers (woohoo!). Still MIA is how many timers are there? Bit depth of each? Does this also apply to port I/O?
    • 15 Ports, Input and Output (pages 26-34): Lots of useful info here, but mostly tied to the instruction set. Some of the tidbits here:
      • Logical ports can be configured as input or output, the StarterKit Hardware Manual (page 14) makes one believe otherwise.
      • Pins are tri-state unless configured otherwise.
      • Pins have configurable pull-ups and/or pull-downs (woohoo!).
      • Ports are 1, 4, 8 and 32 bit (as indicated in the Hardware Manual, but in a much clearer way).
      • One bit ports seem to be the most awesome in terms of flexibility and possible uses (and starter kit has 16 of them).
      • Ports can do serialization and deserialization!!! (triple-woohoo!)
      • Ports are buffered, though I couldn't understand the depth of said buffer.
      • Ports can use the reference clock or other internal clock sources. Beats me if I could find what are those sources, what clock rates they support, whether they are configurable, and what is the effective max clock rate that can be achieved.
      • Ports can have conditional inputs and/or outputs and generate events as well as interrupts (if I understood this correctly).
      • Ports can operate in master or slave modes.
      • Ports can operate asynchronously or synchronously with regards to the port clock.
    • 16 Events, Interrupts and Exceptions (pages 35-40): honestly, didn't read through this one, especially since its talking about the three concepts at the instruction level. What I'd like to know and have C/C++ examples for is:
      • Events: Are there any predefined system events? What are they? Can developers declare their own types of events? How? How to declare an event handler for each type of event? Can they be chained?
      • Interrupts: Are they only hardware interrupts? Or can there be software interrupts? If the latter is possible, how are they declared? How are ISRs hooked into the interrupt system?
      • Exceptions: Why the actual explanation of exceptions was deferred to section 19.3 (pages 247-257) some 210 pages later beats me. Anyway, a one page listing what exceptions exist with C/C++ snippets of code that would provoke each type would be more than enough.
  • Some six hours of reading, looking for info, and writing these posts, I am still nowhere closer to understanding how memory is allocated on the XCore, whether its used for data or program and data (I'm kind of sure its the latter, but would be nice to have some factual info), or filling many of the other blanks regarding the chip in the StarterKit.
  • The more I read about the XCore (and I've been kind of following it since 2010), the more I'm convinced this architecture, and especially the chip in the StarterKit, has the potential to revolutionize the hobbyist electronics market the way the Arduino did. All that is needed is a some info gathering and organization, and some simple tutorials to get our training wheels off.
I know its the holidays season and many (most?) XMos people are probably on holiday, but I hope soon I/we can get some of those wholes plugged and some info made available in an easier, less time consuming (for interested developers) way.

XMos already invested in giving away 3500 StarterKit boards. If only half of those who got one want to use it for a project, that is still more than 29 man-hours working on their actual ideas/projects for every minute saved by making info easier to access!
AJB2K3
Member++
Posts: 27
Joined: Sat Dec 14, 2013 1:03 pm

Post by AJB2K3 »

IraqiGeek wrote:So, further reading answered some questions, but again, things are way harder than they should be:
  • The Wikipedia Page about the XCore XS1 provides a sorely missing nice and simple overview of the XCore architecture.
  • The mini site's link to the xTIMEcomposer User Guide is broken. As always, Google's to the rescue. But honestly, there needs to be a quick tutorial (no more than 3 pages worth of text) on how to do the basic things. A quick cheat sheet of the 10 or most common keyboard shortcuts would also be nice.
  • Said Wikipedia Page also links to theXmos XS1 architecture book which, for the life of me, couldn't find on the mini site.
  • Reading the Architecture book, found some tidbits that answered some of my previous questions, such as:
    • 5.1 Scheduler Implementation (pages 9 and 10): really helps understand how to calculate the expected performance of a thread in the chip.
    • 11 Concurrency and Thread Synchronisation (pages 18-20): explains the concept. A similar explanation with actual C/C++ code instead of assembly would really help.
    • 12 Communication (pages 21-24): inter-thread communication. This was quite confusing to me, and this is from a guy who has written multi-stage threaded software pipelines with syncs and locks for years. A producer-consumer explanation would help.
    • 13 Locks (page 24): producer-consumer C/C++example of this would help show how to use it.
    • 14 Timers and Clocks (pages 24-26): First mention of the actual clock of the timers (woohoo!). Still MIA is how many timers are there? Bit depth of each? Does this also apply to port I/O?
    • 15 Ports, Input and Output (pages 26-34): Lots of useful info here, but mostly tied to the instruction set. Some of the tidbits here:
      • Logical ports can be configured as input or output, the StarterKit Hardware Manual (page 14) makes one believe otherwise.
      • Pins are tri-state unless configured otherwise.
      • Pins have configurable pull-ups and/or pull-downs (woohoo!).
      • Ports are 1, 4, 8 and 32 bit (as indicated in the Hardware Manual, but in a much clearer way).
      • One bit ports seem to be the most awesome in terms of flexibility and possible uses (and starter kit has 16 of them).
      • Ports can do serialization and deserialization!!! (triple-woohoo!)
      • Ports are buffered, though I couldn't understand the depth of said buffer.
      • Ports can use the reference clock or other internal clock sources. Beats me if I could find what are those sources, what clock rates they support, whether they are configurable, and what is the effective max clock rate that can be achieved.
      • Ports can have conditional inputs and/or outputs and generate events as well as interrupts (if I understood this correctly).
      • Ports can operate in master or slave modes.
      • Ports can operate asynchronously or synchronously with regards to the port clock.
    • 16 Events, Interrupts and Exceptions (pages 35-40): honestly, didn't read through this one, especially since its talking about the three concepts at the instruction level. What I'd like to know and have C/C++ examples for is:
      • Events: Are there any predefined system events? What are they? Can developers declare their own types of events? How? How to declare an event handler for each type of event? Can they be chained?
      • Interrupts: Are they only hardware interrupts? Or can there be software interrupts? If the latter is possible, how are they declared? How are ISRs hooked into the interrupt system?
      • Exceptions: Why the actual explanation of exceptions was deferred to section 19.3 (pages 247-257) some 210 pages later beats me. Anyway, a one page listing what exceptions exist with C/C++ snippets of code that would provoke each type would be more than enough.
  • Some six hours of reading, looking for info, and writing these posts, I am still nowhere closer to understanding how memory is allocated on the XCore, whether its used for data or program and data (I'm kind of sure its the latter, but would be nice to have some factual info), or filling many of the other blanks regarding the chip in the StarterKit.
  • The more I read about the XCore (and I've been kind of following it since 2010), the more I'm convinced this architecture, and especially the chip in the StarterKit, has the potential to revolutionize the hobbyist electronics market the way the Arduino did. All that is needed is a some info gathering and organization, and some simple tutorials to get our training wheels off.
I know its the holidays season and many (most?) XMos people are probably on holiday, but I hope soon I/we can get some of those wholes plugged and some info made available in an easier, less time consuming (for interested developers) way.

XMos already invested in giving away 3500 StarterKit boards. If only half of those who got one want to use it for a project, that is still more than 29 man-hours working on their actual ideas/projects for every minute saved by making info easier to access!

I think have the problem is that if the Xsoftipexplorer is used then the base configuration of the tile (is it tile of chip?) is no longer standered. The startkit is quite new and one would guess that there waiting to see what we the community can make of it!
IraqiGeek
Member++
Posts: 23
Joined: Wed Dec 18, 2013 3:10 pm

Post by IraqiGeek »

AJB2K3 wrote:I think have the problem is that if the Xsoftipexplorer is used then the base configuration of the tile (is it tile of chip?) is no longer standered. The startkit is quite new and one would guess that there waiting to see what we the community can make of it!
Took me a good three hours to compile that info last night. Three hours!

After writing that post, I was able to find a datasheet for the Analog XS1, not on Xmos' site mind you. Had to Google for the StarterKit, from which I was able to find the press release announcing the StarterKit. From that page, I learned the chip in the starter kit is the XS1-A8-64-DEV, for which I still can't find a datasheet :\

However, Googling for XS1-A8-64 finally got me a datasheet. Lots of tidbits of info there that should be on the StarterKit micro site, and hardware manual.

Tonight, time permitting, I'll write a post detailing that info, and what I have yet to find an answer for, even after reading the datasheet.
IraqiGeek
Member++
Posts: 23
Joined: Wed Dec 18, 2013 3:10 pm

Post by IraqiGeek »

Read a couple of datasheets:
  • XS1-L8A-64-TQ48: This is the smallest pin count 8-tile XS1-L, and one of the few that can be handled/soldered by hobbyists into a DIP breakout. Its also very close to the StarterKit in terms of core resources (clocks, timers, and the like).
  • XS1-U16A-128-FB217 Datasheet: On another thread, segher reccomends reading this as the closest chip/package to that of the StarterKit, ignoring tile 0 and USB.
Another document that really helps understand ports organization and operation including conditional input and serialization/deserialization (which is really awesome) is Ports Specification (X1373A).

Then, there is XS1-L System Specification (X1151A) which explains links (pages 3-20).

For the AVR/ARduino fans, there is/was a XMOS to AVR project buried in the archive of the old xmoslinkers forum. I am attaching the code file for future reference.
Attachments
306.zip
AVR-XMOS Link
(18.82 KiB) Downloaded 306 times
306.zip
AVR-XMOS Link
(18.82 KiB) Downloaded 306 times
markey1979
New User
Posts: 3
Joined: Fri Dec 27, 2013 7:16 am

Post by markey1979 »

@IraqiGeek

There is a datasheet for the STARTkit. It has a xs1-a8a-64 chip ( taken from the schematic)

The datasheet is here:

https://www.xmos.com/en/download/public ... 91H%29.pdf

There is also a chip marking decoder:

https://www.xmos.com/en/published/xcore ... rking-list

This document seems to confirm the part that I just referenced.

I think the hardware manual is also incorrect on page 9. I think the port and pin numbers should be reversed. It is just a little confusing because everywhere else in the document the naming convection's are reversed.

.... But I am new to this also. I could be totally wrong.
IraqiGeek
Member++
Posts: 23
Joined: Wed Dec 18, 2013 3:10 pm

Post by IraqiGeek »

markey1979 wrote:@IraqiGeek

There is a datasheet for the STARTkit. It has a xs1-a8a-64 chip ( taken from the schematic)

The datasheet is here:

https://www.xmos.com/en/download/public ... 91H%29.pdf

There is also a chip marking decoder:

https://www.xmos.com/en/published/xcore ... rking-list

This document seems to confirm the part that I just referenced.
Quoting from the thread I linked above:
segher wrote:It's not an FB96 package, it's an FB217. Have a look at
this one, ignore tile 0 and the USB device.

Port-to-pin mappings are the same on all devices.
Hence the reason why I referenced the XS1-U16A-128-FB217.
Post Reply