Home

netANALYZER API - Windows XP/Vista/7/8

1. Element Type Description ulCardCnt UINT32 Number of available netANALYZER devices ulVersionMajor UINT32 ulVersionMinor UINT32 Beer ulVersionBuild UINT32 ulVersionRevision UINT32 ulMaxFileCount UINT32 Maximum number of files that can be created handled ulDMABufferSize UINT32 Size of DMA Buffers in Bytes ulDMABufferCount UINT32 Number of available DMA Buffers per Device ulToolkitVersionMajor UINT32 ulToolkitVersionMinor UINT32 AER ulToolkitVersionBuild UINT32 ulToolkitVersionRevision UINT32 IMarshallerStatus INT32 Error code status of the Marshaller API interface ulMarshallerVersionMajor UINT32 ulMarshallerVersionMinor UINT32 Marshaller version only valid if netAnaMarshaller API extension is ulMarshallerVersionBuild UINT32 used ulMarshallerVersionRevision UINT32 Table 7 Structure Driver Information You can evaluate the error code status of the Marshaller API interface 1MarshallerStatus as follows NETANA NO ERROR 0 means the Marshaller is available and ready to operate Otherwise an error code is returned in 1MarshallerStatus For meanings of Marshaller related error codes see Table 8 Meanings of Marshaller related Error Codes below Value Definition Description 0x80200008 NETANA_NO_ENTRY_FOUND Wrong or missing registry entry 0x80200009 NETANA_FUNCTION_NOT_AVAILABLE Missing function in the DLL of the Marshaller API 0x80220007 NETANA_FILE_OPEN_E
2. errors ullShortFrames UINT64 Short Frames lt 60 Bytes ullFramesRejected UINT64 Number of frames that have been filtered out ullLongPreambleCnt UINT64 Frames with long preamble ullShortPreambleCnt UINT64 Frames with short preamble ullBytesLineBusy UINT64 Number of received bytes ulMinIFG UINT32 Lowest IFG Interframe Gap in 10 ns increments ullTime UINT64 Actual capture time as a running nanosecond counter based on ullReferencetime passed to netana_start_capture Table 15 Structure Portstate Description 3 1 7 NETANA_FILE_INFORMATION_T This structure provides file capture statistics for currently running capture used in the netana_file_info see section netana_file_info on page 39 function Element Type Description ulActualFileNr UINT32 Current capture file ulMaxFileCnt UINT32 Maximum number of files in list ullTotalBytesWritten UINT64 Total number of bytes stored in files ullMaxBytes UINT64 Maximum number of bytes that can be stored ulRingBufferMode UINT32 0 if capturing is done in Ring buffermode Table 16 Structure File Information Description netANALYZER API Windows XP Vista 7 8 DOC091113DRVO7EN Revision 7 English 2014 05 Released Public Hilscher 2009 2014 API Definitions 18 60 3 18 NETANA_MNGMT_DEV_SCAN_IN_T This structure is required when calling the netana_mngmt_exec_cmd function with the Management Command NETANA_MNGMT_CMD_D
3. Error configuring GPIO 0 ErrorCode 0x 08X r n lResult else printf Configured GPIO 0 for rising edge detection r n f Serua GRO L to stoo Ceyjorivieiinc accer 2 pa alice ralling seee Vecuis y tGpio ulCaptureTriggers NETANA_GPIO_TRIGGER_STOP tGpio ulMode NETANA_GPIO_MODE_FALLING_EDGE tGpio ulEndDelay 200 if NETANA_NO_ERROR lResult netana_set_gpio_mode hDevice 1 amp tGpio printf Error configuring GPIO 1 ErrorCode 0x 08X r n lResult else printf Configured GPIO 1 to stop capturing after 2 us when a falling edge is detected r n netANALYZER API Windows XP Vista 7 8 DOC091113DRVO7EN Revision 7 English 2014 05 Released Public Hilscher 2009 2014 Example Code 4 2 Function ConfigureFilters Setting Filters The following piece of C code function ConfigureFilters can be used to configure filters on a netANALYZER card It configures the port O of a card in such manner that only TCP IP and ARP telegrams are recorded void ConfigureFilters NETANA_HANDLE hDevice NETANA_FILTER_T tFilterA 0 abate abFilterMaskA 16 MINAS ie abFilterValueA 16 0 0 NETANA_FILTER_T tFilterB 0 EE abFilterMaskB 16 0 EE abFilterValueB 16 0 iS 2 ulRelation IME SZ E lResult Filter A matches TCP IP Frames Frametype 0x0800
4. The HEA Header has the following structure Element Type Description ulCookie UINT32 ASCII Cookie HEA 0x4145482E in little endian format ulldx UINT32 Running file number used for detecting file sequence in ring buffer mode ullCaptureStart UINT64 Capture start time Default Modified UNIX timestamp nanoseconds since 1 1 1970 ullDataSize UINT64 Size of the captured data in this file NETANA_FILE_HEADER_SIZE_INVALID 1 indicates a not yet written completed file ITimezoneCorrection INT32 Time zone correction to UTC in seconds ulReserved UINT32 Reserved set to zero Table 3 Structure of HEA Header netANALYZER API Windows XP Vista 7 8 DOC091113DRVO7TEN Revision 7 English 2014 05 Released Public Hilscher 2009 2014 Overview 10 60 The length of the data packets is aligned on 32 Bit boundaries packets These are stored in the following format Element Type Description ulHeader UINT32 Packed information for the following Data Bit 8 O Ethernet Port 1 GPIO Port Bit 9 O Ethernet mode 1 Transparent mode Bits 10 13 Version field set it always to 1 Bits 14 15 Port number this frame was received on Bits 16 27 Length of the following data Caplen ullTimestamp UINT64 Nanosecond timestamp based on ullCaptureStart from header abData UINT8 Caplen Captured data Size is included in ulHeader Note This array wi
5. 100 000 000 ulLoPeriod UINT32 Low period of signal generator in 10 ns Min 1 maximum 100 000 000 Table 14 Structure GPIO Description PWM generation is only active while capture is started netANALYZER API Windows XP Vista 7 8 DOC091113DRVO7TEN Revision 7 English 2014 05 Released Public O Hilscher 2009 2014 API Definitions 17 60 3 1 6 NETANA_PORT_STATE_T Statistics and error counters for a specific port used in the netana_get_portstat see section netana_get_portstat on page 28 function Element Type Description ulLinkState UINT32 Current link state bitmask 0x00000001 NETANA_LINK_STATE_UP Link detected 0x00000002 NETANA_LINK_STATE_SPEED100 Link with 100 MBit detected 10MBit if bit is not set 0x00000004 NETANA_LINK_STATE_SPEED_VALID If set the contents of NETANA_LINK_STATE_SPEED100 is valid If not set the contents of NETANA_LINK_STATE_SPEED100 is not reliable ullFrameReceivedOk UINT64 Total number of successfully received Ethernet frames ullRXErrors UINT64 Number of receive errors ullAlignmentErrors UINT64 Number of frames with alignment errors 1 additional nibble received ullFrameCheckSequenceErrors UINT64 Number of frames with a bad FCS including short frames with a bad FCS ullFrameTooLongErrors UINT64 Number of long frames received gt 1514 bytes ullSFDErrors UINT64 Number of Ethernet frames with a SFD Start of frame delimiter
6. 16 36 60 netana_get filter Get the currently active filters of an Ethernet port JENES MD A U N N U NGS MOPOT ENTRY netana_get_filter NETANA_HANDLE hDev ETANA_FILTER_T ptFilterA ETANA_FILTER_T ptFilterB INT32 pulRelationShip Parameter Description hDev Device handle ulPort Ethernet port number ptFilterA Filter A Note Pointers in these structure must be allocated by user and the correct length must be passed ptFilterB Filter B Note Pointers in these structure must be allocated by user and the correct length must be passed pulRelationShip Relationship of both filters Bitmask 0x00000001 NETANA_FILTER_RELATION_A_OR_B 0 Result Filter A AND Filter B corresponds to NETANA_FILTER_RELATION_A_AND_B 0 1 Result Filter A OR Filter B corresponds to NETANA_FILTER_RELATION_A_OR_B 1 0x00000080 NETANA_FILTER_RELATION_REJECT_FILTER 0 Accept frames if filter matches corresponds to NETANA_FILTER_RELATION_ACCEPT_FILTER 0 1 Reject frames if filter matches corresponds to NETANA_FILTER_RELATION_REJECT_FILTER 0x00000080 0x00008000 NETANA_FILTER_RELATION_ACCEPT_ERROR_FRAMES 0 Error frames are rejected 1 Error frames are accepted 0x00010000 NETANA_FILTER_RELATION_FILTER_B_NOT 0 Do not negate Filter B 1 Negate Filter B 0x00800000 NETANA_FILTER_RELATION_FILTER_B_ ENABLE 0 Do not enable Filter B 1
7. 2014 Example Code char tDevInfo szFirmwareName tDevInfo ulVersionMajor DevInfo ulVersionMinor DevInfo ulVersionBuild DevInfo ulVersionRevision 53 60 Premier Porres Zu Cros Su Pilllktersize Sacha tDevInfo ulPortCnt tDevInfo ulGpioCnt tDevInfo ulFilterSize if NULL szDeviceToUse primer NIS cewiles found Cor Further Castine er y else NETANA_HANDLE hDevice NULL Get a handle to the device if NETANA_NO_ERROR lResult netana_open_device szDeviceToUse amp hDevice printf Error opening device s ErrorCode 0x 08X r n szDeviceToUse lResult else printf Starting tests on Device s r n joe alione x8 1 ConfigureGPIOs hDevice ConfigureFilters hDevice DoCapture hDevice EE EEN printf Test ended r n netana_close_device hDevic return 0 netANALYZER API Windows XP Vista 7 8 DOC091113DRVO7EN Revision 7 English 2014 05 Released Public szDeviceToUse ran r n Hilscher 2009 2014 Error List 54 60 5 Error List Generally there are two separate kinds of errors within the netANALYZER API netANALYZER Device Driver Errors on page 54 Capturing Errors on page 58 5 1 netANALYZER Device Driver Errors The netANALYZER Device Driver Error Numbers are built according to the following table Bit Description D15 DO C
8. NETANA_CAPTURE_STATE_RUNNING Capture is active 3 NETANA_CAPTURE_STATE_STOP_PENDING Capturing is stopped and firmware waits for user to call netana_stop_capture The error is indicated in the ulCaptureError parameter ulCaptureError Error indication of firmware 0x00000000 NETANA_CAPTURE_ERROR_STOP_TRIGGER Capturing stopped by user or GPIO trigger 0xC0660004 NETANA_CAPTURE_ERROR_NO_DMACHANNEL Firmware was unable to find a free DMA channel 0xC0660005 NETANA_CAPTURE_ERROR_URX_OVERFLOW Critical error in XPEC during reception 0xC066000B NETANA_CAPTURE_ERROR_NO_HOSTBUFFER No free host buffer found This indicates the filesystem for filewriting is slow or the application takes to long handling the incoming data 0xC066000C NETANA_CAPTURE_ERROR_NO_INTRAM Firmware is out of memory resources and is unable to buffer more data This may also be caused by a slow file system or a slow application 0xC066000D NETANA_CAPTURE_ERROR_FIFO_FULL Firmware is out of FIFO resources and is unable to buffer more data This may also be caused by a slow file system or a slow application 0xC0770000 NETANA_CAPTURE_ERROR_DRIVER_FILE_FULL End of capture file reached Driver has stopped capturing 0xC0770001 NETANA_CAPTURE_ERROR_DRIVER_INVALID_BUFFERSIZE Internal capture buffer overflow no free INTRAM pvUser User specific parameter passed to netana_start_capture Table 22 Status Callback Parameters netANA
9. be processed Therefore the average of the callback s execution time must not exceed the cycle time of a notifcation Otherwise the DMA buffer resources will be exhausted and the running capture will fail with the error NETANA_CAPTURE_ERROR_NO_HOSTBUFFER The period of the notification callbacks depends on A The configured default DMA buffer timeout default value 50 ms Example Default timeout 50 ms Number of DMA buffers 8 Resulting cycle time 50 ms Independently of the amount of data to be captured the data callback will be called at least every 50 ms Blocking the execution for more than 400 ms 8 50 ms the DMA buffer resources will be exhausted B The configured DMA buffer size and the amount of data to be captured Example Size of DMA buffer 512 kByte Number of DMA buffers 8 Capture load max 50 MB sec Resulting cycle time 10 ms Due to the capture load every 10 ms one DMA buffer will be signaled Blocking the execution for more than 80 ms 8 10 ms the DMA buffer resources will be exhausted Depending on the configuration and the amount of traffic to capture blocking the execution for more than the resulting cycle time may lead to exhaustion of DMA buffer resources The resulting error will stop the running capture netANALYZER API Windows XP Vista 7 8 DOC091113DRVO7EN Revision 7 English 2014 05 Released Public O Hilscher 2009 2014 API Definitions 42 60 High load mode Note Th
10. 000D NETANA FILECAPTURE NOT ACTIVE Capturing to file is not enabled 0x8022000E NETANA_CONFIGURATION_ERROR Capture configuration error 0x8022000F NETANA THREAD CREATION FAILED Creation of worker thread failed 0x80220010 NETANA_NO_BUFFER_DATA Buffer content not valid 0x80220011 NETANA NO STATE CHANGE No state change 0x80220012 NETANA NO PLUGIN FOUND No plug in found Table 35 List of Driver Errors netANALYZER API Windows XP Vista 7 8 DOC091113DRVO7EN Revision 7 English 2014 05 Released Public 56 60 Hilscher 2009 2014 Error List 57 60 5 1 4 Transport Errors These errors are associated with facility code NETANA_DRIVER 35 Value Definition Description 0x80230001 ETANA_TRANSPORT_CHECKSUM_ERROR Checksum incorrect 0x80230002 ETANA_TRANSPORT_LENGTH_INCOMPLETE Transport length is incomplete 0x80230003 ETANA_TRANSPORT_DATA_TYPE_UNKOWN Unknown data type 0x80230004 ETANA_TRANSPORT_DEVICE_UNKNOWN Device is unknown 0x80230005 ETANA_TRANSPORT_CHANNEL_UNKNOWN Channel is unknown 0
11. 021000C NETANA_TRANSFER TIMEOUT Transfer timed out 0x8021000D NETANA_IROEVENT_CREATION FAILED Error creating interrupt events 0x8021000E NETANA_IRQLOCK_CREATION_ FAILED Error creating internal IRQ locks Table 34 List of Toolkit Errors netANALYZER API Windows XP Vista 7 8 DOC091113DRVO7EN Revision 7 English 2014 05 Released Public Hilscher 2009 2014 Error List 5 1 3 Driver Errors These errors are associated with facility code NETANA_DRIVER 34 Value Definition Description 0x80220001 NETANA_IOCTL_FAILED Error sending IOCTL to driver 0x80220002 NETANA DRIVER NOT RUNNING netANALYZER Driver is not running 0x80220003 NETANA DEVICE NOT FOUND Device with the given name does not exist 0x80220004 NETANA DEVICE STILL OPEN Device is still in use by another application 0x80220005 NETANA DEVICE NOT OPEN Device is not open 0x80220006 NETANA MEMORY MAPPING FAILED Failed to map memory 0x80220007 NETANA FILE OPEN ERROR Error opening file 0x80220008 NETANA FILE READ FAILED Error reading file 0x80220009 NETANA_FILE CREATION FAILED Error creating file 0x8022000A NETANA FILE WRITE FAILED Error writing file 0x8022000B NETANA CAPTURE ACTIVE Capturing is currently active 0x8022000C NETANA CAPTURE NOT ACTIVE Capturing is currently stopped 0x8022
12. 0x80200002 NETANA INVALID PORT Invalid port number 0x80200003 NETANA OUT OP MEMORY Out of memory 0x80200004 NETANA FUNCTION FAILED Function failed Generic Error 0x80200005 ETANA_INVALID_POINTER Invalid pointer 0x80200006 ETANA_INVALID_HANDLE Invalid handle 0x80200007 ETANA_NO_WORKING_DIRECTORY No working directory 0x80200008 ETANA_NO_ENTRY_FOUND No entry found 0x80200009 ETANA_FUNCTION_NOT_AVAILABLE Function not available Table 33 List of Generic Errors 5 1 2 Toolkit Errors These errors are associated with facility code Ni ETANA_TOOLKIT 33 Value Definition Description 0x80210001 NETANA TKIT INITIALIZATION FAILED Toolkit initialization failed 0x80210002 NETANA_DMABUFFER_CREATION FAILED Creation of DMA buffers failed 0x80210003 NETANA_HWRESET_ERROR Error during hardware reset of device 0x80210004 NETANA CHIP NOT SUPPORTED Chip type is not supported by toolkit 0x80210005 NETANA DOWNLOAD FAILED Download of Bootloader Firmware failed 0x80210006 NETANA_FW_START_FAILED Error starting firmware 0x80210007 NETANA DEV MAILBOX FULL Device mailbox is full 0x80210008 NETANA DEV NOT READY Device not ready 0x80210009 NETANA DEV MAILBOX TOO SHORT Mailbox is too short for packet 0x8021000A NETANA_DEV_GET_NO_PACKET No packet available 0x8021000B NETANA BUFFER_TOO_SHORT Given buffer is too short 0x8
13. 27 Management CommandNETANA MNGMT CMD D EN GCAN nennen 45 Table 28 Management CommandNETANA MNOGMT CMD GET D V FEATURE ssssssssssssssinsssrrssrrnnerrrrrrrrnnsrrrnnnt 46 Table 29 Management Command NETANA_MNGMT_CMD_SET_DEV_CLASS_ EIUTER 47 Table 30 Systematics of netANALYZER Device Driver Error Numbers nen 54 Table 31 Classification of Severity codes AAA 54 T ble 32 Classification of facillty ee EE 54 Table 337 Listof E Al AAA 20 nalen NENNEN tiata ite denr nina lalaheinn 55 Table 34 List of Toolkit Err rs 4 2 ee HR Renee 55 BEE Ee BE DIAA el EE 56 kable 36 l stof Transport Errofs cities 57 Table 37 List of Transport Header State Erors nono nn nnnnnn nn nrnnnn rn nan nnnrnnnnnnnrnnnnrnranennnninns 57 Table 38 List of Marshaller Target Errors AAA 58 Table 39 Listof Capturing EMOS ui a lid 58 6 2 List of Figures Figure 1 Overview Capturing ProCeSs AA 7 Figure 2 Ring Buffer Mode State Diagram ccccecsceseseeeseeeceneeeeeeeseaeeeaeeceaeeeaeeseaeeeaaeeseaeeeaeeseaeeseaeeeeeeeeeeeeeeeieeesieeeeeeee 8 Figure 3 Capture File Overview V1 3 and later AAA 9 netANALYZER API Windows XP Vista 7 8 DOC091 113DRVO7EN Revision 7 English 2014 05 Released Public O Hilscher 2009 2014 Appendix 6 3 Contacts Headquarters Germany Hilscher Gesellschaft f r Systemautomation mbH Rheinstrasse 15 65795 Hattersheim Phone 49 0 6190 9907 0 Fax 49 0 6190 9907 50 E Mail info hilscher
14. 80200001 Invalid parameter at least one parameter points to 0 NETANA_IOCTL_FAILED 0x80220001 General error at sending of IOCTL Example NETANA_HANDLE hDev if NETANA_NO_ERROR 0x0 netana_open_device netANALYZER_0 amp hDev netANALYZER API Windows XP Vista 7 8 DOC091113DRVO7EN Revision 7 English 2014 05 Released Public Hilscher 2009 2014 API Definitions 3 3 5 netana_close device Close a previously opened device 27 60 INT32 netana_close_device NETANA_HANDLE hDev Parameter Description hDev Device returned from a previous call to netana_open_device Returns NETANA_NO_ERROR 0x0 Success NETANA_INVALID_HANDLE 0x80200006 Invalid handle NETANA_IOCTL_FAILED 0x80220001 General error at sending of IOCTL 3 3 6 netana_device_info Get device information for an open device INT32 netana_device_info NETANA_HANDLI UINT32 ulDevInfoSize E hDev NETANA_DEVICE_INFORMATION_T ptDevInfo Parameter Description hDev Device handle ulDevinfoSize Size of the structure passed in ptDevInfo ptDevinfo Returned device information Returns NETANA_NO_ERROR 0x0 Success NETANA_INVALID_HANDLE 0x80200006 Invalid handle NETANA_IOCTL_FAILED 0x80220001 General error at sending of IOCTL NETANA_INVALID_PARAMETER 0x80200001 Invalid para
15. ANA_MNGMT_CMD_DEV_SCAN 45 60 Command ID NETANA_MNGMT_CMD_DEV_SCAN Function Scan for new devices Input parameters Element Type Description ptScanInParam NETANA_MNGMT_DEV_SCAN_IN_T Function pointer to call back function for signaling bus scan state For more information see NETANA_MNGMT_DEV_SCAN_IN_T on page 18 Output parameters Element Type Description ptScanOutParam NETANA_MNGMT_DEV_SCAN_OUT_T Number of found devices For more information see NETANA_MNGMT_DEV_SCAN_OUT_T on page 18 Table 27 Management Command NETANA_MNGMT_CMD_DEV_SCAN Returns NETANA_NO_ERROR 0x0 Success NETANA_IOCTL_FAILED 0x80220001 General error at sending of IOCTL NETANA_INVALID_PARAMETER 0x80200001 Invalid parameter NETANA_DEVICE_NOT_FOUND 0x80220003 Device with the given name not found netANALYZER API Windows XP Vista 7 8 DOC091113DRVO7EN Revision 7 English 2014 05 Released Public O Hilscher 2009 2014 API Definitions 46 60 NETANA_MNGMT_CMD_GET_DEV_FEATURE Command ID NETANA_MNGMT_CMD_GET_DEV_FEATURE Function Returns information structure of the device various features Input parameters Element Type Description ptFeatureln NETANA_MNGMT_GET_DEV_FEATURE_IN_T Need to be set to the handle of the requested device For more information see NETANA
16. API Windows XP Vista 7 8 DOC091113DRVO7EN Revision 7 English 2014 05 Released Public Hilscher 2009 2014 API Definitions 25 60 3 3 3 netana_enum_device Enumerate available devices INT32 netana_enum_device UINT32 ulCardNr UINT32 ulDevInfoSize NETANA_DEVICE_INFORMATION_T ptDevInfo Parameter Description ulCardNr Number of the device to return ulDevinfoSize Size of the structure passed in ptDevinfo ptDevinfo Returned device information Returns NETANA_NO_ERROR 0x0 Success NETANA_DEVICE_NOT_FOUND 0x80220003 Device with card number was not found NETANA_IOCTL_FAILED 0x80220001 General error at sending of IOCTL Example UINT32 ulCard 0 NETANA_DEVICE_INFORMATION_T tDevInfo 0 hile NETANA_NO_ERROR 0x0 netana_enum_device ulCard sizeof tDevInfo amp tDevInfo os netANALYZER API Windows XP Vista 7 8 DOC091113DRVO7EN Revision 7 English 2014 05 Released Public Hilscher 2009 2014 API Definitions 3 3 4 netana_open_device 26 60 Opens a device for exclusive access A device can only be opened once even from the same process INT32 netana_open_device char szDevice NETANA_HANDLE phDev Parameter Description szDevice Device description phDev Returned handle for device access Returns NETANA_NO_ERROR 0x0 Success NETANA_INVALID_PARAMETER 0x
17. CaptureError s_fCaptureStopPending true break default printf Unknown Capture State u ErrorCode 0x 08X r n ulCaptureState ulCaptureError break bes New data indication callback Called by the driver when new Capture data has arrived static void APIENTRY DataCallback void pvBuffer uint32_t ulDataSize void pvUser uint8_t pbBuffer uint8_t pvBuffer babes 2 ic Os e E 0 uint32_t ulFrameCnt 0 while ulOffset lt ulDataSize NETANA_FRAME_HEADER_T ptFrame NETANA_FRAME_HEADER_T pbBuffer ulOffset uint32_t ulFrameLen ptFrame gt ulHeader NETANA_FRAME_HEADER_LENGTH_MSK gt gt NETANA_FRAME_HEADER_LENGTH_SRT ulFrameCnt netANALYZER API Windows XP Vista 7 8 DOC091113DRVO7EN Revision 7 English 2014 05 Released Public O Hilscher 2009 2014 Example Code 52 60 4 4 Main Program This piece of C code can be used as main program to execute the functions ConfigureGPIOs ConfigureFilters DoCapture described above il Main Fi ER Z aloe cel ame ere MORA pare Ap 22 IE lResult NETANA_DRIVER_INFORMATION_T tDriverInfo 0 charsz szDeviceToUse NULL E ey To open che Cleiweie if NETANA_NO_ERROR lResult netana_driver_information sizeof tDriverInfo amp tDriverInfo printf Error opening driver ErrorCode 0x 08X r n lResult e
18. D_FUNCTION Function is not supported 0x80230026 NETANA_TRANSPORT_TIMEOUT Transport timeout Table 37 List of Transport Header State Errors netANALYZER API Windows XP Vista 7 8 DOC091113DRVO7EN Revision 7 English 2014 05 Released Public Hilscher 2009 2014 58 60 Error List 5 1 6 Marshaller Target Error This error is associated with facility code NETANA_DRIVER 35 Value Definition Description 0xC0230001 NETANA_CAPTURE_ERROR_ON_TARGET Capture error on the target device Table 38 List of Marshaller Target Errors 5 2 Capturing Errors These are low level errors detected by netANALYZER hardware Capture Errors 0x00000000 NETANA_CAP TURE ERROR_STOP_TRIGGER No error Capturing stopped by user or GPIO trigger 0xC0660004 NETANA_CAPTURE ERROR_NO_DMACHANNEL No free DMA channel available Probably host is too slow 0xC0660005 NETANA_CAPTURE ERROR_URX_OVERFLOW XC buffer overflow URX overflow Occurs because a non IEEE802 3 conform traffic is captured e g too short frames too small IFG 0xC066000B NETANA_CAPTURE ERROR_NO_HOSTBUFFER No free DMA buffer available Host is too slow to handle data efficiently 0xC066000C NETANA_CAPTURE ERROR_NO_INTRAMBUFFER Internal capture buffer overflow no free INTRA
19. ERROR 0x0 Success NETANA_INVALID_HANDLE 0x80200006 Invalid handle NETANA_IOCTL_FAILED 0x80220001 General error at sending of IOCTL NETANA_FUNCTION_FAILED 0x80200004 Function failed Problem at reading or setting the status netANALYZER API Windows XP Vista 7 8 DOC091113DRVO7TEN Revision 7 English 2014 05 Released Public Hilscher 2009 2014 API Definitions 3 3 21 netana_mngmt_exec_cmd 43 60 netana_mngmt_exex_cma provides a general function call interface The command specified by ulCommandld specifies the function to execute UINT32 VOLE UN SZ void UIN32 INT32 netana_mngmt_exec_cmd ulCommandlId pvInputParameter ulInputParameterSize pvOutputParameter ulOutputParameterSize Parameter Description ulCommandld Number of the command see table below pvinputParameter depending on the command see table below ullnputParameterSize Size of related input parameter in units of bytes pvOutputParameter depending on the command see table below ulOutputParameterSize Size of related output parameter in units of bytes The following table lists the available function interface commands provided by the general function call Command Description NETANA_MNGMT_CMD_BLINK Blink command see table Management Command NETANA_MNGMT_CMD_BLINK NETANA_MNGMT_CMD_DEV_SCAN Scan for new devices see table Management Command
20. EV_SCAN Element Type Description pfnCallBack PFN_SCAN_CALLBACK Function pointer to scan callback For more information see PFN_SCAN_CALLBACK on page 22 Table 17 Structure NETANA_MNGMT_DEV_SCAN_IN_T Description 3 1 9 NETANA_MNGMT_DEV_SCAN_OUT_T This structure is required when calling the netana_mngmt_exec_cmd function with the Management Command NETANA_MNGMT_CMD_DEV_SCAN Element Type Description ulNofDevices UINT32 Number of found devices Table 18 Structure NETANA_MNGMT_DEV_SCAN_OUT_T Description 3 1 10 NETANA_MNGMT_GET_DEV_FEATURE_IN_T This structure is required when calling the netana_mngmt_exec_cmd function with the Management Command NETANA_MNGMT_CMD_GET_DEV_FEATURE Element Type Description hDev NETANA_HANDLE Handle of the requested device Table 19 Structure NETANA_MNGMT_GET_DEV_FEATURE_IN_T Description netANALYZER API Windows XP Vista 7 8 DOC091113DRVO7EN Revision 7 English 2014 05 Released Public O Hilscher 2009 2014 API Definitions 3 1 11 19 60 NETANA_MNGMT_GET_DEV_FEATURE_OUT_T This structure provides the device features and limitations The information structure is returned when calling the netana_mngmt_exec_cmd function with the Management Command NETANA_MNGMT_CMD_GET_DEV_FEATURE Element Type Description ulStructVersion ulPhysType UINT32 UINT32 Version of thi
21. Enable Filter B 0x01000000NETANA_FILTER_RELATION_FILTER_A_NOT 0 Do not negate Filter A 1 Negate Filter A 0x80000000 NETANA_FILTER_RELATION_FILTER_A_ENABLE 0 Do not enable Filter A 1 Enable Filter A netANALYZER API Windows XP Vista 7 8 DOC091113DRVO7TEN Revision 7 English 2014 05 Released Public Hilscher 2009 2014 API Definitions Returns 37 60 NETANA_NO_ERROR 0x0 Success NETANA_INVALID_HANDLE 0x80200006 Invalid handle NETANA_IOCTL_FAILED 0x80220001 General error at sending of IOCTL NETANA_INVALID_PORT 0x80200002 Invalid port number netANALYZER API Windows XP Vista 7 8 DOC091113DRVO7EN Revision 7 English 2014 05 Released Public O Hilscher 2009 2014 API Definitions 38 60 3 3 17 netana_set filter Set the capturing filters of an Ethernet port INT32 APIENTRY netana_set_filter NETANA_HANDLE hDev UINT32 ulPort NETANA_FILTER_T ptFilterA NETANA_FILTER_T ptFilterB UINT32 ulRelationShip Parameter Description hDev Device handle ulPort Ethernet port number ptFilterA Filter A Note Pointers in these structure must be allocated by user and the correct length must be passed ptFilterB Filter B Note Pointers in these structure must be allocated by user and the correct length must be passed ulRelationShip Relationship of both filters Bit mask 0
22. Extended Device Information Structure NETANA_EXTENDED_DEV_INFO_1 netANALYZER API Windows XP Vista 7 8 DOC091113DRVO7EN Revision 7 English 2014 05 Released Public Hilscher 2009 2014 API Definitions 15 60 3 1 4 NETANA_FILTER_T This structure defines a filter that can be used to filter out Ethernet traffic and is used in the following functions netana_get_ netana_set_fil fi lter see section netana_get_filteron page 33 lter see section netana_set_filter on page 38 Table 11 Structure Filter Description netANALYZER API Windows XP Vista 7 8 Element Type Description ulFilterSize UINT32 Size of the filter Note This value must match the length of the following pointers pbMask UINT8 Filter Mask byte array of ulFilterSize pbValue UINT8 Filter Value byte array of ulFilterSize DOC091113DRVO7EN Revision 7 English 2014 05 Released Public Hilscher 2009 2014 API Definitions 16 60 3 1 5 NETANA_GPIO_MODE_T This structure defines the mode of a GPIO and is used in the following functions netana_get_gpio_mode see section netana_get_gpio_mode on page 32 netana_set_gpio_mode see section netana_set_gpio_mode on page 32 The following modes are available Mode Value Action NETANA_GPIO_MODE_NONE 0 don t capture GPIO NETANA_GPIO_MODE_RISING_EDGE 1 Capture rising edge NETANA_GPIO_MODE_FALLING_EDGE NETANA_GPIO_MODE_OU
23. FA hilscher COMPETENCE IN COMMUNICATION Driver Manual netANALYZER API Windows XP Vista 7 8 V1 5 x x Hilscher Gesellschaft fur Systemautomation mbH www hilscher com DOC091113DRVO7TEN Revision 7 English 2014 05 Released Public Introduction 2 60 Table of Contents 1 Jl de GT de BE 4 LI About this Document sechs un ern 4 1 2 MISVORReVISIONS iaa a RICH Ikea 4 1 3 Terms Abbreviations and Definitions cocccncnnnnncncnonononenenenenininenenonenanenonanenonenanonanananananananeninoss 4 1 4 Legal Nolesz nn Heeres A AA ed a ag 5 1 41 Copyright arme riesen 5 1 4 2 Important Notes ninia aio 5 UE Exclusi n of Elabllityaraasra ee ehe 6 E ele 6 2 O dE ROESER En E 7 sch Ring BUttenMOGGs stees eebe ER Eege reiege 8 2 2 Capture File Structure oooooonoccccnnnoccccnononccnnononnncnnnnnnncnnnno nn rn ER EAE EEEE E ERRORE KEEN rr nn EEAS EnO EA 9 3 API Definitions Zeen 22 222 EE EE EES EC 11 dl Stegen eege e deeg 11 3 1 1 NETANA FRAME HEADER Tu nern dt 11 3 1 2 NETANA_DRIVER_INFORMATION TA 12 3 1 3 NETANA_DEVICE_ INFORMATION TA 13 Sul NET ANAZEILEERST Er o Es 15 3 1 5 NETANA GPIO MODE Tissot keep ea Aaa Re lol 16 SLP NETANAZPORTZSTATEZST eebe ees de ee ees 17 3 1 7 NETANAZFILE INFORMATIONLT 2 nennen ar sine 17 3 1 8 NETANA MNGMT D EN GCAN INTE 18 3 1 9 NETANA_MNGMT_DEV_SCAN_QUT Te 18 2110NETANA MNOGMT GET D V FEATURE INTE 18 3 1 11 NETANA_MNGMT_GET_DEV_FEAT
24. IOO NETANA_GPIO1_VOLTAGE_MASK GPIO1 NETANA_GPIO2_VOLTAGE_MASK GPIO2 NETANA_GPIO3_VOLTAGE_MASK GPIO3 ulGpioVoltageSel Voltage selction NETANA_GPIO VOLTAGE 3V 3V NETANA_GPIO_VOLTAGE_24V 24V Returns NETANA_NO_ERROR 0x0 NETANA_INVALID_HANDLE 0x80200006 Success Invalid handle NETANA_IOCTL_FAILED 0x80220001 General error at sending of IOCTL NETANA_INVALID_PARAMETER 0x80200001 Invalid parameter wrong configuration parameter netANALYZER API Windows XP Vista 7 8 DOC091113DRVO7EN Revision 7 English 2014 05 Released Public Hilscher 2009 2014 API Definitions 35 60 3 3 15 netana_get_gpio_voltage The function returns the currently active GPIO voltage selection for a specific GPIO INT32 netana_set_gpio_output NETANA_HANDLE hDev UINT32 ulGpio UINT32 pulGpioVoltageSel Parameter Description hDev Device handle ulGPIO Number of the GPIO pulGpioVoltageSel Pointer to a buffer in which the currently active voltage setting will be returned Returns NETANA_NO_ERROR 0x0 Success NETANA_INVALID_HANDLE 0x80200006 Invalid handle NETANA_IOCTL_FAILED 0x80220001 General error at sending of IOCTL NETANA_INVALID_PARAMETER 0x80200001 Invalid parameter netANALYZER API Windows XP Vista 7 8 DOC091113DRVO7EN Revision 7 English 2014 05 Released Public O Hilscher 2009 2014 API Definitions 3 3
25. InfoSize S SOT to sizeof NETANA_EX ulExtendedInfoType is set to the value 0x00476245 indicating GbE ETANA_ DEVICE _INFORMATION_T must be taken into ENDED_DEV_INFO_T 2 sizeof UINT32 The extended information structure will be filled with additional information about the target system The following table shows the information contained in the structure NETANA_EXTENDED_GBE_DEV_INFO_T within union NETANA_EXTENDED_DEV_INFO_T Element Type Description ablpAddr UINT8 4 IP Address of the remote device abSubnetMask UINT8 4 Subnet Mask of the remote device abMacAddr UINT8 6 MAC Address of the remote device ulServerVersionMajor UINT32 ulServerVersionMinor UINT32 Marshaller server version of the remote device ulServerVersionBuild UINT32 ulServerVersionRevision UINT32 ulDrvVersionMajor UINT32 ulDrvVersionMinor UINT32 Driver version of the remote device ulDrvVersionBuild UINT32 ulDrvVersionRevision UINT32 ulToolkitVersionMajor UINT32 ulToolkitVersionMinor UINT32 Toolkit version of the remote device ulToolkitVersionBuild UINT32 ulToolkitVersionRevision UINT32 ulOSVersionInfoSize UINT32 ulOSMajorVersion UINT32 ulOSMinorVersion UINT32 OS version information of the remote device ulOSBuildNumber UINT32 ulOSPlatformld UINT32 szCSDVersion char 128 Table 10
26. LYZER API Windows XP Vista 7 8 DOC091113DRVO7TEN Revision 7 English 2014 05 Released Public O Hilscher 2009 2014 API Definitions 22 60 3 2 2 PFN_DATA_CALLBACK This function is called if the device has captured new data Note Note the callback restrictions under netana_start_capture on page 40 Function definition void DataCallback void pvData UINT32 ulDataLen void pvUser Parameter Description pvData Pointer to captured data For structure of the data refer to section NETANA_FRAME_HEADER_T on page 11 ulDataLen Length of data in buffer pvUser User specific parameter passed to netana_start_capture Table 23 Data Callback Parameters 3 2 3 PFN_SCAN CALLBACK This function is called cyclically during bus scan At a local device scan bProgress is set to 0 Function definition void ScanCallback UINT8 bProgress UINT32 ulFoundNumber char szLastFound void pvUser Parameter Description bProgress Progress of bus scan in percent 0 100 ulFoundNumber Number of found devices szLastFound Name of the last found device pvUser User specific parameter passed to ScanCallback Table 24 Scan Callback Parameters netANALYZER API Windows XP Vista 7 8 DOC091113DRVO7TEN Revision 7 English 2014 05 Released Public Hilscher 2009 2014 API Definitions 3 3 Functions 23 60 The netANALYZER function offers driver based func
27. M Firmware is out of memory resources and is unable to buffer more data This may also be caused by a slow file system or a slow application 0xC066000D NETANA_CAPTURE ERROR_FIFO_FULL Firmware is out of FIFO resources and is unable to buffer more data This may also be caused by a slow file system or a slow application 0xC0770000 NETANA_CAPTURE ERROR_DRIV ER_FILE FULI End of capture file reached Driver has stopped capturing 0xC0770001 NETANA_CAP TURE ERROR_DRIV UFFERSIZE ER_INVALID_B Internal capture buffer overflow no free INTRAM Table 39 List of Capturing Errors netANALYZER API Windows XP Vista 7 8 DOC091113DRVO7EN Revision 7 English 2014 05 Released Public Hilscher 2009 2014 Appendix 59 60 6 Appendix 6 1 List of Tables Table le EistOt REVISION I VERERREREREREICTEERPEELPEPRERFEPFERFEFEFERUFEFETHEERSTLTERFFEFEBPEPEFIERFEEFEFEUDLERFTEFERESEFER lOs leia rias 4 Table 2 Terms Abbreviations and Definitions naar nn n rn cnn nan nnnnnn nn rnnnnnnncnnnncnns 4 Table 3 Structure of HEA Header da nice ao da 9 Table 4 Structure Capture File Data V1 3 and later 10 Table 5 Structure Capture Data Header 11 hable 62 Erame Error Godes 2 aid eds 11 Table 7 Structure Driver Inf rmation seniri 0er anna et
28. NETANA_MNGMT_CMD_DEV_SCAN NETANA_MNGMT_CMD_GET_DEV_FEATURE Returns structure containing information about the device features see table Management Command NETANA_MNGMT_CMD_GET_DEV_FEATURE NETANA_MNGMT_CMD_SET_DEV_CLASS_FILTER Allows altering the device filter of the driver see table Management Command NETANA_MNGMT_CMD_SET_DEV_CLASS_FILTER Table 25 General Function Call Interface netANALYZER API Windows XP Vista 7 8 DOC091113DRVO7EN Revision 7 English 2014 05 Released Public Hilscher 2009 2014 44 60 API Definitions NETANA_MNGMT_CMD_BLINK Command ID NETANA_MNGMT_CMD_BLINK Function Execute the blink command on a specific device for device identification Will blink the status LEDs on the device for 10 seconds Input parameters Element Type Description szDevice char Device name Output parameters Element Type Description none none none Table 26 Management Command NETANA_MNGMT_CMD_BLINK Returns NETANA_NO_ERROR 0x0 Success NETANA_IOCTL_FAILED 0x80220001 General error at sending of IOCTL NETANA_INVALID_PARAMETER 0x80200001 Invalid parameter NETANA_DEVICE_NOT_FOUND 0x80220003 Device with the given name not found netANALYZER API Windows XP Vista 7 8 DOC091113DRVO7EN Revision 7 English 2014 05 Released Public O Hilscher 2009 2014 API Definitions NET
29. Packed information for the following Data Bit 0 7 Frame error code see Table 6 Frame Error Codes below Bit 8 O Ethernet Port 1 GPIO Port Bit 9 O Ethernet mode 1 Transparent mode Bits 10 13 Version field set it always to 1 Bits 14 15 Port number this frame was received on Bits 16 27 Length of the following data Caplen ullTimestamp UINT64 Nanosecond timestamp based on ullReferencetime from netana_start_capture abData UINT8 Caplen Captured data The size is included in ulHeader Note This array will be padded up to the next 32 bit boundary Table 5 Structure Capture Data Header The following frame error codes are defined for bits O to 7 of ulHeader Frame error code NETANA_FRAME_HEADER_ERROR_CODE SES en a ans MSK_TO MSK_FCS MSK_ALI MBLE E R O LONG ERROR GN_ERR MII RX_ER error Alignment error FCS error Frame too long No valid SFD found Frame smaller 64 bytes Preamble shorter than 7 bytes Preamble longer than 7 bytes Table 6 Frame Error Codes netANALYZER API Windows XP Vista 7 8 DOC091113DRVO7EN Revision 7 English 2014 05 Released Public Hilscher 2009 2014 API Definitions 12 60 3 1 2 NETANA_DRIVER_INFORMATION_T This structure is used in the netana_device_information section NETANA_DEVICE_INFORMATION_T on page 13 to query all features configuration of the driver
30. RROR Error when opening the Marshaller API specified in the reg path Table 8 Meanings of Marshaller related Error Codes netANALYZER API Windows XP Vista 7 8 DOC091113DRVO7EN Revision 7 English 2014 05 Released Public Hilscher 2009 2014 API Definitions 3 1 3 13 60 NETANA_DEVICE_INFORMATION_T This structure defines all features of a netANALYZER device and is used in the following functions netana_enum_device see section nelana_enum_device on page 25 netana_device_in fo see section netana_device_info on page 27 Element Type Description szDeviceName char 64 Name of the device Used for netana_open_device ulPhysicalAddress UINT32 Physical DPM Address of the device ulDPMSize UINT32 Size ofthe device DPM ulUsedDPMSize UINT32 Used DPM size of firmware ulDPMLayoutVersion UINT32 Version information of DPM Structure ullnterrupt UINT32 Interrupt Vector ulDeviceNr UINT32 Device number of netANALYZER card ulSerialNr UINT32 Device s serial number ausHwOptions UINT16 4 Hardware options of all 4 ports usManufacturer UINT16 Manufacturer code of device usProductionDate UINT16 Production date usDeviceClass UINT16 Device class bHwRevision UINT8 Revision of the hardware bHwCompatibility UINT8 Hardware compatibility Index ulOpenCnt UINT32 Number of times this device has been opened ulPortCnt UINT32 Number of available Ethe
31. SD 3 1 8 Update for driver V1 5 3 3 1 9 3 1 10 3 1 11 3 1 12 3 3 14 3 3 15 3 3 21 7 2014 04 29 SD 3 3 19 Added note of callback restrictions RG 3 3 19 Description of high load mode and small corrections added Table 1 List of Revisions 1 3 Terms Abbreviations and Definitions Term Description DPM Dual Ported Memory DMA Direct Memory Access GbE Gigabit Ethernet GPIO General Purpose Input Output Table 2 Terms Abbreviations and Definitions netANALYZER API Windows XP Vista 7 8 DOC091113DRVO7EN Revision 7 English 2014 05 Released Public O Hilscher 2009 2014 Introduction 5 60 1 4 Legal Notes 1 4 1 Copyright 2008 2014 Hilscher Gesellschaft f r Systemautomation mbH All rights reserved The images photographs and texts in the accompanying material user manual accompanying texts documentation etc are protected by German and international copyright law as well as international trade and protection provisions You are not authorized to duplicate these in whole or in part using technical or mechanical methods printing photocopying or other methods to manipulate or transfer using electronic systems without prior written consent You are not permitted to make changes to copyright notices markings trademarks or ownership declarations The included diagrams do not take the patent situation into account The company names and product descriptions included in t
32. TPUT Capture falling edge Set output mode level is set by netana_set_gpio_output 2 3 NETANA_GPIO_MODE_OUTPUT_PWM 4 Set output to one 5 NETANA_GPIO_MODE_SYNC Table 12 GPIO Modes Use this GPIO as sync input currently not supported For the NETANA_GPIO_MODE_RISING_EDGE and NETANA_GPIO_MODE_FALLING_EDGE modes use the following structure in order to define capturing triggers Element Type Description ulMode UINT32 Mode for this GPIO 0 NETANA_GPIO_MODE_NONE Don t use GPIO 1 NETANA_GPIO_MODE_RISING_EDGE Capture rising edges on this GPIO 2 NETANA_GPIO_MODE_FALLING_EDGE Capture falling edges on this GPIO ulCaptureTriggers UINT32 Setup trigger events Bitmask 0x00000001 NETANA_GPIO_TRIGGER_START Use first detected rising falling edge to start capture 0x00010000 NETANA_GPIO_TRIGGER_STOP Use first detected rising falling edge to stop capture ulEndDelay UINT32 Delay in multiples of 10 ns after capturing is stopped Note This value will be used if NETANA_GPIO_TRIGGER_STOP is set for this GPIO Table 13 Structure GPIO Description For the mode NETANA_GPIO_MODE_OUTPUT_PWM use the following structure Element Type Description ulMode UINT32 Mode for this GPIO 4 NETANA_GPIO_MODE_OUTPUT_PWM Sets GPIO to PWM mode ulHiPeriod UINT32 High period of signal generator in 10 ns Minimum value is 1 maximum
33. URE_OUTLT uueeessensssnsnnsennnnnnennnnnnnnnnnnnnnnnnnnennennnnnnenn 19 3 1 12 NETANA_MNGMT_SET_DEV_CLASS_FILTER_INLT nuuususssnessnnnensennnnnnnnnnnnnnnnnnnnennnnnenneenn 20 3 2 e lee 21 3 21 PEN STATUS GALLBAGK ee eege aan Een SE eet ees 21 3 22 PENZDATAZGALEBACK na eege ed dE geed Ita Gd Eed deeg 22 3 2 3 PFN SCAN OA T BAO K 0 Eed 22 3 3 FUNCIONS a er A EH 23 3 3 1 petana driver Information 24 3 3 2 metana_get_error description 24 38 3 Netana EIDEN sde Sege ern ie Eege dE een EE 25 3 3 4 Netana open device nenne een 26 3 3 5 Metana lte GeVICEs EE EE EENS 27 3 3 6 netana device J A Eed ee lees 27 3 3 7 petana get portstat u enn see elle a eda eee A 28 CeMo MNA LEE EH 29 3 39 petana access PAY reg BOERPRPERHFELFHRRERRSPERRTEEFEIPRUPRETEFEFEELTHECEERTLEFEERRFEFFGFEFEFEFGIERFPETTEFFELITERFFERFTTERFLEFFPER ERFR 30 e El BEIER TEE 31 3 3517 n t na get gpi MOE cocina ia ic 32 3 3 12 petana Set gplo Modest cia e a tee eee 32 3 3 18 netan set gpio output asiatico ralla dio 33 3 3 14 netana Set gpio voltgee eege ee enciende alain Adnan REES ERe 34 3 3 15 netana get ele e Be UE EE 35 33 16 netanalget lilter er Her aaa een ati 36 SE el TEE 38 e DEE In ANG Le e EE 39 3 3 19 Netana Start EE 40 3 3 20 n8tana stop Captures soci een he une Ed ENEE 42 3 3 21 NetanaMNGMt Exec CMG viaria atadas 43 4 Example OA ii adenda 48 4 1 Function ConfigureGPIOs Configuring GPIO nana nccnncnnns 48 4 2 Fu
34. _MNGMT_GET_DEV_FEATURE_IN _Ton page 18 e g ptFeatureln gt hDev hDeviceHandle Output parameters Element Type Description ptFeatureOut NETANA_MNGMT_GET_DEV_FEATURE_OUT_T Strucutre contains information about the device features For more information see NETANA_MNGMT_GET_DEV_FEATURE_O UT_T on page 19 Table 28 Management Command NETANA_MNGMT_CMD_GET_DEV_FEATURE Returns NETANA NO ERROR 0x0 Success NETANA_IOCTL_FAILED 0x80220001 General error at sending of IOCTL NETANA_INVALID_PARAMETER 0x80200001 Invalid parameter NETANA_DEVICE_NOT_FOUND 0x80220003 Device with the given name not found netANALYZER API Windows XP Vista 7 8 DOC091113DRVO7EN Revision 7 English 2014 05 Released Public O Hilscher 2009 2014 API Definitions 47 60 NETANA_MNGMT_CMD_SET_DEV_CLASS_FILTER Command ID NETANA_MNGMT_CMD_SET_DEV_CLASS FILTER Function Allows changing the device filter of the driver Input parameters Element Type Description ptFilterIn NETANA_MNGMT_SET_DEV_CLASS FILTER_IN_T Mask need to be set to the device class to be filtered For for more information see NETANA_MNGMT_SET_DEV_CLASS_FILT ER_IN_T on page 20 e g ptFilterln gt ulDeviceClass NETANA_DEV_CLASS_NANL_500 By default the driver filters for netANALYZER Output parameters Element Type Description Ta
35. _info NETANA_HANDLE hDev UINT32 ulFilelnfoSize NETANA_FILE_INFORMATION_T ptFileInfo Parameter Description hDev Device handle ulFilelnfoSize Size of the passed structure in ptFilelnfo ptFilelnfo Returned File information Returns NETANA_NO_ERROR 0x0 Success NETANA_INVALID_HANDLE 0x80200006 Invalid handle NETANA_IOCTL_FAILED 0x80220001 General error at sending of IOCTL NETANA_INVALID_PARAMETER 0x80200001 Invalid parameter at least one parameter points to 0 NETANA_CAPTURE_NOT_ACTIVE 0x8022000C Capturing is currently stopped NETANA_FILECAPTURE_NOT_ACTIVE 0x8022000D Capturing to file is not enabled netANALYZER API Windows XP Vista 7 8 DOC091113DRVO7EN Revision 7 English 2014 05 Released Public O Hilscher 2009 2014 API Definitions 3 3 19 40 60 netana_start_capture Start a live capture This function must be called after all ports and GPIOs have been correctly configured Note Always call the function netana_set filelist before calling netana_start_capture if capturing to file is intended INT32 netana_start_capture UINT UINT UINT UINT PEN 32 ulCaptureMode NETANA_HANDLE hDev 32 ulPortEnableMask 32 ulMacMode 64 ullReferenceTime STATUS_CALLBACK pfnStatus PFN_DATA_CALLBACK pfnData void pvUser Parameter Description hDev Devic
36. abFilterMaskA 12 OxFF abFilterMaskA 13 OxFF abFilterValueA 12 0x08 abFilterValueA 13 0x00 tFilterA ulFilterSize sizeof abFilterMaskA tFilterA pbMask abFilterMaskA tFilterA pbValue abFilterValueA Filter B matches ARP Frames Frametype 0x0806 abFilterMaskB 12 OxFF abFilterMaskB 13 OxFF abFilterValueB 12 0x08 abFilterValueB 13 0x06 tFilterB ulFilterSize sizeof abFilterMaskB tFilterB pbMask abFilterMaskB tFilterB pbValue abFilterValueB ulRelation NETANA FILTER RELATION FILTER_A_ ENABLE ETANA FILTER RELATION PILIER BR ENABLE ETANA FILTER _RELATION_A OR P ETANA_FILTER_RELATION_ACCEPT_ FILTER Setup filters on Port 0 to only capture TCP IP Frames Frametype 0x0800 and ARP Type 0x0806 frames if NETANA_NO_ERROR lResult netana_set_filter hDevice 0 amp tFilterA amp tFilterB ulRelation printf Error setting filters on port 0 ErrorCode 0x 08X r n lResult else printf Successfully set filters on Port O r n netANALYZER API Windows XP Vista 7 8 DOC091113DRVO7EN Revision 7 English 2014 05 Released Public Hilscher 2009 2014 Example Code 50 60 4 3 Function DoCapture Capturing This piece of C code function DoCapture can be used to start capturing data It starts the capturing p
37. ana_file_info Get current file capture state Actual file written total bytes captured etc netana_start_capture Start a live capture netana_stop_capture Stop a running live capture netana_mngmt_exec_cmd General function interface netANALYZER API Windows XP Vista 7 8 DOC091113DRVO7EN Revision 7 English 2014 05 Released Public Hilscher 2009 2014 API Definitions 24 60 3 3 1 netana_driver_information Query driver specific information INT32 netana_driver_information WINS UDSYN OSTAS NETANA_DRIVER_INFORMATION_T ptDrvInfo Parameter Description ulDrvinfoSize Size of the structure passed in ptDrvInfo ptDrvinfo Returned driver information Returns NETANA_NO_ERROR 0x0 Success NETANA_DEVICE_NOT_FOUND 0x80220003 Device has not been found NETANA_IOCTL_FAILED 0x80220001 General error at sending of IOCTL NETANA_INVALID_ PARAMETER 0x80200001 Invalid parameter occurs when ptDrvInfo NULL 3 3 2 netana_get_error_description Get the error description text for a return code from the netANALYZER API INT32 netana_get_error_description INT32 lError UINT32 ulBufferSize char szBuffer Parameter Description lError Error code to return description for ulBufferSize Size of the passed buffer szBuffer Buffer for returned text Returns NETANA_NO_ERROR 0x0 Success netANALYZER
38. ble 29 Management Command NETANA_MNGMT_CMD_SET_DEV_CLASS_FILTER Returns NETANA_NO_ERROR 0x0 Success NETANA_IOCTL_FAILED 0x80220001 General error at sending of IOCTL NETANA_INVALID_PARAMETER 0x80200001 Invalid parameter NETANA_DEVICE_NOT_FOUND 0x80220003 Device with the given name not found netANALYZER API Windows XP Vista 7 8 DOC091113DRVO7EN Revision 7 English 2014 05 Released Public Hilscher 2009 2014 Example Code 4 Example Code 48 60 The following examples explain the use of the netANALYZER API They commonly require the following set of include statements incl E cil incl incl mei alae al 4 1 The following piece of C code function Con Windows h netana_user h netana_errors h lt stdio h gt lt conio h gt lt string gt lt time h gt figureGP on a netANALYZER card It adjusts GPIOs 0 and 1 void ConfigureGPIOs N ae E RESTINTA N ETANA_GPIO_MODE_T tGpio ETANA_HANDLE hDevice 0 I Berio C20 0 to b caprcorec on risia odee tGpio ulCaptureTriggers tGpio ulMode if NI ETANA os Function ConfigureGPIOs Configuring GPIO Os can be used to configure the GPIOs NETANA_GPIO_TRIGGER_NONE NETANA_GPIO_MODE_RISING_EDGE ERROR lResult netana_set_gpio_mode hDevice 0 amp tGpio printf
39. com Support Phone 49 0 6190 9907 99 E Mail de support hilscher com Subsidiaries China Hilscher Systemautomation Shanghai Co Ltd 200010 Shanghai Phone 86 0 21 6355 5161 E Mail info hilscher cn Support Phone 86 0 21 6355 5161 E Mail cn support hilscher com France Hilscher France S a r l 69500 Bron Phone 33 0 4 72 37 98 40 E Mail info hilscher fr Support Phone 33 0 4 72 37 98 40 E Mail fr support hilscher com India Hilscher India Pvt Ltd New Delhi 110 065 Phone 91 11 26915430 E Mail info hilscher in Italy Hilscher Italia S r l 20090 Vimodrone MI Phone 39 02 25007068 E Mail info hilscher it Support Phone 39 02 25007068 E Mail it support hilscher com netANALYZER API Windows XP Vista 7 8 DOC091113DRVO7EN Revision 7 English 2014 05 Released Public 60 60 Japan Hilscher Japan KK Tokyo 160 0022 Phone 81 0 3 5362 0521 E Mail info hilscher jp Support Phone 81 0 3 5362 0521 E Mail jp support hilscher com Korea Hilscher Korea Inc Seongnam Gyeonggi 463 400 Phone 82 0 31 789 3715 E Mail info hilscher kr Switzerland Hilscher Swiss GmbH 4500 Solothurn Phone 41 0 32 623 6633 E Mail info hilscher ch Support Phone 49 0 6190 9907 99 E Mail ch support hilscher com USA Hilscher North America Inc Lisle IL 60532 Phone 1 630 505 5301 E Mail info hilscher us Support Phone 1 630 505 5301 E Mai
40. e handle ulCaptureMode 0 NETANA_CAPTUREMODE_DATA Capture whole Ethernet frames 1 NETANA_CAPTUREMODE_TIMESTAMPS Only capture timestamps reception time of incoming frames 2 NETANA_CAPTUREMODE_HIGHLOAD A special mode for measurements to capture reduced frames at very high network load In order to avoid PCI bus overload all frames are truncated to a length of 58 bytes See description below 0x80000000 NETANA_CAPTUREMODE_RINGBUFFER Set this bit to enable data capturing in ringbuffer mode only valid for capturing to file ulPortEnableMask Bitmask of enabled Ethernet ports Each bit represents a port ulMacMode 0 NETANA_MACMODE_ETHERNET Capture IEEE 802 3 frames in Ethernet mode 1 NETANA_MACMODE_TRANSPARENT Capture all bytes on Ethernet without regarding any specifications ullReferenceTime Capture reference time in nanoseconds This value is expected to be the UNIX time Seconds since 1 1 1970 in nanoseconds as Wireshark expects this format Note When using a non UNIX reference time conversion with the standard tools will produce a wrong timestamp When using customer tools the reference time may by set to any customer value pfnStatus Status change notification callback Set to NULL if not needed when registering callback note the following restrictions pfnData Callback for captured data Set to NULL if not needed Note If this parameter is NULL a capturing fil
41. e namen nassen el 12 Table 8 Meanings of Marshaller related Error Codes nro nnnnnnnn ramon nrnnnnnnnnnnnnnnnanennnninns 12 Table 9 Structure Device Information nr n nan nn rra nn nn nan RR RR RR Rra NEEE aa E nn nnnnnnnnnanennnninns 13 Table 10 Extended Device Information Structure NETANA_EXTENDED_DEV_INFO_Tocconooccnnnonnnnnonncnnnnnnnnnnnnnnnnnnnnnnenenns 14 Table 11 Structure Filter Description ld 15 Table 12G PIO Modest hai date 16 TFable 13 Structure GPIO DeScriptionin egen d id dre de ii 16 Table ke Structure GPIO Description iii ti Earl entre 16 Table 15 Structure Portstate Descrptlon A 17 Table 16 Structure File Information Description ooooncccinninicnccinnncnncccnoncnnorncnnrnnn nn n norris 17 Table 17 Structure NETANA_MNGMT_DEV_SCAN_IN_T Description 18 Table 18 Structure NETANA_MNGMT_DEV_SCAN_OUT_T Description 18 Table 19 Structure NETANA_MNGMT_GET_DEV_FEATURE_IN_T Description 18 Table 20 Structure NETANA_MNGMT_GET_DEV_FEATURE_OUT_T Description 20 Table 21 Structure NETANA_MNGMT_SET_DEV_CLASS_FILTER_IN_T Description 20 Table 22 Status Callback Parameter 21 Table 23 Data Callback Parameters ccccscccecseneceeseeeeeseneeeeeseeeeeseaeeesscaeeeeecaaeeeseaaeeesecaeeceseaeesecseeseecneeeessneeeesenseeeess 22 Table 24 Scan Callback Parameters seisine eiiiaoaioe alu ns is 22 Table 25 General Function Call Interface 43 Table 26 Management Command NETANA_MNGMT_CMD_ BLINK onen 44 Table
42. e needs to be set via netana_set_filelist when registering callback note the following restrictions pvUser User parameter passed on callbacks netANALYZER API Windows XP Vista 7 8 DOC091113DRVO7EN Revision 7 English 2014 05 Released Public Hilscher 2009 2014 API Definitions 41 60 Returns NETANA_NO_ERROR 0x0 Success NETANA_INVALID_HANDLE 0x80200006 Invalid handle NETANA_IOCTL_FAILED 0x80220001 General error at sending of IOCTL NETANA_INVALID_PARAMETER 0x80200001 Invalid parameter wrong configuration parameter NETANA_MEMORY_MAPPING_FAILED 0x80220006L Error mapping memory to user application NETANA_THREAD_CREATION_ FAILED 0x8022000F Error creating worker thread NETANA_CAPTURE_ACTIVE 0x8022000B Capture is already active NETANA_FILE_WRITE_FAILED 0x8022000A Writing the capture file failed NETANA_FUNCTION_FAILED 0x80200004 Function failed Problem at reading or setting the status Restrictions of registered callbacks Restricted API usage within callback It is not possible to call any other function of the netANALYZER API within the callbacks Duration of callback is limited The callback functions registered via the parameter pfnStatus and pfnData must ensure not to block the execution Since the driver will wait for the callbacks to be completed during callback execution no further data or state changes will
43. ending of IOCTL NETANA_INVALID_PARAMETER 0x80200001 Invalid parameter wrong configuration parameter NETANA_FUNCTION_FAILED 0x80200004 Function failed Problem at reading or setting the status netANALYZER API Windows XP Vista 7 8 DOC091113DRVO7EN Revision 7 English 2014 05 Released Public Hilscher 2009 2014 31 60 API Definitions 3 3 10 netana_set filelist Set file data and activate capturing to HEA file Files will be named lt szPath gt 1 lt szBaseFilename gt _ lt Filenumber gt hea Example SAB Lern szBaseFileName capture ulFileCount 2 The following files will be created C capture_0 hea C capture_l hea INT32 netana_set_filelist NETANA_HANDLE hDev char szPath char szBaseFilename UINT32 ulFileCount UINT64 ullFileSize Parameter Description hDev Device handle szPath Directory to place files in Note UNC paths are not supported szBaseFilename Base filename without extension ulFileCount Number of files to create ullFileSize Size in Bytes of each file Returns NETANA_NO_ERROR 0x0 Success NETANA_IOCTL_FAILED 0x80220001 General error at sending of IOCTL NETANA_INVALID_PARAMETER 0x80200001 Invalid parameter wrong configuration parameter NETANA_CAPTURE_ACTIVE 0x8022000B Capture is currently active netANALYZER API Windows XP Vista 7 8 DOC091113DRVO7EN Revis
44. firmware we ve understood that capturing was automatically stopped netana_stop_capture hDevice primei Stores Capirmelac ye in p static bool s_fCaptureStopPending false Yi Status change callback Called by the driver if a function pointer was passed in netana_start_capture and the state of the card has changed Wi ae netANALYZER API Windows XP Vista 7 8 DOC091113DRVO7TEN Revision 7 English 2014 05 Released Public Hilscher 2009 2014 Adjust Offset to next DWORD aligned address ulOffset sizeof ptFrame while ul printf Received Su frames ulOffset Offset ulFrameLen 4 DataLen u r n ulFrameCnt ulDataSize Example Code 51 60 static void APIENTRY StatusCallback uint32_t ulCaptureState uint32_t ulCaptureError void pvUser switch ulCaptureState case NETANA_CAPTURE_STATE_OFF printf Capture Stopped ErrorCode 0x 08X r n ulCaptureError break case NETANA_CAPTURE_STATE_START_PENDING primer Mibiejoysueiinve Capture Start ea e break case NETANA_CAPTURE_STATE_RUNNING printf Capture Running r n break case NETANA_CAPTURE_STATE_STOP_PENDING printf Capture Stop Pending ErrorCode 0x 08X r n ul
45. his document may be trademarks or brands of the respective owners and may be trademarked or patented Any form of further use requires the explicit consent of the respective rights owner 1 4 2 Important Notes The user manual accompanying texts and the documentation were created for the use of the products by qualified experts however errors cannot be ruled out For this reason no guarantee can be made and neither juristic responsibility for erroneous information nor any liability can be assumed Descriptions accompanying texts and documentation included in the user manual do not present a guarantee nor any information about proper use as stipulated in the contract or a warranted feature It cannot be ruled out that the user manual the accompanying texts and the documentation do not correspond exactly to the described features standards or other data of the delivered product No warranty or guarantee regarding the correctness or accuracy of the information is assumed We reserve the right to change our products and their specification as well as related user manuals accompanying texts and documentation at all times and without advance notice without obligation to report the change Changes will be included in future manuals and do not constitute any obligations There is no entitlement to revisions of delivered documents The manual delivered with the product applies Hilscher Gesellschaft f r Systemautomation mbH is not liable under any ci
46. ime sync support 0 no 1 yes via DPM Table 20 Structure NETANA_MNGMT_GET_DEV_FEATURE_OUT_T Description 3 1 12 NETANA_MNGMT_SET_DEV_CLASS FILTER_IN_T This structure is required when calling the netana_mngmt_exec_cmd function with the Management Command NETANA_MNGMT_CMD_SET_DEV_CLASS FILTER Element Type Description ulDeviceClass UINT32 Device class which should be applied Mask need to be set to the device class to be filtered NETANA_DEV_CLASS_NANL_ 500 netANALYZER devices NETANA_DEV_CLASS_NSCP_100 netSCOPE devices Table 21 Structure NETANA_MNGMT_SET_DEV_CLASS_FILTER_IN_T Description netANALYZER API Windows XP Vista 7 8 DOC091113DRVO7EN Revision 7 English 2014 05 Released Public O Hilscher 2009 2014 API Definitions 21 60 3 2 Callbacks The netANALYZER API can notify the user for different events via callbacks This chapter describes the available callbacks 3 2 1 PFN_STATUS_ CALLBACK This function is called if the device changes its state during capture Note Note the callback restrictions under netana_start_capture on page 40 Function definition void StatusCallback UINT32 ulCaptureState UINT32 ulCaptureError void pvUser Parameter Description ulCaptureState State of the capturing 0 NETANA_CAPTURE_STATE_OFF Capture is inactive 1 NETANA_CAPTURE_STATE_START_PENDING Firmware is preparing to start capturing 2
47. ion 7 English 2014 05 Released Public Hilscher 2009 2014 API Definitions 3 3 11 Get the current configuration of a GPIO netana_get_gpio_mode 32 60 INT32 netana_get_gpio_mode NETANA_HANDLE hDev UINT32 ulGpio NETANA_GPIO_MODE_T ptMode Parameter Description hDev Device handle ulGPIO Number of the GPIO ptMode Returned GPIO configuration Returns NETANA_NO_ERROR 0x0 Success NETANA_INVALID_HANDLE 0x80200006 Invalid handle NETANA_IOCTL_FAILED 0x80220001 General error at sending of IOCTL NETANA_INVALID_PARAMETER 0x80200001 Invalid parameter wrong GPIO number NETANA_CAPTURE_NOT_ACTIVE 0x8022000C Capturing is currently stopped 3 3 12 netana_set_gpio_mode Configure a GPIO pin as input trigger INT32 netana_set_gpio_mode NETANA_HANDLE hDev UINT32 ulGpio NETANA_GPIO_MODE_T ptMode Parameter Description hDev Device handle ulGPIO Number of the GPIO mode ptMode GPIO configuration Returns NETANA_NO_ERROR 0x0 Success NETANA_INVALID_HANDLE 0x80200006 Invalid handle NETANA_IOCTL_FAILED 0x80220001 General error at sending of IOCTL NETANA_INVALID_PARAMETER 0x80200001 Invalid parameter wrong GPIO number NETANA_CAPTURE_NOT_ACTIVE 0x8022000C Capturing is currently stopped NETANA_FUNCTION_FAILED 0x80200004 Function failed PWM is already ac
48. is function is available from Windows driver version 1 5 5 Use at least netANALYZER firmware version 1 5 4 At very high data load occurring on all four ports simultaneously the whole amount of data is too large be fully transmitted via PCI DMA Therefore the netANALYZER offers a special high load mode to be able to perform measurements under such conditions at all However this special high load mode reduces data load by truncating each frame length to 58 bytes This mode is useful for generating frame statistics in cases where the frame payload is not important The status is always still valid FCS alignment errors Nevertheless the following negative effects have to be taken into account Truncated data is lost also there is no possibility to get the original length of a specific frame Wireshark would always indicate a frame size of 58 bytes and many frames would be incomplete Therefore using Wireshark in conjunction with the high load mode is not recommendable We recommend to use high load mode only in case all ports have a very high data load near 100 at the same time 3 3 20 netana_stop capture Stop a running live capture This will also close the file in the filelist To re enable capturing to file after this call you will need to call netana_set_filelist INT32 netana_stop_capture NETANA_HANDLE hDev Parameter Description hDev Device handle Returns NETANA_NO_
49. l us support hilscher com O Hilscher 2009 2014
50. ll be padded up to the next 32 Bit boundary Table 4 Structure Capture File Data V1 3 and later 2 2 1 1 File sequence detection in ring buffer mode To be able to process capture files from a ring buffered capture it is necessary to detect all files belonging to the same capture The following steps need to be performed to read capture files recorded in ring buffer mode 1 Get ullCaptureStart from first file 2 Collect all files with the same value for ullCaptureStart 3 Search for the file with the lowest value in ulldx and with a valid ullDataSize gt This is the starting file of the capture 4 Iterate over all following files until the last file or a file with an invalid DataSize is reached netANALYZER API Windows XP Vista 7 8 DOC091113DRVO7TEN Revision 7 English 2014 05 Released Public Hilscher 2009 2014 API Definitions 11 60 3 API Definitions The netANALYZER API located in the files netANALYZER_API d11 netANALYZER_API 1ib offers several functions to access the device These functions and their parameters structures are defined in the following sections 3 1 Structures The following sections describe all structures that can be passed to the netANALYZER functions 3 1 1 NETANA_FRAME_HEADER_T This structure is the base of all captured data It is used in the capture files HEA and in the data callbacks Element Type Description ulHeader UINT32
51. lse Panel UDrealwere Iie renarsie Ae We hat pri VENADO p princi Y Version Su Su Su u r n tDriverInfo ulVersionMajor tDriverInfo ulVersionMinor tDriverInfo ulVersionBuild tDriverInfo ulVersionRevision d jovealioieit Y Carels printf DMA Buffers tDriverInfo ulDMABufferSize printf Max Files UE Via Ee eer ao Desen A u x Su Bytes r n tDriverInfo ulDMABufferCount 7 u r n tDriverInfo ulMaxFileCount eiert 1 Pound cards s yonne Enumerate all available boards and use the first found one to do our tests For Lab e ulltere Or ullaze lt edeiverinto wlliCarcleinee willCareckrr NETANA_DEVICE_INFORMATION_T tDevInfo 0 if NETANA_NO_ERROR lResult netana_enum_device ulCard sizeof tDevInfo amp tDevInfo printf u Error enumerating card u ErrorCode 0x 08X r n ullard ullard lResult else if NULL szDeviceToUse NOTE We will always use the first available device for our tests szDeviceToUse _strdup char tDevInfo szDeviceNanme printf u DeviceName s r n ulCard char tDevInfo szDeviceName jOIETLIME IE OU DeviceNr u SerialNr Sulrin tDevinfo ulDeviceNr tDevInfo ulSerialNr prat say Firmware s V u u u u r n netANALYZER API Windows XP Vista 7 8 DOC091113DRVO7TEN Revision 7 English 2014 05 Released Public Hilscher 2009
52. meter at least one parameter points to 0 netANALYZER API Windows XP Vista 7 8 DOC091113DRVO7EN Revision 7 English 2014 05 Released Public Hilscher 2009 2014 28 60 API Definitions 3 3 7 netana_get_portstat Retrieve diagnostic statistic counters for a specific port INT32 netana_get_portstat NETANA_HANDLE hDev SNS ierg WEINE SL WS NETANA_PORT_STATE_T ptStatus Parameter Description hDev Device handle ulPort Port to get information for ulSize Size of the structure passed in ptStatus ptStatus Returned port state Returns NETANA_NO_ERROR 0x0 Success NETANA_INVALID_HANDLE 0x80200006 Invalid handle NETANA_IOCTL_FAILED 0x80220001 General error at sending of IOCTL NETANA_INVALID_PARAMETER 0x80200001 Invalid parameter wrong configuration parameter NETANA_FUNCTION_FAILED 0x80200004 Function failed Problem at reading or setting the status netANALYZER API Windows XP Vista 7 8 DOC091113DRVO7EN Revision 7 English 2014 05 Released Public Hilscher 2009 2014 API Definitions 3 3 8 netana_get_state Get current capturing state error 29 60 INT32 netana_get_state NETANA_HANDLE hDev UINT32 pulCaptureState UINT32 pulCaptureError Parameter Description hDev Device handle pulCaptureState Returned capture state 0 NETANA_CAPTURE_STATE_OFF Capture is inac
53. nction ConfigureFilters Setting Filters nen 49 4 3 Function DoCapture Capturing iaieiiea a a a a ie a E a aaia 50 AA Mal Progr il dE e 52 5 O A see EE EE Ee 54 5 1 metANALYZER Device Driver Emors nenn 54 5AA Generic Errors lt i geass Raabe cat dE EES 55 netANALYZER API Windows XP Vista 7 8 DOC091113DRVO7EN Revision 7 English 2014 05 Released Public Hilscher 2009 2014 Introduction 3 60 ENK e all ge Henn ee ran Ba een 55 Bled Driver O 56 e O TC TE 57 5 1 5 Transport Header State Errors u n enseeen o 57 5 1 6 Marshaller Target Error 2 een ea an Hi 58 5 2 Capturing Errr Srnie aiteru ean eda ea a aaa hrs 58 6 NT 2 22 Ee 59 621 EISE ot Tables en mare MER Henn valerie ates 59 SE DC ge el az 59 6 3 0 1 72 EE 60 netANALYZER API Windows XP Vista 7 8 DOC091113DRVO7EN Revision 7 English 2014 05 Released Public Hilscher 2009 2014 Introduction 4 1 1 This manual netANALYZ Introduction 4 60 About this Document ER_AP1 describes the netANALYZER API which are functions provided by the d11 netANALYZER_API lib 1 2 List of Revisions Rev Date Name Chapter Revision 1 2009 11 28 MTr all Created for V1 3 2 2010 02 01 MTr RG all Expanded 3 2010 02 01 MTr RG Examples added 4 2012 03 27 SD HP RG Update for V1 4 GbE extension 5 2012 05 04 SD HP RG 3 1 5 Small corrections 3 2 3 3 3 17 6 2013 11 06
54. ode This item represents facility s individual status code D27 D16 Facility This item represents the facility code according to Table 32 Classification of facility codes D28 Reserved bit This item contains a reserved bit D29 Customer code flag D31 D30 Severity code The severity code classifies the error messages according to their severity according to Table 31 Classification of severity codes Table 30 Systematics of netANALYZER Device Driver Error Numbers The following table explains the possible severity codes D31 D30 Error classification 0 0 Success 0 1 Informational 1 0 Warning 1 1 Error Table 31 Classification of severity codes The following table explains the possible facility codes Facility Source facility of error code 0 FACILITY_NULL 32 NETANA_GENERIC 33 NETANA_TOOLKIT 34 NETANA_DRIVER Table 32 Classification of facility codes netANALYZER API Windows XP Vista 7 8 DOC091113DRVO7EN Revision 7 English 2014 05 Released Public Hilscher 2009 2014 Error List 5 1 1 Generic Errors These errors are associated with facility code NETANA_GE 55 60 Value Definition Description 0x00000000 NETANA_NO ERROR No Error 0x80200001 NETANA INVALID PARAMETER Invalid parameter
55. presents one GPIO from 0 max 31 currently up to 4 0 does not support output mode 1 does support output mode ulGpioOutputPWMSupport UINT32 Bitmask each represents one GPIO from 0 max 31 currently up to 4 0 does not support output PWM 1 does support output PWM ulGpioSyncInSupport UINT32 Bitmask each represents one GPIO from 0 max 31 currently up to 4 0 does not support sync input at GPIO 1 does support sync input at GPIO ulGpioTriggerStartSupport UINT32 Bitmask each represents one GPIO from 0 max 31 currently up to 4 0 does not support trigger start event at GPIO 1 does support trigger start event at GPIO ulGpioTriggerStopSupport UINT32 Bitmask each represents one GPIO from 0 max 31 currently up netANALYZER API Windows XP Vista 7 8 DOC091113DRVO7EN Revision 7 English 2014 05 Released Public O Hilscher 2009 2014 API Definitions 20 60 to 4 0 does not support trigger stop event at GPIO 1 does support trigger stop event at GPIO ulGpioVoltage3VSupport UINT32 Bitmask each represents one GPIO from 0 max 31 currently up to 4 0 does not support 3 3V at GPIO 1 does support 3 3V at GPIO ulGpioVoltage24VSupport UINT32 Bitmask each represents one GPIO from 0 max 31 currently up to 4 0 does not support 24V at GPIO 1 does support 24V at GPIO ulSyncSupport UINT32 The device offers t
56. rcumstances for direct indirect incidental or follow on damage or loss of earnings resulting from the use of the information contained in this publication netANALYZER API Windows XP Vista 7 8 DOC091113DRVO7EN Revision 7 English 2014 05 Released Public Hilscher 2009 2014 Introduction 6 60 1 4 3 Exclusion of Liability The software was produced and tested with utmost care by Hilscher Gesellschaft f r Systemautomation mbH and is made available as is No warranty can be assumed for the performance and flawlessness of the software for all usage conditions and cases and for the results produced when utilized by the user Liability for any damages that may result from the use of the hardware or software or related documents is limited to cases of intent or grossly negligent violation of significant contractual obligations Indemnity claims for the violation of significant contractual obligations are limited to damages that are foreseeable and typical for this type of contract It is strictly prohibited to use the software in the following areas for military purposes or in weapon systems for the design construction maintenance or operation of nuclear facilities in air traffic control systems air traffic or air traffic communication systems in life support systems in systems in which failures in the software could lead to personal injury or injuries leading to death We inform you that the software was not developed for u
57. rnet ports ulGpioCnt UINT32 Number of available GPIO Inputs ulFilterSize UINT32 Size of the Ethernet filters in bytes ulCounterSize UINT32 Size of the statistics counter area in DPM szFirmwareName char 32 Firmware name ulVersionMajor UINT32 ulVersionMinor UINT32 EEN ulVersionBuild UINT32 ulVersionRevision UINT32 ulExtendedInfoSize UINT32 Size of the extended info field in bytes ulExtendedInfoType UINT32 Type of extended info tExtendedInfo NETANA_EXTENDED_DEV_INFO_T Extended information block depends on ulExtendedInfoType Table 9 Structure Device Information In order to be backward compatible with V1 3 it is possible to simply omit the last three elements Of NETANA_DEVI CE INFORMATION_T i e last three lines of Table 9 Structure Device Information In this case the structure of V1 3 is used and the reduced length of the structure has to be taken into account in the calculation of parameter ulDevInfoSize in netana_enum_device Ofnetana_device_info respectively netANALYZER API Windows XP Vista 7 8 DOC091113DRVO7EN Revision 7 English 2014 05 Released Public Hilscher 2009 2014 API Definitions 14 60 Otherwise in case of referencing a remote device when calling the above mentioned functions The full length of the structure N account for the calculation of parameter ulDevInfoSize ulExtended
58. rocess with data transfer by callback via DataCallback and status callback via StatusCallback Note If you want to capture to a file you will need to call netana_set_filelist before starting the capture e g netana_set_filelist hDevice C Capture 1 1 1024 1024 1024 void DoCapture NETANA_HANDLE hDevice ae ie JUResullie s Reference time for wireshark needs to be UNIX Timestamp seconds sind 1 1 1970 and as we are using a nanosecond timestamp we need to multiply it with 1000000000 a uint64_t ullReferenceTime _time64 NULL 1000 1000 1000 NOTE If you want to capture to a file you will need to call netana_set_filelist before starting the capture e EI ebe eree Nene ndewieea WEHT Wiessel I 1 1024 1024 Lan Ay if NETANA_NO_ERROR lResult netana_start_capture hDevice 0 OxF NETANA_MACMODE_ETHERNET ullReferenceTime StatusCallback DataCallback NULL printf Error starting capture ErrorCode 0x 08X r n lResult else printf Press any key to stop capturing r n while _kbhit if s_fCaptureStopPending printf netANALYZER Firmware detected an error and stopped capturing r n printf Aborting capture r n break Sleep 10 NOTE We need to call netana_stop_capture even if the firmware stopped automatically to tell the
59. s structure currently 0x00000000 Type of supported physics 0x00000000 Ethernet ulNumPhysPorts UINT32 Number of available Physics ports ulPhysTapPresent UINT32 Physics TAP is built in 0 no 1 yes Bitmask each represents one Eth port from 0 max 31 currently up to 4 ulPhysForwardingSupport UINT32 Support of Physics frame forwarding if no TAP is present 0 no 1 yes Bitmask each represents one Eth port from 0 max 21 currently up to 4 ulPhysPortSpeedSupport UINT32 Bitmask each represents one Physics port from 0 max 31 currently up to 4 0 does not support indicating the link speed 1 does support indicating the link speed ulPhysTransparentModeSuppo rt UINT32 Bitmask each represents one Physics port from 0 max 31 currently up to 4 0 does not support capturing in transparent mode 1 does support capturing in transparent mode ulNumGpios UINT32 Number of available GPIOs ulGpiolnputRisingSupport UINT32 Bitmask each represents one GPIO from 0 max 31 currently up to 4 0 does not support input mode to capture rising edge 1 does support input mode to capture rising edge ulGpiolnputFallingSupport UINT32 Bitmask each represents one GPIO from 0 max 31 currently up to 4 0 does not support input mode to capture falling edge 1 does support input mode to capture falling edge ulGpioOutputModeSupport UINT32 Bitmask each re
60. se in dangerous environments requiring fail proof control mechanisms Use of the software in such an environment occurs at your own risk No liability is assumed for damages or losses due to unauthorized use 1 4 4 Export The delivered product including the technical data is subject to export or import laws as well as the associated regulations of different counters in particular those of Germany and the USA The software may not be exported to countries where this is prohibited by the United States Export Administration Act and its additional provisions You are obligated to comply with the regulations at your personal responsibility We wish to inform you that you may require permission from state authorities to export re export or import the product netANALYZER API Windows XP Vista 7 8 DOC091113DRVO7EN Revision 7 English 2014 05 Released Public Hilscher 2009 2014 Overview 7 60 2 Overview This chapter gives a short overview how capturing with a netANALYZER card works internally It explains capturing to file and the generic state machine for starting stopping a capture The host needs to provide DMA buffers for the firmware running on the netANALYZER device These buffers will be used by the firmware as a circular buffer If a buffer is filled completely or a timeout occurs this buffer will be released to the host The host must now write these buffers to disk or process them directly After this step has been comple
61. ted this buffer must be marked as free again so the firmware can continue using this buffer If the firmware does not find a usable buffer in the ring it will abort capturing and indicate a capture error The following figure shows the capturing process Application Driver Firmware Ethernet Traffic Buffer0 UsedSize TransferSize AE DMA to Host Buffer 0 Ethernet Traffic Write Buffer to File Indicate new Buffer Butter is Full gt Switch Buffer kel p Release rocess incoming SE data o New Data Callback DMA to Host Buffer 1 d ee E Ethernet Traffic DMA to Host Buffer 1 DMA Finished hada so doi e tt EE ANA oeh deg e gt gt Free Buffer 0 Write Buffer to File Indicate new Buffer Buffer 1 Timeout gt Switch Buffer Process incoming Release kel data ad New Data Callback o lo gt Free Buffer 1 Figure 1 Overview Capturing Process netANALYZER API Windows XP Vista 7 8 DOC091113DRVO7EN Revision 7 English 2014 05 Released Public Hilscher 2009 2014 Overview 8 60 2 1 Ring Buffer Mode Since Version 1 3 the netANALYZER supports a ring buffer mode which allows capturing to a set of files until a specific GPIO event occurs or the user stops the capturing process The capture files are named with a running n
62. tions to find open close devices on the computer and device specific functions to configure devices and start stop Ethernet capturing The following functions are available Function Description Driver based netana_driver_information Get driver information Version number of devices netana_get_error_description Get error description text english from an error code netana_enum_device Enumerate found netANALYZER devices netana_open_device Exclusively open a netANALYZER device netana_close_device Close an exclusively opened netANALYZER device Device based netana_device_ into Get device information Firmware version supported features etc netana_get_portstat Get error counters link state and statistics counters netana_get_state Get current capturing state netana_access D reg Read Write PHY registers on a specific port netana_set_filelist De Activate capturing traffic to file for next capture netana_get_gpio_mode Get Configuration of a GPIO Input netana_set_gpio_mode Set Configuration of a GPIO Input netana_set_gpio_output Set Configuration of a GPIO Output netana_set_gpio_voltage Set voltage configuration of GPIOs netana_get_gpio_voltage Get voltage configuration of a GPIO netana_get filter Get active filters for a given port netana_set filter Set active filters for a given port net
63. tive netANALYZER API Windows XP Vista 7 8 DOC091113DRVO7EN Revision 7 English 2014 05 Released Public Hilscher 2009 2014 API Definitions 3 3 13 netana_set_gpio_output 33 60 Configures a GPIO used as output This is only possible while recording is running INT32 netana_set_gpio_output UINT32 ulGpio UINT32 ulLevel NI ETANA_HANDLE hDev Parameter Description hDev Device handle ulGPIO Number of the GPIO ulLevel Output level to be driven 0 1 Returns NETANA_NO_ERROR 0x0 Success NETANA_INVALID_HANDLE 0x80200006 Invalid handle NETANA_IOCTL_FAILED 0x80220001 General error at sending of IOCTL NETANA_INVALID_PARAMETER 0x80200001 Invalid parameter wrong configuration parameter NETANA_FUNCTION_FAILED 0x80200004 Function failed GPIO has not been configured for output netANALYZER API Windows XP Vista 7 8 DOC091113DRVO7EN Revision 7 English 2014 05 Released Public O Hilscher 2009 2014 API Definitions 3 3 14 Configures the GPIO voltage settings netana_set_gpio_voltage 34 60 INT32 netana_set_gpio_output NETANA_HANDLE hDev UINT32 ulGpioSelMask UINT32 ulGpioVoltageSel Parameter Description hDev Device handle ulGpioSelMask Mask of the GPIOs to be affected by the voltage setting delivered by ulGpioVoltageSel NETANA_GPIOO_VOLTAGE_MASK GP
64. tive 1 NETANA_CAPTURE_STATE_START_PENDING Firmware is preparing to start capturing 2 NETANA_CAPTURE_STATE_RUNNING Capture is active 3 NETANA_CAPTURE_STATE_STOP_PENDING Capturing is stopped and firmware waits for user to call netana_stop_capture pulCaptureError Returned capture error Valid if Capture state is NETANA_CAPTURE_STATE_STOP_PENDING Returns NETANA NO ERROR 0x0 Success netANALYZER API Windows XP Vista 7 8 DOC091113DRVO7EN Revision 7 English 2014 05 Released Public Hilscher 2009 2014 API Definitions 3 3 9 netana_access phy_reg Read Write PHY registers on a specific port UN SA BUILD reci lo UINT8 bPhyNum UINT8 bPhyReg UINT16 pusValue UINT32 ulTimeout INT32 netana_access_phy_reg NETANA_HANDLE hDev 30 60 Parameter Description hDev Device handle ulDirection 0 NETANA PHY DIRECTION READ Read from PHY 1 NETANA_PHY_DIRECTION_WRITE Write to PHY bPhyNum Phy Port number 0 3 bPhyReg Register to read write 0 31 pusValue Write value if Direction is NETANA PHY DIRECTION WRITE Returned value if Direction is NETANA PHY DIRECTION READ ulTimeout Timeout in ms to wait for access to complete Returns NETANA_NO_ERROR 0x0 Success NETANA_INVALID_HANDLE 0x80200006 Invalid handle NETANA_IOCTL_FAILED 0x80220001 General error at s
65. umber appended to the base filename see 3 3 10 The following figure describes how the files are handled in ring buffer mode 1 ulldx 0 File 0 WriteFileHeader ullDataSize 1 Wait for data stop New data Data fits in file Update ullDataSize Update ullDataSize in current file in current file ulldx ulldx 1 Switch to next file File File 1 ulFileCount WriteFileHeader ullDataSize 1 Close all files Write data to file Stop Figure 2 Ring Buffer Mode State Diagram netANALYZER API Windows XP Vista 7 8 DOC091113DRVO7EN Revision 7 English 2014 05 Released Public Hilscher 2009 2014 Overview 9 60 2 2 Capture File Structure The capture files are stored in a proprietary format The capturing file format described in the following applies for version 1 3 and higher of the netANALYZER API In contrast to prior versions of the netANALYZER API capturing to multiple files is now supported and the file now contains a special 32 Byte file header The data is stored in raw format starting after the header These files always have a fixed size independently of the length of captured data This allows capturing in ring buffer mode 0x00000000 HEA Fileheader 0x00000020 Packet 5 ullDataSize 0x20 Unused space End of File Figure 3 Capture File Overview V1 3 and later
66. x00000001 NETANA_FILTER_RELATION_A_OR_B 0 Result Filter A AND Filter B corresponds to NETANA_FILTER_RELATION_A_AND_B 0 1 Result Filter A OR Filter B corresponds to NETANA_FILTER_RELATION_A_OR_B 1 0x00000080 NETANA_FILTER RELATION REJECT_FILTER 0 Accept frames if filter matches corresponds to NETANA_FILTER_RELATION_ACCEPT_FILTER 0 1 Reject frames if filter matches corresponds to NETANA_FILTER_RELATION_REJECT_FILTER 0x00000080 0x00008000 NETANA_FILTER_RELATION_ACCEPT_ERROR_FRAMES 0 Error frames are rejected 1 Error frames are accepted 0x00010000 NETANA_FILTER_RELATION_FILTER_B_NOT 0 Do not negate Filter B 1 Negate Filter B 0x00800000 NETANA_FILTER_RELATION_FILTER_B_ ENABLE 0 Do not enable Filter B 1 Enable Filter B 0x01000000 NETANA_FILTER_RELATION_FILTER_A_NOT 0 Do not negate Filter A 1 Negate Filter A 0x80000000 NETANA_FILTER_RELATION_FILTER_A_ENABLE 0 Do not enable Filter A 1 Enable Filter A netANALYZER API Windows XP Vista 7 8 DOC091113DRVO7TEN Revision 7 English 2014 05 Released Public Hilscher 2009 2014 API Definitions 39 60 Returns NETANA_NO_ERROR 0x0 Success NETANA_INVALID_HANDLE 0x80200006 Invalid handle NETANA_IOCTL_FAILED 0x80220001 General error at sending of IOCTL NETANA_INVALID_PORT 0x80200002 Invalid port number 3 3 18 Get the current capture file state netana_file_info INT32 netana_file
67. x80230006 ETANA_TRANSPORT_SEQUENCE Sequence error 0x80230007 ETANA_TRANSPORT_BUFFEROVERFLOW Buffer overflow 0x80230008 ETANA_TRANSPORT_KEEPALIVE Keep alive error 0x80230009 ETANA_TRANSPORT_RESOURCE Resource error 0x8023000A ETANA_TRANSPORT_ERROR_UNKNOWN Unknown error 0x8023000B ETANA_TRANSPORT_RECV_TIMEOU Timeout while receiving data 0x8023000C ETANA_TRANSPORT_SEND_TIMEOU Timeout while sending data 0x8023000D ETANA_TRANSPORT_CONNECT Unable to communicate to the device no answer 0x8023000E ETANA_TRANSPORT_ABORTED Transfer has been aborted due to keep alive timeout or interface detachment 0x8023000F ETANA_TRANSPORT_INVALID_RESPONSE The packet response was rejected due to invalid packet data 0x80230010 ETANA_TRANSPORT_UNKNOWN_DATALAYER The data layer provided by the device is not supported 0x80230011 ETANA_CONNECTOR_FUNCTIONS_READ_ERROR Error reading the connector functions from the DLL 0x80230012 ETANA_CONNECTOR_IDENTIFIER_TOO_LONG Connector delivers an identifier longer than 6 characters 0x80230013 ETANA_CONNECTOR_IDENTIFIER_EMPTY Connector delivers an empty identifier 0x80230014 ETANA_CONNECTOR_DUPLICATE_IDENTIFIER Connector identifier already used Table 36 List of Transport Errors 5 1 5 Transport Header State Errors These errors are associated with facility code NETANA_DRIVER 35 Value Definition Description 0x80230024 NETANA_TRANSPORT_DATA_TOO_SHORT Received transaction data too short 0x80230025 NETANA_TRANSPORT_UNSUPPORTE

netANALYZER API - Windows XP/Vista/7/8

Contents

Download Pdf Manuals

Related Search

Related Contents