From c39ac7a604d9f01f602f88f5770b5832e79fcdde Mon Sep 17 00:00:00 2001 From: "Suren A. Chilingaryan" <csa@suren.me> Date: Tue, 5 May 2015 17:09:46 +0200 Subject: Add doxygen configuration --- NOTES | 311 ------------------------------------------------------------------ 1 file changed, 311 deletions(-) delete mode 100644 NOTES (limited to 'NOTES') diff --git a/NOTES b/NOTES deleted file mode 100644 index d87bbfc..0000000 --- a/NOTES +++ /dev/null @@ -1,311 +0,0 @@ -Memory Addressing -================= - There is 3 types of addresses: virtual, physical, and bus. For DMA a bus - address is used. However, on x86 physical and bus addresses are the same (on - other architectures it is not guaranteed). Anyway, this assumption is still - used by xdma driver, it uses phiscal address for DMA access. I have ported - in the same way. Now, we need to provide additionaly bus-addresses in kmem - abstraction and use it in NWL DMA implementation. - -DMA Access Synchronization -========================== - - At driver level, few types of buffers are supported: - * SIMPLE - non-reusable buffers, the use infomation can be used for cleanup - after crashed applications. - * EXCLUSIVE - reusable buffers which can be mmaped by a single appliction - only. There is two modes of these buffers: - + Buffers in a STANDARD mode are created for a single DMA operation and - if such buffer is detected while trying to reuse, the last operation - has failed and reset is needed. - + Buffers in a PERSISTENT mode are preserved between invocations of - control application and cleaned up only after the PERSISTENT flag is - removed - * SHARED - reusable buffers shared by multiple processes. Not really - needed at the moment. - - KMEM_FLAG_HW - indicates that buffer can be used by hardware, acually this - means that DMA will be enabled afterwards. The driver is not able to check - if it really was enable and therefore will block any attempt to release - buffer until KMEM_HW_FLAG is passed to kmem_free routine as well. The later - should only called with KMEM_HW_FLAG after the DMA engine is stopped. Then, - the driver can be realesd by kmem_free if ref count reaches 0. - - KMEM_FLAG_EXCLUSIVE - prevents multiple processes mmaping the buffer - simultaneously. This is used to prevent multiple processes use the same - DMA engine at the same time. When passed to kmem_free, allows to clean - buffers with lost clients even for shared buffers. - - KMEM_FLAG_REUSE - requires reuse of existing buffer. If reusable buffer is - found (non-reusable buffers, i.e. allocated without KMEM_FLAG_REUSE are - ignored), it is returned instead of allocation. Three types of usage - counters are used. At moment of allocation, the HW reference is set if - neccessary. The usage counter is increased by kmem_alloc function and - decreased by kmem_free. Finally, the reference is obtained at returned - during mmap/munmap. So, on kmem_free, we do not clean - a) buffers with reference count above zero or hardware reference set. - REUSE flag should be supplied, overwise the error is returned - b) PERSISTENT buffer. REUSE flash should be supplied, overwise the - error is returned - c) non-exclusive buffers with usage counter above zero (For exclusive - buffer the value of usage counter above zero just means that application - have failed without cleaning buffers first. There is no easy way to - detect that for shared buffers, so it is left as manual operation in - this case) - d) any buffer if KMEM_FLAG_REUSE was provided to function - During module unload, only buffers with references can prevent cleanup. In - this case the only possiblity to free the driver is to call kmem_free - passing FORCE flags. - - KMEM_FLAG_PERSISTENT - if passed to allocation routine, changes mode of - buffer to PERSISTENT, if passed to free routine, vice-versa changes mode - of buffer to NORMAL. Basically, if we call 'pci --dma-start' this flag - should be passed to alloc and if we call 'pci --dma-stop' it should be - passed to free. In other case, the flag should not be present. - - If application crashed, the munmap while be still called cleaning software - references. However, the hardware reference will stay since it is not clear - if hardware channel was closed or not. To lift hardware reference, the - application can be re-executed (or dma_stop called, for instance). - * If there is no hardware reference, the buffers will be reused by next - call to application and for EXCLUSIVE buffer cleaned at the end. For SHARED - buffers they will be cleaned during module cleanup only (no active - references). - * The buffer will be reused by next call which can result in wrong behaviour - if buffer left in incoherent stage. This should be handled on upper level. - - - At pcilib/kmem level synchronization of multiple buffers is performed - * The HW reference and following modes should be consistent between member - parts: REUSABLE, PERSISTENT, EXCLUSIVE (only HW reference and PERSISTENT - mode should be checked, others are handled on dirver level) - * It is fine if only part of buffers are reused and others are newly - allocated. However, on higher level this can be checked and resulting - in failure. - - Treatment of inconsistencies: - * Buffers are in PRESISTENT mode, but newly allocated, OK - * Buffers are reused, but are not in PERSISTENT mode (for EXCLUSIVE buffers - this means that application has crashed during the last execution), OK - * Some of buffers are reused (not just REUSABLE, but actually reused), - others - not, OK until - a) either PERSISTENT flag is set or reused buffers are non-PERSISTENT - b) either HW flag is set or reused buffers does not hold HW reference - * PERSISTENT mode inconsistency, FAIL (even if we are going to set - PERSISTENT mode anyway) - * HW reference inconsistency, FAIL (even if we are going to set - HW flag anyway) - - On allocation error at some of the buffer, call clean routine and - * Preserve PERSISTENT mode and HW reference if buffers held them before - unsuccessful kmem initialization. Until the last failed block, the blocks - of kmem should be consistent. The HW/PERSISTENT flags should be removed - if all reused blocks were in HW/PERSISTENT mode. The last block needs - special treatment. The flags may be removed for the block if it was - HW/PERSISTENT state (and others not). - * Remove REUSE flag, we want to clean if allowed by current buffer status - * EXCLUSIVE flag is not important for kmem_free routine. - - - At DMA level - There is 4 components of DMA access: - * DMA engine enabled/disabled - * DMA engine IRQs enabled/disabled - always enabled at startup - * Memory buffers - * Ring start/stop pointers - - To prevent multiple processes accessing DMA engine in parallel, the first - action is buffer initialization which will fail if buffers already used - * Always with REUSE, EXCLUSIVE, and HW flags - * Optionally with PERSISTENT flag (if DMA_PERSISTENT flag is set) - If another DMA app is running, the buffer allocation will fail (no dma_stop - is executed in this case) - - Depending on PRESERVE flag, kmem_free will be called with REUSE flag - keeping buffer in memory (this is redundant since HW flag is enough) or HW - flag indicating that DMA engine is stopped and buffer could be cleaned. - PERSISTENT flag is defined by DMA_PERSISTENT flag passed to stop routine. - - PRESERVE flag is enforced if DMA_PERSISTENT is not passed to dma_stop - routine and either it: - a) Explicitely set by DMA_PERMANENT flag passed to dma_start - function - b) Implicitely set if DMA engine is already enabled during dma_start, - all buffers are reused, and are in persistent mode. - If PRESERVE flag is on, the engine will not be stopped at the end of - execution (and buffers will stay because of HW flag). - - If buffers are reused and are already in PERSISTENT mode, DMA engine was on - before dma_start (PRESERVE flag is ignored, because it can be enforced), - ring pointers are calculated from LAST_BD and states of ring elements. - If previous application crashed (i.e. buffers may be corrupted). Two - cases are possible: - * If during the call buffers were in non-PERSISTENT mode, it can be - easily detected - buffers are reused, but are not in PERSISTENT mode - (or at least was not before we set them to). In this case we just - reinitialize all buffers. - * If during the call buffers were in PERSISTENT mode, it is up to - user to check their consistency and restart DMA engine.] - - IRQs are enabled and disabled at each call - -DMA Reads -========= -standard: default reading mode, reads a single full packet -multipacket: reads all available packets -waiting multipacket: reads all available packets, after finishing the - last one waiting if new data arrives -exact read: read exactly specified number of bytes (should be - only supported if it is multiple of packets, otherwise - error should be returned) -ignore packets: autoterminate each buffer, depends on engine - configuration - - To handle differnt cases, the value returned by callback function instructs -the DMA library how long to wait for the next data to appear before timing -out. The following variants are possible: -terminate: just bail out -check: no timeout, just check if there is data, otherwise - terminate -timeout: standard DMA timeout, normaly used while receiving - fragments of packet: in this case it is expected - that device has already prepared data and only - the performance of DMA engine limits transfer speed -wait: wait until the data is prepared by the device, this - timeout is specified as argument to the dma_stream - function (standard DMA timeout is used by default) - - first | new_pkt | bufer - -------------------------- -standard wait | term | timeout -multiple packets wait | check | timeout - DMA_READ_FLAG_MULTIPACKET -waiting multipacket wait | wait | timeout - DMA_READ_FLAG_WAIT -exact wait | wait/term | timeout - limited by size parameter -ignore packets wait | wait/check| wait/check - just autoterminated - -Shall we do a special handling in case of overflow? - - -Buffering -========= - The DMA addresses are limited to 32 bits (~4GB for everything). This means we - can't really use DMA pages are sole buffers. Therefore, a second thread, with - a realtime scheduling policy if possible, will be spawned and will copy the - data from the DMA pages into the allocated buffers. On expiration of duration - or number of events set by autostop call, this thread will be stopped but - processing in streaming mode will continue until all copyied data is passed - to the callbacks. - - To avoid stalls, the IPECamera requires data to be read continuously read out. - For this reason, there is no locks in the readout thread. It will simplify - overwrite the old frames if data is not copied out timely. To handle this case - after getting the data and processing it, the calling application should use - return_data function and check return code. This function may return error - indicating that the data was overwritten meanwhile. Hence, the data is - corrupted and shoud be droped by the application. The copy_data function - performs this check and user application can be sure it get coherent data - in this case. - - There is a way to avoid this problem. For raw data, the rawdata callback - can be requested. This callback blocks execution of readout thread and - data may be treated safely by calling application. However, this may - cause problems to electronics. Therefore, only memcpy should be performed - on the data normally. - - The reconstructed data, however, may be safely accessed. As described above, - the raw data will be continuously overwritten by the reader thread. However, - reconstructed data, upon the get_data call, will be protected by the mutex. - - -Register Access Synchronization -=============================== - We need to serialize access to the registers by the different running - applications and handle case when registers are accessed indirectly by - writting PCI BARs (DMA implementations, for instance). - - - Module-assisted locking: - * During initialization the locking context is created (which is basicaly - a kmem_handle of type LOCK_PAGE. - * This locking context is passed to the kernel module along with lock type - (LOCK_BANK) and lock item (BANK ADDRESS). If lock context is already owns - lock on the specified bank, just reference number is increased, otherwise - we are trying to obtain new lock. - * Kernel module just iterates over all registered lock pages and checks if - any holds the specified lock. if not, the lock is obtained and registered - in the our lock page. - * This allows to share access between multiple threads of single application - (by using the same lock page) or protect (by using own lock pages by each of - the threads) - * Either on application cleanup or if application crashed, the memory mapping - of lock page is removed and, hence, locks are freed. - - - Multiple-ways of accessing registers - Because of reference counting, we can successfully obtain locks multiple - times if necessary. The following locks are protecting register access: - a) Global register_read/write lock bank before executing implementation - b) DMA bank is locked by global DMA functions. So we can access the - registers using plain PCI bar read/write. - c) Sequence of register operations can be protected with pcilib_lock_bank - function - Reading raw register space or PCI bank is not locked. - * Ok. We can detect banks which will be affected by PCI read/write and - lock them. But shall we do it? - -Register/DMA Configuration -========================== - - XML description of registers - - Formal XML-based (or non XML-based) language for DMA implementation. - a) Writting/Reading register values - b) Wait until <register1>=<value> on <register2>=<value> report error - c) ... ? - -IRQ Handling -============ - IRQ types: DMA IRQ, Event IRQ, other types - IRQ hardware source: To allow purely user-space implementation, as general - rule, only a single (standard) source should be used. - IRQ source: The dma/event engines, however, may detail this hardware source - and produce real IRQ source basing on the values of registers. For example, - for DMA IRQs the source may present engine number and for Event IRQs the - source may present event type. - - Only types can be enabled or disabled. The sources are enabled/disabled - by enabling/disabling correspondent DMA engines or Event types. The expected - workflow is following: - * We enabling IRQs in user-space (normally setting some registers). Normally, - just an Event IRQs, the DMA if necessary will be managed by DMA engine itself. - * We waiting for standard IRQ from hardware (driver) - * In the user space, we are checking registers to find out the real source - of IRQ (driver reports us just hardware source), generating appropriate - events, and acknowledge IRQ. This is dependent on implementation and should - be managed inside event API. - - I.e. the driver implements just two methods pcilib_wait_irq(hw_source), - pcilib_clear_irq(hw_source). Only a few hardware IRQ sources are defined. - In most cirstumances, the IRQ_SOURCE_DEFAULT is used. - - The DMA engine may provide 3 additional methods, to enable, disable, - and acknowledge IRQ. - - ... To be decided in details upon the need... - -Updating Firmware -================= - - JTag should be connected to USB connector on the board (next to Ethernet) - - The computer should be tourned off and on before programming - - The environment variable should be loaded - . /home/uros/.bashrc - - The application is called 'impact' - No project is needed, cancel initial proposals (No/Cancel) - Double-click on "Boundary Scan" - Right click in the right window and select "Init Chain" - We don't want to select bit file now (Yes and, then, click Cancel) - Right click on second (right) item and choose "Assign new CF file" - Select a bit file. Answer No, we don't want to attach SPI to SPI Prom - Select xv6vlx240t and program it - - Shutdown and start computer - - Firmware are in - v.2: /home/uros/Repo/UFO2_last_good_version_UFO2.bit - v.3: /home/uros/Repo/UFO3 - Step5 - best working revision - Step6 - last revision - - \ No newline at end of file -- cgit v1.2.3