|
|
|
PIC24 MCU and dsPIC® DSC RTOS ports
[RTOS Ports]
This page presents the FreeRTOS port and demo application for
Microchip's 16bit microcontroller offerings.
Two demo applications are provided, one preconfigured for the PIC24FJ128GA010,
and one for the dsPIC33FJ256GP710.
Both demos are targeted at the Explorer16 Development Board (instructions are provided should you wish to use an alternative development board)
and utilise the MPLAB® C30 compiler
and MPLAB ICD 2 debug/programming interface.
The V4.3.0 (and higher) FreeRTOS download includes the following modifications to the dsPIC and PIC24 ports and demos:
- The demo projects are now configured to build using V3.0 of the MPLAB C30 compiler.
- The configuration macro configKERNEL_INTERRUPT_PRIORITY has been introduced to permit much more flexible interrupt management. Further details are provided in the "Configuration and Usage Details" section
of this page.
- The demo applications have been updated to make use of the Explorer16 LCD.
IMPORTANT! Notes on using the PIC24 and dsPIC DSC ports
Please read all the following points before using this RTOS port.
- Source Code Organization
- The Demo Application
- Configuration and Usage Details
See also the FAQ My application does not run, what could be wrong?
Source Code Organization
The FreeRTOS download contains the source code for all the FreeRTOS ports so contains many more files than used by this demo.
See the Source Code Organization section for a description of the
downloaded files and information on creating a new project.
The MPLAB demo application workspace for the PIC24 port is called RTOSDemo.mcw and can be located in the FreeRTOS/Demo/PIC24_MPLAB directory.
The MPLAB demo application workspace for the dsPIC DSC port is also called RTOSDemo.mcw and can be located in the FreeRTOS/Demo/dsPIC_MPLAB directory.
The Demo Application
This section relates to both the PIC24 and dsPIC DSC demo applications.
Demo application hardware setup
All the Explorer 16 jumpers can remain in their default positions - in particular, JP2 should be fitted to ensure correct operation of the LEDs.
The demo application includes tasks that send and receive characters over UART2. The characters sent by one task are received by another - with an error condition
being flagged should any characters be missed or received out of order. A loopback connector is required on the Explorer16 9way D socket for this mechanism to
operation (pins 2 and 3 the socket should be connected together). The internal loopback mode of the UART itself is not used by default.
The demo application uses the LEDs built onto the prototyping board so no other hardware setup is required.
Functionality
The demo application creates fourteen tasks (including the idle task), five co-routines, and a high frequency interrupt test. When executing correctly the demo will behave as follows:
- LEDs marked D3 to D7 are under control of the 'flash' co-routines. Each will flash at a constant frequency, with LED D3 being
the fastest and LED D7 being the slowest. This provides a basic example of how co-routines can be mixed with tasks.
- LED D9 will toggle each time a character is transmitted on the serial port. The frequency is such that you cannot distinguish the individual toggles between
characters, although the spacing between complete message transfers can be viewed.
- LED D10 will flash each time a character is received and validated on the serial port (though the loopback connector). Again the frequency is too
fast to distinguish the individual toggles.
- Most of the tasks do not update an LED so have no visible indication that they are operating correctly.
Therefore a 'Check' task is created whose job it is to ensure that no errors have been detected in any of the
other tasks or co-routines. The check task monitors the system operation every 3 seconds then writes a PASS or FAIL message to the LCD. Any failures are
latched, and the message displayed indicates in which task the failure was detected (this functionality can be tested by removing the loopback connector while the demo is executing).
The PASS message is a time measurement in nano seconds, as described in the next bullet point.
-
A high frequency periodic interrupt is generated
using a free running timer to demonstrate the use of the
configKERNEL_INTERRUPT_PRIORITY configuration constant. The interrupt
service routine measures the number of processor clocks that occur between
each interrupt - and in so doing measures the jitter in the interrupt
timing. The maximum measured jitter time is latched in the usMaxJitter
variable, and displayed on the LCD by the 'Check' task as just described. The interrupt frequency is set to 20KHz.
This test demonstrates how the RTOS kernel can be configured such that is has no impact on the latency of interrupt service routines.
- The application also demonstrates the use of a 'gatekeeper' task, in this case an LCD gatekeeper. The LCD task is the only task that
is permitted to access the LCD directly. Other tasks wishing to write a
message to the LCD send the message on a queue to the LCD task instead of
accessing the LCD themselves. The LCD task just blocks on the queue waiting
for messages - waking and displaying the messages as they arrive.
Building and executing the demo application
These instructions assume you have MPLAB and the MPLAB C30 compiler correctly installed on your host computer.
To build the application:
- Open the demo application workspace from within the MPLAB IDE.
- From the 'Project' menu within the IDE, select 'Build Options', then 'Project'. The project options dialogue box will open.
- Edit the paths in the 'Include Path' text box to be correct for your FreeRTOS installation. For example, if you have installed the
FreeRTOS source code in a directory called d:\FreeRTOS then use this path in place of the default c:\Dev\FreeRTOS.
 The Include Path options, which include absolute paths to the required directories
