ARM APIs: application.c

The default workspace template includes three 'C' language files. main.c contains initialization and main event loop code - not really intended to be modified by a user, it just makes building an image more convenient. parse.c contains the command line parser - it can be modified by the user for debugging purposes. Since there's no command line when running from flash, the parser is not used in the standalone or rom variants.

The third file, application.c, is where the application programmer starts adding code. There are two primary functions: app_Init() and app_Main(). At least one of the primary functions must have some user code in order to do useful work. In addition, there are three secondary functions: app_RunCommand(), app_PrintMenu(), and app_FIQISR(). Use of these functions is optional. See details below.

NOTES:

app_Main() must return i.e. do not put infinite loops or blocking functions in application code. The kernel calls app_Main() within an event loop that does other kernel-specific tasks, like idling the CPU to save power. If you loop in app_Main(), the kernel can't do these other tasks. There is one exception: if, for debugging purposes, you need to do console or file I/O, it's OK to block on a read. systest_RunCommand() does this for command entry.

ALL functions in application.c are callbacks i.e. they are called by the operating system, not the user. For instance, app_Init() is called at system startup while app_Main() is called periodically to do whatever work may be queued up.

You do NOT have to put all app code in application.c. If you want to create another 'C' file and add it to the project, in the ARM Project Manager 1) highlight Sources, 2) pull down the Project menu, and 3) select 'Add to Sources'.

If a Xilinx program is used AND any Xilinx library blocks that require port connections to the I/O block are used AND support for that Xilinx library block from an ARM library will be used, the application programmer must tell the operating system which port is connected to which library block. An interface is provided for this: xilinx_SetPortAssignment(int service, int port). Call this function once in app_Init() for each library block with a port connection, using a global symbolic constant for service. See Xilinx Port Assignment Labels below for the constants. For instance, if you use port 5 for the Bluetooth control interface, call:

xilinx_SetPortAssignment(PA_RADIO_CNTL, 5);

in app_Init().

FUNCTIONS
(see application.c for more info)

void app_Init(InitOpts *opts); Any initialization code goes in here. This function is called once at system start-up. Common usage is for data structure initialization, Xilinx programming, etc.

void app_Main(InitOpts *opts); All user code except for initialization goes in here. The code can be in-line or calls into other 'C' files, either in the user project of one of the system libraries.

void app_FIQISR(void) Put FIQ interrupt service routing code in this function. Code must be in-line (no function calls). Use macros instead. If you have to call functions, use an IRQ. IRQ interrupt service routines (ISRs, or handlers) are per device. See the interrupt documentation. There is ONLY ONE User-level FIQ ISR.

void app_RunCommand(InitOpts *opts, char *arglist) If you are using systest_RunCommand(), modify this function to add custom commands. arglist is a pointer to the command string entered at the main systest_RunCommand() prompt.

void app_PrintMenu(FILE *fh) This is a companion function to app_RunCommand(). If you want to add a line to the systest_RunCommand() menu, add it here. This function is called by systest_RunCommand() at entry, so custom commands will be displayed at the top of the default menu. fh is a file handle used when the menu is written to a file for printing. You should use fprintf(fh,...) for creating output.

common opts is a structure pointer to a set of global parameters, primarily command-line arguments such as ID override. You probably won't use it much.

For information about systest_RunCommand(), go here.

XILINX PORT ASSIGNMENT LABELS

Label Direction ARM
Library Xilinx
Library Block(s) Purpose

PA_RADIO_CNTL down armos
bluetooth, proxim
ARM control interface.

PA_RADIO_DATA down Programming data from ARM (nearly obsolete).

PA_RADIO_STATUS up Status

PA_RSSI_DATA up channels Raw RSSI value.

PA_MAC_CNTL down channels TDMA Control e.g. slot ack/nack, basestation/remote selection.

PA_MAC_STATUS up Slot set database control e.g. add Tx/Rx slot, remove slot, clear all slots.

PA_MAC_DB down . Block status/debug signals.

PA_DATAPATH_CNTL down .
datapath
Control e.g. Tx/Rx enable, use CRC.

PA_DATAPATH_DATA_DN down channels Main 32-bit downlink (Tx) data stream.

PA_DATAPATH_STATUS up Block status e.g. FIFO state.

PA_DATAPATH_DATA_UP up Main 32-bit uplink (Rx) data stream.

PA_RX_COMPLETE down channels . Completed Rx packet notification. Can be used directly by a custom Xilinx block or routed back to the ARM via IRQ.

PA_DATASTREAM_HI down .
datastream
High 32 bits of the 64 bit programmable free-running serial stream.

PA_DATASTREAM_LO down . Low 32 bits of the 64 bit programmable free-running serial stream.

Maintainer: Fred Burghardt
Modified: July 23, 2001

FUNCTIONS (see application.c for more info)
void app_Init(InitOpts **opts*);	Any initialization code goes in here. This function is called once at system start-up. Common usage is for data structure initialization, Xilinx programming, etc.
void app_Main(InitOpts **opts*);	All user code except for initialization goes in here. The code can be in-line or calls into other 'C' files, either in the user project of one of the system libraries.
void app_FIQISR(void)	Put FIQ interrupt service routing code in this function. Code must be in-line (no function calls). Use macros instead. If you have to call functions, use an IRQ. IRQ interrupt service routines (ISRs, or handlers) are per device. See the interrupt documentation. There is ONLY ONE User-level FIQ ISR.
void app_RunCommand(InitOpts *opts, char *arglist)	If you are using systest_RunCommand(), modify this function to add custom commands. arglist is a pointer to the command string entered at the main systest_RunCommand() prompt.
void app_PrintMenu(FILE *fh)	This is a companion function to app_RunCommand(). If you want to add a line to the systest_RunCommand() menu, add it here. This function is called by systest_RunCommand() at entry, so custom commands will be displayed at the top of the default menu. fh is a file handle used when the menu is written to a file for printing. You should use fprintf(fh,...) for creating output.
common	opts is a structure pointer to a set of global parameters, primarily command-line arguments such as ID override. You probably won't use it much.

XILINX PORT ASSIGNMENT LABELS
Label	Direction	ARM Library	Xilinx Library Block(s)	Purpose
PA_RADIO_CNTL	down	armos	bluetooth, proxim	ARM control interface.
PA_RADIO_DATA	down			Programming data from ARM (nearly obsolete).
PA_RADIO_STATUS	up			Status
PA_RSSI_DATA	up	channels		Raw RSSI value.
PA_MAC_CNTL	down	channels	TDMA	Control e.g. slot ack/nack, basestation/remote selection.
PA_MAC_STATUS	up	channels		Slot set database control e.g. add Tx/Rx slot, remove slot, clear all slots.
PA_MAC_DB	down	.		Block status/debug signals.
PA_DATAPATH_CNTL	down	.	datapath	Control e.g. Tx/Rx enable, use CRC.
PA_DATAPATH_DATA_DN	down	channels		Main 32-bit downlink (Tx) data stream.
PA_DATAPATH_STATUS	up			Block status e.g. FIFO state.
PA_DATAPATH_DATA_UP	up			Main 32-bit uplink (Rx) data stream.
PA_RX_COMPLETE	down	channels	.	Completed Rx packet notification. Can be used directly by a custom Xilinx block or routed back to the ARM via IRQ.
PA_DATASTREAM_HI	down	.	datastream	High 32 bits of the 64 bit programmable free-running serial stream.
PA_DATASTREAM_LO	down	.	datastream	Low 32 bits of the 64 bit programmable free-running serial stream.