MATLAB XPC TARGET 4 - DEVICE DRIVERS User's Guide

xPC Target™ 4Device Drivers

1 Customizing xPC Target™ DriversIntroductionIn this section...“xPC Target Drivers” on page 1-2“When to Write Your Own Drivers” on page 1-3“Restrictio

xpcAllocPhysicalMemor yPurpose Allocate physical memoryPrototype void *xp cAllocPhysicalMemory(uint32_T numBytes)HeaderFilexpctarget.hArgumentsnumByte

xpcBusyWaitPurpose Wait for specified length of time in secondsPrototype void xpc BusyWait(real_T seconds)HeaderFilexpctarget.hArgumentssecondsLength

xpcFreePhysicalMemor yPurpose Free physical memoryPrototype void xpc FreePhysicalMemory(const void * phys ical)HeaderFilexpctarget.hArgumentsphysicalF

xpcGetElapsedTimePurpose Return time since system bootPrototype real_T x pcGetElapsedTime(xpcTime *upTime)ArgumentsupTimePointer to an xpcTime structu

xpcGetPCIDeviceInfoPurpose Return information for PCI devicePrototype int32_T xpcGetPCIDeviceInfo (uint16_T v endorId, uint16_TdeviceId, uint16_T subV

xpcGetPCIDeviceInfousing only vendor ID and device ID, use XPC_NO_SUB for s ubDeviceIdand XPC_N O_SU B for subVen dor Id.This function returns 0 upon

xpcInpB, xpcInpW, xpcInpDWPurpose I/O port input functions for byte, word, and double word accessesPrototype uint8_T xpcInpB(uint16_T port)uint16_T xp

xpcIsModelInitPurpose Return target application load statePrototype boolean_T xpcIsModelInit(vo id)HeaderFilexpctarget.hArgumentsnoneDescription The x

xpcOutpB, xpcOutpW, xpcOutpDWPurpose I/O port output functions for byte, word, and double word accessesPrototype void xpc OutpB(uint16_T port, uint8_T

xpcReser veMemoryRegionPurpose Return virtual address that corresponds to physical address and markregion as readable/writablePrototype void * xpcRese

IntroductionWhen to Write YourOwnDriversConsider writing your own device drivers for the xPC Target block library if:• No xPC Ta rge t driver exists f

xpcShowPCIDeviceInfoPurpose Display contents of PCIDevice structurePrototype void xpc ShowPCIDeviceInfo(xpcPCIDevice *pciInfo)ArgumentspciInfoPointer

xpcSubtractTimePurpose Return differe n ce between two timesPrototype real_T x pcSubtractTime(xpcTime *time,const xpcTime *time2, const xpcTime *time1

1 Customizing xPC Target™ Drivers• Good C programming skills• Knowledge of how Sim u link simul ation works, for example, t he type an dorder of calls

IntroductionSee...For...Developing S-Functions How to write MATLAB C-MEX S-functions (noninlined S-functions).Note the following references in this gu

1 Customizing xPC Target™ DriversxPC Target Exported FunctionsThe xPC Target software provides kernel functions that y ou can use whenwriting your dev

IntroductionBlock maskUnderlying driver code (C-file)Mask editorMask initialization (M-file)Anatomy of an xPC Target™ Driver1-7

1 Customizing xPC Target™ DriversBefore You Star tIn this section...“Introduction” on page 1-8“Driver Types” on page 1-9“Bus Types and Register Access

Before Yo u Start• Sele ct poll in g versus i nterrupt.• Specify the blocks for the drivers. Identify- Input and output ports- Mask parameters- Work v

1 Customizing xPC Target™ DriversBus AccessISA Board switches or jumpers usually select I/O port address and anymemory-mapped region.PCI The BIOS dete

Creating a C ustom DriverCreating a Custom DriverThe following is a generic procedure for how to create a custom device driver.For additional note s o

How to Contact MathWorkswww.mathworks.comWebcomp.soft-sys.matlab Newsgroupwww.mathworks.com/contact_TS.html Technical [email protected] Pro

1 Customizing xPC Target™ Drivers4 Open the Simulink Library Browser and create a new library, for example,your_company_namelib.mdl (see “Creating Blo

Creating a C ustom Driver7 Double-click the S-Function block and create a block mask (see Chapter 4,“Masking Drivers”).8 Save and close the S-Function

1 Customizing xPC Target™ DriversRename this file your_co mpany_namelib_xpcblocks. m and edit this file asfollows:• Setout.Library to your new library

Creating a C ustom Driverboards(1).VendorName = 'Co mmte ch';boards(1).DeviceType = 'Se rial Ports';e Save and close the file.f To

1 Customizing xPC Target™ DriversDebugging NotesWhile developing your custom driver, you can use pr intf statements in yourcode. This displays output

2PCI Drivers• “PCI Bus Co nsiderations” on page 2-2• “Sample PCI Device Driver” on page 2-8

2 PCI DriversPCI Bus ConsiderationsIn this section...“Introduction” on page 2-2“PCI Configuration Space API” on page 2-3“Memory-Mapped A ccesse s” on

PCI Bus ConsiderationsYou can have the drivers locate PCI devices in one of the following ways:• If the system has one board of any one type, you can

2 PCI DriversPCI Device InformationUse the xpcGetPCIDeviceInf o function to get information for a PCI device inyour system. The syntax for this functi

PCI Bus ConsiderationsSet...To ...Set slot = -1 Assume bus = 0 and call the xpcGetPCIDeviceInfofunction to find the first instance of the b oard.Set s

Revision HistoryMarch 2007 Online only New for Version 3.2 (Release 2007a)September 2007 Online only Updated for Version 3.3 (Release 2007b)March 2008

2 PCI DriversvendorId = (uint16_T)0x1234;deviceId = (uint16_T)0x9876;subvendor = (uint16_T)0x5678;subdevice = (uint16_T)0x8765;/* Set subvendor and su

PCI Bus Considerations• xpcInpB, xpcInpW, xp cInpDW — I/O port input functions for byte, word,anddoublewordaccesses•xpcOutpB, xpcOutpW, xpc Outp DW —

2 PCI DriversSample PCI Device DriverFor example PCI dev ice driv er code, seematlabroot\toolbox\rtw\targets\xpc\target\build\xpcblocks\dikpci1800.cTh

3ISA and PC/104 Drivers

3 ISA and PC/104 DriversISA and PC/104 Bus ConsiderationsIn this section...“Introduction” on page 3-2“I/O Mapped” on page 3-2“Memory Mapped” on page 3

ISA and PC/104 Bus Consid e rationsMemory MappedThe I/O and memory on the board is set via jumpers or sw itches. Driverscannot discoverthese addresses

3 ISA and PC/104 Drivers3-4

4Masking Drivers• “Creating Driver Subsystem Masks” on page 4-2• “Driver M ask Guidelines” on page 4-3• “Cross-Block Checking” on page 4-5• “When You

4 Masking DriversCreating Driver Subsystem M asksThis chapter describes guidelines for creating a Simulink block user interface(mask) for the S-Functi

Driver Mask GuidelinesDriver Mask GuidelinesThis top ic lists guidel in es you sh ould follow when cre ati ng a ma sk for yourxPC Target driver. You s

4 Masking Drivers- Range checking for all parameters. For example, if you expect inputvalues from1 to 10, do not allow users to enter negative values,

Cross-Block CheckingCross-Block CheckingCross-block checking determines if multiple blocks are trying to access thesame hardware. You should include c

4 Masking DriversWhen You Are DoneAfter you write the driver S-function and create the S-Function block, optionalblock mask, and MATLAB file for it, b

Sample Driver MaskSample Driver MaskThe following is the block mask for the Diamond MM-32 Analog Input block.If you were to create this mask as a new

4 Masking DriversNumber of channels:RangeSample time:Base address (for e xamp le 0x300):• In the Variable column, enter the parameter names. Be sure t

Sample Driver Mask3 Select the Initialization tab . The tab displays the dialog v ari ables youentered in the Parameters tab.4 In the Initialization c

4 Masking DriversThis example returns a string to display on the block with the variableport_label commands with which to label the input and output p

Sample Driver MaskAt InitF cn time, no variables in the mask exist yet. You cannot pass theminto theInitFcn. H ow ev er, in the function, you can get

4 Masking Drivers4-12

5Interrupt Support• “xPC Target Interrupts” on page 5-2• “Addin g Interrupt Suppo rt” on page 5 -7• “Hook Function Prototypes — A lphabetical List” on

ContentsCustomizing xPC Target Drivers1Introduction ... 1-2xPC Target Drivers... 1-2Wh

5 Interrupt SupportxPC Target InterruptsIn this section...“Introduction” on page 5-2“Interrupt Processing in the x PC Target Environment” on page 5-2I

xPC Target™ InterruptsThe following illustrates the flow of processing once a hardware interruptoccurs. This is background information to help you und

5 Interrupt SupportInterrupt occursCall PreHookFunction(if one exists)Did PreHookFunctionreturn a value ofXPC_RUN_ISR?Functioncall oninterrupt?Send wa

xPC Target™ InterruptsWhen a hardware interrupt occurs, the generated code uses the following stepsfor each device on this IRQ to determine which devi

5 Interrupt SupportNote The Allow preemption of function call subsystem check box hasno effect. Interrupts are never enabled when the function-call su

Adding Interrupt SupportAdding Interrupt SupportIn this section...“Introduction” on page 5-7“Guidelines for Creating Interrupt Functions” on page 5-9“

5 Interrupt SupportFunction DescriptionStartRuns as the last item when starting a model, justbefore the model runs. It is typically used to turnon int

Adding Interrupt Support4 Copy the file sample_int.m toauniquefilenameinthefollowingdirectory:matlabroot\toolbox\rtw\targets\xpc\target\build\xpcblock

5 Interrupt Supportmatlabroot\toolbox\rtw\targets\xpc\target\build\xpcblocks\thirdpartydrivers\When modifying an existing hook file:• Change the nam e

Adding Interrupt Support• Depending on the bus type of your board, select a board structure of anexisting board that has the same bus type. The inform

ISA and PC/104 Drivers3ISA and PC/104 Bus Considerations ... 3-2Introduction... 3-2I/O Mapped...

5 Interrupt Supportthat board with either two or four ID values, depending on the specifichardware. W hen calling the hook functions, the xPC Target k

Adding Interrupt Support- PreHookFunctionPrototype:int __cdecl your_company_name_ boardPreHook(xpcPCIDevice *pciI nfo);- PostHookFunctionPrototype:voi

5 Interrupt Support• HookIncl udeFile — Interrupt handling file that contains thePreHookFunction, PostH ookF unction, StartFunction,andStopFunctionfun

Hook Function Prototypes — Alphabetical ListHook Function Prototypes — Alphabetical List• your_company_name_boardPostHook• your_company_name_boardPreH

your_company_name_boardPostHookPurpose Run after return from interrupt service routine function-call subsystemor after sending wakeup call to model th

your_company_name_boardPreHookPurpose Run just b efore the interrupt service routineSyntax int __cdecl your_company_name_boardPreHook(xpcPCIDevice*pci

your_company_name_boardStar tPurpose Run as the last item in mdlStartSyntax void __cdecl your_company_name_boardStart(xpcPCIDevice*pciInfo);Argumentpc

your_company_name_boardStopPurpose Run at the beginning of mdlTerminateSyntax void __cdecl your_company_name_boardStop(xpcPCIDevice*pciInfo);Argumentp

your_company_name_boardStop5-20

6Custom xPC Target DriverNotes• “S-Function Guidelines” on page 6-2• “mdlStart and mdlTerminate Considerations” on page 6-4• “DMA Considerations” on p

Hook Function Prototypes — Alphabetical List ... 5-15Custom xPC Target Driver Notes6S-Function Guidelines ... 6-2mdlStar

6 Custom xPC Target™ Driver NotesS-Function GuidelinesYou implement xPC Target device driver blocks using Simulink S-functions.An S-function is a set

S-Function Guidelinesis also compiled with your application to run on the target PC. Because ofthe following reasons, you must conditionally compile c

6 Custom xPC Target™ Driver NotesmdlStart and mdlTerminate ConsiderationsWhen you load a target application onto a target PC, the driver executes them

DMA ConsiderationsDMA ConsiderationsIf your board directly accesses system RAM, such as a DMA controller, youmust allocate that memory using thexpcAll

6 Custom xPC Target™ Driver NotesPassing ParametersSee “Passing Parameters to S-Functions” in Developing S-Functions.6-6

Accessing RegistersAccessing RegistersIn this section...“I/O Space” on page 6-7“Memory-Mapped Space” on page 6-7I/O SpaceFor registers in I/O space, u

6 Custom xPC Target™ Driver Notes• Structurestruct bdregs {volatile int reg1;volatile int reg2;etc.};struct bdregs *regs = pciInfo.Virtua lAdd ress[1]

7Creating Custom DriversUsing the xPC T argetDriver Authoring Tool• “xPC Target Driver Authoring Tool” on page 7-2• “Generating C ustom Driver Templat

7 Creating Custom Drivers Using the xPC Target™ D river Authoring ToolxPC Tar get Driver Authoring ToolxPC Target Driver Authoring Tool helps you crea

xPC Target™ Driver Authoring ToolNote The xPC Target Driver Authoring Tool creates custom driver templatesusing the Legacy Code Tool (LCT). You do not

I/O Structures — By Category8I/O Structures — Alphabetical List9I/O Functions — By Category10Port I/O ... 10-2

7 Creating Custom Drivers Using the xPC Target™ D river Authoring ToolGenerating Custom Driver Te mplatesIn this section...“Using the xPC Target Drive

Generating Custom Driver TemplatesThe xPC Target Driver Authoring Tool is displayed.3 In the M ain tab, enter:• Driver name — The name for your driver

7 Creating Custom Drivers Using the xPC Target™ D river Authoring Tool• Size — E nter the maximum size number of storage locations to beallocated f or

Generating Custom Driver Templatesfunction argument that contains the size into the start, output and/orterminate functions along with the port/parame

7 Creating Custom Drivers Using the xPC Target™ D river Authoring ToolYou can iteratively change the configuration and resave the MAT-file a s oftenas

Generating Custom Driver TemplatesNote Use the xPC Target Driver Authoring Tool to build the C Mex file ifyou have not edited the C source code file (

7 Creating Custom Drivers Using the xPC Target™ D river Authoring Tool7-10

8I/O Structures — ByCategoryxpcPCIDeviceType definition for PCI configurationspace structurexpcTimeType definition of time structure

8 I/O Structures — By Catego ry8-2

9I/O Structures —Alphabetical List

1Customizing xPC TargetDrivers• “Introduction” on page 1-2• “Before You Start” on page 1-8• “Creating a Custom Driver” on page 1-11• “Debugging Notes”

xpcPCIDevicePurpose Type definition for PCI configuration space structurePrototype typedef struct xpcPCIDe viceStruct{uint32_T BaseAddress[6];uint32_T

xpcPCIDeviceIndicates whether the board is I/O portmapped or memory-mapped. Values areone of t he fo ll owing. Verify this value inthe hardware manufa

xpcPCIDeviceof these addresses. Base addresses are filled in during the BIOSplug and play initialization, before the xPC Target kernel starts toexecut

xpcTimePurpose Type definition of time structurePrototype typedef struct xpcTime6 4Struct{uint32_T NanoSecondsLo;uint32_T NanoSecondsHi;} xpcTime64;ty

xpcTime9-6

10I/O Functions — ByCategoryPort I/O (p. 10-2) I/O port input and output functionsfor byte, word and double wordaccessesPCI Confi gu ration Inform ati

10 I/O Functions — By C atego ryPor t I/OxpcInpB, xpcInpW, xpcInpDWI/O port input functions for byte,word, and double word accessesxpcOutpB, xpcOutpW,

MiscellaneousMiscellaneousxpcBusyWaitWait for specified length of time insecondsxpcIsModelInitReturn target application load state10-3

10 I/O Functions — By C atego ry10-4

11I/O Functions —Alphabetical List