Squashed 'panda/' content from commit ae816c104

git-subtree-dir: panda
git-subtree-split: ae816c104a99a8cd4d508ccd6abdc7b93053529c

drivers/windows/docs/other notes.txt

@@ -0,0 +1,347 @@
+When using the ISO 15765-4 protocol, only SingleFrame messages can be transmitted without a matching
+flow control filter. Also, PCI bytes are transparently added by the API. See PassThruStartMsgFilter
+and Appendix A for a discussion of flow control filters.
+
+
+
+PassThruReadMsgs
+This function reads messages and indications from the receive buffer. All messages and indications shall
+be read in the order that they occurred on the bus. If a transmit message generated a loopback message
+and TxDone indication, the TxDone indication shall always be queued first. Except for loopback messages
+and indications, no messages shall be queued for reception without matching a PASS_FILTER
+(for non-ISO 15765) or FLOW_CONTROL filter (for ISO 15765). On ISO 15765, PCI bytes are transparently
+removed by the API. If the function is successful, a value of STATUS_NOERROR is returned.
+
+
+PassThruWriteMsgs
+Write timeout (in milliseconds).  When a value of 0 is specified, the function queues as
+many of the specified messages as possible and returns immediately. When a value
+greater than 0 is specified, the function will block until the Timeout has expired, an error
+has occurred, or the desired number of messages have been transmitted on the vehicle
+network. Even if the device can buffer only one packet at a time, this function shall be
+able to send an arbitrary number of packets if a Timeout value is supplied. Since the
+function returns early if all the messages have been sent, there is normally no penalty for
+having a large timeout (several seconds). If the number of messages requested have
+been written, the function shall not return ERR_TIMEOUT, even if the timeout value is
+zero.
+
+When an ERR_TIMEOUT is returned, only the number of messages that were sent on
+the vehicle network is known. The number of messages queued is unknown. Application
+writers should avoid this ambiguity by using a Timeout value large enough to work on
+slow devices and networks with arbitration delays.
+
+
+
+PassThruStartPeriodicMsg
+This function will immediately queue the specified message for transmission, and repeat at the specified
+interval. Periodic messages are limited in length to a single frame message of 12 bytes or less, including
+header or CAN ID. Periodic messages shall have priority over messages queued with
+PassThruWriteMsgs, but periodic messages must not violate bus idle timing parameters (e.g. P3_MIN).
+Periodic messages shall generate TxDone indications (ISO 15765) and loopback messages (on any
+protocol, if enabled).  On ISO 15765, periodic messages can be sent during a multi-frame transmission or
+reception. If the function is successful, a value of STATUS_NOERROR is returned. The Pass-Thru
+device must support a minimum of ten periodic messages.
+
+PassThruDisconnect shall delete all periodic messages on that channel. PassThruClose shall delete all
+periodic messages on all channels for the device. All periodic messages will be stopped on a
+PassThruDisconnect for the associated protocol or a PassThruClose for the device.
+
+
+
+PASSTHRUSTARTMSGFILTER
+This function starts filtering of incoming messages.  If the function is successful, a value of
+STATUS_NOERROR is returned. A minimum of ten message filters shall be supported by the interface
+for each supported protocol. PassThruDisconnect shall delete all message filters on that channel.
+
+PassThruClose shall delete all filters on all channels for the device. Pattern and Mask messages shall
+follow the protocol formats specified in Section 8. However, only the first twelve (12) bytes, including
+header or CAN ID, are used by the filter. ERR_INVALID_MSG shall be returned if the filter length
+exceeds 12. Note that this function does not clear any messages that may have been received and
+queued before the filter was set. Users are cautioned to consider performing a CLEAR_RX_BUFFER
+after starting a message filter to be sure that unwanted frames are purged from any receive buffers.
+
+
+
+
+
+
+
+
+FILTER RELATED STUFF
+For all protocols except ISO 15765:
+• PASS_FILTERs and BLOCK_FILTERs will be applied to all received messages. They shall not be
+applied to indications or loopback messages
+
+• FLOW_CONTROL_FILTERs must not be used and shall cause the interface to return
+ERR_INVALID_FILTER_ID
+
+• Both pMaskMsg and pPatternMsg must have the same DataSize and TxFlags. Otherwise, the
+interface shall return ERR_INVALID_MSG
+
+• The default filter behavior after PassThruConnect is to block all messages, which means no messages
+will be placed in the receive queue until a PASS_FILTER has been set. Messages that match a
+PASS_FILTER can still be blocked by a BLOCK_FILTER
+
+• Figure 16 and Figure 17 show how the message filtering mechanism operates
+
+For ISO 15765:
+• PASS_FILTERs and BLOCK_FILTERs must not be used and shall cause the interface to return
+ERR_INVALID_FILTER_ID
+
+• Filters shall not be applied to indications or loopback messages. When loopback is on, the original
+message shall be copied to the receive queue upon the last segment being transmitted  on the bus.
+
+• Non-segmented messages do not need to match a FLOW_CONTROL_FILTER.
+
+• No segmented messages can be transmitted without matching an appropriate FLOW_CONTROL_FILTER.
+An appropriate filter is one in which the pFlowControlMsg CAN ID matches the messages to be
+transmitted. Also, the ISO 15765_ADDR_TYPE (reference TxFlags in Section 8.7.3) bits must match.
+If that bit is set, the first byte after the CAN IDs (the extended address)
+must match too.
+
+• No message (segmented or unsegmented) shall be received without matching an appropriate
+FLOW_CONTROL_FILTER. An appropriate filter is one in which the pPatternMsg CAN ID matches
+the incoming message ID. If the ISO 15765_ADDR_TYPE (reference TxFlags in Section 8.7.3) bit is
+set in the filter, the first byte after the CAN IDs (the extended address) must match too.
+
+• All 3 message pointers must have the same DataSize and TxFlags. Otherwise, the interface shall
+return ERR_INVALID_MSG.
+
+• Both the pFlowControlMsg ID and the pPatternMsg ID must be unique (not match any IDs in any other
+filters). The only exception is that pPatternMsg can equal pFlowControlMsg to allow for receiving
+functionally addressed messages. In this case, only non-segmented messages can be received.
+
+• See Appendix A for a detailed description of flow control filter usage.
+
+
+
+
+8.4 Format Checks for Messages Passed to the API
+The vendor DLL shall validate all PASSTHRU_MSG structures, and return an ERR_INVALID_MSG in the following cases:
+• DataSize violates Min Tx or Max Tx columns in Figure 42
+
+• Source address (Data[3]) is different from the Node ID (Ioctl SET_CONFIG, Parameter NODE_ADDRESS) on J1850PWM
+
+• The header length field is incorrect for the number of bytes in the message on ISO14230
+
+• The CAN_29_BIT flag of the message does not match the CAN_29_BIT flag passed to
+PassThruConnect, unless the CAN_ID_BOTH bit was set on connect
+
+The vendor DLL shall return ERR_MSG_PROTOCOL_ID when the ProtocolID field in the message does
+not match the Protocol ID specified when opening the channel.
+
+
+
+8.5 Conventions for Returning Messages from the API
+When returning a message in PassThruReadMsg:
+– DataSize shall tell the application how many bytes in the Data array are valid. ExtraDataIndex will be
+the (non-zero) index of the last byte of the message. If ExtraDataIndex is not equal to DataSize there
+are extra data bytes after the message. If loopback is on, RxStatus must be consulted to tell if the
+message came via loopback.
+
+– DataSize will be in the range shown in the Min Rx and Max Rx columns of Figure 42. If the device
+receives a message from the vehicle bus that is too long or too short, the message shall be discarded
+with no error.
+
+– For received messages, ExtraDataIndex shall be equal to DataSize, except when the interface is
+returning SAE J1850 PWM IFR bytes. In no case shall ExtraDataIndex be larger than DataSize.
+
+– When receiving a message on an SAE J1850 PWM channel, the message shall have any IFR bytes
+appended. In this case, ExtraDataIndex shall be the index of the first IFR byte, and DataSize shall be
+the total length of the original message plus all IFR bytes. For example, if there are two IFR bytes,
+DataSize will be incremented by two, and ExtraDataIndex will be DataSize - 2. When loopback is on,
+the loopback message shall contain any IFR bytes.
+
+
+
+8.6 Conventions for Retuning Indications from the API
+When returning an indication in PassThruReadMsg:
+– ExtraDataIndex must be zero
+
+– DataSize shall tell the application how many bytes in the Data array are valid
+
+– RxStatus must be consulted to determine the indication type (See Section 8.4).
+
+– A TxDone indication (ISO 15765 only) is generated by the DLL after a SingleFrame message is sent,
+or the last frame of a multi-segment transmission is sent. DataSize shall be 4 (or 5 when the message
+was using Extended Addressing). Data shall contain the CAN ID (and possible Extended Address) of
+the message just sent. If loopback is on, the TxDone indication shall precede the loopback message in
+the receive queue.
+
+– An RxBreak indication (SAE J2610/SCI and SAE J1850VPW only) is generated by the DLL if a break
+is received.
+
+– An RxStart indication is generated by the DLL when starting to receive a message on ISO9141 or
+ISO14230, or when receiving the FirstFrame signal of a multi-segment ISO 15765 message.
+
+
+
+9.1 Naming of Files
+Each vendor will provide a different name implementation of the API DLL and a number of these
+implementations could simultaneously reside on the same PC. No vendor shall name its implementation
+“J2534.DLL”. All implementations shall have the string “32” suffixed to end of the name of the API DLL to
+indicate 32-bit. For example, if the company name is “Vendor X” the name could be VENDRX32.DLL.
+
+For simplicity, an API DLL shall be named in accordance with the file allocation table (FAT) file system
+naming convention (which allows up to eight characters for the file name and three characters for the
+extension with no spaces anywhere).  Note that, given this criteria, the major name of an API DLL can be
+no greater than six characters.  The OEM application can determine the name of the appropriate vendor’s
+DLL using the Win32 Registry mechanism described in this section.
+
+
+
+
+A.1 Flow Control Overview
+ISO 15765-2 was designed to send blocks of up to 4095 bytes on top of the limited 8-byte payload of raw
+CAN frames. If the data is small enough, it can fit in a single frame and be transmitted like a raw CAN
+message with additional headers. Otherwise, the block is broken up into segments and becomes a
+segmented transmission, generating CAN frames in both directions. For flexibility, the receiver of the
+segments can control the rate at which the segments are sent.
+
+Each transmission is actually part of a conversation between two nodes. There is no discovery
+mechanism for conversation partners. Therefore, each desired conversation must be pre-defined on each
+side before the conversation can start. Conversations are symmetric, meaning that either side can send a
+block of data to the other. A conversation can only have one transfer (in one direction) in progress at a
+time. One transfer must complete before the next transfer (in the same or in a different direction) can
+start. The device must support multiple transfers at once, as long as each one is part of a different
+conversation. Raw CAN frames are not allowed when using ISO15765-2.
+
+A key feature of a conversation is that each side has a unique CAN ID, and each side uses their unique
+CAN ID for all transmissions during the conversation. No other CAN IDs are part of the conversation.
+Even though the useful data is only flowing in one direction, both sides are transmitting. One side is
+sending the flow control message to pace the segments of data coming from the other side.
+
+For example, during OBD communication, a pass-thru device and an ECU might have a conversation.
+The pass-thru device will use the "Tester1" physical CAN ID ($241), and the first ECU will use the
+"ECU1" physical CAN ID ($641). During a multi-segment transfer, both sides will be transmitting using
+only their respective IDs. It does not matter if the data is being sent by the ECU or by the Tester, the IDs
+remain the same.
+
+It is important to understand the difference between OBD Requests/Responses and ISO 15765-2
+transfers. The OBD Request is transmitted from the Tester to the ECU using functional addressing.
+Because segmented transfer is not possible on functional addresses, the message must fit in a single
+frame. The OBD Response is a message from the ECU to the Tester using physical addressing. Unlike
+other protocols, the responses are not sequential. In fact, the responses can overlap, as if each ECU
+were having a private conversation with the Tester.  Some of the responses may fit in a single frame,
+while others will require a segmented transfer from the ECU to the tester.
+
+
+A.2 Transmitting a Segmented Message
+When PassThruWrite is called, the API will search the list of flow control filters, looking for a
+pFlowControlMsg that matches the CAN ID (and possible extended address) of the message being sent.
+Upon matching a filter, the pass-thru device will:
+
+• Start the ISO 15765 transfer by sending a FirstFrame on the bus. The CAN ID of this segment was
+specified in both the message and the matching pFlowControlMsg. In our example, this is $241.
+
+• Wait for a FlowControl frame from the conversation partner. The CAN ID to look for is specified in the
+corresponding pPatternMsg. In our example, this is $641.
+
+• Transmit the message data in ConsecutiveFrames according to the FlowControl frame’s instructions
+for BS (BlockSize) and STmin (SeparationTime minimum). Again, the pass-thru device transmits using
+CAN ID specified in pFlowControlMsg. In our example, this is $241.
+
+• Repeat the previous two steps as required.
+
+• When finished, the pass-thru device will place a TxDone indication in the API receive queue. The data
+will contain the CAN ID specified in pFlowControlMsg. In our example, this is $241.
+
+• If loopback is on, the entire message sent will appear in the API receive queue with the
+TX_MSG_TYPE bit set to 1 in RxStatus. The loopback shall not precede the TxDone indication.
+
+Before any multi-segment transfer can take place, the conversation must be set up on both sides. It’s
+assumed that the ECU is already setup. The application is responsible for setting up the pass-thru device.
+This setup must be done once (and only once) per conversation. The setup involves a single call to
+PassThruStartMsgFilter, with the following parameters:
+
+A.2.2 Data Transmission
+Once the conversation is set up, any number of messages (to the conversation partner) can be
+transmitted using PassThruWriteMsg. The interface shall handle all aspects of the transfer, including
+pacing (slowing) the transmission to the requirements of the receiver.
+
+When there are multiple conversations setup, the pass-thru device will search all of the flow control filters
+for a matching pFlowControlMsg. If there is no match, the message cannot be sent because the pass-
+thru device doesn’t know which partner will be pacing the conversation.
+
+When doing blocking writes, it is important to pick a timeout long enough to cover entire transfer, even if
+the ECU is pacing things slowly. Otherwise PassThruWriteMsg will return with a timeout, even though the
+transmission is proceeding normally.
+
+
+A.3 Transmitting an Unsegmented Message
+As a special case, transfers that fit in a single frame can be transmitted without setting up a conversation.
+This is useful during an OBD Request, which is a functionally addressed message that is broadcast to all
+ECUs. This message must be small enough to fit into a single frame (including headers) because it is not
+possible to do one segmented transfer to multiple ECUs.
+
+When using functional addressing for an OBD Request, it is important to remember that there can be no
+direct reply. Instead, each ECU will send their OBD Response using physical addressing to their
+conversation partner (e.g. ECU1 to Tester1, ECU2 to Tester2) as defined by ISO 15765-4. The OBD
+Response may be a segmented transfer, or it may be a single frame.
+
+In this case, no conversation setup is necessary. The call to PassThruWriteMsg is the same as above,
+except that the DataSize must be 7 bytes or less (6 bytes or less if extended addressing is turned on).
+The pass-thru device will automatically insert a PCI byte before transmission.
+
+
+A.4 Receiving a Segmented Message
+Message reception is asynchronous to the application. When a FirstFrame is seen on the bus, the pass-
+thru device will search the list of flow control filters, looking for a pPatternMsg message with the same
+CAN ID (and possible extended address) as the FirstFrame. Upon matching a filter, the pass-thru device will:
+
+• Place an RxStart indication in the API receive queue. This indication has the START_OF_MESSAGE
+bit set in RxFlags. The message data will contain the CAN ID of the sender. In our example, this is
+$641. DataSize will be 4 bytes (5 with extended addressing), and ExtraDataIndex will be zero.
+
+• Send a FlowControl frame to the conversation partner. The FlowStatus field shall be set to
+ontinueToSend. The CAN ID of this segment comes from the filter’s corresponding
+pFlowControlMsg. In our example, this CAN ID is $241. The BS (BlockSize) and STmin
+(SeparationTime minimum) parameters default to zero, but can be changed with the SET_CONFIGIoctl.
+
+• Wait for the conversation partner to send C
+onsecutiveFrames containing the actual data.  The
+partner’s CAN ID is specified in pPatternMsg. In our example, this CAN ID is $641.
+
+• Repeat as necessary until the entire block has been received. When finished, the pass-thru device will
+put the assembled message into the API receive queue. The CAN ID of the assembled message will
+be the CAN ID of the sender. In our example, this CAN ID is $641.
+
+If the FirstFrame does not match any flow control filters, then the message must be ignored by the
+device.
+
+Segmented messages cause the API to generate an RxStart indication. This lets the application know
+that the device has started message reception. It may take a while before message reception is
+complete, especially if the application has increased BS and STmin.
+
+Once the transfer is complete, the entire message can be read like on any other protocol. Usually,
+applications will call PassThruReadMsg again immediately after getting an RxStart indication. Application
+writers should not assume that the complete message will always follow the RxStart indication. If multiple
+conversations are setup, indications and messages from other conversations can be received in between
+the RxStart indication and the actual message. The parameters for PassThruReadMsg are exactly the
+same as in the previous section. The only difference is that the DataSize will be larger and
+ExtraDataIndex will be non-zero.
+
+
+
+A.5 Receiving an Unsegmented Message
+No messages can be received until a conversation is setup. Each conversation setup will receive
+messages from exactly one CAN ID (and extended address if present). Because setup is bi-directional,
+the same PassThruStartMsgFilter call used for transmission will allow for message reception.
+
+When a SingleFrame is seen on the bus, the pass-thru device will search the list of flow control filters,
+looking for a pPatternMsg message with the same C
+AN ID (and possible extended address) as the
+SingleFrame. Upon matching a filter, the pass-thru device will strip the PCI byte and queue the packet for
+reception. If the SingleFrame does not match a flow control filter, it must be discarded.
+
+The only difference between the previous cases is that single-frame messages do not generate an
+RxStart indication.
+
+
+
+
+
+
+
+
+

