Learn more about xPC Target

Adding Interrupt Support

On this page…
Introduction Guidelines for Creating Interrupt Functions Filling in the Driver board Structure

Introduction

To add interrupt handling for a custom driver, you must create

• A descriptor file to connect a board type to the functions needed to start, handle, and stop interrupts

• A C file to implement these functions

Include the following functions. See Hook Function Prototypes — Alphabetical List for the prototype details.

Function	Description
PreHook	Runs just before either a function-call subsystem or entire model is called. Program this function to acknowledge the interrupt and cause the board to stop issuing the interrupt signal.
PostHook	Runs after return from function call on interrupt, and before model execution. It is typically not used.
Start	Runs as the last item when starting a model, just before the model runs. It is typically used to turn on interrupt generation. Program this function to enable interrupts on the board and start any action.
Stop	Runs at the beginning of a stop request, before any mdlTerminate entries for any block in the model runs. It is typically used to turn off interrupt generation. Program this function to disable interrupts from the board and stop any action. This is the first action called, when a target application stops executing.

Note   You must use the Stop function to turn off interrupts if you have turned them on in the Start function. In this way, the stop and start functions should cancel each other.

To add interrupts for your custom driver, use the following general steps:

1. Create a hook file in the following directory:

   matlabroot\toolbox\rtw\targets\xpc\target\build\
   xpcblocks\thirdpartydrivers

   Hook files are C files (.c). For example, look at files in matlabroot\toolbox\rtw\targets\xpc\target\build\src, such as xpc6804hooks.c.

2. Name the hook file something like:

   your_company_name_board_hook.c

3. As necessary, create the interrupt functions the PreHook, PostHook, Start, and Stop functions and add them to the hook file. See Guidelines for Creating Interrupt Functions for information on how to create these functions.

4. Copy the file sample_int.m to a unique file name in the following directory:

   matlabroot\toolbox\rtw\targets\xpc\target\build\
   xpcblocks\thirdpartydrivers

   For example:

   your_company_name_int.m

   The xPC Target software searches in this directory for file names that end with _int.m and looks for board interrupt descriptions.

5. Open and edit the following file:

   matlabroot\toolbox\rtw\targets\xpc\target\build\
   xpcblocks\thirdpartydrivers\your_company_name_int.m

   Add to this file a board structure for each xPC Target supported board for which interrupt functions have been written. See Filling in the Driver board Structure for a description of how to fill in a board structure.

6. Save and close the file.

7. At the MATLAB Command Window, type:

   rehash toolbox

8. Restart the MATLAB interface to update the Async IRQ Source block and Configuration Parameters dialogs.

Back to Top

Guidelines for Creating Interrupt Functions

xPC Target interrupt functions have predefined purposes and typically follow a particular order. This section describes the guidelines on creating interrupt functions. See Hook Function Prototypes — Alphabetical List for the prototypes for these functions.

To prepare for the creation of the hook file, examine the existing xPC Target hook files (matlabroot\toolbox\rtw\targets\xpc\target\build\src) and copy and modify one that is the same board type, PCI or ISA, as the board for which you are creating a custom driver. For example, xpc6804hooks.c is for an ISA board. Place your new file in

matlabroot\toolbox\rtw\targets\xpc\target\build\
xpcblocks\thirdpartydrivers\

When modifying an existing hook file:

• Change the names of all of the functions to match those you have selected for your board.

• Do not change the function signatures.

• Do not remove the __cdecl string.

• The PreHook and PostHook functions run with interrupts disabled. Do not change the interrupt status in these functions.

When writing the interrupt functions, note the following:

• When an interrupt occurs, the kernel calls the PreHook function.

  Note   This function is run with interrupts disabled. If this function cannot turn off the interrupt, an infinite loop will occur because the interrupt service routine (ISR) will continuously call the PreHook function.

• Because the PostHook function has limited use, you most likely do not need to define this function. Set this function to 'NULL' if you do not need it.

• The generated code calls the Start function during the startup phase of model execution as the last action, after the model has called all mdlStart routines.

  This function is typically used to enable interrupts from the board. The target application is ready to accept interrupts a few microseconds after this function is called. Do not try to enable interrupts from the board mdlStart function.

• When a target application stops executing, the generated code calls the Stop function first. Disable interrupts from the board in this function.

Back to Top

Filling in the Driver board Structure

This section describes how to fill in a driver board structure, element by element.

