General Technical MQX FAQ

[#1]

Q: I installed the MQX software release, but when I run a project, CodeWarrior can't find file x... 

A: Symptom
A project will build correctly, but when you run it, CodeWarrior asks you to locate files that it can't find.

Solution:
This problem is caused if you are running from a directory that is not the default directory that the installer placed the files. You just need to re-build the libraries.
To build all MQX libraries at once, the special mass-build project may be used. The project is located together with the user_config.h file in directory: <install_dir>/config/<board>/build_libs.mcp.

See the Release Notes for more details on building the libraries.

Q: What software tools do I need for the MQX 3.0.0 demos and lab tutorials?
A: The first release of Freescale MQX (3.0.0) requires CodeWarrior for ColdFire v7.1 Professional Edition (30-day evaluation available) to unlock the full potential of the demos and labs.

Is version 7.1 necessary?  Yes, 7.1 contains the necessary support for M5225EVB and M52259DEMOKIT.

What about CodeWarrior Special Edition?  Due to the code size limitation (<128k) of Special Edition, several lab demos will not compile/program.  These include MQX labs 3 and 4.  Also, Task Aware Debugging is not available in Special edition, therefore lab 5 is not possible.  Additionally, the targets which utilize the MRAM on the M52259EVB will not work.

What about CodeWarrior Basic and Standard Edition?

Task Aware Debugging is not available in Basic or Standard edition,therefore lab 5 is not possible.  Also, with Basic Edition the targets whichutilize the MRAM on the M52259EVB may not work.

Q: I'm having trouble establishing an Ethernet connection between my PC and the board.  What do I do?

A:

1) Hit the Reset button on the board after you plug in the cable. 

2) Wait a minute or two for your computer to connect.

Connect the board directly to your computer with an ethernet crossover cable.  You must wait a minute or two for your computer to try to aquire a network address.  Since you're no longer connected to your network the computer will eventually revert to an Auto IP address on the same subnet as board (169.254.x.x).

3) Disable your wireless router if you have one.

4) Disable proxy server settings in your web browser.

Notes:

When connected your computer might report limited or no connectivity, but it should still work.

Ping is disabled in release 3.0.0, so pinging the board from the computer will not work.

If all else fails, configure your IP address manually as instructed by the quick start guide.

Q: Can I modify the webpages used in the webserver lab?

A: Yes, there is a tool called MKTFS which can be used to convert web pages and images into a C array's, which are used by the MQX webserver.  Edit the webpages in the folder \demo\web_hvac\web_pages.  Then click on \demo\web_hvac\mktfs.bat.  The script will update the file tfs_data.c in the \demo\web_hvac folder.  When you recompile the hvac_web project and program it the new webpages will be loaded into memory.       
 

Q: Can I use my own USB Flash drive in the labs?

A: Yes, just copy over the files from the flash drive that is provided with the M52259EVB or M52259DEMOKIT.

Q: My USB Flash drive doesn’t work, what should I do?

A: Not all USB flash drive conform to the same specification and there are small differences between them that could cause some not to work.  It will say "Unable to open USB disk" at the terminal if the flash drive is not compatible.

We are working to expand compatibility to as many usb flash drive manufactures and models as possible.  If you encounter one that does not work please perform the following tasks.

Open up the project in <mqx install directory>/usb/host/examples/mass/msc_commands/codewarrior/
Load and run the project with the USB stick unattached. Then with the Terminal open and connected, plug in the non-functioning USB stick. A test will run automatically upon insertion of the USB stick.  The test will output useful information to the terminal that will help us.

Please provide us the output that this test generates, along with the exact make and model of the USB flash drive.  We will create a thread on the forums that you can post this to.

More info: Tested USB Stick

Q: What are tasks and how are they created?

A: Tasks share the same code space if they execute the same root function. A task always starts executing at the entry point of the root function even if the function is its creator’s root function. This is not the same behavior as fork() in UNIX.

Q:Do I always need at least one autostart task?

A: Yes. In an application, at least one autostart application task is required in order to start the application. In a multiprocessor application (the application can create tasks remotely), each image need not have an autostart application task; however, each image must include IPC Task as an autostart task in the task template list. If no application task is created on a processor, Idle Task runs.

Q:How much stack space should I give to various tasks in my application?

A: This is a really hard question to answer as the amount of stack space is extremely application specific. Different tasks will need varying amounts of stack space depending on the job they are trying to perform. We usually recommend starting all (or most) of tasks with plenty of stack memory (double or triple what you think they would need) and then later optimizing the system with TAD (Task Aware Debugging module).

Q: How do I dynamically alter the task stack size?

A: In a situation where a task runs a while and then blocks. In it's blocked state, it holds a couple of event connections which are used by interrupts, but otherwise needs no stack space. One would like to reduce the stack space being used by the task in its blocked state. How do you do this?
If the task is never going to run again, the user could _mem_free or better yet _mem_free_part on the stack. Using _mem_free_part will not cause some of our tools to complain.
In the task whose stack to be freed, the very first thing it does is to save the value of kernel_data->ACTIVE_PTR->MEMORY_RESOURCE_LIST;

