Freescale MC9S12NE64 development with Imagecraft ICC12 and NoICE

• Ethernet input to RS-485 output, RS-485 format
  
• File playback from media cards, with configurable randomization of parameters and fading in&out
  
• Small size, since sometimes it has to go inside minimally-sized art pieces
• Can be powered from 12V to 24V, since much Colorkinetics gear runs on 24V (read: need a DC/DC to generate 5V and 3.3V)
  
• One Leoplayer playing from media can "broadcast" parts of each frame to others over Ethernet to drive large installations from a single media card
• Various test pattern generation built-in and status indicators
• Flexible playback setup via configuration file on media card
• Responds to "ping", and mini-webserver desirable
  

• Vias under the SD socket pins, I didn't have a socket in hand when I did the board layout, and when the SD card is inserted some of the little 'fingers' that touch the SD card contacts could momentarily touch vias.  A piece of electrical tape on the pcb prevented this in the prototype.
• Make sure the crystal is near the oscillator pins on the chip.  And you have to use a 25Mhz crystal if you want 100mbit ethernet - datasheet page 361.  This came to bite me later, as I wound up needing 20Mhz to generate 625K baud exactly.  This was conveniently solved in software by using the bus clock PLL to multiply by 4/5.  A cool feature of this chip.  Note that several changes must be made if not running at 25Mhz: BUS_CLOCK in ne64config.h, the EtherOpen() call in ne64driver.c (pass MII_C20 as first argument), the RTI timer needs tweaking - see RTI_init() in rti.c and datasheet page 178 (I used 0x73 for RTICTL_RTR, which measures 10.4msec on the scope), and any hand-coded precision delays (I have a delay_us() I wrote in assembler that does no-op loops for precision).
  
• This particular LCD is an unreliable PITA in 4-bit mode.  A number of hours were wasted fighting with it and the poor documentation.  If you use it, use it in 8-bit mode and yes you waste 4 pins on the NE64 to do so.  4-bit was never 100% reliable so I eventually patched the board to use it in 8-bit mode, which works perfectly.  I believe all the problems revolve around being unable to reset it after it is put into 4-bit mode (apart from doing a software controlled power-cycle, requiring external PFETs since the LCD is 5V in a 3.3V world) so if the board power comes up badly and the LCD needs a reset, or the NE64 resets (during debugging one does this all the time) sending the LCD another go-into-4-bit-mode as per normal startup essentially crashes it.  Crap.  No documentation about any of this from Lumex about any of this although it is clear it is a real problem.  Shame on you Lumex for errors and omissions in the datasheet - that wasn't even available on your website.  Your lack of QC cost me time and my client money.
  
• The 6-pin BDM (programmer/debugger) connection is a semi-standard; be sure to get the pins the right way around so you can hook up a programmer to it without hassle.  More below.
  

• MC9S12NE64.h is a monster (10K lines) header file with every bit of every register defined 9 different ways.  It is pretty useful actually.  Unfortunately Metrowerks has a non-standard extension whereby bitfields can be an unsigned char size.  ICC12 requires them to be unsigned int.  Many hundreds of lines have to change.  So, a little Windows console program was written to do this smartly.  Additionally, the IEVENT and IMASK structures are 16 bits long, and the ordering of the bits differ between Metrowerks and ICC12.  To save re-inventing the wheel, here is the modified MC9S12NE64.h, called MC9S12NE64_icc12.h The file is copyrighted, but since it is publicly available from Freescale I think its ok to provide this modified one here.
  
• How ISRs are declared.  Er, I don't have an example of the Metrowerks way anymore, but with ICC12 they are done like this.  I don't know if the nonpaged_function pragma is required or if that is implied by interrupt_handler, but to be safe I explicity declare all ISRs as nonpaged.  More about paging below.
  

• Unsupported or irrelevant Metrowerks #pragmas... Er, its been too long, don't remember.  Whatever they were, when ICC12 complains, fix or remove them.  Wasn't hard.
  
• Moving where RAM is and the stack pointer.  A few things need to happen:
• The NE64 puts the three ethernet buffers at 0x2000, and the arrays used for this space need to be defined like this:  (in ne64driver.c):

