pic24_util.h File Reference

Go to the source code of this file.

Defines

#define SLEEP()   Sleep()
#define IDLE()   Idle()
#define CLRWDT()   ClrWdt()
#define NOP()   Nop()
#define ENABLEWDT()   _SWDTEN = 1
#define DISABLEWDT()   _SWDTEN = 0
#define REPORT_ERROR(msg)   reportError(ERROR_FILE_LINE(msg))
#define HELLO_MSG   "\n" __FILE__ ", built on " __DATE__ " at " __TIME__ "\n"
#define USE_HEARTBEAT   1
#define HB_LED   _LATB15
#define CONFIG_HB_LED()   CONFIG_RB15_AS_DIG_OD_OUTPUT()
Chip identification
These routines assist in identifying the device and revision of the PIC in use. See checkDeviceAndRevision() for a usage example.

#define DEV_ID_LOCATION   0xFF0000
#define REVISION_LOCATION   0xFF0002
#define DEV_ID   0x00080a
#define DEV_ID_STR   "PIC24HJ12GP201"
#define EXPECTED_REVISION1   0x003001
#define EXPECTED_REVISION1_STR   "A2"
#define EXPECTED_REVISION2   0x003002
#define EXPECTED_REVISION2_STR   "A3"
#define EXPECTED_REVISION3   0x003003
#define EXPECTED_REVISION3_STR   "A4"
Peripheral identification
#define NUM_UART_MODS   1
#define NUM_I2C_MODS   1
#define NUM_SPI_MODS   1
#define NUM_ECAN_MODS   1
Bitfield to struct conversion
Given a bitfield struct representing an SFR, convert this to a word (uint16) or to the high and low bytes (uint8) of that word. Note: though this looks ugly, it introduces no unexpected compiler overhead at -O1. See u16_INTTREGlast for an example.

#define BITS2WORD(sfrBitfield)   ( *((uint16*) &sfrBitfield) )
 Convert a bitfield to a word (uint16).
#define BITS2BYTEL(sfrBitfield)   ( ((uint8*) &sfrBitfield)[0] )
 Return the low byte (as a uint8) of a bitfield.
#define BITS2BYTEH(sfrBitfield)   ( ((uint8*) &sfrBitfield)[1] )
 Return the high byte (as a uint8) of a bitfield.

Functions

void reportError (const char *szErrorMessage)
uint32 readProgramMemory (uint32 u32_address)
void checkDeviceAndRevision (void)
void checkOscOption (void)
void printResetCause (void)
void configPinsForLowPower (void)
void configBasic (const char *psz_helloMsg)
uint32 roundFloatToUint32 (float f_x)
uint16 roundFloatToUint16 (float f_x)
void configHeartbeat (void)
void doHeartbeat (void)
void toggleHeartbeat (void)

Variables

_PERSISTENT char * sz_lastTimeoutError
uint32 u32_heartbeatCount


Detailed Description

This file contains miscellaneous functions that that do not fall under any particular category. See pic24_util.c for details on how these functions were implemented.

Definition in file pic24_util.h.


Define Documentation

 
#define CONFIG_HB_LED (  )     CONFIG_RB15_AS_DIG_OD_OUTPUT()

Define a config function for the heartbeat pin.

Definition at line 922 of file pic24_util.h.

#define DEV_ID   0x00080a

The device ID for this chip, located in program memory at DEV_ID_LOCATION.

Definition at line 62 of file pic24_util.h.

#define DEV_ID_LOCATION   0xFF0000

The location in program memory of the device ID. Revision information is found in the Silicon Errata sheet for the device. The Device ID is contained in the datasheet for the target device.

Definition at line 53 of file pic24_util.h.

#define DEV_ID_STR   "PIC24HJ12GP201"

A string to identify this chip, printed by checkDeviceAndRevision().

Definition at line 66 of file pic24_util.h.

#define EXPECTED_REVISION1   0x003001

A revision for this device, located in program memory at REVISION_LOCATION. Additional revisions can be defined as EXPECTED_REVISIONn, where n = 1..5.

Definition at line 71 of file pic24_util.h.

#define EXPECTED_REVISION1_STR   "A2"

A string to accompany this revision, printed by checkDeviceAndRevision(). Additional revision strings can be defined as EXPECTED_REVISIONn, where n = 1..5.

Definition at line 76 of file pic24_util.h.

#define HB_LED   _LATB15

Choose a pin for the heartbeat. If USE_HEARTBEAT is false, the heartbeat is disabled.

Definition at line 920 of file pic24_util.h.

#define NUM_ECAN_MODS   1

Define the number of ECAN modules supported by this chip. See NUM_UART_MODS for details on this methodology.

Definition at line 848 of file pic24_util.h.

#define NUM_I2C_MODS   1

Define the number of I2C modules supported by this chip. See NUM_UART_MODS for details on this methodology.

Definition at line 826 of file pic24_util.h.

#define NUM_SPI_MODS   1