/* Global var */
pointer stack_ptr;

{ /* In task */
KERNEL_DATA_STRUCT_PTR kernel_data = _mqx_get_kernel_data();

/* Do this very first thing */
stack_ptr = kernel_data->ACTIVE_PTR->MEMORY_RESOURCE_LIST;

/* Rest of code for task */
}

{ /* some other task*/
_mem_free(stack_ptr);
}

Q:How does MQX™ measure a timeslice? Is the timeslice absolute or relative? That is, if a task has a 10-ms timeslice and starts at time=0 ms, does it give up the processor at time=10 ms, or does it give up the processor after 10 ms of execution?

A: With a 10-ms timeslice, MQX counts the number of periodic timer interrupts that have occurred while the task is active. If the equivalent of 10 or more milliseconds have expired, MQX effectively runs _sched_yield() for the task. As a result, a task does not get 10 ms of linear time since higher-priority tasks will preempt it. Also, if the task calls a scheduling service (for example _task_block() or _sched_yield()), MQX sets the task’s timeslice counter back to zero. As with timeouts, the time that MQX allocates is plus or minus BSP_ALARM_RESOLUTION.

Q: How do I increase TCP performance?

A: Increase the size of the send and/or receive windows. Send data in multiples of the maximum segment size (MSS). Disable the Nagle algorithm.

Q: Is there a limit to the number of sockets that can be created with RTCS?

A: No. Sockets come from a partition with an infinite growth factor, so the number of sockets is limited only by the available memory on the board.

Q: Do I always need at least one autostart task?

A: Yes. In an application, at least one autostart application task is required in order to start the application. In a multiprocessor application (the application can create tasks remotely), each image need not have an autostart application task; however, each image must include IPC Task as an autostart task in the task template list. If no application task is created on a processor, Idle Task runs.

Q: Is it possible to rename a task after it is created?

A: Here's a function to get a pointer to the task's template struct where the task's name is stored. The function needs a couple of structures from mqx_prv.h.Namely, TD_STRUCT and KERNEL_DATA_STRUCT. You can add the function to your application or add it into MQX itself. If you are adding it to app, you will need to include "mqx_inc.h" and add mqx\source\include to the compiler's include search path.

/*FUNCTION*-------------------------------------------------------------------* * Function Name : _task_get_template_ptr* Returned Value : TASK_TEMPLATE_STRUCT_PTR* Comments :* Returns a pointer to the task's template structure* *END*----------------------------------------------------------------------*/TASK_TEMPLATE_STRUCT_PTR _task_get_template_ptr(_task_id){ /* Body */  KERNEL_DATA_STRUCT_PTR kernel_data;  TD_STRUCT_PTR td_ptr;  _GET_KERNEL_DATA(kernel_data);  if (task_id == MQX_NULL_TASK_ID) {    td_ptr = kernel_data->ACTIVE_PTR;  } else {    td_ptr = (TD_STRUCT_PTR)_task_get_td(_task_id);  } /* Endif */  if (td_ptr) {    return( td_ptr->TASK_TEMPLATE_PTR );  } /* Endif */  return( NULL );} /* Endbody */An example of how to use this function:/* Need prototype */extern TASK_TEMPLATE_STRUCT_PTR _task_get_template_ptr(_task_id);..../* Dynamically create the task */some_task_id = _task_create(..... );.../* Change name of some_task */template_ptr = _task_get_template_ptr(some_task_id);template_ptr->TASK_NAME = "new name";../* Change name of the current (active) task */template_ptr = _task_get_template_ptr(MQX_NULL_TASK_ID);template_ptr->TASK_NAME = "new name";

Q: How are exceptions or unhandled interrupts handled by MQX?

A: Basically, there are three ways of handling unhandled interrupts. They are mutually exclusive - in other words, you can only have one active at a time. You'd pick the one that best suits you for an application and use it:

1) _int_default_isr()
This is the default mode of handling interrupts - it simply blocks the offending task and sets its state to "Unhandled Interrupt Blocked"
2) _int_unexpected_isr()
This mode can be activated by calling _int_install_unexpected_isr() from the application. This will also block the offending task and set its state, but also will print some info on the console about who and what caused the unexpected exception
3) _int_exception_isr()
This is the most functional (but also most complex) of all the modes. It can be activated by calling _int_install_exception_isr().
Once this is installed, any unhandled interrupts will call _int_exception_isr(). It might help you understand the behavior of this function by actually looking at the code. It's in source\psp\\int_xcpt.c.

