M- Module Configuration
8.3 Administrative Functions
8.3.1 Initialization and M-Module Configuration
MIO_Init()
Function prototype int MIO_Init(void *IO_Space)
Description
This function initializes the MIO module. It has to be called once at program start and prior to any other MIO function. The registration table of M modules will be cleared, the configu-ration of all modules will get lost.
In order to assure proper access to the M modules,MIO_Init()opens the device/dev/MIO and checks the version of the MIO device driver. The initialization fails, if the MIO module was compiled with a newer version of the MIO driver, or if the compatibility version of the MIO driver is newer than the MIO module.
The argumentIO_Spacegives the base address of the VME bus address space, where all M modules are located.
If the initialization was successful,MIO_Init()returns a file handle to the MIO driver (>= 0), otherwise it returns an error code (< 0).
Example if (MIO_Init(A16D16) < 0) {
while (MIO_ErrorGet(&ErrCode, &ErrMsg) > 0) LogErrF(EC_General, ErrMsg);
LogErrF(EC_General, "MIO initialization failed. IO disabled");
return -1;
}
MIO_MasterConfig()
Function prototype
int MIO_MasterConfig(int StartSlotNo, int Slots, long BaseAddr)
Description
Call this function to register M module carrier boards. The type of carrier board is recog-nized by the argumentSlots:
• MEN A201 (4 Slots)
• MEN B201 (1 Slot)
• MEN B202 (2 Slots)
The argumentStartSlotNogives the slot number for the first M module on the carrier board.
BaseAddrgives the base address of the carrier board as an offset to the address of the VME bus address space.
153 MIO – M-Module Input/Output
Administrative Functions
In this way you can register different types of M module carrier boards in an arbitrary order.
You can choose nearly freely the assignment of slot numbers to the M modules. Of course, it is recommended to configure the carrier boards contiguous in increasing order to avoid confusions.
IfBaseAddrhas an invalid value, or if any of the slotsStartSlotNo .. StartSlotNo+Slots-1 are already in use, or if no M module carrier board is detected at BaseAddr, then MIO_MasterConfig() returns an error code. Otherwise, the return value is 0.
Example MIO_MasterConfig(0, 4, 0);
MIO_MasterConfig(4, 4, 2048);
This registers two M module carrier boards, each with 4 slots (type MEN A201). The first board is configured to occupy slots 0 .. 3, beginning at offset 0, the second carrier board has an offset of 2048 and continues with slots 4 .. 7.
MIO_CheckModuleType()
Function prototype
int MIO_CheckModuleType(int Slot, int Type)
Description
This function checks, if there is a M module located at a given slot and if it is of a specific type.
Slotgives the M module slot where the module is mounted,Typespecifies the module type (M module number) to be expected.
If there is no M module located atSlot, or if the M module is not of typeType, then a value
<0 is returned. If there is a M module located at slotSlot, but the module type could not be determined due to a lack of an Id EEPROM, then a value >0 is returned. If the M module at slotSlot is of typeType, thenMIO_CheckModuleType() returns 0.
Example if (MIO_CheckModuleType(4, MIO_MT_M35) == 0) MIO_M35_Config(4);
else if (MIO_CheckModuleType(4, MIO_MT_M34) == 0) MIO_M34_Config(4);
else
return -1;
This example checks, if there is either a M35 module or a M34 module located at slot 4 and automatically calls the appropriateMIO_Mxx_Config()function. It is a common way to initial-ize one of the hard- and software compatible A/D conversion modules M34, M35 or M35N, without being aware of the exact hardware configuration.
MIO_RegisterModule()
Function prototype
int MIO_RegisterModule(int Slot, int Type)
Description
B e fo r e a M m o d u l e c a n b e u s e d , i t h a s t o b e r e g i s t e r e d w i t h t h e f u n c t i o n MIO_RegisterModule().
154 MIO – M-Module Input/Output
Administrative Functions
The registration of M modules is done automatically by theMIO_Mxx_Config()function. You do not have to call this function explicitly. However, in some cases – e.g. if you implement support for an unsupported M module on your own – this function might be useful.
Slotgives the M module slot where the module is mounted,Typespecifies the module type (M module number).
The functionMIO_RegisterModule()scans the given M module slot and checks by reading the contents of the Id EEPROM, if the module type matchesType. IfSlotis out of range, if there is a different or even no M module mounted atSlot, then an error code is returned. If Typematches the type of the mounted M module at Slot– or if the module has no Id EEPROM – thenMIO_RegisterModule() returns 0.
MIO_ResetModules()
Function prototype void MIO_ResetModules(void)
Description
This function scans all configured M modules and calls the specificMIO_Mxx_Reset() func-tions, in order to (re-)initialize all configured M modules.
This function should be called at the beginning of your application, after all M modules have been configured successfully.
MIO_DeleteAll()
Function prototype void MIO_DeleteAll(void)
Description
At the end of your application, before exiting and after the last access to any M module, this function should be called.MIO_DeleteAll()marks all configured M modules as unused and frees all occupied resources. Before using any M module again, the associated MIO_Mxx_Config() function has to be called again.
8.3.2 MIO and M-Module Information
MIO_GetVersion()
Function prototype
const char *MIO_GetVersion(void)
Description
This function returns a string with some information of the MIO software module. The string looks like
155 MIO – M-Module Input/Output
Administrative Functions
mio.o lynx4 1.0.3 2005-07-07
and contains the name of the MIO software module (mio.o), the target architecture (lynx4), the version of the module and the compilation date. This identification is used to check, if the header file which you use when compiling your application, matches the used MIO soft-ware module.
MIO_ModuleInfo()
Function prototype
char *MIO_ModuleInfo(int Slot, MIO_Type ModuleType)
Description
Returns a description for a M module. IfSlothas a valid value – which means that there is a module found atSlot– thenMIO_ModuleInfo()returns a description of this module. IfSlot has an invalid value (e.g. -1), then a description for a M module of typeModuleType is returned.
MIO_ModuleShow()
Function prototype void MIO_ModuleShow(void)
Description
This function prints configuration information for all registered M modules to stdout. Please use this function for debugging purpose, only.
8.3.3 VME Bus Interrupt Handling
MIO_SetIntrHandler()
Function prototype
void MIO_SetIntrHandler(int Slot, int IntrLevel, int IntrVecNo, int ExternalDTACK)
Description
This function configures the MC68C153 compatible interrupt controller on the MEN M mod-ule carrier boards A201, B201 and B202.
The location of the M module is specified bySlot. To activate interrupts for the given M mod-ule, the interrupt controller atSlotis programmed with the interrupt levelIntrLevel(0 .. 7) and the interrupt vectorIntrVecNo(valid range is 48 .. 255 for VME bus I/O interrupts under LynxOS). The flagExternalDTACKspecifies, if the M module atSlotgenerates the interrupt vector and the/DTACKsignal on its own (ExternalDTACK = 1), or if this has to be done by the interrupt controller (ExternalDTACK = 0),.
156 MIO – M-Module Input/Output
Administrative Functions
MIO_VMEIntrDisable()
Function prototype
void MIO_VMEIntrDisable(void)
Description
This function disables interrupts for all mounted M modules by configuring the MC68C153 compatible interrupt controller on the MEN M module carrier boards A201, B201 and B202.
MIO_VMEIntrEnable()
Function prototype void MIO_VMEIntrEnable(void)
Description
This function (re-)enables interrupts for all mounted M modules by configuring the MC68C153 compatible interrupt controller on the MEN M module carrier boards A201, B201 and B202.
8.3.4 Shared Memory Management
MIO_GetShMem()
Function prototype
char *MIO_GetShMem(tMIO_SharedMem *shmem)
Description
With LynxOS, the only way to allocate physical contiguous memory in user processes are Shared Memory Objects. Physical contiguous memory is required, if both, user process and kernel, need to access a portion of memory simultaneously, especially if the memory has to be accessed within an interrupt routine.
A Shared Memory Object is identified by an unique name, which has to be constructed according the standard path name rules. Once created, a Shared Memory Object can be accessed by other processes, too. It continues to exist even after the creating process ter-minates.
The functionMIO_GetShMem()creates a Shared Memory Object and maps physical contigu-ous memory to it. The name and the desired size for the Shared Memory Object is passed through the pointer*shmem to a data structure of typetMIO_SharedMem:
Listing 8.3: ThetMIO_SharedMem struct
1: typedef struct { 2: char *Addr;
3: int fid;
4: int Len;
5: char *Name;
6: } tMIO_SharedMem;
157 MIO – M-Module Input/Output
Administrative Functions
MIO_GetShMem()takes the name, pointed to by the data field*Name, to open a new Shared Memory Object with the system callshm_open(). If a Shared Memory Object with the same name already exists, it will be deleted first. The file descriptor of the newly created Shared Memory Object will be stored in the data fieldfid.
The desired size of the Shared Memory Object is specified by the data fieldLen. IfLenis not a multiple of the page size (4 kB),Lenwill be rounded up to the next multiple of the page size. The size of the Shared Memory Object is set with the system callftruncate().
The next step is to map physical contiguous memory to the Shared Memory Object ofLen bytes. This is done with the system callmmap(). The address to the mapped memory region is stored in the data field*Addr.
If the creation of the Shared Memory Object was successful, MIO_GetShMem()returns a pointer to the mapped memory region. Otherwise,MIO_GetShMem()returns theNULLpointer.
MIO_RemShMem()
Function prototype
void MIO_RemShMem(tMIO_SharedMem *shmem)
Description
Shared Memory Objects, that were created by the functionMIO_GetShMem(), can be deleted with a call to functionMIO_RemShMem().
Again,MIO_RemShMem()takes a pointer to the data structuretMIO_SharedMem(seeListing 8.3), which contains the address to the mapped memory region (*Addr), the file descriptor to the Shared Memory Object (fid), the length of the mapped memory region (Len) and the name of the Shared Memory Object (*Name).
MIO_RemShMem()first unmaps the mapped memory region at *Addrwith the system call munmap()and closes the Shared Memory Object by calling the system callclose(). After that, the Shared Memory Object is deleted with the system callshm_unlink().
Withshm_unlink(), the Shared Memory Object is deleted immediately only, if there are no other references to it. If there are still references – e.g. by another process – then the Shared Memory Object will only be marked for deletion. Only if all file descriptors to it have been closed, the Shared Memory Object will be finally deleted. This might cause problems, if you recreate a formerly deleted Shared Memory Object again, while another process accesses the Shared Memory Object, too.
8.3.5 Error Handling Functions
MIO_ErrorGet()
Function prototype
int MIO_ErrorGet(tMIO_ErrCode *ErrCode, const char **ErrMsg)
158 MIO – M-Module Input/Output
Administrative Functions
Description
If errors occur during a call toMIO_xx()functions, an error message and a description is generated and stored in an internal error list. This list holds up to 10 errors, which can be obtained with the functionMIO_ErrorGet().
MIO_ErrorGet() takes the oldest error in the list and writes the error code to the variable pointed to by*ErrCode. A pointer to the error message is stored in the variable pointed to by**ErrMsg. The error message contains a brief description of the error, which is very useful to find the reason of the error.
A return value < 0 indicates, that there was an error while returning the error – usually, this happens only, if either*ErrCodeor**ErrMsgareNULL. A return value >= 0 indicates that there are remaining errors, including the one which is returned at the same time. If there are no more errors available, then 0 is returned.
IfMIO_ErrorGet() returns an error, then the error is also deleted from the list.
MIO_ErrorClear()
Function prototype void MIO_ErrorClear(void)
Description
This function clears the list of errors, even if no errors were requested with the function MIO_ErrorGet().
159 MIO – M-Module Input/Output
M-Module Function Description