drivers/windows/docs/reginfo.txt

@@ -0,0 +1,2 @@
+#32 bit: HKEY_LOCAL_MACHINE\SOFTWARE\PassThruSupport
+#64 bit: HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\PassThruSupport

drivers/windows/docs/timeout_info.txt

@@ -0,0 +1,42 @@
+From focum information on NI hardware: https://forums.ni.com/t5/Automotive-and-Embedded-Networks/15765-2-with-NI-products/td-p/1454256
+
+/////////////////////////////////////////////////////////////////////
+Timeout Diag Command is the timeout in milliseconds the master
+waits for the response to a diagnostic request message. The default is
+1000 ms.
+
+Timeout FC (Bs) is the timeout in milliseconds the master waits
+for a Flow Control frame after sending a First Frame or the last
+Consecutive Frame of a block. The default is 250 ms.
+
+Timeout CF (Cr) is the timeout in milliseconds the master waits
+for a Consecutive Frame in a multiframe response. The default is
+250 ms.
+
+Receive Block Size (BS) is the number of Consecutive Frames the
+slave sends in one block before waiting for the next Flow Control
+frame. A value of 0 (default) means all Consecutive Frames are sent
+in one run without interruption.
+
+Wait Time CF (STmin) defines the minimum time for the slave to
+wait between sending two Consecutive Frames of a block. Values
+from 0 to 127 are wait times in milliseconds. Values 241 to 249
+(Hex F1 to F9) mean wait times of 100 μs to 900 μs, respectively.
+All other values are reserved. The default is 5 ms.
+
+Max Wait Frames (N_WFTmax) is the maximum number of WAIT
+frames the master accepts before terminating the connection. The
+default is 10.
+
+
+There are no defined lower limits for these values; you can specify any
+value down to 0. However, as you correctly pointed out, the timing is
+done by Windows, and will be subject to the jitter introduced by the OS
+which can easily be in the order of 10s of milliseconds. It is however
+hard to give more accurate numbers as the actual jitter is dependent on
+the workload of the computer
+/////////////////////////////////////////////////////////////////////
+
+J2534 04.04 does not appear to have default adjustable parameters for
+the timeout related fields. For now, these default values shall be used
+in the Panda J2534 implementation.