Here are the comments that define the behavior:
If an exception happens while a task is running, then:
if a task exception handler exists, it is executed, otherwise the task is aborted.
If an exception happens while an isr is running, then:
if an isr exception handler exists, it is executed, and the isr aborted otherwise the isr is aborted.
This is why you have to provide exception handlers.
For tasks, you install these with _task_set_exception_handler(). You would need to install a handler for each task in your system that you want handled (conceivably, this could be the same handler for all of them)
For ISRs, you install these with _int_set_exception_handler(). The parameter is the vector number of the interrupt your installing a handler for, not the exception vector itself (in other words, you'd install handlers for the vectors of ethernet, UARTs, timers, etc, not the divide by zero vector)
So, if you want to have full "handling" of all unhandled interrupts, you'll have to install handlers for all the tasks and ISRs that exist in your system. The handler itself could simply flag the error and allow the task to continue running. Other comments:
-Note that you shouldn't have to rebuild MQX libraries to change the modes - its simply done with a function call
-If one of the above three methods of handling unhandled interrupts does not suit you, you can also create your own handler to take whichever action you want and install it by calling _int_install_default_isr() with your own ISR as a parameter. This might be a simpler approach than using the exception handlers.

Q:How is DNS enabled?

A:Include DNS.H in the application. Call DNS_init() after calling RTCS_create(). Then insert the following code: DNS_First_Local_server[0].IP_ADDR = "my dns server's ip addr";

Q:Does MQX have memory protection?

A: No, not full memory protection (this allows us to run the same code on CPUs -- like DSPs -- without MMUs).

However, we do have a version of MQX with some level of MMU support. It allows simple memory protection between tasks and is available for some PowerPC derivatives.

Q:What happens if Idle Task blocks because of an exception?

A: If Idle Task blocks, System Task, which is really a system task descriptor that has no code, becomes the active task. System Task Descriptor sets up the interrupt stack; then re-enables interrupts. As a result, the application can continue to run.

Q:If more than one task "owns" a semaphore, and a priority boost is required, do all owning tasks have their priority raised, or just one?

A: The owning task with the highest priority gets boosted.

Q:In many RTCS examples we find "/* Enable IP forwarding */ _IP_forward = TRUE;". What does this do?

A: This enables forwarding of IP packets from one interface to another. If you have two Ethernet connections, this allows RTCS to route packets between the two interfaces.

Q:How do we setup Ethernet auto-negotiation?

A:Normally, this is done in the file enet_ini.c, located in the BSP (source/bsp), and normally autonegotiate is the default. Sometimes (but not always) the flag passed to enet_initialize is passed down to this function, and is used to select autonegotiate.

Q:How do I bind a UDP socket to a specific IP address and have it receive broadcast packets?

A: RTCS does not allow UDP sockets bound to a specific IP address to receive broadcast packets. You can get around this by binding using INADDR_ANY, however in this case you may receive extra traffic you do not wish to receive (e.g. there are two Ethernet interfaces on the board). RTCS emulates BSD and we consider this to be an appropriate behavior.

Q:If there is no file system on an MQX target running RTCS how can I use FTP to upload and download files to it? Say I have a datafile on a PC that I want to be able to upload over ethernet to my MQX app as well as later download it. Can I do that without a file system ... say get a file line by line and interpret it? Likewise output it line by line?

A: Yes, this is possible, but it requires that you do some work to design the "device" to handle this.

Without a file system, the FTP server can communicate with any MQX device - these are usually identified by a string such as "ttya:", "ittyb:", "flash:", etc. They can either by installed by the application or the BSP. The ones previously mentioned are installed by the BSP, but the RTCS apps example (apps.c) also installs two new devices called null: and kmem:

In order to communicate with these devices via FTP, on the PC you would do the following:
Type: ftp my_ip_address
(prompt for user name) - hit Enter
To put a file to the server, type: put localfilename remotedevice
For example: put test.txt ttya:

This will send the contents of test.txt from the PC to the target - the ttya: device will put it to the screen. If you replace ttya: with null: in the apps example, it will simply discard everything it reads.
To get a file from the server, type: get remotedevice localfilename
For example: get kmem: coredump

This will store the contents of kernel data into a file on the PC
Now, you can design your own device to do something similar.

I would recommend looking at the source\io\io_mem and source\io\io_null devices to use as templates. Basically, you need to code an install, open, close, read, write and ioctl function for your device. When the FTP server calls fopen(), read() and write() on your device, it will access these functions. It would be up to you to decide what to do with the data once it arrives in your functions, but you could process it and also store it for later use.

Note that both the RTCS TFTP and FTP *servers* use the same structure. The FTP client uses device names to access the data to send. However, the TFTP client API decodes the data without using a device.

Q: Is there a documented API for the IP layer?

A:This interface isn't documented since it's assumed that the user won't usually access it. There are four functions: IP_init(), IP_send() (for outgoing packets), IP_send_if() and IP_service() (for incoming packets). IP_send_if() is used only by BOOTP/DHCP to send a limited broadcast with a source IP address of 0.0.0.0.

Q: How is the timer used on MQX?

A: On ColdFires, timer PIT is used as system timer for scheduler (dispatcher) and for time counting.

Q: How to free memory after use mem_alloc?

A: Use mem_free