Home

RadiSys ARTIC960 Programmer`s Reference

1. GetQueue Get or Peek at an Element on a Queue seen eene SearchQueue Search a Queue for an Element eene enne enne nennen CreateMbx Create a Mailbox OpenMbx Open a Mailbox GetMbxBuffer Get a Free Mailbox FreeMbxBuffer Free Mailbox SendMbx Send a Message ReceiveMbx Receive a Message CloseMbx Close a Mailbox CreateSig Create a Signal OpenSig Open a Signal CloseSig Close a Signal InvokeSig Call a Signal Device Driver Subsystem Services CreateDev Register a Subsystem or Device DEIV6et uie beo ti erbe eerie EE REEE OpenDev Open a Subsystem or Device Driver nennen CloseDev Close a Subsystem or Device nemen eene InvokeDev Call a Subsystem or Device Driver esessesesssseseeeeeeeeee nennen AllocVector Allocate an Interrupt Vector eseesesseeeeeseeeeeeeeennen eene nre nre enne AllocVectorMux Allocate an Interrupt nnne SetVector Set a New Interrupt Vector Entry Point seseeeeseeeseeee eene ener SetVectorMux Set an Interrupt trennen ennt eere Return
2. 8 ARTIC960 Support for AIM sais cdl GEA isi wen t Ga deen SUN ee elie 10 Supported ARTIC960 Configurations eeeeeeeeeseeeen eene nennen trennen nete enne trennen eee 10 Device Driver Installation erre rrr Ee ei rere Eee eee te regn 11 Mailbox Process riCMDX cccccccsscccecesssssececesessceccecsesceceeceesssececesensaesesesesesaeeeeceseseeeecesesssaeeeecessaaees 11 Error d 13 Trace iTi v L E 13 ARTIC960 Support for Windows 14 Supported ARTIC960 Configurations eeeseeseesees esent 14 Device Driver Installation esee tenen tenen 14 Mailbox PROCESS pe 14 Event COS DINE ER 14 Chapter 2 ARTIC960 Kernel Services sss 15 Summary EP EKE E RAVER ETSE NRS 15 Parameter bg RC M 18 Chapter 3 Base Kernel Services um tele 21 Process Management SorviCeS M 22 CompleteInit Mark Process as Completely Initialized sese 23 Quer
3. 222 Record Description Example Data in Words Trace Record 0x0033 222 Status Utility Syntax tede nire Minis hea eiit mte Edi dte eR 224 Formatted DUMI M 226 Status Utility M in Menu veiene ee irte a ei eta 228 Status Utility Configuration Display nennen eren 229 Status Utility Process Summary Display essere ene 230 Status Utility Resource Summary Display sese nennen 231 Status Utility Memory Display eene nennen nennen nere enne 232 Status Utility Process Details Display sesseeseseeeeeene eene 233 Process Details Display Process Terminated by Software Event sess 234 Process Details Display Process Terminated by Processor Event 235 Process Details Display Process Terminated by Adapter Event sss 236 Status Utility Process Resources Display eene 237 Status Utility Process Parameters Display seen nennen 238 Resource Details Submenu eec cient tht deseen ttn sinere eta esae eenei iek 239 Device Driver Detail Display tte eise tue deed e HE Ete edi 240 Byent D tail DIS plays te er
4. Return Code Description 0x00000000 RC_SUCCESS No error occurred 0x00000006 RC SU INVALID HANDLE In OS 2 an invalid handle was passed to the call 0x00000009 RC SU INVALID HANDLE In AIX an invalid handle was passed to the call 0x00000013 RC SU OPEN FAILED In AIX this error indicates the driver is not installed 0x0000006E RC SU OPEN FAILED In OS 2 this error indicates the driver is not installed 0x00010001 RC ADAPTER EXCEPTION A terminal adapter exception condition has been detected on the adapter 0x00010002 RC DUMP ACTIVE The command was aborted by a dump of the adapter or the request or command cannot be issued because a dump is active 0x00010003 RC NO ADAPTER RESPONSE This error indicates a severe adapter error This code is returned when the adapter fails to pass the power on self test at power on or after a reset 0x00010004 RC RESET ACTIVE A reset is currently active on the destination unit 0x00010005 RC RESET FAILED The card failed to reset properly This error usually indicates defective hardware This error may also be returned because of either user specified timeouts or internal driver timeouts during API calls 0x00010006 RC SCB TRANSFER FAILED An error occurred when trying to transfer data using a subsystem control block 0x00010007 RC SYSTEM ERROR An unexpected system error occurred Under AIX more information about the error condition can be found in errno 0x00010008
5. 241 Mailbox Detail Display EET EET 242 Memory Detail DISplay dM 243 Queue Detail Display eter eet ERE RR 244 Semaphore Detail Display eie deseen cota tete coetus ci eee sere eee 245 Signal Detail Display ined Sus dee enfermedades 246 Timer Detail Display 247 Hardware Device Detail Display oo eee eee nennen 248 Vector Detail Display ient iere tit aeree ette hito eei pese 249 Status Utility Exception Conditions Display essere nennen 250 Status Utility VPD Information Display essere ennemi 251 Displayed VPD Information for Intel based Systems seen 251 Displayed VPD Information for RISC System 6000 seen 251 Figures ix X 6 43 6 44 6 45 6 46 6 47 6 48 6 49 6 50 6 51 6 52 6 53 6 54 6 55 6 56 6 57 6 58 6 59 6 60 6 61 6 62 6 63 6 64 6 65 6 66 6 67 Status Utility 80960 Registers Display 252 Example Screen Configuration esssesseeseeseeeeeeenen rennen rennen nennen 253 Example Screen Process Summary sss ener rennen nennen
6. opened 4 Enter process name or ID gt 6 Name Handle Type PRS procab rel 0x03040586 emory PRC procab rel 0x0304058B emory PRD procab rel 0x03040589 emory BMJ PAMO5BJ 0x02040588 emory STM procab rel 0x020A0582 timer BS PAM 0x02070581 semaphore BXNPAM 0x0203058A nailbox EM buffa 0x02040583 nemory QSMNErrMsg 0x02070580 semaphore QUE ErrMsg 0x02060584 queue SEM 0x0207057F semaphore M Figure 6 52 Sample Screen Process Resources 256 ARTIC960 Programmer s Reference Examples of Interactive Messages 7 Process Parameters Enter process name or ID gt Mason argv 0 Mason argv 1 Get argv 2 off argv 3 the argv 4 table argv 5 you argv 6 stupid argv 7 cat M 2 Figure 6 53 Example Parameters 8 Resource Details The following are example screens for resource details S Enter resource name or handle gt 0101057A Resource type driver Driver name SDD_PortDriver Process name PRC DriverX Protection disabled Access list Proc No Process Name Handle 0x0005 PRC_Driverx 0x0101057A 0x0006 PRC inproc rel 0x01010569 0x0007 PRC outproc rel 0x0101055C M 2 Figure 6 54 Example Screen Device Driver Detail Enter resource name or handle gt 0102055F Resource type event Name EVN EVENT 01 Semaphores SEM ProcessSyncl SEM ProcessSync 2 SEM Access list Proc No Process Name H
7. Returns RC SUCCESS RC INVALID RESERVED PARM RC ADAPTER EXCEPTION RC NO ADAPTER RESPONSE RC BUFFER TOO SMALL RC SU INVALID HANDLE RC INVALID MEM ACCESS RC SYSTEM ERROR AIX only RC INVALID SIZE Remarks following information is returned in the RIC_CONFIG structure Card and slot numbers Window sizes and locations Memory sizes AIBID The SlotNum field is not supported when using the ARTIC960 PCI ARTIC960Hx or ARTIC960Rx adapters The value returned should not be used at this time For more details on the information returned by this structure see RIC_CONFIG Structure on page 290 When either RC ADAPTER EXCEPTION or RC NO ADAPT ER R ESPONSE 15 returned most of the configuration data is not valid The partial data that is returned on these errors includes only the logical card number slot number and system bus base I O address The return code RC INVALID MEM ACCESS cannot be received in OS 2 If the driver detects an access violation OS 2 terminates the process with a trap unless the application has an exception handler registered with OS 2 ARTIC960 Programmer s Reference RiCGetVersion Get Version Number RIC GetVersion Get Version Number This routine is used to obtain the version numbers of all of the installed ARTIC960 software The structure returned includes major and minor version numbers for
8. Explanation An error was received when attempting to access file yyyyyyyy Action Verify that the file still exists and is accessible If the file exists make sure that no other applications are accessing the file or have a lock on it For output files verify that the destination file is write accessible and that the disk is not full Source Applicatio Loader Dump Status Configuration and Mailbox Process RICO005 Invalid card number nn Explanation The specified logical card number is invalid The card number is either nonnumeric or out of range Action Correct the card number and reissue the command Source Application Loader Dump Status Configuration Reset RICO006 Insufficient storage Explanation There is not enough free storage to complete the request Action On a load operation this indicates that there is not enough free memory available on the card Either reduce the amount of memory required by the process free up storage on the adapter or install more memory on the adapter During Mailbox Process initialization this message indicates there is not enough system unit memory to allocate the threads memory pools Reduce the values set for any of the following in the mailbox configuration parameter file MAX GLOBAL MAILBOX MAX REMOTE MBX MAX REMOTE MAILBOX OPEN MAX REMOTE MAILBOX SEND MAX REMOTE MAILBOX RCV MAX NUM OF UNITS Source Application Loader Mailbox Process 296 X ARTIC960 Programmer s Refer
9. RIC0024 XXXXXXXX Successfully started on card nn Explanation The process xxxxxxxx was successfully started on logical card nn Action None Source Application Loader RIC0025 XXXxxxxx already started on card nn Explanation The process xxxxxxxx was already running on logical card nn Action Either stop and restart the process or let it run Source Application Loader RIC0026 File format error in file Internal error xxxxxxxx Explanation The file yyyyyyyyy is not in the proper format The Application Loader returns this when a process file does not have the proper executable format The Status utility returns this message when a dump file does not have the proper format The error code xx is an internal error code that indicates the problem detected in the file Action When reported by the Application Loader recompile and relink the process in error with the proper options When reported by the Status utility the dump file is probably corrupted the card must be dumped again Source Application Loader Status RIC0027 Correct syntax is TI ricload C config filename path Q Explanation Action Source card_num filename A process_args F arg_filename D cache_option K stack size W timeout N process name O P priority T V S process_name W timeout Eu U process name Application Loader utility syntax help message Select the proper
10. Returns RC_SUCCESS RC INVALID MEM ACCESS RC INVALID HANDLE RC INVALID CALL RC INVALID RESERVED PARM RC INVALID OPTION RC QUEUE EMPTY RC INVALID TIMEOUT Remarks If the QUE READ bit of OptionWord is set and if more than one process is reading the queue each may get a pointer to the same queue element Chapter 3 Base Kernel Services 101 SearchQueue Search a Queue for an Element SearchQueue Search a Queue for an Element 102 This service searches a queue for a queue element and optionally removes it from the queue Functional Prototype RIC_ULONG SearchQueue RIC_QUEHANDLE QueueHandle void Element RIC ULONG OptionWord RIC ULONG KeyValue RIC ULONG KeyOffset RIC ULONG KeyMask RIC ULONG Reserved Parameters QueueHandle Input Handle of queue to search for element Element Output Pointer to queue element OptionWord Input Option word indicating how to do search QUE SEARCH ADDRS If ORed with OptionWord the KeyValue parameter is an element address to search for QUE SEARCH KEY If ORed with OptionWord the KeyValue is a key value within the queue elements to search for If the queue element is found QUE GET If specified the element is removed from the queue and the queue s semaphore is decremented QUE READ If specified the pointer to the element is returned and the queue element is not removed
11. 253 Example Screen Resource Summary sess 254 Example 254 Example Screen Process Details 0 00 0 sssesscessesscesssencenssenseneseneconssee soeeneessessseessesssensesereee 254 Example Screen Process Terminated by Software Event 255 Example Screen Process Terminated by Processor Event eee 255 Example Screen Process Terminated by Adapter Event sese 256 Sample Screen Process Resources rennen nennen nennen nente tnmen eren 256 Example Screen Process Parameters seseseeseerererersereusrerereererererereererenreerusrerererrrrersrererreere 257 Example Screen Device Driver Detail sesessssssseeseeeeeeenne nennen nennen 257 Example Screen Event Detail eese enne enne en nennen nennen trennen 257 Example Screen Mailbox Detail eese eene eren enne 258 Example Screen Memory Detail sese nennen 258 Example Screen Queue Detail eese ener ener emen trementes 259 Example Screen Semaphore Detail essent entrent nennen 259 Example Screen Signal Detail 0 0 cece ceeceseeseceseeseceeeeseseneceeecaeesaecaecsaecaesaeeseseeeeseseeeeees 259 Example Screen Timer Detail
12. Message Number Exit Code Notes RICO001 RC UTIL INVALID CMDLINE OPTION RICO0005 RC UTIL INVALID CARD NUMBER RICO009 RC_UTIL_RESET_FAILED This message is followed by message RIC0034 RIC0010 RC_UTIL_NO_ADAPTER_RESPONSE This message is followed by message RIC0034 RIC0019 RC_UTIL_NOT_INSTALLED RICO031 RC UTIL WRNHELP GIVEN RIC0032 None Information only message RICO033 RC UTIL SUCCESS Successful reset operation RIC0034 None Exit code depends on preceding message RICO09 or RICO010 RIC0038 RC UTIL ACCESS ERROR Chapter 6 System Unit Utilities 211 Trace Utilities Trace Utilities The ARTIC960 kernel supports tracing of selected kernel services and user definable services Three system unit utilities support tracing of services on the card Set Trace Get Trace and Format Trace e Set Trace initializes enables and disables tracing of specified services e Get Trace reads the trace buffer log on the card and stores it on the system unit in a user definable trace file Format Trace formats the trace file into a user readable format 212 ARTIC960 Programmer s Reference Set Trace Utility Set Trace Utility The Set Trace utility initializes enables and disables tracing of various service classes on the ARTIC960 adapter There is a defined set of kernel service classes that can be specified The defined service classes are listed under EnableTrace Enable Tracing of Service Classes on page
13. char DeviceName DEVICE NAME SIZE RIC PROCESSID ProcessID RIC ULONG PostStatus ULONG DataSize unsigned char DeviceData MAX DATA SIZI Lu Chapter 3 Base Kernel Services 135 ReturnHW Return a Hardware Device ReturnHW Return a Hardware Device 136 This service returns a previously allocated hardware device Functional Prototype RIC_ULONG ReturnHW char DeviceName RIC ULONG Reserved Parameters DeviceName Input Name of the hardware device to return Reserved Input Reserved parameter must be 0 Returns RC INVALID RESERVED PARM RC INVALID MEM ACCESS Remarks None ARTIC960 Programmer s Reference QueryHW Query Status of Hardware Device QueryHW Query Status of Hardware Device This service returns the status of a hardware device to the calling subsystem or device driver Functional Prototype RIC_ULONG QueryHW char DeviceName RIC_ULONG BufferSize RIC_ULONG Status RIC_ULONG POSTStatus unsigned char DeviceDataPtr RIC ULONG Reserved Parameters DeviceName Input Name of the hardware device requested by this service This name is predefined for each type of device BufferSize Input Size of the buffer pointed to by DeviceDataPtr The kernel copies device related data to this buffer If the buffer is too small the kernel copies BufferSize amounts of data into the buffer and re
14. Return Code VALUE RC_ADAPTER_EXCEPTION 0x00010001 RC_ALREADY_INITIALIZED 0x00010209 RC BAD QUEUE ELEMENT 0x8001 1601 RC BAD CONFIG PARAM 0x0001 1201 RC BUFFER TOO SMALL 0x00010019 RC CALL TERMINATED 0x00010105 RC CANT STOP SHARING 0x00010303 RC CLOSE ENTRY FAILURE 0x00010A04 RC CMD NOT DELIVERED 0x00010E02 RC DD RC OUT OF RANGE 0x00010A06 RC DEPENDENT EVENTS 0x00010403 RC_DEVICE_DRIVER 0x00010206 RC_DMA_TRANSFER_FAILED 0x00010021 RC_DUMP_ACTIVE 0x00010002 RC_DUMP_NOT_ACTIVE 0x00010009 RC_DUP_ASYNC_EVENT 0x00010D01 RC DUP RES HANDLES 0x00010503 RC DUP RES NAME 0x00010101 RC ELEMENT NOT FOUND 0x00010802 RC ENTITY ALREADY REGISTERED 0x00010010 RC ENTITY NOT FOUND 0x00011102 RC ENTITY NOT REGISTERED 0x0001001 1 RC HANDLE CLOSED 0x0001000A RC HOOK ALREADY REGISTERED 0x00010F01 RC HOOK NOT REGISTERED 0x00010F02 RC HW ALREADY ALLOCATED 0x00010C01 RC HW NOT ALLOCATED 0x00010C02 RC INVALID ADDRESS 0x0001001A RC INVALID ALIGNMENT 0x00010307 RC INVALID BASEPTR 0x00010302 RC INVALID CALL 0x00010104 RC INVALID CALLER POSITION 0x0001 1004 RC INVALID CARD NUMBER 0x0001000D RC INVALID CMD DEST 0x00010E01 RC INVALID COMMAND 0x00010E03 RC INVALID COUNT 0x00010014 RC INVALID ENTITY NUMBER 0x00010012 RC INVALID EVN MASK 0x00010501 RC INVALID FUNCTION CODE 0x00010108 RC INVALID HANDLE 0x00010020 RC INVALID HOOK 0x00010F03 RC INVALID MBX BUFFER ADDR 0x00010905 RC INVALID MEM ACCESS 0x0001001B RC INVALID MSG BUFFER 0x00010908 RC INVALID NAME 0x0
15. sese eee en entree nennen 260 Example Screen Hardware Device Detail sese 260 Example Screen Vector Detail sessi ener nnne nennen 260 Example Screen Exception Conditions essent 261 Example Screen V PD Information for PS 2 Systems ooo eee ee sse 261 Example Screen V PD Information for RISC System 6000 see 261 Example Screen 80960 Registers esses 262 ARTIC960 Programmer s Reference Tables 1 1 1 2 1 3 1 4 1 5 2 2 6 5 6 7 6 8 6 9 6 10 6 11 6 12 Adapters Supported by Each Operating System sess emen 1 Parameters de 4 OS 2 Driver M UEM 8 OS 2 Mailbox Process Messages 9 AIX Mailbox Process Messages 13 ARTIC960 Kernel Services x aH RESO MIHI Me ERU e e SUR 15 Iwan dh lg 18 Service Class C ASYNC EVENT SERVICE eterne 156 Service Class C DEVICE DRIVER SERVICE eere nne 156 service Class C EVENT SERVICE 157 Service Class C HOOK SERVICE 157 Service Class C INTERRUPT SERVICE 157 Service Class 157 Service Class
16. Sw Field The SW field in AsyncEvent has the following definition struct RIC_SoftwareEvent union RIC_DEVHANDLE DevHandle struct RIC SharedRsrcClose ShrRes Swinfo where DevHandle Device handle in the case of device driver termination ShrRes Structure of information related to the closing of shared resources The ShrRes field in SoftwareEvent has the following definition struct RIC_SharedRsrcClose RIC_ULONG ResType RES_HANDLE ResHandle RIC_ULONG OpenCount RIC ULONG Resinfo where ResType Number indicating the type of the resource being closed ResHandle Resource handle OpenCount Number of processes that have the resource open Resinfo Resource specific information Memory Contains a base pointer Mailbox TRUE if the creator is closing Semaphore TRUE if the semaphore is MUTEX and the owner is closing Events FALSE always Signals The number of receivers remaining Queues FALSE always 144 ARTIC960 Programmer s Reference DeregisterAsyncHandler Deregister an Async Handler DeregisterAsyncHandler Deregister an Async Handler This service deregisters the asynchronous event notification handler of a process for specified events Functional Prototype RIC_ULONG DeregisterAsyncHandler RIC_ULONG SwEvents RIC_ULONG HwEvents RIC_ULONG PrEvents RIC_ULONG Reserved Parameters SwEvents Input Mask specifying of which software events the proces
17. ULONG Reserved Parameters ProcessID Input Process ID of the process that is to be unloaded A value of 0 means that the calling process is unloading itself Reserved Input Reserved parameter must be 0 Returns RC SUCCESS RC INVALID RESERVED PARM RC INVALID PROCESSID RC INVALID CALL RC PERMANENT PROCESS RC DEVICE DRIVER Remarks The kernel calls the exit routine of the process before unloading the process if the process had been started All the resources acquired by the process are released The kernel releases the code data parameter and stack memory areas of the process The process cannot be restarted without being reloaded When process is stopping another process the requesting process will not run until the stopping process has completely stopped including execution of its exit handler Locally only a device driver subsystem can unload a device driver subsystem The system unit can unload a device driver subsystem through the U parameter of the Application Loader utility see Application Loader ricload Utility on page 196 for details about the utility or through a global mailbox command to a kernel mailbox from any unit see Chapter 4 Kernel Commands on page 163 for details about mailbox commands ARTIC960 Programmer s Reference SuspendProcess Suspend a Process SuspendProcess Suspend a Process This service suspends a process I
18. CommandNum in the common header must be set to KERN_REG_RESP_MBX RespMbxld in the common header is not defined for this command Structures struct RIC RegisterResponseMbxCmd char MbxName MAX RES USER ULONG Reserved where MbxName Response mailbox name Reserved Reserved field must be 0 Response Parameters ReturnCode values in RIC KernResponse are RC SUCCESS The following shows the variant part of the response for this command struct RIC RegisterResponseMbxResp RIC_RESPMBX RespMbxID RIC_ULONG Reserved where RespMbxID Identifier used on all subsequent kernel commands Reserved Reserved field must be 0 Remarks This command must be issued prior to any other commands being issued It is the user s responsibility to issue a DeRegisterResponseMbx command when the application terminates ARTIC960 Programmer s Reference DeRegisterResponseMbx Deregister a Command Response Mailbox DeRegisterResponseMbx Deregister a Command Response Mailbox This command removes a response mailbox when its ID is specified Command Parameters CommandNum in the common header must be set to KERN_DEREG_RESP_MBX Structures struct RIC_DeRegisterResponseMbxCmd RIC_RESPMBX RespMbxID RIC_ULONG Reserved where RespMbxID Response mailbox identifier Reserved Reserved field must be 0 Response Parameters
19. KeyValue Input Either the address of the element to search for or the value with the queue element to search for KeyOffset Input If the QUE SEARCH KEY is set this parameter indicates the offset within the queue element where the key value is found The key word must be located on a word 4 byte boundary KeyMask Input If the QUE SEARCH KEY is set this parameter indicates the mask to be ANDed with the key word before comparing it with the Key Value Reserved Input Reserved parameter must be 0 ARTIC960 Programmer s Reference SearchQueue Search a Queue for an Element Returns RC_SUCCESS RC ELEMENT NOT FOUND RC INVALID HANDLE RC INVALID MEM ACCESS RC INVALID RESERVED PARM RC INVALID OPTION Remarks If the queue element is not found control returns to the calling process This service will not wait until a queue element arrives that satisfies the search criteria Chapter 3 Base Kernel Services 103 CreateMbx Create a Mailbox CreateMbx Create a Mailbox This service creates a mailbox and gives access to the requesting process Functional Prototype RIC_ULONG CreateMbx char MbxName char MbxRxMemName RIC ULONG sgUnitSize RIC ULONG sgUnitCount RIC ULONG OptionWord RIC MBXHANDLE MbxHandle RIC SEMHANDLE SemHandle ULONG Reserved Parameters MbxName Input A mailbox na
20. EM AIB WRITABLE The current daughter board access to the created memory is overridden The default is daughter board access is not changed The daughter board DMA can read from memory The default is memory cannot be read or written by the daughter board DMA The daughter board DMA can write to memory The default is memory cannot be read or written by the daughter board DMA Chapter 3 Base Kernel Services 65 CreateMem Allocate Memory MEM_DCACHE Memory is cachable The default is that memory is not cachable This option should not be used for memory that is accessed by other masters This option is ignored if data cache hardware is not present on the adapter or if data cache has not been enabled through the kernel configuration DATA_CACHE parameter MEM_BIG_ENDIAN The big endian address of the allocated memory is returned The byte order of the allocated memory is big endian By default all memory is treated as little endian If the kernel does not support big endian memory regions RC_INVALID_OPTION is returned The kernel supports only big endian memory regions on the ARTIC960Hx adapter 66 ARTIC960 Programmer s Reference OpenMem Get Addressability to Allocated Memory OpenMem Get Addressability to Allocated Memory This service gets addressability to memory allocated by another process Functional Prototype RIC_ULONG OpenMem char MemName RIC_ULONG Access void
21. Device Driver Installation Two pieces of code provide the AIX support the device driver and a daemon process The ARTIC960 AIX device driver ricio is installed through the AIX Configuration Manager at system boot time It is a multiprocessing safe MP Safe device driver Mailbox Process ricmbx The mailbox process ricmbx is a daemon process that works in conjunction with the device driver to handle remote mailbox processing Version 1 3 of ricmbx added the support for the first ten ARTIC960 adapters numbers 0 through 9 Mailboxes can be used locally on the adapters 10 and above but the system unit mailboxes will not be able to communicate remotely Mailbox Process Call Configuration parameters must be supplied on the command line or through a configuration file The mailbox process must be loaded prior to any application process calls to mailbox services You can start the mailbox process at system boot time by adding a line to the etcinittab file Chapter 1 Loading and Configuring 11 12 The mailbox process is called using the following syntax The superuser authority is required to start the mailbox process l T1T ricmbx ath p C config filename path K Figure 1 3 AIX Mailbox Process Syntax C config filename Specifies that the contents of the file config filename should be used as input to the mailbox process for configuration parameters K Kill the active mailbox process sup
22. Enter process name or ID gt ame SSSSSSSSSSSSSSSS ID nnnnnnnn Priority nnnnnnnn Entry point nnnnnnnn Stack pointer nnnnnnnn Param pointer nnnnnnnn State SSSSSSSSSSS Version nnnnnnnn Type SSSSSSSSSSS Termination Code adapter Trap Type SSSSSSSSSSSSSSSS Memory Address nnnnnnnn Code Address nnnnnnnn Figure 6 25 Process Details Display Process Terminated by Adapter Event 236 ARTIC960 Programmer s Reference Status Interactive Messages 6 Process Resources The following screen shows the prompts and items displayed when the Process resources option is chosen from the main menu The display format is identical to the Resource summary on page 231 except that only the resources for the selected process resources are displayed The output line is repeated for each resource See Figure 6 52 on page 256 for an example EN Enter adapter number gt Enter process name or ID gt Name Handle Type SSSSSSSSSSSSSSSS nnnnnnnn 555555555 M J Figure 6 26 Status Utility Process Resources Display Chapter 6 System Unit Utilities 237 Status Interactive Messages 7 Process Parameters The following screen shows the prompts and items displayed when the Process parameters option is chosen from the main menu The output line is repeated to display all parameters See Figure 6 53 on page 257 for an example f N Enter adapter number gt Enter process name or ID gt argv nn ss
23. Functional Prototype RIC_ULONG RegisterAsyncHandler Parameters Software Events RIC_ULONG SoftwareEvents RIC_ULONG AdapterEvents RIC_ULONG ProcessorEvents RIC_ASYNCHANDLER AsyncHandler RIC_ULONG Reserved Input Mask specifying of which software events the process wants to be notified The software event mask is built by ORing the following event flags together The event flags can be used to build the software event mask A EN DI EV TERM A A A AdapterEvents EN P EN P ROCESS START ROCESS STOP EN 5 HARED RESOURCE Device driver or subsystem termination Process start Process stop Closing a shared resource Input Mask specifying of which adapter events the process wants to be notified You can OR the following event flags together to form the adapter event mask A A EN WATCHDOG EN PARITY EM PROCESSOR EM MICROCHANNEL AIB b EM VIOLATION td 2 PCI ERROR Watchdog timer expiration Parity error e Multiple bit ECC error e AIB bus read parity error with 80960 master e Local bus parity for RadiSys ARTIC 32 bit Memory Controller Chip System bus Interface Chip CFE Local Bus AIB Interface Chip Memory protection violation 80960 processor Memory protection violation system bus master Memory protection violation AIB master Non existent memory access by t
24. RIC ULONG Regions Offset to next entry RIC_ULONG TimeStamp Time Date Stamp DUMPFILEHDR DumpInfo 31 PMCFILEHEADER typedef struct DUMPFileHeader RIC_ULONG AddressDump Address to dump RIC_ULONG LengthDump Amount to dump RIC ULONG Offset Offset into the binary dump file to locate information for this entry RIC ULONG Reserved DUMPF ILEHDR 204 ARTIC960 Programmer s Reference Dump Utility Example of a PMC_cfgfile Dump File The following is an example of the binary file created with the O option when viewed with a binary editor 0x00000000 BAAB EDFE 0002 0000 0200 0000 7A08 1236 0x00000010 0010 FAIF 2800 0000 0002 0000 0000 0000 0x00000020 0010 1B1F 2500 0000 2802 0000 0000 0000 0x00000030 0000 0000 0000 0000 0000 0000 0000 0000 0x00000040 0000 0000 0000 0000 0000 0000 0000 0000 0x00000050 0000 0000 0000 0000 0000 0000 0000 0000 0x00000060 0000 0000 0000 0000 0000 0000 0000 0000 0x00000070 0000 0000 0000 0000 0000 0000 0000 0000 0x00000080 0000 0000 0000 0000 0000 0000 0000 0000 0x00000090 0000 0000 0000 0000 0000 0000 0000 0000 0x000000A0 0000 0000 0000 0000 0000 0000 0000 0000 0x000000B0 0000 0000 0000 0000 0000 0000 0000 0000 0x000000C0 0000 0000 0000 0000 0000 0000 0000 0000 0x000000D0 0000 0000 0000 0000 0000 0000 0000 0000 0x000000E0 0000 0000 0000 0000 0000 0000 0000 0000 0x000000F0 0000 0000 0000 0000 0
25. Reserved Input Must be 0 Returns RC SUCCESS RC UNABLE TO CONVERT ADDRESS Y The compatibility of this function is not guaranteed across future releases Chapter 5 Adapter Library Routines 181 ConvertCardToMC Convert Card Address to System Bus Address ConvertCardToMC Convert Card Address to System Bus Address 182 This service converts a logical card number and local address pointer to a system bus address Functional Prototype RIC ULONG ConvertCardToMC RIC DEVHANDLE DDHandle RIC CARDNUM Card void LocalAddptr void MCAddress ULONG Reserved Parameters DDHandle Input Handle of subsystem returned by OpenDev of System Bus I O Susbystem Card Input Logical card number for local address LocalAddptr Input Local address to be converted MCAddress Output Converted system bus address Reserved Input Must be 0 Returns RC_SUCCESS RC INVALID CARD NUMBER v The compatibility of this function is not guaranteed across future releases ARTIC960 Programmer s Reference PCI Local Bus Configuration Device Driver Services PCI Local Bus Configuration Device Driver Services The kernel provides the following adapter PCI local bus interface services Service Page pciBiosPresent 184 pciFindDevice 186 pciFindClassCode 187 pciReadConfigByte 188 pciReadConfigWord 189 pciReadConfigDWord 190 pciWriteConfigByte 191 pciWr
26. 0x00000002 Service Classes Enabled 3 7 M Figure 6 12 Trace Control Block Example 2 Service Class 0x07 C_MAILBOX_SERVICE Procedure ID 0x03 P_OPENMBX Caller Position 0x00 PROCEDURE ENTRY Data Size 0x00000005 Process In Exec PRC rmblpreb rel Data Bytes 4D 42 58 31 00 1 V P Figure 6 13 Record Description Example Data in Bytes Trace Record 0x002E Service Class 0 03 Procedure ID 0x07 Caller Position OxFF Data Size 0x00000004 Process In Exec Data Words 00000000 M C SEMAPHORE SERVICE P RELEASESEM PROCEDURE EXIT PRC RIC Mbx SS A Figure 6 14 Record Description Example Data in Words Trace Record 0x0033 222 ARTIC960 Programmer s Reference Status Utility Status Utility The Status utility is a development tool used to examine the state of the ARTIC960 adapter This utility can operate in the following states Live analysis Examines an active card in a system This is the default Post analysis Examines a raw adapter dump file that was produced by the Dump utility The following are modes to control the display of card data Interactive mode The user can interactively request the display of specific data on the card It uses the standard input stdin and standard output stdout devices This is the default Status mode The utility displays a standard set of adapter structures to the standard output device The mode is simila
27. Baseptr RIC ULONG Reserved Parameters MemName Input Name of allocated memory This should be the same as the name used to allocate the memory block Access Input Bit field specifying the access rights to the memory block These flags are sharable read write and read only The MEM_DCACHE and MEM BIG ENDIAN flags are ignored by this service The access rights do not have to be the same as the process that created the memory The memory must be sharable to be able to open it See the Remarks section under CreateMem Allocate Memory on page 64 for more information Baseptr Output Pointer to memory block Reserved Input Reserved parameter must be 0 Returns RC SUCCESS RC NAME NOT FOUND RC INVALID RESERVED PARM RC MEM SHARING ERROR RC NO MORE RES RC INVALID MEM ACCESS RC INVALID NAME RC INVALID CALL RC INVALID OPTION Remarks This service gets access to a memory block allocated with the CreateMem service provided that the memory was allocated as shareable Chapter 3 Base Kernel Services 67 CloseMem Remove Addressability to Memory CloseMem Remove Addressability to Memory 68 This service releases access to previously allocated memory Functional Prototype RIC_ULONG CloseMem void Baseptr RIC_ULONG Reserved Parameters Baseptr Input Pointer to allocated memory block Reserved Input Reserved parameter must be 0 Returns
28. MoveMCData Move System Bus Data 180 The following constants have been defined for the OptionWord parameter MOV_MEMORY Move is for a memory address default MOV IO Move is for an I O address RC INVALID OPTION is returned if The peer card is an ARTIC960Rx PCI adapter or ARTIC960RxD PCI adapter These adapters do not support I O The initiator card is an ARTIC960Rx PCI or ARTIC960RxD PCI adapter and the peer card does not have memory mapped I O MOV INCR Increment remote unit address after each byte transfer default MOV NO INCR Do not increment remote unit address after each byte transfer This option may be used to move consecutive bytes to an I O address This option is ignored by PCI devices ARTIC960 Programmer s Reference ConvertMCToCard Convert System Bus Address to Card Address ConvertMCToCard Convert System Bus Address to Card Address This service converts a system bus address to a logical card number and local address pointer Functional Prototype RIC_ULONG ConvertMCToCard RIC_DEVHANDLE DDHandle void MCAddress RIC_CARDNUM Card void LocalAddptr RIC ULONG Reserved Parameters DDHandle Input Handle of subsystem returned by OpenDev of system bus I O Subsystem MCAddress Input System bus address to be converted Card Output Logical card number represented by system bus address LocalAddptr Output Local address on the indicated logical card
29. QUE_PUT_FIFO A queue element is added to the end of the queue QueueStatus Output Returns the status of the queue QUE_EMPTY The queue went from empty to not empty QUE_NOT_EMPTY The queue already had at least one element on the queue Reserved Input Reserved parameter must be 0 Returns RC_SUCCESS RC_INVALID_HANDLE RC_INVALID_RESERVED_PARM RC INVALID MEM ACCESS RC INVALID OPTION Remarks Eight bytes must be reserved at the top of the queue element for queueing service pointers e If all elements are queued with the QUE LIFO flag on the queue becomes a virtual stack e If all elements are queued with the QUE_PUT_LIFO flag off the queue manages the elements in FIFO order as expected ARTIC960 Programmer s Reference PutQueue Put an Element into a Queue Ifthe elements are queued alternating between QUE_PUT_LIFO on and off a two priority queue is built Elements added with the QUE_PUT_LIFO flag on have a higher priority because they are put at the front of the queue Elements added with the QUE_PUT_LIFO flag off have a lower priority because they are put at the back of the queue Chapter 3 Base Kernel Services 99 GetQueue Get or Peek at an Element a Queue GetQueue Get or Peek at an Element a Queue 100 This service gets or peeks at the top element of a queue If
30. 1024 bytes for card to card pipes and 2048 bytes for system unit to card pipes C config filename Specifies that the contents of the file config filename is to be used as input to the Configuration utility Each line in the configuration file is treated as an individual configuration request The format of the file is described in Figure 6 4 To specify a config filename with spaces or special characters in the name the name must be enclosed within quotes Quotes within a name are not supported Specifies that all pipes system unit adapter and adapter adapter be configured using the default pipe sizes Specifies that system unit adapter pipes be configured using the default pipe sizes Configuration File Entry Format L card num1 comments Figure 6 4 Configuration Utility File Entry Format v Blank lines and comments in configuration files are ignored 208 ARTIC960 Programmer s Reference Configuration Utility Configuration Messages and Exit Codes The contents of the message file used by all utilities are listed in Appendix B Message File on page 295 The messages used by the Configuration utility are listed in Table 6 3 The Configuration utility also sets its exit code value to indicate the status of the configuration operation The following table correlates the exit code of the Configuration utility with its messages Table 6 3 Configuration Utility Messages and Exit codes Message
31. 3 Mailbox Resource Details Submenu The following screen shows the prompts and items displayed when a mailbox is selected from the Resource details submenu e Valid mailbox types are local global and remote The Name field is the name of the memory associated with the mailbox If no memory is associated with the mailbox nothing is displayed in this field e The entries in the Access list fields show all processes that have access to the resource e Ifthe mailbox is empty the string lt empty gt is displayed on the Messages line Otherwise the first 16 bytes of each mailbox element are displayed in the standard memory display format See Figure 6 56 on page 258 for an example gt Enter adapter number gt Enter resource name or handle gt Resource type mailbox Name SSSSSSSSSSSSSSSS Type SSSSSS Receiver SSSSSSSSSSSSSSSS Semaphore nnnnnnnn Access list Proc No Process Name Handle Memory Name nnnnnnnn Sssssssssssssssss nnnnnnnn SSSSSSSSSSSSSSSS Messages SSSSSSS aaaaaaaa hh hh hh hh hh hh hh hh hh hh hh hh hh hh hh hh CCccccccccccccccq NS J Figure 6 31 Mailbox Detail Display 242 ARTIC960 Programmer s Reference Status Interactive Messages 4 Memory Resource Details Submenu The following screen shows the prompts and items displayed when a memory is selected from the Resource details submenu e Valid strings for the AIB DMA Access and Mchl Access fields are R W
32. Base I 0 address nnnn nterrupt level nn AIB ID nnnnnnnn sssssssssss Full window address nnnnnnnn Total memory size nnnnnnnn n n MB Available memory nnnnnnnn Memory Region Size Type nnnnnnnn nnnnnnnn n n MB tttttttttttttttttttttt nnnnnnnn nnnnnnnn n n MB tttttttttttttttttttttt Press Enter to continue Figure 6 18 Status Utility Configuration Display Chapter 6 System Unit Utilities 229 Status Interactive Messages 230 2 Process Summary The following screen shows the prompts and items displayed when the Process Summary option is chosen from the main menu The output line is repeated for each process running on the adapter Valid states are loaded queued blocked suspended stopped driver waiting on PMRq expired See Figure 6 45 on page 253 for an example a Enter adapter number gt Name ID Version Priority State 5555555555555555 nnnnnnnn nnnnnnnn nnnnnnnn sssssssss Press Enter to continue Figure 6 19 Status Utility Process Summary Display ARTIC960 Programmer s Reference Status Interactive Messages 3 Resource Summary The following screen shows the prompts and items displayed when the Resource Summary option is chosen from the main menu The output line is repeated for each resource on the adapter Valid resource types are semaphore event memory timer queue mailbox signal vector driver hardware device See Figure 6 46 o
33. Base Kernel Services 79 MallocMem Allocate Memory MallocMem Allocate Memory 80 This service allocates a block of memory from the dynamic memory pool Functional Prototype void MallocMem RIC_ULONG Size ULONG OptionWord Parameters Size Input Size in bytes of memory block to be allocated OptionWord Input Bit field to describe the options to be used to allocate the memory The following constants should be ORed together to build the appropriate set of options Type of memory to create By default memory is allocated without regard to memory type If the option word is set to OPTION_PACKET_MEMORY memory is allocated from packet memory If memory protection is active the packet memory is given system bus read write access The default option is OPTION_ANY_MEMORY Data cache option for created memory By default memory is not created as cachable To create cachable memory MEM_DCACHE can be ORed into the option word This option should not be used for memory that is accessed by other masters This option is ignored if data cache hardware is not present on the adapter or if data cache has not been enabled through the kernel configuration DATA_CACHE parameter Big endian option for created memory By default memory is created little endian To create memory for big endian access MEM_BIG_ENDIAN can be ORed into the option word This option is valid only on A
34. Number of semaphores in semaphore handle array no more than 32 semaphores EvnHandle Output Event handle to be used with other event services when referring to this event Reserved Input Reserved parameter must be 0 Returns RC SUCCESS RC NO MORE EVNS RC NO MORE RES RC INVALID HANDLE RC INVALID RESERVED PARM RC INVALID MEM ACCESS RC INVALID NAME RC INVALID CALL RC DUP RES NAME RC INVALID COUNT RC DUP RES HANDLES Remarks The semaphore handle list can be any combination of explicit returned by CreateSem or OpenSem or implicit returned by other services such as queues and mailboxes semaphores A process therefore can wait for synchronization with other processes as well as resources at the same time Explicit semaphores are decremented before control returns to the process Implicit semaphores are decremented when the process calls the appropriate resource services such as removing a queue element or mailbox message ARTIC960 Programmer s Reference OpenEvent Open Access to an Event Word OpenEvent Open Access to an Event Word This service provides access to a previously created event word Functional Prototype RIC_ULONG OpenEvent char EvnName RIC EVNHANDLE EvnHandle RIC ULONG Reserved Parameters EvnName Input Event name to be accessed EvnHandle Output Event handle to be used with other event services when referri
35. Process Synchronization Services ssseeeenee CreateSem Create a Semaphore sss OpenSem Open a Semaphore sse CloseSem Close a Semaphore ssssee ReleaseSem Release Semaphore sss RequestSem Request a Semaphore sess QuerySemCount Get a Semaphore Count SetSemCount Set a Semaphore CreateEvent Create an Event Word sss OpenEvent Open Access to an Event Word CloseEvent Release Access to an Event Word WaitEvent Wait on an Event Memory Management Services sesssseeeeene CreateMem Allocate Memory eee OpenMem Get Addressability to Allocated Memory CloseMem Remove Addressability to Memory ResizeMem Reallocate Memory eere SetMemProt Change Memory Protection sess SetProcMemProt Change a Process Memory Protection QueryMemProt Query Memory QueryProcMemProt Query a Process Memory Protection QueryFreeMem Query Free InitSuballoc Prepare a Block of Memory for Suballocation GetSuball
36. RC_SUCCESS C_INVALID_RESERVED_PARM RC_INVALID_BASEPTR RC_NO_RES_ACCESS RC_INVALID_CALL Remarks This service complements the function of CreateMem and OpenMem When the last process releases access to a block of memory the memory is returned to the free storage pool and all access rights are revoked ARTIC960 Programmer s Reference ResizeMem Reallocate Memory ResizeMem Reallocate Memory This service resizes allocated memory Functional Prototype RIC_ULONG ResizeMem void Baseptr ULONG NewSize RIC ULONG Reserved Parameters Baseptr Input Pointer to allocated memory block NewSize Input New size of the memory block in bytes If the size is 0 RC_INVALID_ SIZE is returned Reserved Input Reserved parameter must be 0 Returns RC_SUCCESS RC_INVALID_RES RC INVALID RC INVALID 5121 RC INVALID CALL Lr RVED PARM PTR E Lm Remarks The size of the block can be increased only if it does not increase the number of memory pages The block can always be reduced in size Chapter 3 Base Kernel Services 69 SetMemProt Change Memory Protection SetMemProt Change Memory Protection 70 This service changes the access of a process to a block of memory Functional Prototype RIC_ULONG SetMemProt void BlockPtr RIC_ULONG Size RIC_ULONG Access RIC_ULONG Reserved Parameters BlockPtr Input Pointer to
37. RC_UTIL_INVALID_CMDLINE_OPTION RIC0002 RC_UTIL_INVALID_CMDLINE_PARM RICO003 RC_UTIL_FILE_NOT_FOUND RIC0004 RC_UTIL_FILE_ACCESS RIC0005 RC_UTIL_INVALID_CARD_NUMBER RIC0006 RC_UTIL_NO_MORE_MEM RIC0007 RC_UTIL_INVALID_NAME RICO008 RC UTIL DUP RES NAME RICO009 RC UTIL ADAPTER EXCEPTION RICO010 RC UTIL NO ADAPTER RESPONSE RICO016 RC UTIL SYSTEM ERROR RIC0019 RC_UTIL_NOT_INSTALLED RIC0022 RC_UTIL_SUCCESS Successful unload process operation RIC0023 RC_UTIL_NAME_NOT_FOUND RIC0024 RC_UTIL_SUCCESS Successful start process operation RICO025 RC UTIL ALREADY STARTED RIC0026 RC_UTIL_FILE_FORMAT RIC0027 RC_UTIL_WRNHELP_GIVEN RICO035 UTIL INVALID MICROCODE Kernel not loaded first RIC0037 RC_UTIL_MICROCODE_ERROR Microcode error RIC0038 RC UTIL ACCESS ERROR RIC0042 RC_UTIL_PROC_MISMATCH RIC0044 RC_UTIL_PROC_DID_NOT_INIT RIC0045 RC_UTIL_PROC_INIT_ERROR RICO052 RC UTIL TIMESET ERROR RIC0053 RC_UTIL_SUCCESS Successful start of System Clock RIC0054 RC_UTIL_SUCCESS Additional Information about task being loaded RIC0057 RC_UTIL_SUCCESS Successful load process operation V RC UTIL SUCCI If the Application Loader is processing a configuration file and the entire file is processed successfully
38. RIC0026 RC_UTIL_FILE_FORMAT RIC0030 RC_UTIL_WRNHELP_GIVEN None RC_UTIL_SUCCESS Normal exit RIC0038 RC_UTIL_ACCESS_ERROR RICO100 None Interactive messages menus and RIC0299 prompts Status Dump Format The following shows the format of data displayed when using the dump format mode of the Status utility rraaaaaaaa hh hh hh hh hh hh hh hh hh hh hh hh hh hh hh hh cccccccccccccccc where Is either gt to indicate repeated blocks of dataor to indicate a new block of data aaaaaaaa 15 the 32 bit address of this 16 byte block of data hh Is the hexadecimal value of each byte in the block c Is the ASCII representation of each printable character in the block or a period if the character is not printable The Status utility displays all of the memory address space contained in the dump file Gaps in memory address space are shown as a blank line See Figure 6 16 for an example of a formatted dump Chapter 6 System Unit Utilities 225 Status Utility 226 Example of a Formatted Dump This example shows e Two unique blocks of data at addresses 00100000 through 0010002r followed by a block of FFs from address 00100030 001014FF e The memory address 00101410 through 0010141F is the other unique block e The block from 00101420 0010200F is all FFs e The block from 00102010 through 0010210F contains a repetitive string e The blank line indicates a gap in memory from 00102110 001FFFFF f
39. Reserved Input Reserved parameter must be 0 Returns RC SUCCESS TERMINATED ALID RESERVED PARM ALID NAME E NOT FOUND RC NO MORE RES RC INVALID MEM ACCESS RC INVALID CALL AJ Q H z saat Remarks This service gets access to the already registered subsystem or device driver The kernel gives control to subsystem or device driver on its OpenEntry entry point with the parameters specified on page 123 The subsystem or device driver can return a 32 bit device memo to the kernel on the exit from its OpenEntry function The kernel passes this memo back to the subsystem or device driver on any call for this process Multiple opens of a device driver are allowed but the number of closes by a single process should match the number of opens by that process Return codes returned by the OpenEntry function of a subsystem or device driver are passed back to the calling process as the return code of OpenDev These return codes must be either RC SUCCESS or within the range OxFFFF0000 to OxFFFFFFFF Return codes outside this range are discarded The return code from OpenEntry is used by the kernel to remove access to the device driver if the return code is not RC SUCCESS Chapter 3 Base Kernel Services 125 CloseDev Close a Subsystem or Device Driver CloseDev Close a Subsystem or Device Driver 126 This service releases the access of this process to the s
40. ReturnCode values in RIC_KernResponse are RC_INVALID_RESERVED_PARM RC_INVALID_HANDLE There is no variant response part for this command Remarks None Chapter 4 Kernel Commands 167 QueryProcessStatus Get the Process Status QueryProcessStatus Get the Process Status 168 This command returns the process status and process identification when the process name is specified Command Parameters CommandNum in the common header must be set to KERN QUERY PROC STAT Structures struct RIC_QueryProcessStatusCmd char ProcName MAX RES USER struct ProcessStatusBlock ProcSB RIC_ULONG Reserved where ProcName Process name ProcSB Reference to the structure containing status information See QueryProcessStatus Get the Process Status on page 25 for the format of the process status block Reserved Reserved field must be 0 Response Parameters ReturnCode values in RIC_KernResponse are RC_SUCCESS RC_INVALID_NAME RC_INVALID_RESERVED_PARM RC NAME NOT FOUND The following shows the variant part of the response for this command struct RIC QueryProcessStatusResp struct ProcessStatusBlock ProcSB RIC ULONG Reserved where ProcSB Reference to the structure containing status information See QueryProcessStatus Get the Process Status on page 25 for the format of the process status block Rese
41. System Unit APIs vi Base APIs una etant ORI RICOpen Open an ARTIC960 Adapter RICClose Close an ARTIC960 Adapter ARTIC960 Programmer s Reference 170 171 173 173 175 175 176 177 181 182 183 184 186 187 188 189 190 191 192 193 195 196 196 199 200 202 202 206 207 208 209 210 210 211 212 213 215 217 223 224 225 225 227 253 263 264 265 266 RICRead Read from ARTIC960 Memory esses nne RICWrite Write to ARTIC960 Memory sese enren nennen enne trennen trennen RICReset Reset an ARTIC960 Adapter eese RICGetConfig Get Configuration Information essere RICGetVersion Get Version Number esee enne RICGetException Get Exception Status eese eene nennt enne trennen tnnt Mailbox CreateMbx Create a Mailbx ccccccccccecsssscececesesseececesessnacececessnasecececesaeeecceceseeaececcsessaececesessaeeeees OpenMbx Open a Mailbox ic Erb dE abe Eee rb a oer GetMbxBuffer Get a Free Mailbox Buffer cccccccccccsssssccecessssseeececsssseccecesnsaeceecessseeeeeeeseaeeeeees FreeMbxBuffer Free Mailbox Buffer 0 0 00 ccccccccccccesssssececeesaeceececesaececeeceesseseeceesaeecesenseaeececenseaees Send MbxX S
42. WaitEvent No No No Yes Yes Memory Management Services CreateMem No No No Yes Yes OpenMem No No No Yes Yes CloseMem No No No Yes Yes ResizeMem No No No Yes Yes SetMemProt No No No Yes Yes SetProcMemProt Yes Yes Yes Yes Yes QueryMemProt No No No Yes Yes QueryProcMemProt Yes Yes Yes Yes Yes QueryFreeMem Yes Yes Yes Yes Yes InitSuballoc No No No Yes Yes GetSuballoc Yes Yes Yes Yes Yes FreeSuballoc Yes Yes Yes Yes Yes GetSuballocSize Yes Yes Yes Yes Yes MallocMem Yes Yes Yes Yes Yes FreeMem Yes Yes Yes Yes Yes CollectMem No Yes Yes Yes Yes Timer Services CreateSwTimer No No No Yes Yes CloseSwTimer No No No Yes Yes StartSwTimer Yes Yes Yes Yes Yes StopSwTimer Yes Yes Yes Yes Yes SetSystemTime Yes Yes Yes Yes Yes QuerySystemTime Yes Yes Yes Yes Yes StartPerfTimer Yes Yes Yes Yes Yes StopPerfTimer Yes Yes Yes Yes Yes ReadPerfTimer Yes Yes Yes Yes Yes 16 ARTIC960 Programmer s Reference Table 2 1 Sheet 3 of 4 ARTIC960 Kernel Services Function Interrupt Signal Async Process Critical Handler Handler Handler Exit Section Process Communication Services CreateQueue No No No Yes Yes OpenQueue No No No Yes Yes CloseQueue No No No Yes Yes PutQueue Yes Yes Yes Yes Yes GetQueue Yes2 Yes2 Yes2 Yes Yes SearchQueue Yes Yes Yes Yes Yes CreateMbx No No No Yes Yes OpenMbx No No No Yes Yes4 GetMbxBuffer Yes Yes Yes Yes Yes FreeM
43. f other trademarks registered trademarks service marks and trade names are the property of their respective owners November 2000 Copyright 2000 by RadiSys Corporation rights reserved Contents About This ESRI T e xiii Gude Contents renen a AR Iit e tp xiii Notational Conventions cceccessscesceceseceseeceneececesaeeeecesseceacecsaeeesaeeseeeaeeseneceeeeceaeseneeeeeeecaeeeeeeeaees xiv Where to Get More Information 15i ib er AKE A EKER TAKERE Tr RASA XV Developer s Assistance Progratis i css sseseconssctesstetssatsipcap coadesncescesnssvonsnsessnsvascsbavans sesnessessreabesseetees xvi Chapter 1 Loading and Configuring sss 1 SUpported Adapters PRO 1 50 1 Kernel Performance 2 Configuration Parameters eine o erre ker re Ro EH ARE Feb EP E tb rk RR 4 ARTIC960 Stipport for ONT fa Supported ARTIC960 z Device Driver Installation inter terrre e e a E ie z Mailbox Process RICMBX32 EXE
44. for which the trace is to be disabled See the Remarks section for details Returns RC SUCCESS RC TRACE NOT INITIALIZED RC INVALID SERVICECLASS Remarks This service disables the logging of the trace for the service classes given as argument It does not report errors if the trace on a particular service was already disabled It disables the trace on the given services in addition to those for which trace is already disabled The valid service classes for the kernel are ALL SERVICES C ASYNC EVENT SERVICI C CLIB DEVICE DRIVER S EVENT ERVICE RVICE CI Q CJ RVICI 1 AN I 1 RN_COMMANDS_SERVICI I HP pd U D 0 m O n Pe lt H H m C UE i 5 A lt H nn n PSP ae PE n Jj lt H E Q SUBALLOC Q Ca z H ia lt H Q C TIM zo ca lt H Q 152 ARTIC960 Programmer s Reference LogTrace Log Trace Information LogTrace Log Trace Information This service logs the trace information in the trace buffer Functional Prototype RIC ULONG LogTrace RIC ULONG ServiceClass RIC ULONG ProcedureID RIC_ULONG CallerP
45. information RIC0071 Card ROM downlevel warning RIC0081 Calibrating ARTIC960Rx timers information Mailbox Process RICMBX32 EXE 8 The mailbox process RICMBX32 EXE is a detached process that works with the physical device driver to handle remote mailbox processing Mailbox Process Call The mailbox process is called using the following syntax It expects configuration parameters to be supplied to it through the command line or through a configuration file The mailbox process must be loaded prior to any application process calls to mailbox PIED RICMBX32 drive path config filename L path K Figure 1 2 OS 2 Mailbox Process Syntax C config filename Specifies that the contents of the file config filename should be used as input to the mailbox process for configuration parameters K Specifies to stop the active mailbox process If the mailbox process is stopped it may not be restarted without resetting and reloading the adapters The mailbox process requires certain initialization parameters If you do not specify these parameters they are assigned default values The parameters take the form of keywords followed by an sign and the value Spaces tabs or new lines should separate individual parameters ARTIC960 Programmer s Reference The following parameters be set MAX GLOBAL MAILBOX The maximum number of global mailboxes created in the system unit The default is 16 MAX R
46. mailbox for sending messages by this process A value of NULL means that there is no name associated with the memory and the memory cannot be shared Refer to the ARTIC960 Programmer s Guide for more information about mailbox memory options MsgUnitSize Input The smallest allocatable message size All messages are allocated in units of this size If the size is 0 RC INVALID SIZE is returned MsgUnitCount Input The maximum number of messages that can be allocated from this mailbox OptionWord Input A bit field to describe the options to be used to open the mailbox The following constants should be ORed together to build the appropriate set of options Search options for finding a mailbox MBX OPEN SEARCH GLOBAL Other peer units are searched if the mailbox does not exist on this unit MBX OPEN SEARCH LOCAL Search only this unit ARTIC960 Programmer s Reference OpenMbx Open a Mailbox Type of memory access for storage area The caller can OR the following constants together to specify both types of access to the memory The default is that neither access type is given for a local mailbox and that system bus access is given for a global mailbox MBX_MEM_MC_ACCESS For system bus access rights to the memory MBX MEM AIB ACCESS For daughter card access rights to the memory MbxHandle Output Mailbox handle returned to requesting process This handle is passed to all other mailbox serv
47. the Application Loader returns a ESS If an error occurs during the processing of the file the load operation terminates with an exit code corresponding to the error detected If a POST error is detected during the loading of a configuration file and no subsequent errors are detected the exit code RC UTIL ADAPTER EXCEPTION is displayed Chapter 6 System Unit Utilities 199 Application Loader ricload Utility Examples of Application Loader Calls The following examples show different methods of using ricload Example Load Start and Name a Process This example loads and starts the process c vnydirvnyproc rel to logical card 0 and assigns it a process name of PROCess I ricload 0 c mydir myproc rel N PROCess 1 A C T text The parameters passed to the process are argv 0 PROCess 1 argv 1 7G argv 2 T text Example Load and Start a Process with a Default Name This example loads and starts the process process rel to logical card 0 The process is named process rel because a name was not specified ricload 0 process rel A abc def ghi jkl mno The parameters passed to the process are argv 0 process rel argv 1 abc argv 2 def argv 3 ghi argv 4 jk1 argv 5 mno 200 Example Unload a Process This example unloads the process PROCess 1 from logical card 0 ricload 0 U PROCess 1 ARTIC960 Programmer s Reference Application Lo
48. 0 to 30 In addition a priority value of OxFFFFFFFF sets the new priority level to the current priority level minus 1 A priority value of 0 can be used to get off of interrupt priority but remain within the interrupt context The caller must clear the interrupt source before lowering the interrupt priority EntryPoint Prototype The function prototype for the EntryPoint must be RIC_ULONG EntryPoint RIC_ULONG VectorNum Returns Must return 0 if the interrupt was not claimed or non zero if the interrupt was claimed ARTIC960 Programmer s Reference SetVector Set a New Interrupt Vector Entry Point SetVector Set a New Interrupt Vector Entry Point This service sets a new entry point for a previously allocated interrupt vector Functional Prototype RIC_ULONG SetVector RIC_ULONG VectorNum RIC_VECTOR EntryPoint RIC_ULONG OptionWord RIC_ULONG Reserved Parameters VectorNum Input The interrupt vector number whose entry address is to be changed EntryPoint Input Pointer to the interrupt handling routine for the interrupt vector OptionWord Input OPTION PROT ON Causes the kernel to enable memory protection prior to passing control to the EntryPoint OPTION PROT OFF Does not enable memory protection Reserved Input Reserved parameter must be 0 Returns RC SUCCESS RC INVALID RESERVED PARM RC INVALID VECTOR RC INVALID CALL RC INVALID MEM ACCESS RC INVALID OPTION RC VECTOR
49. 15 6 16 6 17 6 18 6 19 6 20 6 21 6 22 6 23 6 24 6 25 6 26 6 27 6 28 6 29 6 30 6 31 6 32 6 33 6 34 6 35 6 36 6 37 6 38 6 39 6 40 6 41 6 42 OS 2 Device Driver SyMtax ped reri ERE REI eR ERROR XE E EES 7 OS 2 Mailbox Process Synt x a eet rur Ree ned ua e EL Ren ERE RR ENEE 8 AIX Mailbox Process Syntax tette terrent tee oup nere 12 Application Loader Syntax 1 UE Rea SEL ed dn Re Bebe neo eden 196 Brindisi C 202 Configuration Utility Syntax 208 Configuration Utility File Entry Format eene nennen nennen 208 Reset Utility Syntax aes 210 Set Trace Utility Syntax Hp eodd a 213 Get Trace Utility Syntax axes eoa er ieee Onde e HERES 215 Format Trace Utility Syntax oe rt teri rt ipo Ie itp dire E AEN 217 Trace Control Block aia tiet eoa rale eevee ek aoe 219 Record Description for a Service Class Data in Bytes 220 Record Description for a Service Class Data in Words eene 221 Trace Control Block Example triente eret the dert eie euet erede sies depu te HER dh 222 Record Description Example Data in Bytes Trace Record 0 002
50. 151 In addition the user can define his own service classes The trace buffer must first be initialized before a service class can be enabled An optional wrap count may be specified to set the maximum number of times the trace buffer can wrap If a wrap count is not specified the trace buffer wraps indefinitely The wrap count is helpful in cases when tracing exceeds the trace buffer This utility can be used to initialize the trace buffer and enable a service class on the same command line prompt Also multiple or all service classes can be enabled and disabled on the same command line prompt Set Trace Syntax gt gt _ __ ricsettr path l path l sze ml W count D class E class Figure 6 6 Set Trace Utility Syntax card num Specifies the logical card number to be traced I size Specifies the size of the trace buffer in KB to be created and initialized on the adapter Valid size range is 1 to 64 W count Specifies the count after which the tracing should stop wrapping in the trace buffer A count of 1 wraps the trace buffer infinitely D class Specifies the service classes for which tracing is to be disabled Valid service classes are between and 255 Service classes between and 127 are reserved for kernel services User defined services classes are between 128 and 255 For performance reasons the kernel does not perform any class range checking E cla
51. C MAILBOX SERVICE 158 Service Class C MEMORY SERVICE essere nee enne 158 Service Class C PROCESS SERVICE 159 Service Class C MEMPROT SERVICE ennt 160 Service Class QUBUB SER V OE irr er dec ce eR Sessa E ERE EE CER PERROS 160 Service Class C SEMAPHORE SERVICE eee nennen nennen nennen 160 Service Class C SIGNAL SERVICE 161 Service Class C SUBALLOC SERVICE essere nennen nennen trennen ennt 161 Service Class C SWTIMER SERVICE eese ener enne teer enne 161 Service Class C TIMER SERVICE seeeeeeeee eren eene nemen nnne nnn nnne 162 service Class C CUB sis ettet ete e Coe eee reae 162 Application Loader Messages and Return Codes seen 199 Dump Utility Messages and Exit Codes essseseseeeeeeeeeeenne nennen 206 Configuration Utility Messages and Exit codes sesesssseeeeeeeeneeeenee nenne 209 Reset Utility Messages and Exit Codes 211 Set Trace Utility Messages and Exit Codes sese 214 Get Trace Utility Messages and Exit Codes sessseeeseeeeeeeeeneenneeee 216 Format
52. CALL RC NO MORE RES RC INVALID SIZE RC INVALID NAME RC INVALID OPTION RC DUP RES NAME RC INVALID ALIGNMENT RC NO MORE Remarks This service is intended for large memory allocations such as buffer pools For smaller more dynamic allocations see GetSuballoc Suballocate Memory on page 77 The minimum amount of memory that can be allocated is one page 4 KB The following constants are defined and can be ORed to create the appropriate access rights for the allocated memory M EM SHARE Memory can be shared with other processes The default is memory that cannot be shared READABLE Memory can be read by the 80960 The default is memory cannot be read or written by the 80960 EM_WRITABLE Memory can be written by the 80960 The default is memory cannot be read or written by the 80960 EM OVERRIDE MC ACCESS EM MC READABLE EM MC WRITABLI The current system bus access to the created memory is overridden The default is system bus access is not changed Memory can be read from the system bus In addition the on card DMA channel can read the memory The default is memory cannot be read or written from either Memory be written from the system bus In addition the on card DMA channel can write to memory The default is memory cannot be read or written from either EM OVERRIDE AIB ACCESS EM AIB READABLE
53. DeregisterHook Deregister an Entry Point for a Hook 148 This service deregisters an entry point for a hook Functional P rototype RIC_ULONG DeregisterHook Parameters RIC ULONG HookNum RIC ULONG OptionWord RIC ULONG Reserved HookNum Input Number of the hook that was registered OptionWord Input If the OptionWord is ORed with HOOK PREPROCESS the preprocessing entry point of the process should be deregistered If the OptionWord is ORed with HOOK POSTPROCESS the post processing entry point is deregistered Reserved Input Reserved parameter must be 0 Returns RC SUCCESS RC HOOK NOT REGISTERED ESS RC INVA RC INVA Remarks None MEM ACC ID CALL ARTIC960 Programmer s Reference RC INVALID RESERVED PARM RC INVALID OPTION RC INVALID HOOK Kernel Trace Services Kernel Trace Services The following are the kernel trace services These services let the user define a trace buffer and to selectively enable and disable trace on different service classes Service Name Page InitTrace 150 EnableTrace 151 Disable Trace 152 LogTrace 153 Refer to the ARTIC960 Programmer s Guide for additional information on trace services Chapter 3 Base Kernel Services 149 InitTrace Initialize a Trace Buffer InitTrace Initialize a Trace Buffer 150 This service sets up a trace buffer for
54. Entry ProcessID integer Exit rc integer P RESUMEPROCESS ResumeProcess Entry ProcessID integer Exit rc integer P QUERYPROCESSINEXEC QueryProcessInExec Entry none Exit ProcessID integer Exit rc integer P QUERYCARDINFO QueryCardinfo Entry none Exit rc integer P QUERYCONFIGPARAMS QueryConfigParams Entry none Exit rc integer P SETPROCESSDATA SetProcessData Entry ApplID character Exit rc integer P GETPROCESSDATA GetProcessData Entry ApplID character Exit ProcessDataPtr integer P_ENTERCRITSEC EnterCritSec Entry OptionWord integer Exit rc integer P_EXITCRITSEC ExitCritSec Entry OptionWord integer Exit rc integer Chapter 3 Base Kernel Services 159 Kernel Trace Information Table 3 10 Service Class C MEMPROT SERVICE Trace Format of Procedure ID Kernel Service Position Trace Data Data P SETPROCMEMPROT SetProcMemProt Entry ProcessID integer Exit rc integer P QUERYPROCMEMPROT QueryProcMemProt Entry ProcessID integer Exit rc integer Table 3 11 Service Class C QUEUE SERVICE Trace Format of Procedure ID Kernel Service Position Trace Data Data P CREATEQUEUE CreateQueue Entry QueueName character Exit rc integer P OPENQUEUE OpenQueue Entry QueueName character Exit rc integer P CLOSEQUEUE CloseQueue Entry QueueHandle integer Exit rc integer P PUTQUEUE PutQueue Entry QueueHandle integer Exit rc integer P GETQUEUE GetQueue En
55. Event 62 Remarks If the OptionWord parameter is set to EVENT_WAIT_ALL the service tests each semaphore count for a positive value If all are positive the parameter decrements the explicit semaphores that are positive and control returns to the caller If all the semaphores do not have a positive value the requester is waited When one or more semaphores in the list become available all other semaphores are tested to determine if they are positive values Any explicit semaphores that are positive are decremented and control returns to the caller The performance of this option can be optimized by specifying the semaphore handles least likely to be available first in the list of semaphore handles supplied on the CreateEvent service If the OptionWord parameter is set to EVENT_WAIT_ANY the service tests to see if any one of the semaphores is positive If one is positive the service decrements the explicit semaphores that are positive and returns to the caller If no semaphores are positive the caller is waited When one or more semaphores in the list become available the service decrements the explicit semaphores that are positive and control returns to the caller If the timeout value is exceeded the process is awakened regardless of the state of the event If a semaphore included in a wait event gets a new semaphore count any processes waiting for events that include that semaphore are awakened with the
56. LONG RIC UI LONG P Handle SrcBuffer DestBuffer BufferLen OptionWord Input The handle for the ARTIC960 adapter Input The source buffer address in system memory This is a 32 bit logical address Input The destination buffer address on the adapter This is a flat 32 bit ARTIC960 address Input The length in bytes to be written Input Reserved must be 0 CCESS RC_NO_MORE_RES APTER_EXCEPTION RC_RESET_ACTIVE MP_ACTIVE RC_SCB_TRANSFER_FAILED A_TRANSFER_FAILED AIX only RC_SU_INVALID_HANDLE VALID_ADDRESS RC SYSTEM ERROR VALID MEM ACCESS RC TIMEOUT VALID OPTION RC UNIT NOT FUNCTIONING VALID SIZE RC WRN PIPES NOT CONFIGURED ADAPTER RESPONSE references to ARTIC960 memory are flat addresses There is no concept of paging shared memory or DMA visible to the user application The memory protection hardware on the ARTIC960 adapter reports all errors to the ARTIC960 processor The system unit driver is not directly notified of access violations Because of this short RICRead calls may succeed even though they cause access violations whereas a long RICRead call to the same region may be rejected because of improper access rights The reason is because the subsystems on the card verify proper access on all transfers requested by the system unit using SCB
57. NOT ALLOCATI Er Remarks The application must allocate the vector before calling this service Chapter 3 Base Kernel Services 131 SetVectorMux Set an Interrupt Vector SetVectorMux Set an Interrupt Vector 132 This service sets a new entry point for a previously allocated interrupt vector Functional Prototype RIC_ULONG SetVectorMux RIC_ULONG VectorNum RIC_VECTOR_MUX EntryPoint RIC_ULONG OptionWord RIC ULONG Reserved Parameters VectorNum Input The interrupt vector number whose entry address is to be changed EntryPoint Input Pointer to the interrupt handling routine for the shared interrupt vector The interrupt handling routine must return a value of 0 if the interrupt was not claimed or a non zero value if the interrupt was claimed See EntryPoint Prototype on page 132 OptionWord Input OPTION_PROT_ON The kernel enables memory protection prior to passing control to the EntryPoint OPTION_PROT_OFF The kernel does not enable memory protection Reserved Input Reserved parameter must be 0 Returns RC_SUCCESS RC INVALID RESERV RC INVALID VECTOR RC INVALID CALL RC INVALID MEM ACCESS RC INVALID OPTION RC VECTOR NOT ALLOCATI I D PARM Er The calling process must have allocated the vector before calling this service EntryPoint Prototype The function prot
58. Number Exit Code Notes RIC0001 RC_UTIL_INVALID_CMDLINE_OPTION RIC0002 RC_UTIL_INVALID_CMDLINE_PARM RICO003 RC_UTIL_FILE_NOT_FOUND RICO004 RC UTIL FILE ACCESS RICO005 RC UTIL INVALID CARD NUMBER RICO009 RC UTIL ADAPTER EXCEPTION RICO010 RC UTIL NO ADAPTER RESPONSE RICO016 RC UTIL SYSTEM ERROR RIC0019 RC_UTIL_NOT_INSTALLED RIC0029 RC_UTIL_WRNHELP_GIVEN RIC0036 RC_UTIL_SUCCESS RIC0037 RC_UTIL_MICROCODE_ERROR Microcode error RIC0038 RC UTIL ACCESS ERROR RIC0041 RC_UTIL_PIPE_UNCONF PS 2 systems only RIC0043 RC_UTIL_PIPE_SIZE_OUT_OF_RANGE RIC0046 RC_UTIL_PIPE_ALREADY_CONF RIC0047 RC UTIL PIPE CONF FAILED RICO055 RC UTIL UNIT NOT FUNCTIONING 0067 RC_UTIL_SNGL_PIPE_CONF_FAILED RICO068 RC_UTIL_SUBSYSTEM_NOT_FOUND RICO080 RC UTIL UNSUPPORTED OPTION Chapter 6 System Unit Utilities 209 Reset Utility Reset Utility The Reset utility allows users to reset ARTIC960 adapters Multiple adapters can be reset with a single call of the Reset utility The Reset utility ensures that all other SCB units system driver and adapters are notified of the reset operation before resetting the card Reset Syntax path Q Figure 6 5 Reset Utility Syntax Q Specifies quiet operation Typically the Reset utility displa
59. Option hnnnnnnn ssssssssssssssss nnnnnnnn nnnnnnnn nnnnnnnn SSSSSSSS M J Figure 6 35 Signal Detail Display ARTIC960 Programmer s Reference Status Interactive Messages 8 Timer Resource Details Submenu The following screen shows the prompts and items displayed when a timer is selected from the Resource details submenu Valid timer states are running stopped and expired See Figure 6 61 on page 260 for an example Enter adapter number gt Enter resource name or handle gt Resource type timer ame SSSSSSSSSSSSSSSS Handle nnnnnnnn Handler nnnnnnnn State SSSSS Owner name SSSSSSSSSSSSSSSS Owner no nnnnnnnn P Figure 6 36 Timer Detail Display Chapter 6 System Unit Utilities 247 Status Interactive Messages 9 Hardware Device Resource Details Submenu The following screen shows the prompts and items displayed when a hardware device is selected from the Resource details option of the main menu e The values for the Valid data field are yes and no The Owner name and Owner no fields may be blank if the device is not allocated e The Device data fields are displayed only if the valid data flag indicates that it is available See Figure 6 62 on page 260 for an example 7 Enter adapter number gt Enter resource name or handle gt Resource type hardware device Name SSSSSSSSSSSSSSSS Status n Valid data SSS Owner name SSSSSSSSSSSSSSSS Owner no nnnnnnnn
60. RC PIPES NOT CONFIGURED The operation completed successfully even though there is no subsystem control block SCB pipe configured to communicate with the adapter 0x00010009 RC DUMP NOT ACTIVE A dump command was called without first activating the dump 0x0001000A RC HANDLE CLOSED Another thread within the process closed the process handle which forces any threads using that handle to abort with this error The SCB entity is also deregistered 0x0001000B RC NO ELEMENTS This error is returned on a dequeue SCB call when no elements are available to be dequeued 0x0001000C RC PIPE FULL The element cannot be enqueued at this time because the destination pipe is full The SCB pipe was full when attempting to enqueue a control element 0x0001000D RC INVALID CARD NUMBER The requesting card is not one of the cards specified in the move system bus operation The logical card number is out of range or invalid The requested operation is not supported on this card in this environment 316 ARTIC960 Programmer s Reference Return Codes Listed Numerically Return Code Description 0x0001000E RC_UNIT_NOT_FUNCTIONING The peer unit involved in the operation is not functioning A timeout error occurred accessing the unit or waiting for a response from the unit A timeout occurred when trying to send or receive an SCB element to the unit 0x0001000F RC INVALID UNIT NUMBER The unit numb
61. RIC_ULONG Reserved Parameters SemHandle Input Semaphore handle SemCount Input New count of semaphore Values less than zero are not permitted In addition mutual exclusion semaphores cannot be assigned a count greater than 1 Reserved Input Reserved parameter must be 0 Returns RC_SUCCESS RC INVALID SEM COUNT RC INVALID HANDLE RC PROCESSES WAITING ON SEM RC INVALID RESERVED PARM RC NEW SEM COUNT Remarks This service should be used immediately after the semaphore is created to configure the semaphore to the desired type If any processes are waiting for the semaphore when the count is set they are released and returned with RC NEW SEM COUNT This includes processes waiting for events that include the semaphore Chapter 3 Base Kernel Services 57 CreateEvent Create an Event Word CreateEvent Create an Event Word 58 This service creates an event word based on a semaphore list and mask Functional Prototype RIC_ULONG CreateEvent char EvnName RIC SEMHANDLE SemHandles RIC ULONG SemCount RIC EVNHANDLE EvnHandle ULONG Reserved Parameters EvnName Input A name to assign to the event word so that other processes can get access to it SemHandles Input Pointer to an array of up to 32 semaphore handles to associate with the event word These semaphore handles can be implicit or explicit SemCount Input
62. Reserved parameter must be 0 Returns RC_SUCCESS RC INVALID RESERV ED PARM RC INVALID CALL RC INVALID PROCES RC INVALID PRIORI Remarks SID TY The kernel changes the priority of the process to Priority If the priority of the currently executing process is lowered dispatch cycle may occur Refer to the ARTIC960 Programmer s Guide for the priority recommendations ARTIC960 Programmer s Reference QueryPriority Query the Priority of the Process QueryPriority Query the Priority of the Process This service queries the priority of the process Functional Prototype RIC ULONG QueryPriority RIC PROCESSID ProcessID ULONG Priority RIC ULONG Reserved Parameters ProcessID Input Queries the priority of this process A value of 0 means the calling process Priority Output Priority of the process Reserved Input Reserved parameter must be 0 Returns RC SUCCESS RC INVALID RESERVED PARM RC INVALID PROCESSID RC INVALID MEM ACCESS Remarks None Chapter 3 Base Kernel Services 43 QueryProcessInExec Get ID of Process in Execution QueryProcessInExec Get ID of Process in Execution 44 This service returns the process ID of the process that currently is executing Functional Prototype ULONG QueryProcessInExec PROCESSID ProcessID Parameters RIC ULONG Reserved Proc
63. Routines 175 System Bus Interface Services System Bus Interface Services The kernel provides the following system bus interface services Service Page MoveMCData 177 ConvertMCToCard 181 ConvertCardToMC 182 These services allow a process to perform system bus operations They are provided by the System Bus I O Subsystem RIC_MCIO REL Programs that use the system bus interface services must define the constant INCL_MCHL prior to the include ric h statement to obtain the proper declarations The libraries for these services are contained in the file libmclib a for OS 2 and libmclibx a for AIX To link a program with this library add 1mclib or 1mclibx to the LNK960 call Refer to the ARTIC960 Programmer s Guide for more information 176 ARTIC960 Programmer s Reference MoveMCData Move System Bus Data MoveMCData Move System Bus Data This service moves data to from a buffer on the local unit from to a buffer on another unit a remote unit through a system bus operation It blocks the requesting process until the operation is complete Functional Prototype RIC_ULONG MoveMCData RIC_DEVHANDLE DDHandle struct RIC_MoveBlock PPtr RIC_ULONG Reserved Parameters DDHandle Input Handle of subsystem returned by OpenDev of System Bus YO Subsystem PPtr Input Pointer to the move block Reserved Input Reserved parameter must be 0 The move block structure is struct RIC_Move
64. Size ULONG Access RIC ULONG Reserved BlockPtr Input Pointer to block of memory The caller must have created or opened the memory that contains this block Size Input Size of block to query Access Output Access rights to memory This can include the MEM DCACHE and MEM BIG ENDIAN options See the Remarks section under CreateMem Allocate Memory on page 64 for more information Reserved Input Reserved parameter must be 0 Returns RC SUCCESS RC INVA RC INVA RC INVA RC INVA RC INVALID SIZE Remarks ID BASEPTR ID RESERVED PARM ID CALL ACCESS P This service returns the access rights to the memory block for the calling process Only a single set of daughter card and system bus access flags are saved by the memory protection services Therefore this service returns the same value for these two sets of flags regardless of the caller s process ID ARTIC960 Programmer s Reference QueryProcMemProt Query a Process Memory Protection QueryProcMemProt Query a Process Memory Protection This service queries the memory protection of a block of memory for a given process It is available only to device drivers and subsystems Functional Prototype RIC ULONG QueryProcMemProt RIC PROCESSID ProcessID Parameters ProcessID BlockPtr Size Access Reserved Returns void BlockPtr RIC ULONG Size RIC ULON
65. Size Output Size of the received message buffer Reserved Input Reserved parameter must be 0 Returns RC SUCCESS RC INVALID TIMEOUT RC INVALID HANDLE RC MBX EMPTY RC INVALID OPTION RC NO MBX PROCESS RC INVALID RECEIVER RC NO MORE RES RC INVALID RESERVED PARM RC SYSTEM ERROR ARTIC960 Programmer s Reference ReceiveMbx Receive a Message Remarks call dequeues the first message buffer from the mailbox queue The semaphore associated with the mailbox on the ARTIC960 adapter is decreased by 1 e Ifthe MBX RECEIVE GET MESSAGE option is set in the OptionWord parameter this In OS 2 system unit mailboxes the semaphore is set if the dequeued message is the last one in the queue e In AIX system unit mailboxes the variable semval of the semaphore is set to 1 if the dequeued message is the last one in the queue For information on semval see usr include sys sem h e Ifthe MBX RECEIVE READ MESSAGE option is set in the OptionWord parameter the message is not dequeued from the message queue Chapter 7 System Unit APIs 287 CloseMbx Close a Mailbox CloseMbx Close a Mailbox This releases the mailbox and deletes it if no other process has access to it Functional Prototype RIC_ULONG CloseMbx RIC MBXHANDLE MbxHandle RIC ULONG Reserved Parameters MbxHandle Input Handle of the mailbox to close
66. This service cannot be called from an interrupt handler It can be called from a call handler However doing so with a ProcessID value of 0 can give unexpected results and should be used with caution While in a call handler the process in execution is considered to be the process that called the handler If call processes are nested it is the process that called the first handler should be called in the following order 1 CreateProcess EnterCritSec to disable preemption StartProcess SetProcessData ExitCritSec to enable preemption V To set process data for a process that is started by CreateProcess services amp c Chapter 3 Base Kernel Services 45 GetProcessData Get Process Data GetProcessData Get Process Data 46 This service returns the process instance data associated with the indicated application environment and process Functional Prototype RIC_ULONG GetProcessData void ProcessDataPtr unsigned char ApplID PROCESSID ProcessID Parameters ProcessDataPtr Input Pointer to location where the kernel returns the pointer to the process instance data If no process instance data is found a NULL pointer is returned ApplID Input Unique ID to indicate with which application environment the process instance data is associated ProcessID Input Process ID of the instance data to be retrieved A value of 0 indicates the process in execution Returns RC SUCCESS RC INV
67. Trace RIC0304 Correct syntax is MEX ricfmttr ee eee hee 0 2 path in filename O out filename C class filename Explanation Format Trace utility syntax help message Action Select the proper parameters and call the Format Trace Source Format Trace RICO305 Trace uninitialized on card nn Explanation Get Trace failed to enable and or disable a service class because the trace buffer was not previously initialized on card number nn Action Include I on the ricgettr command line Source Get Trace 308 ARTIC960 Programmer s Reference RIC0306 RICO400 RICO460 RICO306 Explanation Action Source The trace buffer is empty no trace logged The trace file is empty Run the card application to be traced run Get Trace and rerun Format Trace Format Trace RIC0307 RICO322 Explanation These messages are used to format the trace buffer Action None Source Format Trace RIC0323 Trace input file successfully formatted Explanation The Trace Formatter successfully formatted the input trace file Action None Source Format Trace RIC0324 Invalid Service Class xxx Valid Class Range 0 255 Explanation The service class specified xxx must be in the range 0 to 255 Action Select a valid service class and reenter command Source Set Trace RIC0325 Explanation This message is used to format the trace buffer Action None Source Format Trace RIC0
68. Trace Utility Messages and Exit Codes sse 218 status Utility Options 5 aero eot decebat ep UL d rete 223 Status Utility Messages and Exit Codes sese ener 225 source OF Request RH ee HE a eee UD 234 Termination Status Fault Types and Subtypes for a Processor Event 235 Recognized Exception Conditions essent enne eene enne 250 Tables Xi xii ARTIC960 Programmer s Reference About This Book This book describes specific aspects of programming in the RadiSys ARTIC960 coprocessor environments This book contains information about the ARTIC960 services available for writing adapter resident programs It also contains a brief description of the system unit utility programs and the steps required to compile and link both system unit and adapter programs This book does not include sample code Guide Contents The following lists the contents of this Guide Chapter Description 1 Loading and Configuring Explains how to load and configure the kernel and related subsystems and RadiSys ARTIC960 Support for OS 2 AIX and Windows NT 2 ARTIC960 Kernel Services Provides a summary of RadiSys ARTIC960 kernel services and ARTIC960 parameter types 3 Base Kernel Services Describes the base kernel services 4 Kernel Commands Lists and describes the kernel commands 5 Adapter Library Routines Lists ANSI C library calls and d
69. ULONG Reserved I Parameters QueueName Input A queue name to assign to the queue so that other processes can access the same queue by name This name also can be NULL The queue cannot be shared when QueueName is NULL The kernel s subsystems allocate all resources with the first four characters being RIC_ for the resource name User queue names should not start with this prefix QueueHandle Output Queue handle returned to requesting process This handle is passed to all other queue services when this queue is referenced SemHandle Output Handle of the semaphore used to wait on queue elements The handle is returned so that it can be part of a multiple event wait Reserved Input Reserved parameter must be 0 Returns RC SUCCESS RC NO MORE RES RC INVALID RESE RC INVALID NAP RC DUP RES NAP RC INVALID MEM ACCESS RC INVALID CALL u lt ED_PARM Remarks This service creates a new queue and assigns it the specified name Other processes can access the same queue with the OpenQueue service The initial semaphore count is set to 0 It is up to the process to ensure that it has read write memory access to all queue elements Multiple processes can read and receive from a single queue Chapter 3 Base Kernel Services 95 OpenQueue Open a Queue OpenQueue Open a Queue 96 This service
70. Unit Utilities 253 Examples of Interactive Messages 3 Resource Summary QUE_QUEUE_A MEM_DATA_BUFFERS SEM_ProcessSyncl SEM_ProcessSync2 TIM_FeedMeNow Type queue emory timer Press Enter to continue semaphore semaphore Figure 6 46 Example Screen Resource Summary 4 Memory Enter Address Name Length BIW Or 0 to Return gt 22040000 2A B 22040000 30 31 32 33 34 00 41 42 43 00 00 00 00 00 00 00 22040010 30 30 30 00 00 00 61 62 00 00 00 00 00 00 00 00 22040020 00 00 00 00 01 02 03 04 05 06 Enter Address Name Length BIW Or 0 to Return gt 22040000 8 W 22040000 33323130 42410034 00000043 00000000 22040010 00303030 62610000 00000000 00000000 5 Process Details Figure 6 47 Example Screen Memory ame ID Priority Entry point Stack pointer Param pointer State Version Type Enter process name or ID gt PROCESS A PROCESS A 0x01050007 0x28 0x22061C60 0x220661F0 0x22067134 queued 0x0 normal Figure 6 48 Example Screen Process Details 254 ARTIC960 Programmer s Reference Examples of Interactive Messages This example shows a process terminated by a software event The process stopped normally with an error code of 0 FL UN Enter process name or ID gt 6 ame PRC stopproc rel ID 0x01050006 Priority 0x28 Entry point 0x2207FDCO Stack pointer 0x2207E1E0 Param pointer 0x22080134 State stop
71. VectorNum integer Exit rc integer P_RETURNVECTOR ReturnVector Entry VectorNum integer Exit rc integer P_ALLOCHW AllocHW Entry DeviceName character Exit rc integer P_RETURNHW ReturnHW Entry DeviceName character Exit rc integer P_QUERYHW QueryHW Entry DeviceName character Exit rc integer P CREATEDEV CreateDev Entry DDName character Exit rc integer P OPENDEV OpenDev Entry DDName character Exit rc integer P INVOKEDEV InvokeDev Entry DDHandle integer Exit rc integer P CLOSEDEV CloseDev Entry DDHandle integer Exit rc integer 156 ARTIC960 Programmer s Reference Kernel Trace Information Table 3 3 Service Class C EVENT SERVICE Trace Format of Procedure ID Kernel Service Position Trace Data Data P CREATEEVENT CreateEvent Entry EvnName character Exit rc integer P OPENEVENT OpenEvent Entry EvnName character Exit rc integer P CLOSEEVENT CloseEvent Entry EvnHandle integer Exit rc integer P WAITEVENT WaitEvent Entry EvnHandle integer Exit rc integer Table 3 4 Service Class C HOOK SERVICE Trace Format of Procedure ID Kernel Service Position Trace Data Data P REGISTERHOOK RegisterHook Entry HookNum integer Exit rc integer P DEREGISTERHOOK DeregisterHook Entry HookNum integer Exit rc integer Table 3 5 Service Class C INTERRUPT SERVICE Trace Format of Procedure ID Kernel Service Position Trace Data Data P FIRSTLEVELINT First level inte
72. Word from PCI Configuration Space eese pciReadConfigDWord Read a Doubleword from PCI Configuration Space peiWriteConfigByte Write a Byte to PCI Configuration Space sesseeeeeeee peiWriteConfigWord Write a Word to PCI Configuration Space sse pciWriteConfigDWord Write a Doubleword to PCI Configuration Chapter 6 System Unit Utilities Application Loader ricload Utility Application Loader Syntax Application Loader Messages and Exit Codes sess nennen Examples of Application Loader Calls Dump Utility eth et tn Dump Syntax eese Dump Messages and Exit Codes Configuration Utility ener cree Configuration Syntax Configuration Messages and Exit Codes Reset Reset Syntax uiid ete Sensis Reset Messages and Exit Codes Trace Utihties aie engen Set Trace Utility sse Get Trace Utility 00 eee Format Trace Utility Status Utility ioter mtn Status Syntax Status Messages and Exit Codes Status Dump Status Interactive Messages Examples of Interactive Messages Chapter 7
73. a Software Timer This service returns a previously created software timer Functional Prototype RIC_ULONG CloseSwTimer RIC_TMRHANDLE TimerHandle RIC_ULONG Reserved Parameters TimerHandle Input Timer handle of the timer to be returned This handle is passed to the process by the service CreateSwTimer Reserved Input Reserved parameter must be 0 Returns RC_SUCCESS RC_INVALID_RESERVED_PARM RC_INVALID_HANDLE RC_INVALID_CALL Remarks This service returns a previously created software timer The process cannot access this software timer any more This call stops a timer that is started Chapter 3 Base Kernel Services 85 StartSwTimer Start a Software Timer StartSwTimer Start a Software Timer This service starts a software timer Functional Prototype RIC_ULONG StartSwTimer RIC_TMRHANDLE TimerHandle RIC_ULONG TimeCount RIC TMRHANDLER TimerHandler RIC ULONG OptionWord RIC ULONG TimerMemo RIC ULONG Reserved Parameters TimerHandle Input Timer handle of the timer to be started This handle is passed to the process by the service CreateSwTimer TimeCount Input Timeout count This parameter is specified in terms of milliseconds and can range from 1 to 65535 The granularity of the timer is five milliseconds The timeout value is rounded up to the next multiple of five if it is not already a multiple of five A value of 0 is not valid T
74. adapters For information on this utility see Configuration Utility on page 207 ARTIC960 Programmer s Reference Mailbox Process Messages and Return Codes The content of the message file is listed in Appendix B Message File on page 295 The following table correlates the return code of the driver with the driver messages used by the AIX mailbox process Table 1 5 AIX Mailbox Process Messages Message Number Return Code Notes RIC0001 RC_UTIL_INVALID_CMDLINE_OPTION Invalid configuration file invalid parameter names or values RIC0002 RC_UTIL_INVALID_CMDLINE_PARM RIC0003 RC_UTIL_FILE_NOT_FOUND Configuration file not found RIC0004 RC_UTIL_FILE_ACCESS Cannot access configuration file RIC0006 RC_UTIL_NO_MORE_MEM Parameter value exceeds system memory limit RIC0016 RC_UTIL_SYSTEM_ERROR OS or device driver error RIC0019 RC_UTIL_NOT_INSTALLED Device driver not installed RIC0021 RC_UTIL_SUCCESS Process successfully started RIC0048 RC_UTIL_WRNHELP_GIVEN RIC0050 RC_UTIL_RESOURCE_BUSY shmid semid used by mailbox has been allocated in the system RIC0051 RC_UTIL_ALREADY_STARTED RIC0076 RC_UTIL_FILE_ACCESS No root authority Error Logging The error log is a tool designed to help isolate hardware problems The AIX Support Device Driver provides error logging The following ARTIC errors are logged to the system error log TO Error Problems reading or writing to the system bus address
75. additional information ARTIC960 Programmer s Reference CreateSem Create a Semaphore CreateSem Create a Semaphore This service creates a semaphore and gives access to the requesting process Functional Prototype RIC_ULONG CreateSem char SemName RIC ULONG SemCount RIC ULONG OptionWord RIC SEMHANDLE SemHandle RIC ULONG Reserved Parameters SemName Input A name to assign to the semaphore so other processes can get access to the same semaphore by name This name can be NULL however the semaphore cannot be shared when SemName is NULL The kernel s subsystems allocate all resources with the first four characters as RIC_ for the resource name User semaphore names should not start with this prefix SemCount Input New count of semaphore Values greater than 0x80000000 are not permitted In addition mutual exclusion semaphores cannot be assigned a count greater than one OptionWord Input SEMTYPE COUNTING Specifies the semaphore as a counting type SEMTYPE MUTEX Indicates a mutual exclusion type semaphore SemHandle Output Semaphore handle returned to requesting process This handle is passed to all other semaphore services when referring to this semaphore Reserved Input Reserved parameter must be 0 Returns RC SUCCESS RC INVALID MEM ACCESS RC NO MORE RES RC INVALID CALL RC_INVALID_RES RC_INVALID_NAD RC DUP RES RVED PARM RC IN
76. any process waiting for the semaphore is awakened with RC NEW SEM COUNT Processes cannot wait for implicit semaphores with this service Instead processes should use the services related to the semaphore such as GetQueue or ReceiveMbx In addition implicit semaphores can be part of an event wait Chapter 3 Base Kernel Services 55 QuerySemCount Get a Semaphore Count QuerySemCount Get a Semaphore Count 56 This service returns the count of a semaphore Functional Prototype ULONG QuerySemCount SEMHANDLE SemHandle RIC_ULONG SemCount RIC_ULONG Reserved Parameters SemHandle Input Handle of semaphore SemCount Output Count of semaphore Reserved Input Reserved parameter must be 0 Returns RC_SUCCESS RC_INVALID_RESERVED_PARM RC_INVALID_MEM_ACCESS RC_INVALID_HANDLI Gl Remarks If the count is zero the semaphore is not available Other processes may be waiting for the semaphore A positive count indicates the number of times that processes can request the semaphore before they are blocked This is the only semaphore service that can be used on implicit semaphores ARTIC960 Programmer s Reference SetSemCount Set a Semaphore Count SetSemCount Set a Semaphore Count This service sets the count of a semaphore Functional Prototype RIC_ULONG SetSemCount RIC_SEMHANDLE SemHandle RIC_ULONG SemCount
77. as RIC_ for the resource name User memory names should not start with this prefix Input Size of allocated block in bytes If the size is 0 RC INVALID SIZEis returned Input Boundary alignment for the start of the allocated block Alignment values are the log of the boundary number For example a 4 KB boundary translates to an Alignment value of log 4096 12 Alignment values less than 4 KB are rounded up to 4 KB Input Bit field specifying the access rights to the memory block See Remarks on page 65 for more information Input Flag indicating the type of memory to be allocated MEM TYPE INSTR MEM TYPE PACKET By hardware design the processor is more efficient using instruction memory Packet memory is more efficient for access from the daughter card or system bus On adapters that have only packet memory packet memory is allocated even if instruction memory is requested MEM TYPE PACKET Allocate packet memory Return with an error if no packet memory is available MEM TYPE INSTR Allocate instruction memory Return with an error if no instruction memory is available Output Pointer to allocated memory block Input Reserved parameter must be 0 ARTIC960 Programmer s Reference CreateMem Allocate Memory Returns RC_SUCCESS RC INVALID MEM ACCESS RC INVALID RESERVED PARM RC INVALID
78. configuration between card nn and the system unit failed Action Reset the adapter and reconfigure Also ensure that all of the necessary subsystems are loaded on the card before attempting to configure the card Source Configuration Application Loader Reset RICOO068 One or more of the required subsystems was not found for card nn Explanation The card could not be configured because a required system was not found Action Reset the adapter and load the necessary subsystems on the card before attempting to configure the card Source Reset Application Loader Configuration RICO069 XXXXXXXX SCB transfers disabled Explanation Device driver data transfers through SCB are disabled All transfers are done through programmed I O This driver option is usually only configured for a development or debug environment Action To enable device driver SCB transfers remove the S option from the device driver CONFIG SYS entry Source OS 2 Driver Appendix B Message File 305 RIC0070 RICO080 RICO070 XXXXXXXX timeouts disabled Explanation Device driver timeouts for SCB transfers and commands to the card are disabled This driver option is usually only configured for a development or debug environment Action To enable device driver timeouts remove the option from the device driver CONFIG SYS entry Source OS 2 Driver RICO071 Down level ROM version on card 1 Explanation The version of ROM on the adap
79. configuring The kernel and related subsystems ARTIC960 Support for OS 2 The ARTIC960 Support for AIX e The ARTIC960 Support for Windows NT Supported Adapters Table 1 1 shows which adapters are supported by each operating system Table 1 1 Adapters Supported by Each Operating System OS 2 AIX Windows NT Adapter Version 1 2 2 Version 1 4 1 Version 1 2 0 ARTIC960 Micro Channel y ARTIC960 PCI y y ARTIC960Rx PCI N N ARTIC960Hx PCI J ARTIC960RxD PCI ARTIC960Rx Frame Relay PCI Kernel and Subsystems The kernel and related subsystems collectively called system executables must be loaded onto the adapter before any application processes are loaded The list of system executables and associated file names are ric_kern rel Runtime kernel This module provides all of the services described in Chapter 3 Base Kernel Services on page 21 ric_kdev rel This module can be used instead of ric_kern rel during the debug phase of application development ric base rel Base device driver This module provides memory protection services If ric base rel is loaded when memory protection is not active it is unloaded automatically by the kernel ric mcio rel System Bus I O subsystem This module provides basic support for moving data between adapters and the system unit Chapter 1 Loading and Configuring 1 ric_scb rel This module provides peer to peer transport servi
80. control elements The return codes RC DUMP ACTIVI E and RC Ri is ET_ACTIV indicate a dump or reset was active when this call was made or a dump or reset was done while the call was blocked Chapter 7 System Unit APIs 269 RICWrite Write to ARTIC960 Memory 270 The return code RC INVALID MEM ACCESS cannot be received in OS 2 If the driver detects an access violation OS 2 terminates the process with a trap unless the application has an exception handler registered with OS 2 The return code RC UNIT NOT FUNCTIONING occurs when the driver uses SCB control elements to move the data and the adapter does no respond within an internal driver timeout period The return code RC PIPES NOT CONFIGURED is a warning indicating the memory transfer was completed but the SCB subsystem is not configured A buffer length of 0 is not valid The maximum buffer size is limited to 64 KB The IBM RISC System 6000 uses big endian memory format whereas the 80960 on the ARTIC960 adapter uses little endian format across the PCI or MCA bus It is up to the calling application to perform byte and word swapping where necessary The RICRead and RICWrite functions do not steer the data for the application ARTIC960 Programmer s Reference RICReset Reset an ARTIC960 Adapter RICReset Reset an ARTIC960 Adapter This routine is used to reset an adapter Functional Pr
81. has been received by the software 28 RC UTIL UNIT NOT FUNCTIONING The peer adapters could not be configured to communicate on a peer to peer basis because of the configuration of the adapter Either the adapter full memory window is not present or it is in a location that is inaccessible to the other peer adapter 29 RC UTIL WRNHELP GIVEN Appropriate syntax diagram is displayed for the selected utility 30 RC UTIL RESOURCE BUSY The process is unable to create the resource because it is already being used by another process 31 RC UTIL TIMESET ERROR There was a timeout waiting for a response from the adapter 32 RC UTIL SNGL PIPE ALRDY CONF Peer communications between the adapter and the system unit were successfully configured 33 RC UTIL NOT RUNNING The mailbox process was not found or could not be terminated 34 RC UTIL SNGLPIPE CONF FAILED Configuration failed between the adapter and the system unit 35 RC UTIL SUBSYSTEM NOT FOUND The specified subsystem was not found 328 ARTIC960 Programmer s Reference Exit Codes for System Unit Utilities Exit Code Description 36 RC_UTIL_FILL_ROM_FAILED Fill ROM failed during the ROM update process on the adapter 37 RC_UTIL_ERASE_ROM_FAILED Erase ROM failed during the ROM update process on the adapter 38 RC_UTIL_WRITE_ROM_FAILE
82. have ROM Cannot update the PMC ROM 53 RC_UTIL_UNSUPPORTED_OPT_HARDWARE The option listed is not supported on the current hardware 54 RC UTIL DUMP PROCESS ERROR A regular dump on the card was not initiated before the PMC dump was requested 55 RC UTIL DUMP CONFIG ERROR The config file specified for the PMC dump has too many entries 56 RC UTIL PARM SYNTAX ERROR The format of the parameter is incorrect 58 RC UTIL NO MORE ROM The image is too large for the ROM size Appendix C Return Error and Exit Codes 329 Exit Codes for System Unit Utilities Exit Code Description 59 RC_UTIL_OEM_ROM The image is non RadiSys 330 ARTIC960 Programmer s Reference Glossary A AAL ATM Adaptation Layer Enhances the services provided by the ATM Layer to support functions required by the next higher level BIB Backward indicator bit calling processes Processes that open a signal with a NULL EntryPoint See receiving process counting semaphore Semaphore used for synchronizing processes such as synchronizing a producer consumer pair of processes DMA Direct memory access E explicit semaphore Semaphore that is decremented before control returns to the process H HAL Hardware abstraction layer HPFS High performance file system 80960 interactive computing environment implicit semaphore Semaphores that are decremented when the process calls the appropriate resource service
83. lines displayed and the number of lines on the screen when the Status utility is initiated If the number of data lines would cause the displayed data to scroll off the screen press Enter to continue Also when displaying structures that have lists of data that may potentially be corrupted or very long the Status utility allows the user to abort the display of the list by pressing q key while the list is being displayed The scroll feature is disabled if the number of lines in the current window is less than 25 The following defines the characters used in the data n represents numeric data S represents string data t represents a memory type Chapter 6 System Unit Utilities 227 Status Interactive Messages 228 Main Menu This is the main menu for the Status utility 0 Quit D 1 Configuration 2 Process summary 3 Resource summary 4 emory 5 Process details 6 Process resources 7 Process parameters 8 Resource details 9 Exception conditions 10 VPD Information 11 80960 registers Enter item for display gt Figure 6 17 Status Utility Main Menu The following sections explain each of the options on the Status utility main menu 1 Configuration on page 229 2 Process Summary on page 230 3 Resource Summary on page 231 4 Memory on page 232 5 Process Details on page 233 6 Process Resources on page 237 7 Process Parameters on page 238 8 Resource Details on page 2
84. mailbox buffer 282 memory for trace buffer 50 message units 04 resources 95 timer 5 AllocHW Allocate a Hardware Device 34 AllocVector Allocate an Interrupt Vector 28 AllocVectorMux Allocate an Interrupt Vector 29 ANSI C end of line file 798 ANSI C functions support 73 APIs base services 264 mailbox 276 system unit return codes 3 2 3 6 application loader description 96 messages and exit codes 99 sample calls 200 syntax 96 arguments within quotes 96 arithmetic controls AC register 42 ARTIC960 services 5 ARTIC960 Support for AIX 0 ARTIC960 Support for OS 2 7 ARTIC960 Support for Windows NT 4 assign logical card numbers 95 name to event word 5 amp name to memory 05 process name 34 queue name 95 semaphore 5 timer 54 async handler deregister 45 register 739 asynchronous events DeregisterAsyncHandler 45 notification 738 RegisterAsyncHandler 39 base APIs RICClose 266 RICGetConfig 272 RICGetException 274 RICGetVersion 273 RICOpen 265 RICRead 267 RICReset 27 RICWrite 269 base device driver configuration 6 base kernel services 27 bit map allocation 75 bits defined 27 blank lines in file 196 208 block alignment values 64 call parameter 27 size of 69 books reference xv buffer trace 50 byte swapping 266 270 C C functions ANSI support 73 call device driver 7 kernel mailbox process 8 calling process 7 16 333 calls ANSI C libr
85. message and removes the message from the mailbox This is the default Timeout Input Optional timeout for waiting on semaphore associated with this mailbox There is no timeout Return immediately if there are no mailbox elements Any other value from 1 to 65535 Wait time in milliseconds The granularity of the timer is five milliseconds The timeout value is rounded up to the next multiple of five if it is not already a multiple of five MsgPtr Output Pointer to the received message buffer Size Output Size of the received message buffer Reserved Input Reserved parameter must be 0 ARTIC960 Programmer s Reference ReceiveMbx Receive a Message Returns RC_SUCCESS RC INVALID OPTION RC INVALID RESERVED PARM RC INVALID MEM ACCESS RC INVALID HANDLE RC INVALID CALL RC INVALID RECEIVER RC INVALID TIMEOUT RC MBX EMPTY Remarks dequeued from the message queue Ifthe MBX RECEIVE READ MESSAGE option is set in OptionWord the message is not If the MBX RECEIVE READ MESSAGE option is not set in OptionWord this service removes the first message from the queue and the semaphore associated with the mailbox is decremented Chapter 3 Base Kernel Services 113 CloseMbx Close a Mailbox CloseMbx Close a Mailbox 114 This service releases the mailbox and deletes it if no other process has access to it Fun
86. modified whenever a message is placed in the mailbox In OS 2 it is cleared in AIX the semval variable is set to 0 For information on semval see usr include sys sem h OS 2 Output The semaphore is allocated by the service and the semaphore handle is returned to the application to allow it to be used in OS 2 multiple semaphore waits AIX Input Output The semaphore must be created by the application and removed after CloseMbx The application can then use the semaphore handle for a multiple wait call For input the user must initialize semid and semnum of the RIC_Semhandle see page 279 Upon return semval is initialized to 1 indicating an empty mailbox Reserved Input Reserved parameter must be 0 Returns RC_SUCCESS RC NO MBX PROCESS RC DUP RES NAME RC NO MORE MBX RC INVALID COUNT RC NO MORE MEM RC INVALID NAME RC NO MORE RES RC INVALID OPTION RC NO MORE SEM RC INVALID RESERVED PARM RC SYSTEM ERROR RC INVALID SIZE Remarks Only the process that created the mailbox can receive messages from the mailbox This service call allocates the memory requested by the user This memory is used to keep the messages in the mailbox If the memory name provided by the process is the same as that used on a previous CreateMbx or OpenMbx call this service call gets access to the memory pool already created Otherwise the service call allocates the memory request
87. not displayed if the exception code indicates that no exception condition is present See Figure 6 64 on page 261 for an example a Enter adapter number gt Exception code nnnnnnnn sssssssssssssssss Exception data aaaaaaaa hhhhhhhh hhhhhhhh hhhhhhhh hhhhhhhh Press Enter to continue Figure 6 39 Status Utility Exception Conditions Display Table 6 12 Recognized Exception Conditions Fault Type Exception Processor Fault Operation Processor Fault Arithmetic Processor Fault Constraint Processor Fault Type Mismatch Adapter Fault Watchdog Timeout Adapter Fault Parity Adapter Fault 80960 Memory Protection Violation Adapter Fault System Bus Master Memory Protection Violation Adapter Fault AIB Memory Protection Violation Adapter Fault Async No More Resources Adapter Fault Invalid Interrupt Adapter Fault Processor Adapter Fault NMI Interrupt Adapter Fault PLX Interrupt Adapter Error Power On Self Test Failure Software Error Data Corruption Software Error Adapter POST Failure Software Error System Bus I O Subsystem Failure Software Error SCB Subsystem Failure Software Error External Mailbox Failure 250 ARTIC960 Programmer s Reference Status Interactive Messages 10 VPD Information The following submenu shows the available selections to di
88. number of entries in the configuration file or correct the syntax of the entries in the configuration file and reissue the command Source Dump RIC0087 Explanation The format specified is incorrect Action Correct the format and reissue the command Source Dump RICO100 RICO299 Explanation Action Source These messages are used in the status utility None Status Appendix B Message File 307 RICO300 RICO305 RICO300 gt L path J Correct syntax is ricsettr I E W count D class E class Explanation Set Trace utility syntax help message Action Select the proper parameters and call the Set Trace Source Set Trace RICO301 Correct syntax is gt gt ricgettr card num DIG path O out filename E Explanation Get Trace utility syntax help message Action Select the proper parameters and call the Get Trace Source Get Trace RIC0302 Trace buffer successfully fetched from card nn in file ssssssss Explanation The trace buffer was successfully read from card number nn and written to a file name ssssssss Action None Source Get Trace RIC0303 Run ricfmttr to format and view the trace Explanation After a successful Get Trace this message is displayed to instruct the user to run the Format Utility to analyze the results of the trace Action None Source Get
89. opens a queue previously created by another process Functional Prototype RIC_ULONG OpenQueue char QueueName RIC QUEHANDLE QueueHandle RIC SEMHANDLE SemHandle RIC ULONG Reserved Parameters QueueName Input The queue name used to create the queue QueueHandle Output Queue handle returned to the requesting process This handle is passed to all other queue services when this queue is referenced SemHandle Output Handle of the semaphore used to wait on queue elements This is returned so it can be part of a multiple event wait Reserved Input Reserved parameter must be 0 Returns RC SUCCESS RC INVALID NAME RC NAME NOT FOUND RC NO MORE TIMERS RC NO MORE RES RC INVALID CALL RC INVALID RESERVED PARM RC INVALID MEM ACCESS Remarks This service gets access to a queue already created by another process with the CreateQueue service It is up to the process to ensure that it has read write memory access to the queue elements Multiple processes can read and receive from a single queue ARTIC960 Programmer s Reference CloseQueue Close a Queue CloseQueue Close a Queue This service releases access to a queue and deletes the queue if no other processes have access to it Functional Prototype RIC_ULONG CloseQueue RIC_QUEHANDLE QueueHandle RIC_ULONG Reserved Parameters QueueHandle Input Queue handle of
90. peer to peer adapter operations If the window is not visible on the system bus either not physically mapped or not addressable due to slot constraints peer to peer adapter operations are not supported Multiple Virtual DOS Machines MVDM DOS applications are not supported in ARTIC960 OS 2 Support Device Driver Installation Two pieces of code provide OS 2 device driver support the device driver and a detached process The ARTIC960 OS 2 device driver RICIO16 SYS is installed through CONFIG SYS It is a symmetric multiprocessing safe SMP safe device driver P DEVICE jS ER Ed 6 SYS drive path N Figure 1 1 OS 2 Device Driver Syntax This entry must be placed in the CONFIG SYS file to call the ARTIC960 OS 2 device driver N Disable interrupt nesting Chapter 1 Loading and Configuring 7 Driver Messages The content of the message file is listed in Appendix B Message File on page 295 The following are the messages in that file used by the OS 2 driver Table 1 3 OS 2 Driver Messages Message Number Notes RICO0001 Invalid option RICO002 Invalid parameter RICO0009 Warning message POST error RICO010 Warning message adapter failure RIC0016 System error RICO020 Information only message installing RIC0021 Installed RIC0039 No adapters RIC0049 Unable to install interrupt handler RIC0064 Card ROM error warning RIC0066 Interrupt nesting disabled
91. queue to release Reserved Input Reserved parameter must be 0 Returns RC_SUCCESS RC_INVALID_HAN RC_INVALID_RESERVED_PARM RC_DEPENDENT_EVENTS RC_INVALID_CALL 2 Remarks If the close is issued by a process while other processes still have access to the queue the service removes access rights for the issuing process When the last process with access rights calls this service the queue ceases to exist See the services CreateQueue Create a Queue on page 95 and OpenQueue Open a Queue on page 96 for more information If the close is issued by the kernel on behalf of the process such as when the kernel cleans up resources for a process that is stopped or unloaded all other processes are notified through their asynchronous handlers that the process has gone away Chapter 3 Base Kernel Services 97 PutQueue Put an Element into a Queue PutQueue Put an Element into a Queue 98 This service puts a queue element on a queue and increments the semaphore associated with the queue Functional Prototype RIC_ULONG PutQueue RIC_QUEHANDLE QueueHandle void Element RIC ULONG OptionWord RIC ULONG QueueStatus RIC_ULONG Reserved Parameters QueueHandle Input Handle of queue to add element to Element Input Pointer to element to add to queue OptionWord Input QUE_PUT_LIFO The queue element is added to the head of the queue
92. rc integer P_GETSUBALLOC GetSuballoc Entry BlockPtr integer Exit rc integer P_FREESUBALLOC FreeSuballoc Entry BlockPtr integer Exit rc integer Table 3 15 Service Class C SWTIMER SERVICE Trace Format of Procedure ID Kernel Service Position Trace Data Data P_CREATESWTIMER CreateSwTimer Entry TimerName character Exit rc integer P_CLOSESWTIMER CloseSwTimer Entry TimerHandle integer Exit rc integer P_STARTSWTIMER StartSwTimer Entry TimerHandle integer Exit rc integer P_STOPSWTIMER StopSwTimer Entry TimerHandle integer Exit rc integer Chapter 3 Base Kernel Services 161 Kernel Trace Information Table 3 16 Service Class C_TIMER_SERVICE Trace Format of Procedure ID Kernel Service Position Trace Data Data P_SETSYSTIME SetSystemTime Entry SysTimelnfo Time integer Exit rc integer P_QUERYSYSTIME QuerySystemTime Entry none Exit rc integer P_STARTPERFTIMER StartPerfTimer Entry none Exit rc integer P_STOPPERFTIMER StopPerfTimer Entry none Exit rc integer P_READPERFTIMER ReadPerfTimer Entry none Exit rc integer Table 3 17 Service Class C_CLIB Trace Format of Procedure ID Kernel Service Position Trace Data Data P_FD_STDOUT printf character P FD STDERR printf character 162 ARTIC960 Programmer s Reference Kernel Commands Processes located on a remote card or in the system unit can send command and status requ
93. resources to satisfy the request 0x0001090B RC NO BUFFER The destination mailbox has no receive buffers to accept the message 0x0001090C RC UNABLE TO ACCESS UNIT This unit is unable to perform the requested operation with the peer unit Possible reasons are adapter exception dump active reset active peer unit not functioning 0x0001090D NO MORE REM MBX All of the remote mailboxes have been allocated 0x0001090E RC_REMOTE_CFG_NOT_EST A global search for the named mailbox cannot be made because the remote configuration has not been established This could be because the Configuration Utility has not successfully established system unit lt gt adapter SCB pipes because the system bus I O Subsystem has not been installed successfully on the adapter or because the SCB Subsystem has not been installed successfully on the adapter 0x0001090F RC MBX BUFFER IN QUEUE The buffer is queued currently to a mailbox and has not been received by the mailbox creator 0x00010910 RC INVALID SEMHANDLE Cannot access the semaphore handle Appendix C Return Error and Exit Codes 321 Return Codes Listed Numerically Return Code Description 0x00010A01 RC_NOT_DD_OR_SS This process is not a device driver or subsystem but is attempting to use a service restricted to device drivers and subsystems 0x00010A02 RC_N
94. semaphore 50 create access rights 65 binary file name 203 event word 56 mailbox 104 277 memory 64 memory type 80 process 34 queue 95 semaphore 5 105 signal 715 software timer 54 CREATE_CACHE_DATA option 35 CreateDev Register a Subsystem or Device Driver 22 CreateEvent Create an Event Word 58 CreateMbx Create a Mailbox 104 277 CreateMem Allocate Memory 64 CreateProcess Create a Process 34 CreateQueue Create a Queue 95 CreateSem Create a Semaphore 5 CreateSig Create a Signal 15 CreateSwTimer Allocate Software Timer 54 critical code section 47 D data cache enable 5 1960 197 options 197 data steering 270 DATA_CACHE parameter 80 decimal values parameter 795 default pipe size 207 delete event 60 extraneous quotes in argument 96 mailbox 288 DeregisterAsyncHandler Deregister an Async Handler 145 DeregisterHook Deregister an Entry Point for a Hook 148 DeRegisterResponseMbx command 67 device driver subsystem AllocVector 28 AllocVectorMux 29 asynchronous event notification 738 CloseDev 726 configuration 6 CreateDev 722 DeregisterAsyncHandler 45 DeregisterHook 48 driver call syntax OS 2 Support 7 InvokeDev 727 messages 8 295 OpenDev 25 QueryHW 37 RegisterAsyncHandler 39 RegisterHook 47 ReturnHW 36 ReturnVector 33 ric base rel file RICIO16 SYS 7 SetVector 3 support 2 diagnostic dump 202 disable interrupts preemptions 47 DisableTrace servic
95. space ROM Error The read only memory ROM boot strap microcode not responding in reasonable time during initialization or ROM finds a hardware error during its boot strap initialize or reset Watchdog Timer Interrupt Hard exceptions reported by the ARTIC960 kernel or the adapter ARTIC960 Watchdog Timeouts Adapter Kernel Exception Software exceptions by the ROM or the kernel Trace Facility The AIX Support device driver provides trace hooks to monitor the entry and exit of the driver routines and the interrupt routine The trace event is 29F Chapter 1 Loading and Configuring 13 ARTIC960 Support for Windows NT The following sections describe the ARTIC960 Support for Windows NT Supported ARTIC960 Configurations The ARTIC960 Support for Windows NT uses the hardware abstraction layer HAL to configure the configurable hardware options such as interrupt level I O addresses and system bus memory configurations Device Driver Installation The Windows NT Version 4 0 device driver is installed when the ARTIC960 Support for Windows NT is installed The driver is started at boot time It is a symmetric multiprocessing SMP safe device driver Mailbox Process The ARTIC960 Support for Windows NT supports card to card mailbox activity However the System Unit mailbox process is not supported Event Logging Four types of events are logged to the Windows NT Event Log for any particular ARTIC960 device Configurat
96. special processing to handle the OS 2 lt Ctrl gt lt Break gt or lt Ctrl gt lt C gt program termination signals e Ifthe user breaks out of a load operation it may be necessary to unload partially loaded process or reset the card to continue If the user breaks out of the Configuration utility or out of an active dump a reset is required to continue e If the user breaks out of a dump while waiting with an exception trigger set no action should be necessary Utilities that use input files use the following as search criteria to find the required file e Current directory e RICPATH environment variable e DPATH environment variable for OS 2 and Windows NT and PATH environment variable in AIX and Windows NT If the file is not found using this search criteria the appropriate error code is returned For all utilities the length of the command line is limited to 256 bytes lines within files processed by the utilities are limited to a length of 256 bytes including the end of line sequence The number of entries within configuration files and parameter files is unlimited Chapter 6 System Unit Utilities 195 Application Loader ricload Utility Application Loader ricload Utility The Application Loader is a command line driven utility that loads processes onto the ARTIC960 adapter The Application Loader does not require the presence or absence of any optional parameters to specify other optional parame
97. support personnel Source OS 2 Driver RIC0040 Dump on card nn already active Explanation An attempt to call the dump utility on card nn failed because dump was already active for that adapter Action Wait until the dump of the card has completed Source Dump Appendix B Message File 301 RIC0041 RICO047 RIC0041 Peer communications not configurable with current hardware options Explanation The peer adapters could not be configured to communicate on a peer to peer basis due to the configuration of the adapter Either the adapter full memory window is not present or it is ina location that is inaccessible to the other peer adapter This error can only be received in PS 2 systems Action Use the Reference Diskette to configure the location of the adapter memory window to allow the two adapters to communicate In address constrained environments it may be necessary to move an adapter from a 16 bit slot to a 32 bit slot to enable the necessary configuration Source Configuration RIC0042 WARNING Process mismatch Explanation The file to be loaded was compiled for a processor type that is different from the one on the ARTIC960 adapter Action Recompile the file for the appropriate processor type Source Application Loader RIC0043 Peer communications pipe size out of range Explanation The peer adapters could not be configured to communicate on a peer to peer basis because the specified pipe size w
98. the mutual exclusion semaphore may have been left in an indeterminable state When this happens the semaphore count is reset to one so the semaphore can be re requested if the application process knows that the protected code and data is in a valid state Chapter 3 Base Kernel Services 53 ReleaseSem Release a Semaphore ReleaseSem Release a Semaphore 54 This service makes a semaphore available to the next process waiting for it Functional Prototype RIC ULONG ReleaseSem RIC SEMHANDLE SemHandle RIC ULONG Reserved Parameters SemHandle Input Handle of semaphore to increment Reserved Input Reserved parameter must be 0 Returns RC SUCCESS RC INVALID HANDLE RC INVALID RESERVED PARM RC SEM NOT OWNED Remarks The next process waiting for the semaphore is posted if this is the only semaphore for which it is waiting If no processes are waiting the semaphore count is incremented A mutual exclusion semaphore cannot be released with this service twice by the same process unless it does a RequestSem in between In addition a mutual exclusion semaphore cannot be released by a process other than the one that last requested it ARTIC960 Programmer s Reference RequestSem Request a Semaphore RequestSem Request a Semaphore This service waits for a semaphore Functional Prototype RIC_ULONG RequestSem RIC_SEMHANDLE SemHandle RIC_TIMEOUT Time
99. this service has been called for successful initialization This service is optional for normal processes However to use the W option of the Application Loader utility the process must use this service Chapter 3 Base Kernel Services 23 Completelnit Mark Process as Completely Initialized If the caller passes a non zero value in ErrorCode the process is stopped and does not regain control after the call The ErrorCode is intended as a safety net for reporting status when no other method is available for example the process was not able to open a mailbox If a process wants to report non error initialization status another communications mechanism should be used Although the ProcessRev format is not required it is recommended that application programmers implement it because the diagnostic utility RICSTAT uses this field 24 ARTIC960 Programmer s Reference QueryProcessStatus Get the Process Status QueryProcessStatus Get the Process Status This service gets the status and other process related information accepting either a process name or process ID for input When a process name is specified this service resolves it to a process ID Functional Prototype RIC_ULONG QueryProcessStatus char ProcessName RIC_PROCESSID ProcessID RIC_ULONG OptionWord struct RIC_ProcessStatusBlock PSBBufferPtr RIC_ULONG BufferSize RIC_ULONG Reserved Parameters ProcessName Input Process name whose s
100. to determine the cause of the failure Source Reset RIC0035 Invalid microcode load Explanation The adapter kernel is not loaded Action Make sure that the kernel is properly loaded before attempting to load another process Source Application Loader RIC0036 Peer communications between cards xx and yy successfully configured Explanation The SCB delivery pipe was successfully configured Action None Source Configuration RIC0037 Microcode error Internal error xxxx Explanation The adapter kernel unexpectedly returned an error xxxx is an internal error code Action Verify that the kernel is properly loaded and there is enough memory available to satisfy Application Loader requests xxxx is an internal kernel error code that generally maps to a kernel return code If the problem persists call support personnel Source Application Loader Configuration RIC0038 Error accessing card nn Internal error nnnn Explanation An unexpected error was returned by the device driver while accessing card nn xxxx is an internal error code that generally maps to a device driver return code Action Call support personnel Source Application Loader Dump Status Configuration and Reset RIC0039 XXXXXXxXxxX not installed no adapters found Explanation The driver xxxxxxxx did not install because no ARTIC960 adapters were found Action Verify that an adapter is installed before attempting to install the driver If the problem persists call
101. value is interpreted as a conditional call Only receiving processes that have a matching SigHanID or that set their Always flag get control Parms Input Pointer to parameters to pass to receiving processes ParmLen Input Size of parameters to pass to receiving processes Reserved Input Reserved parameter must be 0 Returns RC SUCCESS RC CALL TERMINATED RC INVALID RESERVED PARM RC INVALID HANDLE RC NO SUCH SIG ID RC INVALID MEM ACCESS Remarks Before passing control to a receiving process the kernel changes the memory protection to allow the receiving process to access the parameter block as well as its own memory code data and stack This is also true for a subsystem or device driver with memory protection turned on The OPTION PROT OFF option in the OptionWord parameter of CreateDev is used to determine if memory protection is enabled for signals received by a device driver or subsystem 120 ARTIC960 Programmer s Reference Device Driver Subsystem Services Device Driver Subsystem Services The following are the device driver subsystem services Service Name Page CreateDev 122 OpenDev 125 CloseDev 126 InvokeDev 127 AllocVector 128 AllocVectorMux 129 SetVector 131 SetVectorMux 132 ReturnVector 133 AllocHW 134 ReturnHW 136 QueryHW 137 Refer to the ARTIC960 Programmer s Guide for additional information Chapter 3 Base Kernel Servi
102. 000 0000 0000 0000 0x00000100 0000 0000 0000 0000 0000 0000 0000 0000 0x00000110 0000 0000 0000 0000 0000 0000 0000 0000 0x00000120 0000 0000 0000 0000 0000 0000 0000 0000 0x00000130 0000 0000 0000 0000 0000 0000 0000 0000 0x00000140 0000 0000 0000 0000 0000 0000 0000 0000 0x00000150 0000 0000 0000 0000 0000 0000 0000 0000 0x00000160 0000 0000 0000 0000 0000 0000 0000 0000 0x00000170 0000 0000 0000 0000 0000 0000 0000 0000 0x00000180 0000 0000 0000 0000 0000 0000 0000 0000 0x00000190 0000 0000 0000 0000 0000 0000 0000 0000 0x000001A0 0000 0000 0000 0000 0000 0000 0000 0000 0x000001B0 0000 0000 0000 0000 0000 0000 0000 0000 0x000001C0 0000 0000 0000 0000 0000 0000 0000 0000 0x000001D0 0000 0000 0000 0000 0000 0000 0000 0000 0x000001E0 0000 0000 0000 0000 0000 0000 0000 0000 0x000001F0 0000 0000 0000 0000 0000 0000 0000 0000 0x00000200 FFFF FFFF FFFF FFFF FFFF FFFF FFFF FFFF 0x00000210 FFFF FFFF FFFF FFFF FFFF FFFF FFFF FFFF 0x00000220 FFFF FFFF FFFF FFFF FFFF FFFF FFFF FFFF 0x00000230 FFFF FFFF FFFF FFFF FFFF FFFF FFFF FFFF 0x00000240 FFFF FFFF FFFF FFFF FFFF FFFF FF Chapter 6 System Unit Utilities 205 Dump Utility Dump Messages and Exit Codes The contents of the message file used by all utilities are listed in Appendix B Message File on page 295 The messages used by the Dump utility are listed in Table 6 2 The Dump utility also sets its exit code value to i
103. 0010015 RC INVALID NUM RES 0x0001 1202 312 ARTIC960 Programmer s Reference Return Codes Listed Alphabetically Return Code VALUE RC INVALID OPTION 0x00010016 RC INVALID PIN 0x00010B04 RC INVALID PRIORITY 0x0001020A RC INVALID PROCEDURE ID 0x0001 1003 RC INVALID PROCESSID 0x00010106 RC INVALID RECEIVER 0x00010903 RC INVALID RESERVED PARM 0x0001001C RC INVALID SEM COUNT 0x00010402 RC INVALID SEMHANDLE 0x00010910 RC INVALID SERVICECLASS 0x0001 1002 RC INVALID SIZE 0x0001001D RC INVALID SUBALLOC ADDR 0x00010304 RC INVALID TICKS 0x8001 1502 RC INVALID TIMEOUT 0x0001001E RC INVALID TIMER 0x8001 1501 RC INVALID UNIT NUMBER 0x0001000F RC INVALID VECTOR 0x00010B01 RC INVOKE ENTRY FAILURE 0x00010A05 RC MBX BUFFER IN QUEUE 0x0001090F RC MBX EMPTY 0x00010906 RC MC BUS FAULT 0x0001130F RC MC CHAINING EX ERR 0x0001 1309 RC MC CARD SEL FDBACK ERR 0x0001 1303 RC MC CHCK ERR 0x0001 1302 RC MC DATA PARITY ERR 0x0001 1301 RC MC EXCEPTION ERR 0x0001 1306 RC MC INVALID COMBINATION 0x00011308 RC MC LOCAL BUS PARITY ERR 0x0001 1305 RC MC LOSS OF CHANNEL ERR 0x0001 1304 RC MC MASTER ABORT 0x0001130E MC MEM FAULT 0x0001 1310 RC MC POSTSTAT EX ERR 0x0001130A RC MC SERR 0x0001130D RC MC TARGET ABORT 0x0001130C RC MC TIMEOUT 0x0001 1307 RC MEM SHARING ERROR 0x0001 0301 RC MOVE ASYNC AL
104. 326 Trace successfully set on card nn Explanation The Set Trace command was successfully executed on card number nn Action None RIC0350 RICO399 Explanation These messages are used for the ROM Update Utility Action None Source ROM Update RIC0400 RIC0460 Explanation Action Source These messages are used for the RICDiag utility None RICDiag Appendix B Message File 309 RIC0400 RICO0460 RICO400 RICO460 310 ARTIC960 Programmer s Reference Return Error and Exit Codes This appendix contains a listing of the codes used by programs and applications in the ARTIC environment Return codes are returned by the various routines and services provided by the ARTIC960 APIs These codes are listed in alphabetic and numeric order The numeric listing includes a description of the exception condition The terminal error codes for the adapter returned by the kernel and the exit codes returned by the system utilities are listed in numeric order only e Return Codes Listed Alphabetically on page 312 e Return Codes Listed Numerically on page 316 Kernel Terminal Error Codes on page 325 e Exit Codes for System Unit Utilities on page 327 Appendix C Return Error and Exit Codes 311 Return Codes Listed Alphabetically Return Codes Listed Alphabetically
105. 39 9 Exception Conditions on page 250 10 VPD Information on page 251 11 80960 Registers on page 252 This option is displayed only if the Status utility is called on a dump file with the F switch Vector details are available only when specified by name or number See Vector Resource Details on page 249 for an explanation of the displayed information See Figure 6 63 on page 260 for an example ARTIC960 Programmer s Reference Status Interactive Messages 1 Configuration The following screen shows the prompts and items displayed when the Configuration option is chosen from the main menu e Ifamemory window is not configured its data line is not displayed e On 2 systems with PCI cards the Slot Number field displays FF e Valid values for Bus Type are MCA or PCI e Valid values for Interface Chip are Miami MiamiP2P or Rx e Valid values for Data Cache HW are Present or Not Present e To the right of the AIB ID is a descriptive AIB name Ifthe daughter card type is a PMC and the card is not present 0X00000000 is displayed IfaPMC card is present OXFFFFFFFF PMC Adapter Present is displayed e The Total memory size is first shown in bytes To the right of the size in bytes is the memory size converted to megabytes See Figure 6 44 on page 253 for an example C Enter adapter number gt Slot number nn Card ID nnnnnnnn Bus Type SSS nterface Chip SSSS Data Cache HW SSSSSSS
106. 4 RC PIPE FULL 0x0001000C RC PIPES NOT CONFIGURED 0x00010017 RC PROCESSES WAITING ON SEM 0x00010408 RC PROCESS ALREADY STARTED 0x0001 0203 RC PROCESS NOT LOADED 0x0001 0202 RC PROCESS NOT STARTED 0x0001 0201 RC PROCESS STOPPED 0x0001 0205 RC QUEUE EMPTY 0x0001 0801 RC REMOTE CFG NOT EST 0x0001090E RC RESET ACTIVE 0x00010004 RC RESET FAILED 0x00010005 RC SCB INIT ERROR 0x0001 1101 RC SCB TRANSFER FAILED 0x00010006 RC SEM ALREADY OWNED 0x00010407 RC SEM NOT OWNED 0x00010409 RC SU INVALID HANDLE 0x00000006 OS 2 0x00000009 AIX RC SU OPEN FAILED 0x0000006E 0x00000013 AIX RC SUCCESS 0x00000000 RC SYSTEM ERROR 0x00010007 RC TIMEOUT 0x00010018 314 ARTIC960 Programmer s Reference Return Codes Listed Alphabetically Return Code VALUE RC TIMER IS ACTIVE 0x00010702 RC TIMER IS INACTIVE 0x00010703 RC TIMER OVERFLOWED 0x00010706 RC TOD NOT ENABLED 0x00010705 RC TRACE NOT INITIALIZED 0x0001 1001 RC UNABLE TO ACCESS UNIT 0x0001090C RC UNABLE TO CONVERT ADDRESS 0x0001130B RC_UNIT_NOT_FUNCTIONING 0x0001000E RC_UNSUPPORTED_FUNCTION 0x00010107 RC_VECTOR_NOT_ALLOCATED 0x00010B03 RC_VECTOR_NOT_AVAILABLE 0x00010B02 RC WRN PIPES NOT CONFIGURED 0x00010008 Appendix C Return Error and Exit Codes 315 Return Codes Listed Numerically Return Codes Listed Numerically See Mailbox Process Messages and Return Codes on page 13 for mailbox process return codes
107. 5 The messages used by the Get Trace utility are listed in Table 6 6 The Get Trace utility also sets its exit code value to indicate the status of the Get Trace operation The following table correlates the exit code of the Get Trace utility with the messages Table 6 6 Get Trace Utility Messages and Exit Codes Message Number Exit Code Notes RIC0001 RC_UTIL_INVALID_CMDLINE_OPTION RIC0002 RC_UTIL_INVALID_CMDLINE_PARM RIC0004 RC_UTIL_FILE_ACCESS RIC0005 RC_UTIL_INVALID_CARD_NUMBER RIC0010 RC_UTIL_NO_ADAPTER_RESPONSE RIC0016 RC_UTIL_SYSTEM_ERROR RIC0019 RC_UTIL_NOT_INSTALLED RIC0038 RC UTIL ACCESS ERROR RICO301 RC UTIL WRNHELP GIVEN RIC0302 RC_UTIL_SUCCESS Successful Get Trace operation RIC0303 None Information message to run Format Trace utility RIC0305 None Trace is not initialized ARTIC960 Programmer s Reference Format Trace Utility Format Trace Utility The Format Trace utility allows users to format the data obtained in a file by the Get Trace utility The formatted data consists of the fields of the Trace Control Block which contains general information about the trace and the trace data of the service classes enabled by the Set Trace utility The trace data is in the form of records to enhance readability The utility requires a service class file to correlate the service classes and procedure names to service class numbers and procedure IDs The text fil
108. 86 stop 88 standard input output devices 223 start allocated block alignment 64 mailbox process 8 performance timer 9 priority process 798 process 36 process examples 200 software timer 86 STARTED STOPPING states 27 StartPerf Timer Start the Performance Timer 97 StartProcess Start a Process 36 171 StartSw Timer Start a Software Timer 86 status utility description 223 interactive message examples 227 253 main menu 228 status get process 25 stop performance timer 92 process 37 software timer 88 StopPerfTimer Stop the Performance Timer 92 StopProcess Stop a Process 37 170 StopSwTimer Stop a Software Timer 88 structure 35 suballocation free memory 78 GetSuballoc 77 GetSuballocSize 79 prepare memory block 75 Subsystem Control Block SCB 2 332 summary ARTIC960 services 5 kernel services 5 support xv supported adapters suspend process 39 SuspendProcess Suspend a Process 39 syntax Configuration utility 208 Format Trace 2 7 Get Trace 2 5 mailbox process Reset utility 2 0 Set Trace 2 5 Status utility 224 system bus interface ConvertCardToMC 782 ConvertMCToCard 781 I O subsystem parameters 6 MoveMCData 77 ric mcio rel I O subsystem file 2 system executables system time 98 system unit APIs base RICClose 266 RICGetConfig 272 RICGetException 274 RICGetVersion 273 RICOpen 265 RICRead 267 RICReset 271 RICWrite 269 mailbox CloseMbx 288 CreateMbx 277 FreeMbxBu
109. 960 Programmer s Reference SetExitRoutine Set the Exit Routine for the Process SetExitRoutine Set the Exit Routine for the Process This service sets the exit routine for the process Functional Prototype RIC_ULONG SetExitRoutine RIC_VECTOR ExitRoutine RIC_ULONG Reserved Parameters ExitRoutine Input Address of the routine the kernel calls when this process is stopped normally or abnormally Reserved Input Reserved parameter must be 0 Returns RC_SUCCESS RC_INVALID_RESERVED_PARM RC_INVALID_CALL RC INVALID MEM ACCESS Remarks The kernel calls the ExitRoutine of the process when the process is stopped whether it was normal or abnormal because of asynchronous errors This service is mapped to the C function atexit which allows the registration of multiple exit handlers No kernel trace information is provided for this service Chapter 3 Base Kernel Services 41 SetPriority Set the Priority of the Process SetPriority Set the Priority of the Process 42 This service changes the priority of the current process Functional Prototype RIC_ULONG SetPriority Parameters ProcessID Input Sets this calling process RIC_PROCESSID ProcessID RIC_ULONG Priority RIC_ULONG Reserved process ID to the new priority A value of 0 means the Priority Input New priority of the process A value of 0 means the default priority Reserved Input
110. ALID CALL RC INVALID BASEPTR RC INVALID ALIGNMENT RC INVALID SIZE Remarks The block must be contained within memory that is accessible to the calling process The suballocation unit size helps tune the suballocation services for higher performance and lower memory utilization The suballocation unit size should be as large as possible while still mapping well to the size of the expected suballocations Bit map allocation is used to implement suballocation the larger the unit size the fewer the bits required to represent the pool This results in smaller bit map size and quicker searches of the bit map Chapter 3 Base Kernel Services 75 InitSuballoc Prepare a Block of Memory for Suballocation When calculating the alignment of suballocation chunks this service rounds the unit size up to the next power of two The actual alignment is the larger of this rounded value and the alignment represented by the Alignment parameter For example e A unit size of 4 bytes and Alignment value of 0 1 byte boundary result in suballocation on 4 byte boundaries Aunitsize of 4 bytes and an Alignment value of 4 16 byte boundary result in suballocation on 16 byte boundaries e A unit size of 3 and an Alignment value of 1 2 byte boundaries result in suballocation on 4 byte boundaries Use GetSuballocSize to determine the proper size of the block to accommodate the requested number of suballocation units and the bit map 76 ART
111. ALID MEM ACCESS RC MC POSTSTAT EX ERR RC INVALID CALL RC RESET ACTIVE RC MC DATA PARITY ERR RC MC MASTER ABORT RC MC CHCK ERR RC MC BUS FAULT RC MC CARD SEL FDBACK ERR RC MC EM FAUL Remarks The caller of this service must ensure that a reset does not occur during a System bus operation e This function may block the requesting process The function returns to the caller when the move is complete e To open the system bus I O subsystem issue the following command OpenDev MCSSNAME void NULL 0 amp DDhandle e The source and destination units must be different and one must be the requester unit e validation is done on the physical system bus addresses e The logical card number is checked for validity If memory protection is enabled the local memory address is checked for system bus access and a RC INVALID MEM ACCESS error is returned if access is not correct e unsupported system unit address can generate a channel check e Because requests can be passed to two different system bus DMA channels the order of message delivery is not guaranteed The order is guaranteed only within a chain moves chained in the same MoveMCData request To ensure correct operation such requests should be issued in separate MoveMCData requests V This function does not support mixing of card to card and card to system unit Chapter 5 Adapter Library Routines 179
112. ALID PROCESSID Remarks This service can be called from an interrupt handler or a call handler However doing so with a ProcessID value of 0 may give unexpected results and should be used with caution While in an interrupt handler the process in execution is considered to be the kernel While in a call handler the process in execution is considered to be the process that called the handler If call processes are nested it is the process that called the first handler ARTIC960 Programmer s Reference EnterCritSec Enter Critical Section EnterCritSec Enter Critical Section This service disables interrupts and or preemptions Functional Prototype RIC ULONG EnterCritSec RIC ULONG OptionWord RIC ULONG Reserved Parameters OptionWord Input DISABLE INTERRUPTS If ORed into the option word interrupts are disabled the default is not to change the interrupt state DISABLE PREEMPTION If ORed into the option word preemption is disabled the default is not to change the preemption state Failure to select either option causes an RC INVALID OPTION to be returned Reserved Input Reserved parameter must be 0 Returns RC SUCCESS RC INVALID RESERVED PARM RC INVALID CALL RC INVALID OPTION Remarks The number of calls to enable interrupts must match the number of calls to disable interrupts similar to pushes and pops of a stack The same is true f
113. BM Publications IBM Operating System 2 OS 2 Version 3 0 Advanced Interactive Executive AIX Version 4 1 and 4 2 IBM AIX Version 4 x Kernel Extensions and Device Support Programming Concepts SC23 2207 For information about writing a STREAMS module or driver refer to the AIX Web site http www rs6000 ibm com doc link en US a doc lib aixprogd progcomc str prgref htm AIX supports a subset of SVR4 2 STREAMS calls and the on card STREAMS subsystem supports a subset of AIX STREAMS IBM Personal System 2 Hardware Reference S85 F 16786 IBM XL C Language Reference SC09 1260 Intel Publications i960 RP Microprocessor User s Manual i960 Rx I O Microprocessor Developer s Manual i960 Hx Microprocessor User s Manual i960 Cx Microprocessor User s Manual 80960CA User s Manual Developer s Assistance Program xvi Programming and hardware development assistance is provided by the RadiSys ARTIC Developer s Assistance Program DAP The DAP provides via phone and electronic communications on going technical support such as sample programs debug assistance and access to the latest microcode upgrades You can get more information or activate your free membership in the RadiSys ARTIC DAP by contacting us By telephone call 561 981 3200 By E mail send to artic radisys com ARTIC960 Programmer s Reference Loading and Configuring This chapter contains information about loading and
114. Block RIC_ULONG OptionWord RIC_CARDNUM SourceCard RIC_CARDNUM DestCard void SourceAddptr void DestAddptr RIC_ULONG Size struct RIC MoveBlock ChainPtr OptionWord Input Specifies options that can be selected for system bus operations See the Remarks section for option information SourceCard Input The logical card number for the ARTIC960 adapter source unit A valid ARTIC960 logical card number indicates that the source address specifies a local address on that unit MC_SU_ADDR_CARD_NUMBER This value indicates that the source unit is the system unit and that the source address specifies a physical system bus address for the system unit Chapter 5 Adapter Library Routines 177 MoveMCData Move System Bus Data MC_ADPT_ADDR_CARD_NUMBER This value indicates that the source unit is not an ARTIC960 adapter and that the source address specifies a physical system bus address for that adapter bus address ARTIC960 Support for AIX Version 1 1 or higher and ARTIC960 Support for NT Version 1 0 do not support DMA transfers between two peer adapters They support DMA transfers only between the adapter and system unit W An ARTIC960 address cannot be expressed as a physical system DestCard Input The logical card number for the ARTIC960 adapter destination unit A valid ARTIC960 logical card number indicates that the destination address specifies a local address on that unit MC_SU_ADDR_CA
115. C_SERR A SERR error was returned on a system bus operation on the ARTIC960 PCI card 0x0001130E RC MC MASTER ABORT A master abort error was returned on a system bus operation on the ARTIC960Rx PCI card Appendix C Return Error and Exit Codes 323 Return Codes Listed Numerically Return Code Description 0x0001130F RC MC BUS FAULT A bus fault error was returned on a system bus operation on the ARTIC960Rx PCI card 0x0001310 RC MC MEM FAULT A memory fault error was returned on a system bus operation on the ARTIC960Rx PCI card 0x0001 1401 RC PCI NO BIOS PCI driver not installed or card does not have a local PCI bus 0x0001 1402 RC PCI INVALID COMMAND An invalid IOCTL number was issued to the PCI driver This happens only when the driver library services are not being used 0x0001 1403 RC PCI BAD REGISTER NUMBER An invalid configuration register number was specified 0x0001 1404 RC PCI DEVICE NOT FOUND The PCI device is not present 0x8001 1401 RC MOVE ASYNC HANDLER NOT REG The service called requires an async handler to be registered 0x8001 1402 RC MOVE ASYNC ALREADY REG The subsystem name is already registered as a move async handler 0x8001 1501 RC INVALID TIMER A bad timer number was given to the base subsystem 0x8001 1502 RC INVALID TICKS The base subsystem attempted to start a hardware timer with zero ticks 0x8001 1601 RC BAD QUEUE ELEMENT An internal link list is invalid
116. D Write ROM failed during the ROM update process on the adapter 39 RC_UTIL_CHECKSUM_FAILED Checksum procedure failed during the ROM update process on the adapter 40 RC UTIL DATA COMPARE FAILED ROM Update on the adapter failed After the new image was written to the ROM a comparison was done with the ROM image supplied This comparison failed 41 RC UTIL INVALID VPD DATA Invalid data was detected in the VPD data file 42 RC UTIL INVALID VPD FILE Invalid VPD file format The VPD file specified does not conform to the required format 43 RC UTIL INVALID SERIAL NUMBER The serial number specified is invalid 44 RC UTIL AIB VPD NOT FOUND VPD information not found in the file specified 45 RC UTIL AIB NOT INSTALLED AIB option is not installed An attempt was made to update a card that is not installed 46 RC UTIL INVALID MFG ID NUMBER The manufacturer ID specified is invalid 47 RC UTIL BASE VPD NOT FOUND VPD information not found in the file 48 RC UTIL UNSUPPORTED OPTION The option listed is not supported The option is not supported in this environment 49 RC UTIL INVALID ROM FILE ROM image file specified for ROM update is not valid for the specified card 50 RC UTIL ROM FILE WARNING The specified ROM image file cannot be positively identified for the specified card 51 RC_UTIL_PROTECT_ROM_SECTOR One of the sectors of the flash is write protected and cannot be updated by the ROM update utility 52 RC_UTIL_NO_ROM_FOR_PMC The PMC card does not
117. D pciID Parameters DevicelD Input The PCI device ID VendorID Input The PCI vendor ID Instance Input The instance number of the device The first device with a given device and vendor ID is instance zero The next device with the same device and vendor ID is instance one pcilD Output If the device is found a unique identifier for the device is returned This identifier is then used when accessing the device on subsequent PCI driver calls Returns RC SUCCESS RC PCI NO BIOS RC PCI DEVICE NOT FOUND Remarks To find multiple devices having the same vendor ID and device ID the calling software should make successive calls to this function starting with Instance set to zero and incrementing it until the return code is RC PCI DEVICE NOT FOUND ARTIC960 Programmer s Reference pciFindClassCode Find a PCI Device by PCI Class Code pciFindClassCode Find a PCI Device by PCI Class Code This service finds a specific PCI device given a class code Functional Prototype RIC ULONG pciFindClassCode PCI CLASS CODE ClassCode PCI INSTANCE Instance PCI ID pcilD Parameters ClassCode Input The PCI device class code Instance Input The instance number of the device The first device with the given class code is instance zero The next device with the same class code is instance one pciD Output If the device is found a unique identifier for the device is returned This identi
118. D TIMEOUT The timeout value given must be between 0 and OxFFFF or 1 0x0001001F RC NO MORE RES Either no more of the resource is available for allocation or not enough internal kernel control blocks are available to handle the allocation If the latter is true increasing the maximum value for the resource type removes this constraint All available internal Mailbox Process resources have been allocated 0x00010020 RC INVALID HANDLE Aninvalid resource handle was passed to a resource service The user can use only handles returned by the Create and Open services In addition implicit semaphore handles returned by CreateQueue and CreateMbx cannot be passed directly to ReleaseSem or RequestSem They can be passed only to WaitEvent To wait on a single implicit semaphore use GetQueue or ReceiveMbx Aninvalid semaphore handle or an invalid lock was passed to the call 0x00010021 RC DMA TRANSFER FAILED RICRead or RICWrite attempted to obtain direct memory access to the data and a failure was reported by the operating system This is an AIX only return code 0x00010101 RC DUP RES NAME The same name cannot be used to create two resources of the same type Resources of different types can have identical names 0x00010102 RC NO RES ACCESS The requester does not have access to the resource Global mailboxes of the same name exist on two or more units 0x00010103 RC NAME NOT FOUND The open resource name does not match any
119. DLER Entry point of code address for a CloseDev entry point RIC_DIHANDLER Entry point of code address for an nvokeDev entry point RIC_VECTOR_MUX Code address Chapter 2 ARTIC960 Kernel Services 19 20 ARTIC960 Programmer s Reference Base Kernel Services The realtime multi tasking kernel which is downloaded to the adapter provides the following base services Service Group Page Process management 22 Process synchronization 50 Memory management 63 Timer 83 Process communication 94 Device driver subsystem 121 Asynchronous event notification 138 Hooks 146 Kernel trace 149 Chapter 3 Base Kernel Services 21 Process Management Services Process Management Services The following are the process management services Service Name Page Completelnit 23 QueryProcessStatus 25 QueryCardlnfo 28 QueryConfigParams 31 CreateProcess 34 StartProcess 36 StopProcess 37 UnloadProcess 38 SuspendProcess 39 ResumeProcess 40 SetExitRoutine 41 SetPriority 42 QueryPriority 43 QueryProcessInExec 44 SetProcessData 45 GetProcessData 46 EnterCritSec 47 ExitCritSec 48 Dispatch 49 Refer to the ARTIC960 Programmer s Guide for additional information 22 ARTIC960 Programmer s Reference Completelnit Mark Process as Completely Initialized Completelnit Mark Process as Completely Initialized This service notifies the kernel t
120. Device data aaaaaaaa hh hh hh hh hh hh hh hh hh hh hh hh hh hh hh hh CCCCCCCCCCCCCCCC Figure 6 37 Hardware Device Detail Display 248 ARTIC960 Programmer s Reference Status Interactive Messages Vector Resource Details The following screen shows the prompts and items displayed when a vector resource number or name is specified on the main menu e The entries in the Access list fields show all processes that have access to the resource e Valid values for the Protection field are enabled and disabled e Valid values for the Return Code field are yes and no See Figure 6 63 on page 260 for an example 7 Enter adapter number gt Enter resource name or handle gt Resource type vector Vector nnnnnnnn Access list Proc No Process Name Handle Handler Protection Return Code nnnnnnnn ssssssssssssssss nnnnnnnn nnnnnnnnnn 5555555555 5555555555 Figure 6 38 Vector Detail Display Chapter 6 System Unit Utilities 249 Status Interactive Messages 9 Exception Conditions The following screen shows the prompts and items displayed when the Exception conditions option is chosen from the main menu e The exception code is interpreted and a descriptive string is displayed if the exception is a predefined exception condition Table 6 12 lists the recognized exceptions The entries in the Exception data fields show the data for all exception conditions However the Exception data fields are
121. EMOTE MAILBOX The maximum number of remote mailboxes opened from the system unit The default is 16 MAX REMOTE MAILBOX OPEN The maximum number of remote mailbox open requests outstanding at any one time The default is 16 MAX REMOTE MAILBOX SEND The maximum number of remote mailbox send requests outstanding at any one time The default is 32 MAX REMOTE MAILBOX RCV The maximum number of remote mailbox receive requests outstanding at any one time The default is 64 MAX NUM OF UNITS The maximum number of SCB units The default is 16 MBX PROCESS PRI CLASS The priority class of the mailbox process as listed below The default is 4 1 Idle 2 Regular 3 Timecritical 4 Fixed high MBX PROCESS PRI DELTA The priority delta of the mailbox process The priority delta parameter is a decimal value in the range 31 to 31 The default is 0 PEER TIMEOUT Timeout value in seconds when communicating with peer processes Valid values are 1 to 60 The default is 5 For remote mailbox processing to occur the Configuration utility must be used to establish communication between the system unit and adapters For information on this utility see Configuration Utility on page 207 Mailbox Process Messages and Return Codes The content of the message file is listed in Appendix B Message File on page 295 The following table correlates the return code of the drive
122. EPTION The adapter has detected an exception condition RC UTIL ALREADY STARTED The process was already running on the adapter RC UTIL DUP RES NAME A process with the same name has already been loaded on the adapter RC UTIL FILE ACCESS An error was received when attempting to access a file RC UTIL FILE FORMAT A file is not in the proper format The Application Loader returns this message when a process file does not have the proper executable format The status utility returns this message when a dump file does not have the proper format The trace formatter returns this message when the input trace file is not in the proper format RC UTIL FILE NOT FOUND A file does not exist or is not in the specified directory Under AIX it may indicate a file permissions problem RC UTIL INVALID CMDLINE OPTION An option is not a valid command line option RC UTIL INVALID CMDLINE PARM A parameter is invalid Either a required parameter is missing or a optional parameter has been improperly specified RC UTIL INVALID MICROCODE The RadiSys ARTIC960 kernel is not loaded RC UTIL INVALID NAME The process name is too long RC UTIL MICROCODE ERROR The kernel unexpectedly returned an error RC UTIL NAME NOT FOUND The process was not found on the adapter and could not be unloaded Appendix C Return Error and Exit Codes 327 Exit Codes for System Unit Utilities Exit Code Descri
123. ERVED PARM RC INVALID MEM ACCESS RC INVALID OPTION 1 Remarks None 74 ARTIC960 Programmer s Reference InitSuballoc Prepare a Block of Memory for Suballocation InitSuballoc Prepare a Block of Memory for Suballocation This service prepares a block of allocated memory area for suballocation Functional Prototype RIC_ULONG InitSuballoc void BlockPtr RIC_ULONG Size RIC_ULONG Alignment RIC_ULONG SuballocUnit RIC_ULONG Reserved Parameters BlockPtr Input Pointer to block of memory On cards that support big endian memory regions the memory must have been created as little endian If a big endian pointer is given RC INVALID BASEPTR is returned Size Input Size of block in bytes Alignment Input Boundary alignment of suballocated memory Alignment values are the log of the boundary number For example An 8 byte boundary would translate to an Alignment value of log5 8 23 e 4 boundary would translate to an Alignment value of log5 4096 212 Alignment defaults to 1 byte if a value of 0 is passed SuballocUnit Input Size of smallest block of memory that can be suballocated Larger suballocated memory blocks are suballocated as multiples of this unit The unit size is rounded up to the next power of 2 Reserved Input Reserved parameter must be 0 Returns RC SUCCESS RC SUBALLOCATED MEM RC INVALID RESERVED PARM RC INV
124. Entry address on which user gets control on calling of the signal If this parameter is NULL the calling process does not get control through this signal It gets only a handle back in SigHandle to use in calling the signal OptionWord Input Describes how to receive a signal This parameter is valid only if the EntryPoint parameter is not NULL SIG CONTROL ALWAYS Calling process wants control any time the signal is called SIG CONTROL MATCH Calling process wants control only when the signal is called with a matching SigHanID SigHanID Input This parameter is valid only if OptionWord is SIG CONTROL MATCH The caller gets control only when the signal is called with a matching SigHanID SigHandle Output Signal handle returned to requesting process This handle is used to call the signal Reserved Input Reserved parameter must be 0 Returns RC SUCCESS RC DUP RES NAME RC INVALID RESERVED PARM RC INVALID MEM ACCESS RC NO MORE RES RC INVALID CALL RC INVALID NAME RC INVALID OPTION Chapter 3 Base Kernel Services 115 CreateSig Create a Signal 116 Remarks Processes that open a signal with a NULL EntryPoint are calling processes Processes that open a signal with a non NULL EntryPoint are receiving processes The EntryPoint for a receiving process should be a handler that accepts three parameters e SigHanID e A pointer to a parameter block e parameter block size It should also ret
125. Figure 6 66 Example Screen VPD Information for RISC System 6000 Chapter 6 System Unit Utilities 261 Examples of Interactive Messages 262 11 80960 Registers Q Q QQQ sf0 h mH Ho Hn og sf2 ip ac tc item for display gt 11 0x20003104 ro 0x2206B5D0 pfp 0x00000000 rl 0x2206B660 sp 0x00000000 r2 0x2200681C rip 0x220672DC r3 Ox1FFA2010 0x20003138 r4 0x00000000 0x220672D8 rb 0x0000001C 0x00000000 r6 0x00000001 0x00000000 r7 0x00000001 0x2206B3C0 r8 0x220672A0 0x00000101 r9 0x00000024 0x00000404 r10 0x00000020 0x00000030 r11 0x00000020 0x22068080 r12 0x00000000 0x00000012 r13 0x00000000 0x00000000 r14 0x00000000 0x2206B610 fp r15 0x00000000 0x00000FFF CIPND 0x00000000 IMSK 0x00000000 DMAC 0x2200681C 0xD87F88FF OxFFFF6EFC OxFOOIFF81 Figure 6 67 Example Screen 80960 Registers ARTIC960 Programmer s Reference System Unit APIs System unit application program interfaces APIs are provided to allow the developer to write programs that use the services of an ARTIC960 adapter These APIs support only C programs API Page Base API 264 Mailbox API 276 Chapter 7 System Unit APIs 263 Base Base API The following interface routines are available to the application in the base API Routine Page RICOpen 265 RICClose 266 RICRe
126. G Access RIC ULONG Reserved Input Process ID of process whose memory protection is to be queried Input Pointer to a block of memory Input Size of block to query Output Access rights to memory This can include the MEM DCACHE and MEM BIG ENDIAN options See the Remarks section under CreateMem Allocate Memory on page 64 for more information Input Reserved parameter must be 0 RC SUCCESS RC INVALID PROC RC INVALID ADDRESS ESSID RC INVALID MEM ACCESS RC NOT DD OR SS Remarks This service returns the access rights to the memory block for the given process This service is made available for device drivers and subsystems so that they can check memory access for their clients Chapter 3 Base Kernel Services 73 QueryFreeMem Query Free Memory QueryFreeMem Query Free Memory This service returns the total amount of free memory and the size of the largest unallocated block of memory Functional Prototype RIC_ULONG QueryFreeMem RIC_ULONG OptionWord ULONG Largest ULONG Total RIC ULONG Reserved Parameters OptionWord Input MEM TYPE PACKET Free packet memory MEM TYPE INSTR Free instruction memory Largest Output Size of largest block of free memory in bytes Total Output Total amount of free memory in bytes Reserved Input Reserved parameter must be 0 Returns RC SUCCESS RC INVALID RES
127. I REG NUM RegNum ULONG Value Parameters pcuD Input The PCI device identifier obtained by way of either the pciFindDevice or pciFindClassCode service RegNum Input The register number to be read normally 0 to 255 The register number must be evenly divisible by 4 Value Input The doubleword to be written Returns RC SUCCESS RC PCI NO BIOS RC PCI BAD REGISTER NUMBER Remarks None Chapter 5 Adapter Library Routines 193 pciWriteConfigDWord Write a Doubleword to PCI Configuration Space 194 ARTIC960 Programmer s Reference System Unit Utilities System unit utilities are a set of command line driven utilities used to initialize and examine the ARTIC960 adapter Although it is not shown in the syntax diagrams help is provided for all utilities by using the switch The utilities display a brief message containing the syntax diagram for the utility The utilities also display the help messages if no parameters or switches are entered or if they are entered incorrectly All numeric parameters and command line options are assumed to be decimal values unless otherwise noted To pass a hexadecimal value for any numeric parameter prefix the parameter with 0x or 0X For example 0x10 and 0X10 are equivalent to the decimal parameter of 16 The logical card numbers referred to by the utilities are assigned by the driver during installation The ARTIC960 utilities do not perform any
128. IC960 Programmer s Reference GetSuballoc Suballocate Memory GetSuballoc Suballocate Memory This service suballocates memory from previously allocated memory Functional Prototype RIC_ULONG GetSuballoc void Blockptr RIC_ULONG Size void Suballocptr RIC_ULONG Reserved Parameters Blockptr Input Pointer to beginning of suballocation pool On cards that support big endian memory regions the memory must have been created as little endian If a big endian pointer is given RC INVALID BASEPTR is returned Size Input Amount of memory in bytes to suballocate The size is rounded up to a multiple of the suballocation unit size set with InitSuballoc If the size is 0 RC INVALID SIZE is returned Suballocptr Output Pointer to suballocated memory Reserved Input Reserved parameter must be 0 Returns RC SUCCESS RC NO MORE MEM RC INVALID RESERVED PARM RC INVALID MEM ACCESS RC INVALID BASEPTR RC INVALID SIZE Remarks No more than 65535 64K 1 times the suballocation unit size in bytes can be suballocated with a single call to GetSuballoc This restriction lowers the memory overhead of the suballocation services Application writers should be aware that the kernel s suballocation control information is stored in the user s memory unlike all the other kernel services whose control information is in protected memory This decision was made to improve suba
129. IC_TIMEOUT Timeout RIC_ULONG Status RIC_ULONG Reserved Parameters EvnHandle Input Event handle returned by CreateEvent and OpenEvent services Mask Input Mask telling which semaphores to include in the event wait If bit n is set in the mask the nth semaphore in the semaphore handle array passed to CreateEvent is included in the event wait OptionWord Input EVENT WAIT ALL Indicates that the process is awakened only when all the semaphores are available EVENT WAIT ANY Indicates that the process is awakened when the first semaphore becomes available Timeout Input Optional timeout value for waits for events Wait indefinitely Return immediately if the semaphores are unavailable Any other value from 1 to 65535 Wait time in milliseconds The granularity of the timer is five milliseconds The timeout value is rounded up to the next multiple of five if it is not already a multiple of five Status Output Bit field that returns which semaphores that were part of the event wait were positive available Reserved Input Reserved parameter must be 0 Returns RC SUCCESS RC INVALID MEM ACCESS RC INVALID HANDLE RC INVALID CALL RC INVALID RESERVED PARM RC INVALID OPTION RC TIMEOUT RC INVALID TIMEOUT RC NEW SEM COUNT RC OWNER CLOSED SEM RC INVALID EVN MASK Chapter 3 Base Kernel Services 61 WaitEvent Wait an
130. INVALID RESERVED PARM RC NO BASE DEVICE DRIVER Remarks The TimelInfo is defined as follows struct TimeInfo RIC_ULONG Time RIC_SLONG TimeZone RIC LONG DayLight char TimeZoneStr 4 char DayLightStr 4 Is the time in seconds in GMT since 1970 TimeZone Is the difference in hours between the local time zone and GMT DayLight Is true if daylight savings time is to be applied TimeZoneStr Is a time zone character string for example EST and CST DayLightStr Is a daylight savings time zone for example EDT and PDT Chapter 3 Base Kernel Services 89 QuerySystemTime Get the Time of Day QuerySystemTime Get the Time of Day 90 This service gets the time of day Functional Prototype RIC ULONG QuerySystemTime struct TimeInfo Time RIC ULONG Reserved Parameters Time Output Pointer to a user s structure that contains time information see the Remarks section for this service Reserved Input Reserved parameter must be 0 Returns RC SUCCESS RC INVALID MEM ACCESS RC INVALID RESERVED PARM RC NO BASE DEVICE DRIVER RC TOD NOT ENABLE U Remarks Users typically use the standard C calls for getting and setting the time The underlying services call this kernel service ARTIC960 Programmer s Reference StartPerfTimer Start the Performance Timer StartPerfTimer Start the Per
131. Ini MBXInfo SCBInfo MCInfo RPInfo HxInfo Appendix A Structure Definition 293 RIC EXCEPT Structure 294 ARTIC960 Programmer s Reference Message File Driver Mailbox Process and Utility Messages The following messages are displayed by the ARTIC960 tools drivers and processes See Mailbox Process Messages and Return Codes on page 13 for a list of return codes for the OS 2 mailbox process Appendix B Message File 295 RICO001 RICO006 RIC0001 Unrecognized option xx Explanation The option xx is not a valid command line option This message is followed by help messages RIC0027 RIC0031 Action Correct the command line and reissue the command Source Application Loader Dump Status Configuration Reset OS 2 Driver and Mailbox Process RICO002 Invalid parameter Explanation The parameter xxxxxxxx is invalid Either a required parameter is missing or an optional parameter has been improperly specified Action Correct the parameter and reissue the command Source Application Loader Dump Status Configuration OS 2 driver and Mailbox Process RICO003 File yyyyyyyy not found Explanation File yyyyyyyy does not exist or is not in the specified directory Action Verify that the file exists and is in the proper directory Source Application Loader Dump Status Configuration and Mailbox Process RIC0004 Error accessing file
132. Input Process ID of the process that is to be stopped A value of 0 means that the calling process is stopping itself Reserved Input Reserved parameter must be 0 Returns RC_SUCCESS RC INVALID CALL RC INVALID RESERVED PARM RC PERMANENT PROCESS RC PROCESS NOT STARTED RC DEVICE DRIVER RC INVALID PROCESSID Remarks The kernel calls the exit routine of the process before stopping the process All the resources acquired by the process are released This process can be restarted at a later time When process is stopping another process the requesting process will not run until the stopping process has completely stopped including execution of its exit handler Locally only a device driver subsystem can stop a device driver subsystem The system unit can stop and unload a device driver subsystem through the U parameter of the Application Loader utility see Application Loader ricload Utility on page 196 for information on this utility The system unit can stop a device driver subsystem through a global mailbox command to a kernel mailbox from any unit see Chapter 4 Kernel Commands on page 163 for details on the mailbox commands Chapter 3 Base Kernel Services 37 UnloadProcess Unload a Process UnloadProcess Unload a Process 38 This service unloads a previously loaded process Functional Prototype RIC_ULONG UnloadProcess RIC PROCESSID ProcessID
133. LONG TotalMemSize Size in bytes RIC_ULONG Reservedl 9 RIC_ULONG MCBaseIOAddr Base I O address CARDNUM CardNum Logical card number RIC ULONG NumOfMemoryRegions RIC ADDRESS RANGE emoryRegions MAX MEM REGIONS RIC ULONG NumOfIO Regions RIC ADDRESS RANGE IO Regions MAX IO REGIONS unsigned char SlotNum Physical slot number unsigned char UnitID SCB unit ID RIC CONFIG ReservedO xf 2 Reserved contains information about the adapter card type It indicates the bus type the presence of data cache hardware and the interface chip type The following masks can be used RIC CARD TYPI RIC DCACHI Indicates the bus type Bus type values are RIC_MCA Micro Channel RIC_PCI PCI Peripheral Connect Interface Indicates the presence of data cache hardware Data cache hardware values are 0 Data cache hardware is not present 1 Data cache hardware is present ARTIC960 Programmer s Reference RIC_CONFIG Structure RIC_IF_CHIP Indicates the type of interface chip Interface chip values are RIC_MIAMI Miami on an ARTIC960 MCA or ARTIC960 PCI adapter RIC_MP2P Miami PCI to PCI on an ARTIC960Hx PCI adapter RIC_RP 1960Rx on an ARTIC960Rx PCI adapter RIC_RXD 1960Rd on an ARTIC960RxD PCI adapter RIC_NO_P2P Indicates that peer to peer activity is not supported Defined Macros The following macros can be used to determine card informatio
134. MAX REMOTE MAILBOX 16 Maximum number of remote mailboxes MAX PEER ADAPTERS 0 Maximum number of peer units not including this adapter or the system unit 4 ARTIC960 Programmer s Reference Parameter Table 1 2 Sheet 2 of 2 Kernel Parameters Description MAX_SYSTEM_MC_REQ 8 Maximum number of system bus read write requests from the system unit outstanding DEFAULT_STACK_SIZE 4096 Default process stack size TIME_SLICE_INTERVAL 10 Time slice interval disable 0 means disable Interval value is in milliseconds WATCHDOG_INTERVAL 2000 Watchdog interval disable 0 means disable Interval value is in milliseconds The watchdog timer is not supported on ARTIC960Rx PCI and ARTIC960Hx PCI cards It will be ignored TIME OF DAYZzYES NO Time of day clock enable PERFORMANCE TIMERZYES NO Performance timer enable If the performance timer is not enabled the StartPerfTimer StopPerfTimer and ReadPerfTimer services return RC PERF TIMER NOT ENABLED You can request the kernel to leave the time slice timer watchdog timer time of day timer or performance timer available for a user process See Timer Notes on page 5 for more information DATA CACHEZYES NO Data cache enable This parameter is ignored if data cache hardware is not present on the adapter or if MEMORY PROTECTION YES REG CACHE 7 Number of register sets that are cached Valid values depend
135. ONFIG Invalid parameter passed to kernel through configuration file 0x0001 1202 RC INVALID NUM RES The configuration parameters passed were such that the required number of resources exceeded the kernel s limit 0x0001 1301 RC MC DATA PARITY ERR A system bus data parity error was returned on a Micro Channel operation 0x0001 1302 RC MC CHCK ERR A channel check was returned on a system bus operation 0x0001 1303 RC MC CARD SEL FDBACK ERR A card selected feedback error was returned on a system bus 0x0001 1304 RC MC LOSS OF CHANNEL ERR A loss of channel error was returned on a system bus operation 0x0001 1305 RC MC LOCAL BUS PARITY ERR A local bus parity error was returned on a system bus operation 0x0001 1306 RC MC EXCEPTION ERR An exception error was returned on a system bus operation 0x0001 1307 RC MC TIMEOUT A timeout occurred on a system bus operation or waiting for DMA resources 0x0001 1308 RC MC INVALID COMBINATION An invalid combination error was returned on a system bus operation 0x0001 1309 RC MC CHAINING EX ERR A list chaining exception error was returned on a system bus operation 0x0001130A RC MC POSTSTAT EX ERR A posted status exception error was returned on a system bus operation 0x0001130B RC_UNABLE_TO_CONVERT_ADDRESS The system bus address does not correspond to a local card address 0x0001130C RC_MC_TARGET_ABORT A target abort error was returned on a system bus operation on the ARTIC960 PCI card 0x0001130D RC_M
136. OT FOUND RICO004 RC UTIL FILE ACCESS RIC0026 RC UTIL FILE FORMAT RICO304 RC UTIL WRNHELP GIVEN RICOS306 RC UTIL SUCCESS Trace buffer is empty RIC0307 None Format messages 22 25 RIC0323 RC_UTIL_SUCCESS Successful Format Trace operation ARTIC960 Programmer s Reference Format Trace Utility Format Trace Record Details The following figures depict the records displayed by the Format Trace utility The first record contains the trace control block information Each successive record contains information for the required service classes All displayed values are hexadecimal For examples see Format Trace Record Examples on page 222 Trace Control Block Record The following is the first record in the formatted trace A WrapAroundCount of OxFFFFFFFF indicates an infinite wrap count Service Classes Enabled fields indicate which service classes were enabled at the time the ricgettr was called S WrapAroundCount Oxnnnnnnnn CurWrapAroundCount Oxnnnnnnnn Service Classes Enabled nnn nnn nnn nnn nnn nnn nnn nnn nnn nnn Figure 6 9 Trace Control Block Chapter 6 System Unit Utilities 219 Format Trace Utility 220 Record Description Data in Bytes In this record the data is shown in bytes The valid kernel ServiceClass and ProcedureID fields are obtained from the service class file ricclass tre and the optional C service class configuration file Th
137. OTE RC INVALID SIZE RC SYSTEM ERROR RC NAME NOT FOUND Remarks If the memory name provided by the process is the same as that used on a previous CreateMbx or OpenMbx call this service gets access to the already created memory Otherwise the service allocates the memory requested by the process When memory is shared the MsgUnitSize and MsgUnitCount parameters must each be less than or equal to those passed when the memory was allocated Otherwise RC INVALID SIZE or RC INVALID COUNT error is returned depending on which parameter is not the same as the respective input parameter In AIX MBXHandle is valid only within the process that obtained it There is no thread support Chapter 7 System Unit APIs 281 GetMbxBuffer Get a Free Mailbox Buffer GetMbxBuffer Get a Free Mailbox Buffer This allocates a free mailbox buffer to the requesting process 282 Functional Prototype RIC_ULONG GetMbxBuffer RIC MBXHANDLE MbxHandle RIC_ULONG Size void RIC_SUPTR MsgPtr RIC_ULONG Reserved Parameters MbxHandle Input Handle of the mailbox from which the process wants to get a message buffer Size Input Message size in bytes The size is rounded up to a multiple of the message unit size set by CreateMbx or OpenMbx The size parameter must be in the range 0 Size 65503 MsgPtr Output Pointer to allocated mailbox buffer Reserved Input Reserved parameter must be 0 Returns RC
138. O_MORE_DEV No more device drivers subsystems can be created 0x00010A03 RC_OPEN_ENTRY_FAILURE The open entry routine failed for the subsystem or device driver 0x00010A04 RC_CLOSE_ENTRY_FAILURE The close entry routine failed for the subsystem or device driver 0x00010A05 RC_INVOKE_ENTRY_FAILURE The call entry routine failed for the subsystem or device driver 0x00010A06 RC_DD_RC_OUT_OF_RANGE A subsystem or device driver has returned a value out of the range specified for use by subsystems and device drivers The acceptable range is OXFFFF0000 through OXFFFFFFFF 0x00010B01 RC INVALID VECTOR The process is trying to allocate a vector greater than 255 0x00010B02 RC VECTOR NOT AVAILABLE The requested vector number is not available 0x00010B03 RC VECTOR NOT ALLOCATED The requester is trying to return or set a vector that was never allocated 0x00010B04 RC INVALID PIN The valid range of external interrupt pin numbers is from 0 to 7 0x00010C01 RC_HW_ALREADY_ALLOCATED The requested hardware name is already allocated 0x00010C02 RC_HW_NOT_ALLOCATED The requester is returning a hardware resource that was not previously allocated 0x00010D01 RC_DUP_ASYNC_EVENT A process can register an async handler for an event only once If a process wants to change the address of its async handler then it should de register the async handler before re registering it 0x00010D02 RC_NOT_REGISTERED A process is trying to deregister an asynchronous event for which it is n
139. PCI REG NUM RegNum RIC_USHORT Value Parameters pcuD Input The PCI device identifier obtained by way of either the pciFindDevice or pciFindClassCode service RegNum Input The register number to be read normally 0 to 255 The register number must be divisible by 2 Value Output The word read is returned in this parameter Returns RC_SUCCESS RC_PCI_NO_BIOS RC PCI BAD REGISTER NUMBER Remarks None Chapter 5 Adapter Library Routines 189 pciReadConfigDWord Read Doubleword from PCI Configuration Space pciReadConfigDWord Read a Doubleword from PCI Configuration Space This service reads one 32 bit doubleword from the device PCI configuration space Functional Prototype RIC ULONG pciReadConfigDWord PCI ID pciID PCI REG NUM RegNum RIC ULONG Value Parameters pcuD Input The PCI device identifier obtained by way of either the pciFindDevice or pciFindClassCode service RegNum Input The register number to be read normally 0 to 255 The register number must be evenly divisible by 4 Value Output The doubleword read is returned in this parameter Remarks None 190 ARTIC960 Programmer s Reference pciWriteConfigByte Write a Byte to PCI Configuration Space pciWriteConfigByte Write a Byte to PCI Configuration Space This service writes one byte to the device PCI configuration space Functional Prototype RIC_ULONG pciWriteConfigByte PCI_ID pciID PCI REG NUM RegNum u
140. PROCESS RC MC TIMEOUT AIX only RC NO MBX RECEIVER Remarks If MBX SEND FREE BUFFER is specified and the SendMbx service fails the buffer is not freed It must be explicitly freed by the sender using the FreeMbxBuffer service Chapter 7 System Unit APIs 285 ReceiveMbx Receive a Message ReceiveMbx Receive a Message 286 This reads or receives a message from a mailbox Functional Prototype RIC_ULONG ReceiveMbx RIC MBXHANDLE MbxHandle RIC ULONG OptionWord RIC TIMEOUT Timeout void RIC SUPTR MsgPtr RIC ULONG RIC SUPTR Size ULONG Reserved Parameters MbxHandle Input Handle of the mailbox from which the process wants to receive a message OptionWord Input Option word for specifying receive options The following constant can be used MBX RECEIVE READ MESSAGE Return the pointer to the message but do not remove it from the mailbox message queue MBX RECEIVE GET MESSAGE Return the pointer to the message and remove it from the mailbox message queue This is the default Timeout Input Optional timeout in milliseconds for waiting on a semaphore associated with this mailbox The process should not wait if no messages are available in the mailbox There is no timeout The process waits indefinitely for a message to arrive MsgPtr Output Pointer to the received message buffer
141. Programmer s Reference StartProcess Start a Process StartProcess Start a Process This command starts the process specified by the process ID Command Parameters CommandNum in the common header must be set to KERN_START_PROC Structures struct RIC StartProcessCmd RIC PROCESSID ProcessID RIC ULONG OptionWord SLONG TimeOut RIC ULONG Reserved where ProcessID Process identification OptionWord Bit field indicating whether the requester wants the kernel to wait for the process being started to perform a CompleteInit before the kernel returns a return code and thus completes the command WAIT FOR COMPLETEINIT The kernel waits for the starting process to issue the CompleteInit call NO WAIT FOR COMPLETEINIT The kernel does not wait TimeOut Time specified in seconds that the kernel waits for the process to perform the CompleteInit The actual time waited is a multiple of approximately 1 4 seconds A value of zero indicates that the requester does not want to wait There is no infinite timeout Reserved Reserved field must be 0 Response Parameters ReturnCode values in RIC KernResponse are RC SUCCESS RC INVALID RESERVED PARM RC INVALID PROCESSID RC PROCESS ALREADY STARTED RC PROCESS STOPPED RC TIMEOUT Error code used by a process on CompleteInit There is no variant response part for this command Remar
142. R O W O or none e Valid strings for the Sharable field are yes or no e The entries in the Access list fields show all processes that have access to the resource See Figure 6 57 on page 258 for an example C N Enter adapter number gt Enter resource name or handle gt Resource type memory Name SSSSSSSSSSSSSSSS Address nnnnnnnn Size nnnnnnnn AIB DMA Access sss Mchl Access SSS Sharable SSS Access list Proc No Process Name Handle Access nnnnnnnn SSSSSSSSSSSSSSSS nnnnnnnn SSS M E Figure 6 32 Memory Detail Display Chapter 6 System Unit Utilities 243 Status Interactive Messages 244 5 Queue Resource Details Submenu The following screen shows the prompts and items displayed when a queue is selected from the Resource details submenu e The entries in the Access list fields show all processes that have access to the resource The Semaphore field is the handle of the semaphore associated with the queue If the queue is empty the string lt empty gt is displayed on the Elements line Otherwise the first 16 bytes of each queue element are displayed in the standard memory display format See Figure 6 58 on page 259 for an example S Enter adapter number gt Enter resource name or handle gt Resource type queue Name SSSSSSSSSSSSSSSS Access list Proc No Process Name Semaphore nnnnnnnn SSSSSSSSSSSSSSSS nnnnnnnn Elements SSSSSSS aaaaaaaa hh hh hh hh
143. RD_NUMBER This value indicates that the destination unit is the system unit and that the destination address specifies a physical system bus address for the system unit MC_ADPT_ADDR_CARD_NUMBER This value indicates that the destination unit is not an ARTIC960 adapter and that the destination address specifies a physical system bus address for that adapter An ARTIC960 address cannot be expressed as a physical system bus address SourceAddptr Input The address of the source buffer on the source unit The address format is determined by the source unit field DestAddptr Input The address of the destination buffer on the destination unit The address format is determined by the destination unit field Size Input The number of bytes of data to be moved The maximum value is 1M 1 for the MCA adapter The maximum value is 16M 1 for PCI adapters 0 is not valid ChainPtr Input The pointer to the next Move structure If this is the last block in the chain this field is NULL 178 ARTIC960 Programmer s Reference MoveMCData Move System Bus Data Returns RC_SUCCESS RC_MC_LOSS_OF_CHANNEL_ERR RC_INVALID ADDRESS RC C LOCAL BUS PARITY ERR RC INVALID COMBINATION RC MC EXCEPTION ERR RC INVALID SIZE RC MC TIMEOUT RC INVALID OPTION RC MC INVALID COMBINATION RC INVALID CARD NUMBER RC MC CHAINING EX ERR RC INV
144. READY REG 0x80011402 RC MOVE ASYNC HANDLER NOT REG 0x8001 1401 RC MSG BUFFER NOT FREED 0x00010902 RC NAME NOT FOUND 0x00010103 RC NEW SEM COUNT 0x00010401 RC NO ADAPTER RESPONSE 0x00010003 RC NO BASE DEVICE DRIVER 0x00010701 RC NO ELEMENTS 0x0001000B RC NO FLOAT SUPPORT 0x00010208 RC NO MBX BUFFER 0x00010907 RC NO MBX PROCESS 0x00010909 NO MBX RECEIVER 0x00010901 Appendix C Return Error and Exit Codes 313 Return Codes Listed Alphabetically Return Code VALUE RC_NO_MORE_DEV 0x00010A02 RC_NO_MORE_ENTITIES 0x00010013 RC_NO_MORE_EVNS 0x00010502 RC_NO_MORE_HOOKS 0x00010F04 RC NO MORE MBX 0x00010904 RC NO MORE MEM 0x00010306 RC NO MORE PROC 0x00010207 RC NO MORE QUEUES 0x00010803 RC NO MORE REM MBX 0x0001090D RC NO MORE RES 0x0001001F RC NO MORE RES ON REMOTE 0x0001090A RC NO MORE SEM 0x00010404 RC NO MORE SIGS 0x0001 0602 RC NO MORE TIMERS 0x00010704 RC NO BUFFER 0x0001090B RC NO RES ACCESS 0x00010102 RC NO SUCH SIG ID 0x00010601 RC NOT DD OR SS 0x00010A01 RC_NOT_REGISTERED 0x00010D02 RC_OPEN_ENTRY_FAILURE 0x00010A03 RC_OWNER_CLOSED_SEM 0x00010406 RC PCI BAD REGISTER NUMBER 0x0001 1403 RC PCI DEVICE NOT FOUND 0x0001 1404 RC PCI INVALID COMMAND 0x0001 1402 RC PCI NO BIOS 0x0001 1401 RC PERF TIMER NOT ENABLED 0x00010707 RC PERMANENT PROCESS 0x0001020
145. RTIC960Hx PCI adapter An invalid option causes a value of NULL to be returned Returns Pointer to the allocated memory A NULL pointer means that no memory is available or that an invalid size or option was specified Remarks This service can be called from an interrupt handler The C library malloc function is mapped into this service using the default option ARTIC960 Programmer s Reference FreeMem Free Memory FreeMem Free Memory This service returns a block of memory that was allocated using the service MallocMem to the dynamic memory pool Functional Prototype RIC_ULONG FreeMem void Blockptr Parameters Blockptr Input Pointer to the memory block to be freed Returns RC_SUCCESS RC_INVALID_BASEPTR Remarks This service can be called from an interrupt handler The C library free function is mapped into this service Chapter 3 Base Kernel Services 81 CollectMem Collect Memory CollectMem Collect Memory 82 This service returns pages of memory that are in dynamic memory pools and are not being used The pages are returned to the memory page pool It also provides information about the amount of memory available in dynamic memory pools after collection is done Functional Prototype ULONG CollectMem ULONG OptionWord RIC ULONG FreeUnits RIC ULONG FreedPages Parameters OptionWord Input A bit field specifying options for the CollectMe
146. RadiSys ARTIC960 Programmer s Reference RadiSys Corporation 5445 NE Dawson Creek Drive Hillsboro OR 97124 503 615 1100 FAX 503 615 1150 www radisys com November 2000 References in this publication to RadiSys Corporation products programs or services do not imply that RadiSys intends to make these available in all countries in which RadiSys operates Any reference to a RadiSys licensed program or other RadiSys product in this publication is not intended to state or imply that only RadiSys Corporation s program or other product can be used Any functionally equivalent product program or service that does not infringe on any of RadiSys Corporation s intellectual property rights or other legally protectible rights can be used instead of the RadiSys product program or service Evaluation and verification of operation in conjunction with other products programs or services except those expressly designated by RadiSys are the user s responsibility RadiSys may have patents or pending patent applications covering subject matter in this document The furnishing of this document does not give you any license to these patents You can send license inquires in writing to RadiSys Corporation 5445 NE Dawson Creek Drive Hillsboro OR 97124 EPC iRMX INtime Inside Advantage and RadiSys are registered trademarks of RadiSys Corporation Spirit DAI ASM Brahma and SAIB are trademarks of RadiSys Corporation
147. Read Current Time of the Performance Timer This service reads the performance timer count without stopping it Functional Prototype RIC ULONG ReadPerfTimer RIC ULONG TimeCount RIC ULONG Reserved Parameters TimeCount Output Current count of performance timer in microseconds Reserved Input Reserved parameter must be 0 Returns RC SUCCESS RC TIMER IS INACTIVE RC INVALID MEM ACCESS RC INVALID RESERVED PAR RC TIMER OVERFLOWED RC PERF TIMER NOT ENABLED Remarks None Chapter 3 Base Kernel Services 93 Process Communication Services Process Communication Services Using the following services process communication can be accomplished through queues mailboxes and signals Service Page CreateQueue 95 OpenQueue 96 CloseQueue 97 PutQueue 98 GetQueue 100 SearchQueue 102 CreateMbx 104 OpenMbx 106 GetMbxBuffer 108 FreeMbxBuffer 109 SendMbx 110 ReceiveMbx 112 CloseMbx 114 CreateSig 115 OpenSig 117 CloseSig 119 InvokeSig 120 Refer to the ARTIC960 Programmer s Guide for additional information 94 ARTIC960 Programmer s Reference CreateQueue Create a Queue CreateQueue Create a Queue This service creates a queue and gives access to the requesting process Functional Prototype RIC ULONG CreateQueue char QueueName RIC QUEHANDLE QueueHandle RIC SEMHANDLE SemHandle
148. RegisterAsyncHandler Register an Async Handler Ad Field The Ad field in AsyncEvent has the following definition struct RIC_AdapterEvent void CodeAdadr void MemAddr struct RIC PCIError PCIError where CodeAddr Code address after and near the faulting instruction MemAddr Memory address that the code was attempting to access If the value is OxFFFFFFFF the address is unknown PClError Structure of information related to the PCI bus error The PCIError field in AsyncEvent has the following definition For a definition of RPJnfo and HxInfo refer to the ARTIC960 Programmer s Guide This information should be checked to determine the specific cause of the interrupt struct RIC_PCIError union struct RIC RPErrInfo RPInfo struct RIC HxErrInfo HxInfo TermErrInfo RIC ULONG TermErrCode RIC ULONG ReturnCode where TermErrInfo A union containing the exception data that will be posted after all asynchronous handlers have been called VW ARTIC960RxD information will be filled in the RPInfo field TermErrCode The exception code to be posted either TERMERR PLX INTERRUPT or TERMERR NMI INTERRUPT ReturnCode A field that the asynchronous handler may set to 1 to force the kernel not to generate a terminal error Otherwise handlers should not modify this field Chapter 3 Base Kernel Services 143 RegisterAsyncHandler Register an Async Handler
149. Reserved Input Reserved parameter must be 0 Returns RC SUCCESS RC INVALID HANDLE RC INVALID RESERVED PARM RC NO MBX PROCESS RC NO MORE RES RC PIPES NOT CONFIGUR RC SYSTE ERROR RC UNABLE TO ACCESS UNIT e Ifthe close is issued by a process while other processes still have access to the mailbox the service simply removes access rights for the calling process If the calling process is the only process using the memory pool associated with the mailbox this memory pool is released by the mailbox process e In OS 2 if the mailbox to be closed was created by the calling process the semaphore associated with the mailbox is released by the mailbox process In AIX the semaphore associated with the mailbox must be removed by the calling process after it calls CloseMbx 288 ARTIC960 Programmer s Reference Structure Definition This appendix contains structure definitions for RIC CONFIG RIC VERDATA and RIC EXCEPT Appendix A Structure Definition 289 RIC_CONFIG Structure RIC_CONFIG Structure The following is the structure definition for RIC_CONF IG configuration information for the ARTIC960 adapter 290 typedef struct RIC_Config RIC_ULONG Reserved0 RIC ULONG AIBID AIB ID RIC ULONG FullWindowLoc Physical address RIC ULONG FullWindowSize Size in bytes RIC_U
150. S indicates that an exception has occurred and the exception data is in the ExceptData field e RC DUMP ACTIVE and RC RESET ACTIVE are returned if a dump or reset is active when the RICGetException call is made e RC BUFFER TOO SMALL indicates that an exception has occurred but that the length of the buffer provided specified in ExceptLen is insufficient to return all of the exception information partial data is returned e RC INVALID MEM ACCESS cannot be received in OS 2 If the driver detects an access violation OS 2 terminates the process with a trap unless the application has an exception handler registered with OS 2 ARTIC960 Programmer s Reference RICGetException Get Exception Status e RC NO ADAPTER RESPONSE is returned if the adapter does not complete POST and cannot reliably report the failing exception condition e RC TIMEOUT is immediately returned if the caller specifies a timeout of 0 and no exception condition is present In AIX ExceptData is word swapped for the caller because all exception data fields are defined as word length For more details on the information returned by this structure see EXCEPT Structure on page 293 Chapter 7 System Unit APIs 275 Mailbox API Mailbox The programming interface for the mailbox routines is the same as the ARTIC960 kernel mailbox API except that there may be slight differences in the i
151. SUCCESS RC INVALID HANDLE RC INVALID RESERVED PARM RC INVALID SIZE RC NO MBX BUFFER RC NO MBX PROCESS RC NO MBX RECEIVER Remarks No more than 65503 bytes can be allocated with a single call to GetMbxBuffer ARTIC960 Programmer s Reference FreeMbxBuffer Free Mailbox Buffer FreeMbxBuffer Free Mailbox Buffer This returns a previously allocated mailbox buffer Functional Prototype RIC_ULONG FreeMbxBuffer MBXHANDLE MbxHandle void RIC SUPTR MsgPtr ULONG Reserved Parameters MbxHandle Input Handle of the mailbox where the process wants to free a message buffer MsgPtr Input Pointer to allocated mailbox buffer Reserved Input Reserved parameter must be 0 Returns RC SUCCESS RC INVALID HANDLE RC INVALID MBX BUFFER ADDR RC INVALID RESERVED PARM RC NO MBX PROCESS RC MBX BUFFER IN QUEUE Remarks None Chapter 7 System Unit APIs 283 SendMbx Send a Message SendMbx Send a Message 284 This puts a message into a mailbox Functional Prototype RIC_ULONG Parameters MbxHandle MsgPtr Size OptionWord Reserved SendMbx RIC MBXHANDLE MbxHandle void RIC SUPTR MsgPtr RIC ULONG Size RIC ULONG OptionWord ULONG Reserved Input Handle of the mailbox to which the process wants to send the message Input Pointer to the message buffer Input Size of th
152. Source Configuration Dump Application Loader 306 ARTIC960 Programmer s Reference RIC0081 RICO100 RICO299 RIC0081 Calibrating ARTIC 960 RP Timers using card nn Explanation Informational message notifying the user that the device driver is calculating the local bus speed constant using the ARTIC 960 RP card displayed in the message Action None Source OS 2 Driver RICO082 Unsupported option xxxxxxxx for this hardware Explanation This option xxxxxxxx is not supported with the current hardware Action Reissue the command without option xxxxxxxx Source Dump RIC0083 Dump process not followed correctly Explanation One must first initiate a regular dump of the card before a dump of the PMC regions can be dumped Action Reissue the command dumping the card first and then the PMC regions Source Dump RICO084 Dump of PMC on card xxxxxxxx in progress Explanation The PMC dump of card is currently in progress Action Wait for a message indicating that the PMC dump has completed Source Dump RICO085 Dump of PMC on card xxxxxxxx complete Explanation The PMC dump of card xxxxxxxx is complete Action Use a binary editor to analyze the raw dump file Reset the card to continue using it Source Dump RICO086 The format of the configuration file is incorrect Explanation The configuration specified has too many entries or the syntax of the entries is incorrect Action Reduce the
153. The smallest message size that can be allocated All messages are allocated in units of this size MsgUnitCount Input The maximum number of message units that can be allocated from this mailbox OptionWord Input Bit field to describe the options to be used to create the mailbox The following constants should be ORed together to build the appropriate set of options Type of mailbox to create The caller can create either a mailbox that accepts messages from other units using MBX CREATE GLOBAL or one that does not accept these messages using MBX CREATE LOCAL Because the system unit supports only remote mailboxes the MBX CREATE LOCAL option is ignored Mailbox buffer pinning option ignored in AIX The caller can have the memory associated with mailbox buffers permanently pinned using MBX PIN MEMORY If this option is not selected memory is pinned only for as long as absolutely necessary This option applies only when memory is allocated by this CreateMbx call MbxHandle Output The mailbox handle returned to the requesting process This handle is passed to all other mailbox services when referring to this mailbox Chapter 7 System Unit APIs 277 CreateMbx Create a Mailbox 278 SemHandle The semaphore handle associated with the mailbox This handle is passed to all other semaphore services when referring to this mailbox associated semaphore This semaphore is
154. VALID OPTION RC INVALID SEM COUNT 1 d Remarks This service creates a new semaphore and assigns to it the specified name The usual initial count for counting semaphores is 0 the initial count for mutual exclusion semaphores is 1 To use another starting semaphore count see SetSemCount Set a Semaphore Count on page 57 Other processes can get access to the same semaphore using the OpenSem service see OpenSem Open a Semaphore on page 52 If a mutex semaphore is created with a count of 0 the creator owns it also Otherwise the first requester owns it Chapter 3 Base Kernel Services 51 OpenSem Open a Semaphore OpenSem Open a Semaphore This service opens a semaphore previously created by another process Functional Prototype RIC_ULONG OpenSem char SemName RIC SEMHANDLE SemHandle ULONG Reserved Parameters SemName Input The semaphore name used to create the semaphore SemHandle Output Semaphore handle returned to requesting process This handle is passed to all other semaphore services when referring to this semaphore Reserved Input Reserved parameter must be 0 Returns RC SUCCESS RC NAME NOT FOUND RC NO MORE RES RC INVALID RESERVE RC INVALID NAME RC INVALID MEM ACCESS RC INVALID CALL i D J lt Remarks This service gets access to a semaphore already created by an
155. Vector Return an Interrupt AllocHW Allocate a Hardware Device ReturnHW Return a Hardware Device essere QueryHW Query Status of Hardware Device sess enne n rennes Asynchronous Event Notification Services RegisterAsyncHandler Register an Async Handler seeeseeeeeeeneeeeen nennen DeregisterAsyncHandler Deregister an Async Handler eene Hook Services eeeeeee RegisterHook Register an Entry Point for a Hook DeregisterHook Deregister an Entry Point for a enne Kernel Trace Services InitTrace Initialize a Trace Buffer eeeeeesseesseeeeeeeeeese eene nennen nne nene EnableTrace Enable Tracing of Service Classes essere DisableTrace Disable Tracing of Service Classes ccccccceesssssssssssscecececsccecceceecesessesesauauseseseueeeeees LogTrace Log Trace Information onenean innate e a o o aieiai Kernel Trace Information Chapter 4 Kernel Commands Common Headers for Commands and Responses eese RegisterResponseMbx Register a Command Response Mailbox esee DeRegisterResponseMbx Dereg
156. able 2 1 Sheet 1 of 4 ARTIC960 Kernel Services Function Interrupt Signal Async Process Critical Handler Handler Handler Exit Section Process Management Services Completelnit No No No No No QueryProcessStatus Yes Yes Yes Yes Yes QueryCardInfo Yes Yes Yes Yes Yes QueryConfigParams Yes Yes Yes Yes Yes CreateProcess No No No Yes Yes StartProcess No No No Yes3 Yes StopProcess No No No Yes3 Yes UnloadProcess No No No Yes3 Yes SuspendProcess Yes Yes6 Yes Yes Yes ResumeProcess Yes Yes Yes Yes Yes SetExitRoutine No No No No Yes SetPriority Yes Yes Yes Yes Yes QueryPriority Yes Yes Yes Yes Yes QueryProcessInExec Yes Yes Yes Yes Yes SetProcessData No Yes Yes Yes Yes GetProcessData Yes Yes Yes Yes Yes EnterCritSec Yes5 Yes Yes Yes Yes ExitCritSec Yes5 Yes Yes Yes Yes Dispatch No No No Yes Yes Chapter 2 ARTIC960 Kernel Services 15 Table 2 1 Sheet 2 of 4 ARTIC960 Kernel Services Funetion Handie _ Edt Seaton Process Synchronization Services CreateSem No No No Yes Yes OpenSem No No No Yes Yes CloseSem No No No Yes Yes ReleaseSem Yes Yes Yes Yes Yes RequestSem No No No Yes Yes QuerySemCount Yes Yes Yes Yes Yes SetSemCount Yes Yes Yes Yes Yes CreateEvent No No No Yes Yes OpenEvent No No No Yes Yes CloseEvent No No No Yes Yes
157. ad 267 RICWrite 269 RICReset 271 RICGetConfig 272 RICGetVersion 273 RICGetException 274 API routines block until they are completed unless otherwise noted Refer to the ARTIC960 Programmer s Guide for additional information on system unit APIs 264 ARTIC960 Programmer s Reference RICOpen Open an ARTIC960 Adapter RICOpen Open an ARTIC960 Adapter This routine is used to obtain a handle for use in accessing the ARTIC960 adapter Functional Prototype RIC_ULONG RICOpen RIC_CARDNUM CardNum RIC_HANDLE Handle RIC_ULONG Reserved Parameters CardNum Input The logical card number to open for access Handle Output Adapter device handle returned to the calling process This handle is passed to all other services when referring to this adapter Reserved Input Reserved parameter must be 0 Returns RC SUCCESS RC INVALID CARD NUMBER RC INVALID RESERVED PARM RC SU OPEN FAILED Remarks e An application must obtain a handle for each card it accesses directly through the base API services e logical card numbers are assigned by the driver during installation Refer to the ARTIC960 Programmer s Guide for information on the Micro Channel and PCI buses In AIX The configuration manager scans the physical slots from low to high and defines the consecutive logical card numbers starting at 0 for each supported card found If an ARTIC960 adapter is added t
158. ader ricload Utility Example Load a Process and Pass the Contents of a File This example loads the process sub dir proc FILEOO1 rel to logical card 0 The process is not started The contents of the file parms txt are passed as parameters argv ricload 0x0 sub dir proc FILEOO1 rel f parms txt L The following shows the contents of the file parms txt and the parameters passed to the process in argv Contents of File parms txt this is the FIRST line of parameters this is the second line parameter 3 Parameters argv argv 0 proc FILEOO1 rel argv 1 this is the FIRST line of parameters argv 2 this is the second line argv 3 parameter 3 Example Load and Start a Process Using a Configuration File The following shows the contents of the file setup cfg and the resulting action The entire load operation is done quietly no messages displayed ricload C setup cfg Q Contents of File setup cfg Setup configuration file 0 ric kern rel F ric kern cfg 0 ric base rel 0 ric mcio rel F ric mcio cfg 0 ric scb rel F ric scb cfg Resulting Action 1 The file ric_kern rel is loaded to logical card 0 with ric_kern cfg passed as its parameters Then the process is started 2 The file ric_base rel is loaded to logical card 0 and started 3 The file ric_mcio rel is loaded to logical card 0 with ric_mcio cfg passed as its parameters Then the process
159. ailed ARTIC960 Programmer s Reference InvokeDev Call a Subsystem or Device Driver InvokeDev Call a Subsystem or Device Driver This service calls the subsystem or device driver on its strategy entry point Functional Prototype RIC ULONG InvokeDev RIC DEVHANDLE DDHandle void DDParams RIC ULONG Size ULONG Reserved Parameters DDHandle Input Handle of subsystem or device driver to call DDParams Input Address of subsystem or device driver defined parameters Size Input Size of subsystem or device driver defined parameters The size of the buffer pointed to by DDParams Reserved Input Reserved parameter must be 0 Returns RC SUCCESS RC CALL TERMINATED RC INVALID RESERVED PARM RC INVALID HANDLE RC INVALID MEM ACCESS RC INVOKE ENTRY FAILUR RC DD RC OUT OF RANGE E Remarks The kernel gives control to subsystem or device driver at the InvokeEntry entry point with the parameters specified in the nvokeEntry Prototype on page 124 with driver memo returned by the subsystem or device driver on call of OpenEntry by kernel as parameters If the device driver or subsystem has specified memory protection be disabled it is disabled when its call handler gets control If the device driver or subsystem requested that memory protection be enabled the device driver or subsystem will have access to the call parameter block as wel
160. an be pinned depends on the size of the instruction cache which varies by processor type e The Cx processor is used on ARTIC960 and ARTIC960 PCI cards On Cx or Rx processor the kernel pins 2 KB of the 4 KB instruction cache On a Cx or Rx processor only one type of critical code can be pinned e Onan Hx processor the kernel pins up to 8 KB of the 16 KB instruction cache On an Hx processor the cache is big enough to allow both process intensive and interrupt intensive critical code to be pinned The type of critical code to be pinned is controlled by the PIN KERN PROC CODE and PIN KERN INT CODE kernel configuration parameters See page 5 for information about these parameters ARTIC960 Programmer s Reference Internal Data RAM The following provide for use of 1960 internal data RAM e ARTIC960 Support for OS 2 Version 1 2 1 e ARTIC960 Support for AIX Version 1 2 e ARTIC960 Support for Windows NT Version 1 0 Internal data RAM is used for key kernel data and is also available for application use The size of the internal data RAM is 1 KB for a Cx Rx processor and 2 KB for an Hx processor Internal data RAM is used in the following manner Top 0x400 on Cx Rx 0x800 on Hx Register Cache Growth Available for Applications 0x200 Reserved for Kernel Usage 0x040 Vectors 0x000 The value of n is determined by the number of cached register sets This is controlled by the REG_CACHE kerne
161. andle 0x0009 PRC PamsProcess 0x0102055F M J Figure 6 55 Example Screen Event Detail Chapter 6 System Unit Utilities 257 Examples of Interactive Messages 258 Enter resource name or handle gt 0x01030557 Resource type mailbox Name MBX IncomingDataMbx Type local Receiver PRC_LineProcessor Semaphore 0x01070527 Access list Proc No Process Name Handle Memory Name 0x0011 PRC LineProcessor 0 01030557 MBM LineBufferData 0x0012 PRC LineFeeder 0x0103055B MBM_LineBufferData Messages 20040000 30 31 32 33 34 00 41 42 43 00 00 00 00 00 00 00 20042050 30 30 30 00 00 00 61 62 00 00 00 00 00 00 00 00 20040170 31 31 30 00 00 00 61 62 43 00 00 00 00 00 00 00 01234 ABC 000 ab 110 abC Figure 6 56 Example Screen Mailbox Detail Enter resource name or handle gt 0104055E Resource type memory Name MEM DATA BUFFERS Address 0x20042000 Size 0x2000 AIB DMA Access R W Mchl Access R W Sharable yes Access list Proc No Process Name Handle Access 0x001A PRC_ProcMemHog 0x0104055E R W 0 001 PRC_ProcessMonitor 0x01040517 R O N Figure 6 57 Example Screen Memory Detail ARTIC960 Programmer s Reference Examples of Interactive Messages S Enter resource name or handle gt 01060572 Resource type queue Name QUE QUEUE A Access list Proc No Process Name Handle Semaphore 0x0011 PRC DonsProcess 0x01060572 0x01070571 0x0012 PRC StevesPro
162. apter 3 Base Kernel Services 83 CreateSwTimer Allocate a Software Timer CreateSwTimer Allocate a Software Timer 84 This service creates a software timer and gives access to the requesting process Functional Prototype RIC_ULONG CreateSwTimer char TimerName RIC_TMRHANDLE TimerHandle RIC_ULONG Reserved Parameters TimerName Input A name to assign to the timer This parameter also can be NULL The kernel subsystems allocate all resources with the first four characters as RIC_ for the resource name User timer names should not start with this prefix TimerHandle Input Timer handle returned to requesting process This handle is passed to all other timer services when this timer is referenced Reserved Input Reserved parameter must be 0 Returns RC_SUCCESS RC_INVALID_RESERVED_PARM A Q s pa H z 1 ze Q ur 2 lt E P Z p Eri RC INVALID MEM ACCESS RC INVALID CALL Remarks This service creates a new software timer and assigns it the specified name Because software timers cannot be shared there is not an equivalent open service The granularity of the software timer is five milliseconds The TimeCount value is rounded up to the next multiple of five if it is not already a multiple of five ARTIC960 Programmer s Reference CloseSwTimer Return a Software Timer CloseSwTimer Return
163. ary 73 card configuration information getting 28 change adapter attributes using SMIT memory protection 70 71 process priority 42 close semaphore 53 CloseDev Close a Subsystem or Device Driver 26 CloseEvent Release Access to an Event Word 60 CloseMbx Close a Mailbox 4 288 CloseMem Remove Addressability to Memory 66 CloseQueue Close a Queue 97 CloseSem Close a Semaphore 53 CloseSig Close a Signal 779 CloseSwTimer Return a Software Timer 85 collect memory 82 CollectMem Collect Memory 82 commands kernel common header 64 DeRegisterResponseMbx 67 overview 763 QueryProcessStatus 768 RegisterResponseMbx 66 StartProcess 71 StopProcess 70 UnloadProcess 69 common header kernel commands 64 165 CompleteInit Mark Process as Completely Initialized 23 compress dump data 202 CONFIG SYS 7 configuration ARTIC960 Support for AIX 0 ARTIC960 Support for OS 2 7 ARTIC960 Support for Windows NT 4 device driver subsystem 6 driver PCI bus 2 332 file entry format 208 for adapter SCB 271 get hardware data 272 kernel kernel subsystem 4 subsystems 6 system bus I O subsystem 6 utility 207 constants defined 65 control information kernel 77 conventions notational xiv ConvertCardToMC Convert Card Address to System Bus Address 782 ConvertMCToCard Convert System Bus Address to Card Address 787 corruption data structure 77 count set semaphore 57 334 ARTIC960 Programmer s Reference counting
164. as too small Action Increase the pipe size to the minimum size Source Configuration RICO044 Process failed to initialize Explanation The process was loaded using the W option of the Application Loader and it failed to issue the kernel service Completelnit function call in the specified time period Action Correct the initialization error in the process Source Application Loader RIC0045 Process failed to initialize correctly Error xxxxxxxx Explanation The process was loaded using the W option of the Application Loader and it passed a non zero error code on the kernel service Completelnit function call contains the error code Action Correct the initialization error in the process Source Application Loader RIC0046 Cards xx and yy are already configured Explanation The SCB pipes between units are already configured Action Accept the configuration as defined or reset the adapter and reconfigure Source Configuration RIC0047 Configuration failed between xx and yy Explanation The SCB pipe between units xx and yy is already configured Action Verify the unit is not out of memory if not contact support personnel Source Configuration 302 ARTIC960 Programmer s Reference RIC0048 RICO053 RIC0048 Correct syntax is gt Tr RICMBX32 drive path C config_filename L path Explanation Mailbox process syntax help message Action Select the proper parameters and call
165. ata into the buffer and returns an error POSTStatus Output A zero in this field indicates power on self test POST code for this device completed successfully A non zero value is device specific but indicates that some form of error occurred during POST DeviceDataPtr Output Pointer to a buffer to which the kernel copies device dependent data see Device Dependent Data on page 135 for more information Reserved Input Reserved parameter must be 0 Returns RC_SUCCESS RC_BUFFER_TOO_SMALL RC INVALID RESERVED PARM RC INVALID NAME RC NO MORE RES RC NOT DD OR SS RC HW ALREADY ALLOCATED RC INVALID CALL RC NAME NOT FOUND RC INVALID MEM ACCESS Remarks The kernel allocates the requested hardware device to the calling process if available For device names refer to the documents for the applicable daughter card For example for the 4 Port Multi Interface Application Interface Board see the related chapter in the ARTIC960 Co Processor Platforms Hardware Technical Reference ARTIC960 Programmer s Reference AllocHW Allocate a Hardware Device Device Dependent Data When the adapter is powered on or reset POST code on the adapter or daughter card updates the Resource Descriptor Table RDT with device information The kernel returns this device information on this call The following is the structure of the Resource Descriptor Table struct RIC_RDTEntry
166. ate and the termination code is software See Figure 6 49 on page 255 for an example Enter adapter number gt B Enter process name or ID gt ame SSSSSSSSSSSSSSSS ID nnnnnnnn Priority nnnnnnnn Entry point nnnnnnnn Stack pointer nnnnnnnn Param pointer nnnnnnnn State SSSSSSSSSSS Version nnnnnnnn Type SSSSSSSSSSS Termination Code software Requester Id nnnnnnnn Source Of Req SSSSSSSSSSSSSSSS Error Code nnnnnnnn M P Figure 6 23 Process Details Display Process Terminated by Software Event The valid values for Source Of Req are shown in Table 6 10 Table 6 10 Source of Request Source of Request Value Meaning Local Request came from a process on the local adapter Remote Request came through a kernel mailbox command from either the local adapter or a peer unit System Unit Command Request came from the system unit through a command probably issued using ricload with the U parameter ARTIC960 Programmer s Reference Status Interactive Messages Process Terminated by Processor Event The following screen shows the prompts and items displayed when the Process Details option is chosen the process is in a stopped or expired state and the termination code is processor See Figure 6 50 on page 255 for an example va ame ID Priority Entry point Stack pointer Param pointer State Version Type Termination Code Fault Type SubType Code Addre
167. ated If messages are being sent to other units the kernel ensures that system bus access has been enabled on the mailbox pool Mailbox memory areas are allocated from packet memory If there is not enough packet memory to allocate the buffer the service returns a RC NO MORE MEM error Chapter 3 Base Kernel Services 107 GetMbxBuffer Get a Free Mailbox Buffer GetMbxBuffer Get a Free Mailbox Buffer This service allocates a free mailbox buffer to the requesting process Functional Prototype RIC_ULONG GetMbxBuffer RIC_MBXHANDLE MbxHandle RIC_ULONG Size void MsgPtr RIC ULONG Reserved Parameters MbxHandle Input Handle of mailbox from which the process wants to get a message buffer Size Input Message size specified in bytes The size is rounded up to a multiple of the message unit size set by CreateMbx or OpenMbx A value of 0 is invalid The maximum size allowed with a single call is 65535 times the size of the message unit MsgPtr Output Pointer to allocated mailbox buffer Reserved Input Reserved parameter must be 0 Returns RC SUCCESS RC INVALID RESERVED PARM RC INVALID HANDLE RC NO MBX BUFFER RC NO MBX RECEIVER RC INVALID SIZE RC INVALID MEM ACCESS Remarks No more than 65535 times the message size in bytes can be allocated with a single call to GetMbxBuffer 108 ARTIC960 Programmer s Reference FreeMbxBuffer F
168. block of memory The calling process must have created or opened the memory that contains this block Size Input Size of block of memory in bytes Access Input New access rights to memory The MEM_DCACHE and MEM_BIG_ENDIAN options are ignored by this service See the Remarks section under CreateMem Allocate Memory on page 64 for more information Reserved Input Reserved parameter must be 0 Returns RC_SUCCESS RC INVALID SIZE RC INVALID RESERVED PARM RC CANT STOP SHARING RC INVALID BASEPTR RC INVALID CALL Remarks If the kernel has been loaded with memory protection enabled the access rights to the referenced memory block change for the calling process Only a single set of daughter card and system bus access flags are kept They are not stored on a per process basis Therefore setting these two sets of access flags affects all processes To use this service the process had to have created or opened the memory This service differs from SetProcMemProt which does not verify that the caller created or opened the memory However SetProcMemProt is available only to device drivers and subsystems ARTIC960 Programmer s Reference SetProcMemProt Change a Process Memory Protection SetProcMemProt Change a Process Memory Protection This service changes the access of a given process to a block of memory It is available only to device drivers and subsystems Functional Pro
169. box 286 Set Trace 2 4 Status utility 225 Status utility interactive 223 modes kernel service 5 move system bus data 77 MoveMCData Move system bus Data 77 move mode SCB pipes 207 MP Safe multiprocessing safe driver Multiple Virtual DOS Machines MVDM 7 mutex semaphores 50 mutual exclusion semaphore 50 MVDM Multiple Virtual DOS Machines 7 N name mailbox 277 memory 278 281 queue 95 notational conventions xiv null terminated strings 35 O open access to event word 59 mailbox 280 RadiSys ARTIC960 adapter 265 semaphore 52 OpenDev Open a Subsystem or Device Driver 725 OpenEvent Open Access to an Event Word 59 OpenMbx Open a Mailbox 706 280 OpenMem Get Addressability to Allocated Memory 67 OpenQueue Open a Queue 96 OpenSem Open a Semaphore 52 OpenSig Open a Signal 717 P parameter DATA_CACHE 80 MEM_DCACHE 80 separators 4 peek at queue 700 peer process creating 34 peer to peer communication 207 performance timer read current time 93 start 97 physical system bus address 78 pipe size default 207 pipes configure SCB 207 POST error load 99 primary process state bits 27 priority process 42 198 query process 43 process change memory protection 7 Completelnit 23 control block 23 faults 40 ID getting 44 instance data location 45 instance data returned 46 management services 22 mark as completely initialized 25 messages 295 peer creating 34 ProcessSleep 75
170. bxBuffer Yes Yes Yes Yes Yes SendMbx Yes8 Yes8 Yes8 Yes Yes4 ReceiveMbx Yes2 Yes2 Yes2 Yes Yes CloseMbx No No No Yes Yes CreateSig No No No Yes Yes OpenSig No No No Yes Yes CloseSig No No No Yes Yes InvokeSig Yes Yes Yes Yes Yes Device Driver Subsystem Services CreateDev No No No Yes Yes OpenDev No No No Yes Yes CloseDev No No No Yes Yes InvokeDev Yes Yes Yes Yes Yes AllocVector No No No Yes Yes ReturnVector No No No Yes Yes SetVector No No No Yes Yes AllocHW No No No Yes Yes ReturnHW No No No Yes Yes QueryHW No No No Yes Yes AllocVectorMux No No No Yes Yes SetVectorMux No No No Yes Yes Asynchronous Event Notification Services RegisterAsyncHandler No No No Yes Yes DeregisterAsyncHandler No No No Yes Yes Hooks RegisterHook No No No Yes Yes DeregisterHook No No No Yes Yes Chapter 2 ARTIC960 Kernel Services 17 Table 2 1 Sheet 4 of 4 ARTIC960 Kernel Services Function Interrupt Signal Async Process Critical Handler Handler Handler Exit Section Kernel Trace Services InitTrace No No No Yes Yes EnableTrace Yes Yes Yes Yes Yes DisableTrace Yes Yes Yes Yes Yes LogTrace Yes Yes Yes Yes Yes 1 When the service is called with Preemption or Interrupts disabled if the process blocks interrupts and preemption are enabled May be called with timeout equal to 0 3 When an exit handler a process cannot start stop or unload itself f the service is called for a remote mailbox interrupts and preem
171. ces 121 CreateDev Register a Subsystem or Device Driver CreateDev Register a Subsystem or Device Driver 122 This service registers the process as a subsystem or device driver Functional Prototype RIC_ULONG CreateDev char DDName RIC_DOHANDLER OpenEntry RIC_DCHANDLE CloseEntry RIC_DIHANDLER InvokeEntry A RIC ULONG OptionWord RIC DEVHANDLE DDHandle ULONG Reserved Parameters DDName Input A device name to assign to this subsystem or device driver so that other processes can access this subsystem by name The kernel s subsystems allocate all resources with the first four characters being RIC_ for the resource name User device driver and subsystem names should not start with this prefix OpenEntry Input Address of open entry point of subsystem or device driver It gets control on this entry point when an application uses OpenDev See OpenEntry Prototype on page 123 CloseEntry Input Address of close entry point of subsystem or device driver It gets control on this entry point when an application uses CloseDev See CloseEntry Prototype on page 124 InvokeEntry Input Address of strategy entry point of subsystem or device driver It gets control on this entry point when an application uses InvokeDev See InvokeEntry Prototype on page 124 OptionWord Input Bit field that gives various create options These constants may be ORed together to create the device dri
172. ces using the Subsystem Control Block SCB architecture ric_oss rel STREAMS subsystem OSS This module provides a STREAMS environment on the adapter ric_ess rel On card STREAMS Cross Bus Subsystem This module transmits STREAMS data across the system unit bus between STREAMS Access Library SAL and the On card STREAMS Subsystem OSS ric_pci rel PCI bus configuration driver This module provides basic services for configuring devices attached to the adapter s local PCI bus Specific applications may not require all modules The system executables must be loaded in the preceding order using the Application Loader utility For information see Application Loader ricload Utility on page 196 Kernel Performance Considerations 2 Kernel performance can be affected by the way the adapter is loaded and configured Instruction Cache The following support provides options that enable the kernel to pin critical kernel code in instruction cache e ARTIC960 Support for IBM OS 2 Version 1 2 1 e ARTIC960 Support for IBM AIX Version 1 2 or higher e ARTIC960 Support for Microsoft Windows NT Version 1 0 There are two types of critical kernel code e Code critical for process intensive applications dispatcher request release semaphore and so forth e Code critical for interrupt intensive applications such as first level interrupt handlers and enter exit critical section The amount of kernel code that c
173. cess 0x01060561 0x01070560 Elements empty LN gl Figure 6 58 Example Screen Queue Detail di N Enter resource name or handle gt 01070560 Resource type semaphore Name SEM ProcessSyncl Count 0 Access list Proc No Process Name Handle 0x0006 PRC_PROCA rel 0x01070571 0x0007 PRC_PROCB rel 0x01070560 M J Figure 6 59 Example Screen Semaphore Detail C N Enter resource name or handle gt 0108057E Resource type signal Name BufferRcvdSig Access list Proc No Process Name Handle Entry Key Option 0x0005 MonitorAl 0x0108057E Ox2209B4F0 0x00000000 always 0x0006 MonitorSome 0x02080576 0x220617A4 0x00000001 match X P Figure 6 60 Example Screen Signal Detail Chapter 6 System Unit Utilities 259 Examples of Interactive Messages Enter resource name or handle gt 010A0573 Resource type timer Name TIM_FeedMeNow Handle 0x010A055E Handler 0x220841AC State running Owner name PRC Mason Owner no 0x0006 Figure 6 61 Example Screen Timer Detail Enter resource name or handle gt 000C0022 Resource type hardware device Name Strange Device Status 0x000 Valid data yes Owner name PRC proc Owner no 0x000B Device data 00040000 30 30 30 30 34 00 41 42 43 00 00 00 00 00 00 00 00004 ABC 00040010 39 39 99 Figure 6 62 Example Screen Hardware Device Detail The following screen shows the prompts and items displayed when a vector resource number or name is specif
174. cess trying to release it 0x00010501 RC INVALID EVN MASK Invalid wait mask passed to WaitEvent 0x00010502 RC NO MORE EVNS All available events have been created 0x00010503 RC DUP RES HANDLES Duplicate semaphore handles were passed to CreateEvent 0x00010601 RC NO SUCH SIG ID There was no process to receive the signal 0x00010602 RC NO MORE SIGS All signal resources are allocated 0x00010701 RC NO BASE DEVICE DRIVER The service failed because the base subsystem or device driver is not installed 0x00010702 RC TIMER IS ACTIVE The TimeOfDay or Performance timers cannot be started because it is active 0x00010703 RC TIMER IS INACTIVE The time of day or performance timer cannot be stopped because it is inactive 0x00010704 RC NO MORE TIMERS All the timers have been allocated 0x00010705 RC_TOD_NOT_ENABLED The time of day timer was not enabled using the TIME_OF_DAY parameter in the kernel configuration file 0x00010706 RC_TIMER_OVERFLOWED The performance timer has already expired 0x00010707 RC_PERF_TIMER_NOT_ENABLED The performance timer was not enabled using the PERFORMANCE_TIMER parameter in the kernel configuration file 0x00010801 RC_QUEUE_EMPTY The queue was empty and no elements were added before the timeout expired on the call to GetQueue 0x00010802 RC ELEMENT NOT FOUND SearchQueue did not find the element in the queue 0x00010803 RC NO MORE QUEUES All queues are allocated 320 ARTIC960 Programmer s Reference Return Codes Lis
175. cessInExec 44 QueryProcessStatus 25 QueryProcMemProt 73 QuerySemCount 56 QuerySystemTime 90 ReadPerfTimer 93 ReceiveMbx 712 RegisterAsyncHandler 39 RegisterHook 47 ReleaseSem 54 RequestSem 55 ResizeMem 69 ResumeProcess 40 ReturnHW 36 Return Vector 33 SearchQueue 02 SendMbx 710 SetExitRoutine 47 SetMemProt 70 SetPriority 42 340 ARTIC960 Programmer s Reference SetProcessData 45 SetProcMemProt 77 SetSemCount 57 SetSystemTime 89 SetVector 3 StartPerf Timer 97 StartProcess 36 StartSwTimer 86 StopPerfTimer 92 StopProcess 37 StopSwTimer 86 SuspendProcess 39 UnloadProcess 38 WaitEvent 67 set bits 27 configuration parameters 3 exit routine 4 process instance data 45 process priority 42 time of day on adapter 98 trace buffer 50 Set Trace utility 2 3 SetExitRoutine Set the Exit Routine for the Process 4 SetMemProt Change Memory Protection 70 SetPriority Set the Priority of the Process 42 SetProcessData Set Process Data 45 SetProcMemProt Change a Process s Memory Protection 7 SetSemCount Set a Semaphore Count 57 SetSystemTime Set the Time of Day Clock 89 SetVector Set a New Interrupt Vector Entry Point 3 signal CloseSig 9 InvokeSig 20 OpenSig 7 signaling types 716 size memory block 69 memory to allocate 77 return suballocation pool 79 smallest allocatable message 04 sleep a process 75 software timer close return 85 create allocate 84 start
176. created If the file already exists the file is overwritten Use a binary editor to view the file created with the 0 option V 0 out file is used only with P _cfgfile Specifies an immediate dump This is the default mode of operation Specifies a triggered dump The dump is triggered by an adapter exception Specifies the previously requested triggered dump should be canceled and the Dump utility should terminate and uninstall A triggered dump cannot be canceled once the trigger has occurred Chapter 6 System Unit Utilities 203 Dump Utility PMC_cfgfile Dump File Header Structures The A option can be used to dump a daughter card I O region This option is not needed if the daughter card ROM or daughter card device driver fills in its specific daughter card regions in the IORegions structure of ROMTable Refer to the hardware technical reference for your adapter for more information on ROMTable If the address specified by addr is not a valid Intel 960 local bus card address for the length specified by len a bus error may be generated causing the system to halt To specify a filename with spaces or special characters in the name the name must be enclosed within quotes Quotes within a name are not supported Data begins at offset 0x00000200 typedef struct PMCFileHeader RIC_ULONG agicNo Magic No to specify a dump file RIC ULONG HdrSize Indicates total header size
177. ctional Prototype RIC_ULONG CloseMbx RIC_MBXHANDLE MbxHandle RIC_ULONG Reserved Parameters MbxHandle Input Handle of mailbox to close Reserved Input Reserved parameter must be 0 Returns RC_SUCCESS RC_INVALID_RESERVED_PARM RC_INVALID_HANDLE RC_DEPENDENT_EVENTS RC_INVALID_CALL 1 If the close is issued by a process while other processes still have access to the mailbox the service removes access rights for the calling process Any memory pool associated with the mailbox for sending by this process is released When the last process closes the mailbox the mailbox is deleted When the creator closes the mailbox the semaphore associated with the mailbox is closed and the memory used by the mailbox for receiving data is closed ARTIC960 Programmer s Reference CreateSig Create a Signal CreateSig Create a Signal This service creates a signal and optionally registers a signal handler Functional Prototype RIC_ULONG CreateSig char SigName RIC SIGHANDLER EntryPoint RIC ULONG OptionWord RIC ULONG SigHanID RIC SIGHANDLE SigHandle ULONG Reserved Parameters SigName Input Name to assign to signal so that other processes can access it This parameter also can be NULL However if it is NULL only the creating process can use the signal EntryPoint Input
178. d for peer to peer I O memory operations only 8 16 KB Memory Window ARTIC960 Micro Channel only This window is used only during device driver configuration and then it is disabled 8 KB Memory Mapped I O ARTIC960 PCI and ARTIC960Hx only This window is used for system unit to card I O memory operations Full Memory Window Under AIX the system unit driver uses this window for small accesses to ARTIC960 memory DMA Direct Memory Access Peer to Peer Support ARTIC960 Support for AIX Version 1 1 6 supports DMA between two peer adapters In versions after 1 1 6 DMA between two peer adapters is supported only for Micro Channel adapters ARTIC960 Programmer s Reference Micro Channel Only Arbitration Levels All configurable arbitration levels are supported The ARTIC960 adapters can have two arbitration levels defined The ARTIC960 AIX support uses the first arbitration level for system unit to adapter DMA transfers and the second arbitration level for peer to peer DMA transfers The adapter attribute that controls the second arbitration level is DMA2Enable and it can be changed using SMIT When DMA2Enable is set to YES a second arbitration level is reserved for peer to peer transfers Streaming Data Enable Use SMIT to change this attribute Selected Feedback Return Enable Use SMIT to change this attribute Parity Enable Use SMIT to change this attribute Channel Check Enable Use SMIT to change this attribute
179. d function number is passed 0x00010201 RC PROCESS NOT STARTED The process being stopped is not started as yet 0x00010202 RC PROCESS NOT LOADED Only a previously loaded process can be started or unloaded 0x00010203 RC PROCESS ALREADY STARTED The process has already been started 0x00010204 RC PERMANENT PROCESS The process has declared itself as permanent and cannot be stopped or unloaded 0x00010205 RC PROCESS STOPPED The process is already stopped 0x00010206 RC DEVICE DRIVER Only a device driver subsystem or the kernel can stop a device driver subsystem 0x00010207 RC NO MORE PROC No more process management resources are available to create a new process 0x00010208 RC NO FLOAT SUPPORT The adapter does not support floating point 0x00010209 RC ALREADY INITIALIZED Process has already called issued a Completelnit 0x0001020A RC INVALID PRIORITY The process is trying to use a reserved or out of range priority 0x00010301 RC MEM SHARING ERROR The memory cannot be opened because it was not made sharable by the creating process 0x00010302 RC INVALID BASEPTR The memory base pointer is invalid 0x00010303 RC CANT STOP SHARING The memory protection on the allocated memory cannot be made non sharable because multiple processes have access to the memory 0x00010304 RC INVALID SUBALLOC ADDR The suballocation block cannot be freed because the suballocation block pointer is invalid 0x00010306 RC NO MORE MEM There is no more memory or not enough conti
180. dToMC 82 ConvertMCToCard 787 MoveMCData 177 ProcessSleep 75 load application description 196 messages and exit codes 799 336 ARTIC960 Programmer s Reference sample calls 200 syntax 196 loading configuring ARTIC960 Support log trace information 53 logical card numbers 78 182 LogTrace service 53 mailbox allocate free buffer 282 APIs system unit 276 CloseMbx 4 create 277 CreateMbx 04 FreeMbxBuffer 09 GetMbxBuffer 08 messages 295 open 280 OpenMbx 06 process start 8 71 put message in 284 ReceiveMbx 112 release delete 288 return buffer 283 SendMbx 0 type 104 MallocMem Allocate Memory 80 MEM_DCACHE parameter SO memory addressability to allocated open get 67 alignment 75 allocate 64 80 close remove addressability to allocate 68 collect 82 free 87 free suballocated 7S free query 74 get suballocation 77 get remove addressability 68 management 63 protection 70 140 protection services protection query 72 73 resize allocated 69 suballocation 75 transfer 267 269 memory management CloseMem 68 CollectMem 82 CreateMem 64 FreeMem 8 FreeSuballoc 78 GetSuballoc 77 GetSuballocSize 79 InitSuballoc 75 MallocMem 80 OpenMem 67 QueryFreeMem 74 QueryMemProt 72 QueryProcMemProt 73 ResizeMem 69 SetMemProt 70 SetProcMemProt 77 messages Configuration utility 209 driver mailbox utility 295 Format Trace 2 6 Get Trace 2 6 loader 99 put into mailbox 284 quiet mode 96 read receive mail
181. displayed only on adapters with an 80960 processor that supports floating point operations 252 ARTIC960 Programmer s Reference Examples of Interactive Messages Examples of Interactive Messages The following examples all assume that the adapter number has been passed on the command line as a default 1 Configuration This example shows an Rx card with one window slot number OxFF Card ID 0x801014 Bus Type PC nterface Chip Rx Data Cache HW Not Present Base I 0 address 0x0000 nterrupt level AIB ID OxFFFFFFFF PMC Adapter Present Full window address OxFDC00000 Total memory size 0x00400000 4 0 MB Available memory 0x003B8000 Memory Region Size Type 0xA0000000 0x00400000 4 0 MB Packet Press Enter to continue X J Figure 6 44 Example Screen Configuration 2 Process Summary Name D Version Priority State PRC ric kern rel 0 00050000 0x01000001 0x00000000 blocked PRC_RIC_Mbx_SS 0x01050001 0x01000001 0x00000002 blocked PRC ric base rel 0x01050002 0x01000001 0x00000028 driver PRC ric mcio rel 0x01050003 0x01000001 0x00000028 blocked PRC ric scb rel 0x01050004 0x01000001 0x00000001 blocked PRC PROCI rel 0x02050005 0x00000000 0x00000028 queued PRC Alfonso 0x02050006 0x00000000 0x00000028 Suspended PRC Mason 0x02050007 0x00000000 0x00000028 blocked Press Enter to continue J Figure 6 45 Example Screen Process Summary Chapter 6 System
182. dy configured Action None Source Configuration RICO0061 Configuration failed between card nn and system unit Explanation Configuration between card nn and the system unit failed Action Reset the adapter and reconfigure Source Configuration 304 ARTIC960 Programmer s Reference RIC0062 RICO069 RICO062 Mailbox process successfully terminated Explanation The Mailbox process was successfully terminated Action None Source Mailbox Process RICO063 Mailbox process not running Explanation The Mailbox process was not found and could not be terminated Action None Source Mailbox Process RICO064 ROM error Oxnnnnnnnn detected on card nn Explanation The adapter has detected ROM error Oxnnnnnnnn hex on card nn Action This message indicates that an unrecoverable exception has occurred on the adapter Reset the adapter and retry the operation If the problem persists call support personnel Source Application Loader Configuration Reset OS 2 Driver RICO065 Symbol xxxxxxxx is undefined Explanation The linker failed to understand the external symbol Action Define symbol then recompile and link Source Application Loader RICO066 XXXXXXXX Interrupt nesting disabled Explanation Interrupt nesting disabled in the driver through the N command line switch Action None Source OS 2 Driver RIC0067 Pipe configuration failed between card nn and system unit Explanation The
183. e 52 Dispatch Cause a Dispatch Cycle 49 Direct Memory Access 0 driver messages 295 dump utility description 202 file decomprsesion 202 format 225 messages and return codes 206 modes 202 syntax 202 E e mail address RadiSys xv enable interrupts preemptions 48 EnableTrace service 5 end access to adapter 266 end of line sequence 96 EnterCritSec Enter Critical Section 47 entry point deregister hook 48 interrupt vector 3 register hook 47 error bus 204 codes kernel terminal 325 messages 295 POST load 99 event notification asynchronous 38 wait for 61 event word creating 58 deleting 60 open access to 59 release close access to an 60 executable files executing process get ID 44 exit codes system unit utilities 327 exit routine setting process 4 ExitCritSec Exit Critical Section 48 expired process 233 F faults processor 40 file entry format configuration 208 find PCI device 187 flags access 70 Format Trace utility 2 7 format big endian little endian 270 FreeMbxBuffer Free Mailbox Buffer 09 285 FreeMem Free Memory 8 FreeSuballoc Free Suballocated Memory 78 functional prototype 3 G get adapter handle 265 addressability to memory 67 hardware configuration data 272 memory suballocation 77 ROM information 28 semaphore count 56 software version numbers 273 Get Trace utility 2 5 GetMbxBuffer Get a Free Mailbox Buffer 708 282 GetProcessData Ge
184. e message buffer The size parameter must be in the range 0 Size 65503 For ARTIC960 PCI co processors the size parameter must be in the range 0 Size 16384 Input Bit field to describe how to send the message Use the OR operation on the following constants to build the appropriate set of options MBX SEND COPY Forces a copy of the message in the mailbox memory This option applies only when the sender and receiver are sharing memory Because the system unit supports only remote mailboxes the MBX SEND COPY option is ignored MBX SEND NO COPY This is the default because the system unit supports only remote mailboxes MBX SEND FREE BUFFER Returns the buffer to the free pool MBX SEND KEEP BUFFER The buffer must be freed explicitly with the FreeMbxBuffer call This is the default MBX SEND LIFO Puts the message in the front of the message queue MBX SEND FIFO The message is put in the back of the message queue This is the default Input Reserved parameter must be 0 ARTIC960 Programmer s Reference SendMbx Send a Message Returns RC_SUCCESS RC_NO_MORE_RES RC INVALID HANDLE RC NO RCV BUFFER RC INVALID MSG BUFFER RC PIPES NOT CONFIGURED RC INVALID OPTION RC SYSTEM ERROR RC INVALID RESERVED PARM RC UNABLE TO ACCESS UNIT RC INVALID SIZE RC MBX BUFFER IN QUEUE RC NO MBX
185. e ricclass tre has all the predefined kernel service classes and procedure names This file must be present in the current directory or one of the directories defined in the RICPATH or DPATH for OS 2 or PATH for AIX environment variables for the Format Trace utility to find it for trace formatting You have the option to specify a user trace file using the option Your trace file must contain the same classes and procedure names that you have defined You should use ricclass trc as an example for the format of the file Service class names must begin with C and procedure ID names must begin with P_ If the Format Trace utility fails to find ricclass trc the warning message RIC0003 is displayed The trace file is formatted However the service class and procedure names do not appear in the output file If the Format Trace utility fails to find the user specified service class file the message RIC0003 is displayed and the Format Trace utility terminates with exit code RC_UTIL_FILE_NOT_FOUND The Format Trace utility fails with RC UTIL FILE FORMAT ifthe binary data it formats is corrupted Format Trace Syntax eel eus path in filename O out filename C class filename Figure 6 8 Format Trace Utility Syntax Lin filename Specifies the name of the file that contains data obtained by the Get Trace utility The Format Trace utility formats the data in this file If in filename is not specified the utility searches t
186. e sender and the receiver are not sharing memory the value of the MBX SEND COPY bit is ignored and the message is copied automatically to the receive memory I The MBX SEND FREE BUFFER option is ignored if the sender and receiver are sharing memory and the MBX SEND COPY option was not requested The call returns the RC MSG BUFFER NOT FREED return code after sending the message 1 If MBX_SEND_FREE_BUFFER is specified and the SendMbx service fails the buffer is not freed It must be explicitly freed by the sender using FreeMbxBuffer If messages are being sent to other units the kernel ensures system bus access has been enabled on the mailbox pool Chapter 3 Base Kernel Services 111 ReceiveMbx Receive a Message ReceiveMbx Receive a Message 112 This service reads or receives a message from a mailbox Functional Prototype RIC_ULONG ReceiveMbx RIC_MBXHANDLE MbxHandle RIC_ULONG OptionWord RIC_TIMEOUT Timeout void MsgPtr RIC ULONG Size RIC ULONG Reserved Parameters MbxHandle Input Handle of the mailbox from which the process wants to receive a message OptionWord Input Option word for specifying receive options The following constant can be used MBX RECEIVE READ MESSAGE Return a pointer to the message but do not remove the message from the mailbox MBX RECEIVE GET MESSAGE Returns a pointer to the
187. e valid kernel CallerPosition strings are PROCEDURE_ENTRY and PROCEDURE_EXIT C 5 N ServiceClass 0 SSSSSSSSSSSSSSSS ProcedureID Oxnn SSSSSSSSSSSSSSSS CallerPosition Oxnn SSSSSSSSSSSSSSSS DataSize Oxnnnnnnnn ProcessInExec SSSSSSSSSSSSSSSS Data Bytes nn nn nn nn nn nn nn nn nn nn nn nn nn nn nn nn CCCCCCCCCCCCCCCC nn nn nn nn CCCC M J Figure 6 10 Record Description for a Service Class Data in Bytes ARTIC960 Programmer s Reference Format Trace Utility Record Description Data in Words In this record the data is shown in words The valid kernel ServiceClass and ProcedureID fields are obtained from the service class file ricclass tre and the optional C service class configuration file The valid kernel CallerPosition strings are PROCEDURE ENTRY and PROCEDURE EXIT FC UN ServiceClass Oxnn SSSSSSSSSSSSSSSS ProcedureID Oxnn SSSSSSSSSSSSSSSS CallerPosition Oxnn SSSSSSSSSSSSSSSS DataSize Oxnnnnnnnn ProcessInExec SSSSSSSSSSSSSSSS Data Words nnnnnnnn nnnnnnnn nnnnnnnn nnnnnnnn nnnnnnnn nnnnnnnn nnnnnnnn nnnnnnnn nnnnnnnn nnnnnnnn nnnnnnnn nnnnnnnn nnnnnnnn nnnnnnnn 9 J Figure 6 11 Record Description for a Service Class Data in Words Chapter 6 System Unit Utilities 221 Format Trace Utility Format Trace Record Examples S WrapAroundCount OxFFFFFFFF CurWrapAroundCount
188. e vector as shared OPTION VECTOR NOT SHARED Allocates the vector as nonshared This is the default Reserved Input Reserved parameter must 0 Returns RC SUCCESS RC VECTOR NOT AVAILABLE RC INVALID RESERVED PARM RC NOT DD OR SS RC INVALID VECTOR RC INVALID MEM ACCESS RC INVALID OPTION RC INVALID CALL RC NO MORE RES Remarks The kernel allocates the requested vector to the calling process If OPTION VECTOR NOT SHARED is requested and the vector was previously allocated as nonshared RC VECTOR NOT AVAILABLE is returned Refer to the ARTIC960 Programmer s Guide for information about vector sharing Memory protection for an interrupt handler is disabled when global memory protection is disabled regardless of the state of the OptionWord The calling process must be a device driver or subsystem A process may not allocate the same vector multiple times Chapter 3 Base Kernel Services 129 AllocVectorMux Allocate an Interrupt Vector 130 TheSetInterruptPriority macro be used from within an interrupt handler to set a new interrupt priority level for the processor This macro gives an interrupt handler the ability to lower its priority and allow other interrupts at the same level or lower levels to be serviced The macro is defined as follows define SetInterruptPriority priority 0 Valid priority values are
189. ed memory protection is turned on if global memory protection is enabled For device drivers and subsystems the state of memory protection depends on the OptionWord specified in CreateDev ARTIC960 Programmer s Reference CloseSig Close a Signal CloseSig Close a Signal This service releases access to a signal and deletes the signal if no other processes have access Functional Prototype RIC_ULONG CloseSig RIC_SIGHANDLE SigHandle RIC_ULONG Reserved Parameters SigHandle Input Signal handle of signal to release Reserved Input Reserved parameter must be 0 Returns RC_SUCCESS RC_INVALID_HANDLE RC_INVALID_RESERVED_PARM RC_INVALID_CALL Remarks If a process attempts to close a signal while other processes still have access to the signal the service removes access rights for the process issuing the call When the last process with access rights calls this service the signal ceases to exist Chapter 3 Base Kernel Services 119 InvokeSig Call a Signal InvokeSig Call a Signal This service calls a signal Functional Prototype RIC_ULONG InvokeSig RIC_SIGHANDLE SigHandle RIC_ULONG SigHanID void Parms RIC_ULONG ParmLen ULONG Reserved Parameters SigHandle Input Handle of signal returned from CreateSig or OpenSig SigHanID Input A value of 0 is interpreted as a broadcast Every receiving process gets control unconditionally Any other
190. ed by the process When memory is shared the MsgUnitSize and MsgUnitCount parameters must each be equal to those passed when the memory was allocated Otherwise the RC INVALID SIZE Or RC INVALID COUNT error is returned depending on which parameter is not the same as the respective input parameter OS 2 does not provide counting semaphores In its implementation the ReceiveMbx call sets the semaphore before blocking on it Applications wanting to use the semaphore directly to wait on the arrival of a message must call the ReceiveMbx call with a no wait timeout value before blocking on the semaphore The semaphore is cleared by mailbox services when a message arrives ARTIC960 Programmer s Reference CreateMbx Create a Mailbox In AIX the application is responsible for creating a semaphore and providing the returned information into the structure RIC_Semhandle defined in rictaixa h typedef struct RIC_Semhandle int semid int semnum RIC_SEMHANDLE semid semaphore identifier returned from semget system call semnum The semaphore number After CloseMbx is called the application is responsible for removing the semaphore from the system The application must not modify the variable semval for information on semval see usr include sys sem h which is modified by the AIX Mailbox Daemon and has one of the following values Messages in mailbox 1 No messages in mailbox In AIX MbxHandle is valid
191. ence Application Loader ricload Utility process_args Specifies that the arguments in process_args which is enclosed within a single set of quote marks are to be passed to the process as argv 1 through argv n The process args arguments themselves must not contain the quote characters To use a quote mark within the arguments use the F arg filename parameter Using this parameter allows you to pass command line parameters in a file F arg filename Specifies that the contents of the file arg filename are passed to the process as argv 1 through argv n Each line in the file is passed as a separate argv entry D cache option Specifies data cache options for loading the process The valid values are D 0 Caching is not used the default D 1 Process stack is cached D 2 Process data section is cached D 3 Both the process stack and data sections are cached This option has no effect unless the i960 data cache is enabled See the definition of DATA CACHE on page 5 K stack size L W timeout Specifies the size of the process stack in bytes If this parameter is not specified the kernel chooses its default stack size Specifies that the process is to be loaded but not started Specifies the time in seconds that the Application Loader waits for the loaded process to complete initialization The Application Loader then outputs a message indicating the success o
192. ence RIC0007 RIC0014 RICO007 Invalid process name Explanation The process name xxxxxxxx is too long Action Rename the process and retry the command Source Application Loader RICOO008 Duplicate process name xxxxxxxxx Explanation The process name xxxxxxxx is already active on the adapter Action Either specify a different process name or unload the active process and retry the command Source Application Loader RICO009 Exception condition xxxxxxxx detected on card nn Explanation The adapter has detected exception condition hex on card nn Action This message indicates that an unrecoverable exception has occurred on the adapter Reset the adapter and retry the operation If the problem persists call support personnel Source Application Loader Configuration Reset OS 2 driver RICO010 No device response from card nn Explanation Adapter nn is not responding to commands Action Check the state of the processes running on the adapter for severe error conditions Reset the adapter and retry the operation If the problem persists call support personnel Source Application Loader Dump Configuration Reset Status RICOO011 Dump of card nn in progress Explanation A dump of card nn is currently in progress This message is displayed during an immediate dump and after a triggered dump has been triggered by an error condition on the card Action Wai
193. end a Message C ReceiveMbx Receive a Message GCloseMbx Close a Maillb x 5 nette tec EE E eec eo Pee Appendix A Structure RIC CONFIG RIC VERDA TA Structures lis eere RIC Appendix B Message Driver Mailbox Process and Utility Messages Appendix C Return Error and Exit Codes sss Return Codes Listed Alphabetically 000 ceceececeseeeeeeseeeeeeseecaecaaesaecacsaeceseeseeeeeeecaessaecaaeaesaeenaees Return Codes Listed Kernel Terminal Error Codes eene enne Exit Codes for System Unit Utilities sssini aiene EEEE E nennen enne teen Ru M Contents 267 269 271 272 273 274 276 277 280 282 283 284 286 288 289 290 292 293 295 295 311 312 316 325 327 331 333 vii viii ARTIC960 Programmer s Reference Figures 1 1 1 2 1 3 6 1 6 2 6 3 6 4 6 5 6 6 6 7 6 8 6 9 6 10 6 11 6 12 6 13 6 14 6
194. er is beyond the range of acceptable unit numbers Aninvalid unit number was passed 0x00010010 RC ENTITY ALREADY REGISTERED The entity is already registered 0x0001001 1 RC ENTITY NOT REGISTERED The entity number passed by the caller is invalid The entity number has not been registered 0x00010012 RC INVALID ENTITY NUMBER Entity zero is reserved by the system for the system management entity 0x00010013 RC NO MORE ENTITIES The number of entities registering has exceeded the maximum 8 0x00010014 RC INVALID COUNT The count parameter is out of range The mailbox message count is incompatible with the previously created mailbox 0x00010015 RC INVALID NAME The name used to create or open a resource exceeds the maximum size 0x00010016 RC INVALID OPTION Aninvalid user option was selected possibly through an OptionWord parameter Aninvalid option was passed on the call 0x00010017 RC PIPES CONFIGURED SCB pipes are not configured for this unit after a reset The SCB pipes to the destination unit are no longer configured 0x00010018 RC TIMEOUT The semaphore wait timed out before the process was awakened This may occur during an explicit call to RequestSem or implicitly through another call that waits on a semaphore for the process The operation timed out before it could complete successfully 0x00010019 RC BUFFER TOO SMALL The buffer provided by the caller is too small The buffer will be filled up to its size The su
195. erm system bus can refer to either the Micro Channel or PCI bus counts in this book are assumed to start at zero numeric parameters and command line options are assumed to be decimal values unless stated otherwise To pass a hexadecimal value for any numeric parameter the parameter should be prefixed by 0 or 0X Thus the numeric parameters 16 0x10 and 0X10 are all equivalent Utilities all accept the switch as a request for help with command syntax representations of bytes words and double words are in the little endian format All bit numbering conforms to the industry standard of the most significant bit having the highest bit number Bit 0 is the low order bit If a bitis set to 1 the associated description is true unless stated otherwise Screen text and syntax strings appear in this font Notes indicate important information Cautions indicate situations that may about the product result in damage to data or the hardware Tips indicate alternate techniques or ESD cautions indicate situations that procedures that you can use to save may cause damage to hardware via time or better understand the product electrostatic discharge The globe indicates a World Wide J Warnings indicate situations that may Web address result in physical harm to you or the hardware ARTIC960 Programmer s Reference Where to Get More Information You can find out more about RadiSys ARTIC960 from these sources Wo
196. error code RC_NEW_SEM_COUNT If a process closes a mutex semaphore while owning it the WaitEvent is canceled with the error code RC_OWNER_CLOSED_SEM ARTIC960 Programmer s Reference Memory Management Services Memory Management Services The following are the memory management services Service Name Page CreateMem 64 OpenMem 67 CloseMem 68 ResizeMem 69 SetMemProt 70 SetProcMemProt 71 QueryMemProt 72 QueryProcMemProt 73 QueryFreeMem 74 InitSuballoc 75 GetSuballoc 77 FreeSuballoc 78 GetSuballocSize 79 MallocMem 80 FreeMem 81 CollectMem 82 Refer to the ARTIC960 Programmer s Guide for additional information Chapter 3 Base Kernel Services 63 CreateMem Allocate Memory CreateMem Allocate Memory 64 This service allocates memory from the free storage pool to a requesting process Functional Prototype RIC_ULONG Parameters MemName Size Alignment Access MemType Baseptr Reserved CreateMem char MemName RIC_ULONG Size RIC_ULONG Alignment RIC_ULONG Access RIC_ULONG MemType void Baseptr RIC ULONG Reserved Input An optional storage area name to assign to the memory block so that other processes can get access to the same block by name This name also can be NULL Memory cannot be shared when MemName is NULL The kernel s subsystems allocate all resources with the first four characters
197. eruser authority required The mailbox process requires certain initialization parameters If you do not specify these parameters they take default values The parameters take the form of keywords followed by an sign and their value Spaces tabs or new lines should separate individual parameters The following parameters can be set MAX GLOBAL MAILBOX The maximum number of global mailboxes created in the system unit The default is 16 MAX REMOTE MAILBOX The maximum number of remote mailboxes opened from system unit The default is 16 MAX REMOTE MAILBOX OPEN The maximum number of remote mailbox open requests outstanding at any one time The default is 16 MAX REMOTE MAILBOX SEND The maximum number of remote mailbox send requests outstanding at any one time The default is 32 MAX REMOTE MAILBOX RCV The maximum number of remote mailbox receive requests outstanding at any one time The default is 64 MAX NUM OF UNITS The maximum number of SCB units The default is 16 AIX MBX PROCESS PRIORITY The mailbox process priority for the mailbox Application processes wanting to use the mailbox services need to have their process priority a lesser priority than the mailbox process 1 is the highest priority level within AIX The default is 16 For remote mailbox processing to occur the Configuration utility must be used to establish communication between the system unit and
198. escribes the Miscellaneous Service the System Bus Interface Services and the PCI Services 6 System Unit Utilities Describes the available system unit utilities 7 System Unit APIs Describes the system unit APIs The appendices provide additional information about ARTIC960 Appendix Description A Structure Definition Lists the RIC_CONFIG RIC_VERDATA and RIC_EXCEPT structures B Message File Explains the error messages and the actions to be taken C Return Error and Exit Codes Lists and explains the return codes About This Book xiii Notational Conventions xiv This manual uses the following conventions d 4 The term ARTIC960 always refers to the RadiSys ARTIC960 products The term ARTIC960 can refer to programs that run on the ARTIC960 ARTIC960 ARTIC960Rx PCI or ARTIC960Hx PCI adapters or the adapters themselves The term ARTIC960 PCI refers to functions supported only on the ARTIC960 PCI adapter ARTIC960 MCA refers to functions supported only on the ARTIC960 Micro Channel adapter The term ARTIC960Rx PCI refers to functions supported by the ARTIC960Rx PCI adapter ARTIC960Hx PCI refers to functions supported by the ARTIC960Hx PCI adapter The term ARTIC960RxD PCI refers to functions supported by the ARTIC960RxD PCI adapter The term OS 2 always refers to the OS 2 operating system The term AIX always refers to the IBM AIX operating system The t
199. essID Output The process ID of the currently executing process Reserved Input Reserved parameter must 0 Returns RC SUCCESS RC INVALID RESERV ED PARM RC INVALID MEM ACCESS Remarks At process time this call returns the caller s process ID When called in interrupt handlers this call returns the process that was executing at the time of the interrupt If no process was executing at the time of the interrupt ProcessID is set to INVALID PROCESSID ARTIC960 Programmer s Reference SetProcessData Set Process Data SetProcessData Set Process Data This service sets process instance data for the indicated application environment and process Functional Prototype RIC_ULONG SetProcessData void ProcessDataPtr unsigned char ApplID PROCESSID ProcessID Parameters ProcessDataPtr Input Pointer to process instance data ApplID Input Unique ID to indicate which application environment the process instance data is associated with IDs 0 through 63 are reserved for ARTIC960 use ProcessID Input Indicates which process the instance data is for A value of 0 indicates the process in execution Returns RC SUCCESS RC NO MORE RES RC INVALID PROCESSID RC INVALID CALL Remarks This service maintains process instance data pointers for up to 15 application IDs If more than 15 application IDs are specified RC NO MORE RES is returned
200. ests to the kernel using the kernel command facility These requests are sent to the kernel through its mailbox named RIC_KERNMBXn n is a logical card number As an example commands destined for the kernel on logical card 0 would be sent to mailbox RIC_KERNMBXO Command completion status is returned to the requester in a response mailbox specified using the RegisterResponseMbx command Requesters should check the status provided in the response mailbox to verify successful command completion The following kernel commands have been defined Refer to the ARTIC960 Programmer s Guide for additional information Service Group Page RegisterResponseMbx 166 DeRegisterResponseMbx 167 QueryProcessStatus 168 UnloadProcess 169 StopProcess 170 StartProcess 171 Chapter 4 Kernel Commands 163 Common Headers for Commands and Responses 164 Commands All commands have a common header with a variant part unique for each command The format is struct RIC_KernCommand struct RIC_KernMbxCmd Header union struct RIC_RegisterResponseMbxCmd struct RIC_DeregisterResponseMbxCmd Cmd1 struct RIC QueryProcessStatusCmd Cmd2 struct RIC StopProcessCmd Cmd3 struct RIC StartProcessCmd Cmd4 struct RIC_UnloadProcessCmd Cmd5 Cmds struct RIC_KernMbxCmd RIC_ULONG CommandNum RIC RESPMBX RespMbxID RIC_ULONG CorrelationID RIC ULONG ReturnCode RIC ULONG Reserved where CommandN
201. et of options OR the following constants MBX Sl END COPY Forces a copy of the message in the mailbox memory This option applies only when sender and receiver are sharing memory The default is MBX_SEND_NO_COPY MBX_S END FREE BUFFER Returns the buffer to the free pool The default is MBX SEND KEEP BUFF ER which means the buffer must be freed explicitly with the FreeMbxBuffer service MBX S END LIFO Puts a message in the front of the message queue The default is MBX SEND FIFO which means that the message is put at the end of the message queue Reserved Input Reserved parameter must be 0 Returns RC SUCCESS RC INVALID RESERVED PARM RC INVALID RC INVALID SIZE HANDLE RC NO MBX R RC MSG BUFF RC INVALID 110 ARTIC960 Programmer s Re ER NOT FREED BX BUFFER ADDR ference RC NO RCV BUFFER RC INVALID CALL RC INVALID OPTION RC INVALID MEM ACCESS RC UNABLE TO ACCESS UNIT RC PIPES NOT CONFIGURED RC MBX BUFFER IN QUEUE SendMbx Send a Message Remarks The semaphore associated with this mailbox is incremented by 1 The MBX SEND COPY option is valid only if the sender and the receiver are sharing memory It can be used with shared memory to keep the message around for further processing If th
202. et the Configuration Parameters This service gets the kernel parameters Functional Prototype RIC_ULONG QueryConfigParams struct RIC_ConfigParms ParmPtr RIC_ULONG BufferSize RIC_ULONG Reserved Parameters ParmPtr Input Pointer to user s structure The kernel parameters are copied into this memory BufferSize Input Number of bytes to copy to the user s buffer Reserved Input Reserved parameter must be 0 Returns RC_SUCCESS RC_BUFFER_TOO_SMALL RC_INVALID_MEM_ACCESS RC_INVALID_RESERVED_PARM Remarks This is the configuration parameter structure These values are set at load time The user can set these with a configuration file A default value is used for each parameter not set by the user struct RIC_ConfigParms RIC_ULONG MemoryProtection RIC_ULONG DefaultPriority RIC_ULONG MaxProcess RIC_ULONG MaxTimer RIC_ULONG MaxSemaphore RIC_ULONG MaxMemAlloc RIC ULONG MaxQueue RIC ULONG MaxEvent RIC ULONG MaxDDSS RIC_ULONG MaxSignal RIC_ULONG MaxLocalMailbox RIC_ULONG MaxGlobalMailbox RIC_ULONG MaxRemoteMailbox RIC_ULONG MaxRemoteMailboxOpen RIC_ULONG MaxRemoteMailboxSend RIC_ULONG MaxRemoteMailboxRcv RIC_ULONG MaxPeerAdapters RIC_ULONG MaxSystemMCReq RIC_ULONG MaxAdapterMCReqg RIC ULONG DefaultStackSize RIC_ULONG TimeSlice RIC_ULONG WatchDog Chapter 3 Base Kernel Services 31 QueryConfigParams Get the Configuration Paramete
203. eue an SCB element Note This error can occur in RISC systems if the secondary arbitration level is not configured See ARTIC960 Support for AIX on page 10 0x100E TERMERR_PIPE_TIMEOUT A system bus timeout error occurred while trying to enqueue an SCB element 0x100F TERMERR_INVOKING_RIC_MCIO An error occurred trying to open or call the system bus Subsystem 0x1010 TERMERR_INVOKING_RIC_SCB An error occurred trying to open or call the system bus Subsystem Refer to the ARTIC960 Programmer s Guide for more information about terminal errors 326 ARTIC960 Programmer s Reference Exit Codes for System Unit Utilities Exit Codes for System Unit Utilities The following exit codes are listed by decimal value Exit Code Description 0 RC_UTIL_SUCCESS The utility command executed successfully RC UTIL INVALID CARD NUMBER The specified logical card number is invalid The card number is either non numeric or out of range RC UTIL RESET FAILED The card failed to reset due to an exception condition detected on the card RC UTIL ACCESS ERROR An unexpected error was returned by the device driver while accessing the card RC UTIL NO ADAPTER RESPONSE The adapter is not responding to commands RC UTIL NOT INSTALLED The driver is not installed and running in the system This occurs when a utility or mailbox process attempts to access an adapter and the device driver is not installed RC UTIL ADAPTER EXC
204. expected that each subsystem or device driver will run with memory protection disabled in production systems The following are examples of function prototypes for OpenEntry CloseEntry and InvokeEntry that must be followed when writing a device driver or subsystem OpenEntry Prototype The function prototype for OpenEntry must be RIC ULONG Open Name void DDParams RIC ULONG Size RIC PROCESSID ProcessID RIC_ULONG DevMemo RIC_ULONG DevMemo Parameters DDParams Input Address of subsystem or device driver defined parameters Size Input Size of subsystem or device driver defined parameters The size of the buffer pointed to by DDParams ProcessID Input The ProcessID of the process in execution DevMemo Output Device memo returned to the kernel from the driver or subsystem Returns Must return RC SUCCESS if it is successful or a non zero value between OxFFFF0000 and OxFFFFFFFF if it fails Chapter 3 Base Kernel Services 123 CreateDev Register a Subsystem or Device Driver 124 CloseEntry Prototype The function prototype for CloseEntry must be RIC_ULONG Close_Name RIC PROCESSID ProcessID RIC ULONG DevMemo Parameters ProcessID Input The ProcessID of the process in execution DevMemo Input Device memo value previously provided by the subsystem Returns Must return RC SUCCESS if it is successful or a non zero value between OxFFFF0000 and OxFFFFFFFF
205. ffer 283 GetMbxBuffer 282 OpenMbx 280 ReceiveMbx 286 SendMbx 254 technical support xv terminate access to adapter 266 time of day clock setting the 89 query system 90 timeout value mailbox 5 timer services 63 trace buffer 50 trace control block record 2 9 trace information disable 52 enable 5 logging 53 trace utilities 2 2 transport services triggered dump mode 202 troubleshooting xv U UnloadProcess Unload a Process 35 169 URL RadiSys xv utility application loader 196 configuration 207 dump 202 format trace 2 7 get trace 2 5 messages 295 reset 2 0 set trace 2 3 Status 223 trace 2 2 V VPD Vital Product Data 267 Index 341 wait for exception conditions 274 wait for semaphore 55 WaitEvent Wait on an event 6 word swapping 268 270 World Wide Web accessing RadiSys xv wrap trace buffer 2 3 write 32 bit doubleword to PCI space 793 byte to PCI space 97 data to adapter memory 269 word to PCI space 92 342 ARTIC960 Programmer s Reference
206. fier is then used when accessing the device on subsequent PCI driver calls Returns RC SUCCESS RC PCI NO BIOS RC PCI DEVICE NOT FOUND Remarks To find multiple devices having the same class code the calling software should make successive calls to this function starting with Instance set to zero and incrementing it until the return code is RC PCI DEVICE NOT FOUND Chapter 5 Adapter Library Routines 187 pciReadConfigByte Read a Byte from PCI Configuration Space pciReadConfigByte Read a Byte from PCI Configuration Space 188 This service reads one byte from the device PCI configuration space Functional Prototype RIC_ULONG pciReadConfigByte Parameters PCI_ID RegNum unsigned char Value pcuD Input The PCI device identifier obtained by way of the pciFindDevice or pciFindClassCode service RegNum Input The register number to be read normally 0 to 255 Value Output The byte read is returned in this parameter Returns RC SUCCESS RC PCI NO BIOS RC PCI BAD R EGISTI ER NUMBI Remarks None ARTIC960 Programmer s Reference ER pciReadConfigWord Read a Word from PCI Configuration Space pciReadConfigWord Read a Word from PCI Configuration Space This service reads one 16 bit word from the device PCI configuration space Functional Prototype RIC_ULONG pciReadConfigWord PCI_ID
207. formance Timer This service starts the performance timer Functional Prototype RIC ULONG StartPerfTimer RIC ULONG Reserved Parameters Reserved Input Reserved parameter must be 0 Returns RC SUCCESS RC TIMER IS ACTIV RC_INVALID_RESERVED_PAR RC NO BASE DEVICE DRIVER RC PERF TIMER NOT ENABLED Remarks The range of the performance timer is from 1 microsecond to 6 seconds The performance timer cannot be restarted once it is active To restart the performance timer it must first be stopped with StopPerfTimer As long as users check the return code from this service it effectively serializes use of the performance timer Chapter 3 Base Kernel Services 91 StopPerfTimer Stop the Performance Timer StopPerfTimer Stop the Performance Timer This service stops the performance timer and returns the final time Functional Prototype RIC_ULONG StopPerfTimer RIC_ULONG TimeCount RIC_ULONG Reserved Parameters TimeCount Output Final count of performance timer in microseconds Reserved Input Reserved parameter must be 0 Returns RC_SUCCESS RC_INVALID_MEM_ACCESS RC_INVALID_RESERVED_PAR RC TIMER OVERFLOWED RC PERF NOT ENABLED ES A Remarks None 92 ARTIC960 Programmer s Reference ReadPerfTimer Read Current Time of the Performance Timer ReadPerfTimer
208. g process wants control any time the signal is called SIG_CONTROL_MATCH Calling process wants control only when the signal is called with a matching SigHanID SigHanID Input This parameter is valid only if OptionWord is SIG CONTROL MATCH The caller gets control only when the signal is called with a matching SigHanID The SigHanID cannot have a value of 0 because it is used for broadcasts SigHandle Output Handle for the signal requested by the process This handle is used to call the signal Reserved Input Reserved parameter must be 0 Returns RC_SUCCESS RC INVALID NAME RC INVALID RESERVED PARM RC INVALID MEM ACCESS RC NO MORE RES RC INVALID CALL RC NAME NOT FOUND RC INVALID OPTION Chapter 3 Base Kernel Services 117 OpenSig Open a Signal 118 Remarks Processes that open a signal with a NULL EntryPoint are calling processes Processes that create a signal using a non NULL EntryPoint are receiving processes The EntryPoint for a receiving process should be a handler that accepts three parameters e SigHanID e A pointer to a parameter block e parameter block size It should also return a flag as the function value indicating what the kernel should do next The kernel should call the rest of the receiving processes in the chain The kernel should give control back to the calling process immediately For normal processes when the handler is call
209. guous memory to complete the allocation request 0x00010307 RC INVALID ALIGNMENT The process is trying to allocate memory on a boundary that is not possible 0x00010401 RC NEW SEM COUNT When SetSemCount is called for a semaphore that has processes waiting on it the processes are awakened with this return code 0x00010402 RC INVALID SEM COUNT An invalid semaphore count was passed to SetSemCount 0x00010403 RC DEPENDENT EVENTS The semaphore could not be closed because events still exist that depend on the semaphore Close the events before attempting to close the semaphore Appendix C Return Error and Exit Codes 319 Return Codes Listed Numerically Return Code Description 0x00010404 RC_NO_MORE_SEM No more semaphores can be allocated All available semaphores have been allocated 0x00010406 RC_OWNER_CLOSED_SEM The process that owned a mutex semaphore closed it or a process was stopped while it owned the mutex semaphore The code and data serialized by the mutual exclusion semaphore may be in an state that cannot be determined 0x00010407 RC_SEM_ALREADY_OWNED The process requesting the mutual exclusion semaphore already owns that semaphore 0x00010408 RC_PROCESSES_WAITING_ON_SEM Returned when calling SetSemCount This is a warning to the process that other processes were waiting on this semaphore 0x00010409 RC_SEM_NOT_OWNED The semaphore is not owned by the pro
210. guration Parameters 3 QueryFreeMem Query Free Memory 74 QueryHW Query Status of Hardware Device 37 QueryMemProt Query Memory Protection 72 QueryPriority Query the Priority of the Process 43 QueryProcessInExec Get ID of Process in Execution 44 QueryProcessStatus Get the Process Status 25 768 QueryProcMemProt Query a Process s Memory Protection 73 QuerySemCount Get a Semaphore Count 56 QuerySystemTime Get the Time of Day 90 queue CloseQueue 97 CreateQueue 95 GetQueue 00 name 95 OpenQueue 96 PutQueue 98 SearchQueue 02 quiet dump operation 202 quiet mode 96 208 quote in parameter 797 R RadiSys contacting xv RDT Resource Descriptor Table 35 read 16 bit word from PCI space 789 32 bit doubleword from PCI space 790 byte from PCI space 788 data from adapter memory 267 mailbox message 286 ReadPerfTimer Read Current Time of the Performance Timer 93 realtime multitasking kernel 27 receive mailbox message 286 ReceiveMbx Receive a Message 72 286 receiving process 16 record description 220 221 records Format Trace utility 2 9 reference publications xv Register asynch handler service 739 register PC and AC 42 RegisterHook Register an Entry Point for a Hook 47 RegisterResponseMbx command 66 release access to memory 66 mailbox 288 release access to event word 60 ReleaseSem Release a Semaphore 54 remove queue element 02 response mailbox 167 RequestSem Request a Se
211. hapter 3 Base Kernel Services 153 LogTrace Log Trace Information 154 DataSize Input Number of bytes of data to be logged from Address The DataSize must be 0 and the address must be NULL if TraceOption is TRACE_NOINFO Address Input Pointer to the buffer containing the data to be logged Returns RC_SUCCESS RC_INVALID_SERVICECLASS RC_INVALID_MEM_ACCESS RC_INVALID_PROCEDURE_ID RC_INVALID_OPTION RC TRACE NOT INITIALIZI Remarks RC INVALID CALLER POSITION This service logs the trace information for the calling procedure if the trace was enabled for the service class of the calling procedure The task calling This service must be compiled with the DTRACE option The service classes defined for the kernel are C_ASYNC_EVENT_SERVICE C_CLIB _DEVICE_DRIVER_S Q RVICE EVENT SERVICE HOOK SERVICE TERRUPT SERVIC 2 1 AN ERN COMMANDS SERVIC 1 pH H UJ O O 5 lt H a U nO HEGYE z Dd U m O Fa Uu A lt H a x 0 n H H P J H a id d uad n H ES m n pa lt H Q ARTIC960 Programmer s Reference Kernel Trace I
212. hat the calling process has completed initialization This service can also indicate initialization errors Functional Prototype ULONG CompleteInit ULONG ErrorCode RIC ULONG ProcessRev RIC ULONG OptionWord RIC ULONG Reserved Parameters ErrorCode Input Contains process specific information stored in the process control block If this field is 0 the process initialized successfully If this field is greater than 0 the process found an error during initialization ProcessRev Input Contains process specific information stored in the process control block Although no specific format is defined the following format is recommended ProcessRev is a 32 bit application version number 8 bit major version number most significant byte e 8 bit minor version number 16 bit revision number least significant two bytes OptionWord Input A bit field specifying options for the CompleteInit service PERMANENT PROCESS The process is defined as permanent and cannot be stopped or unloaded RANSIENT PROCESS Specifies that the process can be stopped or unloaded Reserved Input Reserved parameter must 0 Returns RC_SUCCESS RC INVALID CALL RC INVALID RESERVED PARM RC INVALID OPTION RC ALREADY INITIALIZED Remarks This service is used by all processes device drivers and subsystems Device drivers and subsystems will not receive OPEN requests until
213. he 80960 PCI bus error Chapter 3 Base Kernel Services 139 RegisterAsyncHandler Register an Async Handler 140 ProcessorEvents Input Mask specifying of which processor events the process wants to be notified You can OR the following event flags together to form the processor event mask AEN_80960_ARITHMETIC Arithmetic AEN_80960_CONSTRAINT Constraint AEN_80960_OPERATION Operation AEN_80960_PROTECTION Protection AEN_80960_TRACE Trace AEN_80960_TYPE Type AsyncHandler Input Address of user defined asynchronous event notification handler This handler is called when any of the events specified in the masks occur See Asynchronous Event Notification Handler on page 141 Reserved Input Reserved parameter must be 0 Returns RC_SUCCESS RC NO MORE RES RC DUP ASYNC EVENT RC INVALID MEM ACCESS RC INVALID RESERVED PARM RC INVALID CALL Remarks See the Intel 80960CA User s Manual for more information on processor faults Parallel faults are not reported to users directly Instead the processes are notified separately of each fault that is part of the parallel fault If a process calls this service more than once the process is notified of all events requested in all calls However the process cannot register for a particular event again unless it first deregisters for that event If the process issues a call to register for an event again
214. he current directory then RICPATH followed by the DPATH for OS 2 or PATH for AIX environment variables for rictrace bin O out filename Specifies the name of the file for which the formatted information is stored If the file already exists the data in the file is overwritten If out filename is not specified the formatted data is written to stdout C class filename Specifies the name of the file that contains the user s service class and procedure ID information Chapter 6 System Unit Utilities 217 Format Trace Utility 218 Example of a Format Trace Call The following example illustrates the use of format trace ricgettr 0 ricfmttr This sample reads the trace buffer on card 0 and writes the formatted trace to stdout A file rictrace bin is created in the current directory Format Trace Messages and Exit Codes The contents of the message file used by all utilities are listed in Appendix B Message File on page 295 The messages used by the Format Trace utility are listed in Figure 6 6 The Format Trace utility also sets its exit code value to indicate the status of the Format Trace operation The following table correlates the exit code of the Format Trace utility with the messages Table 6 7 Format Trace Utility Messages and Exit Codes Message Number Exit Code Notes RICO001 RC UTIL INVALID CMDLINE OPTION RIC0002 RC UTIL INVALID CMDLINE PARM RIC0003 RC UTIL FILE N
215. hh hh hh hh hh hh hh hh hh hh hh hh CCCCCCCCCCCCCCCC J Figure 6 33 Queue Detail Display ARTIC960 Programmer s Reference Status Interactive Messages 6 Semaphore Resource Details Submenu The following screen shows the prompts and items displayed when Semaphore is selected from the Resource details submenu The entries in the Access list fields show all processes that have access to the resource See Figure 6 59 on page 259 for an example Enter adapter number gt Enter resource name or handle gt Resource type semaphore Name SSSSSSSSSSSSSSSS Count nnnnnnnn Access list Proc No Process Name Handle nnnnnnnn SSSSSSSSSSSSSSSS nnnnnnnn M P Figure 6 34 Semaphore Detail Display Chapter 6 System Unit Utilities 245 Status Interactive Messages 246 7 Signal Resource Details Submenu The following screen shows the prompts and items displayed when a signal is selected from the Resource details submenu e Valid signal options are always match and sender e The entries in the Access list fields show all processes that have access to the resource The Entry field is empty if the Option field is sender e The Key field is ignored unless the Option field is match See Figure 6 60 on page 259 for an example di Enter adapter number gt Enter resource name or handle gt Resource type signal Name SSSSSSSSSSSSSSSS Access list Proc No Process Name Handle Entry Key
216. ices when this mailbox is referred to MbxType Output Type of mailbox that was opened The MbxStatus field can return the following values TI MBX TYPE LOCAL The mailbox is on this unit and does not accept messages from other units MBX TYPE GLOBAL The mailbox is on this unit and accepts messages from other units MBX TYPE REMOTE The mailbox was created on another unit Reserved Input Reserved parameter must be 0 Returns RC SUCCESS RC NO MORE RES ON REMOTE RC INVALID RESERVED PARM RC NO MORE RE BX RC INVALID NAME RC NO MORE QUEUES RC NAME NOT FOUND RC REMOTE CFG NOT EST RC INVALID OPTION RC INVALID MEM ACCESS RC NO MORE RES RC INVALID CALL RC DUP RES NAME RC INVALID SIZE RC NO MORE MEM RC INVALID COUNT Remarks If the memory name provided by the process is the same as that passed to CreateMbx the service does not create a new memory pool it gives the process access to the memory pool already created If the memory name is not the same this service allocates the memory requested by the process This memory is used to send messages by this process and a copy operation is performed by SendMbx If the process is sharing the memory the MsgUnitSize and MsgUnitCount parameters must be less than or equal to the values specified when the memory was cre
217. ied on the main menu Enter resource name or handle gt 64 Resource type vector Vector VEC_SWVect 64 Access list Proc No Process Name Handle Handler Protection Return Code 0x0005 PRC_TransData 0 0108057 Ox2209B4FO enabled yes 0x0006 PRC MonitorErr 0x02080576 0x220617A4 disabled yes M Figure 6 63 Example Screen Vector Detail 260 ARTIC960 Programmer s Reference Examples of Interactive Messages 9 Exception Conditions Exception code 0x24 Adapter Fault Watchdog Timeout Exception data 0x00000001 0 00000000 0 01050002 0 00000001 0x2200CBA4 0 00000000 0 00000000 0 00000000 0x00000000 0 00000000 0 00000000 0 00000000 Press Enter to continue X J Figure 6 64 Example Screen Exception Conditions 10 VPD Information S Displayable Message ARTIC960 Co Processor Adapter Adapter Type 00 Part Number 0000091F7710 FRU Number 000006162916 Serial Number 12345678 anufacturer ID 1988000000 EC Level 000000033261 ROS Level and ID 1 4 Press Enter to continue M J Figure 6 65 Example Screen VPD Information for PS 2 Systems C gt Displayable Message ARTIC960 Co Processor Adapter Adapter Type 00 Part Number 0000091F7710 FRU Number 0000061G2916 Serial Number 2345678 anufacturer ID 988000000 EC Level 000000033261 Device Driver Level 0 Diagnostic Level 0 Loadable Microcode 01 01 ROS Level and ID 4 Press Enter to continue
218. if it fails InvokeEntry Prototype The function prototype for InvokeEntry must be RIC ULONG Invoke Name void DDParams RIC ULONG Size RIC PROCESSID ProcessID RIC_ULONG DevMemo Parameters DDParams Input Address of subsystem or device driver defined parameters Size Input Size of subsystem or device driver defined parameters The size of the buffer pointed to by DDParams ProcessID Input The ProcessID of the process in execution DevMemo Input Device memo value previously provided by the subsystem Returns Must return RC SUCCESS if it is successful or a non zero value between OxFFFF0000 and OxFFFFFFFF if it fails ARTIC960 Programmer s Reference OpenDev Open a Subsystem or Device Driver OpenDev Open a Subsystem or Device Driver This service opens a previously registered subsystem or device driver Functional Prototype RIC_ULONG OpenDev char DDName void DDParams RIC_ULONG Size RIC DEVHANDLE DDHandle RIC ULONG Reserved Parameters DDName Input A device name used to create the subsystem or device driver DDParams Input Address of subsystem or device driver defined parameters Size Input Size of subsystem or device driver defined parameters The size of the buffer pointed to by DDParams DDHandle Output Device handle returned to the requesting process This handle is passed to all other services related to subsystem or device driver
219. imerHandler Input Address of timer handler OptionWord Input A set of options for starting the software timer TIMER REPEAT If the constant is ORed with OptionWord the timer is restarted after expiration This occurs until the user stops the timer using StopSw Timer or restarts it with another StartSwTimer TIMER ONE SHOT The timer is not restarted OPTION PROT ON If the constant is ORed with OptionWord and global protection is on memory protection is enabled for the timer handler OPTION PROT OFF The timer handler runs without memory protection TimerMemo Input Optional user defined input Reserved Input Reserved parameter must be 0 Returns RC SUCCESS RC INVALID RESERVED PARM RC INVALID HANDLE RC INVALID MEM ACCESS RC INVALID OPTION RC INVALID TIMEOUT RC NO BASE DEVICE DRIVER 86 ARTIC960 Programmer s Reference StartSwTimer Start a Software Timer Rema rks This service starts a software timer for the requested timer interval unconditionally When the timer expires the kernel gives control to the timer handler TimerMemo as the parameter The timer handler runs as an extension of the kernel interrupt handler Because a timer handler is an interrupt routine care should be taken not to remain in the timer handler for very long If TIM ER RI EP control back from the timer handler of the process The proce
220. ines 173 174 String Handlings memchr strcat memcmp strchr memopy strcmp memmove strcpy memset strcspn Date and Times asctime difftime ctime gmtime strerror strlen strncat strncmp strncpy localtime mktime strpbrk strrchr strspn strstr strtok time 1 Some ANSI C functions cannot be called from interrupt handlers 2 These functions are implemented in libricc a OS 2 and libriccx a AIX along with other kernel services 3 Refer to the ARTIC960 Programmer s Guide for information on using this C function ARTIC960 Programmer s Reference ProcessSleep Sleep Process Miscellaneous Service ProcessSleep Sleep a Process This service blocks a process for the specified length of time Functional Prototype RIC_ULONG ProcessSleep RIC_TIMEOUT Timevalue RIC_ULONG Reserved Parameters Timevalue Input The length of time in milliseconds for the process to sleep Reserved Input Reserved parameter must be 0 Returns RC_SUCCESS RC_INVALID_CALL RC_INVALID_RESERVED_PARM RC_INVALID_TIMEOUT RC_NO_MORE_SEM RC_NO_MORE_TIMERS Remarks This library routine allows users to block for a specified period of time without first creating a semaphore It does the equivalent of creating a semaphore blocking on it for the requested time and then closing the semaphore This routine is contained in the file libricc a Chapter 5 Adapter Library
221. ion 5 Specifies non interactive status mode D dump file Specifies a dump file for dump format mode To specify a dump file with spaces or special characters in the name the name must be enclosed within quotes Quotes within name are not supported If no parameters are specified the default is to prompt for card numbers in interactive live analysis mode rather than to provide help The card number is always interpreted as decimal 224 ARTIC960 Programmer s Reference Status Utility Status Messages and Exit Codes The contents of the message file used by all utilities are listed in Appendix B Message File on page 295 The messages used by the Status utility are listed in Table 6 9 The Status utility also sets its exit code value to indicate the status of the operation The following table correlates the exit code of the Status utility with the utility messages The menus prompts and displays used by the Status utility in interactive mode follow those shown in Status Interactive Messages on page 227 Table 6 9 Status Utility Messages and Exit Codes Message Number Return Code Notes RICO0001 RC UTIL INVALID CMDLINE OPTION RICO0002 RC UTIL INVALID CMDLINE PARM RICO0003 RC UTIL FILE NOT FOUND RIC0004 RC_UTIL_FILE_ACCESS RIC0005 RC_UTIL_INVALID_CARD_NUMBER RIC0010 RC_UTIL_NO_ADAPTER_RESPONSE RIC0016 RC_UTIL_SYSTEM_ERROR RIC0019 RC_UTIL_NOT_INSTALLED
222. ion CREATE CACHE DATA By default the data section is not cached To designate the data section cacheable can be ORed into the option word This option is ignored if data cache hardware is not present on the adapter or if data cache has not been enabled through the kernel configuration DATA CACHE parameter CreateProcess ignores the CREATE CACHE DATA option if the V load module that contains the process issuing the CreateProcess was not itself loaded with the data section cacheable This is because the spawned process shares the data section of the load module ProcessID Output Process ID of the created process Reserved Input Reserved parameter must be 0 Returns RC_SUCCESS RC DUP RES NAME RC INVALID RESERVED PARM RC INVALID MEM ACCESS RC INVALID CALL RC INVALID NAM RC_NO_MORE_PROC RC_INVALID_PRIORITY RC_NO_MORE_MEM RC_INVALID_OPTION RC_NO_MORE_RES Remarks The kernel allocates the stack for the newly created process The size of stack depends on the StackSize parameter passed to the service The newly created process shares the code and data area of the calling process It runs at the priority level set by the creator The newly created process does not inherit the creator s resources exit routine or floating point usage Even if the creator is a subsystem the new process starts as a normal process if the start opt
223. ion Errors These errors are issued when the device driver has encountered errors with interfacing to the hardware abstraction layer HAL ROM Errors The read only memory ROM bootstrap microcode is not responding in reasonable time during initialization or ROM finds a hardware error during its bootstrap initialize or reset Watchdog Timer Interrupt Hard exceptions reported by the ARTIC960 kernel or adapter Informational Various messages indicating starting and stopping of a device or ARTIC960 kernel exceptions 14 ARTIC960 Programmer s Reference ARTIC960 Kernel Services This chapter summarizes the ARTIC960 kernel services and parameter types Summary of Services Table 2 1 lists the modes in which each kernel service can be called The first column lists all the services in the same sequence as they appear in this book The remaining columns define whether the service can be called from an interrupt handler a signal handler an asynchronous event notification handler a process exit routine and a critical section Normal process time is one of the modes that is not in the table because all services can be called at normal process time The other mode that is not in the table is device driver or subsystem call handlers The rules that determine which services can be called are the same as the mode from which the device driver or subsystem was called Each service is described in Chapter 3 Base Kernel Services on page 21 T
224. ion is used The kernel gives control to the newly created process at its entry point with ParamPtr and ParamSize as parameters The new process gets control at main with the arguments parsed into argc and argv if The passed parameters are built up in the creator s data area The passed parameters are in the format of null terminated strings with the last string double null terminated e The label ricstart is passed for the entry point Chapter 3 Base Kernel Services 35 StartProcess Start a Process StartProcess Start a Process This service starts a stopped process Functional Prototype RIC_ULONG StartProcess RIC PROCESSID ProcessID RIC ULONG Reserved Parameters ProcessID Input Process ID of the process that is to be started Reserved Input Reserved parameter must be 0 Returns RC SUCCESS RC INVALID RESERVED PARM RC INVALID PROCESSID RC PROCESS ALREADY START RC INVALID CALL E The kernel starts a previously loaded process The entry point of the process is defined when the process is loaded from the system unit or by the CreateProcess service of the kernel 36 ARTIC960 Programmer s Reference StopProcess Stop a Process StopProcess Stop a Process This service stops a previously started process Functional Prototype RIC_ULONG StopProcess RIC_PROCESSID ProcessID RIC_ULONG Reserved Parameters ProcessID
225. is started 4 The file ric_scb rel is loaded to logical card 0 with ric_scb cfg passed as its parameters Then the process is started Chapter 6 System Unit Utilities 201 Dump Utility Dump Utility The Dump utility dumps the state of the ARTIC960 adapter for diagnostic purposes The Dump utility dumps all of the memory and I O regions of the ARTIC960 adapter address space The Dump utility does not break a dump into pieces across several diskettes The target drive must have the space necessary to capture the entire dump file or the dump fails The Dump utility compresses the dump data to minimize the size of the dump file The Status utility handles dump file decompression The Dump utility does not contain any user prompts which enables it to run unattended The Dump utility has two modes of operation triggered and immediate In multitasking operating systems running the Dump utility in triggered mode requires a dedicated session While running in triggered mode the Dump utility blocks on a triggering mechanism provided by the device drivers Dump Syntax A adar len P PMC_cfgfile T ricdump card num filename path Q path O out file C Figure 6 2 Dump Utility Syntax Q Specifies quiet dump operation Normally the Dump utility displays messages indicating a successful or unsuccessful operation on the standard output device In quiet mode no messages are displayed card_
226. ister a Command Response Mailbox sese QueryProcessStatus Get the Process Status enne nennen UnloadProcess Unload a Process Contents 94 95 96 97 98 100 102 104 106 108 109 110 112 114 115 117 119 120 121 122 125 126 127 128 129 131 132 133 134 136 137 138 139 145 146 147 148 149 150 151 152 153 155 163 164 166 167 168 169 StopProcess Stop a Process StartProcess Start a Chapter 5 Adapter Library Routines ANSI C Functions eeseeeeeeee Miscellaneous Service ProcessSleep Sleep a Process System Bus Interface Services MoveMCData Move System Bus Data ConvertM CToCard Convert System Bus Address to Card Address sss ConvertCardToMC Convert Card Address to System Bus Address sess PCI Local Bus Configuration Device Driver Services ssssessssseeeeeeeeeeen ener pciBiosPresent Query PCI Driver Presence esssssseeeeeeeeeeeneee emen nennen nennen pciFindDevice Find a PCI Device by Vendor and Device ID sese pciFindClassCode Find a PCI Device by PCI Class Code eee pciReadConfigByte Read a Byte from PCI Configuration Space sese pciReadConfigWord Read a
227. iteConfigWord 192 pciWriteConfigDWord 193 These services call a device driver to access PCI devices on the adapter s local PCI bus on the ARTIC960Rx and ARTIC960Hx adapters They are provided by the PCI Device Driver RIC_PCI REL Programs that use the PCI local bus interface services must define the constant INCL_PCI prior to the include lt ric h gt statement to obtain the proper declarations The libraries for these services are contained in the regular kernel services libraries Chapter 5 Adapter Library Routines 183 pciBiosPresent Query PCI Driver Presence pciBiosPresent Query PCI Driver Presence 184 This service determines the presence of the PCI device driver and returns version information and the number of PCI buses in the system Functional Prototype RIC ULONG pciBiosPresent struct PCI BIOS INFO PCI InfoPtr Parameters PCI InfoPtr Input Pointer to the user s structure The PCI parameters are copied into this memory Returns RC SUCCESS RC PCI NO BIOS Remarks struct PCI BIOS INFO RIC_ULONG Options RIC_ULONG DriverVersion RIC_ULONG BIOSVersion RIC_ULONG LastBus RIC_ULONG LocalMemBase RIC_ULONG LocallO Base unsigned char IntPinA Vector unsigned char IntPinB Vector unsigned char IntPinC Vector unsigned char IntPinD Vector Options Reserved parameter currently 0 DriverVersion Version number of the RIC_PCI REL device driver BIOSVersion PCI BIOS versio
228. ks None Chapter 4 Kernel Commands 171 StartProcess Start a Process 172 ARTIC960 Programmer s Reference Adapter Library Routines This chapter lists ANSI C library calls and describes the Miscellaneous Service the System Bus Interface Services and the PCI Services ANSI Functions The following ANSI C library calls are supported by the kernel Use of some functions may require that additional libraries be used Refer to your V compiler documentation for details You can modify your ricproc ld file to include additional libraries Refer to the ARTIC960 Programmer s Guide for information about doing this Character Handling isalnum isgraph isalpha islower iscntrl isprint isdigit Mathematics acos cosh asin exp atan fabs atan2 floor ceil fmod cos frexp Variable Arguments va arg va end Input Output fflush 3 printf2 3 General Utilities abs atol atexit bsearch atof div atoi exitt ispunt isspace isupper Idexp log log10 modf pow sin va start sprintf free malloc qsort rand isxdigit tolower toupper sinh sqrt tan tanh sscanf srand strtod strtol strtoul 1 Some ANSI C functions cannot be called from interrupt handlers 2 These functions are implemented in libricc a OS 2 and libriccx a AIX along with other kernel services 3 Refer to the ARTIC960 Programmer s Guide for information on using this C function Chapter 5 Adapter Library Rout
229. l allocates the requested vector to the calling process as non shared If the vector was previously allocated as non shared RC VECTOR NOT AVAILABLE is returned Refer to the ARTIC960 Programmer s Guide for information about vector sharing Memory protection for an interrupt handler is disabled when global memory protection is disabled regardless of the state of the OptionWord The calling process must be a device driver or subsystem ARTIC960 Programmer s Reference AllocVectorMux Allocate an Interrupt Vector AllocVectorMux Allocate an Interrupt Vector This service allocates an interrupt vector to the calling subsystem or device driver Functional Prototype RIC_ULONG AllocVectorMux RIC_ULONG VectorNum RIC VECTOR MUX EntryPoint RIC ULONG OptionWord RIC ULONG Reserved Parameters VectorNum Input The interrupt vector number to be allocated EntryPoint Input Pointer to the interrupt handling routine for the requested interrupt vector The interrupt handling routine must return a value of 0 if the interrupt was not claimed or a non zero value if the interrupt was claimed OptionWord Input Bit field to describe options Use the OR operation on the following constants to build the appropriate set of options OPTION PROT ON The kernel enables memory protection prior to passing control to the EntryPoint OPTION PROT OFF The kernel does not enable memory protection OPTION VECTOR SHARED Allocates th
230. l as its own code data stack allocated memory and so forth Return codes returned by the InvokeEntry function are passed back to the calling process as the return code of InvokeDev These return codes must be either RC SUCCESS RC INVOKE ENTRY FAILURE or in the range OxFFFF0000 to OxFFFFFFFF Return codes not in this range are discarded and the RC DD RC OUT OF RANGE error is returned Chapter 3 Base Kernel Services 127 AllocVector Allocate an Interrupt Vector AllocVector Allocate an Interrupt Vector 128 This service allocates an interrupt vector to the calling subsystem or device driver Functional Prototype RIC_ULONG AllocVector RIC_ULONG VectorNum RIC_VECTOR EntryPoint RIC_ULONG OptionWord RIC_ULONG Reserved Parameters VectorNum Input The interrupt vector number to be allocated EntryPoint Input Pointer to the interrupt handling routine for the requested interrupt vector OptionWord Input OPTION PROT ON The kernel enables memory protection before passing control to the EntryPoint OPTION PROT OFF The kernel does not enable memory protection Reserved Input Reserved parameter must be 0 Returns RC SUCCESS RC INVALID RESERVED PARM RC INVALID VECTOR RC INVALID OPTION RC NO MORE RES RC VECTOR NOT AVAILABL RC NOT DD OR SS RC INVALID MEM ACCESS RC INVALID CALL Remarks The kerne
231. l parameter The default for this parameter is 7 Values of 5 or less require no additional internal data RAM n 0 Values from 6 to 15 for REG CACHE cause 64 bytes of internal data RAM to be used for each stack frame n REG_CACHE 5 64 the ARTIC960Rx PCI card internal data RAM is not used for register cache growth n 0 Applications can use the range of internal data RAM from 200 to the top n However the kernel does not manage this data area To avoid potential conflicts only applications that take over the card that is do not share the card with other applications can make use of the application internal data RAM area It is not guaranteed that the compatibility of this function will be maintained across future releases Chapter 1 Loading and Configuring 3 Run Time Versus Development Kernel There are two versions of the kernel e ric kern rel runtime ric kdev rel development These versions are supported by the following ARTIC960 programs e ARTIC960 Support for OS 2 Version 1 2 1 e ARTIC960 Support for AIX Version 1 2 or higher e ARTIC960 Support for Windows NT Version 1 0 Either version of the kernel can be loaded onto the adapter by way of the ricload utility The runtime version has limited error checking and no memory protection support Validity checking of most input parameters has been eliminated from kernel service calls Once an application has been debugged this ver
232. lization error 0x002D TERMERR NMI INTERRUPT An NMI interrupt occurred on an ARTIC960Rx adapter 0 002 TERMERR_PLX_INTERRUPT PLX caused an error on an ARTIC960Hx adapter 0x1001 TERMERR_NO_MORE_MEM There is not enough memory left in the internal pools to perform the operation 0x1002 TERMERR_MC_ERR An error occurred on a system bus operation 0x1003 TERMERR NO MORE SEM There is no semaphore available to perform the operation 0x1004 TERMERR NO MORE QUEUES There is no queue available to perform the operation 0x1005 TERMERR NO MORE TIMERS There is no timer available to perform the operation Appendix C Return Error and Exit Codes 325 Kernel Terminal Error Codes Error Code Description 0x1006 TERMERR_DATA_PARITY A data parity error was returned on a system bus operation 0x1007 TERMERR_CHCK A channel check error was returned on a system bus operation 0x1008 TERMERR_CARD_SEL_FDBACK A data card selected feedback error was returned on a system bus operation 0x1009 TERMERR_LOSS_OF_CHANNEL A loss of channel error was returned on a system bus operation 0x100A TERMERR_LOCAL_BUS_ PARITY A local bus parity error was returned on a system bus operation 0x100B TERMERR_EXCEPTION A local exception error was returned on a system bus operation 0x100C TERMERR_TIMEOUT A timeout error was returned on a system bus operation 0x100D TERMERR_PIPE_ACCESS A system bus error was returned while trying to enqu
233. llocation performance but it potentially allows corruption of kernel suballocation data structures Chapter 3 Base Kernel Services 77 FreeSuballoc Free Suballocated Memory FreeSuballoc Free Suballocated Memory 78 This service frees suballocated memory Functional Prototype RIC_ULONG FreeSuballoc void Blockptr void Suballocptr RIC_ULONG Reserved Parameters Blockptr Input Pointer to beginning of suballocation pool Suballocptr Input Pointer to suballocated memory Reserved Input Reserved parameter must be 0 Returns RC_SUCCESS RC_INVALID_RESERVED_PARM RC_INVALID_BASEPTR RC_INVALID_SUBALLOC_ADDR Remarks None ARTIC960 Programmer s Reference GetSuballocSize Return Size of Suballocation Pool GetSuballocSize Return Size of Suballocation Pool This service returns the amount of memory required for a suballocation pool Functional Prototype RIC_ULONG GetSuballocSize RIC_ULONG UnitCount ULONG UnitSize RIC ULONG Alignment RIC ULONG SuballocSize RIC ULONG Reserved Parameters UnitCount Input Number of suballocation blocks in the pool UnitSize Input Size of the smallest block of memory that can be suballocated Larger suballocated memory blocks are suballocated as multiples of this unit The unit size is rounded up to the next power of 2 If the size is 0 RC INVALID SIZE is returned Alignment In
234. logging information during execution Functional Prototype ULONG InitTrace ULONG BufferSize SLONG WrapAroundCount Parameters BufferSize Input Size of the trace buffer in KB WrapAroundCount Input Number of times the trace buffer should do a wrap around before the trace gets disabled Use a value of 1 for infinite A negative value not equal to 1 is invalid Returns RC_SUCCESS RC_INVALID_CALL RC_NO_MORE_MEM RC_NO_MORE_RES RC_INVALID_OPTION Remarks This service allocates memory for the trace buffer and must be called before any call to EnableTrace or DisableTrace If called twice the previous trace buffer is purged and a fresh buffer of size specified in the second call is allocated In this case all the previous logs are lost EnableTrace must be called to enable the logging of the trace data after each call to InitTrace ARTIC960 Programmer s Reference EnableTrace Enable Tracing of Service Classes EnableTrace Enable Tracing of Service Classes This service enables the logging of the trace information for the given set of service classes Functional Prototype RIC ULONG EnableTrace RIC ULONG ParamCount Parameters ParamCount Input Number of service classes being supplied as arguments to EnableTrace Input List of all the service classes separated by commas for which the trace is to be enabled See the Remarks section for de
235. m service OPTION COLLECT PROCESS Unused pages belonging to the dynamic memory pool of the process in execution are returned OPTION COLLECT PROCESS is meaningful only if memory protection is active OPTION COLLECT ALL unused pages in both the general and the process specific dynamic memory pools are returned This is the default FreeUnits Output The number of free units that exist in the dynamic memory pools after the collection is done If OPTION COLLECT PROCESS was used it reflects the number of free units in the dynamic memory pools of the process A unit is 32 bytes FreedPages Output The number of pages in dynamic memory pools that were returned to the Memory Page Pool after the collection is done Returns RC SUCCESS RC INVALID OPTION RC INVALID CALL Remarks This service cannot be called from an interrupt handler If RC NO MORE xxx is returned by a service CollectMem can be issued to make unused pages available Then the service can be retried to determine if enough memory is available ARTIC960 Programmer s Reference Timer Services Timer Services The following are the timer services Service Name Page CreateSwTimer 84 CloseSwTimer 85 StartSwTimer 86 StopSwTimer 88 SetSystemTime 89 QuerySystemTime 90 StartPerfTimer 91 StopPerfTimer 92 ReadPerfTimer 93 Refer to the ARTIC960 Programmer s Guide for additional information Ch
236. mailbox and that system bus access is given for a global mailbox MBX_MEM_MC_ACCESS System bus access rights to the memory MBX_MEM_AIB_ACCESS Daughter card access rights to the memory MbxHandle Output Mailbox handle returned to requesting process This handle is passed to all other mailbox services when this mailbox is referred to SemHandle Output Semaphore handle associated with the mailbox This handle is passed to event services when this mailbox associated semaphore is referred to Reserved Input Reserved parameter must be 0 Returns RC_SUCCESS RC_INVALID_MEM_ACCESS RC_INVALID_RESERVED_PARM RC_INVALID_CALL RC INVALID NA RC NO MORE SEM RC DUP RES NA RC NO MORE TIMERS RC INVALID OPTION RC INVALID COUNT RC NO MORE RES RC INVALID SIZE RC NO MORE ME 1 d Remarks This service creates a semaphore associated with this mailbox The initial semaphore count is set to 0 Users can wait on this semaphore through WaitEvent to receive messages This service also allocates the memory requested by the user This memory is used to keep the messages in the mailbox Optionally a name can be assigned to this memory and the sending process can access this memory by passing the same name to OpenMbx Sharing the memory between sending and receiving processes avoids a copy operation by SendMbx Refer to the ARTIC960 Programmer s Guide f
237. maphore 55 reset utility 2 0 resize allocated memory 69 ResizeMem Reallocate Memory 69 responses common header 65 resume process 40 ResumeProcess Resume a Process 40 return hardware device 36 hardware device status 37 interrupt vector 33 mailbox buffer 285 memory pages 82 size of suballocation pool 79 software timer 85 return codes Configuration utility 209 Get Trace 2 6 listed alphabetically 3 2 listed by values 3 6 loader 99 Set Trace 2 4 system unit API 3 2 3 6 terminal error kernel 325 ReturnHW Return a Hardware Device 7136 ReturnVector Return an Interrupt Vector 33 ric_base rel system executable file RIC_CONFIG structure 290 ric_ess rel system executable file 2 RIC_EXCEPT structure 293 ric_kdev rel system executable file ric kern rel kernel file ric mcio rel system executable file 2 ric oss rel system executable file 2 ric pci rel system executable file 2 ric scb rel system executable file 2 RIC_VERDATA structure 292 RICCLOSE Close a RadiSys ARTIC960 Adapter 266 RICGetConfig Get Configuration Information 272 RICGetException Get Exception Status 274 RICGetVersion Get Version Number 273 RICIOI6 SYS device driver 7 RICLOAD application loader 796 RICOpen Open a RadiSys ARTIC960 Adapter 265 RICRead Read from RadiSys ARTIC960 Memory 267 RICReset Reset a RadiSys ARTIC960 Adapter 271 RICWirite Write to RadiSys ARTIC960 Memory 269 ROM Read Only Memory 3 ROM data s
238. me to assign to the mailbox so other processes can access the same mailbox by name This name also can be NULL The mailbox cannot be shared when MbxName is NULL The kernel s subsystems allocate all resources with the first four characters as RIC_ for the resource name User mailbox names should not start with this prefix MbxRxMemName Input Optional storage area name associated with this mailbox for receiving messages A value of NULL means there is no name associated with the memory and memory cannot be shared MsgUnitSize Input The smallest allocatable message size All messages are allocated in units of this size If the size is 0 RC INVALID SIZE is returned MsgUnitCounpmt Input The maximum number of message units that can be allocated from this mailbox OptionWord Input Bit field to describe the options to be used to create the mailbox The following constants should be ORed together to build the appropriate set of options Type of mailbox to create The caller can create either type MBX CREATE GLOBAL Mailbox accepts messages from other peer units MBX CREATE LOCAL Mailbox does not accept messages from other units 104 ARTIC960 Programmer s Reference CreateMbx Create a Mailbox Type of memory access for storage area The caller can OR the following constants together to specify both types of access to the memory The default is that neither access type is given for a local
239. mmer s Reference RegisterHook Register an Entry Point for a Hook RegisterHook Register an Entry Point for a Hook This service registers an entry point for a hook Functional Prototype RIC_ULONG RegisterHook RIC_HOOKHANDLER EntryPoint RIC_ULONG HookNum RIC_ULONG OptionWord RIC_ULONG Reserved Parameters EntryPoint Input The entry point where the process wants control when it is called from the dispatcher HookNum Input Number of the hook to register Initially only one hook is available HOOK_DISPATCH OptionWord Input If the OptionWord is ORed with HOOK_PREPROCESS the entry point of the process is called before the action If the OptionWord is ORed with HOOK_POSTPROCESS the entry point is called after the action A process can register for preprocessing and post processing in the same call Reserved Input Reserved parameter must be 0 Returns RC_SUCCESS RC INVALID OPTION RC HOOK ALREADY REGISTERED RC INVALID RESERVED PARM RC INVALID MEM ACCESS RC INVALID HOOK RC INVALID CALL Remarks The hook entry point should be defined in this way void HookEntry union HookDataStruc HookData where HookDataStruc is defined as follows union HookDataStruc RIC_PROCESSID ProcessInExec for Dispatch hook Chapter 3 Base Kernel Services 147 DeregisterHook Deregister an Entry Point for a Hook
240. mplementations such as additional error codes and different limits due to word sizes These differences are noted within the function descriptions The following are the mailbox routines Service Page CreateMbx 277 OpenMbx 280 GetMbxBuffer 282 FreeMbxBuffer 283 SendMbx 284 ReceiveMbx 286 CloseMbx 288 Only remote mailboxes are supported mailboxes between a system process and a card process For system process to system process communications the inter process communication features of the operating system can be used Refer to the ARTIC960 Programmer s Guide for additional information on mailboxes 276 ARTIC960 Programmer s Reference CreateMbx Create a Mailbox CreateMbx Create a Mailbox This creates a mailbox and gives access to the requesting process Functional Prototype RIC_ULONG CreateMbx char RIC_SUPTR MbxName char RIC_SUPTR MbxRxMemName RIC_ULONG MsgUnitSize RIC_ULONG MsgUnitCount RIC_ULONG OptionWord RIC_MBXHANDLE RIC_SUPTR MbxHandle RIC_SEMHANDLE RIC_SUPTR SemHandle RIC_ULONG Reserved Parameters MbxName Input A mailbox name to assign to the mailbox so other processes can get access to the same mailbox by name MbxRxMemName Input Optional storage area name associated with this mailbox for receiving messages A value of null means that there is no name associated with the memory and memory cannot be shared MsgUnitSize Input
241. mption ARTIC960 Programmer s Reference Dispatch Cause a Dispatch Cycle Dispatch Cause a Dispatch Cycle This service causes a dispatch cycle Functional Prototype RIC_ULONG Dispatch void Returns RC_SUCCESS RC_INVALID_CALL Remarks This service cannot be called from an interrupt handler Chapter 3 Base Kernel Services 49 Process Synchronization Services Process Synchronization Services 50 Process synchronization is accomplished through semaphores and events Semaphores are the post wait mechanism for all processes and come in two types mutual exclusion and counting semaphores e Mutual exclusion mutex semaphores are used for serializing access to code or data structures e Counting semaphores are used for synchronizing processes such as synchronizing a producer consumer pair of processes Semaphores can be explicit or implicit e Explicit semaphores are decremented before control returns to the process e Implicit semaphores are decremented when the process calls the appropriate resource services such as removing a queue element or mailbox message Processes can allocate and manipulate semaphores using the following services Service Name Page CreateSem 51 OpenSem 52 CloseSem 53 ReleaseSem 54 RequestSem 55 QuerySemCount 56 SetSemCount 57 CreateEvent 58 OpenEvent 59 CloseEvent 60 WaitEvent 61 Refer to the ARTIC960 Programmer s Guide for
242. n e isMCA e isPCI e isMIAMI e isMP2P e isRXD For example RIC_CONFIG ConfigData isMCA amp ConfigData F Appendix A Structure Definition 291 RIC_VERDATA Structure RIC_VERDATA Structure The following is the structure definition for RIC_VERDATA version numbers of the installed ARTIC960 software typedef struct RIC_Version union RIC_ULONG CombinedVer struct RIC SeparateV SeparateVer Driver union RIC ULONG CombinedVer struct RIC SeparateV SeparateVer Lib union RIC ULONG CombinedVer struct RIC SeparateV SeparateVer Kernel union RIC ULONG CombinedVer struct RIC SeparateV SeparateVer BaseSS union RIC_ULONG CombinedVer struct RIC SeparateV SeparateVer MChanSS union RIC_ULONG CombinedVer struct RIC SeparateV SeparateVer SCBSS VERDATA 292 ARTIC960 Programmer s Reference RIC EXCEPT Structure RIC EXCEPT Structure The following is the structure definition for EXCEPT the exception conditions for the ARTIC960 adapters struct RIC_Except RIC_ULONG RIC_ULONG union struct RIC_Asy struct RIC_Inv struct RIC_Dat struct RIC_Ker struct RIC MBX struct RIC SCB struct RIC MCE struct RIC RPE struct RIC HxE ExceptionData H ExceptionCode ExceptionDataSize ncEvent alid_Intr a_Corrupt n Init Errinfo ErrInfo rrinfo rrinfo rrinfo EventInfo Invintr BadData Kern
243. n CardNum number NumCards Number of ARTIC960 cards in the configuration CardType Type of adapter card Provides information about the type of bus the presence of data cache and the type of interface chip The following masks can be used to determine CardType information RIC CARD TYPE Indicates the type of bus Possible values are RIC MCA Micro Channel RIC PCI PCI Peripheral Component Interconnect RIC DCACHE Indicates the presence of a data cache Possible values are Data cache hardware is not present Data cache hardware is present RIC IF CHIP Indicates the type of interface chip Possible values are RIC MIAMI Miami RIC_MP2P Miami PCI to PCI RIC_RP 1960RP RxD 1960RxD Masterl Version Version of ARTIC 32 bit Memory Controller Chip Master2 Version Version of system bus Interface Chip Master3 Version Version of CFE Local Bus AIB Interface Chip Reserved Reserved field Chapter 3 Base Kernel Services 29 QueryCardinfo Get the Card Configuration Information BaseCardVersion Base card version ROSVersion ROS version MemRegions Number of memory regions MemBase Base address of memory region MemTotal Size in bytes of memory region MemType Type of memory region Possible values are MEM TYPE INSTRUCTION MEM TYPE PACKET 30 ARTIC960 Programmer s Reference QueryConfigParams Get the Configuration Parameters QueryConfigParams G
244. n number compatible LastBus Number of the last PCI bus on the adapter LocalMemBase Local bus base address for i960 access to PCI device memory see LocalIO Base for more information ARTIC960 Programmer s Reference pciBiosPresent Query PCI Driver Presence LocallO_Base Local bus base address for 1960 access to a PCI device memory mapped I O The LocalMemBase and LocalIO Base values are used as a base address when accessing a PCI device from the 1960 These values should be added to the physical address read from a PCI device base address register to obtain a local 1960 address for accessing the device The LocalMemBase value should be used for memory base address registers and the LocallO Base value should be used for accessing memory mapped I O base address registers IntPinA Vector IntPinB Vector IntPinC Vector IntPinD Vector PCI interrupt pin vector assignments Normally the interrupt line configuration register for the device should be read to determine the vector The IntPin information is provided for deviant PMCs Chapter 5 Adapter Library Routines 185 pciFindDevice Find a PCI Device by Vendor and Device ID pciFindDevice Find a PCI Device by Vendor and Device ID 186 This service finds the PCI device that is specified by the vendor and device ID Functional Prototype ULONG pciFindDevice PCI DEVICE ID DevicelID PCI VENDOR ID VendorID PCI INSTANCE Instance PCI I
245. n page 254 for an example C gt Enter adapter number gt Name Type SSSSSSSSSSSSSSSS 555555555 Press Enter to continue NC Figure 6 20 Status Utility Resource Summary Display Chapter 6 System Unit Utilities 231 Status Interactive Messages 232 The following screen shows the prompts and items displayed when the Memory option is chosen from the main menu e The address of the card can be specified by the local card address or the memory name e By entering a B or W at the prompt the data can be displayed two different ways byte mode or word mode Ifthe byte mode B is chosen the three groups displayed are Address Hexadecimal value of each byte ASCII representation of each byte if the character is not a printable character a period is displayed Ifthe word mode W is chosen the two groups displayed are Address Hexadecimal value of each word e If the address was previously entered and a NULL value was entered at the memory address prompt the Status utility continues to display the memory e The output line is repeated as necessary to display all data See Figure 6 47 on page 254 for an example Enter adapter number gt Enter Address Name Length B W Or 0 to Return gt aaaaaaaa hh hh hh hh hh hh hh hh hh hh hh hh hh hh hh hh CCCCCCCCCCCCCCCC OR aaaaaaaa hhhhhhhh hhhhhhhh hhhhhhhh hhhhhhhh Figure 6 21 Sta
246. n the ProcessRev field on the CompleteInit system call ProcessType Returned by the kernel It can be one of the following types PROCESS_TYPE_NORMAL PROCESS_TYPE_DEVDRV PROCESS_TYPE_SUBSYS Priority Indicates the current execution priority for this process MemProtState Defines the state of memory protection M M EMPRO EMPRO ENABLE Memory protection enabled DISABLE Memory protection disabled ARTIC960 Programmer s Reference QueryProcessStatus Get the Process Status Primary Process State Bits The primary process state bits are shown in the following table State bit Description LOADED The LOADED bit is set while a process is being loaded and is reset when the loading operation is complete PROC_STOPPED The PROC_STOPPED bit is set when a process has been loaded and is reset when it is unloaded by the system unit or another process STARTED The STARTED bit is set when a process is started and is reset when it is stopped by the system unit or another process STOPPING The STOPPING bit is set when the exit handler of a process is running Secondary Process State Bits Processes that are in the started or stopping states have a valid secondary state as defined in the following table State Description SUSPENDED The SUSPENDED bit is set when the process has been suspended The process is taken off the di
247. ndicate the status of the dump operation The following table correlates the exit code of the Dump utility with the dump messages Table 6 2 Dump Utility Messages and Exit Codes Message Number Exit Code Notes RICO0001 RC UTIL INVALID CMDLINE OPTION RIC0002 RC UTIL INVALID CMDLINE PARM RICO003 RC UTIL FILE NOT FOUND RIC0004 RC UTIL FILE ACCESS RICO005 RC UTIL INVALID CARD NUMBER RIC0010 RC UTIL NO ADAPTER RESPONSE RICOO 1 1 None Information only message RIC0012 RC_UTIL_SUCCESS Successful dump completion RIC0013 None Information only message RIC0014 RC UTIL SUCCESS Successful dump cancellation RIC0015 RC_UTIL_NOT_PENDING RIC0016 RC_UTIL_SYSTEM_ERROR RIC0019 RC_UTIL_NOT_INSTALLED RIC0028 RC_UTIL_WRNHELP_GIVEN RIC0038 RC UTIL ACCESS ERROR RICO040 RC UTIL ALREADY STARTED RIC0056 None Information only message RIC0075 RC UTIL INVALID CMDLINE OPTION RIC0080 RC UTIL UNSUPPORTED OPTION Warning message RICO0082 RC UTIL UNSUPPORTED Warning message HARDWARE RIC0083 RC UTIL DUMP PROCESS ERROR RIC0084 None RICO085 RC UTIL SUCCESS Successful PMC dump completion RICO086 RC UTIL DUMP CONFIG ERROR RIC0087 RC UTIL PARM SYNTAX ERROR Syntax for parameters incorrect 206 ARTIC960 Programmer s Reference Configuration Utility Configuration Utility The Subsystem Control Block SCB Logical I O Architecture specifies how unit
248. nformation Kernel Trace Information The following tables indicate the procedures that are traced when a particular service class is enabled They also indicate the contents of the trace records associated with each procedure Service Class Page C_ASYNC_EVENT_SERVICE 156 C_DEVICE_DRIVER_SERVICE 156 C_HOOK_SERVICE 157 C_INTERRUPT_SERVICE 157 C KERN COMMANDS SERVICE 157 MAILBOX SERVICE 158 C MEMORY SERVICE 158 C PROCESS SERVICE 159 C MEMPROT SERVICE 160 C QUEUE SERVICE 160 C SEMAPHORE SERVICE 160 C SIGNAL SERVICE 161 C SUBALLOC SERVICE 161 C SWTIMER SERVICE 161 C TIMER SERVICE 162 C CLIB 162 Chapter 3 Base Kernel Services 155 Kernel Trace Information Table 3 1 Service Class C ASYNC_EVENT_SERVICE Trace Format of Procedure ID Kernel Service Position Trace Data Data P_REGISTER_ASYNC_HNDLER RegisterAsyncHandler Entry SoftwareEvents integer AdapterEvents integer ProcessorEvents integer AsyncHandler integer Exit rc integer P_DEREGISTER_ASYNCH_ DeregisterAsyncHandler Entry SoftwareEvents integer HNDLER AdapterEvents integer ProcessorEvents Exit rc Table 3 2 Service Class C DEVICE DRIVER SERVICE Trace Format of Procedure ID Kernel Service Position Trace Data Data P SETVECTOR SetVector SetVectorMux Entry VectorNum integer Exit rc integer P ALLOCVECTOR AllocVector AllocVectorMux Entry
249. ng to this event Reserved Input Reserved parameter must be 0 Returns RC SUCCESS RC INVALID NAME RC NAME NOT FOUND RC INVALID HANDLE RC NO MORE RES RC INVALID MEM ACCESS RC INVALID RESERVED PARM RC INVALID CALL Remarks The calling process must have already opened the semaphores that make up the event Chapter 3 Base Kernel Services 59 CloseEvent Release Access to an Event Word CloseEvent Release Access to an Event Word 60 This service releases access to an event word and deletes the event if no other processes have access Functional Prototype RIC_ULONG CloseEvent RIC_EVNHANDLE EvnHandle RIC_ULONG Reserved Parameters EvnHandle Input Event handle returned by CreateEvent service Reserved Input Reserved parameter must be 0 Returns RC SUCCESS RC INVALID HANDLE RC INVALID RESERVED PARM RC INVALID CALL Remarks If a process closes an event that is shared with other processes this service removes access rights for the caller only Only when the last process closes the event does the event cease to exist ARTIC960 Programmer s Reference WaitEvent Wait an Event WaitEvent Wait on an Event This service waits for the requesting process until the event occurs Functional Prototype RIC_ULONG WaitEvent RIC_EVNHANDLE EvnHandle RIC_ULONG Mask RIC_ULONG OptionWord R
250. nsigned char Value Parameters pcuD Input The PCI device identifier obtained by way of either the pciFindDevice or pciFindClassCode service RegNum Input The register number to be read normally 0 to 255 Value Input The byte to be written Returns RC SUCCESS RC PCI NO BIOS RC PCI BAD REGISTER NUMBER Remarks None Chapter 5 Adapter Library Routines 191 pciWriteConfigWord Write Word to PCI Configuration Space pciWriteConfigWord Write a Word to PCI Configuration Space 192 This service writes one 16 bit word to the device PCI configuration space Functional Prototype RIC_ULONG pciWriteConfigWord PCI_ID pciID PCI REG NUM RegNum RIC_USHORT Value Parameters pciD Input The PCI device identifier obtained by way of either the pciFindDevice or pciFindClassCode service RegNum Input The register number to be read normally 0 to 255 The register number must be evenly divisible by 2 Value Input The word to be written Returns RC SUCCESS RC PCI NO BIOS RC PCI BAD R Remarks None EGIST ER NUMBI ARTIC960 Programmer s Reference ER pciWriteConfigDWord Write a Doubleword to PCI Configuration Space pciWriteConfigDWord Write a Doubleword to PCI Configuration Space This service writes one 32 bit doubleword to the device PCI configuration space Functional Prototype RIC ULONG pciWriteConfigDWord PCI ID pciID PC
251. nteractive Messages 1 Device Driver Resource Details Submenu The following screen shows the prompts and items displayed when a device driver is selected from the Resource details submenu The entries in the Access list fields show all processes that have access to the resource See Figure 6 54 on page 257 for an example Enter adapter number gt Enter resource name or handle gt Resource type driver Driver name SSSSSSSSSSSSSSSS Process name SSSSSSSSSSSSSSSS Protection SSSSSSSSS Access list Proc No Process Name Handle nnnnnnnn SSSSSSSSSSSSSSSS nnnnnnnn M Figure 6 29 Device Driver Detail Display 240 ARTIC960 Programmer s Reference Status Interactive Messages 2 Event Resource Details Submenu The following screen shows the prompts and items displayed when an event is selected from the Resource details submenu The entries in the Semaphores field show each semaphore in the event The entries in the Access list fields show all processes that have access to the resource See Figure 6 55 on page 257 for an example C N Enter adapter number gt Enter resource name or handle gt Resource type event Name SSSSSSSSSSSSSSSS Semaphores SSSSSSSSSSSSSSSS SSSSSSSSSSSSSSSS Access list Proc No Process Name Handle nnnnnnnn SSSSSSSSSSSSSSSS nnnnnnnn Ke A Figure 6 30 Event Detail Display Chapter 6 System Unit Utilities 241 Status Interactive Messages
252. num Specifies the logical card number to be dumped filename Specifies the file into which the raw dump data is to be dumped If the file already exists it is overwritten Specifies an I O region to be dumped This option can be repeated up to four times This option is not supported on the ARTIC960Rx PCI adapter addr Address of an I O region to be dumped No validity checking is done on this address len Length of an I O region to be dumped No validity checking is done on this length P cfgfile Specifies a PMC region to be dumped Specifies that the configuration file PMC_cfgfile contains a list of addresses and lengths to dump Each line in the configuration file is treated as an individual dump request 202 ARTIC960 Programmer s Reference Dump Utility O out file The PMC_cfgfile can contain up to 31 lines of information The following is an example of this configuration file The first parameter in each line is the address to be dumped and the second parameter is the amount of data to dump 0 1 1000 40 0 1 02000 0x28 If an error is encountered during the processing of the configuration file the dump operation is terminated and the remaining entries are not processed This option is not supported on ARTIC960 MCA and ARTIC960 PCI adapters Specifies that the dump output from P option is written to a binary file named out_file If out_file is not specified the default file pmcdump bin is
253. o a slot before an already defined ARTIC960 adapter it is assigned the next consecutive logical number Handle is only valid to use within the process that opened it There is no thread support e The error RC SU OPEN FAILED is returned if the device driver 15 not installed RC INVALID CARD NUMBER is returned if the card number is out of range 0 6 for OS 2 and Windows NT and 0 13 for AIX Chapter 7 System Unit APIs 265 RICClose Close an ARTIC960 Adapter RICClose Close ARTIC960 Adapter 266 This routine is used to terminate access to an individual ARTIC960 adapter Functional Prototype RIC_ULONG RICClose RIC_HANDLE Handle RIC_ULONG Reserved Parameters Handle Input The handle to be closed Reserved Input Reserved parameter must be 0 Returns RC_SUCCESS RC_INVALID_RESERVED_PARM RC_SU_INVALID_HANDLE Remarks An application calls this routine to return a handle when it is no longer needed to access the adapter ARTIC960 Programmer s Reference RICRead Read from ARTIC960 Memory RICRead Read from ARTIC960 Memory This routine is used to read data from memory on an ARTIC960 adapter into system memory Functional Prototype RIC_ULONG RICRead RIC_HANDLE Handle RIC_PTR SrcBuffer void DestBuffer RIC_ULONG BufferLen RIC ULONG OptionWord Parameters Handle Input The handle for the ARTIC960 adapter SrcBuffe
254. oc Suballocate Memory see FreeSuballoc Free Suballocated GetSuballocSize Return Size of Suballocation Pool MallocMem Allocate Memory eee FreeMem Free Memory eese CollectMem Collect Memory eene Timer SOL VICES iiec RE Se EE ee e CreateSwTimer Allocate a Software Timer CloseSwTimer Return a Software Timer StartSwTimer Start a Software Timer esses StopSwTimer Stop a Software Timer esses SetSystemTime Set the Time of Day Clock QuerySystemTime Get the Time of StartPerfTimer Start the Performance Timer StopPerfTimer Stop the Performance ReadPerfTimer Read Current Time of the Performance Timer ARTIC960 Programmer s Reference 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 63 64 67 68 69 70 71 72 73 74 75 77 78 79 80 81 82 83 84 85 86 88 89 90 91 92 93 Process Communication Services CreateQueue Create a Queue OpenQueue Open a Queue CloseQueue Close a Queue PutQueue Put an Element into a
255. ollowed by a 16 byte block of 00s 00100000 30 31 32 33 34 35 36 37 41 42 43 44 61 62 63 64 01234567ABCDabcd 00100010 OD 24 23 40 21 00 00 00 00 00 00 61 61 61 61 80 aaaa 00100020 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 gt 00101400 Pb FF FF FF FF FF FF FF FF 00101410 61 20 64 75 6D 6D 79 20 70 61 74 74 65 72 6E 20 dummy pattern gt 00102000 FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF gt 00102100 01 01 01 01 01 01 01 01 30 30 30 30 31 31 31 31 00200000 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 Figure 6 16 Sample Formatted Dump ARTIC960 Programmer s Reference Status Interactive Messages Status Interactive Messages The following figures depict all of the menus prompts and displays of the Status utility in interactive mode In these figures e All displayed values are in hexadecimal e All numeric prompts are assumed to be hexadecimal unless preceded by 0 e The full hexadecimal width of numerical values is always displayed e Ifa default adapter number is passed on the command line the Enter adapter number prompt does not appear and the default is used When responding to interactive prompts any invalid data entering Z at an adapter number prompt for example causes the invalid input message to be displayed followed by a re prompt for data When displaying data the status utility keeps track of the number of
256. on about the loaded task Displayed information includes the address of the task s entry point code segment data segment BSS segment stack address and parameter address S process Specifies that the process previously loaded is to be started U process name Specifies that the process should be unloaded To specify either a config filename filename process name or arg filename with spaces or special characters in the name the name must be enclosed within quotes This allows support of the OS 2 high performance file system HPFS The text files processed by the Application Loader config filename and arg filename are processed as a text stream The ANSI C end of line and end of file sequence translation rules apply to these files Blank lines and comments in configuration files are ignored 198 ARTIC960 Programmer s Reference Application Loader ricload Utility Application Loader Messages and Exit Codes The contents of the message file used by all utilities are listed in Appendix B Message File on page 295 The messages used by the Application Loader are listed in Table 6 1 The Application Loader also sets its exit code value to indicate the status of the load operation The following table correlates the exit code of the Application Loader with the Application Loader messages Table 6 1 Application Loader Messages and Return Codes Message Number Exit Code Notes RIC0001
257. on the type of processor in use INST CACHEZYES NO Instruction cache enable PIN KERN PROC CODE YESINO When YES kernel code that is critical for process intensive applications is pinned in instruction cache if instruction cache is enabled PIN KERN INT CODE YES NO When YES kernel code that is critical for interrupt intensive applications is pinned in instruction cache if instruction cache is enabled PEER TIMEOUT 5 Timeout value used by the kernel mailbox subsystem when communicating with peer processes Valid values are 0 to 60 seconds A value of 0 means that the timeout will be disabled Timer Notes For ARTIC960 and ARTIC960 PCI adapters you can request the kernel to leave the timeslice timer watchdog timer time of day timer or performance timer available for a user process If TIME IME OF DAYZNO or PERFORMANC T SLICE INTERVAL O WATCHDOG INTERVAL 0 E TIMER NO the kernel does not allocate the indicated timer The timer can be allocated by a user process For ARTIC960Rx PCI and ARTIC960Hx PCI adapters you can request the kernel to leave TIMERO available for a user process If TIME SLICE INTERVAL O and P ERFORMANCI E TIMI allocated by a user process ER NO the kernel will not allocate TIMERO The timer can be Chapter 1 Loading and Configuring 5 Subsystems Configuration e Base Device Driver There a
258. only within the process that obtained it There is no thread support Chapter 7 System Unit APIs 279 OpenMbx Open a Mailbox OpenMbx Open a Mailbox 280 This opens a mailbox previously created by another process Functional Prototype RIC_ULONG OpenMbx char RIC_SUPTR MbxName char RIC_SUPTR SendMbxMemName RIC_ULONG MsgUnitSize RIC_ULONG MsgUnitCount RIC_ULONG OptionWord RIC_MBXHANDLE RIC_SUPTR MbxHandle RIC_ULONG RIC_SUPTR MbxType RIC_ULONG Reserved Parameters MbxName Input The mailbox name used to create the mailbox SendMbxMemName Input Optional storage area name associated with the mailbox for sending messages by this process A value of NULL means that the memory cannot be shared Refer to the ARTIC960 Programmer s Guide for information about mailbox memory options MsgUnitSize Input The smallest allocatable message size All messages are allocated in units of this size If the size is 0 RC INVALID SIZE is returned MsgUnitCount Input The maximum number of messages that can be allocated from this mailbox OptionWord Input Bit field to describe the options to be used to open the mailbox The following constants should be ORed together to build the appropriate set of options Search option for finding mailbox MBX OPEN SEARCH GLOBAL Other cards are searched if the mailbox does not exist on card Because the system unit supp
259. or corrupted 324 ARTIC960 Programmer s Reference Kernel Terminal Error Codes Kernel Terminal Error Codes Error Code Description 0x0020 TERMERR_MC_IO_FAIL System bus IO subsystem failure 0x0021 TERMERR SCB FAIL SCB subsystem failure 0x0022 TERMERR EXTMAIL FAIL External mailbox failure 0x0023 TERMERR INVALID INTR Hardware interrupt occurred No second level handler was installed 0x0024 TERMERR WATCHDOG Watchdog timeout 0x0025 TERMERR PARITY A parity error has occurred It is one of the following multiple bit ECC error AIB bus read parity error with 80960 master and local bus parity for ARTIC960 32 bit Memory Controller Chip system bus Interface Chip and CFE Local Bus AIB Interface Chip 0x0026 TERMERR MEM PROCESSOR Memory protection violation with 80960 master occurred at interrupt time 0x0027 TERMERR MEM MICROCHANNEL Memory protection violation with system bus master 0x0028 TERMERR MEM AIB Memory protection violation with AIB master 0x0029 TERMERR ASYNC NO MORE RES No more async event resources could be allocated because the internal pools are exhausted The event cannot be processed 0x002A TERMERR PROCESSOR Program has attempted to perform an illegal operation on an architecture defined data type or a typed data structure 0x002B TERMERR DATA CORRUPTION The kernel found its internal data structures corrupted 0x002C TERMERR KERNEL INIT Kernel initia
260. or more information about mailbox memory options Optionally mailboxes can accept messages from other peer units The processes on other units can access this mailbox using OpenMbx Only the process that created the mailbox with the CreateMbx service can receive messages from the mailbox If the process is sharing the receive memory of the mailbox with a previously created mailbox the MsgUnitSize and MsgUnitCount parameters must be the same value on both create calls If the mailbox receives messages from other units the kernel ensures system bus access has been enabled for the mailbox s pool Mailbox memory areas are allocated from packet memory If there is not enough packet memory to allocate the buffer the RC NO MORE MEM error is returned If a mailbox is not going to be accessed from off card it should be created with the MBX CREATE LOCAL option Chapter 3 Base Kernel Services 105 OpenMbx Open a Mailbox OpenMbx Open a Mailbox 106 This service opens a mailbox previously created by another process Functional Prototype RIC_ULONG OpenMbx char MbxName char SendMbxMemName RIC ULONG MsgUnitSize RIC ULONG MsgUnitCount RIC ULONG OptionWord RIC MBXHANDLE MbxHandle RIC ULONG MbxType ULONG Reserved Parameters MbxName Input A mailbox name used to create the mailbox SendMbxMemName Input For local mailboxes an optional storage area name associated with the
261. or preemption An interrupt handler cannot disable preemption The following situation forces a critical section to end If 1 interrupts or preemption is disabled and 2 a process calls a kernel service that causes the process to block interrupts and preemption are automatically enabled This allows the block to proceed In other words a blocking call ends a critical section Chapter 3 Base Kernel Services 47 ExitCritSec Exit Critical Section ExitCritSec Exit Critical Section This service enables interrupts and or preemption 48 Functional Prototype RIC ULONG ExitCritSec RIC ULONG OptionWord Parameters OptionWord Input RIC ULONG Reserved ENABLE INTE If ORed i RRUPTS nto the OptionWord interrupts are enabled the default is not to change the interrupt state ENABLE PREE MPTION If ORed into the OptionWord preemption is enabled the default is not to change the preemption state Failure to select either option causes an RC INVALID OPTION to be returned Reserved Input Reserved parameter must be 0 Returns RC SUCCESS RC INVALID RESERV ED PARM RC INVALID CALL RC INVALID OPTION Remarks The number of calls to enabl e interrupts must match the number of calls to disable interrupts similar to pushes and pops of a stack The same is true of preemption An interrupt handler cannot enable pree
262. or the ARTIC960 Support for AIX Version 1 1 3 0 or higher this parameter is ignored The System Bus I O Subsystem always runs with its memory protection disabled USERCHANNUM 1 2 Channel number of the channel to be reserved for the user It can be set to 1 or 2 The default is no channel is reserved for the user 6 ARTIC960 Programmer s Reference ARTIC960 Support for OS 2 The following sections describe the ARTIC960 Support for OS 2 Supported ARTIC960 Configurations The ARTIC960 adapter supports a wide variety of configurations such as interrupt levels I O addresses and system bus memory configurations ARTIC960 32 bit Support for OS 2 supports all configurable adapter options with the following restrictions Interrupt level All configurable interrupt levels are supported I O address configurable base I O addresses are supported 8 16 KB memory window ARTIC960 Micro Channel only This memory window is not used by the 32 bit OS 2 support Its presence and location do not affect operation 8 KB memory mapped ARTIC960 PCI and ARTIC960Hx This memory window is not used by the 32 bit OS 2 support Its presence and location do not affect operation Full memory window Under OS 2 the system unit driver does not require or use direct access to the full memory window to communicate with an ARTIC960 adapter except for ARTIC960Rx However the full memory window must be mapped onto the system bus to support
263. orts only remote mailboxes the MBX OPEN SEARCH LOCAL option local cards are searched is ignored Mailbox buffer pinning option ignored in AIX The caller can have the memory associated with mailbox buffers permanently pinned down with a parameter value of MBX PIN MI EMORY If this option is not selected memory is pinned only for as long as absolutely necessary This option applies only when memory is allocated by this OpenMbx call ARTIC960 Programmer s Reference OpenMbx Open a Mailbox MbxHandle Output The mailbox handle returned to the requesting process This handle is passed to all other mailbox services when referring to this mailbox MbxType Output Type of mailbox that was opened The MbxType field can return the following value MBX_TYPE_REMOTE The mailbox is not local Because the system unit supports only remote mailboxes the following options are ignored e MBX TYPE LOCAL the mailbox is local but does not accept remote messages MBX_TYPE_GLOBAL the mailbox is local and accepts card messages Reserved Input Reserved parameter must be 0 Returns RC_SUCCESS RC NO MBX PROCESS RC DUP RES NAME RC NO MORE MBX RC INVALID COUNT RC NO MORE MEM RC INVALID NAME RC NO MORE REM MBX RC INVALID OPTION RC NO MORE RES RC INVALID RESERVED PARM RC NO MORE RES ON REM
264. osition RIC_ULONG TraceOption RIC_ULONG DataSize void Address Parameters ServiceClass Input Identifies the class of the calling procedure and decides whether the trace is to be logged as set by EnableTrace and DisableTrace calls The range is from 0 to 255 Range 0 to 127 is reserved for the kernel and its subsystems However the kernel does not perform checking to enforce the reserved range ProcedureID Input Identifies the procedure in the given service class The ServiceClass and the ProcedureID together form a unique identification for any procedure Range is from 0 to 255 CallerPosition Input Provides information regarding the position of the caller inside the procedure The following values are supported TRACE ENTRY To mark the entry into any procedure RACE EXIT To mark the exit from any procedure Values 0x00000001 to OxFE To mark different positions inside any procedure TraceOption Input Decides what is to be logged and how it is displayed after formatting by RICFMTTR You can OR more than one option together to form a TraceOption If both TRACE INT and TRACE CHAR are used the data is displayed in both forms in two consecutive trace records RACE IN Take the data from Address and display as integers TRACE CHAR Take the data from Address and display in hexadecimal and ASCII RACE NOINFO No data is associated with this trace record C
265. ot registered 0x00010E01 RC INVALID CMD DEST The destination process ID for the command is invalid 0x00010E02 RC CMD NOT DELIVERED The command could not be delivered to the destination process 0x00010E03 RC INVALID COMMAND The command is invalid 0x00010F01 RC HOOK ALREADY REGISTERED The hook has already been registered by the calling process 0x00010F02 RC HOOK NOT REGISTERED The process is trying to deregister a hook that it has not registered 0x00010F03 RC INVALID HOOK The process is trying to register an invalid hook 0x00010F04 RC NO MORE HOOKS All available hooks are already registered 322 ARTIC960 Programmer s Reference Return Codes Listed Numerically Return Code Description 0x00011001 RC_TRACE_NOT_INITIALIZED A call to EnableTrace or DisableTrace was made without a successful call to InitTrace LogTrace specified a service class that was not enabled 0x00011002 RC INVALID SERVICECLASS The range of valid service classes is from 0 to 255 0x0001 1003 RC INVALID PROCEDURE ID The Procedure ID specified is not valid for the service class 0x0001 1004 RC INVALID CALLER POSITION The caller position is not within the valid range of values 0x0001 1101 RC SCB INIT ERROR The reply to an Initialize SCB Pipe command is responding with an error element 0x0001 1102 RC ENTITY NOT FOUND The named entity was not found on the remote unit 0x0001 1201 RC BAD C
266. other process with the CreateSem service 52 ARTIC960 Programmer s Reference CloseSem Close a Semaphore CloseSem Close a Semaphore This service releases access to a semaphore and deletes the semaphore if no other processes have access Functional Prototype RIC_ULONG CloseSem RIC_SEMHANDLE SemHandle RIC_ULONG Reserved Parameters SemHandle Input Handle of semaphore to release Reserved Input Reserved parameter must be 0 Returns RC_SUCCESS RC_INVALID_HANDL RC_INVALID_RESERVED_PARM RC_DEPENDENT_EVENTS RC_INVALID_CALL Lr Remarks If the close is issued by a process while other processes still have access to the semaphore the service removes access rights for the issuing process When the last process with access rights calls this service the semaphore ceases to exist See CreateSem Create a Semaphore on page 51 and OpenSem Open a Semaphore on page 52 for more information If a process is stopped or unloaded the kernel closes all of its resources It notifies through asynchronous notification all other processes that shared those resources that the process has gone away If a process closes a mutual exclusion semaphore that it owns that is it requested the semaphore last but has not released it all processes waiting for the semaphore are awakened with an error of RC OWNER CLOSED SEM This is done because the code and data protected by
267. ototype RIC_ULONG RICReset RIC HANDLE Handle RIC ULONG Reserved Parameters Handle Input The handle for the ARTIC960 adapter Reserved Input Reserved parameter must 0 Returns RC SUCCESS RC INVALID RESERVED PARM RC NO ADAPTER RESPONSE RC RESET FAI RC SU INVALID HANDLE RC SYSTEM ER Remarks This routine resets the adapter and aborts any pending RICRead RICWrite SendMbx or ReceiveMbx commands for the adapter In addition the SCB configuration for the adapter is lost during the reset Chapter 7 System Unit APIs 271 RICGetConfig Get Configuration Information RiCGetConfig Get Configuration Information 272 This routine is used to obtain specific hardware configuration information that is otherwise unavailable at the application level Functional Prototype RIC ULONG RICGetConfig RIC HANDLE Handle RIC ULONG ConfigLen RIC CONFIG ConfigData ULONG Reserved Parameters Handle Input The handle for the ARTIC960 adapter ConfigLen Input The length of the buffer provided for the returned configuration information The length must be less than 64 KB for OS 2 and Windows NT ConfigData Input The address of a buffer in system unit memory to receive the configuration information This is a 32 bit logical address Reserved Input Reserved parameter must be 0
268. otype for the EntryPoint must be RIC_ULONG EntryPoint RIC_ULONG VectorNum Returns Must return 0 if the interrupt was not claimed or non zero if the interrupt was claimed ARTIC960 Programmer s Reference ReturnVector Return an Interrupt Vector ReturnVector Return an Interrupt Vector This service returns a previously allocated interrupt vector Functional Prototype RIC_ULONG ReturnVector RIC_ULONG VectorNum RIC_ULONG Reserved Parameters VectorNum Input Vector number of vector returned by this service Reserved Input Reserved parameter must be 0 Returns RC_SUCCESS RC_INVALID_RESERVED_PARM RC_VECTOR_NOT_ALLOCATED RC_INVALID_VECTOR RC_INVALID_CALL Remarks None Chapter 3 Base Kernel Services 133 AllocHW Allocate a Hardware Device AllocHW Allocate a Hardware Device 134 This service allocates a hardware device to the calling subsystem or device driver Functional Prototype RIC_ULONG AllocHW char DeviceName RIC_ULONG BufferSize RIC_ULONG POSTStatus unsigned char DeviceDataPtr RIC_ULONG Reserved Parameters DeviceName Input Name of the hardware device requested by this call This name is predefined for each type of device BufferSize Input Size of the buffer pointed to by DeviceDataPtr The kernel copies device related data to this buffer If the buffer is too small the kernel copies BufferSize amount of d
269. out RIC_ULONG Reserved Parameters SemHandle Input Handle of semaphore to decrement Timeout Input Optional timeout for waiting for a semaphore Wait indefinitely Return immediately if the semaphores are unavailable Any other value from 1 to 65535 Wait time in milliseconds The granularity of the timer is five milliseconds The timeout value is rounded up to the next multiple of five if it is not already a multiple of five Reserved Input Reserved parameter must be 0 Returns RC SUCCESS RC OWNER CLOSED SE RC INVALID HANDLE RC SEM ALREADY OWNED RC TIMEOUT RC INVALID CALL RC INVALID RESERVED PARM RC INVALID TIMEOUT RC NEW SEM COUNT Remarks If the semaphore count is positive control returns immediately to the caller and the count is decremented If the count is zero the calling process is made to wait Only processes that have created or opened the semaphore can wait for the semaphore Processes are made to wait in a first in first out FIFO order rather than by priority If a mutual exclusion semaphore is owned by a process that is stopped all waiting processes are awakened with an RC OWNER CLOSED SEM indicating the owner was stopped The error is returned because the code and data protected by the mutual exclusion semaphore may have been left in an indeterminable state If the semaphore s count is modified using SetSemCount
270. parameters and call the Application Loader Application Loader Appendix B Message File 299 RICOO028 RICO032 RIC0028 Correct syntax is aad ra ricdump card_num filename path Q path A addr len P cfgfile O out file C Explanation Dump utility syntax help message Action Select the proper parameters and call the Dump utility Source Dump RIC0029 Correct syntax is gt gt riccnfg L card num1 L Q card_num2 A P C config filename Explanation SCB Configuration utility syntax help message Action Select the proper parameters and call the SCB Configuration utility Source Configuration RICO030 Correct syntax is I ricstat path Explanation Status utility syntax help message Action Select the proper parameters and call the Status utility Source Status RICO031 Correct syntax is path Q Explanation Reset utility syntax help message Action Select the proper parameters and call the Reset utility Source Reset RIC0032 Reset of card nnin progress Explanation A reset of card nn is in progress Action None Source Reset 300 ARTIC960 Programmer s Reference RIC0033 RICO040 RIC0033 Reset of card nn complete Explanation Card nn has been reset successfully Action None Source Reset RIC0034 Reset of card nn failed Explanation Card nn failed to reset Action Run diagnostics
271. ped Version 0x0 Type normal Termination Code Software Requester Id 0x01050006 Source Of Req Local Error Code 0x0 M Figure 6 49 Example Screen Process Terminated by Software Event This example shows a process terminated by a processor event The process was stopped because it tried to perform an unsupported operation C Enter process name or ID gt opfault rel ame PRC opfault rel ID 0x01050007 Priority 0x28 Entry point 0x22082020 Stack pointer 0x220811E0 Param pointer 0x22083144 State stopped Version 0x0 Type normal Termination Code Processor Fault Type Operation Subtype Invalid Opcode Code Address 0x22083000 M P Figure 6 50 Example Screen Process Terminated by Processor Event Chapter 6 System Unit Utilities 255 Examples of Interactive Messages This example shows a process terminated by an adapter event The process was stopped because of an unsupported memory access Enter process name or ID gt TPROC 3 ame PRC TPROC 3 ID 0x0105000B Priority 0x28 Entry point 0x2208C000 Stack pointer 0x2208F1E0 Param pointer 0x22093134 State stopped Version 0x0 Type normal Termination Code Adapter Trap Type Processor Memory Address 0x20002040 Code Address Ox2208E1E0 Figure 6 51 EXample Screen Process Terminated by Adapter Event 6 Process Resources The process resources screen includes resources that the process created owns and
272. pplied memory buffer is not large enough to receive the entire buffer of the data requested 0x0001001A RC INVALID ADDRESS The adapter address is out of range Aninvalid adapter address was specified The invalid address can be either a bad memory or O address 0x0001001B RC INVALID MEM ACCESS The memory access on the address passed by the user is not appropriate for the action to be taken The user should check system bus as well as 80960 access The application does not have proper access to the supplied memory buffer or the driver was unable to pin the physical memory to perform the necessary DMA request Note that in 16 bit OS 2 applications will not receive this return code Instead 16 bit OS 2 terminates the process with a trap In 32 bit OS 2 threads have the ability to get control through an exception handler when the driver reports this error 0x0001001C RC INVALID RESERVED PARM A non zero reserved parameter was passed Reserved parameters must be zero Appendix C Return Error and Exit Codes 317 Return Codes Listed Numerically Return Code Description 0x0001001D RC INVALID SIZE Size of request exceeds amount of memory allocated or size is 0 Mailbox message unit size is incompatible with previously created mailbox Size specified for a system bus operation exceeds maximum allowed The size of a passed parameter was invalid out of range 0x0001001E RC INVALI
273. previously created resources If a mailbox name was specified using the global search option this message indicates that a global mailbox matching the resource name was not found on a remote unit This could be because the mailbox was never created because SCB pipes for the remote unit are not configured or because the remote unit is not functioning The requested name does not exist or could not be found within the specified domain The domain is limited to the SCB pipes configured The query may have failed due to a timeout waiting for the SCB pipes to change to a not full state 0x00010104 RC INVALID CALL The called service is not available from the caller s environment for example calling a blocking service in an interrupt handler 0x00010105 RC CALL TERMINATED The subsystem that was called has been stopped This error occurs when a process was executing as an extension of the caller s process and is stopped 0x00010106 RC INVALID PROCESSID The process ID parameter specified was invalid 0x00010107 RC UNSUPPORTED FUNCTION The function number used for the calling SVC call is invalid 318 ARTIC960 Programmer s Reference Return Codes Listed Numerically Return Code Description 0x00010108 RC INVALID FUNCTION CODE The function number passed to QueryCallAddress is out of range This may also be returned if a service is called directly using InvokeDev and an invali
274. ption 18 RC_UTIL_NOT_PENDING There is no triggered dump pending on the adapter that can be canceled 19 RC_UTIL_NO_MORE_MEM There is not enough free storage to complete the request 20 RC UTIL PIPE ALREADY CONF The SCB pipes between units are already configured 21 RC UTIL PIPE CONF FAILED Configuration failed between the adapter and the system unit 22 RC UTIL PIPE SIZE OUT OF RANGE The peer adapters could not be configured to communicate on a peer to peer basis because the specified pipe size was too small 23 RC UTIL PIPE UNCONF The peer adapters could not be configured to communicate on a peer to peer basis because of the configuration of the adapter Either the adapter full memory window is not present or it is in a location that is inaccessible to the other peer adapter This error can be received only in PS 2 systems 24 RC UTIL PROC DID NOT INIT The process was loaded using the W option of the Application Loader and it failed to issue the kernel Completelnit call in the specified time period 25 RC UTIL PROC INIT ERROR The process was loaded using the W option of the Application Loader and it passed a non zero error code on the kernel Completelnit call 26 RC UTIL PROC MISMATCH The file to be loaded was compiled for a processor type that is different from the adapter type 27 RC UTIL SYSTEM ERROR An operating system error condition
275. ption are enabled 5 Preemption cannot be enabled disabled 6 process may not suspend itself from an interrupt handler a signal handler or an asynchronous handler 7 When in a handler a process ID must be provided that is not the process currently in execution 8 May be called to send a message to a local mailbox only Parameter Types The description of each service includes the type of each parameter The following types are defined Table 2 2 Sheet 1 of 2 Parameter Types Service Description RIC_DEVHANDLE Device driver or subsystem resource handle RIC_PROCESSID Process ID RIC_EVNHANDLE Event resource handle RIC_MBXHANDLE Mailbox resource handle RIC_QUEHANDLE Queue resource handle RIC_SEMHANDLE Semaphore resource handle RIC_SIGHANDLE Signal resource handle RIC TMRHANDLE Software timer resource handle RIC_ASYNCHANDLER Entry point code address for an asynchronous event handler RIC SIGHANDLER Entry point code address for a signal RIC VECTOR Code address RIC SLONG Signed number RIC_TIMEOUT Signed number RIC_ULONG Unsigned number RIC_USHORT Unsigned number RIC_RESPMBX Unsigned number RIC_INVOKENUM Subsystem call function number RIC_CARDNUM Logical card number 18 ARTIC960 Programmer s Reference Table 2 2 Sheet 2 of 2 Parameter Types Service Description RIC_DOHANDLER Entry point of code address for an OpenDev entry point RIC_DCHAN
276. put Boundary alignment of suballocated memory Alignment values are the log of the boundary number For example a 16 byte boundary would translate to an Alignment value of log gt 16 4 SuballocSize Output Number of bytes of memory required to make a suballocation pool with the given suballocation unit size and number of units This size can then be used to calculate the amount of memory to allocate with CreateMem Reserved Input Reserved parameter must be 0 Returns RC SUCCESS RC INVALID COUNT RC INVALID RESERVED PARM RC INVALID SIZE RC INVALID MEM ACCESS RC INVALID ALIGNMENT Remarks This service should be used by applications using the suballocation services so that they know how much memory to allocate for a suballocation pool This service returns only a byte count It does not actually allocate or initialize any memory When calculating the alignment of suballocation chunks this service rounds the unit size up to the next power of two The actual alignment is the larger of this rounded value and the alignment represented by the Alignment parameter For example e A unit size of 4 bytes and Alignment value of 0 1 byte boundary results in suballocation on 4 byte boundaries e A unit size of 4 bytes and an Alignment value of 4 16 byte boundary results in suballocation on 16 byte boundaries e A unit size of 3 and an Alignment value of 1 2 byte boundaries results in suballocation on 4 byte boundaries Chapter 3
277. query memory protection 73 resuming 40 setting exit routine 47 starting 36 status getting 25 suspending 39 synchronization services 50 unloading 36 process communication CloseMbx 114 CloseQueue 97 CloseSig 719 CreateMbx 7 04 CreateQueue 95 CreateSig 715 FreeMbxBuffer 09 GetMbxBuffer 08 GetQueue 00 InvokeSig 20 Index 337 Openmbx 06 OpenQueue 96 OpenSig 7 PutQueue 98 ReceiveMbx 2 SearchQueue 02 SendMbx 0 process management CompleteInit 23 CreateProcess 34 Dispatch 49 EnterCritsec 47 ExitCritSec 45 GetProcessData 46 QueryCardInfo 28 QueryConfigParams 3 QueryPriority 43 QueryProcessInExec 44 QueryProcessStatus 25 ResumeProcess 40 SetExitRoutine 4 SetPriority 42 SetProcessData 45 start stop process 37 StartProcess 36 SuspendProcess 39 UnloadProcess 38 process synchronization CloseEvent 60 CloseSem 53 CreateEvent 58 CreateSem 5 OpenEvent 59 OpenSem 52 QuerySemCount 56 ReleaseSem 54 RequestSem 55 SetSemCount 57 WaitEvent 6 process type signaling 6 process controls PC register 742 ProcessSleep Sleep a Process 75 programming interface mailbox 276 publications reference xv put message into mailbox 284 PutQueue Put an Element into a Queue 98 Q query exception conditions 274 free memory 74 memory protection 72 process priority 43 338 ARTIC960 Programmer s Reference QueryCardInfo Get the Card Configuration Information 28 QueryConfigParams Get the Confi
278. r Input The source memory buffer address on the adapter This is a flat 32 bit ARTIC960 address DestBuffer Input The destination buffer address in system memory This is a 32 bit logical address BufferLen Input The length in bytes to be read OptionWord Input Reserved must be 0 Returns RC_SUCCESS RC_NO_MORE_RES RC_ADAPTER_EXCEPTION RC_RESET_ACTIVE RC DMA TRANSFER FAILED AIX only RC_SCB_TRANSFER_FAILED RC DUMP ACTIVE RC SU INVALID HANDLE RC INVALID ADDRESS RC TIMEOUT RC INVALID MEM ACCESS RC SYSTEM ERROR RC INVALID OPTION RC UNIT NOT FUNCTIONING RC INVALID SIZE RC WRN PIPES NOT CONFIGURED RC NO ADAPTER RESPONSE Remarks e All references to ARTIC960 memory are flat addresses There is no concept of paging shared memory or DMA visible to the user application e The memory protection hardware on the ARTIC960 adapter reports all errors to the ARTIC960 processor The system unit driver is not directly notified of access violations Because of this short RICRead calls may succeed even though they cause access violations whereas a long RICRead call to the same region may be rejected because of improper access rights This is because the subsystems on the card verify proper access on all transfers requested by the system unit using SCB control elements e The retu
279. r failure of that initialization See CompleteInit Mark Process as Completely Initialized on page 23 The maximum timeout value is 64 If a failure occurs the message contains the ErrorCode from the Completelnit call This option is automatically set by the Application Loader for all files beginning with RIC_ N process name Specifies the name for process being loaded The process is passed to the process as argv 0 If this parameter is not specified filename is passed as argv 0 with the path information stripped The length of the process name is limited to 16 characters including the NULL terminator Specifies creating an outfile for symbolic debugging The outfile name is the filename with a file extension of out instead of rel The file is created in the current directory The intended use is to download the task that is not started L and specify the O switch Then filename out can be used with an 80960 interactive computing environment ICE or a supported debugger Chapter 6 System Unit Utilities 197 Application Loader ricload Utility P priority Specifies that the process should be started with a priority level of priority If this parameter is not specified the kernel chooses a default priority level T Specifies to set the time of day on the adapter The system time is obtained and passed to the kernel on the ARTIC960 adapter V Specifies to display verbose informati
280. r integer Exit rc integer P RESIZEMEM ResizeMem Entry Baseptr integer Exit rc integer P SETMEMPROT SetMemProt Entry BlockPtr integer Exit rc integer P QUERYMEMPROT QueryMemProt Entry BlockPtr integer Exit rc integer P QUERYFREEMEM QueryFreeMem Entry OptionWord integer Exit rc integer P MALLOCMEM MallocMem Entry Size integer Exit Baseptr integer P FREEMEM FreeMem Entry Blockptr integer Exit rc integer P COLLECTMEM CollectMem Entry Option integer Exit rc integer FreeUnits integer FreePages integer 158 ARTIC960 Programmer s Reference Kernel Trace Information Table 3 9 Service Class C PROCESS SERVICE Trace Format of Procedure ID Kernel Service Position Trace Data Data P QUERYPROCESSSTATUS QueryProcessStatus Entry OptionWord integer Entry ProcessName character or ProcessID integer Exit rc integer P_SETPRIORITY SetPriority Entry ProcessID integer Entry Priority integer Exit rc integer P QUERYPRIORITY QueryPriority Entry ProcessID integer Exit Priority integer Exit rc integer P STOPPROCESS StopProcess Entry ProcessID integer Exit rc integer P UNLOADPROCESS UnloadProcess Entry ProcessID integer Exit rc integer P_STARTPROCESS StartProcess Entry ProcessID integer Exit rc integer P_CREATEPROCESS CreateProcess Entry ProcessName character Exit rc integer P_COMPLETEINIT Completelnit Entry none integer Exit rc P_SUSPENDPROCESS SuspendProcess
281. r to the PSTAT command in OS 2 Run the Status utility in this mode using pipes Type the following to call pipes ricstat lt parameters gt S more The following items are displayed Base hardware configuration main menu option 1 The name process ID version priority and state of every process on the adapter main menu option 2 The name attributes and owner of every resource on the adapter main menu option 3 Exception conditions main menu option 9 Dump format mode The address space of the adapter is displayed on the standard output device This mode displays all of the dumped adapter memory space in a form similar to the dump memory command in DOS This format is intentionally raw to allow more advanced tools and utilities to scan the decompressed data while still enabling manual inspection of the dump data The following chart summarizes the options for using the Status utility Table 6 8 Status Utility Options Live Analysis Post Analysis Interactive mode default F dump file Status mode S dump file S Dump format mode N A D dump file Chapter 6 System Unit Utilities 223 Status Utility Status Syntax aaa er ricstat Figure 6 15 Status Utility Syntax I Specifies that all numeric prompts are decimal the default is hexadecimal card num Specifies the logical card number for live analysis operation F dump file Specifies a dump file for post analysis operat
282. r to the event masks listed in sections SoftwareEvents and AdapterEvents on page 139 and ProcessorEvents on page 140 Pr Information specific to processor events see Pr Field on page 142 Ad Information specific to adapter events see Ad Field on page 143 Sw Information specific to software events see Sw Field on page 144 Chapter 3 Base Kernel Services 141 RegisterAsyncHandler Register an Async Handler 142 Pr Field The Pr field in AsyncEvent has the following definition For maximum portability applications should limit their accesses of this structure to the Type and CodeAddress fields The other fields are processor specific All fields except the StackFrame field are defined in the Intel 80960 User s Manual struct RIC_ProcessorEvent RIC_ULONG FaultType RIC_ULONG SubType RIC_ULONG CodeAddr RIC ULONG StackFrame RIC ULONG ProcessCtrl RIC ULONG ArithCtrl RIC ULONG Reservedl RIC ULONG Reserved2 where FaultType Fault type given by the processor Subtype Fault subtype given by the processor CodeAddr Code address of the fault undefined for some faults StackFrame Pointer to the process registers on the stack This field is valid only for Trace faults ProcessCtrl Contents of the process controls PC register ArithCtrl Contents of the arithmetic controls AC register Reservedl Reserved2 Reserved for future use ARTIC960 Programmer s Reference
283. r with the driver messages used by the OS 2 mailbox process Table 1 4 OS 2 Mailbox Process Messages Message Number Return Code Notes RICO0001 RC UTIL INVALID CMDLINE OPTION RIC0002 RC UTIL INVALID CMDLINE Chapter 1 Loading and Configuring 9 Table 1 4 OS 2 Mailbox Process Messages Message Number Return Code Notes RIC0003 RC UTIL FILE NOT FOUND RIC0004 RC_UTIL_FILE_ACCESS RICO006 RC UTIL NO MORE MEM RICO016 RC_UTIL_SYSTEM_ERROR RIC0019 RC_UTIL_NOT_INSTALLED RICO0021 RC UTIL SUCCESS Process successfully started RIC0048 RC UTIL WRNHELP GIVEN RIC0050 RC UTIL RESOURCE BUSY RICO051 RC UTIL ALREADY STARTED RIC0062 RC UTIL SUCCESS Process terminated successfully RICO063 RC UTIL NOT RUNNING Not found ARTIC960 Support for AIX The following sections describe the ARTIC960 Support for AIX Supported ARTIC960 Configurations 10 The ARTIC960 adapter supports a wide variety of configurations such as interrupt levels I O addresses and system bus memory configurations ARTIC960 Support for AIX Version 1 3 added support for 14 ARTIC960 adapters 0 through 13 The ARTIC960 Support for AIX supports all configurable hardware options with the following restrictions Interrupt Level configurable interrupt levels are supported I O Address configurable base I O addresses are supported For the RadiSys ARTIC960 PCI and ARTIC960Hx this window is use
284. re no configuration parameters defined for the base subsystem SCB Subsystem The SCB Subsystem parameters that can be set are as follows The default parameters are underlined Parameter Description MEMPROT YES NO Subsystem memory protection enable Protection is enabled only if kernel memory protection has been enabled SIGHANDPROT YES NO Signal interrupt handler memory protection enable Protection is enabled only if kernel memory protection and subsystem memory protection have been enabled e System Bus I O Subsystem The System Bus I O Subsystem parameters that can be set are as follows The default parameters are underlined Parameter Description THRESHOLD 128 Maximum number of bytes to be transferred using channel 1 Requests above this threshold value are sent on channel 2 MEMPROT YES NO Subsystem memory protection enable Protection is enabled only if kernel memory protection has been enabled If you are running the ARTIC960 Support for OS 2 Version 1 1 0 or higher or the ARTIC960 Support for AIX Version 1 1 3 0 or higher this parameter is ignored The System Bus I O Subsystem always runs with its memory protection disabled TCINTPROT YES NO Terminal count interrupt handler memory protection enable Protection is enabled only if kernel memory protection and subsystem memory protection have been enabled If you are running the ARTIC960 Support for OS 2 Version 1 1 0 or higher
285. ree Mailbox Buffer FreeMbxBuffer Free Mailbox Buffer This service frees a previously allocated mailbox buffer Functional Prototype RIC_ULONG FreeMbxBuffer Parameters void RIC_ULONG RIC MBXHANDLE MbxHandle MsgPtr Reserved MbxHandle Input Handle of mailbox where the process wants to free a message buffer MsgPtr Input Pointer to allocated mailbox buffer Reserved Input Reserved parameter must be 0 Returns RC SUCCESS RC INVALID RESERVED PARM RC INVALID HANDLE RC INVALID MBX BUFFER ADDR RC INVALID MEM ACCESS RC MBX BUFFER IN QUEUE Remarks None Chapter 3 Base Kernel Services 109 SendMbx Send a Message SendMbx Send a Message This service puts a message into a mailbox Functional Prototype RIC_ULONG SendMbx RIC_MBXHANDLE Parameters void RIC_ULONG RIC_ULONG RIC_ULONG MbxHandle MsgPtr Size OptionWord Reserved MbxHandle Input Handle of the mailbox where the process sends the message MsgPtr Input Pointer to the message to be sent When the MBX S END FREE BUFFER option is specified MsgPtr must point to the start of the message buffer Otherwise it may point to any location contained in the message buffer Size Input Size of the message buffer A message size of 0 is invalid OptionWord Input Bit field to describe how to send the message To build the appropriate s
286. rld Wide Web RadiSys maintains an active site on the World Wide Web The site contains current information about the company and locations of sales offices new and existing products contacts for sales service and technical support information You can also send E mail to RadiSys using the web site v When sending E mail for technical support please include information about both the hardware and software plus a detailed description of the problem including how to reproduce it To access the RadiSys web site enter this URL in your web browser http www radisys com Requests for sales service and technical support information receive prompt response Other If you purchased your RadiSys product from a third party vendor you can contact that vendor for service and support Reference Publications You may need to use one or more of the following publications for reference RadiSys ARTIC960 Programmer s Guide RadiSys ARTIC960 STREAMS Environment Reference Operating and Installation documentation provided with your computer system Guide to Operations books for one of the following coprocessor adapters RadiSys ARTIC960 PCI adapter RadiSys ARTIC960Rx PCI adapter RadiSys ARTIC960Hx PCI adapter RadiSys ARTIC960RxD PCI adapter Each book contains a description of the coprocessor adapter instructions for physically installing the adapter parts listings and warranty information About This Book XV
287. rn code RC WRN PIPES NOT CONFIGURED is a warning indicating the memory transfer was completed but the SCB subsystem is not configured Chapter 7 System Unit APIs 267 RICRead Read from ARTIC960 Memory 268 e The return codes RC DUMP ACTIVI E and RC Ri ES ET ACTIVI E indicate a dump or reset was active when this call was made or a dump or reset was done while the call was blocked e The return code RC UNIT NOT FUNCTIONING occurs when the driver uses SCB control elements to move the data and the adapter does not respond within an internal driver timeout period e A buffer length of 0 is not valid The maximum buffer size is limited to 64 KB e The IBM RISC System 6000 uses big endian memory format whereas the 80960 on the ARTIC960 adapter uses little endian format across the PCI or MCA bus It is up to the calling application to perform byte and word swapping where necessary The RICRead and RICWrite functions do not steer the data for the application ARTIC960 Programmer s Reference RICWrite Write to ARTIC960 Memory RICWrite Write to ARTIC960 Memory This routine is used to write data to memory on the ARTIC960 adapter Functional Prototype RIC_ULONG RICWrite Parameters Handle SrcBuffer DestBuffer BufferLen OptionWord Returns U RC_S RC_AD RC_D RC_D RC_IN RC_I RC_I RC_I RC_NO U Remarks RIC_HANDL void RIC_PTR RIC_UI
288. rrupt Entry Vector number integer handler Table 3 6 Service Class C KERN COMMANDS SERVICE Trace Format of Procedure ID Kernel Service Position Trace Data Data P PROCESSMBXCOMMAND Receiving a command Entry CommandNum integer in the kernel mailbox Exit none V A NULL resource name is displayed as the string Null Pointer An invalid resource name is displayed as the string Invalid Pointer Chapter 3 Base Kernel Services 157 Kernel Trace Information Table 3 7 Service Class C MAILBOX SERVICE Trace Format of Procedure ID Kernel Service Position Trace Data Data P CREATEMBX CreateMbx Entry MbxName character Entry MbxRxMemName character Exit rc integer P OPENMBX OpenMbx Entry MbxName character Entry SendMemName character Exit rc integer P SENDMBX SendMbx Entry MbxHandle integer Exit rc integer P GETMBXBUFFER GetMbxBuffer Entry MbxHandle integer Exit rc integer P FREEMBXBUFFER FreeMbxBuffer Entry MbxHandle integer Exit rc integer P RECEIVEMBX ReceiveMbx Entry MbxHandle integer Exit rc integer P CLOSEMBX CloseMbx Entry MbxHandle integer Exit rc integer Table 3 8 Service Class C MEMORY SERVICE Trace Format of Procedure ID Kernel Service Position Trace Data Data P CREATEMEM CreateMem Entry MemName character Exit rc integer P OPENMEM OpenMem Entry MemName character Exit rc integer P CLOSEMEM CloseMem Entry Basept
289. rs 32 RIC_ULON RIC_ULON RIC_ULON RIC_ULON RIC_ULON RIC_ULON RIC_ULON RIC_ULON Parameter TimeOfDay PerfTimer DataCache InstCache RegCache PinKernProcCode PinKernIntcode PeerTimeout MemoryProtection DefaultPriori MaxProcess MaxTimer MaxSemapho MaxMemAllo MaxQueue MaxEvent MaxDDSS MaxSignal MaxLocalMa Memory protection enable flag 0 Disabled 1 Enabled y Default process priority Maximum number of processes includes device drivers and subsystems Maximum number of timers re Maximum number of semaphores c Maximum number of memory allocations Maximum number of queues Maximum number of events Maximum number of device drivers and subsystems does not include kernel device drivers and kernel subsystems Maximum number of signals ilbox Maximum number of local mailboxes MaxGlobalMailbox Maximum number of global mailboxes MaxRemoteMailbox Maximum number of remote mailboxes MaxRemoteMailboxOpen Maximum number of remote mailboxes open MaxRemoteMailboxSend Maximum number of remote mailbox sends outstanding MaxRemoteMailboxRcv Maximum number of remote mailbox receives outstanding MaxPeerAdapters Maximum number of peer adapters ARTIC960 Programmer s Reference QueryConfigParams Get the Configuration Parameters MaxSystemMCReq Maximum number of system bus read write requests from the sys
290. rved Reserved field must be 0 Remarks None ARTIC960 Programmer s Reference UnloadProcess Unload a Process UnloadProcess Unload a Process This command unloads a process given its process ID Command Parameters CommandNum in the common header must be set to KERN_UNLOAD_ PROC Structures struct RIC_UnloadProcessCmd RIC PROCESSID ProcessID RIC_ULONG Reserved where ProcessID Process identification Reserved Reserved field must be 0 Response Parameters ReturnCode values in RIC_KernResponse are RC_SUCCESS RC_INVALID_RESERVED_PARM RC_INVALID_PROCESSID RC_PERMANENT_PROCESS There is no variant response part for this command Remarks None Chapter 4 Kernel Commands 169 StopProcess Stop a Process StopProcess Stop a Process 170 This command stops a process given its process ID Command Parameters CommandNum in the common header must be set to KERN_STOP_PROC Structures struct RIC_StopProcessCmd RIC_PROCESSID ProcessID RIC_ULONG Reserved where ProcessID Process identification Reserved Reserved field must be 0 Response Parameters ReturnCode values in RIC_KernResponse are RC_SUCCESS RC_INVALID_RESERVED_PARM RC_PROCESS_NOT_STARTED RC_INVALID_PROCESSID RC_PERMANENT_PROCESS There is no variant response part for this command Remarks None ARTIC960
291. s such as removing a queue element or mailbox message Glossary 331 MVDM MP Safe mutex O OSS R RDT Multiple virtual DOS machines Multiprocessing safe Mutual exclusion semaphores used for serializing access to code or data structures On card STREAMS subsystem Resource Descriptor Table receiving processes ricmbx Processes that open a signal with a non NULL EntryPoint See calling processes The mailbox process for AIX that is a daemon process that works in conjunction with the device driver to handle remote mailbox processing RICMBX32 EXE ROM S SCB SAL semval SMP The mailbox process for OS 2 that is a detached process that works with the physical device driver to handle remote mailbox processing Read only memory Subsystem Control Block STREAMS Access Library AIX variable For information on semval see usr include sys sem h Symmetric multiprocessing System executables A collective term for the kernel and related subsystems that must be loaded onto the adapter before any application processes are loaded 332 ARTIC960 Programmer s Reference Index A access violation 267 269 adapters supported chart address convert system bus 787 destination 778 element 02 fault code 42 7 10 physical system bus 78 addressability get memory 67 AIX mailbox process syntax alignment values block 64 alignment memory boundary 75 allocate free
292. s copied into this Input Size of the buffer is pointed to by ParmPtr If the buffer is not large enough the service copies BufferSize bytes into the user s buffer and returns Parameters ParmPtr memory BufferSize an error code Reserved Returns RC_SUCCESS RC INVALID MEM ACC RC BUFFER TOO SMAL RC INVALID RESERV Remarks Input Reserved parameter must be 0 ESS D PARM This is the card information structure These values are taken from the ROS structure struct RIC CardInfo RIC UI RIC ULO RIC ULON RIC ULON RIC ULO RIC CAR RIC ULO RIC ULO RIC ULO RIC ULO RIC ULO RIC ULO RIC ULO RIC ULO RIC ULON struct RIC MemRegion E o uu 0 A 2 UM uuu uu z z QOQA ARTIC960 Programmer s Reference PageSize KernelVersion BaseSubVersion MCIOSubVersion SCBSubVersion CardNum NumCards CardType MasteriVersion Master2Version Master3Version Reserved BaseCardVersion ROSVersion MemRegions MemInfo MAX MEM REGIONS QueryCardInfo Get the Card Configuration Information struct RIC MemRegion RIC_ULONG MemBase RIC_ULONG MemTotal RIC_ULONG MemType Parameters PageSize Size of memory protection page KernelVersion Kernel version number BaseSubVersion Base subsystem version MClIOVersion System Bus I O subsystem version SCBVersion SCB subsystem versio
293. s on the system bus communicate with one another The SCB Configuration utility configures the move mode SCB pipes between the ARTIC960 adapters and the system processor and between each ARTIC960 adapter The SCB pipes should be configured before using Remote Mailbox services The Configuration utility must be run after the ARTIC960 kernel base subsystem system bus I O subsystem and SCB subsystem are loaded but before any mailbox applications are loaded If you are going to use peer to peer communication load the kernel with the MAX_PEER_ADAPTERS parameter equal to the number of peer SCB units The kernel default is 0 In addition if you are using the ARTIC960 Micro Channel adapter in an AIX environment configure the adapter with the attribute DMA2Enable set to YES if peer to peer communication is needed The attribute default is NO V If an adapter is reset this utility must be rerun Unless otherwise specified a default pipe size is used The default pipe size is 1024 bytes for a logical adapter pipe and 2048 bytes for a system unit pipe When a pipe size is specified it must be a minimum of 128 bytes The Configuration utility prevents configuration of a pair of logical adapters if they are not physically able to communicate If an adapter does not have a full memory window configured other adapters cannot directly access it If an adapter is in a 16 bit Personal System 2 PS 2 slot and the window for the peer adap
294. s should no longer be notified HwEvents Input Mask specifying of which adapter hardware events the process should no longer be notified PrEvents Input Mask specifying of which processor events the process should no longer be notified Reserved Input Reserved parameter must be 0 Returns RC SUCCESS RC INVALID RESERVED PARM RC NOT REGISTERED RC INVALID CALL Remarks The structure of the masks is defined under RegisterAsyncHandler Register an Async Handler on page 139 If the process is not registered for one of the events specified in the masks the process is not deregistered for any of the events Chapter 3 Base Kernel Services 145 Hook Services Hook Services The kernel provides hooks so processes can be notified of special actions These hooks have the option of preprocessing or post processing notification In other words processes can be notified either before the action occurs or after the action occurs This notification takes the form of calling a hook handler registered by the process Within the hook handler the process can take whatever actions are required The following are the hook services Service Name Page RegisterHook 147 DeregisterHook 148 Only one hook is initially provided and it is for the dispatcher A dispatcher hook handler might want to save and restore an environment for processes as they are dispatched 146 ARTIC960 Progra
295. screen shows the prompts and items displayed when the 80960 registers option is chosen from the main menu This option is available only if the Status utility is called on a dump file using the F switch See Figure 6 67 on page 262 for an example C UN Enter adapter number gt g0 nnnnnnnn ro nnnnnnnn pfp gl nnnnnnnn rl nnnnnnnn sp g2 nnnnnnnn r2 nnnnnnnn rip g3 nnnnnnnn r3 nnnnnnnn g4 nnnnnnnn r4 nnnnnnnn gb nnnnnnnn rb nnnnnnnn g6 nnnnnnnn r6 nnnnnnnn g7 nnnnnnnn r7 nnnnnnnn g8 nnnnnnnn r8 nnnnnnnn g9 nnnnnnnn r9 nnnnnnnn 910 nnnnnnnn r10 nnnnnnnn gll nnnnnnnn r11 nnnnnnnn g12 nnnnnnnn r12 nnnnnnnn g13 nnnnnnnn r13 nnnnnnnn 914 nnnnnnnn r14 nnnnnnnn 015 nnnnnnnn fp r15 nnnnnnnn sf0 nnnnnnnn SSSS sfl nnnnnnnn SSSS sf2 nnnnnnnn SSSS sf3 nnnnnnnn SSSS sf4 nnnnnnnn SSSS ip nnnnnnnn nnnnnnnn pc nnnnnnnn tc nnnnnnnn fp0 nnnnnnnnnnnnnnnnnnnn fp2 nnnnnnnnnnnnnnnnnnnn fpl nnnnnnnnnnnnnnnnnnnn fp3 nnnnnnnnnnnnnnnnnnnn Press Enter to continue i Figure 6 43 Status Utility 80960 Registers Display e following SF registers are displayed depending on the adapter SF Registers Displayed Adapters sf0 sti 512 513 514 ARTIC960 and ARTIC960 y y y n n ARTIC960Rx and ARTIC960RxD y y n y n The lines fp0 fp3 are
296. sion can be used to give better performance The development version contains full support The additional functions it provides are normally needed only during application debug Configuration Parameters Configuration for the kernel and related subsystems is done through load time parameters that can be passed on the command line or through a configuration file when using RICLOAD These parameters take the form of keywords representing specific parameters followed by an equal sign and their value The individual parameters are separated by spaces tabs or new lines Parameters not specified at load time take on default values The configuration parameters for the kernel the SCB subsystem and the System Bus I O subsystem follow There are no parameters for the base device driver Kernel Parameters The following are the kernel parameters that can be set The default value for the parameter is underlined Table 1 2 Sheet 1 of 2 Kernel Parameters Parameter Description MEMORY PROTECTION YES NO Global memory protection enable When YES all normal processes run with memory protection on This parameter is ignored when an application is running on an adapter that does not support memory protection DEFAULT PRIORITY 40 Default process priority Unless otherwise specified when a process is loaded its priority is this value It must be at least 32 MAX DD SS 16 Maximum number of device drivers and subsystems
297. spatch queue BLOCKED The BLOCKED bit is set when the process has been blocked using a RequestSem WaitEvent GetQueue or ReceiveMbx call The process is taken off the dispatch queue DEVICE_DRIVER The DEVICE_DRIVER bit is set if a process declares itself as a device driver QUEUED The QUEUED bit is set when a process is ready to run WAITING ON PMREQ The WAITING ON PMREOQ bit is set when a process is blocked because it has issued a StopProcess or UnloadProcess call that is being serviced Process Information Bits Active processes may have valid information bits INITIALIZED The INITIALIZED bitis set when the process issues the Completelnit system call PERMANENT The PERMANENT bit is set when a process subsystem or device driver sets this field with the Completelnit system call The process subsystem or device driver cannot be unloaded by the UnloadProcess call when this bit is set It may be unloaded from the system unit at any time Chapter 3 Base Kernel Services 27 QueryCardiInfo Get the Card Configuration Information QueryCardlnfo Get the Card Configuration Information 28 This service gets information from the read only memory ROM data structure Functional Prototype RIC ULONG QueryCardInfo struct RIC CardInfo ParmPtr RIC ULONG BufferSize RIC_ULONG Reserved Input Pointer to the user s buffer The card information i
298. splay Vital Product Data VPD information when the VPD information option is chosen from the main menu e For each selection the resulting screen format is the same e Selection 2 is not displayed if the attached card is a PMC card 2 N 0 Previous Menu 1 Base ROM VPD Information 2 AIB ROM VPD Information Enter item for display gt 9 P Figure 6 40 Status Utility VPD Information Display The following screen shows the VPD information contained in the ROM for Intel based systems ie Displayable Message SSSSSSSSSSSSSSSSSSSSSSSSSSSSSS Adapter Type nn Part Number nnnnnnnnnnnn FRU Number nnnnnnnnnnnn Serial Number nnnnnnnn anufacturer ID nnnnnnnnnn EC Level nnnnnnnnnnnn ROS Level and ID n n Press Enter to continue Figure 6 41 Displayed VPD Information for Intel based Systems The following screen shows the VPD information contained in the ROM for RISC System 6000 Displayable Message SSSSSSSSSSSSSSSSSSSSSSSSSSSSSS Adapter Type nn Part Number nnnnnnnnnnnn FRU Number nnnnnnnnnnnn Serial Number nnnnnnnn anufacturer ID nnnnnnnnnn EC Level nnnnnnnnnnnn Device Driver Level n n Diagnostic Level n n Loadable Microcode nn nn ROS Level and ID n n Press Enter to continue Figure 6 42 Displayed VPD Information for RISC System 6000 Chapter 6 System Unit Utilities 251 Status Interactive Messages 11 80960 Registers The following
299. ss SN Enter adapter number gt Enter process name or ID SSSSSS nnnnnn nnnnnn nnnnnn nnnnnn nnnnnn SSSSSS nnnnnn SSSSSS proces SSSSSS SSSSSS nnnnnn gt SSSSSSSSSS nn nn nn nn nn SSSSS nn SSSSS sor SSSSSSSSSS SSSSSSSSSS nn ak Figure 6 24 Process Details Display Process Terminated by Processor Event Table 6 11 shows the Fault Type and SubType values Table 6 11 Termination Status Fault Types and Subtypes for a Processor Event Fault Type Fault Subtype Notes Parallel Parallel faults occurred Trace Instruction Branch Call Return PreReturn Supervisor Breakpoint Operation Invalid Opcode Operation Unaligned is Unimplemented 80960CA specific Unaligned extension Invalid Operand Arithmetic Integer Overflow Arithmetic Zero Divide Constraint Constraint Range Privileged Protection Length Type Type Mismatch Reserved Reserved Reserved Chapter 6 System Unit Utilities 235 Status Interactive Messages Process Terminated by Adapter Event The following screen shows the prompts and items displayed when the Process Details option is chosen from the main menu the process is in a stopped or expired state and the termination code is Adapter Valid values for Trap Type are memory violation and processor See Figure 6 51 on page 256 for an example N Enter adapter number gt
300. ss Specifies the service classes for which tracing is to be enabled Valid service classes are between 0 and 255 Service classes between 0 and 127 are reserved for kernel services For performance reasons the kernel does not do any checking Chapter 6 System Unit Utilities 213 Set Trace Utility 214 Set Trace Messages and Exit Codes The contents of the message file used by all utilities are listed in Appendix B Message File on page 295 The messages used by the Set Trace utility are listed in Table 6 5 The Set Trace utility also sets its exit code value to indicate the status of the set trace operation The following table correlates the exit code of the Set Trace utility with the messages Table 6 5 Set Trace Utility Messages and Exit Codes Message Number Exit Code Notes RICO0001 RC UTIL INVALID CMDLINE OPTION RIC0002 RC UTIL INVALID CMDLINE PARM RIC0005 RC UTIL INVALID CARD NUMBER RICO010 RC UTIL NO ADAPTER RESPONSE RIC0019 RC UTIL NOT INSTALLED RIC0038 RC UTIL ACCESS ERROR RICO300 RC UTIL WRNHELP GIVEN RIC0324 RC UTIL INVALID CMDLINE PARM Invalid service class RIC0326 RC_UTIL_SUCCESS Successful set trace operation ARTIC960 Programmer s Reference Get Trace Utility Get Trace Utility The Get Trace utility allows users to read data in the trace buffer on the RadiSys ARTIC960 adapter and store it in a file in binary form The data in this file can be format
301. ss can stop the timer at any time with the StopSwTimer service Chapter 3 Base Kernel Services EAT is ORed with OptionWord the timer is restarted when the kernel gets 87 StopSwTimer Stop a Software Timer StopSwTimer Stop a Software Timer 88 This service stops a previously started software timer Functional Prototype RIC ULONG StopSwTimer RIC TMRHANDLE TimerHandle ULONG Reserved Parameters TimerHandle Input Handle of the timer to be stopped This handle is passed to the process by the service CreateSwTimer Reserved Input Reserved parameter must be 0 Returns RC SUCCESS RC INVALID RESERVED PARM RC INVALID HANDLE Remarks This service stops a previously started software timer When called from an interrupt handler this service can potentially stop a recently expired software timer that is the software timer expired but the timer handler of the process was not called yet ARTIC960 Programmer s Reference SetSystemTime Set the Time of Day Clock SetSystemTime Set the Time of Day Clock This service sets the time of day clock Functional Prototype ULONG SetSystemTime struct TimeInfo SysTimeInfo RIC ULONG Reserved Parameters SysTimelInfo Input Pointer to a user s structure that contains time information see the Remarks section for this service Reserved Input Reserved parameter must be 0 Returns RC SUCCESS RC
302. sss M J Figure 6 27 Status Utility Process Parameters Display 238 ARTIC960 Programmer s Reference Status Interactive Messages 8 Resource Details The format of the Resource details display depends on the individual resource If a resource name without the resource type prefix is specified on the main menu the following menu is displayed and you are asked to indicate the resource type Return to previous menu Device Driver Event Mailbox Memory Queue Semaphore Signal Timer Hardware Device O1 4 CO n9 r2 C Enter the resource type gt Figure 6 28 Resource Details Submenu The following sections explain each of the options on the Resource details submenu 1 Device Driver Resource Details Submenu on page 240 2 Event Resource Details Submenu on page 241 3 Mailbox Resource Details Submenu on page 242 4 Memory Resource Details Submenu on page 243 5 Queue Resource Details Submenu on page 244 6 Semaphore Resource Details Submenu on page 245 7 Signal Resource Details Submenu on page 246 8 Timer Resource Details Submenu on page 247 9 Hardware Device Resource Details Submenu on page 248 Vector details are available only when specified by name or number See Vector Resource Details on page 249 for an explanation of the displayed information See Figure 6 63 on page 260 for an example Chapter 6 System Unit Utilities 239 Status I
303. t Process Data 46 GetQueue Get or Peek at an Element on a Queue 700 GetSuballoc Suballocate Memory 77 Getsuballocsize Return Size of Suballocation Pool 79 H hardware device query status of 37 return a 36 header kernel commands common 7 64 165 help xv hexadecimal value parameter 95 high performance file system HPFS 798 hooks DeregisterHook 48 overview 46 RegisterHook 47 HPFS high performance file system 798 HxInfo 45 1960 data cache 97 ID get process 44 PCI device 86 Index 335 immediate dump mode 202 InitSuballoc Prepare a Block of Memory for Suballocation 75 InitTrace 50 interface routines 264 interrupt vector allocate 128 129 entry point set new 3 return 733 interrupts preemptions disabling 47 invocation device driver 7 kernel mailbox process 8 InvokeDev Call a Subsystem or Device Driver 27 InvokeSig Call a Signal 20 K kernel 5 base services 2 call configuration 4 control information 77 loading parameters 4 process management 22 process synchronization 50 return codes 3 6 ric kern rel file services modes 5 terminal error codes 325 trace information 50 155 kernel commands common header for responses 65 DeRegisterResponseMbx 67 overview 63 QueryProcessStatus 68 RegisterResponseMbx 66 StartProcess 771 StopProcess 70 UnloadProcess 69 keywords 4 L library routines ANSI C functions support 73 ConvertCar
304. t for message indicating that the dump has been completed Source Dump RICO0012 Dump of card nn complete Explanation The dump of card nn is complete Action Use the Status Utility to analyze the raw dump file Reset the card to continue using it Source Dump RICO013 Dump trigger set for card nn Explanation A dump of card nn has been set up to trigger on an NMI error from the card Action No action is necessary This message is followed by a message indicating that a dump has started when the dump is triggered Source Dump RIC0014 Triggered dump of card nn cancelled Explanation The previously set up dump trigger for card nn has been canceled Action To retrigger the card call the dump utility again Source Dump Appendix B Message File 297 RIC0015 RICQ023 RIC0015 Triggered dump of card nn not pending Explanation There is no untriggered dump of card nn pending that can be canceled Action None Source Dump RICO016 Unexpected system error nnnn Explanation An operating system error condition has been received by the adapter firmware The unexpected error code is nnnn decimal Action Consult the appropriate operating system reference to determine the meaning of the error code Source Application Loader Dump Status Configuration OS 2 driver and Mailbox Process RICO019 Driver not installed Explanation The driver is not installed and running in the system This occurs when a utilit
305. t for the ARTIC960 adapter s exception conditions Functional Prototype ULONG RICGetException RIC HANDLE Handle RIC ULONG ExceptLen RIC EXCEPT ExceptData RIC TIMEOUT Timeout RIC ULONG Reserved Parameters Handle Input The handle for the ARTIC960 adapter ExceptLen Input This field specifies the length of the ExceptData buffer provided The value must be at least 8 to allow the exception code and actual exception data length to be returned It cannot be greater than 64K 1 bytes ExceptData Input The pointer to the buffer where the exception data should be returned Timeout Input The timeout parameter specifies whether the call should block waiting for an exception condition to occur A value of 0 indicates the call should return immediately A value of 1 indicates the call should block until an exception occurs on the adapter Any other value specifies the number of milliseconds to wait for an exception before timing out Reserved Input Reserved parameter must be 0 Returns RC SUCCESS RC INVALID TIMEOUT RC DUMP ACTIVE RC NO ADAPTER RESPONSE RC BUFFER TOO SMALL RC NO MORE RES 0S 2 only RC HANDLE CLOSED RC RESET ACTIVE RC INVALID MEM ACCESS RC SU INVALID HANDLE RC INVALID RESERVED PARM RC SYSTEM ERROR RC INVALID 5111 RC_TIMEOUT Remarks RC SUCCES
306. t is taken off the dispatch queue and its process state is set to SUSPENDED Functional Prototype RIC ULONG SuspendProcess RIC PROCESSID ProcessID RIC ULONG Reserved Parameters ProcessID Input Process ID of the process that is to be suspended A value of 0 means the calling process is suspending itself Reserved Input Reserved parameter must be 0 Returns RC SUCCESS RC INVALID RESERVED PARM RC PROCESS NOT START RC INVALID PROCESSID RC DEVICE DRIVER RC INVALID CALL ri None Chapter 3 Base Kernel Services 39 ResumeProcess Resume a Process ResumeProcess Resume a Process This service resumes a process Functional Prototype RIC ULONG ResumeProcess RIC PROCESSID ProcessID ULONG Reserved Parameters ProcessID Input Process ID of the process that is to be resumed Reserved Input Reserved parameter must be 0 Returns RC SUCCESS RC INVALID RESERVED PARM RC PROCESS NOT STARTED RC INVALID PROCESSID Remarks When the process is resumed it is put back on the dispatch queue If the process is already on the dispatch queue no action is taken If the process was suspended by another process after it blocked for a semaphore or an event ResumeProcess will not make it ready to run immediately unless the semaphore or event is also available at the time 40 ARTIC
307. tails Returns RC SUCCESS RC TRACE NOT INITIALIZED RC INVALID SERVICECLASS Remarks InitTrace must be called before any call to EnableTrace The EnableTrace service enables the logging of the trace for the service classes given as argument It does not report errors if the trace on a particular service was already enabled It enables the trace on the given services in addition to those for which trace is already enabled The valid service classes for the kernel are ALL SERVICES C ASYNC EVENT SERVICE C CLIB DEVICE DRIVER S EVENT SERVICE HOOK SERVICE TERR ERN COMMANDS SERVICE Q RVICE H 2 N QUEUE SERVICE I G 00 D o Q n AJ lt m Q e Chapter 3 Base Kernel Services 151 DisableTrace Disable Tracing of Service Classes DisableTrace Disable Tracing of Service Classes This service disables the logging of the trace information for the given set of service classes Functional Prototype RIC ULONG DisableTrace RIC ULONG ParamCount Parameters ParamCount Input Number of service classes being supplied as arguments to DisableTrace Input List of all the service classes separated by commas
308. tatus is required ProcessID Input Process ID whose status is required OptionWord Input Possible values are PROCESS NAME OPTION Specifies the ProcessName parameter is used PROCESS ID OPTION Specifies the ProcessID parameter is used PSBBufferPtr Input Process status and other process related information is returned to the requesting process in this buffer BufferSize Input Size of buffer pointed to by PSBBufferPtr If the buffer is not large enough the service copies BufferSize bytes into the user s buffer and returns an error code Reserved Input Reserved parameter must be 0 Returns RC_SUCCESS RC INVALID MEM ACCESS RC INVALID NAME RC INVALID OPTION RC INVALID RESERVED PARM RC INVALID PROCESSID RC NAME NOT FOUND RC BUFFER TOO SMALL Chapter 3 Base Kernel Services 25 QueryProcessStatus Get the Process Status 26 Remarks The kernel returns the information to the calling process using the following structure struct RIC_ProcessStatusBlock RIC_PROCE RIC_ULONG RIC_ULONG RIC_ULONG RIC_ULONG RIC_ULONG SSID ProcessID ProcessState ProcessInfo ProcessType Priority MemProtState ProcessID The process ID ProcessState Defines the current state of the process using two sets of bits see Primary Process State Bits and Secondary Process State Bits on page 27 ProcessInfo Process related information which is passed to the kernel i
309. ted Numerically Return Code Description 0x00010901 RC_NO_MBX_RECEIVER No receiver is present for the mailbox The mailbox has been closed 0x00010902 RC_MSG_BUFFER_NOT_FREED The message buffer was not returned to the pool even though the buffer return option was set in SendMbx Sender and receiver are sharing memory and copy option was not used Receiver should free buffer when finished with the message 0x00010903 RC INVALID RECEIVER Only the creating process can receive messages from a mailbox 0x00010904 RC NO MORE MBX All available mailboxes have been allocated 0x00010905 RC INVALID MBX BUFFER ADDR The message buffer pointer was invalid Aninvalid mailbox buffer pointer was passed to FreeMbxBuffer 0x00010906 RC MBX EMPTY There are no messages in the mailbox 0x00010907 RC NO MBX BUFFER There is not enough memory left in the mailbox pool to allocate the buffer There are no more available mailbox buffers in the pool 0x00010908 RC INVALID MSG BUFFER The message is not in the message pool associated with the open of this mailbox or the message has been freed 0x00010909 RC NO MBX PROCESS The mailbox process is not loaded 0x0001090A RC NO MORE RES ON REMOTE ARC NO MORE RES error was received from the remote unit on a remote mailbox operation During an open mailbox the remote unit did not have enough available internal Mailbox Process
310. ted by the Format Trace utility discussed in section Format Trace Utility on page 217 Prior to running the Get Trace utility use the Set Trace utility to initialize the trace buffer The trace buffer should not be read while tracing is active Before reading the trace buffer the Get Trace utility disables tracing of all services currently enabled unless the E option is specified Tracing of services can be enabled again after the buffer is read by using the Set Trace utility Get Trace Syntax T ricgettr card num Ebo qu gt path O out filename E Figure 6 7 Get Trace Utility Syntax card num Specifies the logical card number to be traced O out filename Specifies the name of the file in which data from the trace buffer is stored If this option is not specified the file rictrace bin is created in the current directory E Specifies that the trace buffer should be retrieved without first disabling the active tracing This option should be used only when the trace cannot be retrieved otherwise because the trace buffer could be updated as it is retrieved This option can be used to recover the trace buffer from a card that has an exception condition It should not be used on a card during active tracing Chapter 6 System Unit Utilities 215 Get Trace Utility 216 Get Trace Messages and Exit Codes The contents of the message file used by all utilities are listed in Appendix B Message File on page 29
311. tem unit outstanding MaxAdapterMCReq Maximum number of system bus move requests outstanding DefaultStackSize Default process stack size TimeSlice Time slice interval disable interval value in milliseconds 0 means disabled Watchdog Watchdog interval disable interval value in milliseconds 0 means disabled TimeOfDay Time of day enable flag Disabled 1 Enabled PerfTimer Performance timer enable flag Disabled Enabled DataCache Data cache enable flag Disabled 1 Enabled InstCache Instruction cache enable flag Disabled 1 Enabled RegCache Number of register sets that are cached Valid values are 5 through 15 PinKernProcCode Option to pin kernel code critical for process intensive applications Disabled 1 Enabled PinKernIntCode Option to pin kernel code critical for interrupt intensive applications Disabled 1 Enabled PeerTimeout Timeout value used by kernel mailbox subsystem when communicating with peer processes Chapter 3 Base Kernel Services 33 CreateProcess Create a Process CreateProcess Create a Process 34 This service creates a peer process Functional Prototype RIC_ULONG CreateProcess char ProcessName RIC_USERENTRY EntryPoint RIC_ULONG StackSize void ParamPtr RIC_ULONG ParamSize RIC_ULONG Priority RIC_ULONG OptionWord RIC PROCESSID ProcessID RIC ULONG Reserved Parameters ProcessName Input process name
312. ter is down level and cannot be supported by the device driver Action Update the ROM code on the adapter to a valid level RIC0072 Correct syntax is l1 1T ricmbx path config filename C L path K Explanation Mailbox process syntax help message Action Select the proper parameters and call the mailbox process Source Mailbox process RICO073 Timeout during mailbox initialization Explanation Initialization of the mailbox process failed Action Restart the process Source Mailbox Process 0075 Only 4 A options can be specified Explanation The ricdump utility only accepts four A options at one time Action Retry the command with four or fewer A options Source Dump RICO076 User must have root authority to execute ricmbx Explanation ricmbx requires root authority for execution Action Login with root authority and reissue the command Source Mailbox Process RICO079 Unable to register hardware for card nn Explanation The driver was unable to register hardware information with the operating system Conflicting settings and or unsupported hardware options may be the cause of the problem Action Verify adapter configuration and check that the operating system is at the required install level Source Novell Driver RICO080 Warning Unsupported option xxxxxxxx Explanation The parameter xxxxxxxx is not supported Action No action is needed because the parameter xxxxxxxx is ignored
313. ter is located above the 16 MB line it cannot access the other adapter The Configuration utility rejects both of these configurations with the error message RICO041 In AIX the Configuration utility also prevents configuration of a pair of logical adapters if peer to peer activity is not supported on PCI adapters The error message RICO080 Warning Unsupported option xxxxxxxx is returned The system unit to card SCB pipes have to be configured prior to configuring the card to card SCB pipes Chapter 6 System Unit Utilities 207 Configuration Utility Configuration Syntax gt gt riccnfg L card num1 L path I Q card_num2 A P C config filename Figure 6 3 Configuration Utility Syntax Specifies quiet operation Normally the Configuration utility displays messages indicating the success of an operation on the standard output device In quiet mode no messages are displayed Specifies which logical cards are to be configured A set of SCB delivery pipes are configured between logical card num1 and card num2 If card num32 is not specified it is assumed to be the system unit Specifies the size in bytes of the delivery pipe The size s corresponds to the size of the delivery pipe from num1 to card num2 The size 52 corresponds to the size of the delivery pipe from card num2 to card numl The minimum size for s and 2 is 128 bytes If a size is not specified the default size is used
314. ters Arguments passed within quotes on the command line are passed as a single parameter Extraneous quotes within the argument parameter are deleted See Examples of Application Loader Calls on page 200 Blank lines within either a configuration or parameter file are discarded Within a parameter file the standard C end of line sequence is used to separate parameters Application Loader Syntax 196 gt T ricload C config filename 4 path Q card_num filename A process_args F arg_filename D cache_option K stack_size L W timeout N process_name O P priority T V S process name W timeout T U process_name Figure 6 1 Application Loader Syntax Q Specifies quiet Application Loader operation Normally the Application Loader displays messages indicating a successful or unsuccessful operation on the standard output device In quiet mode the Application Loader does not display any messages C config filename Specifies that the configuration file config filename contains a list of processes to be loaded Each line in the configuration file is treated as an individual load request If an error is encountered during the processing of the configuration file the load operation is terminated and the remaining entries are not processed card num Specifies the logical card number to be loaded filename Specifies the file containing the process to be loaded ARTIC960 Programmer s Refer
315. the process is not registered for any of the events specified in the call If the calling process is a device driver or subsystem the asynchronous event notification handler is called with the memory protection specified when the calling process issued CreateDev Otherwise the handler is called with the memory protection set in accordance with global memory protection Refer to the ARTIC960 Programmer s Guide for additional information on the use of memory protection ARTIC960 Programmer s Reference RegisterAsyncHandler Register an Async Handler Asynchronous Event Notification Handler The AsyncHandler should be thought of as an interrupt handler It has access to the same subset of services as an interrupt handler An AsyncHandler should accept one parameter a pointer to an asynchronous event notification record and should not return a return value The record is defined as follows struct RIC_AsyncEvent RIC_ULONG Class RIC_ULONG IntStat RIC_PROCESSID ProcessID RIC ULONG Type union struct RIC ProcessorEvent Pr struct RIC AdapterEvent Ad struct RIC SoftwareEvent Sw ClassInfo where Class Is the event class Valid values are AEN_CLASS_SOFTWAR AEN_CLASS_ADAPTER AEN_CLASS_PROCESSOR Gl IntStat Set to 1 if fault occurred during an interrupt or a handler ProcessID 1 of the process that caused the event Type Type of event within the Class Refe
316. the device driver library code kernel and base subsystems Functional Prototype RIC_ULONG RICGetVersion RIC_HANDLE Handle RIC_ULONG VersionLen RIC_VERDATA VersionData RIC_ULONG Reserved Parameters Handle Input The handle for the ARTIC960 adapter VersionLen Input The length of the buffer provided for the returned version information Cannot be greater than 64K 1 bytes VersionData Input The address of a buffer in system unit memory to receive the version information This is a 32 bit logical address Reserved Input Reserved parameter must be 0 Returns RC SUCCESS RC INVALID RESERVED PARM RC BUFFER TOO SMALL RC INVALID SIZE RC INVALID MEM ACCESS RC SU INVALID HANDLE Remarks If the kernel or subsystems are not loaded or the adapter is inaccessible reporting an exception being reset and so forth this service returns 0 in the corresponding RIC VERDATA field For more details on the information returned by this structure see RIC_VERDATA Structure on page 292 The return code RC INVALID MEM ACCESS cannot be received in OS 2 If the driver detects an access violation OS 2 terminates the process with a trap unless the application has an exception handler registered with OS 2 Chapter 7 System Unit APIs 273 RICGetException Get Exception Status RICGetException Get Exception Status 274 This routine is used to query and wai
317. the element is removed from the queue the semaphore associated with the queue is decremented Functional Prototype RIC_ULONG GetQueue RIC_QUEHANDLE QueueHandle void Element RIC_TIMEOUT Timeout RIC_ULONG OptionWord RIC_ULONG QueueStatus RIC_ULONG Reserved Parameters QueueHandle Input Handle of queue to get element from Element Output Pointer to element removed from the queue Timeout Input Size of time to wait for queue element Wait indefinitely Return immediately if there are no queue elements Any other value from 1 to 65535 Wait time in milliseconds The granularity of the timer is five milliseconds The timeout value is rounded up to the next multiple of five if it is not already a multiple of five OptionWord Input Bit field that gives receive options EAD his bit should be set if the process wants only to peek at the top element f the queue without removing it from the queue The queue element is removed from the queue QUE 2 Q O QUE QueueStatus Output Returns the status of the queue QUE_EMPTY If returned the queue went from not empty to empty QUE_NOT_EMPTY If returned the queue still has at least one element in the queue Reserved Input Reserved parameter must be 0 ARTIC960 Programmer s Reference GetQueue Get or Peek at an Element a Queue
318. the mailbox process Source Mailbox Process RIC0049 Unable to install interrupt handler for card nn Explanation The driver could not allocate the interrupt level for card nn The driver allocates interrupt levels with the share option Therefore another device has already allocated this interrupt level exclusively or more than four cards tried to share the interrupt level Action For micro channel change the interrupt level for card nn using the reference diskette For PCI this message indicates that a driver loaded prior to the ARTIC960 driver is claiming an interrupt as non shared Install an updated driver that claims the interrupt as shared for this other device Source OS 2 Driver RIC0050 Resource xxxxxxxx already in use Explanation The process is unable to create xxxxxxxx because it is already being used by another person Action Terminate any other process using this resource Source Mailbox Process RIC0051 XXXXxxxx already started on system unit Explanation The process xxxxxxxx was already running on the host machine Action Either stop and restart the process or let it run Source Mailbox Process RIC0052 Unable to set System Clock on card nn Explanation The system clock could not be set on card nn Action Load the base device driver on the card Source Application Loader RIC0053 System Clock successfully started on card nn Explanation The system clock was successfully started on card nn Action None So
319. to assign to the created process The kernel s subsystems have process names beginning with RIC_ User process names should not begin with this prefix EntryPoint Input Address of the entry point of the created process StackSize Input Size of stack to be allocated for the created process If this parameter is the kernel allocates the default size stack ParamPtr Input Pointer to a parameter area passed to created process ParamSize Input Size of parameter area Priority Input The priority of the created process set by creating process 0 means use the default priority as specified in the kernel configuration parameter DEFAULT PRIORITY OptionWord Input A bit field of options for creating a process The constants for the following options should be ORed together to build the appropriate set of options Process start option CREATE AND NO START Creates a peer process without issuing a start CREATE AND START Starts the process after it is created This is the default Stack cache option CREATE CACHE STACK By default the stack is not cached To designate the stack as cacheable can be ORed into the option word This option is ignored if a data cache is not present on the adapter or if a data cache has not been enabled through the kernel configuration DATA CACHE parameter ARTIC960 Programmer s Reference CreateProcess Create a Process Data cache opt
320. totype RIC ULONG SetProcMemProt RIC PROCESSID ProcessID void BlockPtr ULONG Size RIC ULONG Access RIC ULONG Reserved Parameters ProcessID Input Process ID of process whose access is to be set BlockPtr Input Pointer to a block of memory Size Input Size of block of memory in bytes Access Input New access rights to memory The MEM DCACHE and MEM BIG ENDIAN options are ignored by this service See the Remarks section of CreateMem Allocate Memory on page 64 for more information Reserved Input Reserved parameter must be 0 Returns RC SUCCESS RC INVALID ADDRESS RC INVALID RESERVED PARM RC NOT DD OR SS RC INVALID PROCESSID RC INVALID OPTION Remarks If the kernel has been loaded with memory protection enabled the access rights to the referenced memory block change for the given process Only a single set of daughter card and system bus access flags are kept They are not stored on a per process basis Therefore setting these two sets of access flags affect all processes This service is available only to device drivers and subsystems so they can gain access to client memory areas Chapter 3 Base Kernel Services 71 QueryMemProt Query Memory Protection QueryMemProt Query Memory Protection 72 This service queries the memory protection of a block of memory Functional Prototype RIC_ULONG QueryMemProt void BlockPtr Parameters RIC_ULONG
321. tructure get data from 28 RPInfo 45 S sample format trace call 278 formatted dump 226 loader calls 200 SCB subsystem control block configuration 6 Configuration utility 207 file ric scb rel 2 parameters 6 search queue for element 02 SearchQueue Search a Queue for an Element 02 semaphore closing deleting 55 creating 5 get count 56 name 5 opening 52 releasing 54 requesting 55 set count 57 types 50 semval AIX variable 278 SendMbx Send a Message 0 284 sequence translation rules 798 service class names 2 7 services AllocHW 134 AllocVector 28 AllocVectorMux 29 CloseDev 726 CloseEvent 60 CloseMbx 114 CloseMem 68 CloseQueue 97 CloseSem 53 CloseSig 719 CloseSwTimer 85 CollectMeM 82 CompleteInit 23 CreateDev 722 CreateEvent 58 CreateMbx 04 CreateMem 64 CreateProcess 34 CreateQueue 95 CreateSem 5 CreateSig 715 CreateSwTimer 84 DeregisterAsyncHandler 45 Index 339 DeregisterHook 48 DisableTrace 52 Dispatch 49 EnableTrace 5 EnterCritSec 47 ExitCritSec 48 FreeMbxBuffer 09 FreeMem 8 FreeSuballoc 78 GetMbxBuffer 08 GetProcessData 46 GetQueue 00 GetSuballoc 77 GetSuballocSize 79 InitSuballoc 75 InitTrace 50 InvokeDev 27 InvokeSig 20 LogTrace 53 MallocMem 80 OpenDev 25 OpenEvent 59 OpenMbx 06 OpenMem 67 OpenQueue 96 OpenSem 52 OpenSig 7 PutQueue 98 QueryCardInfo 28 QueryConfigParams 3 QueryFreeMem 74 QueryHW 37 QueryMemProt 72 QueryPriority 43 QueryPro
322. try QueueHandle integer Exit rc integer P SEARCHQUEUE SearchQueue Entry QueueHandle integer Exit rc integer Table 3 12 Service Class C SEMAPHORE SERVICE Trace Format of Procedure ID Kernel Service Position Trace Data Data P CREATESEM CreateSem Entry SemName character Exit rc integer P OPENSEM OpenSem Entry SemName character Exit rc integer P CLOSESEM CloseSem Entry SemHandle integer Exit rc integer P RELEASESEM ReleaseSem Entry SemHandle integer Exit rc integer P REQUESTSEM RequestSem Entry SemHandle integer Exit rc integer P QUERYSEMCOUNT QuerySemCount Entry SemHandle integer Exit rc integer P SETSEMCOUNT SetSemCount Entry SemHandle integer Exit rc integer 160 ARTIC960 Programmer s Reference Kernel Trace Information Table 3 13 Service Class C_SIGNAL_SERVICE Trace Format of Procedure ID Kernel Service Position Trace Data Data P_CREATESIG CreateSig Entry SigName character Exit rc integer P_OPENSIG OpenSig Entry SigName character Exit rc integer P_INVOKESIG InvokeSig Entry SigHandle integer Exit rc integer P_CLOSESIG CloseSig Entry SigHandle integer Exit rc integer Table 3 14 Service Class C SUBALLOC SERVICE Trace Format of Procedure ID Kernel Service Position Trace Data Data P_GETSUBALLOCSIZE GetSuballocSize Entry UnitSize integer Exit rc integer P_INITSUBALLOC InitSuballoc Entry BlockPtr integer Exit
323. turns an error Status Output If the return code is RC SUCCESS this field is set to indicate the allocation status of the hardware device HW AVAILABLI Resource is available HW NOT AVAILABLE Resource is not available POSTStatus Output A zero in this field indicates this device completed POST successfully A non zero value is device specific but indicates that an error occurred during POST DeviceDataPtr Output Pointer to a buffer to which the kernel copies device dependent data see Device Dependent Data on page 135 for more information Reserved Input Reserved parameter must be 0 Returns RC_SUCCESS RC INVALID RESERVED RC NOT DD OR SS RC NAME NOT FOUND RC INVALID CALL RC INVALID MEM ACCESS RC INVALID NAM RC BUFFER SMALL Lu Remarks None Chapter 3 Base Kernel Services 137 Asynchronous Event Notification Services Asynchronous Event Notification Services The following are the asynchronous event notification services Service Name Page RegisterAsyncHandler 139 DeregisterAsyncHandler 145 Refer to the ARTIC960 Programmer s Guide for additional information 138 ARTIC960 Programmer s Reference RegisterAsyncHandler Register an Async Handler RegisterAsyncHandler Register an Async Handler This service registers the asynchronous event notification handler of a process for specified events
324. tus Utility Memory Display ARTIC960 Programmer s Reference Status Interactive Messages 5 Process Details The following screen shows the prompts and items displayed when the Process Details option is chosen from the main menu Valid process states are loaded queued blocked driver suspended wait on PMRq stopped expired Valid process types are normal driver subsystem kernel An expired process is one that has been stopped and unloaded from the adapter If a process is in the stopped or expired state the Process Details submenu also shows termination status information process can be terminated because of the following events Process Terminated by Software Event on page 234 Process Terminated by Processor Event on page 235 Process Terminated by Adapter Event on page 236 See Figure 6 48 on page 254 for an example 3 N Enter adapter number gt Enter process name or ID gt ame SSSSSSSSSSSSSSSS ID nnnnnnnn Priority nnnnnnnn Entry point nnnnnnnn Stack pointer nnnnnnnn Param pointer nnnnnnnn State SSSSSSSSSSS Version nnnnnnnn Type SSSSSSSSSSS Figure 6 22 Status Utility Process Details Display Chapter 6 System Unit Utilities 233 Status Interactive Messages 234 Process Terminated by Software Event The following screen shows prompts and items displayed when the Process Details option is chosen from the main menu the process is in a stopped or expired st
325. ubsystem or device driver It also deregisters a device driver or subsystem Functional Prototype RIC_ULONG CloseDev RIC DEVHANDLE DDHandle RIC ULONG Reserved Parameters DDHandle Input Handle of subsystem or device driver to close Reserved Input Reserved parameter must be 0 Returns RC SUCCESS RC CALL TERMINATED RC INVALID RESERVED PARM RC INVALID HANDLE RC INVALID MEM ACCESS RC INVALID CALL I Remarks When this service is issued by a process that had previously issued an OpenDev for the subsystem or device driver the kernel gives control to the subsystem or device driver at the CloseEntry entry point with the parameters specified on page 124 If this service is called by the subsystem or device driver itself using the handle received from CreateDev access to the subsystem or device driver is removed and all other processes having access to this subsystem or device driver are notified through an asynchronous event notification In this case the CloseEntry function is not called Return codes returned by the CloseEntry point of a subsystem or device driver are passed back to the calling process as the return code of CloseDev These return codes must be either RC SUCCESS or in the range OxFFFF0000 to OxFFFFFFFF Return codes outside this range are discarded The kernel removes the access of the process to the subsystem or device driver even if CloseEntry f
326. um Command number unique to each kernel command RespMbxID ID returned on RegisterResponseMbx that indicates the mailbox where the command response is to be sent CorrelationID Value that is passed on with the command and is not interpreted by the kernel The requester can use the field to correlate command responses ReturnCode Reserved field must be 0 Reserved Resereved field must be 0 ARTIC960 Programmer s Reference Responses Like commands responses have a common header with a variant part unique to each response Some responses have no variant part The format is struct RIC_KernResponse RIC_ULONG CorrelationID RIC ULONG ReturnCode RIC ULONG Reserved union struct RIC_RegisterResponseMbxResp Resp0 struct RIC QueryProcessStatusResp Respl Resp H where CorrelationID Value passed in the command The field can be used to correlate command responses ReturnCode Return code returned by the kernel to indicate the completion status of the command Reserved Reserved field must be 0 If a bad RespMbxID is passed on a command the kernel ignores the command and a timeout on the reply occurs Chapter 4 Kernel Commands 165 RegisterResponseMbx Register a Command Response Mailbox RegisterResponseMbx Register a Command Response Mailbox 166 This command returns the response mailbox ID associated with the specified response mailbox name Command Parameters
327. urce Application Loader Appendix B Message File 303 RICO054 RICO061 RIC0054 Entry Point Data BSS Stack Parameters Oxnnnnnnnn Explanation Additional information about the task being loaded Values are all in hexadecimal Action None Source Application Loader RIC0055 Timeout trying to configure with card nn Explanation There was a timeout waiting for a response from card nn Action Reset the adapter and reconfigure Also make sure all of the necessary subsystems are loaded on the card before attempting to configure the SCB pipes Source Configuration RICO056 nnn percent complete Explanation nnn Percent complete of the dump Action None Source Dump RIC0057 XXXXXXXX successfully loaded on card nn Process Name yyyyyyyy Process ID Oxnnnnnnnn Explanation The file xxxxxxxx was successfully loaded on logical card nn The process name is yyyyyyyy and the process ID is Oxnnnnnnnn hex Action None Source Application Loader RIC0059 Peer communications between card nn and system unit successfully configured Explanation Peer communications between card nn and the system unit were successfully configured Action None Source Configuration RICO060 Card nn and system unit area already configured Explanation Communications between card nn and the system unit area alrea
328. urn a flag as the function value indicating what the kernel should do next 0 Indicates that the kernel should call the rest of the receiving processes in the chain 1 Indicates that the kernel should give control back to the calling process immediately For normal processes when the handler is called memory protection is turned on if global memory protection is enabled For device drivers and subsystems the state of memory protection depends on the OptionWord specified in CreateDev A signal can have multiple receiving processes Each can be distinguished with the SigHanID Calling processes can also be receiving processes for the same signal ARTIC960 Programmer s Reference OpenSig Open a Signal OpenSig Open a Signal This service opens a signal and optionally registers a signal handler Functional Prototype RIC_ULONG OpenSig char SigName SIGHANLDER EntryPoint RIC ULONG OptionWord RIC ULONG SigHanID RIC SIGHANDLE SigHandle RIC_ULONG Reserved Parameters SigName Input Name of signal to access EntryPoint Input Entry address on which user gets control on calling of the signal If this parameter is NULL the calling process does not get control through this signal It gets only a handle back in SigHandle which it can use in calling the signal OptionWord Input Describes how to receive a signal This parameter is valid only if the EntryPoint parameter is not NULL SIG_CONTROL_ALWAYS Callin
329. ver options OPTION DEV DRV Registers the process as a device driver OPTION SUB SYS Registers the process as a subsystem OPTION PROT ON Turns on memory protection before the kernel gives control to the process at one of its entry points This constant does not apply to vectors owned by the subsystem or device driver OPTION PROT OFF Turns off memory protection This constant does not apply to vectors owned by the subsystem or device driver ARTIC960 Programmer s Reference CreateDev Register a Subsystem or Device Driver DDHandle Output Device handle returned to the requesting process Reserved Input Reserved parameter must be 0 Returns RC_SUCCESS RC_NO_MORE_RES RC_INVALID_RESERVED_PARM RC INVALID MEM ACCESS RC INVALID NA RC INVALID CALL RC DUP RES RC INVALID OPTION Ed d Remarks An application process communicates with a subsystem or device driver using OpenDev CloseDev and InvokeDev If memory protection is enabled using the OPTION ON in OptionWord the kernel keeps the memory protection enabled and maps the subsystem or device driver s code data and application passed parameters before giving control to the subsystem or device driver Memory protection for subsystem or device driver is expected only during early development Because subsystem or device driver code is more trusted and performance will improve it is
330. y or mailbox process attempts to access an ARTIC960 adapter and the device driver is not installed Action Verify that the proper drivers are installed in the system and retry the operation Source Application Loader Dump Status Configuration Reset and Mailbox Process RIC0020 Licensed Materials Property of RadiSys RadiSys ARTIC960 Adapter Support Version n nn n Copyright RadiSys Corporation yyyy 2222 All rights reserved US Government Users Restricted Rights Use duplication or disclosure restricted by GSA ADP Schedule Contract with RadiSys Corporation XXxxxxxx initializing Explanation The driver or process xxxxxxxx is installing yyyy zzzz are the copyright years Action None This message is normally followed by a message that states that the driver is installed and running Source OS 2 driver RIC0021 XXXXXXXXX installed and running Explanation The driver or process xxxxxxxx has installed successfully Action None Source OS 2 driver and Mailbox Process RIC0022 XXXXXXXX successfully loaded from card nn Explanation The process xxxxxxxx was successfully unloaded from logical card nn Action None Source Application Loader RICO023 Process xxxxxxxx not found on card nn Explanation The process xxxxxxxx was not found on logical card nn and could not be unloaded Action Correct the process name and call the command again Source Application Loader Status 298 960 Programmer s Reference RIC0024 RICQ027
331. yProcessStatus Get the Process Status cei cecesessecescesecesceseeeeeeseeeeeesecaeceaeceseseeeeeeeeeeseeeeaes 25 QueryCardInfo Get the Card Configuration Information 28 QueryConfigParams Get the Configuration Parameters sese 31 CreateProcess Create a PEOCeSS iecit ee tint e pire ent 34 StartProcess Start a Process ede HO Dr e pesci eie teta 36 StopProcess Stop a PLrOCESS eiecit erigere ee Yee E RED dee iS 37 UnloadProcess Unload a Process eeeeeseseeeeeeeeeennen rennen enne enne nene nne 38 Contents ii SuspendProcess Suspend a Process sss ResumeProcess Resume a Process essen SetExitRoutine Set the Exit Routine for the Process SetPriority Set the Priority of the Process QueryPriority Query the Priority of the Process QueryProcessInExec Get ID of Process in Execution SetProcessData Set Process Data sese GetProcessData Get Process Data esse EnterCritSec Enter Critical Section esses ExitCritSec Exit Critical Section ssssssssss Dispatch Cause a Dispatch Cycle sss
332. ys messages indicating a successful or unsuccessful operation on the standard output device In quiet mode no messages are displayed card num Specifies the logical card number to be reset If multiple adapters are specified they are reset sequentially If multiple adapters are being reset with a single call the Reset utility continues to the next adapter if an individual adapter reset fails or if an individual adapter number is invalid The proper messages are generated for each adapter as its reset is done If any errors are detected while resetting any of the adapters the most severe error code is returned by the Reset utility These exit codes from least to most severe are RC UTIL SUCCESS RC_UTIL_INVALID_CARD_NUMBER I RC_U RESET FAILED RC U L NO ADAPTER RESPONSE other errors cause the Reset utility to end immediately with the proper error code 210 ARTIC960 Programmer s Reference Reset Utility Reset Messages and Exit Codes The contents of the message file used by all utilities are listed in Appendix B Message File on page 295 The messages used by the Reset utility are listed in Table 6 4 The Reset utility also sets its exit code value to indicate the status of the reset operation The following table correlates the exit code of the Reset utility with the reset messages Table 6 4 Reset Utility Messages and Exit Codes

RadiSys ARTIC960 Programmer`s Reference

Contents

Download Pdf Manuals

Related Search

Related Contents