Home

OPTO32 - General Standards Corporation

1. Macro Services Description OPTO32 MISC MAP PLX REGS ENABLE h This request that the option be enabled OPTO32 MISC MAP PLX REGS GET h g This requests the current setting OPTO32 MISC MAP PLX REGS SET h s This request a change to the current setting 5 4 5 Miscellaneous Parameter Strict Arguments The purpose of this parameter is to control and retrieve the setting that governs the API s handling of certain unrecognized values For example if the setting supplied when adjusting this parameter is not listed in the appropriate table below then the API can either respond with an error condition or infer the application s intent per the value that was received If Strict Argument processing is enabled then processing is terminated with an error status Otherwise the API is lenient and will try to proceed gracefully This policy is applicable to parameter processing only and applies to most parameters The following tables describe the macros associated with this parameter Macro Parameter Description OPTO32 MISC STRICT ARGUMENTS This is the identifier for this parameter Macro Values Description OPTO32 MISC STRICT ARGUMENTS DEFAULT This is the default which is lenient processing OPTO32 MISC STRICT ARGUMENTS DISABLE This refers to lenient processing OPTO32 MISC STRICT ARGUMENTS ENAB
2. Macro Values Description OPTO32 IRQ CALLBACK FUNC DEFAULT This is the default which is NULL This effectively disables the callback feature since the API has no function to call Macro Services Description OPTO32 IRQ CALLBACK FUNC GET h w g This retrieves a current function pointer OPTO32 IRQ CALLBACK FUNC RESET h w This requests that the function pointer for the referenced interrupts be set to the default value OPTO32 IRQ CALLBACK FUNC SET h w s This requests a function pointer change OPTO32 IRO CALLBACK FUNC XXX GET h g This retrieves the current interrupt XXX function pointer OPTO32 IRQ CALLBACK FUNC XXX RESET h This requests an interrupt XXX function pointer change to its default OPTO32 IRQ CALLBACK FUNC XXX SET h s This requests an interrupt XXX function pointer change E Q o The XXX portion of these macros refers individually to COS 00 through COS_23 and RI 5 3 3 Interrupt Parameter COS 23 Event Counter The purpose of this parameter is to control and report the COS 23 Receive Event Counter value This feature counts low to high state changes on the COS 23 input If the interrupt is enabled an interrupt is generated when the count rolls over from OxFFFF to 0x0 Applying a setting updates the current count and reporting the setting retrieves the current
3. 5 4 1 Miscellaneous Parameter LED The purpose of this parameter is to control and report the state of the LED located near the cable interface This parameter turns the LED on and off The following tables describe the macros associated with this parameter Macro Parameter Description OPTO32 MISC LED This is the identifier for this parameter Macro Values Description OPTO32 MISC LED DEFAULT This is the default which is on OPTO32 MISC LED OFF This refers to the off state OPTO32 MISC LED ON This refers to the on state 40 General Standards Corporation Phone 256 880 8787 OPTO32 Software Development Kit Reference Manual Macro Services Description OPTO32 MISC LED GET h g This requests the current setting OPTO32 MISC LED OFF h This requests that the LED be turned off OPTO32 MISC LED ON h This requests that the LED be turned on OPTO32 MISC LED RESET h This requests that the LED be set to its default state OPTO32 MISC LED SET h s This requests a change to the current setting 5 4 2 Miscellaneous Parameter GSC Register Mapping The purpose of this parameter is to control and report the mapping of GSC registers into application and API memory space This parameter should always be enabled even if unused by applications If it is disabled the API s access to OPTO32
4. 5 3 1 Interrupt Parameter Callback Argument The purpose of this parameter is to modify and report the application provided argument that the application receives as arg2 during an interrupt callback event In the opto32 config service interrupt selections are made using individual OPTO32 WHICH XXX bits Here XXX is any of the predefined interrupt selection options The following tables describe the macros associated with this parameter NOTE Applications must remember that the macros GSC NO CHANGE and GSC DEFAULT have special meaning when applying parameter modifications If the application specific value being supplied for this parameter happens to equal either of these values then the results will be according to the API s use of these special values rather than the applications intent NOTE This parameter can be accessed and altered during the callback but the callback must return before subsequent callbacks can be made on the same interrupt Macro Parameter Description OPTO32 IRQ CALLBACK ARG This is the identifier for this parameter Macro Values Description OPTO32 IRQ CALLBACK ARG DEFAULT This is the default which is zero Macro Services Description OPTO32 IRQ CALLBACK ARG GET h w g This retrieves a current setting OPTO32 IRQ CALLBACK ARG RESET h w This requests that the setting for the referenced interrupts be set to
5. GSC PLX 9080 DMAPADR1 DMA Channel 1 PCI Address Register DMAPADRI GSC PLX 9080 GSC PLX 9080 GSC PLX 9080 MASIZO DMA Channel 0 Transfer Size Register DMASIZO MASIZ1 DMA Channel 1 Transfer Size Register DMASIZ1 MATHR DMA Threshold Register DMATHR Message Queue Registers The following table gives the set of PLX Messaging Queue Registers For detailed definitions of these registers refer to the PCI9080 Data Book Macros Description GSC PLX 9080 IFHP Inbound Free Head Pointer Register IFHPR GSC PLX 9080 IFTP Inbound Free Tail Pointer Register IFTPR GSC PLX 9080 TOP Inbound Queue Port Register IQP go Ap D D YD E Inbound Post Head Pointer Register IPHPR GSC PLX 9080 IPTP GSC PLX 9080 IPHP Inbound Post Tail Pointer Register IPTPR GSC PLX 9080 MQCR Messaging Queue Configuration Register MQCR GSC PLX 9080 OFHPR Outbound Free Head Pointer Register OFHPR GSC PLX 9080 OFTP Outbound Free Tail Pointer Register OFTPR GSC PLX 9080 OPHPR Outbound Post Head Pointer Register OPHPR o GSC PLX 9080 OPLFIM Outbound Post List FIFO Interrupt Mask Register OPLFIM GSC PLX 9080 OPLFIS Outbound Post List FIFO Interrupt Status Register OPLFIS GSC PLX 9080 OPTPR Outbound Post Tail Pointer Register OPTPR GSC PLX 9080 OOP Outbound Queue Port Register OQP GSC PLX 9080 OBAR Queue
6. PLX Technology Inc 870 Maude Avenue Sunnyvale California 94085 USA Phone 1 800 759 3735 WEB http www plxtech com 9 General Standards Corporation Phone 256 880 8787 OPTO32 Software Development Kit Reference Manual 2 Macros The OPTO32 API includes the following macros The headers also contain various other utility type macros which are provided without documentation Parameter support macros are not presented in this subsection These macros are described in section 5 beginning on page 34 2 1 API Version Number This macro defines the version number of the API s executable interface It does not refer to the SDK version number the API Library version number or the Device Driver version number Applications pass this value to the function opto32 api status page 19 which is used to verify that the application and the library are compatible Macros Description OPTO32 API VERSION This is the API s executable interface version number 2 2 Common Parameter Assignment Values The below macros define universal values understood by all parameters to have special meanings as given below Any time a parameter assignment request is being carried out use of these macros as the assignment value will produce the results given here Macros Description GSC DEFAULT Set the parameter to its default state value This is equivalent to using the explicitly defined default macro for the respectiv
7. 1XWn long status else printf COSIER Read 0x 1X n long value 0 return status 4 12 opto32_reg_write This function is the entry point to writing to an OPTO32 register The function should only be called after a successful open of the respective device via opto32_open Only the OPTO32 firmware registers those defined inside opto32_api h may be modified All PCI and PLX registers are read only Prototype U32 opto32 reg write void handle U32 reg U32 value 29 General Standards Corporation Phone 256 880 8787 OPTO32 Software Development Kit Reference Manual Argument Description handle This is an API device handle obtained via opto32 open reg This is the register to access value This is the value to write to the specified register Return Value Description GSC SUCCESS The operation succeeded Otherwise A GSC XXX error status reflecting the problem encountered Example tinclude lt stdio h gt include opto32 api h include opto32 dsl h U32 opto32 dsl cosier write void handle U32 value int verbose U32 status status opto32 reg write handle OPTO32 COSIER value if verbose else if status GSC SUCCI E SS printf opto32 reg write failure Ox 1XMn long else printf COSIER Write 0x 1X n long value return status 4 1
8. All OPTO32 interrupts are temporarily disabled while the Debounce Divisor is being set Macro Parameter Description OPTO32 COS DEBOUNCE PERIOD MS This is the identifier for this parameter FU 35 General Standards Corporation Phone 256 880 8787 OPTO32 Software Development Kit Reference Manual Macro Values Description OPTO32 COS DEBOUNCE PERIOD MS DEFAULT This is the default period The minimum is the default OPTO32 COS DEBOUNCE PERIOD MS MAX This is the maximum period that may be requested which is two minutes OPTO32 COS DEBOUNCE PERIOD MS MIN This is the minimum period that may be requested which is zero Zero corresponds to a period of 600 nanoseconds Macro Services Description OPTO32 COS DEBOUNCE PERIOD MS GET h g This retrieves the current period OPTO32 COS DEBOUNCE PERIOD MS RESET h This requests the default period OPTO32 COS DEBOUNCE PERIOD MS SET h s This requests a specified period 5 2 3 COS Parameter Debounce Period In Microseconds The purpose of this parameter is to control and report the board s debounce period in microseconds This refers to the overall debounce period which consists of three individual sampling intervals When a value 1s applied it is converted from microseconds to the closest corresponding Clock Divider value When the p
9. In these macros XXX refers collectively to 44 General Standards Corporation Phone 256 880 8787 OPTO32 Software Development Kit Reference Manual the set of macros available COS_00 through COS 23 and RECO When the function returns and the status reflects than an interrupt did occur then proceed to the steps below 3 Read debounced input from the OPTO32 For this refer to API function opto32 cos read That s all there is to it Reading the input can be done at any time The value returned will always reflect the current debounced input Applications can read the input in a polling fashion or make use of the API s interrupt notification feature as described in subsequent paragraphs 6 4 Data Output The OPTO32 requires no configuration or setup in order to post output to the cable All output is asynchronous to the write request When writing data to the OPTO32 the data immediately appears at the output or at least as soon as the hardware is able to respond A minimum hold time feature is not supported by either the hardware or the API Applications needing a minimum hold time on the output must implement support in application code 6 5 Event Notification The API Library supports event notification in the form of Interrupt Notification Notification includes both a callback mechanism and a wait mechanism Both are described below Interrupt Notification is driven by interrupts generated by the OPTO32 from any of its inte
10. count The setting refers to the current count not the number of additional events needed to generate an interrupt The number of additional events needed to generate an interrupt is defined as OxFFFF X 1 where X is the current reading The following tables describe the macros associated with this parameter Macro Parameter R This is the identifier for this parameter Macro Val OPTO32 IRQ COS 23 EVENT COUNTER DEFAULT This refers to the default which is zero OPTO32 IRO COS 23 EVENT COUNT El Macro Services Description OPTO32 IRQ COS 23 EVENT COUNTER GET h g This requests the current setting OPTO32 IRQ COS 23 EVENT COUNTER RESET h This sets the counter to its default value OPTO32 IRQ COS 23 EVENT COUNTER SET h s This requests a setting change 5 3 4 Interrupt Parameter COS Polarity The purpose of this parameter is to control and report the COS polarity used for generating interrupts This parameter controls whether a COS interrupt is generated on a rising edge or a falling edge If a setting is High to Low then generation of an interrupt is tied to detection of a high to low state transition This similarly applies for a Low to High setting The following tables describe the macros associated with this parameter Macro Parameter Description OPTO32 IRQ C
11. ee Ee ee Se See 4 11 opto32 reg read Bee Be nono ee ee Ee Ge Ge See 4 12 0opto32 reg write MY 4 13 OPtO32 0 M 4 14 0pt032_status_textl OS ARO O AAA TA 5 Configuration Parameters sissies sissies Ne es Ee erbe eed ke Orde oes cies ese ve Ge as see dL on gegee OM 5 1 Parameter Macros sides ee de ee ee Ge ee ee Ge de GE ee ee Ge ee ee Ge eg ee ee GE ed ee de ge Pe ede eT 5 1T s Parameter Definitions ox eee Ge EE E ED EE ee ee Ge Ee ee Wee EE es 5 12 Val e Definitions EE RE E d icd 51 3 Service Definitions tee Se ES eo ee tte ee eee A S123 Device Handle Ti eoe tinca 5 1 3 2 Which Bits Wii eet EER EE e cu OE OE NOK ee LMBOS MM EID CR 51 34 Get Val ez 8 ea etd SE te e ute S i e ER Nl d dte ER RI d S RATE SUUS 5 2 Change Of State Parameters esse esse esse esse ee Se eee eee essen setenta seta Ee Ee Ee GE Ge RE RE Bee Bee Be Ee nono sensns ens Ge See 5 2 1 COS Parameter Debounce Divi SOF v 25 5 eee ertet E e Ee ee E Pe E EA ees de 5 2 2 COS Parameter Debounce Period In Milliseconds sees eene nennen nennen enne 5 2 3 COS Parameter Debounce Period In Microsecondis essere eene e eene eene enne EAXQEUI slg m 5 3 1 Interrupt Parameter Callback Argument sess eene enne nnne nenn
12. firmware registers operates with reduced efficiency The following tables describe the macros associated with this parameter NOTE There are circumstances where this feature cannot be enabled and utilized This is usually limited to embedded hosts here the BIOS doesn t place all PCI memory access regions on CPU Page Size boundaries If the BIOS cannot be configured to utilize such boundaries then API performance is degraded NOTE This parameter should only be disabled for testing purposes Macro Parameter Description OPTO32 MISC MAP GSC REGS This is the identifier for this parameter Macro Values Description OPTO32 MISC MAP GSC REGS DEFAULT This is the default which is enabled OPTO32 MISC MAP GSC REGS DISABLE This refers to the disabled state When disabled access to firmware registers must go through the Device Driver which reduces efficiency OPTO32 MISC MAP GSC REGS ENABLE This refers to the enabled state When enabled access to firmware registers is done entirely within the API which increases efficiency Macro Services See section 5 1 3 page 34 Description OPTO32 MISC MAP GSC REGS DISABLE h This requests that the option be disabled OPTO32 MISC MAP GSC REGS ENABLE h This requests that the option be enabled OPTO32 MISC MAP GSC REGS
13. or gsc gsc pci9080 h This header contains register definitions for the PCI9080 which is the PCI interface chip used on OPTO32s All items defined here have a prefix of GSC or gsc and include 9080 opto32 api h This header contains the bulk of the API including function calls data types and numerous macros All items defined here include the prefix OPTO32 or opto32 7 General Standards Corporation Phone 256 880 8787 OPTO32 Software Development Kit Reference Manual 1 6 Software Overview The software interface to the OPTO32 consists of a Device Driver and an API Library the primary components of the SDK The Device Driver operates under control of the operating system and must be loaded and running in order to access any installed OPTO32 devices The interface provided by the API Library is based on the board s functionality and is organized around the OPTO32 s set of main hardware features The general categories are as follows and permit access to and manipulation of virtually every feature available on the board e General Access Services API Status Version Numbers Board Count Open Close e Change of State Configuration e Other Miscellaneous Configuration e Interrupt Notification and Configuration All OPTO32 features are individually accessible via a generalized configuration service For each parameter as appropriate the API includes a set of support macros T
14. other use no part of this document may be copied or reproduced in any form or by any means without prior written consent of General Standards Corporation GSC is a trademark of General Standards Corporation PLX and PLX Technology are trademarks of PLX Technology Inc 3 General Standards Corporation Phone 256 880 8787 OPTO32 Software Development Kit Reference Manual Table of Contents A TN 1 1 A NN 7 1 2 ur Mi UN 7 1 3 Definitions GE J 7 TEE M D eT ESOO Ipso 7 1 5 Application Programming Interface seesesseeseseeeoesesoeseeeoeseseoeseeceesoeeeesoeseeeoeseeoesoeeeesorsereorseeeersreoesoesereoesereeeseeeee 7 ISO RI O AAA TA 8 LLO LOLAS Arch sio 8 1 7 Hardware Overvit 8 A A TA 9 1 9 Reference Material R 9 De EILEEN ONE EE EE NE RRA ZA APE Version Number sos ss P Ge GO Gee oeeo ee GE es Ge ed Ge Se ee ed Ge ee Ge ei eg ke 10 2 2 Common Parameter Assignment Values ses sees sees see Be Ee seen seen EE Ge Ge RE BRA tasa Bee Be Ee Ee sens sens ense enne See 10 2 3 Discrete Data Type Options esse sesse esse ese ee Se SE eese eee Bee Bee Be sten sts Ee EE GE tuse suse tasa tasa Bee Be Ee Ee ee Ee enne Se See 11 2 4 Maximum Number of Open Handles Le es Bee Ge EG Ee EE GE Ee Ee GE Ee Ge Ge ee toss ee Ee Ge ee tons ee ee 12 2 5 Paramieter Access Which Bits iere eines seges de
15. succeeded the status was retrieved Otherwise A GSC XXX error status reflecting the problem encountered Example tinclude lt stdio h gt include opto32 api h tinclude opto32 dsl h U32 opto32 dsl api status int verbose U32 arg U32 stat U32 status status opto32 api status amp stat arg OPTO32 API VERSION if verbose else if status GSC_SUCCESS printf opto32 api status failure 0x 1X n long status 19 General Standards Corporation Phone 256 880 8787 OPTO32 Software Development Kit Reference Manual else status stat printf API Status n printf Status OxS1X n long stat printf Argument 0x 1X n long arg return status 4 2 opto32_board_count This function is the entry point to determine the number of OPTO32 boards installed in the system and accessible to the API This service can be called without requiring access to any particular device Prototype U32 opto32 board count U8 count Argument Description count The API records the number of boards at this location This pointer must not be NULL Return Value Description GSC_SUCCESS The operation succeeded Otherwise A GSC XXX error status reflecting the problem encountered Example tinclude lt stdio h gt include opto32 api h tinclude opto32 dsl h U32 opto32 dsl board count U8
16. the default value OPTO32 IRQ CALLBACK ARG SET h w s This requests a setting change to the referenced interrupts OPTO32 IRQ CALLBACK ARG XXX GET h g This retrieves the current interrupt XXX setting OPTO32 IRO CALLBACK ARG XXX RESET h This requests an interrupt XXX setting change to its default BACK ARG XXX SET h s This requests an interrupt XXX setting change OPTO32 IRQ CA The XXX portion of these macros refers individually to COS 00 through COS 23 and RECO 5 3 2 Interrupt Parameter Callback Function The purpose of this parameter is to modify and report the application provided callback function pointer for an interrupt callback event This parameter tells the API which application supplied function to call when an interrupt occurs In the opto32 config service he interrupt selections are made using individual OPTO32 WHICH XXX bits Here XXX is any of the predefined interrupt selection options The following tables describe the macros associated with this parameter NOTE This parameter can be accessed and altered during the callback but the callback must return before subsequent callbacks can be made on the same interrupt 37 General Standards Corporation Phone 256 880 8787 OPTO32 Software Development Kit Reference Manual Macro Parameter Description OPTO32 IRQ CALLBACK FUNC This is the identifier for this parameter
17. third group of macros performs operations on parameters These are utility macros that retrieve parameter settings and states or assign parameter values These macros include the Parameter Definition followed by a double underscore then upper case letters that reflect the action to perform For example OPTO32 MISC STRICT ARGUMENTS GET retrieves the current setting of the Miscellaneous Strict Arguments parameter These macros include arguments which are described as follows 5 1 3 1 Device Handle h In the service macros the argument h refers to the device handle used to access the respective device This handle is obtained by calling opto32 open This argument must not be NULL 5 1 3 2 Which Bits w In the service macros the argument w refers to any combination of the OPTO32 WHICH XXX bits Refer to paragraph 2 5 on page 12 With some parameters this argument is unused or is specified inside the macro s replacement text In those cases the w is not included as a macro argument 5 1 3 3 Set Value s In the service macros the argument s refers to the value to be applied to the referenced parameter With some parameters the value can be arbitrarily assigned by the application With most parameters this argument should be 34 General Standards Corporation Phone 256 880 8787 OPTO32 Software Development Kit Reference Manual one of the predefined value definitions The s is not included as a macro argument for
18. 12 PTO32 WHICH COS 13 This identifies Change Of State input number 13 PTO32 WHICH COS 14 This identifies Change Of State input number 14 PTO32 WHICH COS 15 This identifies Change Of State input number 15 PTO32 WHICH COS 16 This identifies Change Of State input number 16 PTO32 WHICH COS 17 This identifies Change Of State input number 17 PTO32 WHICH COS 18 This identifies Change Of State input number 18 PTO32 WHICH COS 19 This identifies Change Of State input number 19 PTO32 WHICH COS 20 This identifies Change Of State input number 20 PTO32 WHICH COS 21 This identifies Change Of State input number 21 PTO32 WHICH COS 22 This identifies Change Of State input number 22 PTO32 WHICH COS 23 This identifies Change Of State input number 23 PTO32 WHICH COS ALL This identifies all of the Change Of State inputs PTO32 WHICH IRO ALL This identifies off interrupts sources O OIO O O O O OJO O O OJ OJ O O O O O O O OJ O O O O O 12 General Standards Corporation Phone 256 880 8787 OPTO32 Software Development Kit Reference Manual OPTO32 WHICH RE CO This identifies the Receive Event Counter interrupt source 2 6 Registers The following tables give the complete set of OPTO32 registers The tables are divided by register categories There are PCI registers PLX feature set registe
19. 3 opto32_reset This function is the entry point to perform a device hardware reset The function should only be called after a successful open of the respective device via opto32 open WARNING The API performs a variety of actions during this call that are in addition to resetting the hardware This is necessary for proper API operation If an application initiates a hardware reset by writing to the various registers the results may not be identical Prototype U32 opto32 reset void handle Argument Description handle This is an API device handle obtained via opto32 open Return Value Description GSC SUCCESS The operation succeeded 30 General Standards Corporation Phone 256 880 8787 OPTO32 Software Development Kit Reference Manual Otherwise A GSC XXX error status reflecting the problem encountered Example tinclude lt stdio h gt include opto32 api h tinclude opto32 dsl h U32 opto32 dsl reset void handle int verbose U32 status status opto32 reset handle if verbose else if status GSC_SUCCI E SS printf opto32 reset failure Ox 1XWMn long status else printf Device Reset 0x 1X n long handle return status 4 14 opto32_status_text This function is the entry point to retrieving a text based description of the status values supported by the SDK Prototype U32 opto32
20. A GSC XXX error status reflecting the problem encountered Example tinclude lt stdio h gt include opto32 api h include opto32 dsl h U32 opto32 dsl cos read void handle U32 value int verbose U32 status status opto32 cos read handle value if verbose else if status GSC_SUCCESS printf opto32 cos read failure ld n long status else printf COS Read 0x 061X n long value 0 return status 23 General Standards Corporation Phone 256 880 8787 OPTO32 Software Development Kit Reference Manual 4 6 opto32_cos_write This function is the entry point to writing to the cable s output signals The function should only be called after a successful open of the respective device via opto32 open Prototype U32 opto32 cos write void handle U8 value Argument Description handle This is an API device handle obtained via opto32 open value This is the value to write Return Value Description GSC SUCCESS The operation succeeded Otherwise A GSC XXX error status reflecting the problem encountered Example tinclude lt stdio h gt include opto32 api h include opto32 dsl h U32 opto32 dsl cos write void handle U8 value int verbose U32 status status opto32 cos write handle value if verbose else if status GSC_SUCCESS printf opto32 c
21. All are resumed when a referenced event occurs 46 General Standards Corporation Phone 256 880 8787 OPTO32 Software Development Kit Reference Manual Document History Revision Description August 18 2005 Initial release 47 General Standards Corporation Phone 256 880 8787
22. Base Address Register QBAR GSC PLX 9080 OSR Queue Status Control Register QSR 15 General Standards Corporation Phone 256 880 8787 OPTO32 Software Development Kit Reference Manual 2 7 Version Data Selectors This set of macros is used when requesting a version number and indicates which version number is desired The macros are passed as the id argument to the opto32 version get function see page 32 The second table below lists utility macros used to retrieve each of the respective version numbers In the second table the argument h refers to the handle used to access the device the b refers to an application buffer where the version string is recorded and the s is the size of that buffer Macros Values Description GSC VERSION LIBRARY This requests the library s version number GSC_VERSION DRIVER This requests the driver s version number Macro Services Description OPTO32 VERSION GET LIBRARY h b s This requests the version number for the API Library OPTO32 VERSION GET DRIVER h b s This requests the version number for the Device Driver 16 General Standards Corporation Phone 256 880 8787 OPTO32 Software Development Kit Reference Manual 3 Data Types The interface includes the following data types 3 1 Discrete Data Types The following discrete data types are defined and used by the API If an OPTO32 application includes other headers
23. For example to enable or disable the COS 0 interrupt the which value passed with the OPTO32 IRO ENABLE parameter must be OPTO32 WHICH COS 00 When appropriate bits within the same category may be bitwise or d in order to apply the action to multiple objects For retrieval purposes the retrieved setting may reflect the setting of the first item accessed the last item accessed or all items collectively The bits use is explained along with the parameters that each 1s associated with and appears in subsequent portions of this document Macros Description PTO32 WHICH COS 00 This identifies Change Of State input number 0 PTO32 WHICH COS 01 This identifies Change Of State input number 1 PTO32 WHICH COS 02 This identifies Change Of State input number 2 PTO32 WHICH COS 03 This identifies Change Of State input number 3 PTO32 WHICH COS 04 This identifies Change Of State input number 4 PTO32 WHICH COS 05 This identifies Change Of State input number 5 PTO32 WHICH COS 06 This identifies Change Of State input number 6 PTO32 WHICH COS 07 This identifies Change Of State input number 7 PTO32 WHICH COS 08 This identifies Change Of State input number 8 PTO32 WHICH COS 09 This identifies Change Of State input number 9 PTO32 WHICH COS 10 This identifies Change Of State input number 10 PTO32 WHICH COS 11 This identifies Change Of State input number 11 PTO32 WHICH COS 12 This identifies Change Of State input number
24. GET h g This requests the current setting OPTO32 MISC MAP GSC REGS RESET h This requests that the default be selected OPTO32 MISC MAP GSC REGS SET h s This requests a change to the current setting 5 4 3 Miscellaneous Parameter GSC Register Mapping Pointer The purpose of this read only parameter is to retrieve the pointer the API uses for direct access to OPTO32 firmware registers If the GSC Register Mapping feature is enabled the application can use the pointer to directly access OPTO32 firmware registers If disabled the pointer returned is NULL The following tables describe the macros associated with this parameter NOTE There are circumstances where this feature cannot be utilized This is usually limited to embedded hosts here the BIOS doesn t place all PCI memory access regions on CPU Page Size boundaries If the BIOS cannot be configured to utilize such boundaries then API performance is degraded Macro Parameter Description OPTO32 MISC MAP GSC RI EGS PTR This is the identifier for this parameter 41 General Standards Corporation Phone 256 880 8787 OPTO32 Software Development Kit Reference Manual Macro Services See section 5 1 3 page 34 Description OPTO32 MISC MAP GSC REGS PTR GET h g This requests the current pointer 5 4 4 Miscellaneous Parameter PLX Register Mapping The purpose of this parameter is to control and r
25. GSC PLX 9080 MBOX3 Mailbox Register 3 MBOX3 GSC PLX 9080 MBOX4 Mailbox Register 4 MBOX4 GSC PLX 9080 MBOX5 Mailbox Register 5 MBOX5 GSC PLX 9080 MBOX6 Mailbox Register 6 MBOX6 GSC PLX 9080 MBOX7 Mailbox Register 7 MBOX7 GSC PLX 9080 P2LDBELL PCI to Local Doorbell Register P2LDBELL GSC PLX 9080 PCIHIDR PCI Permanent Configuration ID Register PCIHIDR GSC PLX 9080 PCIHREV PCI Permanent Revision ID Register PCIHREV DMA Registers The following table gives the set of PLX DMA Registers For detailed definitions of these registers refer to the PCI9080 Data Book These register definitions are provided for informational purposes only as the OPTO32 implements no features that might use DMA Macros Description GSC PLX 9080 DMAARB DMA Arbitration Register DMAARB GSC PLX 9080 DMACSRO DMA Channel 0 Command Status Register DMACSRO ESE PLX 9080 DMACSR1 DMA Channel 1 Command Status Register DMACSRI GSC PLX 9080 DMADPRO DMA Channel 0 Descriptor Pointer Register DMADPRO GSC PLX 9080 DMADPR1 DMA Channel 1 Descriptor Pointer Register DMADPRI GSC PLX 9080 DMALADRO DMA Channel 0 Local Address Register DMALADRO GSC PLX 9080 DMALADRI DMA Channel 1 Local Address Register DMALADRI GSC PLX 9080 DMAMODEO DMA Channel 0 Mode Register DMAMODEO GSC PLX 9080 DMAMODE1 DMA Channel 1 Mode Register DMAMODE GSC PLX 9080 DMAPADRO DMA Channel 0 PCI Address Register DMAPADRO
26. LE This refers to strict processing T 42 General Standards Corporation Phone 256 880 8787 OPTO32 Software Development Kit Reference Manual Macro Services Description OPTO32 MISC STRICT ARGUMENTS GET h g This requests the current setting OPTO32 MISC STRICT ARGUMENTS NO h This requests lenient processing OPTO32 MISC STRICT ARGUMENTS RESET h This requests that the setting be changed to its default value OPTO32 MISC STRICT ARGUMENTS SET h s This requests a setting change OPTO32 MISC STRICT ARGUMENTS YES h This requests strict processing 5 4 6 Miscellaneous Parameter Strict Configuration The purpose of this parameter is to control and retrieve the setting that governs the API s handling of certain invalid configurations For example if the setting supplied when adjusting a parameter is inconsistent with the board s current configuration then the API can either respond with an error condition or try to proceed gracefully If Strict Configuration processing is enabled then processing is terminated with an error status Otherwise the API is lenient and will try to proceed gracefully This policy is applicable to parameter processing only but is NOT applicable to the OPTO32 at this time The following tables describe the macros associated with this parameter Macro Parameter Description OPTO32 MISC STRIC
27. M D R Expansion ROM Range Register EROMRR GSC PLX 9080 LASOBA Local Address Space 0 Local Base Address Register LASOBA GSC PLX 9080 LASOR R Local Address Space 0 Range Register for PCI to Local Bus LASORR GSC PLX 9080 LASIBA Local Address Space 1 Local Base Address Register LASIBA GSC PLX 9080 LASIR R Local Address Space 1 Range Register for PCI to Local Bus LASIRR GSC PLX 9080 LBRD Local Address Space 0 Expansion ROM Bus Region Descriptor Register LBRDO Local Address Space 1 Bus Region Descriptor Register LBRDI 0 GSC PLX 9080 LBRD1 GSC PLX 9080 MARBR Mode Arbitration Register MARBR Runtime Registers The following table gives the set of PLX Runtime Registers For detailed definitions of these registers refer to the PCI9080 Data Book Macros Description GSC PLX 9080 CNTRL Serial EEPROM Control CPI Command Codes User I O Init Control Register CNTRL GSC PLX 9080 INTCS R Interrupt Control Status Register INTCSR GSC PLX 9080 L2PDB ELL Local to PCI Doorbell Register L2PDBELL GSC PLX 9080 MBOXO Mailbox Register 0 MBOX0 GSC PLX 9080 MBOX1 Mailbox Register 1 MBOXI 14 General Standards Corporation Phone 256 880 8787 OPTO32 Software Development Kit Reference Manual GSC PLX 9080 MBOX2 Mailbox Register 2 MBOX2
28. OPTO32 Optically Isolated VO 24 Input 8 Output PMC OPTO32A Software Development Kit SDK 5 0 0 Reference Manual Manual Revision August 18 2005 General Standards Corporation 8302A Whitesburg Drive Huntsville AL 35802 Phone 256 880 8787 Fax 256 880 8788 URL http www generalstandards com E mail sales generalstandards com E mail support generalstandards com OPTO32 Software Development Kit Reference Manual 2 General Standards Corporation Phone 256 880 8787 OPTO32 Software Development Kit Reference Manual Preface Copyright 2005 General Standards Corporation Additional copies of this manual or other literature may be obtained from General Standards Corporation 8302A Whitesburg Dr Huntsville Alabama 35802 Phone 256 880 8787 FAX 256 880 8788 URL http www generalstandards com E mail sales generalstandards com General Standards Corporation makes no warranty of any kind with regard to this material including but not limited to the implied warranties of merchantability and fitness for a particular purpose Although extensive editing and reviews are performed before release to ECO control General Standards Corporation assumes no responsibility for any errors that may exist in this document No commitment is made to update or keep current the information contained in this document General Standards Corporation does not assume any liability arising out of the application or use of any p
29. OR to set the divisor explicitly Refer to OPTO32 COS DEBOUNCE PERIOD MS to set the debounce period in millisecond increments Refer to OPTO32 COS DEBOUNCE PERIOD US to set the debounce period in microsecond increments 2 If the input is to be read in response to an interrupt then perform the following additional steps a Ifthe input is to be read in response to a COS state change interrupt then configure the polarity of the state change desired For this refer to the utility macros for parameter OPTO32 IRQ COS POLARITY b Ifthe input is to be read in response to a specific number of low to high state changes on the COS 23 input then configure the COS 23 Event Counter for the desired number of events For this refer to the utility macros for parameter OPTO32 IRQ COS 23 EVENT COUNTER c If the input is to be read using the interrupt notification feature s callback option then configure the callback argument and the callback function parameters for the interrupts of interest For these refer respectively to the utility macros for parameters OPTO32 IRQ CALLBACK ARG and OPTO32 IRQ CALLBACK FUNC When the callback occurs proceed to the steps below d If the input is to be read using the interrupt notification feature s wait option then perform the wait for the interrupts of interest For this refer to the API function opto32 irq wait or the utility macros OPTO32 IRQ WAIT XXX h
30. OS POLARITY This is the identifier for this parameter Macro Values Description OPTO32 IRQ COS POLARITY HI LOW This refers to a High to Low state change OPTO32 IRQ COS POLARITY LOW HI This refers to a Low to High state change 38 General Standards Corporation Phone 256 880 8787 OPTO32 Software Development Kit Reference Manual OPTO32 IRQ COS POLARITY DEFAULT This refers to the default which is High to Low Macro Services Description OPTO32 IRQ COS POLARITY GET h w g This requests the current setting for the specified input s OPTO32 IRQ COS POLARITY RESET h w This requests a setting change for the specified input s to the default value OPTO32 IRQ COS POLARITY SET h w s This requests a setting change for the specified input s OPTO32 IRQ COS POLARITY XX GET h g This requests the current setting for the input number XX OPTO32 IRQ COS POLARITY XX H2L h This requests a setting change for the input number SI OPTO32 IRQ COS POLARITY XX L2H h This requests a setting change for the input number XX OPTO32 IRQ COS POLARITY XX RESET h This requests a setting change for the input number XX to its default OPTO32 IRQ COS POLARITY XX SET h s This requests a setting change for the input number XX The XX portion of these macros refers individ
31. Q ENABLE XXX RESET h This requests an interrupt XXX setting change to its default OPTO32 IRQ ENABLE XXX SET h s This requests an interrupt XXX setting change OPTO32 IRQ ENABLE XXX YES h This requests that interrupt XXX be enabled The XXX portion of these macros refers individually to COS 00 through COS 23 and RECO 39 General Standards Corporation Phone 256 880 8787 OPTO32 Software Development Kit Reference Manual 5 3 6 Interrupt Parameter State The purpose of this read only parameter is to report the state of the respective interrupt source This parameter tells whether an interrupt source is active or inactive In the opto32 config service interrupt selections are made using individual OPTO32 WHICH XXX bits Here XXX is any of the predefined interrupt selection options The following tables describe the macros associated with this parameter Macro Parameter Description OPTO32 IRQ STATE This is the identifier for this parameter E Macro Values Description OPTO32 IRQ STATE ACTIVE This reflects that the source was active c GI OPTO32 IRQ STATE INACTIVE This reflects that the source was inactive Macro Services Description OPTO32 IRQ STATE GET h w 9 This retrieves a current state OPTO32 IRQ STATE XXX GET h g This retrieves the current interrupt XXX state 7 The XXX portion of t
32. R value if verbose else if status GSC_SUCCESS printf opto32 reg mod failure 0x 1X n long else printf COSIER Modify n printf Value Ox 1XMn long value printf Mask 0Ox 1X n long mask return status 28 General Standards Corporation Phone 256 880 8787 mask status OPTO32 Software Development Kit Reference Manual 4 11 opto32_reg_read This function is the entry point to reading the value from an OPTO32 register The function should only be called after a successful open of the respective device via opto32 open All OPTO32 registers may be read Prototype U32 opto32 reg read void handle U32 reg U32 value Argument Description handle This is an API device handle obtained via opto32 open reg This is the register to access value The value read is recorded here If this is NULL then no action is taken Return Value Description GSC SUCCESS The operation succeeded Otherwise A GSC XXX error status reflecting the problem encountered Example tinclude lt stdio h gt include opto32 api h include opto32 dsl h U32 opto32 dsl cosier read void handle U32 value int verbose U32 status status opto32 reg read handle OPTO32 COSIER value if verbose else if status GSC_SUCCESS printf opto32 reg read failure Ox
33. SS HD 6 3 Data HORSE N GO E N N A P neones 6 4 Data AAA AAA IN 6 5 Event NOUFICAUOT rentre eo vete ve Xn EO da Na ISA e EA EE E 6 5 AR Ke Ee GE OE iia 6 5 1 1 Interrupt Notification Callback ee ee ee RR RA RA GR AR Re RA GRA GRA GR ee ee ee nenne RA GRA GR ee nenne 6 52 Event Waltinho censorer EE OR EE ER OE N EE EE EE OE OE e eed Document History sss ede see oi ee ee eg ee ee ee be Ge Ee Ge ee Gee ig ee oo eg A 5 General Standards Corporation Phone 256 880 8787 OPTO32 Software Development Kit Reference Manual 6 General Standards Corporation Phone 256 880 8787 OPTO32 Software Development Kit Reference Manual 1 Introduction This reference manual applies to SDK release version 5 0 0 1 1 Purpose The purpose of this document is to describe the Application Programming Interface to the OPTO32 Software Development Kit This software provides the interface between Application Software and the OPTO32 board The interface provided by the SDK is based on the board s functionality 1 2 Acronyms The following is a list of commonly occurring acronyms used throughout this document Acronyms Description API Application Programming Interface GSC General Standards Corporation PCI Peripheral Component Interconnect PMC PCI Mezzanine Card SDK Software Development Kit This is sometimes used synonymously with API or API Library 1 3 Definitions The following is a
34. T CONFIG This is the identifier for this parameter Macro Values Description OPTO32 MISC STRICT CONFIG DEFAULT This is the default which is lenient processing OPTO32 MISC STRICT CONFIG D This refers to lenient processing OPTO32 MISC STRICT CONFIG ENABLE This refers to strict processing E3 n gt UJ ES Macro Services Description OPTO32 MISC STRICT CONFIG GET h g This requests the current setting PTO32 MISC STRICT CONFIG NO h This requests lenient processing PTO32 MISC ST RICT CONFIG RE ET h This requests that the default be selected PTO32 MISC ST RICT CONFIG S O O O OPTO32 MISC ST S T h s This requests a setting change S h This requests strict processing RICT CONFIG Y 43 General Standards Corporation Phone 256 880 8787 OPTO32 Software Development Kit Reference Manual 6 Operation This section explains some operational procedures using the OPTO32 with the SDK This is in no way intended to be a comprehensive guide on using the OPTO32 This is simply to address a very few issues relating to the board s use 6 1 Overview Before accessing any OPTO32 applications first verify the state of the API by calling opto32 api status Once done access is permissible to any and all installed boards by calling opto32 open An open request returns a handle to the d
35. TO32 Software Development Kit Reference Manual return status 4 9 opto32_open This function is the entry point to open a connection to an OPTO32 board This function must be called before any other device access functions may be called If successful the device and all parameters are initialized to default settings Multiple requests can be made to access the same device and each can succeed However care must be taken when doing this as device access via one handle is likely to interfere with the device state maintained by the other Additionally one handle may configure the device in a way that conflicts with the configuration established by the other Prototype U32 opto32 open U8 index void handle Argument Description index This is the zero based index of the board to access handle If the request succeeds the API records at this address the handle to be used for subsequent access to the respective device This pointer must not be NULL The pointer returned will be NULL if the request fails and non NULL otherwise Return Value Description GSC_SUCCESS The operation succeeded Otherwise A GSC XXX error status reflecting the problem encountered Example tinclude lt stdio h gt include opto32 api h include opto32 dsl h U32 opto32 dsl open U8 index void handle int verbose U32 status status opto32 open index handle if verbose el
36. _config This function is the entry point to accessing an individual parameter where all pertinent data is given as separate arguments The function should only be called after a successful open of the respective device via opto32 open Prototype U32 opto32 config void handle 21 General Standards Corporation Phone 256 880 8787 OPTO32 Software Development Kit Reference Manual U32 parm U32 which U32 set U32 get Argument Description handle This is an API device handle obtained via opto32 open parm This is the Parameter Identifier for the parameter to be accessed which This is any number or combination of parameter specific OPTO32 WHICH XXX bits that specify the object s the parameter is applied to Many parameters ignore this argument When it 1s used a value of zero is acceptable and merely specifies to access none of the corresponding objects set This is the value to apply to the parameter being accessed The universal value GSC NO CHANGE specifies that the parameter not be altered and must be used when the purpose of the access is to get the current setting Some parameters are read only in which case this argument is ignored get After applying any changes to the parameter its current setting is recorded here When the which argument specifies multiple objects the value recorded here may be from the first object accessed the last or a collective result This argume
37. atus 2 3 Discrete Data Type Options The below macros are defined by application code as needed to enable or disable declarations for and size validation for the data types S8 U8 S16 U16 S32 and U32 see page 17 11 General Standards Corporation Phone 256 880 8787 OPTO32 Software Development Kit Reference Manual Macros Description GSC DATA TYPES CHECK If the API declares the data types and the application defines this macro then the data type sizes will be validated during the application s build process This macro should only be defined if the compiler in use supports the sizeof macro during preprocessing GSC DATA TYPES NOT NEEDED Applications should define this macro before including opto32 api h to disable the declarations for these data types 2 4 Maximum Number of Open Handles This macro defines the maximum number of device handles that can be opened at any one time All open handles are unique even if they refer to the same device though handles are reused once closed Macros Description GSC PROCESS OPEN MAX This defines the maximum number of open handles 2 5 Parameter Access Which Bits The table below lists the set of selection bits that may be set when a configuration parameter is modified or accessed They are referred to as which bits in that they specify the objects which the parameter is to access
38. configuration is returned to its default state via the opto32 reset service The configuration of the Interrupt Parameters is retained mostly within the OPTO32 firmware registers Applications have access to the OPTO32 interrupt registers but it is advised that they be accessed only through the parameter access service When using the service opto32 config any number or combination of OPTO32 WHICH XXX bits may be used even none An interrupt is accessed only if it s respective which bit is set If none is set then no action will be taken The following table summaries the Interrupt Parameters Parameter Identifier OPTO32 IRQ CALLBACK ARG This gives direct access to the application specific argument for 36 General Standards Corporation Phone 256 880 8787 OPTO32 Software Development Kit Reference Manual the callback form of interrupt notification OPTO32 IRQ CALLBACK FUNC This gives direct access to the application specific callback function for the callback form of interrupt notification OPTO32 IRQ COS 23 EVENT COUNTER This deals with the COS 23 input Event Counter OPTO32 IRQ COS POLARITY This gives direct access to the COS state change polarity used to generate interrupts OPTO32 IRQ ENABLE This gives direct access to the interrupt enable disable option OPTO32 IRQ STATE This reports the interrupt triggered state of the board s interrupt sources
39. count int verbose U32 status status opto32 board count count if verbose else if status GSC_SUCCESS printf opto32 board count failure 0x 1X n long status else printf OPTO32 Board Count d n int count 0 return status 20 General Standards Corporation Phone 256 880 8787 OPTO32 Software Development Kit Reference Manual 4 3 opto32_close This function is the entry point to close a connection to an open OPTO32 board The function should only be called after a successful open of the respective device via opto32 open and must not be used after being closed Before returning the API returns the device to the same state produced when originally opened Prototype U32 opto32 close void handle Argument Description handle This is an API device handle obtained via opto32 open Return Value Description GSC SUCCESS The operation succeeded Otherwise A GSC XXX error status reflecting the problem encountered Example tinclude lt stdio h gt include opto32 api h include opto32 dsl h U32 opto32 dsl close void handle int verbose U32 status status opto32 close handle if verbose else if status GSC_SUCCESS printf opto32 close failure 0x 1X n long status else printf Device Closed 0x 1X n long handle return status 4 4 opto32
40. ction style macro definitions These macros are described in section 5 beginning on page 34 4 1 opto32_api_status This function is the entry point to determine the status of the API Library This must be the very first call into the API and determines the usability of the API Library and the Device Driver If the initial status obtained is other than GSC_SUCCESS then only a limited portion of the API is functional If not fully usable then both values returned may be useful in resolving the situation Thereafter the status obtained might vary if the API encounters irregular circumstances The table below lists the utility macros available for this service Macro Services Description OPTO32 API STATUS s a Retrieve the status information without having to explicitly enter the macro for the current API version Prototype U32 opto32 api status U32 stat U32 arg U32 api ver Argument Description stat The API records the current API status here which can change during use The pointer must not be NULL arg The API records auxiliary status information here which can change during use This value should be related to the above reported status The pointer must not be NULL api ver This must be the version number of the API the application was written for If this number does not match then the API is unusable by the application Return Value Description GSC SUCCESS The operation
41. e parameter Do not change the parameter s state value Since parameter access follows a set then get model this value can be used to achieve a get only operation GSC NO CHANGI El Example tinclude lt stdio h gt include opto32 apin include opto32 dsl h U32 opto32 dsl led reset void handle int verbose U32 get U32 status Reset the LED on off state to its default status opto32 config handle OPTO32 MI SC_LED 0 GSC DEFAULT y amp get if verbose else if status GSC_SUCCESS E printf opto32 config failure sld n long status else 10 General Standards Corporation Phone 256 880 8787 OPTO32 Software Development Kit Reference Manual printf LED State if get OPTO32 MISC LED OFF printf offin else printf Oonin return status Example tinclude lt stdio h gt include opto32 api h tinclude opto32 dsl h U32 opto32 dsl led get void handle int verbose U32 get U32 status Reset the LED on off state to its default status opto32 config handle OPTO32 MISC LED 0 GSC NO CHANGE get if verbose else if status GSC_SUCCESS printf opto32 config failure sld n long status else printf LED State if get 0 OPTO32 MISC LED OFF printf offin else printf Onin return st
42. ee Ke TA 12 2 6 Ed GE ETA O N N EN 13 2 03 GSC Registers iret te e i ee cee EE oe Ra cee ees ee o EE 13 2 6 2 PLX PCI9080 PCI Configuration Registers sesse se sea RA GRA Re Ge ee ee ee ee ee ee ee ee Re ee Re Ge nr enn nennen 13 2 63 PEX PCI9OSO Feature Set Registers sd nr Ri EE asa 14 2 7 Version Data Sele OES eer ended ve eee evt oboe dee retos de ede EE Ee dee de ee ee de ees eg T VPE de Yo Y ee de Ee be ee de ee ee EE eo 16 3 1 Discrete Data TYDES 17 3 2 OPto32 Callback func M 17 3 3 Status TOR 17 4 1 0pt032_api_Status sees se esse ee Ee Ee EE Se SE DRA BEE Bee Bee Be Ee Be Ee Ee Ee Ee Ee Ge SG X 19 4 2 opto32 board count esseesseesse esse esse ee Ee Ee Ee SG DRA Bee Bee Bee Be Ee Ee Ee Se Ee Ee Ee Ge SG so v Be non Ee Ee Ee Ge Se See 20 4 3 OPtO32 close P 21 NA itio 21 PS A AAA Po vd beds de eo Ge E E Ee dee Seed Ve eg ede EEEE 23 EE A TL LL TI LIN 24 LORI 24 RM IKE ir CDU 25 4 General Standards Corporation Phone 256 880 8787 OPTO32 Software Development Kit Reference Manual RE IR TET I RR 4 10 0pt032_reg_MOd nono
43. en enne enn 5 3 2 Interrupt Parameter Callback Function ener enne Re Ge Re ee ee 5 3 3 Interrupt Parameter COS 23 Event Counter esse se ee ee Gee ee GRA eene nennen ennt erret nne ee Re ee ee ene 5 3 4 Interrupt Parameter COS Polarity esses ener GRA in ee nn enne ee E ee Re Eei 5 3 5 Interr pt Parameter Endless 5 3 6 Interrupt P rameter State eese desee retirer eric teris eee Rote eben EP a ee eaten o Eo N eoi d genes 5 4 Miscellaneous Param ters iiss sccscscassssvesennessossccesdones GE ees Noe va eva Dee e ERN See sg dei eg eed oe EN SERE SERE Gog GE suas ocseseowessosesess 5 4 1 Miscellaneous Parameter LED se ee sae se ee ee ee ee Re GR nono Re GR enne GRA GR ee ee non ee ee ee ee Re ee Re ee Re ee ae 5 4 2 Miscellaneous Parameter GSC Register Mapping iese ses ee ee RR AR AR Re ee ee ee ee ee ee ee ee Re ee ee 5 4 3 Miscellaneous Parameter GSC Register Mapping Pointer iese sae sae ee ae ee ee ee ee ee Re Ge Re Ge Re ee ae 5 4 4 Miscellaneous Parameter PLX Register MapDIiNg iese see see sea sea GR RA GRA GRA Re ee ee ee ee ee ee Re ee Re Re ee ae 5 4 5 Miscellaneous Parameter Strict Arguments Re Re RR RA GRA GRA Re ee ee ee ee ee ee Re ee Re ee Re ee ee 5 4 6 Miscellaneous Parameter Strict Configuration esse ese ee se ee GR RR RA GRA GRA Re ee ee Re Ee ee ee ee Re ee Re ee ee ON CLAUOM Ee mcr pd A FR ES EE EE N OE ER 6 2 Direct Resister ACCE
44. eport the mapping of PLX registers into API memory space This parameter is used to give the API direct access to PLX feature set registers When mapping is enabled the API reads these registers itself contributing to improved performance When mapping is disabled the API passes read requests for these registers to the driver which takes more work to complete This parameter should always be enabled even though it is not directly usable by applications The following tables describe the macros associated with this parameter NOTE There are circumstances where this feature cannot be enabled and utilized This is usually limited to embedded hosts here the BIOS doesn t place all PCI memory access regions on CPU Page Size boundaries If the BIOS cannot be configured to utilize such boundaries then API performance is degraded Macro Parameter Description OPTO32 MISC MAE This is the identifier for this parameter d d gt lt Pal Ej Q ca Macro Values Description OPTO32 MISC MAP PLX REGS DEFAULT This is the default which is enabled OPTO32 MISC MAP PLX REGS DISABLE This refers to the disabled state When disabled access to PLX registers must go through the Device Driver which reduces efficiency OPTO32 MISC MAP PLX REGS ENABLE This refers to the enabled state When enabled access to PLX registers is done entirely within the API which increases efficiency d 1
45. eriod is retrieved the Clock Divider is rounded to the nearest microsecond The following tables describe the macros associated with this parameter NOTE All OPTO32 interrupts are temporarily disabled while the Debounce Divisor is being set Macro Parameter Description OPTO32 COS DEBOUNCE PERIOD US This is the identifier for this parameter Macro Values Description OPTO32 COS DEBOUNCE PERIOD US DEFAULT This is the default period The minimum is the default OPTO32 COS DEBOUNCE PERIOD US MAX This is the maximum period that may be requested which is two minutes OPTO32 COS DEBOUNCE PERIOD US MIN This is the minimum period that may be requested which is zero Zero corresponds to a period of 600 nanoseconds Macro Services Description OPTO32 COS DEBOUNCE PERIOD US GET h g This retrieves the current period OPTO32 COS DEBOUNCE PERIOD US RESET h This requests the default period OPTO32 COS DEBOUNCE PERIOD US SET h s This requests a specified period 5 3 Interrupt Parameters The purpose of the Interrupt Parameters is to permit access to and control of the OPTO32 hardware based interrupts All Interrupt Parameters are put in a default state when the device is opened and are returned to that state via the opto32 init service The hardware based interrupt
46. evice which is specific to and usable only by the API The API prevents access to the device other than by this handle Using this handle applications have full access to and control over the OPTO32 and its features Applications can configure all available device and API settings perform discrete I O operations and when done release access to the device by calling opto32 close 6 2 Direct Register Access Application can gain direct access to the OPTO32 firmware registers via the Miscellaneous Parameters OPTO32 MISC MAP GSC REGS and OPTO32 MISC MAP GSC REGS PTR This feature permits applications to read and write the registers using 32 bit pointers such as U32 While direct access to the OPTO32 firmware registers can contribute to a performance gain there may be virtually no gain to an application using this feature The reason is because the API uses direct register access at all times when possible This is done automatically for performance reasons and occurs unless the Miscellaneous GSC Register Mapping parameter is disabled If this is done then direct access is available to neither the API nor the application 6 3 Data Input Very little is required in terms of configuring and using the OPTO32 s data input feature The steps needed are as follows 1 Configure the Debounce Clock Divisor for the desired debounce period For this refer to the utility macros for the following parameters Refer to OPTO32 COS DEBOUNCE DIVIS
47. gives those registers and values that uniquely identify OPTO32 boards Register Value Description GSC PCI 9080 VIDR 0x10B5 The PCI interface chip as a PLX device GSC PCI 9080 DIDR 0x906E The PCI interface chip is reported as a PLX PCI9060E though it is actually a PLX PCI9080 GSC PCI 9080 SVID 0x10B5 The PCI interface chip as a PLX device GSC PCI 9080 SID 0x9080 The PCI interface chip is a PLX PCI9080 2 6 3 PLX PCI9080 Feature Set Registers The following tables give the set of PLX feature set registers Local Configuration Registers The following table gives the set of PLX Local Configuration Registers For detailed definitions of these registers refer to the PCI9080 Data Book Macros Description GSC PLX 9080 BIGEN D Big Little Endian Descriptor Register BIGEND GSC PLX 9080 DMCFGA PCI Configuration Address Register for Direct Master to PCI IO CFG DMCFGA GSC PLX 9080 MLBAM Local Bus Base Address Register for Direct Master to PCI Memory DMLBAM GSC PLX 9080 MLBAI Local Bus Base Address Register for Direct Master to PCI IO CFG DMLBAT PCI Base Address Register for Direct Master to PCI Memory DMPBAM GSC PLX 9080 MRR Local Range Register for Direct Master to PCI DMRR GSC PLX 9080 ROMBA Expansion ROM Local Base Address Register EROMBA GSC PLX 9080 EROMR D D GSC PLX 9080 DMPBA
48. hese include setting options 1 e defaults and acceptable values quick access retrieval macros and quick access manipulation macros All are described later in this document 1 6 1 Software Architecture An application communicates with an OPTO32 using the driver and library described briefly above Any number of applications may make simultaneous use of the library and each use is totally independent unless specifically designed to do otherwise Each instance provides access to at most 32 different OPTO32 devices The diagram below describes the components and how they fit together Application This is any application written to communicate with one or more OPTO32 devices using the PR driver and library provided in the SDK API Libra This library presents an OPTO32 feature based interface to applications wishing to d communicate with OPTO32 devices Device Driver The driver provides access to OPTO32 devices OPTO32 This refers to any number of installed OPTO32 devices NOTE While multiple applications can gain access to the same device this is discouraged since the driver maintains resources and settings per device rather than per application or device handle 1 7 Hardware Overview The OPTO32 is a high performance optically isolated I O board with Change Of State COS detection on all inputs The board includes 24 optically isolated inputs and eight optically isolated outs All inputs are controlled by a g
49. hese macros refers individually to COS 00 through COS 23 and RECO 5 4 Miscellaneous Parameters The purpose of the Miscellaneous Parameters is to permit access to and control of OPTO32 parameters which do not readily fit into the other parameter categories All Miscellaneous Parameters are put in a default state when the device is opened and are returned to that state via the opto32 init service The hardware based Miscellaneous Parameters are returned to their default states via the opto32 reset service Applications have access to these OPTO32 registers but it is advised that these parameters be accessed only through the Miscellaneous Parameter services When using the service opto32 config the which bits argument is ignored The following table summaries the Miscellaneous Parameters Parameter Identifier Description OPTO32 MISC LED This gives direct access to the LED on the OPTO32 panel OPTO32 MISC MAP GSC REGS This refers to direct access to the firmware registers OPTO32 MISC MAP GSC REGS PTR This refers to an application s direct access to the firmware registers OPTO32 MISC MAP PLX REGS This gives direct access to how the API accesses the PLX registers OPTO32 MISC STRICT ARGUMENTS This gives direct access to how the API responds to unrecognized parameter values OPTO32 MISC STRICT CONFIG This refers to how the library responds to invalid configuration requests
50. hree groups which are described the following paragraphs All macros are described in the following pages in association with their respective parameters The parameter categories are as given in the below table Parameter Categories Description OPTO32 COS XXX These refer to the Change Of State Parameters OPTO32 IRQ XXX These refer to the Interrupt Parameters OPTO32 MISC XXX These refer to the Miscellaneous Parameters 5 1 1 Parameter Definitions The first group of macros includes the parameter definitions These are used to identify the specific parameter to be accessed These macros begin with OPTO32 and are followed immediately by upper case letters identifying the parameter category For example OPTO32 MISC prefaces all Miscellaneous Parameter identifiers These macros end with upper case letters indicating the name of the specific parameter For example OPTO32 MISC STRICT ARGUMENTS identifies the Miscellaneous Strict Arguments parameter 5 1 2 Value Definitions The second group of macros identifies predefined values associated with the respective parameters These macros begin with the Parameter Definition and are followed by a single underscore then upper case letters that reflect the meaning of the respective values For example the macro OPTO32 MISC STRICT ARGUMENTS DISABLE is the value that represents the parameter s disabled setting ES 5 1 3 Service Definitions The
51. list of commonly occurring terms used throughout this document Term Definition API Library This refers to the library implementing the application level OPTO32 interface This is sometimes used synonymously with SDK or API Application This refers to user mode processes Driver This refers to the device driver which runs under control of the operating system Library This refers to the library module specific to the OS in use 1 4 Installation Installation instructions for the SDK are provided in separate operating system specific setup guides 1 5 Application Programming Interface The SDK API is defined in the three header files listed below These C language headers are C compatible The only header that need be included by OPTO32 applications is opto32 api h The API consists of macros data types function calls and parameter definitions These are described in other sections of this document The headers define numerous items in addition to those described in this document These additional items are provided without documentation All software components of the API begin with a prefix of OPTO32 or GSC both appear with upper and lower case letters The table below indicates where to look for any particular item s definition File Name Description gsc common h This header contains status definitions a few data type definitions and a variety of macros All items defined here have a prefix of GSC
52. lobal debounce timer The debounce period consists of three sampling intervals where the interval is configurable in 100ns increments from 200ns to just under 215 seconds The debounced input can be read at any time Also each COS input can be independently configured to generate an interrupt on either a rising or falling state transition The D23 input has the added capability of generating an interrupt after receipt of from 1 to 64K low to high state changes The eight outputs include four with normal output capability and four with high output capability 8 General Standards Corporation Phone 256 880 8787 OPTO32 Software Development Kit Reference Manual 1 8 Code Samples All of the code samples in this manual are included in the opto32_ds1 library along with their C source files The examples given are notably simplistic but are provided to illustrate use rather than accomplishment of broader tasks 1 9 Reference Material The following reference material may be of particular benefit in using the OPTO32 and this SDK The specifications provide the information necessary for an in depth understanding of the specialized features implemented on this board e The applicable OPTO32 User Manual from General Standards Corporation e The PCI9080 PCI Bus Master Interface Chip data handbook from PLX Technology Inc e The PLX PCI SDK version 4 0 0 from PLX Technology Inc PLX material is available from PLX at the following location
53. n before subsequent callback notification can occur for that same source The prototype required for all callbacks is the data type opto32 callback func t The three arguments to the callback are each U32 data types Applications must cast the values given to their respective types which are described below 6 5 1 1 Interrupt Notification Callback The callback function arguments are described in the following table The values received during the callback must be cast according to the data types specified Argument Cast Description argi void This is the device handle received from opto32 open arg2 U32 This is the specific which bit for the interrupt that produced the callback Refer to the OPTO32 WHICH XXX macros arg3 U32 This is an application specific argument This is the Interrupt Callback Argument 45 General Standards Corporation Phone 256 880 8787 OPTO32 Software Development Kit Reference Manual parameter 6 5 2 Event Waiting The waiting mechanism operates by blocking the calling thread until any one of a number of referenced events occurs The calling thread is resumed when the first of the referenced events occurs or when a timeout limit expires whichever occurs first The time limit is passed as an argument to the wait service Threads can wait on any number or combinations of interrupts Also any number of threads can wait on identical or different events
54. nt may be NULL in which case the current setting is not retrieved Return Value Description GSC SUCCESS The operation succeeded Otherwise A GSC XXX error status reflecting the problem encountered Example tinclude lt stdio h gt include opto32 api h include opto32 dsl h U32 opto32 dsl led set void handle U32 set int verbose U32 get U32 status Reset the LED on off state to its default status opto32 config handle OPTO32 MISC LED 0 set amp get if verbose else if status GSC_SUCCESS printf opto32 config failure sld n long status else printf LED State 22 General Standards Corporation Phone 256 880 8787 OPTO32 Software Development Kit Reference Manual if get OPTO32 MISC LED OFF printf Off n else printf Oonin return status 4 5 opto32_cos_read This function is the entry point to reading the current debounced input from the cable The function should only be called after a successful open of the respective device via opto32_open Prototype U32 opto32 cos read void handle U32 value Argument Description handle This is an API device handle obtained via opto32 open value The value read is recorded here The upper eight bits will always be zero Return Value Description GSC SUCCESS The operation succeeded Otherwise
55. os write failure ld n long status else printf COS Write 0x 021X n long value return status 4 7 opto32 init This function is the entry point to return a device and all parameters to the state produced when the device was first opened This function should only be called after a successful open of the respective device via opto32 open Prototype U32 opto32 init void handle 24 General Standards Corporation Phone 256 880 8787 OPTO32 Software D evelopment Kit Reference Manual Argument Description handle This is an API device handl e obtained via opto32_open Return Value Description GSC_SUCCESS The operation succeeded Otherwise A GSC XXX error status reflecting the problem encountered Example include lt stdio h gt include opto32 api h tinclude opto32 dsl h U32 opto32 dsl init void handle U32 status status if else if verbose status printf opto32 init else printf Device Initialized return status 4 8 opto32 irq wait GSC SUCC int verbose opto32 init handle E SS failure 0x 1X n long status OxS1X n long handle This function is the entry point to pause thread execution until an interrupt occurs The function should only be called after a successful open of the respective device via opto32 o
56. pen When called the current thread will block until any one of a specified set of interrupts occurs The call will return as soon as the time period expires or when the first referenced interrupt occurs whicheve r occurs first There is no limit to the number of threads that may simultaneously utilize this service or on the combination of interrupts that may be referenced Applications can use the utility macros OPTO32 IRO WAIT XXX h to perform waits on individual interrupts without having to explicitly enter the macro for the respective interrupt In these macros the XXX may be COS 00 through COS 23 for COS inputs zero through 23 respectively or RI below ECO for the COS 23 Rx Event Counter Overflow See the table Macro Services Description OPTO32 IRO WAIT COS XX h to Wait for COS interrupt XX OPTO32 IRQ WAIT RECO h to Wait for the Receive Event Count interrupt The XX portion of these macros refers individually to COS interrupts 00 through 23 25 General Standards Corporation Phone 256 880 8787 Prototype U32 opto32 i OPTO32 Software Development Kit Reference Manual rq wait void handle U32 which U32 timeout ms Argument Description handle This is an API device handle obtained via opto32 open which This is any bitwise or d combination of OPTO32 WHICH XXX bits applicable to interrupts Set the bits according to the interrupts of interest Un
57. referenced interrupts will have no impact If none are set the function returns immediately with GSC SUCCESS timeout ms This is the timeout limit is milliseconds If an interrupt does not occur within this time period then the call returns at the end of the period The timeout period will be at least the amount of time specified but may be longer depending on the OS Return Value Description GSC SUCCESS Either no interrupts were referenced or one of the referenced interrupts occurred No indication is given to indicate which interrupt if any caused the call to return GSC WAIT TI MEOUT The timeout period expired before a referenced interrupt occurred Otherwise Example A GSC XXX error status reflecting the problem encountered include lt stdio h gt include opto32 api h include opto32 dsl h U32 opto32 dsl event count wait void handle long timeout ms int verbose U32 status status opto32 irg wait handle OPTO32 WHICH RECO timeout ms if verbose else if status GSC SUCCESS printf IRQ COS 23 Event Count interrupt occurred Mn else if status GSC WAIT TIMEOUT printf IRQ COS 23 Event Count timeout after ld milliseconds n long timeout_ms else printf opto32 irq wait failure ld n long status 26 General Standards Corporation Phone 256 880 8787 OP
58. ress Register for Memory Accesses to Local Address Space 0 PCIBAR2 GSC PCI 9080 BAR3 PCI Base Address Register for Memory Accesses to Local Address Space 1 PCIBAR3 GSC_PCI_9080 BAR4 Unused Base Address Register PCIBAR4 GSC PCI 9080 BAR5 Unused Base Address Register PCIBARS GSC PCI 9080 BISTR PCI Built In Self Test Register PCIBISTR GSC PCI 9080 CCR PCI Class Code Register PCICCR GSC PCI 9080 CIS PCI Cardbus CIS Pointer Register PCICIS GSC PCI 9080 CLSR PCI Cache Line Size Register PCICLSR GSC PCI 9080 CR PCI Command Register PCICR GSC PCI 9080 DIDR PCI Device ID Register PCIDIDR GSC PCI 9080 ERBAR PCI Expansion ROM Base Address PCIERBAR GSC PCI 9080 HTR PCI Header Type Register PCIHTR GSC PCI 9080 ILR PCI Interrupt Line Register PCIILR GSC PCI 9080 IPR PCI Interrupt Pin Register PCIIPR GSC PCI 9080 LTR PCI Latency Timer Register PCILTR GSC PCI 9080 MGR PCI Min Gnt Register PCIMGR GSC PCI 9080 MLR PCI Max Lat Register PCIMLR 13 General Standards Corporation Phone 256 880 8787 OPTO32 Software Development Kit Reference Manual GSC PCI 9080 REV PCI Revision ID Register PCIREV GSC PCI 9080 SID PCI Subsystem ID Register PCISID GSC PCI 9080 SR PCI Status Register PCISR GSC PCI 9080 SVID PCI Subsystem Vendor ID Register PCISVID GSC PCI 9080 VIDR PCI Vendor ID Register PCIVIDR NOTE The following table
59. roduct or circuit described herein nor is any license conveyed under any patent rights or any rights of others General Standards Corporation assumes no responsibility for any consequences resulting from omissions or errors in this manual or from the use of information contained herein General Standards Corporation reserves the right to make any changes without notice to this product to Improve reliability performance function or design ALL RIGHTS RESERVED The Purchaser of this software may use or modify in source form the subject software but not to re market or distribute it to outside agencies or separate internal company divisions The software however may be embedded in the Purchaser s distributed software In the event the Purchaser s customers require the software source code then they would have to purchase their own copy of the software General Standards Corporation makes no warranty of any kind with regard to this software including but not limited to the implied warranties of merchantability and fitness for a particular purpose and makes this software available solely on an as is basis General Standards Corporation reserves the right to make changes in this software without reservation and without notification to its users The information in this document is subject to change without notice This document may be copied or reproduced provided it is in support of products from General Standards Corporation For any
60. rrupt sources NOTE When interrupt notification is used it is the application s responsibility to enable all applicable interrupts This applies to both the wait mechanism and the callback mechanism To receive continuous interrupt notification applications must re enable each interrupt source after each notification To terminate notification applications should disable the respective interrupts NOTE Once an interrupt is enabled it will remain so until it is disabled by the application or until it is disabled by the API in the normal course of servicing the interrupt 6 5 1 Event Callback The callback feature permits an application supplied function to be called in response to OPTO32 interrupts Each interrupt source can independently be assigned its own callback function along with a different application defined callback argument Callbacks can be assigned to any source and in any combination desired If a given callback is associated with multiple sources then multiple callbacks will be made as the different events occur So for example if a single callback is assigned to two different interrupts then the callback function will be called separately for each interrupt as often as each occurs Since each source is associated with its own callback context a thread context such callbacks must support multithreaded operation Applications are free to reconfigure callbacks during a callback context but the callback for a given event must retur
61. rs and there are GSC firmware based registers The PCI registers and the PLX registers are provided by the PCI interface chips used on the OPTO32 Applications have read access to all registers but write access only to the GSC firmware registers 2 6 1 GSC Registers The following table gives the complete set of GSC specific OPTO32 registers For detailed definitions of these registers refer to the applicable OPTO32 User Manual Macros Description OPTO32 BCR Board Control Register BCR OPTO32 BSR Board Status Register BSR OPTO32 CDR Clock Divider Register CDR OPTO32 COSIER Change Of State Interrupt Enable Register COSIER OPTO32 COSPR Change Of State Polarity Register COSPR OPTO32 COSR Change Of State Register COSR OPTO32 ODR Output Data Register ODR OPTO32 RDR Receive Data Register RDR OPTO32 RECR Receive Event Counter Register RECR 2 6 2 PLX PCI9080 PCI Configuration Registers The following table gives the set of PCI Configuration Registers For detailed definitions of these registers refer to the PCI9080 Data Book Macros Description GSC PCI 9080 BARO PCI Base Address Register for Memory Accesses to Local Runtime and DMA Registers PCIBARO GSC PCI 9080 BAR1 PCI Base Address Register for VO Accesses to Local Runtime and DMA Registers PCIBAR1 GSC PCI 9080 BAR2 PCI Base Add
62. rs either to the library s version number or the GSC revision level The version data can still be retrieved when this status 1s seen GSC INVALID VER SION DRIVER API Library initialization failed because the Device Driver version was incompatible This refers either to the driver s version number or the GSC revision level The version data can still be retrieved when this status is seen GSC LIB FUNCTION ACCESS FAILURE GSC NULL PARAM GSC SUCCESS T GSC THREAD FAIL URE API Library initialization failed because the API could not access a Driver Interface Library function An operation failed because an argument was NULL An operation completed successfully An operation opto32 open failed because a support thread could not be started GSC TOO MANY OP EN HANDLI El ca An operation opto32 open failed because the application attempted too many simultaneous device accesses GSC WAIT TIMEOU T An operation completed because a timeout period lapsed ED GSC WAIT CANCEL An operation waiting for an event ended prematurely This usually means the application was terminated while waiting for the event 18 General Standards Corporation Phone 256 880 8787 OPTO32 Software Development Kit Reference Manual 4 Functions The OPTO32 API includes the following functions The SDK interface also includes a number of fun
63. se if status GSC_SUCCESS E printf opto32 open failure ld n long status else printf Device Opened n printf Index Ox 1XMn long index printf Handle Ox 1XMn long handle return status 27 General Standards Corporation Phone 256 880 8787 OPTO32 Software Development Kit Reference Manual 4 10 opto32_reg_mod This function is the entry point to performing a read modify write operation on an OPTO32 register The function should only be called after a successful open of the respective device via opto32_open Only GSC firmware register may be modified The PCI and PLX feature set registers are read only Prototype U32 opto32 reg mod void handle U32 reg U32 value U32 mask Argument Description handle This is an API device handle obtained via opto32 open reg This is the register to access value This is the value for the bits to be modified mask This is the set of register bit to be modified All others are unchanged Return Value Description GSC SUCCESS The operation succeeded Otherwise A GSC XXX error status reflecting the problem encountered Example include include include lt stdio h gt opto32 api h opto32 dsl h U32 opto32 dsl cosier mod void U32 U32 int handle value mask verbose U32 status status opto32 reg mod handle OPTO32 COSIE
64. status text U32 status char text size t size Argument Description status This is the status value whose description is desired text The descriptive text is recorded here size This gives the size of the above buffer Return Value Description GSC_SUCCESS The operation succeeded Otherwise A GSC XXX error status reflecting the problem encountered Example tinclude lt stdio h gt include opto32 api h include opto32 dsl h U32 opto32 dsl status text U32 stat int verbose 31 General Standards Corporation Phone 256 880 8787 OPTO32 Software Development Kit Reference Manual char buf 1281 U32 status status opto32 status text stat buf sizeof buf if verbose else if status GSC_SUCCESS E printf opto32 status text failure 0x 1xX n long status else printf Status Ox 1X Ss n long stat buf return status 4 15 opto32_version_get This function is the entry point to retrieving version number strings Without a valid device handle only the API Library version number is accessible Access to the Device Driver s version number requires a valid device handle Prototype U32 opto32 version get void handle U8 index char version size t size Argument Description handle This is an API device handle obtained via opto32 open index This identifies the
65. those cases where either a value is not being applied or the value applied is specified inside the macro replacement text 5 1 3 4 Get Value g In the service macros the argument g refers to the address of the variable to receive the parameter s current setting In cases where the current setting is not being read this argument has been omitted from the service macro In all cases this argument can be NULL in which case the current value is not retrieved 5 2 Change Of State Parameters The purpose of the Change Of State COS Parameters is to permit access to and control of the board s COS feature All COS Parameters are put in a default state when the device is opened and are returned to that state via the opto32 init and opto32 reset services Applications are free to manipulate the configuration either via the API s register access services or via the COS Parameter services The following table summaries the COS Parameters Parameter Identifier Description OPTO32 COS DEBOUNCE DIVISOR This gives direct access to the Clock Divider Register OPTO32 COS DEBOUNCE PERIOD MS This refers to the overall debounce period in milliseconds OPTO32 COS DEBOUNCE PERIOD US This refers to the overall debounce period in microseconds T 5 2 1 COS Parameter Debounce Divisor The purpose of this parameter is to control and report the board s debounce Clock Divider Accessing this service is equi
66. ually to 00 through 23 5 3 5 Interrupt Parameter Enable The purpose of this parameter is to modify and report the enabled state of the respective interrupt This parameter enables and disables individual interrupts In the opto32 config service interrupt selections are made using individual OPTO32 WHICH XXX bits Here XXX is any of the predefined interrupt selection options The following tables describe the macros associated with this parameter Macro Parameter Description OPTO32 IRQ ENABLE This is the identifier for this parameter Macro Values Description OPTO32 IRQ ENABLE DEFAULT This is the default which is disabled OPTO32 IRQ ENABLE NO This option disables the interrupt OPTO32 IRQ ENABLE YES This option enables the interrupt Macro Services Description OPTO32 IRQ ENABLE GET h w g This retrieves a current setting OPTO32 IRQ ENABLE NO h w This requests that the referenced interrupts be disabled OPTO32 IRQ ENABLE RESET h w This requests a setting change for the referenced interrupts to the default OPTO32 IRQ ENABLE SET h w s This requests a setting change OPTO32 IRQ ENABLE XXX GET h g This retrieves the current interrupt XXX setting OPTO32 IRQ ENABLE XXX NO h This requests that interrupt XXX be disabled OPTO32 IR
67. valent to accessing the Clock Divider Register CDR directly Setting this parameter updates the Clock Divider Reading this parameter returns the current Clock Divider value The following tables describe the macros associated with this parameter NOTE All OPTO32 interrupts are temporarily disabled while the Debounce Divisor is being set Macro Parameter Description OPTO32 COS DEBOUNCE DIVISOR This is the identifier for this parameter E Macro Values Description OPTO32 COS DEBOUNCE DIVISOR DEFAULT This is the divider s default value which is zero E Macro Services Description OPTO32 COS DEBOUNCE DIVISOR GET h g This retrieves the current divider OPTO32 COS DEBOUNCE DIVISOR RESET h This sets the counter to its default value OPTO32 COS DEBOUNCE DIVISOR SET h s This applies a specified counter value 5 2 2 COS Parameter Debounce Period In Milliseconds The purpose of this parameter is to control and report the board s debounce period in milliseconds This refers to the overall debounce period which consists of three individual sampling intervals When a value is applied it is converted from milliseconds to the closest corresponding Clock Divider value When the period is retrieved the Clock Divider is rounded to the nearest millisecond The following tables describe the macros associated with this parameter NOTE
68. value encountered is GSC SUCCESS and indicates that the request was completed successfully Definition typedef enum y Values Description GSC ABORTED An I O operation was aborted due to a user s explicit or implicit request GSC ACCESS DENIED The operation failed because access to a device service 17 General Standards Corporation Phone 256 880 8787 OPTO32 Software Development Kit Reference Manual or system resource or service was denied GSC FAILED An operation failed in a non specific manner GSC INIT FAILUR m F P API Library initialization failed GSC INSUFFICIEN T RESOURCES An operation failed because insufficient OS resources were available GSC INVALID API HANDL El An operation failed because the application supplied an invalid device handle API device handles are API specific resources and are of no meaning to the OS GSC INVALID DATA An operation failed because invalid data was provided GSC INVALID VER SION API API Library initialization failed because the API Library version was incompatible This refers either to the API s version number or the GSC revision level The version data can still be retrieved when this status is seen GSC INVALID VER SION DIL API Library initialization failed because the Driver Interface Library version was incompatible This refe
69. version number desired It must be one of the GSC VERSION XXX macros version The requested version string is recorded here size This is the size of the above buffer Return Value Description GSC SUCCESS The operation succeeded Otherwise A GSC XXX error status reflecting the problem encountered Example tinclude lt stdio h gt include opto32 apih include opto32 dsl h U32 opto32 dsl version get void handle U8 id int verbose U32 status 32 General Standards Corporation Phone 256 880 8787 OPTO32 Software Development Kit Reference Manual char version 32 status opto32 version get handle id version sizeof version if verbose else if status GSC SUCCESS printf opto32 version get failure 0x 1xX n long status else if id GSC VERSION LIBRARY printf Library Version s n version else printf Driver Version s n version return status 33 General Standards Corporation Phone 256 880 8787 OPTO32 Software Development Kit Reference Manual 5 Configuration Parameters 5 1 Parameter Macros The Configuration Parameters are grouped according to their functional categories Within each category each parameter is described in this section along with the set of utility macros designed to facilitate configuration of and access to the respective parameters Parameter macros fall into t
70. which also define these types then the API can be directed to omit these definitions This is done by defining the macro GSC DATA TYPES NOT NEEDED before including the API header The alternate definitions must however define these types as listed in the below table Data Type Description S8 This is an 8 bit signed integer U8 This is an 8 bit unsigned integer S16 This is a 16 bit signed integer U16 This is a 16 bit unsigned integer S32 This is a 32 bit signed integer U32 This is a 32 bit unsigned integer 3 2 opto32 callback func t This is the data type required for all event notification callback functions This applies to Interrupt Notification callbacks Definition typedef void opto32 callback func t U32 argl U32 arg2 U32 arg3 Arguments Description argl This is the device handle cast to a U32 data type arg2 For Interrupt Notification this is the OPTO32 WHICH XXX bit for the respective interrupt arg3 This is any arbitrary application supplied data value 3 3 Status Values This unnamed enumerated data type lists all possible status values returnable from API service calls The enumerated values represent common definitions used by this and other GSC SDKs Many values will never be encountered when using the OPTO32 SDK The table below gives brief descriptions for many values and omits those that should never be seen The most common

OPTO32 - General Standards Corporation

Contents

Download Pdf Manuals

Related Search

Related Contents