• Depending on the bus type of your board, select a board structure of an existing board that has the same bus type. The information passed to the functions is slightly different for an ISA board or a PCI board. You will use this structure as a template for your own board entry. The following is a structure for an ISA or PC/104 device:

  board.name = 'RTD_DM6804';
  board.VendorId = -1;
  board.DeviceId = 1;
  board.SubVendorId = -1;
  board.SubDeviceId = -1;
  board.PreHookFunction = 'xpc6804';
  board.PostHookFunction = 'NULL';
  board.HookIncludeFile = 'xpc6804hooks';
  board.StartFunction = 'xpc6804start';
  board.StopFunction = 'xpc6804stop';

  The following is a structure for a PCI device:

  board.name = 'General Standards 24DSI12';
  board.VendorId = hex2dec('10b5');
  board.DeviceId = hex2dec('9080');
  board.SubVendorId = hex2dec('10b5');
  board.SubDeviceId = hex2dec('3100');
  board.PreHookFunction = 'xpcgs24dsi12prehook';
  board.PostHookFunction = 'NULL';
  board.HookIncludeFile = 'xpcgs24dsi12hooks';
  board.StartFunction = 'xpcgs24dsi12start';
  board.StopFunction = 'xpcgs24dsi12stop';

• name — Enter an appropriate board name string. The xPC Target software uses this string to populate the drop-down list for the I/O board generating the interrupt parameter in the following:

  • Async IRQ Source block

  • PCI slot (-1: autosearch) or ISA base address parameter in the xPC Target Options section of the model Configuration Parameters dialog box

• VendorId, DeviceId, SubVendorId, SubDeviceId — Enter the appropriate ID strings. If you have a PCI board, the board manufacturer identifies that board with either two or four ID values, depending on the specific hardware. When calling the hook functions, the xPC Target kernel obtains the PCI information for the board and passes it to the hook functions. Use these parameters to help identify the interrupting board.

  • For VendorId and DeviceId, enter the IDs you get from the board manufacturer.

  • Many boards do not have SubVendorId and SubDeviceId values. In these cases, insert the value -1 to prevent The xPC Target software from checking for them.

  If you have an ISA board, it does not have a vendor or device ID; instead, the generated code will insert the ISA base address in the first base address entry of the PCI structure. To indicate to the kernel that this is an ISA board, set VendorId to -1 and DeviceId to 1.

  If you do not need hook functions:

  • Set VendorId to -1 and DeviceId to -1.

  • Set Fnc and PostHookFcn to 'NULL'.

  • Set StartFunction and StopFunction to 'NULL'.

  The Async IRQ Source block will still call the subsystem when an interrupt occurs.

  The following table summarizes your options for this element:

  VendorId	DeviceId	Usage
  +ID	+ID	PCI board
  -1	+1	ISA board
  -1	-1	Special case: If the driver does not need hook functions. The driver can still use the Async IRQ Source block. As an example, see the source code for the serial communication driver.

• Enter the names of the interrupt functions. See Hook Function Prototypes — Alphabetical List for the prototype details.

  • PreHookFunction

    Prototype:

    int __cdecl  your_company_name_boardPreHook(xpcPCIDevice *pciInfo);

  • PostHookFunction

    Prototype:

    void __cdecl your_company_name_boardPostHook(xpcPCIDevice *pciInfo);

  • StartFunction

    Prototype:

    void __cdecl your_company_name_boardStart(xpcPCIDevice *pciInfo);

  • StopFunction

    Prototype:

    void __cdecl your_company_name_boardStop(xpcPCIDevice *pciInfo);

  If any of these four functions does not need to exist, set the corresponding board structure entry to 'NULL' to prevent calls to that function in that context.

  Note   The differences between hook functions for PCI and ISA devices are: PCI devices — A hook function for a PCI device has all fields of the xpcPCIDevice structure filled in except the VirtAddress field. To get the virtual address for a physical memory, in the Start function, call the xpcReserveMemoryRegion function and save the resulting virtual address in the VirtAddress field of the xpcPCIDevice structure. A pointer to the same instance of this structure is passed to all four functions. This action makes data, such as virtual addresses, available to all functions. ISA devices — A hook function for an ISA device has the base I/O address entered in the first physical address. No other fields in the xpcPCIDevice structure are filled in.

• HookIncludeFile — Interrupt handling file that contains the PreHookFunction, PostHookFunction, StartFunction, and StopFunction functions for this board. Specify this name without the .c extension.

• Specify this structure for each board for which interrupt functions have been written. For example:

  board(1).name = 'name1';
  .
  .
  .
  board(2).name = 'name2';

Back to Top

xPC Target Interrupts

Hook Function Prototypes — Alphabetical List

© 1984-2009- The MathWorks, Inc.    -   Site Help   -   Patents   -   Trademarks   -   Privacy Policy   -   Preventing Piracy   -   RSS