Define the number of SPI modules supported by this chip. See NUM_UART_MODS for details on this methodology.

Definition at line 837 of file pic24_util.h.

#define NUM_UART_MODS   1

Define the number of UART modules supported by this chip. NOTE: this only works when testing #defines, not testing variable. So, don't test UxSTA; instead, test _UxRXIF which is uniquely defined for each UART. (Idea taken from the C30 peripheral library, in uart.h.)

Definition at line 815 of file pic24_util.h.

#define REPORT_ERROR ( msg   )     reportError(ERROR_FILE_LINE(msg))

Report an error on reset via reportError, also printing the file and line number where this macro was called via a call to ERROR_FILE_LINE.

Parameters:
msg Error message to report

Definition at line 875 of file pic24_util.h.

#define REVISION_LOCATION   0xFF0002

The location in program memory of the revision.

Definition at line 55 of file pic24_util.h.

 
#define SLEEP (  )     Sleep()

Todo:
Document this section.

Definition at line 792 of file pic24_util.h.

#define USE_HEARTBEAT   1

Todo:
Putting this is a group causes the functions not to be displayed by Doxygen 1.5.8!
If this macro is true, heartbeat functionality is enabled. If false, heartbeat is disabled.

Definition at line 913 of file pic24_util.h.


Function Documentation

void checkDeviceAndRevision ( void   ) 

Determines the device and revision of the PIC this program is executing on. This information is then output via the default UART. A warning message is issued if this program was not compiled for the chip it is running on.

Definition at line 192 of file pic24_util.c.

void checkOscOption ( void   ) 

Reports the oscillator currently in use to the default serial port.

Definition at line 267 of file pic24_util.c.

void configBasic ( const char *  sz_helloMsg  ) 

Perform basic chip configuration:

  • Configure the heartbeat
  • Configure the clock
  • Configure UART1
  • Determine and print the cause of reset
  • Print a hello message.

Parameters:
sz_helloMsg Hello message to print.

Definition at line 493 of file pic24_util.c.

void configHeartbeat ( void   ) 

Configures a GPIO pin for use with the heartbeat and sets up the heartbeat counter.

See also:
doHeartbeat

Definition at line 78 of file pic24_util.c.

void configPinsForLowPower ( void   ) 

This function puts the PIC24 in low-power mode by:

  • Configuring all digital I/O pins as inputs
  • Configuring all analog I/O pins shared with digital I/O pins to be digital only
  • Enables pullups on all pins not used by the oscillator.

WARNING: if pullups are enabled on pins used by the oscillator, the clock typically stops running. Currently, this code works for demo purposes with the FRC oscillator when used in the reset.c program. It *should* also work with primary and secondary oscillators, using conditional compiles in the code.

Definition at line 479 of file pic24_util.c.

void doHeartbeat ( void   ) 

This heartbeat function should be called repeatedly in any sort of blocking wait loop. It will periodically toggle an LED after u32_heartbeatMax increments.

Definition at line 94 of file pic24_util.c.

void printResetCause ( void   ) 

Determines and prints the cause of a CPU reset. This should be called when the chip first starts up. For an example, see the configBasic function.

Definition at line 314 of file pic24_util.c.

uint32 readProgramMemory ( uint32  u32_address  ) 

Reads a 24-bit program memory word at the given address.

Parameters:
u32_address Address of program memory to read.
Returns:
The 24-bit program memory word at u32_address. The upper 8 bits are 0.

Definition at line 180 of file pic24_util.c.

void reportError ( const char *  sz_errorMessage  ) 

Report a critical error by recording a message in sz_lastError then resetting the chip, assuming hat printResetCause will be called during chip initialization.

Parameters:
sz_errorMessage Error message to report.
See also:
REPORT_ERROR

Definition at line 167 of file pic24_util.c.

uint16 roundFloatToUint16 ( float  f_x  ) 

Round a floating-point number to the nearest integer.

Parameters:
f_x Floating-point value to round
Returns:
The nearest uint32 to f_x.

Definition at line 515 of file pic24_util.c.

uint32 roundFloatToUint32 ( float  f_x  ) 

Round a floating-point number to the nearest integer.

Parameters:
f_x Floating-point value to round
Returns:
The nearest uint32 to f_x.

Definition at line 506 of file pic24_util.c.

void toggleHeartbeat ( void   ) 

A function which toggles the hearbeat LED.

See also:
doHeartbeat

Definition at line 106 of file pic24_util.c.


Variable Documentation

_PERSISTENT char* sz_lastTimeoutError

Persistent storage for a timeout error, to be reported if a watchdog reset occurs.

Definition at line 120 of file pic24_util.c.

The current heartbeat count. When this value reaches u32_heartbeatMax, the heatbeat LED is toggled by doHeartbeat().

See also:
doHeartbeat

Definition at line 67 of file pic24_util.c.


Generated on Mon Oct 18 07:40:48 2010 for Python-on-a-chip by  doxygen 1.5.9