• Paged functions.  Unfortunately, with ICC12 you can either mark all functions as paged or not paged by default.  This means if the paged or non-paged memory gets full, you have to go explicity declare functions to be the other to fit in memory.  For chips with lots of paged mem and not much unpaged, this isn't a big deal.  But for the NE64 it is a drag since to get the full 64K you need 32K paged, and 32K non-paged.  What I did was have unpaged functions be default, and put all ISRs, functions called by function pointer, my _jsl_start() two-liner and main() in unpaged, and all the TCP/IP stuff and my more "finished" functions in paged memory.  I just kept adding functions to paged memory until it was full, but of course if you add significant code to a function it (or actually whatever was the last one put in paged memory) might not fit anymore - hence doing it to "finished" functions.  And by looking at the map file you can see what ICC12 put where to check your work and see how much space is left.  So for example at the top of ne64driver.h I have:

• Vector table.  As I recall ... it was awhile ago ... I took the vector table from the Freescale code and pretty much pasted it into the one supplied as a sample by imagecraft.  The last entry (reset vector) points to _jsl_start, given above, not __start.  The datasheet page 88 has them listed as to which one is for what.
  
• Project settings.  Oh so so important!  Here they are, for paged memory.  Listen up, this took awhile to get working.  Go to Projects -> Options:

• The RTI that produces a (nominal) 10msec tick, that OpenTCP uses for all timing.  To start with, the TIMERTIC setting is a little off, it should be 95, not 100.  The timers get updated in an ISR (RTI.c RealTimeInterrupt() calling decrement_timers() in timers.c), and it can be a little long - 130usec.  This caused problems in this design due to the way the LED panels connected to the leoplayer work.  If your design can't ignore interrupts for this long, something has to change.  I rewrote decrement_timers() to be a little faster and had it check for my condition that had to be handled quickly after each timer was decremented.  Alternatively, you could disable the timer during critical code - see RTI_Enable() and RTI_Disable() in RTI.c.  OpenTCP doesn't use them for anything critical, if one is late or even if a bunch are missing no problem.
  
• Unique MAC addresses.  They are supposed to be globally unique (as in, the whole world), so the IEEE has a procedure set up for handling this.  For small fry companies who can do with only 4096 different ones, go here: http://standards.ieee.org/regauth/oui/pilot-ind.html and bring $550 with you.  In reality, they only have to be unique to the subnet the board is on.  How you solve this is your decision, but be sure you don't have multiple boards with the same MAC address.  This causes no end of weird network flakyness.  It can be easy to accidentally have this happen in a lab environment, where there are a couple of prototypes built with various stages of code on them.
  
• 10 or 100Mbit default?  auto-negotiate on/off?  This is set in ne64config.h.  I had 10 & 100Mbit auto-negotiate working, then later discovered that at 10Mbit it would "link" but that was it.  Not sure what happened but for my uses this is a bug I'll probably never investigate.  Note that there is an errata involving auto-negotiation, see the link to the the Freescale errata .pdf at the bottom of the page.
  
• stack overflow.  It appears the NE64 has no hardware means to protect from this (maybe no microcontroller does...) and since the RAM in this project was relatively scarce (due to buffers needed for streaming out serial ports and reading from the SD) I was concerned about overwriting RAM with the stack.  So I did a little trick in main() where I initialize stuff:

• Important bugfix: The function NE64Receive() in ne64api.c has a problem.  This function is called when the ethernet hardware interrupts with a new data packet ready.  The function disables the interrupt for that buffer (A or B), then copies it to user RAM (the call to mENQUEUE()).  The problem is that mENQUEUE() can fail, under conditions of high packet reception and relatively slow processing of them in the main loop.  In that case the disabled interrupt is never enabled again.  After this happens for the first time packets start getting dropped left and right; after the second time it is dead.  I'm unclear on the exact mechanics to create this situation, but in a project Feb 2007 it took two people two days to fully diagnose this failure, which had never been seen before.  For a long time we all thought it was power supply problems.  An installation of 4 leoplayers would run fine for an hour then one would fail, but only when being driven from some custom software for the installation - not my test software.  The revised code is as follows: