Driver Documentation
|
The functionality of the IP-Core is not covered in detail here, however for using the driver it may beneficial to understand what the IP-Core does. To get this information, refer to the IP-Core documentation
The driver is not thread-safe in general. If API functions are used in more than one thread (e.g. in main and IRQs), these API functions must be protected (e.g. by disabling IRQs while the function is executing).
In the simplest case, the IP core is configured before IRQs are enabled and afterwards data is only read from IRQs. In this case, no protection is required.
Why is the IRQ disabling not implemented in the driver itself? Well, what IRQs must be disabled depends on what IRQs the driver API is used from. There may also other protection schemes be used (e.g. mutexes of a RTOS). As a result there is not single true protection mechanism that can be implemented within the driver.
The driver supports two ways of handling IRQs. One of them (Window based IRQ) is a bit more elaborate and easy to use but it only covers the case, that each recorded window is processed by software. This is true in general but the IP-core also allows special configurations where data can be overwritten even if it was not processed. Since the handling of IRQs becomes more specific in this case, a special IRQ handling scheme called Stream based IRQ is implemented. In this case the user is responsible for implementing all actions to be taken in IRQs.
In all IRQ handling schemes, the user is responsible for calling the function PsiMsDaq_HandleIrq() whenever the IP core asserts its interrupt (level sensitive, high active).
Only one IRQ handlig scheme can be used per stream (not both at the same time for the same stream).
In this handling scheme, the driver ensures that the user callback gets called exactly once for every window that is recorded. Spurious interrupts (IRQs getting detected after the data was already processed) are suppressed by the driver. All information about the window which was completed is automatically passed to the user callback.
This handling scheme only works if each window is really processed by the user and protected against being overwritten until the user acknowledged the processing. Implementationwise this means that window overwriting must be disable (config.overwrite = false) and that the user must acknowledge the processing of each window before new data can be recorded into it (by calling PsiMsDaq_StrWin_MarkAsFree()).
Benefits of this scheme is simplicity, drawback is that the driver assumes that the user processes each window which may not be the case in special cases.
In this handling scheme, the driver does only detect which stream fired an IRQ and calls the user callback function. The callback function is called regardless of how many new windows were recorded. The user can do whatever processing of the IRQ he wants. This allows fine grained control over the IP core in special cases but it also means that the user is fully on his own. Therefore this option should only be used if there are good reasons for not using Window based IRQ.
This section contains a little code example to show how the driver is used.