- From the 'Project' menu, select 'Build All'. The project should build with no errors or warnings.
To run the application in the MPLAB simulator:
- From the 'Debugger menu within the MPLAB IDE, select 'Select Tool', then 'MPLAB SIM'.
- Set a break point on the first instruction within the main() function (contained within main.c).
- From the 'Debugger' menu, select 'Run'. The application will start executing, stopping when the break point is reached. The application can then
be manipulated using the standard debugger commands.
When executing within the simulator, the standard ComTest receive task will not receive any characters (there is no loopback connector), causing the
'check' task to detect an error within the communications test tasks.
To debug the application on the Explorer 16 using the ICD 2 interface:
- Connect the ICD 2 to the Explorer 16 development board as described in the Explorer 16 manual.
- From the 'Debugger' menu within the MPLAB IDE, select 'Select Tool', then 'MPLAB ICD 2'.
- From the 'Debugger' menu within the MPLAB IDE, select 'Connect'. This will generate a connection between MPLAB and the ICD 2 device.
- Again from the 'Debugger' menu, select 'Program' to program the demo application and debugger stub into the microcontroller flash memory.
- Set a break point on the first instruction within the main() function (contained within main.c).
- From the 'Debugger' menu, select 'Run'. The application will start executing, stopping when the break point is reached. The application can then
be manipulated using the standard debugger commands.
To run the application stand alone from the microcontroller flash:
- Connect the ICD 2 to the Explorer 16 development board as described in the Explorer 16 manual.
- From the 'Programmer' menu within the MPLAB IDE, select 'Select Programmer', then 'MPLAB ICD 2'.
- Again from the 'Programmer' menu within the MPLAB IDE, select 'Program'. This will program the demo application into the microcontroller flash.
- Remove power from the Explorer 16 board, then remove the ICD 2 interface cable.
- Finally, apply power again to start the application executing.
RTOS port specific configuration
Configuration items specific to this port are contained in FreeRTOS/Demo/[PIC24_MPLAB | dsPIC_MPLAB]/FreeRTOSConfig.h. The
constants defined in this file can be edited to suit your application. In particular -
- configTICK_RATE_HZ
This sets the frequency of the RTOS tick. The supplied value of 1000Hz is useful for testing the RTOS kernel functionality but is faster
than most applications require. Lowering this value will improve efficiency.
- configKERNEL_INTERRUPT_PRIORITY
This sets the interrupt priority used by the RTOS kernel. The RTOS kernel should use a low interrupt priority, allowing higher priority interrupts
to be unaffected by the RTOS kernel entering critical sections. Instead of critical sections globally disabling interrupts, they only disable
interrupts that are below the RTOS kernel interrupt priority.
This permits very flexible interrupt handling:
- At the RTOS kernel priority level interrupt handling 'tasks' can be written and prioritised as per any other task in the system.
These are tasks that are woken by an interrupt. The interrupt service routine (ISR) itself should be written to be as short as
it possibly can be - it just grabs the data then wakes the high priority handler task. The ISR then returns directly into the woken
handler task - so interrupt processing is contiguous in time just as if it were all done in the ISR itself. The benefit of this is
that all interrupts remain enabled while the handler task executes.
- ISR's running above the RTOS kernel priority are never masked out by the RTOS kernel itself, so their responsiveness is not effected by
the RTOS kernel functionality. However, such ISR's cannot use the FreeRTOS API functions. The fast timer interrupt test within this demo
demonstrates this configuration.
Unfortunately, due to limitations in the GCC inline assembler, modifications
to this value will necessitate a small update to the port source code with respect to the interrupt mask value (accessed by inline assembler instructions).
A #error directive has been included in the port source code to indicate the location of the required update, and provide instruction on the update that is required.
Each port #defines 'BaseType_t' to equal the most efficient data type for that processor. This port defines
BaseType_t to be of type short.
Note that vPortEndScheduler() has not been implemented.
Device specific configuration
The MPLAB C30 header file for the specific target microcontroller being used should be included at the top of FreeRTOSConfig.h.
The MPLAB project must define either MPLAB_PIC24_PORT or MPLAB_DSPIC_PORT to build for a PIC24 or dsPIC DSC target respectively. The 'Macro Definitions' section
of the MPLAB C30 build options provides a convenient place for this definition.
Interrupt service routines
Interrupt service routines that cannot cause a context switch have no special requirements and can be written as per the compiler documentation.
Interrupt service routines that can cause a context switch must execute with priority portKERNEL_INTERRUPT_PRIORITY, and only call taskYIELD() at the very
end of the service routine after the interrupt source has been cleared. See the file serial.c included in the demo application for an example.
Critical sections
Exiting a critical section will always set the interrupt priority mask to zero (all interrupts enabled), no matter what its level when the critical section
was entered. FreeRTOS API functions themselves will use critical sections.
Shadow registers
The shadow registers are not saved as part of the task context.
PSV bit handling
The PSV bit within CORCON register must be set identically for every task. If it is necessary to change the default bit setting this must be done prior to
any tasks being created.
Switching between the pre-emptive and co-operative RTOS kernels
Set the definition configUSE_PREEMPTION within FreeRTOS/Demo/[PIC24_MPLAB | dsPIC_MPLAB]/FreeRTOSConfig.h to 1 to use pre-emption or 0
to use co-operative. The demo application will only execute correctly with configUSE_PREEMPTION set to 0 if configIDLE_SHOULD_YIELD is set to 1.
Compiler options
As with all the ports, it is essential that the correct compiler options are used. The best way to ensure this is to base your
application on the provided demo application files.
Memory allocation
Source/Portable/MemMang/heap_1.c is included in the PIC24 and dsPIC DSC demo application projects to provide the memory
allocation required by the RTOS kernel.
Please refer to the Memory Management section of the API documentation for
full information.
Serial port driver
It should also be noted that the serial drivers are written to test some of the real time kernel features - and they are not
intended to represent an optimized solution.
Copyright (C) Amazon Web Services, Inc. or its affiliates. All rights reserved.
|
