Documente Academic
Documente Profesional
Documente Cultură
Embedded Solutions
M66 MEN Driver Interface System (MDIS5) for M66, A302 and D302
M66 32 Binary Inputs/Outputs A302 6U VMEbus Card with 128 Binary I/Os D302 6U CompactPCI Card with 128 Binary I/Os
User Manual
History
Issue E1 E2 E3 E4 E5 First issue Second issue General update Updated for MDIS5 support Removed programming example (example code is included with driver) Cosmetics Comments Date 1998-03-09 2002-04-08 2004-12-15 2011-05-13
Conventions
!
italics bold
monospace
This sign marks important notes or warnings concerning proper functionality of the product described in this document. You should read them in any case. Folder, file and function names are printed in italics. Bold type is used for emphasis. A monospaced font type is used for hexadecimal numbers, listings, C function descriptions or wherever appropriate. Hexadecimal numbers are preceded by "0x". Hyperlinks are printed in blue color. The globe will show you where hyperlinks lead directly to the Internet, so you can look for the latest information online.
hyperlink
Signal names followed by "#" or preceded by a slash ("/") indicate that this signal is either active low or that it becomes active at a falling edge. Signal directions in signal mnemonics tables generally refer to the corresponding board or component, "in" meaning "to the board or component", "out" meaning "coming from it". Vertical lines on the outer margin signal technical changes to the previous issue of the document.
Legal Information
MEN Mikro Elektronik reserves the right to make changes without further notice to any products herein. MEN makes no warranty, representation or guarantee regarding the suitability of its products for any particular purpose, nor does MEN assume any liability arising out of the application or use of any product or circuit, and specifically disclaims any and all liability, including without limitation consequential or incidental damages. "Typical" parameters can and do vary in different applications. All operating parameters, including "Typicals" must be validated for each customer application by customer's technical experts. MEN does not convey any license under its patent rights nor the rights of others. Unless agreed otherwise, MEN products are not designed, intended, or authorized for use as components in systems intended for surgical implant into the body, or other applications intended to support or sustain life, or for any other application in which the failure of the MEN product could create a situation where personal injury or death may occur. Should Buyer purchase or use MEN products for any such unintended or unauthorized application, Buyer shall indemnify and hold MEN and its officers, employees, subsidiaries, affiliates, and distributors harmless against all claims, costs, damages, and expenses, and reasonable attorney fees arising out of, directly or indirectly, any claim of personal injury or death associated with such unintended or unauthorized use, even if such claim alleges that MEN was negligent regarding the design or manufacture of the part. Unless agreed otherwise, the products of MEN Mikro Elektronik are not suited for use in nuclear reactors or for application in medical appliances used for therapeutical purposes. Application of MEN products in such plants is only possible after the user has precisely specified the operation environment and after MEN Mikro Elektronik has consequently adapted and released the product. ESM, ESMini, MDIS, MDIS4, MDIS5, MENMON, M-Module, M-Modules, SA-Adapter, SAAdapters, UBox, USM and the MBIOS logo are trademarks of MEN Mikro Elektronik GmbH. PC-MIP is a registered trademark of MEN Micro, Inc. and SBS Technologies, Inc. MEN Mikro Elektronik, ESMexpress, MIPIOS and the MEN logo are registered trademarks of MEN Mikro Elektronik GmbH. All other products or services mentioned in this publication are identified by the trademarks, service marks, or product names as designated by the companies who market those products. The trademarks and registered trademarks are held by the companies producing them. Inquiries concerning such trademarks should be made directly to those companies. All other brand or product names are trademarks or registered trademarks of their respective holders. Information in this document has been carefully checked and is believed to be accurate as of the date of publication; however, no responsibility is assumed for inaccuracies. MEN Mikro Elektronik accepts no liability for consequential or incidental damages arising from the use of its products and reserves the right to make changes on the products herein without notice to improve reliability, function or design. MEN Mikro Elektronik does not assume any liability arising out of the application or use of the products described in this document. Copyright 2011 MEN Mikro Elektronik GmbH. All rights reserved.
Please recycle
Germany MEN Mikro Elektronik GmbH Neuwieder Strae 5-7 90411 Nuremberg Phone +49-911-99 33 5-0 Fax +49-911-99 33 5-901 E-mail info@men.de www.men.de
France MEN Mikro Elektronik SA 18, rue Ren Cassin ZA de la Chtelaine 74240 Gaillard Phone +33 (0) 450-955-312 Fax +33 (0) 450-955-211 E-mail info@men-france.fr www.men-france.fr
USA MEN Micro, Inc. 24 North Main Street Ambler, PA 19002 Phone (215) 542-9575 Fax (215) 542-9577 E-mail sales@menmicro.com www.menmicro.com
Contents
Contents
1 Low-Level Driver Functionality . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1.1 Logical Channels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1.2 Interrupts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1.3 Programmable Logic Device Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1.4 Buffers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 5 6 6 6
2 Device-Specific SetStat/GetStat Codes and Descriptor Entries . . . . . . . . . . 7 2.1 GetStat/SetStat Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 2.2 Descriptor Entries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 3 Functional Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 3.1 MDIS Application Programming Interface (API) . . . . . . . . . . . . . . . . . 9 3.1.1 Supported API Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 3.1.2 Programming Example for MDIS API . . . . . . . . . . . . . . . . . 11 3.2 Low-Level Driver Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 3.2.1 M66_Init Initialize the Device . . . . . . . . . . . . . . . . . . . . . . 13 3.2.2 M66_Exit Deinitialize the Device . . . . . . . . . . . . . . . . . . . 15 3.2.3 M66_Read Read a Value from the Device . . . . . . . . . . . . . 16 3.2.4 M66_Write Write a Value to the Device . . . . . . . . . . . . . . 17 3.2.5 M66_SetStat Set the Driver Status. . . . . . . . . . . . . . . . . . . 18 3.2.6 M66_GetStat Get the Driver Status . . . . . . . . . . . . . . . . . . 19 3.2.7 M66_BlockRead Read a Data Block from the Device . . . 21 3.2.8 M66_BlockWrite Write a Data Block to the Device . . . . . 22 3.2.9 M66_Irq Interrupt Service Routine . . . . . . . . . . . . . . . . . . 23 4 Installing A302/D302 Devices under MDIS Wizard . . . . . . . . . . . . . . . . . . 24
The driver provides 32 logical channels corresponding to 32 binary I/O lines. The 128 I/O lines of the A302/D302 I/O boards are treated as four units of 32 lines each. The MDIS driver views each of these units as one "M66 device". Please note that you have to add four M66 devices for each A302/D302. For details see Chapter 4 Installing A302/D302 Devices under MDIS Wizard on page 24. Each channel is always input and output, i.e., the output pin can be driven while its state is being read.
Table 1. Channel Correspondence between Hardware and MDIS M66 I/O Line 11 12 13 14 15 16 17 18 21 22 23 24 25 26 27 28 A302/D302 I/O Line 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 MDIS Channel M66 I/O Line 31 32 33 34 35 36 37 38 41 42 43 44 45 46 47 48 A302/D302 I/O Line 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 MDIS Channel 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31
The above table shows one I/O unitor M66 deviceof the A302/D302 board.
1.2
Interrupts
You can enable or disable the interrupt at the rising, falling or at both edges for each of the 32 channels. This can be done via descriptor entry and/or a SetStat call. The interrupt service routine will read all channels. In buffer modes M_BUF_RINGBUF, M_BUF_RINGBUF_OVERWR or M_BUF_CURRBUF the current input state and the occurred edges will be stored in the buffer. The interrupt service routine also stores the number of the channel that triggered the interrupt. This information can be retrieved by a GetStat call. The interrupt service routine can send signals. One of them notifies the user process that an edge has occurred. The signal can be installed through SetStat code M66_SIG_EDGE_OCCURRED. The other signals are buffer signals, e.g. highwater notification.
1.3
The heart of the M-Module is a programmable logic device (PLD). MENs driver contains the PLD data and will automatically program the PLD at initialization (M_open with MDIS API or M66_Init with low-level driver interface).
Note: Newer M-Module versions and A302/D302 have a preloaded PLD. In this case the PLD is not affected by the initialization process.
1.4
Buffers
The M66 driver uses the output buffer to switch all channels as a block. It supports the following output buffer mode: M_BUF_USERBUF The M66 driver uses the input buffer to read all channels. It is also used by the interrupt service routine. The driver supports the following input buffer modes: M_BUF_USERBUF M_BUF_RINGBUF M_BUF_RINGBUF_OVERWR M_BUF_CURRBUF
2.1
GetStat/SetStat Codes
The M66 driver provides the following status codes in addition to the standard codes:
Table 2. Device-Specific SetStat and GetStat Codes Code M66_EDGE_MASK Set/Get Set/Get Description Set or get the edge mask of a channel Values 0..2, M66_IELH, M66_IEHL
Install a signal to be sent by the interrupt Signal number service routine or get the installed signal Deinstall the signal Get the number of the channel that triggered an interrupt Signal number IRQ source
(For a description of the above codes see Chapter 3.2.5 M66_SetStat Set the Driver Status on page 18 and Chapter 3.2.6 M66_GetStat Get the Driver Status on page 19.)
2.2
Descriptor Entries
The low-level driver initialization routine decodes the following entries ("keys") in addition to the general descriptor keys (see Chapter 3.2.1 M66_Init Initialize the Device on page 13):
Table 3. Device-Specific Descriptor Entries Descriptor Entry CHANNEL_%d/IRQ_ENABLE Description Enables the interrupt for a given channel and given edges Possible Values Edge: 0 = disabled 1 = rising edge 2 = falling edge 3 = any edge Channel: %d: 0..31 Default 0 RD_BUF/HIGHWATER Read buffer highwater mark Possible Values 0..RD_BUF/SIZE in bytes Default 512 RD_BUF/MODE Read buffer mode Possible Values See mbuf.h Default MBUF_USR_CTRL RD_BUF/SIZE Size of the read buffer Possible Values 0..n*32 in bytes Default 512 RD_BUF/TIMEOUT Read buffer timeout Possible Values 1..n in ms Default 1000
Functional Interface
Functional Interface
3.1 MDIS Application Programming Interface (API)
The MDIS API is a function interface for the user to access an MDIS driver. This chapter only gives a correspondence table of MDIS API calls and low-level driver functions. For a detailed description please refer to MENs operating-system specific API documentation.
Figure 1. MDIS Application Programming Interface (API)
Device Descriptor Application using MDIS API
MDIS and BBIS Descriptor Generator OS Specific Device Descriptor Low-Level Driver
MDIS API
Operating System
Functional Interface
3.1.1
Table 4. Correspondence between MDIS API Functions and Low-Level Driver Functions M_open Open device MDIS_PATH M_open( char *device ) M_close Close device int32 M_close( MDIS_PATH path ) M_read Read from device int32 M_read( MDIS_PATH path, int32 *value ) M_write Write to device int32 M_write( MDIS_PATH path, int32 value ) M_setstat Set device parameter int32 M_setstat( MDIS_PATH path, int32 code, INT32_OR_64 data ) M_getstat Get device parameter int32 M_getstat( MDIS_PATH path, int32 code, int32 *data ) M_getblock Block read from device int32 M_getblock( MDIS_PATH path, u_int8 *buffer, int32 length ) M_setblock Block write to device int32 M_setblock( MDIS_PATH path, u_int8 *buffer, int32 length) M_errstring Convert MDIS error code to static string char* M_errstring( int32 errCode ) M_errstringTS Convert MDIS error code to static string (thread-safe) char* M_errstringTs(int32 errCode, char *strBuf);
Note on M_setstat and M_getstat For normal status codes, data points to a 32-bit integer value. For block status codes, it is interpreted as a pointer to structure M_SG_BLOCK, which contains the size and location of the data buffer. Structure M_SG_BLOCK
typedef struct { int32 size; void *data; } M_SG_BLOCK; /* application buffer size */ /* application buffer location */
10
Functional Interface
3.1.2
An example program showing how to use the MDIS API functions with the M66 MModule is included with the driver in the subdirectory M66_SIMP.
11
Functional Interface
3.2
The low-level driver is seated directly on the hardware. You can use it to write your own device driver even without profound knowledge of the operating system.
Table 5. Overview of Low-Level Driver Functions Function M66_Init M66_Exit M66_Read M66_Write M66_SetStat M66_GetStat M66_BlockRead M66_BlockWrite M66_Irq Description Allocate and return low-level handle, initialize hardware Deinitialize hardware and clean up memory Read a value from the device Write a value to the device Set the driver status Get the driver status Read a data block from the device Write a data block to the device Interrupt service routine
12
Functional Interface
3.2.1
Syntax
static int32 M66_Init ( DESC_SPEC *descSpec, OSS_HANDLE *osHdl, MACCESS *ma, OSS_SEM_HANDLE *devSem, OSS_IRQ_HANDLE *irqHdl, LL_HANDLE **llHdlP )
Description
Decodes descriptor, allocates and initializes the ll-driver structure. Loads the PLD and initializes the hardware. Reads the ID and checks if it is enabled in the descriptor. Clears and disables the module interrupts. Switches off all outputs. The driver supports 32 digital I/O channels. There may be one read buffer with a width of 32 bytes. Descriptor key -------------DEBUG_LEVEL_DESC DEBUG_LEVEL_MBUF DEBUG_LEVEL RD_BUF/SIZE RD_BUF/MODE RD_BUF/TIMEOUT RD_BUF/HIGHWATER ID_CHECK Default ------OSS_DBG_DEFAULT OSS_DBG_DEFAULT OSS_DBG_DEFAULT 512 MBUF_USR_CTRL 1000 512 1 Range/Unit ---------see oss_os.h see oss_os.h see oss_os.h 0..n*32 in bytes see mbuf.h 1..n in ms 0..RD_BUF/SIZE in bytes 0..1 0 - disabled 1 - enabled 0..3 0 1 2 3 %d 0..31 disabled rising edge falling edge any edge
CHANNEL_%d/IRQ_ENABLE 0
Note:
13
Functional Interface
Input
descSpec osHdl ma devSem irqHdl llHdlP descriptor specifier pointer to the os specific structure access handle (in simplest case M66 base address) device semaphore for unblocking in wait irq handle for mask and unmask interrupts pointer to the variable where low-level driver handle will be stored
Output
*llHdlP return low-level driver handle 0 | error code
14
Functional Interface
3.2.2
Syntax
Description
Deinitialize the hardware, disable interrupts, free allocated memory. Note: Is called by MDIS kernel only.
Input
llHdlP pointer to low-level driver handle
Output
llHdlP return NULL 0 | error code
15
Functional Interface
3.2.3
Syntax
Description
Read input state from current channel
Input
llHdl ch valueP pointer to low-level driver data structure current channel 0..31 pointer to variable where read value is stored
Output
*valueP return read value 0=low, 1=high 0 | error code
16
Functional Interface
3.2.4
Syntax
Description
The output of the current channel will be switched on or off.
Input
llHdl ch value pointer to low-level driver data structure current channel 0..31 switch on/off 0=off, 1=on
Output
return 0 | error code
17
Functional Interface
3.2.5
Syntax
static int32 M66_SetStat ( LL_HANDLE *llHdl, int32 code, int32 ch, INT32_OR_64 value32_or_64 )
Description
Change the device state. Common Codes -----------M_MK_IRQ_ENABLE Values -----0 1 see oss.h irq count Values -----0 1 M66_IELH 2 M66_IEHL Meaning ------disable module interrupt enable module interrupt by writing edge channel mask en/disable debug output at task or interrupt level set the module interrupt counter Meaning ------no edge rising edge falling edge set the edge mask of the current channel install the signal sent by ISR deinstall the signal
M66_SIG_EDGE_OCCURRED
signal number
Input
llHdl code ch value32_or_64 pointer setstat current data or pointer (*) = for block status to low-level driver data structure code channel (ignored for some codes) to block data structure (M_SG_BLOCK) (*) codes
Output
return 0 | error code
18
Functional Interface
3.2.6
Syntax
static int32 M66_GetStat ( LL_HANDLE *llHdl, int32 code, int32 ch, INT32_OR_64 *value32_or_64P )
Description
Get the device state. Common Codes -----------M_LL_CH_NUMBER M_LL_CH_DIR M_LL_CH_LEN M_LL_CH_TYP M_LL_IRQ_COUNT M_LL_ID_CHECK M_LL_DEBUG_LEVEL M_LL_ID_SIZE M_LL_BLK_ID_DATA M_MK_BLK_REV_ID Specific Codes -------------M66_EDGE_MASK Values -----32 M_CH_INOUT 1 M_CH_BINARY 0..x 0..1 see oss.h 128 Meaning ------number of channels direction of curr ch always in/out length in bits binary module irq count SPROM ID is checked in M66_Init() current debug level EEPROM size [bytes] (*1*) EEPROM raw data (*2*)
pointer to the ident function table Values -----0 1 M66_IELH 2 M66_IEHL Meaning ------no edge rising edge falling edge get the edge mask of the current channel get the signal number 0 if not installed irq triggering channel of the last irq
M66_SIG_EDGE_OCCURRED M66_IRQ_SOURCE
Note for D302/A302 devices: (*1*) M_LL_ID_SIZE returns 0 (*2*) M_LL_BLK_ID_DATA not supported
19
Functional Interface
Input
llHdl code ch value32_or_64P pointer to low-level driver data structure getstat code current channel (ignored for some codes) data pointer or pointer to block data structure (M_SG_BLOCK) (*) (*) = for block status codes
Output
value32_or_64P data pointer or pointer to block data structure (M_SG_BLOCK) (*) return success (0) or error code (*) = for block status codes
20
Functional Interface
3.2.7
Syntax
static int32 M66_BlockRead ( LL_HANDLE *llHdl, int32 ch, void *buf, int32 size, int32 *nbrRdBytesP )
Description
Read all channels to buffer. Store input state and occurred edges. Always start with channel 0. Supported modes: M_BUF_USRCTRL M_BUF_RINGBUF M_BUF_RINGBUF_OVERWR M_BUF_CURRBUF reads from hardware reads from buffer " " " " " "
byte structure bit meaning 7..3 2 1 0 +- - -+---------+---------+-------+ | no | H->L | L->H | value | +- - -+---------+---------+-------+
Input
llHdl ch buf size nbrRdBytesP pointer to low-level driver data structure current channel (always ignored) buffer to store read values must be multiple of buffer width (32) pointer to variable where number of read bytes is stored
Output
*nbrRdBytesP number of read bytes return 0 | error code
21
Functional Interface
3.2.8
Syntax
static int32 M66_BlockWrite ( LL_HANDLE *llHdl, int32 ch, void *buf, int32 size, int32 *nbrWrBytesP )
Description
Switch maximum 32 channels. Always start with channel 0. Supported modes: buffer structure byte channel 0 +---+| 0 | +---+1..30 31 - - - -+----+ 1..30 | 31 | - - - -+----+ M_BUF_USRCTRL writes to hardware
0=off, 1=on
Input
llHdl ch buf size pointer to low-level driver data structure current channel (always ignored) buffer where output values are stored number of bytes to write (max. 32)
Output
nbrWrBytesP return number of written bytes 0 | error code
22
Functional Interface
3.2.9
Syntax
Description
The irq routine reads all channels. It stores the input states and the occurred edges to the read buffer if available. It clears the edge flag registers. If signal is installed (setstat code M66_SIG_EDGE_OCCURRED) this is sent. It clears the module irq and stores the number of the channel that triggered the irq. (getstat code M66_IRQ_SOURCE) It increments the module irq counter if an edge was detected. (getstat code M_LL_IRQ_COUNT)
Input
llHdl pointer to low-level driver data structure
Output
return MDIS_IRQ_DEV_NOT | MDIS_IRQ_DEVICE
23
24